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