This page is under work, consider it as a draft.

Prerequisites

Before proceeding, be sure you have read: Getting Around the Chromium Source Code

Obsolete

This document describes our previous attempt at a cross-platform build system. Chromium is moving to GYP, a new cross-platform build system that generates platform-native build files. e.g. on Windows, it generates Visual Studio project files; on Mac, it generates XCode project files; on Linux, it generates SCons project files (but could easily generate Makefiles; patches gratefully accepted).

Chromium still uses the Hammer command on Linux, but it's now just a wrapper around scons.

SCons and Hammer

Chromium uses SCons as software construction tool. SCons is based on the Python programming language and is a replacement for the traditional Make construction tool used in Linux Open Source projects.

The Chromium source tree includes a local copy of the official SCons Package under the directory $CHROMIUM_ROOT/src/third_party/scons/. This allows the user to avoid installing SCons as a system-wide utility.

The use of the SCons tool allows the Chromium team to easily deploy a source tree that can be built on Windows, Linux, and Mac OS.

The preferred way to use Scons is through Hammer. This application is included in the depot_tools package and is installed directly from the SVN repository.

Using Hammer

Basic Usage

Hammer is used to perform operations on the source tree.

Remember to make it usable from your shell environment, by adding the directory $CHROMIUM_ROOT/depot_tools to the $PATH.

To build Chromium, you need to type the following instructions:

cd $CHROMIUM_ROOT/chrome
hammer

To clean the source's tree, you need to type instructions:

cd $CHROMIUM_ROOT/chrome
hammer -c

By default a debug build is performed (with debugging symbols present etc). If you want an optimized (release) build, use this:

cd $CHROMIUM_ROOT/chrome
hammer --mode=opt

Executables created during the build process will be placed in $CHROMIUM_ROOT/src/chrome/Hammer.

After a compilation of Chromium you can recompile only a single library, binary executable or object file. To do so, type commands like these:

• To recompile an object file:

hammer Hammer/dbg/obj/skia/animator/SkTime.o 

• To recompile a library:

hammer Hammer/dbg/lib/libicu.a 

• To recompile a binary executable file:

hammer Hammer/unit_tests

Passing Chromium-Specific Arguments

You can also pass other command line arguments to the Hammer script, that affect the compilation. The following table lists the most important parameters you can use.

Passing Standard SCons Arguments

Any other parameters accepted by SCons can also be passed to the Hammer script. Sometimes it is useful to use parameters --verbose to affect the Scons output, or -j num to accelerate the compilation.

The command:

hammer --verbose

will print the full commands being executed, instead of shortened info like "Compiling x.cc".

The command:

hammer -j 5

will create five parallel compile jobs. But, on Linux only one link job will run at a time (to prevent excessive memory usage when linking for example test_shell and test_shell_tests).

More on the Argument SYSTEM_LIBS

Chromium's source tree includes some system libraries under the directory $CHROMIUM_ROOT/src/third_party/. These libraries are compiled and linked by default.

The argument SYSTEM_LIBS tells hammer not to compile certain embedded libraries under $CHROMIUM_ROOT/src/third_party/, but instead to link the libraries installed on the host system (the machine where you are compiling).

For example, the following command:

hammer SYSTEM_LIBS=libxslt

tells hammer to skip compilation of $CHROMIUM_ROOT/src/tird_party/libxslt and instead to link directly the library installed under /usr/lib (most Linux distributions use this location).

Before using the SYSTEM_LIBS argument, be sure to have also installed the C/C++ headers of the system library you are using.

Remember also that the Chromium build system uses the tool pkg-config to get information about a system library.

For the previous example you need to have installed the file /usr/lib/pkgconfig/libxslt.pc. Chromium build system uses a command like:

pkg-config --cflags --libs libxslt

to get the C Compiler Flags configuration of the local version of libxslt:

-I/usr/include/libxml2  -lxslt -lz -lm -lxml2

This is the list of libraries included in the Chromium source tree that you can override using the SYSTEM_LIBS argument:

• hunspell
• sqlite
• zlib
• bzip2
• libjpeg
• libxslt
• lzma_sdk
• libpng
• libxml

Understanding Hammer and the Use of SCons

What happens when you call the hammer script

The Python-based Hammer script is a front end for scons.py and can be considered a synonym for the following shell command:

exec python ../third_party/scons/scons.py  --site-dir=../site_scons <SCONS-ARGUMENTS>

Remember that directories $CHROMIUM_ROOT/src/chrome and $CHROMIUM_ROOT/src/site_scons are in the same filesystem tree. The hammer tool is always executed from inside the directory $CHROMIUM_ROOT/src/chrome.

The command above tells the Python interpreter:

1. to run the local embedded copy of SCons (third_party/scons/scons.py)
2. to use the directory $CHROMIUM_ROOT/src/site_scons as a custom tool repository (SCons loads custom add-on tools located here before any other SConstruct or SConscript)
3. to pass the remaining arguments to scons.py

By default SCons uses the file $CHROMIUM_ROOT/src/chrome/SConstruct as the starting point for the build. This script in turn calls the main script $CHROMIUM_ROOT/src/build/SConscript.main, which describes all the details.

The script $CHROMIUM_ROOT/src/build/SConscript.main takes following actions:

• It parses ARGUMENTS
• It prepares the list of the modules to build (that is, a list of SCons scripts to run)
• It sets compiler and linker configurations
• It prepares the SCons environment for the compilation

At the end of all it calls the function:

BuildComponents(environment_list)

which starts the build process of Chromium.

How the Chromium Construction System handles platform-specific code

Sometime it is necessary to make settings or take actions depending on which platform we are running on.

Currently supported platforms are:

• Windows, or MSVS
• Linux, or Posix
• Mac, or Xcode

To customize the SCons code on the platform you have to use a statement like:

if env.Bit('windows'):
  env.Append(
      CCFLAGS = [
          '/TC',
          '/wd4800',
      ],
  )

This example adds compilation flags '/TC' and '/wd4800' only if we are running on a windows platform.

How modules are integrated with the Chromium Construction System

Each module of the Chromium source tree has its own SCons script, and this is chained to the main SConscript list (see $CHROMIUM_ROOT/src/build/SConscript.main).

Let's take a short look at the SCons script of the package libxslt, located at $CHROMIUM_ROOT/src/third_party/libxslt/libxslt.scons (see sources).

Then:

• Before starting the script we check if the user has requested to compile and link this embedded version of the library (see also the use of the argument SYSTEM_LIBS)
• The script takes following actions:
• It sets extra compiler and linker configuration (appending to the standard configuration)
• It builds the list of files to compile
• It runs the compilation and links (env.ChromeStaticLibrary('libxslt', input_files))
• It takes specific actions depending on the platform (win32 or posix)

The other Chromium modules have similar scripts.