f995c61709
The interactive UI tests on Wayland can only be run with the bundled Weston compositor, because they require a patched version of Weston's test plugin. This CL adds a note to the docs mentioning this requirement. Bug: - Change-Id: I1c982988910d90cf11605c95dc25e7721c4bfbd0 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3268590 Commit-Queue: Max Ihlenfeldt <mihlenfeldt@igalia.com> Reviewed-by: Maksim Sisov <msisov@igalia.com> Cr-Commit-Position: refs/heads/main@{#939815}
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:
- Upload a patch to gerrit, or receive a review request. e.g. https://chromium-review.googlesource.com/c/572236
- View a specific .md file. e.g. https://chromium-review.googlesource.com/c/572236/2/docs/README.md
- 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-tidytool 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.
ClientTagBasedModelTypeProcessorin 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 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.
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.
seccompSandbox 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.dllinto 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_shellon 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.Logon 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
- 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 synthesis engine used on Chrome OS
- VoiceOver - Using Apple's VoiceOver feature with Chromium on iOS.
Memory
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
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
SUIDSandbox - Sandboxing renderers using a SUID binary on Linux - Linux
SUIDSandbox 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.