The parts of the system shared with Chrome are also built using Chrome's build system, Gyp.
We also have some Makefiles and some shell scripts for certain build tasks.
The usual excuses:
For SCons it is: SConstruct, **/build.scons, **/nacl.scons There are also relevant configuration files in site_scons/site_tools/*, and random Python scripts located here and there.
For Gyp it is: **/*.gyp and **/*.gypi
"Trusted code" encompasses components like:
"Untrusted code" encompasses components like:
Some code can be compiled either as trusted or shared code, e.g. libraries that facilitate communication between trusted and untrusted code. Such code typically lives in src/shared/** and has both build.scons and nacl.scons files.
The MODE= setting or its equivalent --mode is used to select whether you want to compile trusted or untrusted code or both and how. Examples:
NOTE: if you do not specify MODE, "opt-<your-system-os>" will be assumed.
NOTE: if you want to run integration tests, you need to build both trusted and untrusted code simultaneously, because those tests involve running untrusted code under the control of trusted code.
Just like any cross compilation environment, there are some hairy configuration issues which are controlled by BUILD_ARCH, TARGET_ARCH, etc. to force conditional compilation and linkage.
It helps to revisit the terminology used by cross compilers to better understand Native Client:
BUILD_SYSTEM: The system on which the tools will be built (initially) is called the build system.
HOST_SYSTEM: The system on which the tools will run is called the host system.
TARGET_SYSTEM: The system for which the tools generate code is called the target system.
For NaCl we only have two of these, sadly they have confusing names:
BUILD_PLATFORM: The system on which the trusted code runs.
TARGET_PLATFORM: The sandbox system that is being enforced by the trusted code.
The BUILD_PLATFORM is closest in nature to the HOST_SYSTEM, the TARGET_PLATFORM is closest to the TARGET_SYSTEM. We do not have an equivalent to BUILD_SYSTEM since we just assume the build system is x86 (either a 32- or 64-bit system).
Conceptually we have
BUILD_PLATFORM = (BUILD_ARCH, BUILD_SUBARCH, BUILD_OS)
TARGET_PLATFORM = (TARGET_ARCH. TARGET_SUBARCH)
There is no TARGET_OS, since Native Client executables are OS independent.
The BUILD_OS is usually tested for using SCons expressions like "env.Bit('windows')". You cannot really control it as it is inherited from the system you are building on, the BUILD_SYSTEM in cross compiler speak.
Enumeration of all BUILD_PLATFORMs:
(x86, 32, linux) (x86, 32, windows) (x86, 32, mac) (arm, 32, linux) // the 32 is implicit as there is no 64bit arm
(x86, 64, linux) (x86, 64, windows)
Special note for Windows users: The Windows command-line build currently relies on vcvarsXX.bat being called to set up the environment. The compiler's target subarchitecture (32,64) is selected by the version of vcvars that you called (vcvars32/vcvars64). If you call vcvars32 and then build with platform=x86-64, you will get "target mismatch" errors.
Enumeration of all TARGET_PLATFORMs: (x86, 32) (x86, 64) (arm, 32) // the 32 is implicit as there is no 64bit arm
Usually BUILD_ARCH == TARGET_ARCH and BUILD_SUBARCH == TARGET_SUBARCH
There is ONLY ONE exception, you can build the ARM validator like so:
BUILD_ARCH = x86, BUILD_SUBARCH=, TARGET_ARCH=arm TARGET_SUBARCH=32
In particular it is NOT possible to use different SUBARCHs for BUILD and TARGET.
The flavor of the untrusted code is derived from the TARGET_PLATFORM
Usually BUILD_ARCH == TARGET_ARCH and BUILD_SUBARCH == TARGET_SUBARCH so mistakes have no consequences.
[Note: scons --download has been deprecated as of Aug 17, 2010]
The first time you build, you will need to get the latest toolchain build. Do this using gclient runhooks:
Depending on your internet connection this step can take several minutes, as it downloads the TCB tarball which is between 35 and 50 Mb.
The default value for MODE is dbg-<your-system-os> so these two commands are identical
To run all unittests:
To run specific sets of tests:
To run a single test:
There are some other scons options which are useful. Note the confusing syntax differences for option words (platform=), single minus options (-c), and double minus options (--download). Sorry.
The build defaults to a 32-bit build even if the machine running the build is a 64-bit machine. To build for 64-bit:
Also see the Special note for Windows users in the What kind of BUILD_PLATFORM/TARGET_PLATFORM configurations are supported? section above.
The source code is divided into these main areas: