README.md

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

Markdown documents must follow the style guide.

Preview local changes using md_browser:

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

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

Review changes 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/572236
2. View a specific .md file. e.g. https://chromium-review.googlesource.com/c/572236/2/docs/README.md
3. Click on gitiles link at top of page.

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

Document Index

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

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
• 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.
• Using the Origin Trials Framework - A framework for conditionally enabling experimental APIs for testing.
• ClientTagBasedModelTypeProcessor in Unified Sync and Storage - Notes on the central data structure used in Chrome Sync.
• Chrome Sync's Model API - Data models used for syncing information across devices using Chrome Sync.
• Ozone Overview - Ozone is an abstraction layer between the window system and low level input and graphics.
• Optimizing Chrome Web UIs - Notes on making webuis more performant
• Adding a new feature flag in chrome://flags - Quick guide to add a new feature flag to experiment your feature.
• 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).
• 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).

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 desciptions.
• 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.

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 Managment - 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.
• Android BuildConfig files - What are .build_config files and how they are used.
• Android App Bundles - How to build Android app bundles for Chrome.
• Dynamic Feature Modules (DFMs) - How to create dynamic feature modules.
• 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.

Media

• Audio Focus Handling - How multiple MediaSession audio streams interact
• Autoplay of HTMLMediaElements - How HTMLMediaElements are autoplayed.
• Piranha Plant - Future architecture of MediaStreams
• 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 sythesis engine used on Chrome OS
• VoiceOver - Using Apple's VoiceOver feature with Chromium on iOS.

Memory

• Memory Overview

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.

Speed

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

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.