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