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="#python">Check your Python version</a> </li>
  42   <li> <a href="#setup-linux">Setup: Linux</a> </li>
  43   <li> <a href="#setup-mac">Setup: Mac OS X</a> </li>
  44   <li> <a href="#setup-windows">Setup: Windows</a> </li>
  45   </ul></li>
  46 <li> <a href="#building">Build Native Client</a> </li>
  47 <li> <a href="#sdk">If you need to build the SDK</a> </li>
  48 <li> <a href="#more">More build options</a>
  49   <ul>
  50   <li> <a href="#h-option">-h: Help</a></li>
  51   <li> <a href="#c-option">-c: Clean</a></li>
  52   <li> <a href="#prebuilt-option">--prebuilt: Use existing binaries</a></li>
  53   <li> <a href="#j-option">-j<em>X</em>: Use multiple processes to build</a> </li>
  54   </ul></li>
  55 </ul>
  56
  57 <h2><a name="setup"> </a> Perform one-time setup </h2>
  58
  59 <p>
  60 To build Native Client you must have Python
  61 and a platform-specific development environment.
  62 Native Client has been tested with the following configurations:
  63 </p>
  64
  65 <ul>
  66 <li> Linux:
  67      Ubuntu 8.04 (Hardy Heron) and
  68      6.06 (Dapper Drake);
  69      Python 2.4.
  70      </li>
  71 <li> Mac:
  72      Mac OS X 10.5;
  73      Xcode 3.*;
  74      Python 2.5.
  75      </li>
  76 <li> Windows:
  77      XP or Vista;
  78      Visual Studio 2005 (8.0);
  79      Python 2.4.
  80      </li>
  81 </ul>
  82
  83 <p>
  84 For details and additional requirements,
  85 see the <a href="#python">next section</a> and the section for your platform:
  86 <a href="#setup-linux">Linux</a>,
  87 <a href="#setup-mac">Mac OS X</a>, or
  88 <a href="#setup-windows">Windows</a>.
  89 </p>
  90
  91 <h3><a name="python"> </a> Check your Python version </h3>
  92
  93 <p>
  94 Python version 2.4 works best, but 2.5 should also work.
  95 2.3 does not work; we haven't tested 2.6.
  96 </p>
  97
  98 <p>
  99 To check the version of your default <code>python</code> command,
 100 enter the following in a terminal window:
 101 </p>
 102
 103 <pre class="platform-all">
 104 <kbd>python -V</kbd>  <em>#Note: That's an uppercase 'V'</em>
 105 </pre>
 106
 107 <p>
 108 The output should be something like
 109 <code>Python 2.4.3</code>.
 110 If the version string doesn't begin
 111 with <code>2.4</code> or <code>2.5</code>,
 112 get Python 2.4 and make it the default version in your path.
 113 </p>
 114
 115 <p>
 116 <b>Important:</b>
 117 Make sure the full path to <code>python</code> contains <b>no spaces</b>.
 118 </p>
 119
 120 <h3><a name="setup-linux"> </a> Setup: Linux </h3>
 121
 122 <p>
 123 You need to have the right version of Python
 124 installed to use Native Client on Linux.
 125 If you're using a 64-bit system,
 126 you have a bit more work to do.
 127 </p>
 128
 129 <ol>
 130 <li>
 131   Make sure your
 132   <a href="#python">Python version is 2.4 or 2.5</a>.
 133   On Debian-based distributions such as Ubuntu,
 134   you can use the following command to get Python 2.4:
 135
 136 <pre class="platform-linux">
 137 <kbd>sudo apt-get install python2.4</kbd>
 138 </pre>
 139
 140 <p>
 141 Or use Synaptic (<code>sudo synaptic</code>)
 142 for a friendlier interface to APT.
 143 </p>
 144 </li>
 145
 146 <li>
 147   Building on 64-bit systems is not as well tested as
 148   building on 32-bit systems.
 149   However, if you'd like to try building on a 64-bit system,
 150   then run the prep script first:
 151
 152 <pre class="platform-linux">
 153 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client/tools</kbd>
 154 <kbd>./linux.x86_64.prep.sh</kbd>
 155 </pre>
 156
 157 </li>
 158 </ol>
 159
 160
 161 <h3><a name="setup-mac"> </a> Setup: Mac OS X</h3>
 162
 163 <p>
 164 You need the following software to build Native Client on Mac OS X:
 165 </p>
 166
 167 <ul>
 168 <li> Mac OS X 10.5
 169 - We don't test on earlier versions.</li>
 170 <li> Xcode
 171 - You can download this if you don't already have it.
 172   For details, see
 173   <a href="http://developer.apple.com/tools/xcode">http://developer.apple.com/tools/xcode</a>.</li>
 174 <li> Python 2.4 or 2.5
 175 - <a href="#python">Test the Python version</a>.
 176 If <code>python</code> isn't present or isn't 2.4 or 2.5,
 177 download Python 2.4 and make sure it's in your path.
 178 </li>
 179 </ul>
 180
 181 <h3><a name="setup-windows"> </a> Setup: Windows </h3>
 182
 183 <p>
 184 You need the following software to build Native Client on Windows:
 185 </p>
 186
 187 <ul>
 188 <li> Windows XP or Vista </li>
 189 <li> Visual Studio 2005 (8.0) </li>
 190 <li> Cygwin
 191 - Required only if you need to run <code>make</code> &mdash;
 192 for example, if you need to build the SDK
 193 <br />
 194 <b>Note:</b> If you have Cygwin,
 195 use the <b>xterm</b> shell window instead of <code>cygwin.bat</code>.
 196 <li> Python 2.4 or 2.5
 197 - <a href="#python">Test the Python version</a>.
 198 If <code>python</code> isn't present, isn't 2.4 or 2.5,
 199 or is the Cygwin version,
 200 download Python 2.4 and make sure it's in your path.
 201 </li>
 202 </ul>
 203
 204 <p>
 205 <b>Cygwin note:</b>
 206 If you have Cygwin,
 207 make sure your <code>python</code> command
 208 is from the standard Python distribution,
 209 not from Cygwin.
 210 You can test using the following command:
 211 </p>
 212
 213 <pre>
 214 <kbd>python -c "import sys; print sys.platform"</kbd>
 215 </pre>
 216
 217 <p>
 218 If the output is <code>cygwin</code>,
 219 then you're using the Cygwin version of Python
 220 and need to find the standard version.
 221 Once you have the standard version,
 222 put its directory at the front of your PATH:
 223 </p>
 224
 225 <pre>
 226 <kbd>set PATH=c:\<em>python_install_dir</em>;%PATH%</kbd>
 227 </pre>
 228
 229
 230 <h2><a name="building"> </a> Build Native Client </h2>
 231
 232 <p>
 233 Thanks to SCons,
 234 you use the same basic commands to build on all platforms.
 235 </p>
 236
 237 <ol>
 238 <li> <p>
 239      In a shell window, go to the <code>native_client</code> directory
 240      under your Native Client distribution.
 241      For example:
 242
 243 <p>
 244 Linux or Mac:
 245 </p>
 246
 247 <pre class="platform-linux-mac">
 248 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client</kbd>
 249 </pre>
 250
 251 <p>
 252 Windows:
 253 </p>
 254
 255 <pre class="platform-windows">
 256 <kbd>cd <em>install_dir</em>\nacl\googleclient\native_client</kbd>
 257 </pre>
 258 </li>
 259
 260 <li> Build Native Client and the modules that use it.
 261
 262 <p>
 263 Linux or Mac:
 264 </p>
 265
 266 <pre class="platform-linux-mac">
 267 <kbd>./scons --mode=most -c</kbd>&nbsp; <em>#clean</em>
 268 <kbd>./scons --mode=most</kbd> &nbsp;&nbsp;&nbsp; <em>#build</em>
 269 </pre>
 270
 271 <p>
 272 Windows:
 273 </p>
 274
 275 <pre class="platform-windows">
 276 <kbd>.\scons.bat --mode=most -c</kbd>&nbsp; <em>#clean</em>
 277 <kbd>.\scons.bat --mode=most</kbd> &nbsp;&nbsp;&nbsp; <em>#build</em>
 278 </pre>
 279
 280 <p>
 281 <b>Troubleshooting:</b>
 282 If you see a message like the following,
 283 you need to
 284 <a href="#sdk">build the SDK</a>.
 285 </p>
 286 <pre>
 287 NativeClient SDK not present in <em>install_dir</em>/nacl/googleclient/third_party/nacl_sdk/<em>platform</em>/sdk/nacl-sdk
 288 Run again with the --download flag.
 289 </pre>
 290
 291 </li>
 292
 293 <li>
 294 <p> Verify that the build succeeded
 295     by following the steps in
 296     <a href="getting_started.html">Getting Started</a>,
 297     starting with
 298     <a href="getting_started.html#example-nacl">running an example</a>.
 299     </p>
 300 </li>
 301
 302 </ol>
 303
 304 <h2><a name="sdk"> </a> If you need to build the SDK </h2>
 305
 306 <p>
 307 You can probably ignore this section.
 308 The platform-specific distributions of Native Client
 309 have prebuilt SDKs,
 310 so you don't need to build the SDK unless you either
 311 are using the source-only distribution
 312 or have changed SDK files.
 313 </p>
 314
 315 <p>
 316 To build the SDK,
 317 you need <code>make</code>.
 318 Currently, you can build only on Linux or Mac;
 319 you can't build the SDK on Windows, even with Cygwin.
 320 <span class="comment">[PENDING:
 321 When the Windows build starts working, add this:
 322 You can get <code>make</code> as part of Cygwin.]
 323 </span>
 324 </p>
 325
 326 <p class="technote">
 327 <b>Technical detail:</b>
 328 Building the SDK requires <code>make</code>
 329 because part of the SDK
 330 is derived from GNU tools, such as GCC,
 331 that are built using <code>make</code>.
 332 </p>
 333
 334 <p>
 335 Here's how to build the SDK:
 336 </p>
 337
 338 <ol>
 339 <li> In a shell window,
 340 go to the <code>tools</code> directory
 341 under your Native Client distribution.
 342 For example:
 343
 344 <pre class="platform-all">
 345 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client/tools</kbd>
 346 </pre>
 347
 348 <li> Run <code>make</code>,
 349      specifying where to put the SDK (<code>SDKLOC=</code>...).
 350
 351 <p>
 352 Linux:
 353 </p>
 354
 355 <pre class="platform-linux">
 356 <kbd>make SDKLOC=`pwd`/../../third_party/nacl_sdk/linux/sdk</kbd>
 357 </pre>
 358
 359 <p>
 360 Mac:
 361 </p>
 362
 363 <pre class="platform-mac">
 364 <kbd>make SDKLOC=`pwd`/../../third_party/nacl_sdk/mac/sdk</kbd>
 365 </pre>
 366
 367 <div class="comment">
 368 <p>
 369 Windows (Cygwin): [PENDING: add this once the Windows build works]
 370 </p>
 371
 372 <pre class="platform-windows">
 373 <kbd>make SDKLOC=`pwd`/../../third_party/nacl_sdk/windows/sdk</kbd>
 374 </pre>
 375 </div>
 376
 377 </li>
 378
 379 <li> <p>
 380      Check the output to make sure
 381      the build completed successfully.
 382      The build should take about 20 minutes.
 383      </p>
 384      </li>
 385
 386 <li> Continue <a href="#building">building Native Client</a>.
 387      </li>
 388
 389 </ol>
 390
 391 <h2><a name="more"> </a> More build options </h2>
 392
 393 <h3><a name="h-option"> </a> -h: Help</h3>
 394
 395 <p>
 396 Displays SCons options.
 397 </p>
 398
 399 <h3><a name="c-option"> </a> -c: Clean</h3>
 400
 401 <p>
 402 Removes build artifacts.
 403 </p>
 404
 405 <h3><a name="prebuilt-option"> </a> --prebuilt: Use existing binaries</h3>
 406
 407 <p>
 408 Forces SCons to use prebuilt binaries,
 409 rather than rebuilding.
 410 For use with <code>firefox_install</code>.
 411 </p>
 412
 413 <h3><a name="j-option"> </a> -j<em>X</em>: Use multiple processes to build </h3>
 414 <p>
 415 If you are on a multi-core machine,
 416 the build process can use multiple cores to speed up the process
 417 by using the <code>-j<em>X</em></code> option,
 418 where <em>X</em> is the number of concurrent processes
 419 you would like to have in flight.
 420 Normally, a good value is the number of physical cores in the machine.
 421 For example, use <code>-j4</code> if your machine has 4 cores,
 422 as the following example shows.
 423 </p>
 424
 425 <pre class="platform-linux">
 426 <kbd>./scons --mode=most -j4</kbd>
 427 </pre>
 428
 429 <p id="license">
 430 Except as otherwise
 431 <a href="http://code.google.com/policies.html#restrictions">noted</a>,
 432 the content of this page is licensed under a
 433 <a href="http://creativecommons.org/licenses/by/2.5/">Creative Commons
 434 Attribution 2.5 license</a>.
 435 </p>
 436
 437 </body>
 438 </html>