documentation/getting_started.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: Getting Started</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>Getting Started</h1>
  16
  17 <p>
  18 This page tells you how to install Native Client
  19 and run demos,
  20 both in and outside of the browser.
  21 On Linux and Mac OS X,
  22 you can also recompile demos
  23 and run them as standalone applications.
  24 </p>
  25
  26 <h3>Contents</h3>
  27
  28 <ul>
  29 <li> <a href="#software">Get the software</a> </li>
  30 <li> <a href="#example-nacl">Run an example as a Native Client app</a></li>
  31 <li> <a href="#plugin">Install and use the plug-in</a></li>
  32 <li> <a href="#make">Use make to compile and run standalone examples (Linux or Mac)</a></li>
  33 <li> <a href="#next">What next?</a>
  34 </ul>
  35
  36 <h2><a name="software" id="software"></a>Get the software</h2>
  37
  38 <p>
  39 To run the examples as Native Client modules,
  40 you need Native Client, Python,
  41 and a browser &mdash;
  42 we recommend Firefox 3.
  43 If you want to develop your own Native Client modules,
  44 you'll also need platform-specific development tools
  45 such as Xcode on the Mac and Visual Studio on Windows,
  46 as described in
  47 the <a href="#make">make section</a>
  48 and the page
  49 <a href="building.html">Building Native Client</a>.
  50 </p>
  51
  52 <p class="technote">
  53 <b>Technical detail:</b>
  54 Native Client doesn't itself require Python.
  55 We use Python for scripts
  56 such as those that build and run examples
  57 and that install the Native Client plug-in.
  58 We're working on simpler installers that don't require Python.
  59 </p>
  60
  61 <p>
  62 Here's how to install Native Client and Python.
  63 </p>
  64
  65 <ol>
  66
  67 <li>
  68 <p>
  69 Choose an installation directory (<em>install_dir</em>).
  70 Because Native Client is frequently updated,
  71 you might want a path that indicates the download or build date.
  72 For example:
  73
  74 <ul>
  75 <li>
  76 <code>/home/me/NaCl/Testing/2009-02-11&nbsp;&nbsp;&nbsp;</code> <em>(Linux)</em>
  77 </li>
  78 <li>
  79 <code>/Users/me/NaCl/Testing/2009-02-11&nbsp;&nbsp;</code> <em>(Mac)</em>
  80 </li>
  81 <li>
  82 <code>C:\NaCl\Testing\2009-02-11&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code> <em>(Windows)</em>
  83 </li>
  84 </ul>
  85
  86 <p>
  87 <b>Important:</b>
  88 Make sure the full path of <em>install_dir</em> contains <b>no spaces</b>.
  89 </p>
  90 </li>
  91
  92 <li>
  93 <p>
  94 <a href="http://code.google.com/p/nativeclient/wiki/Downloads?tm=2">Download</a>
  95 the Native Client <code>.tgz</code> or <code>.zip</code> file for your platform.
  96 </p>
  97 </li>
  98
  99 <li>
 100 Extract the files into <em>install_dir</em>.
 101 For example:
 102 </p>
 103
 104 <p>Linux:</p>
 105 <pre class="platform-linux">
 106 <kbd>tar xvf nacl_linux*.tgz</kbd>
 107 </pre>
 108
 109 <p>Mac:</p>
 110 <pre class="platform-mac">
 111 <kbd>tar xvf nacl_mac*.tgz</kbd>
 112 </pre>
 113
 114 <p>
 115 Windows:
 116 </p>
 117 <blockquote>
 118 Do <em>not</em> use Cygwin unzip.
 119 Instead, you can use the built-in Windows support or 7-Zip.
 120 For example: In the file manager,
 121 right-click the <code>nacl_windows_*.zip file</code>
 122 and choose Extract All.
 123 </blockquote>
 124 </li>
 125
 126 <li>
 127 <p>
 128 Test your version of Python.
 129 </p>
 130
 131 <pre class="platform-all">
 132 <kbd>python -V</kbd>  <em>#Note: That's an uppercase 'V'</em>
 133 </pre>
 134
 135 <p>
 136 The output should be something like
 137 <code>Python 2.4.3</code>.
 138 If your system can't find <code>python</code>
 139 or the version isn't 2.4 or 2.5,
 140 get the right version of Python
 141 and make sure it's in your path.
 142 For details, see the
 143 <a href="building.html">Native Client build instructions</a>.
 144
 145 <p>
 146 <b>Windows note:</b>
 147 <b>Do not use Cygwin's version of Python</b>.
 148 Instead, use the standard Python distribution.
 149 For details, see the
 150 <a href="building.html#setup-windows">Windows setup instructions</a>.
 151 </p>
 152 </li>
 153
 154 </ol>
 155
 156
 157 <h2><a name="example-nacl" id="example-nacl"></a>Run an example as a Native Client app</h2>
 158
 159 <p>
 160 Now you'll learn how to run an example app in Native Client.
 161 </p>
 162
 163 <p class="technote">
 164 <b>Technical detail:</b>
 165 You might be wondering why we start you off with a command-line application,
 166 rather than with the browser.
 167 The reason is that when you create your own Native Client modules,
 168 it's easier to get started
 169 if you're working outside the browser.
 170 </p>
 171
 172 <ol>
 173 <li>
 174 <p>
 175 In a terminal window, go to the earth demo's directory.
 176 </p>
 177
 178 <p>
 179 Linux or Mac:
 180 </p>
 181
 182 <pre class="platform-linux-mac">
 183 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client/tests/earth</kbd>
 184 </pre>
 185
 186 <p>
 187 Windows:
 188 </p>
 189
 190 <pre class="platform-windows">
 191 <kbd>cd <em>install_dir</em>\nacl\googleclient\native_client\tests\earth</kbd>
 192 </pre>
 193 </li>
 194
 195 <li>
 196 <p>
 197 Run the earth demo as a Native Client application.
 198 The command is the same on all platforms:
 199 </p>
 200 </li>
 201
 202 <pre class="platform-all">
 203 <kbd>python run.py</kbd>
 204 </pre>
 205
 206 <p>
 207 A window should appear
 208 that contains a spinning, ray-traced globe.
 209 The title of the window, <b>NaCl Application</b>,
 210 indicates that you're running a Native Client module in a dedicated process.
 211 </p>
 212
 213 <img src="images/NaClApp.jpg"
 214  width="512" height="534"
 215  alt="screenshot of the earth demo" />
 216 <div class="caption">Figure: The earth demo running as a Native Client app (on Mac)</span></div>
 217
 218 <p>
 219 You can quit the earth demo by clicking the close (X) button
 220 in its window frame.
 221 Or just wait; it quits automatically
 222 after displaying 10000 frames.
 223 </p>
 224
 225 <p>
 226 <b>Troubleshooting:</b>
 227 If no window appears
 228 and you get a message starting with
 229 <code>ERROR: Cannot find Native Client executable</code>,
 230 you've probably downloaded the source-only distribution of Native Client.
 231 You can either
 232 <a href="http://code.google.com/p/nativeclient/wiki/Downloads?tm=2">download the distribution for your platform</a>
 233 (Linux, Mac, or Windows)
 234 or <a href="building.html">build Native Client and its SDK</a>.
 235 </p>
 236
 237 <p class="comment">
 238 [PENDING: What other problems have people run into?]
 239 </p>
 240 </li>
 241 </ol>
 242
 243 <h2><a name="plugin" id="plugin"> </a> Install and use the plug-in </h2>
 244
 245 <p>
 246 Now it's time to run some Native Client modules inside a browser.
 247 To do so, you need to install the Native Client plug-in
 248 and then load a page that refers to one or more Native Client modules.
 249 </p>
 250
 251 <ol>
 252 <li>
 253 <p>
 254 Go to the <code>native_client</code> directory:
 255 </p>
 256
 257 <p>
 258 Linux or Mac:
 259 </p>
 260
 261 <pre class="platform-linux-mac">
 262 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client</kbd>
 263 </pre>
 264
 265 <p>
 266 Windows:
 267 </p>
 268
 269 <pre class="platform-windows">
 270 <kbd>cd <em>install_dir</em>\nacl\googleclient\native_client</kbd>
 271 </pre>
 272 </li>
 273
 274 <li>
 275 <p>
 276 Bookmark this page,
 277 both <a href="http://nativeclient.googlecode.com/svn/trunk/nacl/googleclient/native_client/documentation/getting_started.html">online</a>
 278 and in your Native Client distribution
 279 (<em>install_dir</em>/nacl/googleclient/native_client/documentation/getting_started.html</b>).
 280 The bookmarks will make it easier for you to get back to these instructions
 281 after restarting your browser.
 282 Consider printing out this page, as well,
 283 or saving these instructions to a text or PDF file.
 284 </p>
 285 </li>
 286
 287 <li>
 288 <p>
 289 Exit Firefox if you're running it.
 290 Also exit any other browsers that might have run a Native Client module.
 291 The plug-in might not install correctly if Firefox is running
 292 or if any other browser is running a Native Client module.
 293 </p>
 294 </li>
 295
 296 <li>
 297 <p>
 298 Install the plug-in.
 299 Answer <b>y</b> when asked whether you want to continue.
 300 </p>
 301
 302 <p>
 303 Linux or Mac:
 304 </p>
 305
 306 <pre class="platform-linux-mac">
 307 <kbd>./scons --prebuilt firefox_install</kbd>
 308 ...
 309 Okay to continue? [y/n] <kbd>y</kbd>
 310 ...
 311 </pre>
 312
 313 <p class="technote">
 314 <b>Technical detail:</b>
 315 The <code>--prebuilt</code> option
 316 isn't strictly necessary,
 317 but it makes the install go much more quickly.
 318 Without it, SCons attempts to rebuild some of the Native Client binaries.
 319 </p>
 320
 321 <p>
 322 <b>Linux note:</b>
 323 If you're using a 64-bit Linux system,
 324 we recommend that you use a 32-bit browser.
 325 For instructions, search for
 326 [<a href="http://www.google.com/search?&q=linux+32-bit+64-bit+browser">linux 32-bit 64-bit browser</a>].
 327 <em>If you're adventurous</em>
 328 and your modules don't use NPAPI,
 329 then you might be able to instead use
 330 <a href="http://gwenole.beauchesne.info/en/projects/nspluginwrapper">NSPluginWrapper</a>
 331 (version 1.1.2 or newer)
 332 to make the Native Client plug-in work
 333 in a 64-bit browser.
 334 Don't use NSPluginWrapper if your modules depend on NPAPI;
 335 the performance impact of NSPluginWrapper's NPAPI forwarding can be huge.
 336 </p>
 337
 338 <p>
 339 Windows:
 340 </p>
 341
 342 <pre class="platform-windows">
 343 <kbd>.\scons.bat --prebuilt firefox_install</kbd>
 344 ...
 345 Okay to continue? [y/n] <kbd>y</kbd>
 346 ...
 347 </pre>
 348
 349 <p>
 350 <b>Vista note:</b>
 351 If UAC is enabled,
 352 you can't use SCons to install the plug-in on Vista.
 353 Instead, you need to copy three files into
 354 <code>C:\Program Files\Mozilla Firefox\plugins</code>:
 355 </p>
 356
 357 <ul>
 358 <li> <code><em>install_dir</em>\nacl\googleclient\native_client\scons-out\opt-win\staging\<b>npGoogleNaClPlugin.dll</b></code> </li>
 359 <li> <code><em>install_dir</em>\nacl\googleclient\native_client\scons-out\opt-win\staging\<b>SDL.dll</b></code> </li>
 360 <li> <code><em>install_dir</em>\nacl\googleclient\native_client\scons-out\opt-win\staging\<b>sel_ldr.exe</b></code> </li>
 361 </ul>
 362
 363 <p class="comment">
 364 [PENDING: Troubleshoot any likely problems.]
 365 </p>
 366 </li>
 367
 368 <li>
 369 <p>
 370 Look at the installer output
 371 to make sure the installation was successful.
 372 </p>
 373 </li>
 374
 375 <li>
 376 <p>
 377 Launch Firefox.
 378 </p>
 379 </li>
 380
 381 <li>
 382 <p>
 383 In Firefox, look at the following file:
 384 </p>
 385
 386 <blockquote>
 387 <a href="../scons-out/nacl/staging/index.html"><code><em>install_dir</em>/nacl/googleclient/native_client/scons-out/nacl/staging/index.html</code></a>
 388 </blockquote>
 389
 390 <p>
 391 <b>Note:</b>
 392 That link works only if you're viewing this page
 393 within the Native Client distribution, at
 394 <code><em>install_dir</em>/nacl/googleclient/native_client/documentation/getting_started.html</code>.
 395 </p>
 396
 397 <li>
 398 <p>
 399 Click the bottom-left link to go to the Mandelbrot viewer page.
 400 This page has a Native Client implementation
 401 of a Mandelbrot drawing.
 402 You should see something like this:
 403 </p>
 404
 405 <p>
 406 <img src="images/mandelbrot.jpg"
 407  width="587" height="536"
 408  border="1"
 409  alt="screenshot of the Mandelbrot viewer demo" />
 410 <div class="caption">Figure: The Mandelbrot viewer demo</div>
 411 </p>
 412
 413 <p>
 414 Play with the demo.
 415 You can click the Cycle Colors button to see an everchanging display of colors.
 416 Press and hold the + button to zoom in.
 417 Use the arrows on the large round button to
 418 change which part of the Mandelbrot you can see.
 419 </p>
 420
 421 </li>
 422
 423 </ol>
 424
 425 <p>
 426 For information about the other demos you can run in your browser, see
 427 <a href="examples.html">Examples and Tests</a>.
 428 </p>
 429
 430 <h2><a name="make" id="make"> </a> Use make to compile and run standalone examples (Linux or Mac)</h2>
 431
 432 <p>
 433 In this section, you'll use GNU <code>make</code>
 434 to compile and run the same example that you've already run.
 435 First, you'll make a version that runs as a standalone application.
 436 Next, you'll use <code>make</code>
 437 to recompile the example and run it again as a Native Client app,
 438 using the binaries that you created instead of prebuilt binaries.
 439 Finally, you'll use <code>make clean</code>
 440 and run the Native Client app again using the prebuilt binaries.
 441 </p>
 442
 443 <p class="technote">
 444 <b>Technical detail:</b>
 445 The standard build tool for Native Client is
 446 SCons, not make.
 447 You can compile our examples (on any platform) using SCons,
 448 following the instructions in
 449 <a href="building.html">Building Native Client</a>.
 450 The Makefiles exist so that
 451 you can more easily use our examples
 452 as templates for your own programs,
 453 and so you can run our examples
 454 as either Native Client or standalone applications (on Linux and Mac).
 455 Running a module as a standalone application
 456 can be handy when you're
 457 <a href="debugging.html">debugging</a>.
 458 </p>
 459
 460 <p>
 461 To perform the steps in this section,
 462 your development environment needs to be set up
 463 as described in the build instructions for your platform &mdash;
 464 <a href="building.html#setup-linux">Setup: Linux</a> or
 465 <a href="building.html#setup-mac">Setup: Mac OS X</a>.
 466 Native Client doesn't support <code>make</code> or standalone apps on Windows.
 467 </p>
 468
 469 <ol>
 470 <li>
 471 <p>
 472 In a terminal window, go to the earth demo's directory:
 473 </p>
 474
 475 <pre class="platform-linux-mac">
 476 <kbd>cd <em>install_dir</em>/nacl/googleclient/native_client/tests/earth</kbd>
 477 </pre>
 478 </li>
 479
 480 <li>
 481 <p>
 482 Recompile the demo as a standalone application and run it.
 483 </p>
 484
 485 <pre class="platform-linux-mac">
 486 <kbd>make debug run</kbd>
 487 </pre>
 488
 489 <p>
 490 Just like before,
 491 you should see a window with
 492 a spinning globe.
 493 This time, the title of the window is <b>Standalone Application</b>.
 494 You'll also see the <code>g++</code> command
 495 used to compile the demo as an app.
 496 </p>
 497
 498 <p class="comment">
 499 [PENDING: Troubleshoot any likely problems &mdash; e.g. make missing
 500 on a Mac that doesn't have Xcode installed.]
 501 </p>
 502 </li>
 503
 504 <li>
 505 <p>
 506 Recompile the demo as a Native Client module and run it again:
 507 </p>
 508
 509 <pre class="platform-linux-mac">
 510 <kbd>make release nacl run</kbd>
 511 </pre>
 512
 513 <p>
 514 Again you should see a spinning globe
 515 with the title <b>NaCl Application</b>.
 516 You'll also see the <code>nacl-g++</code> command
 517 that compiles the demo
 518 and the <code>sel_ldr</code> command
 519 that runs it in the Native Client environment.
 520 </p>
 521
 522 <li>
 523 <p>
 524 Remove the binaries you built,
 525 and use the prebuilt binaries
 526 to run the example again as a Native Client module.
 527 </p>
 528
 529 <pre class="platform-linux-mac">
 530 <kbd>make clean</kbd>
 531 <kbd>python run.py</kbd>
 532 </pre>
 533
 534 <p>
 535 You can still run the example after running <code>make clean</code>
 536 because the Makefile refers to binaries in the current directory.
 537 The Python script, on the other hand,
 538 refers to binaries
 539 that are in the <code>scons-out/nacl/staging</code> directory
 540 (which is under <code>nacl/googleclient/native_client</code>).
 541 The binaries under <code>scons-out</code>
 542 are prebuilt for you,
 543 but you can always rebuild using SCons,
 544 as described in
 545 <a href="building.html">Building Native Client</a>.
 546 </p>
 547
 548 </li>
 549 </ol>
 550
 551 <h2><a name="next" id="next"></a>What next?</h2>
 552
 553 <p>
 554 Please try these:
 555 </p>
 556
 557 <ul>
 558 <li> Run all the
 559      <a href="examples.html">examples and tests</a>. </li>
 560 <li> <a href="building.html">Build Native Client</a>
 561      from scratch. </li>
 562 <li> Build Quake and XaoS for Native Client;
 563      run them.
 564      For instructions, see the <code>README.nacl</code> files under
 565      <code>nacl/googleclient/native_client/tests/quake</code> and
 566      <code>nacl/googleclient/native_client/tests/xaos</code>.</li>
 567 <li> Browse the <a href="../README.html">documentation</a>, including the
 568      <a href="nacl_paper.pdf">Native Client paper</a> [PDF].</li>
 569 <li> Browse the project site,
 570      <a href="http://code.google.com/p/nativeclient">http://code.google.com/p/nativeclient</a>,
 571      including the
 572      <a href="http://code.google.com/p/nativeclient/wiki">wiki</a>.</li>
 573 </ul>
 574
 575 <p>
 576 For even more fun, consider:
 577 </p>
 578
 579 <ul>
 580 <li> Port existing open-source packages to run as
 581      Native Client module components. </li>
 582 <li> Write new Native Client modules that use
 583      Native Client's reduced system call interface, NPAPI, and SRPC
 584      to communicate with the browser. </li>
 585 <li> Defeat the NaCl sandbox.
 586      Can you create a NaCl module
 587      that creates a file in the local file system
 588      or otherwise directly executes a system call?
 589      Exploits using <code>sel_ldr</code> from the command line
 590      or from the browser plug-in are both of interest.
 591      Don't use the <code>-d</code> debug flag &mdash;
 592      that would be too easy.
 593      For more suggestions and details,
 594      see the wiki page
 595      <a href="http://code.google.com/p/nativeclient/wiki/WhatToTest">WhatToTest</a>.
 596      </li>
 597 </ul>
 598
 599 <p>
 600 And please participate in the Native Client community:
 601 </p>
 602
 603 <ul>
 604 <li> Join the
 605      <a href="http://groups.google.com/group/native-client-discuss">discussion
 606      group</a> and the
 607      <a href="http://groups.google.com/group/native-client-announce">announcement
 608      group</a>.</li>
 609 <li> <a href="http://code.google.com/p/nativeclient/issues">File issues</a>
 610      about any Native Client problems you've noticed
 611      or features you'd like.</li>
 612 </ul>
 613
 614 <p id="license">
 615 Except as otherwise
 616 <a href="http://code.google.com/policies.html#restrictions">noted</a>,
 617 the content of this page is licensed under a
 618 <a href="http://creativecommons.org/licenses/by/2.5/">Creative Commons
 619 Attribution 2.5 license</a>.
 620 </p>
 621
 622 </body>
 623 </html>