How to Build Chromium's content_shell for Faster Testing

Compiling the entire Chromium web browser from source requires significant time and hardware resources, which can slow down development workflows. This article provides a straightforward guide on how developers can bypass building the full browser UI and instead compile only the content_shell target. By following the configuration, compilation, and execution steps outlined below, you can rapidly test and iterate on changes made to the Blink rendering engine and Chromium's core content module.

What is content_shell?

content_shell is a minimal browser interface that wraps Chromium’s content module. It includes the Blink rendering engine, the V8 JavaScript engine, and the multi-process sandboxed architecture, but strips away all full-browser features like extensions, sync, bookmarks, and the standard Chrome user interface. Because it contains thousands fewer files to compile and link, building content_shell is the fastest way to verify HTML, CSS, JavaScript, and rendering engine modifications.

Step 1: Navigate to the Source Directory

Open your terminal and navigate to the src directory of your existing Chromium checkout. Ensure that your depot_tools are properly installed and exist in your system's PATH.

cd /path/to/chromium/src

Step 2: Configure the Build Directory

Before building the target, you need to generate a build directory using GN (Generate Ninja). To maximize build speed for local testing, configure your build arguments to use a component build with reduced debugging symbols.

Run the following command to open the arguments editor for a build directory named Default:

gn args out/Default

In the text editor that opens, add the following lines, then save and close the file:

is_component_build = true
is_debug = true
symbol_level = 1
enable_nacl = false
blink_symbol_level = 0
  • is_component_build = true: Splits the build into many small shared libraries rather than a few massive executables, drastically reducing link time after making small code changes.
  • symbol_level = 1: Provides enough information for stack traces without the massive overhead of full debugging symbols.
  • blink_symbol_level = 0: Removes debug symbols from Blink to speed up linking (set this to 1 or 2 only if you need to step through Blink code in a debugger).

Step 3: Build the content_shell Target

Instead of building the chrome target, instruct autoninja to compile only content_shell. autoninja is a wrapper around Ninja that automatically chooses the optimal number of parallel jobs for your CPU.

Run the following command:

autoninja -C out/Default content_shell

When you modify files inside the rendering engine (such as inside third_party/blink/), re-running this exact command will only recompile the modified files and relink the necessary components, usually finishing in seconds or a few minutes.

Step 4: Run content_shell to Test Changes

Once the build completes, you can launch the minimal browser directly from the command line to test your rendering changes.

On Linux:

./out/Default/content_shell

On macOS:

./out/Default/Content\ Shell.app/Contents/MacOS/Content\ Shell

On Windows:

out\Default\content_shell.exe

You can also pass a specific URL or a local HTML test file directly as an argument to immediately render your test case upon launch:

./out/Default/content_shell /path/to/your/test.html

Step 5: Running Automated Web Tests

If your rendering engine changes need to be verified against Chromium's automated layout and rendering test suite (Web Tests), content_shell is the exact binary used to run them. Once content_shell is built, you can run a specific web test using the run_web_tests.py script without needing to build anything else:

third_party/blink/tools/run_web_tests.py -t Default fast/css/your-test-file.html

The -t Default flag instructs the test runner to use the content_shell binary located in your out/Default directory.