Building Native Client

This page tells you how to build Native Client, including its examples and tests. Building Native Client is simple if you've already installed the distribution for your platform, as described in the Getting Started section Get the software.

Note: You might not need to build Native Client, at all. You can use Native Client and develop modules without building Native Client, since the platform-specific distributions include binaries for Native Client and its toolchain. For more information, see Getting Started.

Contents

Perform one-time setup

To build Native Client you must have a platform-specific development environment and Python.

Set up your development environment

Follow the instructions for your platform.

Check your Python version

If you followed the instructions in Getting Started, you should already have the right version of Python. The summary: Use Python 2.4 or 2.5 (possibly 2.6), don't use the Cygwin version of Python, and avoid spaces in the path to python. For further details, see Get the software and the details page for your platform (Linux, Mac, or Windows).

Build Native Client

Thanks to SCons, you use the same basic commands to build on all platforms.

  1. In a shell window, go to the native_client directory under your Native Client distribution. For example:

    Linux or Mac:

    cd install_dir/native_client
    

    Windows:

    cd install_dir\native_client
    
  2. Note: If you downloaded pre-built binaries instead of using SVN, insert build before the native_client directory. For example: cd install_dir\build\native_client.

  3. Build Native Client. Unless you've recently downloaded or built the Native Client toolchain, specify the --download flag to download the latest build of the toolchain. The following command downloads the toolchain and builds Native Client.

    Linux or Mac:

    ./scons -c             #clean (optional)
    ./scons --download     #build; --download is optional if you already have the latest toolchain
    

    Windows:

    .\scons.bat -c         #clean (optional)
    .\scons.bat --download #build; --download is optional if you already have the latest toolchain
    

    Troubleshooting (Windows): If the build fails with the message "'cl' is not recognized as an internal or external command", make sure you have your Visual Studio environment set up correctly. For instructions, see Developing on Windows.

  4. Build the optimized binaries. [PENDING: This step should go away if/when we update the default scons target to build everything.]

    Linux:

    ./scons -c --mode=opt-linux #clean (optional)
    ./scons --mode=opt-linux
    

    Mac:

    ./scons -c --mode=opt-mac   #clean (optional)
    ./scons --mode=opt-mac
    

    Windows:

    .\scons.bat --mode=opt-win
    
  5. Build the modules that use Native Client. [PENDING: This step might not be necessary if/when we update the default scons target to build everything.]

    Linux or Mac:

    ./scons --mode=nacl -c     #clean (optional)
    ./scons --mode=nacl        #build
    

    Windows:

    .\scons.bat --mode=nacl -c #clean (optional)
    .\scons.bat --mode=nacl    #build
    
  6. Verify that the build succeeded. One way to do this is to use the run_all_tests target. [PENDING: is that the best, easiest way to verify that you have something useable?]

    Linux or Mac:

    ./scons run_all_tests
    

    Windows:

    .\scons.bat run_all_tests
    

Now you can follow the steps in Getting Started. Start by running an example.

If you need to build the toolchain

[PENDING: We haven't tested this section since the massive upheaval to our codebase.]

You can probably ignore this section. The platform-specific distributions of Native Client have prebuilt toolchains, and the source distribution includes a --download option to get the toolchain. You don't need to build the toolchain unless you have changed toolchain files — such as to change the tools or add doc comments.

To build the toolchain, you need make and texinfo.

Currently, you can build only on Linux or Mac; you can't build the toolchain on Windows, even with Cygwin. [PENDING: When the Windows build starts working, add this: You can get make as part of Cygwin.]

Technical detail: Building the toolchain requires make because part of the toolchain is derived from GNU tools, such as GCC, that are built using make.

Here's how to build the toolchain:

  1. In a shell window, go to the tools directory under your Native Client distribution. For example:
    cd install_dir/native_client/tools
    
  2. Run make, specifying where to put the toolchain (SDKLOC=...).

    Linux:

    make SDKLOC=`pwd`/../src/third_party/nacl_sdk/linux/sdk
    

    Mac:

    make SDKLOC=`pwd`/../src/third_party/nacl_sdk/mac/sdk
    

    Windows (Cygwin): [PENDING: add this once the Windows build works]

    make SDKLOC=`pwd`/../src/third_party/nacl_sdk/windows/sdk
    
  3. Check the output to make sure the build completed successfully. The build should take about 20 minutes.

You should now be able to build Native Client.

More build options

This section describes some of the most commonly used options to SCons. Use the -h option to get more information on these and other options.

-h: Help

Displays SCons options.

-c: Clean

Removes build artifacts.

--prebuilt: Use existing binaries

Forces SCons to use prebuilt binaries, rather than rebuilding. For use with firefox_install.

-jX: Use multiple processes to build

If you are on a multi-core machine, the build process can use multiple cores to speed up the process by using the -jX option, where X is the number of concurrent processes you would like to have in flight. Normally, a good value is the number of physical cores in the machine. For example, use -j4 if your machine has 4 cores, as the following example shows.

./scons --mode=nacl -j4

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license.