native_client_sdk/src/BUILDING.rst

   1 Building the Full SDK
   2 =====================
   3
   4 *Linux users*: Before you run build_sdk.py (below), you must run::
   5
   6   GYP_DEFINES=target_arch=arm gclient runhooks
   7
   8 This will install some ARM-specific tools that are necessary to build the SDK.
   9
  10 *Everyone else*:
  11
  12 To build the NaCl SDK, run::
  13
  14   build_tools/build_sdk.py
  15
  16 This will generate a new SDK in your out directory::
  17
  18   $CHROME_ROOT/out/pepper_XX
  19
  20 Where "XX" in pepper_XX is the current Chrome release (e.g. pepper_38).
  21
  22 The libraries will be built, but no examples will be built by default. This is
  23 consistent with the SDK that is shipped to users.
  24
  25
  26 Testing the SDK
  27 ===============
  28
  29 To build all examples, you can run the test_sdk.py script::
  30
  31   build_tools/test_sdk.py
  32
  33 This will build all examples and tests, then run tests. It will take a long
  34 time. You can run a subset of these "phases" by passing the desired phases as
  35 arguments to test_sdk::
  36
  37   build_tools/test_sdk.py build_examples copy_tests build_tests
  38
  39 These are the valid phases:
  40
  41 * `build_examples`: Build all examples, for all configurations and toolchains.
  42   (everything in the examples directory)
  43 * `copy_tests`: Copy all tests to the SDK (everything in the tests directory)
  44 * `build_tests`: Build all tests, for all configurations and toolchains.
  45 * `sel_ldr_tests`: Run the sel_ldr tests; these run from the command line, and
  46   are much faster that browser tests. They can't test PPAPI, however.
  47 * `browser_tests`: Run the browser tests. This launches a locally built copy of
  48   Chrome and runs all examples and tests for all configurations. It is very
  49   slow.
  50
  51
  52 Testing a Single Example/Test
  53 =============================
  54
  55 To test a specific example, you can run the test_projects.py script::
  56
  57   # Test the core example. This will test all toolchains/configs.
  58   build_tools/test_projects.py core
  59
  60   # Test the graphics_2d example, newlib/Debug only.
  61   build_tools/test_projects.py graphics_2d -t newlib -c Debug
  62
  63 This assumes that the example is already built. If not, you can use the `-b`
  64 flag to build it first::
  65
  66   build_tools/test_projects.py nacl_io_test -t newlib -c Debug -b
  67
  68
  69 Rebuilding the Projects
  70 =======================
  71
  72 If you have made changes to examples, libraries or tests directory, you can
  73 copy these new sources to the built SDK by running build_projects.py::
  74
  75   build_tools/build_projects.py
  76
  77 You can then rebuild the example by running Make::
  78
  79   cd $CHROME_ROOT/out/pepper_XX
  80   cd examples/api/graphics_2d  # e.g. to rebuild the Graphics2D example.
  81   make -j8
  82
  83 You can build a specific toolchain/configuration combination::
  84
  85   make TOOLCHAIN=newlib CONFIG=Debug -j8
  86
  87 The valid toolchains are: `newlib`, `glibc`, `clang-newlib`, `pnacl` and
  88 `bionic`.  The valid configurations are: `Debug` and `Release`.
  89
  90 To run the example::
  91
  92   # Run the default configuration
  93   make run
  94
  95   # Run the newlib/Debug configuration
  96   make TOOLCHAIN=newlib CONFIG=Debug -j8
  97
  98 This will try to find Chrome and launch it. You can specify this manually via
  99 the CHROME_PATH environment variable::
 100
 101   CHROME_PATH=/absolute/path/to/google-chrome make run
 102
 103
 104 Building Standalone Examples/Tests
 105 -------------------------------
 106
 107 Building the standalone tests is often more convenient, because they are faster
 108 to run, and don't require a copy of Chrome. We often use the standalone tests
 109 first when developing for nacl_io, for example. However, note that most tests
 110 cannot be built this way.
 111
 112 To build the standalone configuration::
 113
 114   cd tests/nacl_io_test
 115   make STANDALONE=1 TOOLCHAIN=newlib -j8
 116
 117 To run the standalone tests, you must specify an architecture explicitly::
 118
 119   make STANDALONE=1 TOOLCHAIN=newlib NACL_ARCH=x86_64 -j8 run