documentation/building.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5 <title>Native Client: Building Native Client</title>
   6 <link href="stylesheet.css" type="text/css" rel="stylesheet"></link>
   7 </head>
   8
   9 <body>
  10
  11 <div id="toplink">
  12 <a href="../README.html">Back to README</a>
  13 </div>
  14
  15 <h1>Building Native Client</h1>
  16
  17 <p>
  18 This page tells you how to build Native Client,
  19 including its examples and tests.
  20 Building Native Client is simple
  21 if you've already installed the distribution for your platform,
  22 as described in the Getting Started section
  23 <a href="getting_started.html#software">Get the software</a>.
  24 </p>
  25
  26 <p>
  27 <strong>Note:</strong>
  28 You might not need to build Native Client, at all.
  29 You can use Native Client and develop modules without building Native Client,
  30 since the platform-specific distributions
  31 include binaries for Native Client and its SDK.
  32 For more information,
  33 see <a href="getting_started.html">Getting Started</a>.
  34 </p>
  35
  36 <h3>Contents</h3>
  37
  38 <ul>
  39 <li> <a href="#setup">Perform one-time setup</a>
  40   <ul>
  41   <li> <a href="#devenv">Set up your development environment</a> </li>
  42   <li> <a href="#python">Check your Python version</a> </li>
  43   </ul></li>
  44 <li> <a href="#building">Build Native Client</a> </li>
  45 <li> <a href="#sdk">If you need to build the SDK</a> </li>
  46 <li> <a href="#more">More build options</a>
  47   <ul>
  48   <li> <a href="#h-option">-h: Help</a></li>
  49   <li> <a href="#c-option">-c: Clean</a></li>
  50   <li> <a href="#prebuilt-option">--prebuilt: Use existing binaries</a></li>
  51   <li> <a href="#j-option">-j<em>X</em>: Use multiple processes to build</a> </li>
  52   </ul></li>
  53 </ul>
  54
  55 <h2><a name="setup"> </a> Perform one-time setup </h2>
  56
  57 <p>
  58 To build Native Client you must have
  59 a platform-specific development environment and Python.
  60 </p>
  61
  62
  63 <h3><a name="devenv"> </a> Set up your development environment </h3>
  64
  65 <p>
  66 Follow the instructions for your platform.
  67 </p>
  68
  69 <ul>
  70 <li> <a href="platform-linux.html#dev">Instructions for Linux</a> </li>
  71 <li> <a href="platform-mac.html#dev">Instructions for Mac</a> </li>
  72 <li> <a href="platform-windows.html#dev">Instructions for Windows</a> </li>
  73 </ul>
  74
  75 <h3><a name="python"> </a> Check your Python version </h3>
  76
  77 <p>
  78 If you followed the instructions in
  79 <a href="getting_started.html">Getting Started</a>,
  80 you should already have the right version of Python.
  81 The summary: Use Python 2.4 or 2.5
  82 (possibly 2.6),
  83 don't use the Cygwin version of Python,
  84 and avoid spaces in the path to <code>python</code>.
  85 For further details, see
  86 <a href="getting_started.html#software">Get the software</a>
  87 and the details page for your platform
  88 (<a href="platform-linux.html">Linux</a>,
  89 <a href="platform-mac.html">Mac</a>, or
  90 <a href="platform-windows.html">Windows</a>).
  91 </p>
  92
  93
  94 <h2><a name="building"> </a> Build Native Client </h2>
  95
  96 <p>
  97 Thanks to SCons,
  98 you use the same basic commands to build on all platforms.
  99 </p>
 100
 101 <ol>
 102 <li> <p>
 103      In a shell window, go to the <code>native_client</code> directory
 104      under your Native Client distribution.
 105      For example:
 106
 107 <p>
 108 Linux or Mac:
 109 </p>
 110
 111 <pre class="platform-linux-mac">
 112 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client</kbd>
 113 </pre>
 114
 115 <p>
 116 Windows:
 117 </p>
 118
 119 <pre class="platform-windows">
 120 <kbd>cd <em>install_dir</em>\nacl\googleclient\native_client</kbd>
 121 </pre>
 122 </li>
 123
 124 <li> Build Native Client and the modules that use it.
 125
 126 <p>
 127 Linux or Mac:
 128 </p>
 129
 130 <pre class="platform-linux-mac">
 131 <kbd>./scons --mode=most -c</kbd>&nbsp; <em>#clean</em>
 132 <kbd>./scons --mode=most</kbd> &nbsp;&nbsp;&nbsp; <em>#build</em>
 133 </pre>
 134
 135 <p>
 136 Windows:
 137 </p>
 138
 139 <pre class="platform-windows">
 140 <kbd>.\scons.bat --mode=most -c</kbd>&nbsp; <em>#clean</em>
 141 <kbd>.\scons.bat --mode=most</kbd> &nbsp;&nbsp;&nbsp; <em>#build</em>
 142 </pre>
 143
 144 <p>
 145 <b>Troubleshooting:</b>
 146 If you see a message like the following,
 147 you need to
 148 <a href="#sdk">build the SDK</a>.
 149 </p>
 150 <pre>
 151 NativeClient SDK not present in <em>install_dir</em>/nacl/googleclient/third_party/nacl_sdk/<em>platform</em>/sdk/nacl-sdk
 152 Run again with the --download flag.
 153 </pre>
 154
 155 </li>
 156
 157 <li>
 158 <p> Verify that the build succeeded
 159     by following the steps in
 160     <a href="getting_started.html">Getting Started</a>,
 161     starting with
 162     <a href="getting_started.html#example-nacl">running an example</a>.
 163     </p>
 164 </li>
 165
 166 </ol>
 167
 168 <h2><a name="sdk"> </a> If you need to build the SDK </h2>
 169
 170 <p>
 171 You can probably ignore this section.
 172 The platform-specific distributions of Native Client
 173 have prebuilt SDKs,
 174 so you don't need to build the SDK unless you either
 175 are using the source-only distribution
 176 or have changed SDK files.
 177 </p>
 178
 179 <p>
 180 To build the SDK,
 181 you need <code>make</code>.
 182 Currently, you can build only on Linux or Mac;
 183 you can't build the SDK on Windows, even with Cygwin.
 184 <span class="comment">[PENDING:
 185 When the Windows build starts working, add this:
 186 You can get <code>make</code> as part of Cygwin.]
 187 </span>
 188 </p>
 189
 190 <p class="technote">
 191 <b>Technical detail:</b>
 192 Building the SDK requires <code>make</code>
 193 because part of the SDK
 194 is derived from GNU tools, such as GCC,
 195 that are built using <code>make</code>.
 196 </p>
 197
 198 <p>
 199 Here's how to build the SDK:
 200 </p>
 201
 202 <ol>
 203 <li> In a shell window,
 204 go to the <code>tools</code> directory
 205 under your Native Client distribution.
 206 For example:
 207
 208 <pre class="platform-all">
 209 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client/tools</kbd>
 210 </pre>
 211
 212 <li> Run <code>make</code>,
 213      specifying where to put the SDK (<code>SDKLOC=</code>...).
 214
 215 <p>
 216 Linux:
 217 </p>
 218
 219 <pre class="platform-linux">
 220 <kbd>make SDKLOC=`pwd`/../../third_party/nacl_sdk/linux/sdk</kbd>
 221 </pre>
 222
 223 <p>
 224 Mac:
 225 </p>
 226
 227 <pre class="platform-mac">
 228 <kbd>make SDKLOC=`pwd`/../../third_party/nacl_sdk/mac/sdk</kbd>
 229 </pre>
 230
 231 <div class="comment">
 232 <p>
 233 Windows (Cygwin): [PENDING: add this once the Windows build works]
 234 </p>
 235
 236 <pre class="platform-windows">
 237 <kbd>make SDKLOC=`pwd`/../../third_party/nacl_sdk/windows/sdk</kbd>
 238 </pre>
 239 </div>
 240
 241 </li>
 242
 243 <li> <p>
 244      Check the output to make sure
 245      the build completed successfully.
 246      The build should take about 20 minutes.
 247      </p>
 248      </li>
 249 </ol>
 250
 251 <p>
 252 You should now be able to
 253 <a href="#building">build Native Client</a>.
 254 </p>
 255
 256
 257 <h2><a name="more"> </a> More build options </h2>
 258
 259 <h3><a name="h-option"> </a> -h: Help</h3>
 260
 261 <p>
 262 Displays SCons options.
 263 </p>
 264
 265 <h3><a name="c-option"> </a> -c: Clean</h3>
 266
 267 <p>
 268 Removes build artifacts.
 269 </p>
 270
 271 <h3><a name="prebuilt-option"> </a> --prebuilt: Use existing binaries</h3>
 272
 273 <p>
 274 Forces SCons to use prebuilt binaries,
 275 rather than rebuilding.
 276 For use with <code>firefox_install</code>.
 277 </p>
 278
 279 <h3><a name="j-option"> </a> -j<em>X</em>: Use multiple processes to build </h3>
 280 <p>
 281 If you are on a multi-core machine,
 282 the build process can use multiple cores to speed up the process
 283 by using the <code>-j<em>X</em></code> option,
 284 where <em>X</em> is the number of concurrent processes
 285 you would like to have in flight.
 286 Normally, a good value is the number of physical cores in the machine.
 287 For example, use <code>-j4</code> if your machine has 4 cores,
 288 as the following example shows.
 289 </p>
 290
 291 <pre class="platform-linux">
 292 <kbd>./scons --mode=most -j4</kbd>
 293 </pre>
 294
 295 <p id="license">
 296 Except as otherwise
 297 <a href="http://code.google.com/policies.html#restrictions">noted</a>,
 298 the content of this page is licensed under a
 299 <a href="http://creativecommons.org/licenses/by/2.5/">Creative Commons
 300 Attribution 2.5 license</a>.
 301 </p>
 302
 303 </body>
 304 </html>