src/docs

Chromium docs

This directory contains chromium project documentation in Gitiles-flavored Markdown. It is automatically rendered by Gitiles.

If you add new documents, please also add a link to them in the Document Index below.

[TOC]

Creating Documentation

Guidelines

• See the Chromium Documentation Guidelines and the Chromium Documentation Best Practices.
• Markdown documents must follow the Markdown Style Guide.

Previewing changes

Locally using md_browser

# in chromium checkout
./tools/md_browser/md_browser.py

This is only an estimate. The gitiles view may differ.

Online with Gerrit's links to gitiles

1. Upload a patch to gerrit, or receive a review request. e.g. https://chromium-review.googlesource.com/c/3362532
2. View a specific .md file. e.g. https://chromium-review.googlesource.com/c/3362532/2/docs/README.md
3. You will see something like
   Base preview -> Patchset 3 preview | DOWNLOAD
   at the top left of the page. Click on the second "preview" link to open the preview for the current patch set.

This gitiles view is the authoritative view, exactly the same as will be used when committed.

Document Index

Note: this is not an exhaustive list of all documents.

Checking Out and Building

• Linux Build Instructions - Linux
• Mac Build Instructions - MacOS
• Windows Build Instructions - Windows
• Android Build Instructions - Android target (on a Linux host)
• Cast Build Instructions - Cast target (on a Linux host)
• Cast for Android Build Instructions - Cast for Android (on a Linux host)
• Fuchsia Build Instructions - Fuchsia target (on a Linux host)
• iOS Build Instructions - iOS target (on a MacOS host)
• Chrome OS Build Instructions - Chrome OS
• Linux Chromium ARM Recipes - Recipes for building Chromium for ARM on Linux.
• Chrome Component Build - Faster builds using more libraries
• Using the BuildRunner - Scripts that extract build stops from builders and runs them locally on a slave
• Cr User Manual - Manual for cr, a tool that tries to hide some of the tools used for working on Chromium behind an abstraction layer

Design Docs

• See design/README.md

Integrated Development Environment (IDE) Set Up Guides

• Android Studio - Android Studio for Android builds
• Atom - Atom multi-platform code editor
• CLion - CLion IDE, supports GUI debugging.
• Eclipse for Android - Eclipse for Android
• Eclipse for Linux - Eclipse for other platforms (This guide was written for Linux, but is probably usable on Windows/MacOS as well)
• EMACS Notes - EMACS commands/styles/tool integrations
• Qt Creator - Using Qt Creator as an IDE or GUI debugger
• Visual Studio Code - Visual Studio Code

Git

• Git Cookbook - A collection of git recipes for common tasks
• Git Tips - More git tips
• Git submodules - Git submodule (tips, FAQ)

Clang

• Clang Compiler - General information on the clang compiler, used by default on Mac and Linux
• Clang Tool Refactoring - Leveraging clang tools to perform refactorings that are AST-aware
• The Clang Static Analyzer - How to enable static analysis at build time
• Clang Code Coverage Wrapper - Enable Clang code coverage instrumentation for a subset of source files.
• Writing Clang Plugins - Don't write a clang plugin, but if you do, read this
• Updating Clang - Updating the version of Clang used to build
• Using clang-format on Chromium C++ Code - Various ways to invoke clang-format on C++ code
• Clang Tidy - Support for the clang-tidy tool in Chromium
• Updating Clang Format Binaries - How up update the clang-format binaries that come with a checkout of Chromium

General Development

• Contributing to Chromium - Reference workflow process for contributing to the Chromium code base.
• Commit Checklist - Streamlined checklist to go through before uploading CLs on Gerrit.
• Code Reviews - Code review requirements and guidelines
• Dependency management - Managing dependencies (DEPS, git submodules)
• Respectful Code Reviews - A guide for code reviewers
• Respectful Changes - A guide for code authors
• Mandatory Code-Review Rollout - Upcoming policy changes related to code review and OWNERS
• LUCI Migration FAQ - FAQ on Buildbot-to-LUCI builder migration for Chromium
• Tour of Continuous Integration UI - A tour of our the user interface for LUCI, our continuous integration system
• Parsing Test Results - An introduction for how to understand the results emitted by polygerrit and CI builds.
• Closure Compilation - The Closure JavaScript compiler
• Threading and Tasks in Chrome - How to run tasks and handle thread safety in Chrome.
• Callback<> and Bind() - All about Callbacks, Closures, and Bind().
• Chromium Views UI - Working with the desktop UI framework.
• Views Platform Styling - How views are styled to fit in different native platforms
• Tab Helpers - Using WebContents/WebContentsObserver to add features to browser tabs.
• Adding third_party Libraries - How to get code into third_party/
• Graphical Debugging Aid for Chromium Views - Visualizing view trees during debugging
• Bitmap Pipeline - How bitmaps are moved from the renderer to the screen.
• Flag Guarding Guidelines - When to use server controlled kill switches and A/B experiments to safely roll out changes.
• Using the Origin Trials Framework - A framework for conditionally enabling experimental APIs for testing.
• Chrome Sync - Docs for the subsystem that allows one to sync data across devices.
• Ozone Overview - Ozone is an abstraction layer between the window system and low level input and graphics.
• Guidelines for considering branch dates in project planning - What to do (and not to do) around branch dates when scheduling your project work.
• WebUI Explainer - An explanation of C++ and JavaScript infrastructural code for Chrome UIs implemented with web technologies (i.e. chrome:// URLs).
• Optimizing Chrome Web UIs - Notes on making webuis more performant
• Watchlists - Use watchlists to get notified of CLs you are interested in.
• Shutdown - Explains the steps of Chrome shutdown, to make it easier to determine where to add a new shutdown operation.
• API Keys - When you need access to Google APIs for a custom build, fork, integration of stock Chromium, or are building ChromiumOS (for login).
• User Education - Create in-product help (IPH) and tutorials to call out Chromium features

Testing

• Running and Debugging Web Tests
• On disabling tests
• Writing Web Tests - Web Tests using content_shell
• Web Test Expectations and Baselines - Setting expected results of web tests.
• Web Tests Tips - Best practices for web tests
• Web Tests with Manual Fallback - Writing tests that simulate manual interventions
• Extending the Web Test Framework
• Fixing Web Test Flakiness - Diagnosing and fixing web test flakiness due to ordering dependencies.
• Running Web Tests using content_shell - Running web tests by hand.
• Web Platform Tests - Shared tests across browser vendors
• Using Crashpad with content_shell - Capture stack traces on layout test crashes without an attached debugger
• Test Descriptions - Unit test targets that can be built, with associated descriptions.
• Fuzz Testing - Fuzz testing in Chromium.
• IPC Fuzzer - Fuzz testing of Chromium IPC interfaces.
• Running Chrome tests with AddressSanitizer (asan) and LeakSanitizer (lsan) - Run Chrome tests with ASAN and LSAN builds to detect addressability issues and memory leaks.
• Code Coverage - Code coverage for Chromium.
• Code Coverage in Gerrit - Per-CL code coverage in Gerrit to assist code reviews.

Configuration Docs

• Configuration: Prefs, Settings, Features, Switches & Flags - Explains different ways to gate a new feature.
• Adding a new feature flag in chrome://flags - Quick guide to add a new feature flag to experiment your feature.
• Runtime Enabled Features
• Initialization of Blink runtime features in content layer
• Integrating a feature with the origin trials framework

GPU-related docs

• GPU Pixel Wrangling - Instructions for GPU pixel wrangling (the GPU sheriffing rotation).
• Debugging GPU related code - Hints for debugging GPU- and graphics-related code.
• GPU Testing - Description of Chromium's GPU testing infrastructure.
• GPU Bot Details - In-depth description of how the bots are maintained.

Misc Linux-Specific Docs

• Linux Proxy Config - Network proxy sources on Linux
• Debugging SSL on Linux - Tips on debugging SSL code in Linux
• Linux Cert Management - Managing X.509 Certificates in Linux
• Tips for Debugging on Linux
• Linux GTK Theme Integration - Having Chrome match the GTK+ theme.
• Browser Plugins on Linux - A collection of links to information on how browser plugins work on Linux
• Linux Crash Dumping - How Breakpad uploads crash reports to Google crash servers.
• Linux Minidump to Core - How to convert a Breakpad-generated minidump files to a core file readable by most debuggersx
• Linux Sandbox IPC - The lower level UPC system used to route requests from the bottom of the call stack up into the browser.
• Linux Dev Build as Default Browser - How to configure a Dev build of Chrome as the default browser in Linux.
• Linux Chromium Packages - Packages of Chromium browser (not Chrome) provided by some Linux distributions.
• seccomp Sandbox Crash Dumping - Notes on crash dumping a process running in a seccomp sandbox.
• Linux Password Storage - Keychain integrations between Chromium and Linux.
• Linux Sublime Development - Using Sublime as an IDE for Chromium development on Linux.
• Building and Debugging GTK - Building Chromium against GTK using lower optimization levels and/or more debugging symbols.
• Debugging GTK - Using the GTK Debug packages and related tools.
• Chroot Notes - Setting up a chroot to work around libfreetype differences in some versions of Linux.
• Linux Sandboxing - The Linux multi-process model to isolate browser components with different privileges.
• Zygote Process - How the Linux Zygote process, used to spawn new processes, works.
• Running Web Tests on Linux - Linux-specific instructions for running web tests.
• Linux Sysroot Images - How builds use libraries on Linux
• Linux Hardware Video Decoding - Enabling hardware video decode codepaths on Linux

Misc MacOS-Specific Docs

• Mac Debugging Tips - An introduction to debugging on Mac, as well as a collection of useful tips.
• Using CCache on Mac - Speed up builds on Mac using ccache with clang/ninja
• Cocoa tips and tricks - A collection of idioms used when writing Cocoa views and controllers
• MacViews Release Plan

Misc Windows-Specific Docs

• Handling cygwin rebaseall failures
• Hacking on ANGLE in Chromium - OpenGL ES 2.0 built on top of DirectX
• Windows Split DLLs - Splitting chrome.dll into multiple dlls to work around toolchain limitations on Windows.
• Windows Native Window Occlusion Tracking
• Windows PWA Integration - Integration with Progressive Web Apps on Windows
• Windows Shortcut and Taskbar Handling
• Windows Virtual Desktop Integration

Misc Android-Specific Docs

• Google Play Services in Chrome for Android
• Accessing C++ Enums in Java - How to use C++-defined enums in Java code
• Profiling Content Shell on Android - Setting up profiling for content_shell on Android
• Working Remotely with Android - Building on a remote machine for an Android device connected to your local machine
• Android Test Instructions - Running a build on an Android device or emulator.
• Android Debugging - Tools and tips for how to debug Java and/or C/C++ code running on Android.
• Android Logging - How Chrome's logging API works with android.util.Log on Android, and usage guidelines.
• Android Java Static Analysis - Catching Java related issues at compile time with the 'lint' tool.
• Java Code Coverage - Collecting code coverage data with the EMMA tool.
• Dynamic Feature Modules (DFMs) - What are they and how to create new ones.
• Other build-related Android docs
• Chrome for Android UI - Resources and best practices for developing UI

Misc iOS-Specific Docs

• Continuous Build and Test Infrastructure for Chromium for iOS
• Opening links in Chrome for iOS - How to have your iOS app open links in Chrome.
• User Agent in Chrome for iOS - Notes on User Agent strings using Chrome for iOS.
• Running iOS test suites locally
• Working With Project Files in iOS - How to add, remove, and rename files in the iOS Chromium project.

Misc Chrome-OS-Specific Docs

• Setting up captive portals and other restrictive networks
• Enterprise Enrollment
  • Kiosk mode and public sessions
• Debugging UI in OOBE/login/lock
• Chrome Logging on Chrome OS
• Debugging tips

Misc WebUI-Specific Docs

• Creating WebUI Interfaces in components/ - How to create a new WebUI component in the components/ directory.
• Trusted Types on WebUI - Tips for coding in WebUI with Trusted Types in mind.
• chrome-untrusted:// FAQ - Explainer on the usage of the chrome-untrusted:// scheme for hosting WebUIs that handle untrustworthy content.

Media

• Audio Focus Handling - How multiple MediaSession audio streams interact
• Autoplay of HTMLMediaElements - How HTMLMediaElements are autoplayed.
• Latency tracing - How to use the "audio.latency" tracing category to measure audio latency.
• Piranha Plant - Future architecture of MediaStreams
• Media Capture - Features and APIs that enable the browser to capture pixels and audio from itself or the underlying OS.
• Video Encode Accelerator Tests - How to use the accelerated video encoder test program.
• Video Decoder Tests - Running the video decoder tests.
• Video Decoder Performance Tests - Running the video decoder performance tests.

Accessibility

• Accessibility Overview - Overview of accessibility concerns and approaches in Chromium.
• Accessibility Tests - Where to find accessibility-related tests in the codebase.
• ChromeVox on Chrome OS - Enabling spoken feedback (ChromeVox) on Chrome OS.
• ChromeVox on Desktop Linux - Enabling spoken feedback (ChromeVox) on desktop Linux.
• Offscreen, Invisible and Size - How Chrome defines offscreen, invisible and size in the accessibility tree.
• Text to Speech - Overview of text to speech in Chrome and Chrome OS.
• BRLTTY in Chrome OS - Chrome OS integration with BRLTTY to support refreshable braille displays
• PATTS on Chrome OS - Notes on the PATTS speech synthesis engine used on Chrome OS
• VoiceOver - Using Apple's VoiceOver feature with Chromium on iOS.

Memory

• Memory Overview
• Heap Profiling with External Tools

Memory Infrastructure Timeline Profiling (MemoryInfra)

• Overview
• GPU Profiling
• Adding Tracing to a Component
• Enabling Startup Tracing
• Memory Usage in CC
• Memory Benchmarks
• Heap Profiling

Metrics

• Histograms
• User Actions
• Code review guidelines

Misc

• Useful URLs - A collection of links to various tools and dashboards
• ERC IRC - Using ERC in EMACS to access IRC
• Kiosk Mode - Simulating kiosk mode.
• User Handle Mapping - Names of developers across Chromium/IRC/Google
• Documentation Best Practices
• Documentation Guidelines
• Chromium Browser vs Google Chrome - What's the difference between Chromium Browser and Google Chrome?
• Google Chrome branded builds
• Proxy Auto Config using WPAD - How WPAD servers are used to automatically set proxy settings.
• Installing Chromium OS on VMWare - How to install Chromium OS on VMWare.
• User Data Directory - How the user data and cache directories are determined on all platforms.
• User Data Storage - Policy documentation for files in User Data.

Mojo & Services

• Intro to Mojo & Services - Quick introduction to Mojo and services in Chromium, with examples
• Mojo API Reference - Detailed reference documentation for all things Mojo
• Service Development Guidelines - Guidelines for service development in the Chromium tree
• Servicifying Chromium Features - General advice for integrating new and existing subsystems into Chromium as services
• Converting Legacy IPC to Mojo - Tips and common patterns for practical IPC conversion work
• Mojo “Style” Guide - Recommendations for best practices from Mojo and IPC reviewers
• D-Bus Mojo Connection Service - A service in Chrome to bootstrap CrOS services' Mojo connection.

Security

• The Rule Of 2 - An imoportant security rule when handling untrustworthy contents (like anything downloaded from the web).

Speed

• Chrome Speed - Documentation for performance measurements and regressions in Chrome.
• Chrome Speed Metrics - Documentation about user experience metrics on the web and their JavaScript APIs.

UI

• Chromium UI Platform - All things user interface

What's Up With That Transcripts

These are transcripts of What's Up With That, a video series of interviews with Chromium software engineers.

• What's Up With Pointers - Episode 1
• What's Up With DCHECKs - Episode 2
• What's Up With //content - Episode 3
• What's Up With Tests - Episode 4
• What's Up With BUILD.gn - Episode 5
• What's Up With Open Source - Episode 6
• What's Up With Mojo - Episode 7
• What's Up With Processes - Episode 8
• What's Up With Site Isolation - Episode 9
• What's Up With Web Platform - Episode 10
• What's Up With Web Standards - Episode 11

Probably Obsolete

• TPM Quick Reference - Trusted Platform Module notes.
• System Hardening Features - A list of current and planned Chrome OS security features.
• WebView Policies
• Linux Profiling - How to profile Chromium on Linux
• Linux Graphics Pipeline
• Linux SUID Sandbox - Sandboxing renderers using a SUID binary on Linux
• Linux SUID Sandbox Development - Development on the above system.
• Linux PID Namespace Support
• Vanilla msysgit workflow - A workflow for using mostly vanilla git on Windows.
• Old Options - Pre-Material Design chrome://settings notes.