Configuring Chromium Build Flags: is_debug and symbol_level

This article provides a complete overview of how developers configure build flags like is_debug and symbol_level when setting up an output directory for the Chromium web browser. Using Chromium's meta-build system, GN (Generate Ninja), developers can customize their local builds to balance compilation speed, binary size, and debugging capabilities. You will learn how to initialize a build directory, modify the configuration file, and apply the optimal settings for your development workflow.

Setting Up the Output Directory with GN

Chromium uses GN to generate the configuration files required by the Ninja build system. Before compiling the browser, you must create an output directory and define your build arguments.

To set up a new output directory and configure your flags interactively, run the following command from your chromium/src directory:

gn args out/Default

In this command, out/Default is the path to your chosen output directory. You can replace Default with any name, such as out/Debug or out/Release, to maintain multiple build configurations simultaneously.

Running this command creates the directory and opens a text editor containing a file named args.gn. You configure your build by typing key-value pairs directly into this file. When you save and close the file, GN automatically validates the flags and generates the necessary Ninja build files.

Configuring the is_debug Flag

The is_debug flag is a boolean argument that determines whether you are compiling a debug or release build of Chromium.

is_debug = true
  • is_debug = true (Default): Enables runtime checks (like DCHECK), disables most compiler optimizations, and includes debugging information. This makes the code easier to step through in a debugger, but the resulting binary runs significantly slower and takes up more disk space.
  • is_debug = false: Enables full compiler optimizations to produce a fast, production-like Release build. While the browser will run quickly, debugging becomes difficult because variables and functions may be optimized away by the compiler.

If you want the speed of a release build while still retaining runtime assertions to catch bugs, you can set is_debug = false and add dcheck_always_on = true to your args.gn file.

Configuring the symbol_level Flag

The symbol_level flag accepts an integer (0, 1, or 2) and controls the amount of debugging information (symbols) the compiler generates. Symbols map the compiled binary instructions back to the original C++ source code, which is essential for resolving stack traces and using debuggers like GDB, LLDB, or Visual Studio.

symbol_level = 1
  • symbol_level = 2: Generates full debugging symbols. This allows you to inspect local variables, data structures, and exact line numbers in a debugger. However, it drastically increases compilation time, linking time, and the size of the output directory.
  • symbol_level = 1: Generates minimal symbols. This includes function names and source file line tables, which is enough to produce readable stack traces when the browser crashes. It is much faster to build and link than level 2, though you cannot inspect local variables in a debugger.
  • symbol_level = 0: Generates no debugging symbols. This results in the fastest possible build and link times, as well as the smallest disk footprint, at the cost of making debugging and crash analysis nearly impossible.

To speed up builds further, developers often pair symbol_level with blink_symbol_level = 0. This specifically strips symbols from the Blink rendering engine—one of the largest components of Chromium—saving massive amounts of linking time if you are not actively debugging web platform rendering features.

Depending on your goals, you can combine these flags in your args.gn file in a few standard ways:

For active debugging (Stepping through code):

is_debug = true
symbol_level = 2
is_component_build = true

(Note: is_component_build = true splits Chromium into many small shared libraries rather than one massive executable, drastically reducing link times during development).

For fast compilation (Testing behavior without a debugger):

is_debug = false
symbol_level = 0
dcheck_always_on = true

Setting Flags via the Command Line

If you are automating your setup or prefer not to use the interactive text editor, you can pass the build flags directly through the command line using gn gen with the --args parameter:

gn gen out/Default --args="is_debug=false symbol_level=1"

This command creates the out/Default/args.gn file, writes the specified flags to it, and generates the Ninja build files in one step. Once configured, you can immediately begin compiling the browser using autoninja -C out/Default chrome.