1########################## 2Frequently Asked Questions 3########################## 4 5.. contents:: 6 :local: 7 :backlinks: none 8 :depth: 2 9 10This document answers some frequently asked questions about Native 11Client (NaCl) and Portable Native Client (PNaCl, pronounced 12"pinnacle"). For a high-level overview of Native Client, see the 13:doc:`Technical Overview <overview>`. 14 15If you have questions that aren't covered in this FAQ: 16 17* Scan through the :doc:`Release Notes <sdk/release-notes>`. 18* Search through or ask on the :doc:`Native Client Forums <help>`. 19 20 21What is Native Client Good For? 22=============================== 23 24Why did Google build Native Client? 25----------------------------------- 26 27* **Performance:** Native Client modules run nearly as fast as native 28 compiled code. 29* **Security:** Native Client lets users run native compiled code in the 30 browser with the same level of security and privacy as traditional web 31 applications. 32* **Convenience:** 33 34 * Developers can leverage existing code, written in C/C++ or other 35 languages, in their applications without forcing users to install a 36 plugin. 37 * This code can interact with the embedding web page as part of an 38 HTML and JavaScript web application, or it can be a self-contained 39 and immersive experience. 40 41* **Portability:** Native Client and Portable Native Client applications 42 can execute on: 43 44 * The Windows, Mac, Linux or ChromeOS operating systems. 45 * Processors with the x86-32, x86-64, or ARM instruction set 46 architectures. Native Client also has experimental support for MIPS. 47 48Portable Native client further enhances the above: 49 50* **Performance:** Each PNaCl release brings with it more performance 51 enhancements. Already-released applications get faster over time, 52 conserving user's battery. 53* **Security:** Users are kept secure with an ever-improving sandbox 54 model which adapts to novel attacks, without affecting 55 already-released applications. 56* **Convenience:** Developers only need to ship a single ``.pexe`` file, 57 not one ``.nexe`` file per supported architecture. 58* **Portability:** Developers and users don't need to worry about 59 already-released applications not working on new hardware: PNaCl 60 already supports all architectures NaCl does, and as PNaCl evolves it 61 gains support for new processors and fully uses their capabilities. 62 63.. TODO Expand on the PNaCl performance section in another document, and 64.. link to it here. How does one profile PNaCl code? What are common 65.. causes of slowness? How can code be made faster? What's the best way 66.. to use Pepper's asynchronous APIs? What do I need to know about 67.. threads and inter-thread communications? Can I use SIMD or other 68.. processor-specific instructions? What about the GPU? 69 70For more details, refer to the :doc:`history behind and comparison of 71NaCl and PNaCl <nacl-and-pnacl>`. 72 73When should I use Portable Native Client instead of Native Client? 74------------------------------------------------------------------ 75 76See :doc:`NaCl and PNaCl <nacl-and-pnacl>`. In short: PNaCl works on the Open 77Web platform delivered by Chrome whereas NaCl only works on the Chrome Web 78Store. 79 80When should I use Portable Native Client / Native Client? 81--------------------------------------------------------- 82 83The following are some typical use cases. For details, see the 84:doc:`Technical Overview <overview>`. 85 86* Porting existing applications or software components, written in C/C++ or 87 virtual machines written in C/C++, for use in a web application. 88* Using compute-intensive applications, including threads and SIMD, such as: 89 90 * Scientific computing. 91 * Handling multimedia for a web application. 92 * Various aspects of web-based games, including physics engines and AI. 93 94* Running untrusted code on a server or within an application (such as a plugin 95 system for a game). 96 97Portable Native Client and Native Client are versatile technologies which are 98used in many other contexts outside of Chrome. 99 100How fast does code run in Portable Native Client? 101------------------------------------------------- 102 103Fast! The SPEC2k benchmarks (C, C++ and floating-point benchmarks) give 104the following overhead for optimized PNaCl compared to regular optimized 105LLVM: 106 107+--------+-----+ 108| x86-32 | 15% | 109+--------+-----+ 110| x86-64 | 25% | 111+--------+-----+ 112| ARM | 10% | 113+--------+-----+ 114 115Note that benchmark performance is sometimes bimodal, so different use 116cases are likely to achieve better or worse performance than the above 117averages. For example floating-point heavy code usually exhibits much 118lower overheads whereas very branch-heavy code often performs worse. 119 120Note that PNaCl supports performance features that are often used in 121native code such as :ref:`threading <language_support_threading>` and 122:ref:`Portable SIMD Vectors <portable_simd_vectors>`. 123 124For details, see: 125 126* `PNaCl SIMD: Speed on the Web`_. 127* `Adapting Software Fault Isolation to Contemporary CPU Architectures`_ (PDF). 128* `Native Client: A Sandbox for Portable, Untrusted x86 Code`_ (PDF). 129 130If your code isn't performing as close to native speed as you'd expect, 131:doc:`let us know <help>`! 132 133.. TODO Link to the non-existent performance page! (see above todo). 134 135Why use Portable Native Client instead of *<technology X>*? 136----------------------------------------------------------- 137 138Many other technologies can be compared to Portable Native Client: 139Flash, Java, Silverlight, ActiveX, .NET, asm.js, etc... 140 141Different technologies have different strengths and weaknesses. In 142appropriate contexts, Portable Native Client can be faster, more secure, 143and/or more compatible across operating systems and architectures than 144other technologies. 145 146Portable Native Client complement other technologies by giving web 147developers a new capability: the ability to run fast, secure native code 148from a web browser in an architecture-independent way. 149 150If I want direct access to the OS, should I use Native Client? 151-------------------------------------------------------------- 152 153No---Native Client does not provide direct access to the OS or devices, 154or otherwise bypass the JavaScript security model. For more information, 155see later sections of this FAQ. 156 157 158Development Environments and Tools 159================================== 160 161What development environment and development operating system do you recommend? 162------------------------------------------------------------------------------- 163 164You can develop on Windows, Mac, or Linux, and the resulting Native Client or 165Portable Native Client application will run inside the Google Chrome browser on 166all those platforms as well as ChromeOS. You can also develop on ChromeOS with 167Crouton_ or our `experimental development environment which runs within NaCl`_, 168and we're working on self-hosting a full development environment on Portable 169Native Client. 170 171Any editor+shell combination should work as well as IDEs like Eclipse, 172Visual Studio with the :doc:`Native Client Add-In 173<devguide/devcycle/vs-addin>` on Windows, or Xcode on Mac OSX. 174 175I'm not familiar with native development tools, can I still use the Native Client SDK? 176-------------------------------------------------------------------------------------- 177 178You may find our :doc:`Tutorial <devguide/tutorial/index>` and :doc:`Building 179instructions <devguide/devcycle/building>` useful, and you can look at 180the code and Makefiles for the SDK examples to understand how the 181examples are built and run. 182 183You'll need to learn how to use some tools (like GCC, LLVM, make, Eclipse, 184Visual Studio, or Xcode) before you can get very far with the SDK. Try seaching 185for an `introduction to GCC`_. 186 187 188Openness, and Supported Architectures and Languages 189=================================================== 190 191Is Native Client open? Is it a standard? 192---------------------------------------- 193 194Native Client is completely open: the executable format is open and the 195`source code is open <https://code.google.com/p/nativeclient/>`_. Right 196now the Native Client project is in its early stages, so it's premature 197to consider Native Client for standardization. 198 199We consistenly try to document our design and implementation and hope to 200standardize Portable Native Client when it gains more traction. A good 201example is our :doc:`PNaCl bitcode reference manual 202<reference/pnacl-bitcode-abi>`. 203 204What are the supported instruction set architectures? 205----------------------------------------------------- 206 207Portable Native Client uses an architecture-independent format (the 208``.pexe``) which can currently be translated to execute on processors 209with the x86-32, x86-64, and ARM instruction set architectures, as well 210as experimental support for MIPS. As new architectures come along and 211become popular we expect Portable Native Client to support them without 212developers having to recompile their code. 213 214Native Client can currently execute on the same architectures as 215Portable Native Client but is only supported on the Chrome Web 216Store. Native Client's ``.nexe`` files are architecture-dependent and 217cannot adapt to new architectures without recompilation, we therefore 218deem them better suited to a web store than to the open web. 219 220With Portable Native Client we deliver a system that has comparable 221portability to JavaScript and can adapt to new instruction set 222architectures without requiring recompilation. The web is better when 223it's platform-independent, and we'd like it to stay that way. 224 225.. _other_languages: 226 227Do I have to use C or C++? I'd really like to use another language. 228------------------------------------------------------------------- 229 230Right now only C and C++ are supported directly by the toolchain in the SDK. C# 231and other languages in the .NET family are supported via the `Mono port`_ for 232Native Client. Moreover, there are several ongoing projects to support 233additional language runtimes (e.g. `naclports supports Lua, Python and Ruby`_) 234as well as to compile more languages to LLVM's intermediate representation 235(e.g. support Halide_, Haskell with GHC_ or support Fortran with flang_), or 236transpile languages to C/C++ (source-to-source compilation). 237 238If you're interested in getting other languages working, please contact the 239Native Client team by way of the native-client-discuss_ mailing list. 240 241Do you only support Chrome? What about other browsers? 242------------------------------------------------------ 243 244We aim to support multiple browsers. However, a number of features that 245we consider requirements for a production-quality system that keeps the 246user safe are difficult to implement without help from the 247browser. Specific examples are an out-of-process plugin architecture and 248appropriate interfaces for integrated 3D graphics. We have worked 249closely with Chromium developers to deliver these features and we are 250eager to collaborate with developers from other browsers. 251 252What's the difference between NPAPI and Pepper? 253----------------------------------------------- 254 255:doc:`Pepper <pepper_stable/index>` (also known as PPAPI) is a new API that 256lets Native Client modules communicate with the browser. Pepper supports 257various features that don't have robust support in NPAPI, such as event 258handling, out-of-process plugins, and asynchronous interfaces. Native 259Client has transitioned from using NPAPI to using Pepper. 260 261Is NPAPI part of the Native Client SDK? 262--------------------------------------- 263 264NPAPI is not supported by the Native Client SDK, and is `deprecated in Chrome`_. 265 266Does Native Client support SIMD vector instructions? 267---------------------------------------------------- 268 269Native Client currently supports SSE on x86 and NEON on ARM. Support for 270AVX on x86 is under way. 271 272Portable Native Client supports portable SIMD vectors, as detailed in 273:ref:`Portable SIMD Vectors <portable_simd_vectors>`. 274 275Can I use Native Client for 3D graphics? 276---------------------------------------- 277 278Yes. Native Client supports `OpenGL ES 2.0`_. 279 280To alert the user regarding their hardware platform's 3D feature set 281before loading a large NaCl application, see :doc:`Vetting the driver in 282Javascript <devguide/coding/3D-graphics>`. 283 284Some GL extensions are exposed to Native Client applications, see the `GLES2 285file`_. This file is part of the GL wrapper supplied by the library 286``ppapi_gles2`` which you'll want to include in your project. In most cases 287extensions map to extensions available on other platforms, or differ very 288slightly (if they differ, the extension is usually CHROMIUM or ANGLE instead of 289EXT). 290 291.. TODO Improve documentation for GL extensions. 292 293Does Native Client support concurrency/parallelism? 294--------------------------------------------------- 295 296Native Client and Portable Native Client both support pthreads, 297C11/C++11 threads, and low-level synchronization primitives (mutex, 298barriers, atomic read/modify/write, compare-and-exchange, etc...), thus 299allowing your Native Client application to utilize several CPU cores. 300Note that this allows you to modify datastructures concurrently without 301needing to copy them, which is often a limitation of shared-nothing 302systems. For more information see :ref:`memory model and atomics 303<memory_model_and_atomics>` and :ref:`threading 304<language_support_threading>`. 305 306Native Client doesn't support HTML5 Web Workers directly but can 307interact with JavaScript code which does. 308 309 310Coming Soon 311=========== 312 313Do Native Client modules have access to external devices? 314--------------------------------------------------------- 315 316At this time Native Client modules do not have access to serial ports, 317camera devices, or microphones: Native Client can only use native 318resources that today's browsers can access. However, we intend to 319recommend such features to the standards bodies and piggyback on their 320efforts to make these resources available inside the browser. 321 322You can generally think of Pepper as the C/C++ bindings to the 323capabilities of HTML5. The goal is for Pepper and JavaScript to evolve 324together and stay on par with each other with respect to features and 325capabilities. 326 327 328Security and Privacy 329==================== 330 331What happens to my data when I use Native Client? 332------------------------------------------------- 333 334Users can opt-in to sending usage statistics and crash information in 335Chrome, which includes usage statistics and crash information about 336Native Client. Crashes in your code won't otherwise send your 337information to Google: Google counts the number of such crashes, but 338does so anonymously without sending your application's data or its debug 339information. 340 341For additional information about privacy and Chrome, see the `Google Chrome 342privacy policy`_ and the `Google Chrome Terms of Service`_. 343 344How does Native Client prevent sandboxed code from doing Bad Things? 345-------------------------------------------------------------------- 346 347Native Client's sandbox works by validating the untrusted code (the 348compiled Native Client module) before running it. The validator checks 349the following: 350 351* **Data integrity:** No loads or stores are permitted outside of the 352 data sandbox. In particular this means that once loaded into memory, 353 the binary is not writable. This is enforced by operating system 354 protection mechanisms. While new instructions can be inserted at 355 runtime to support things like JIT compilers, such instructions will 356 be subject to runtime verification according to the following 357 constraints before they are executed. 358* **No unsafe instructions:** The validator ensures that the Native 359 Client application does not contain any unsafe instructions. Examples 360 of unsafe instructions are ``syscall``, ``int``, and ``lds``. 361* **Control flow integrity:** The validator ensures that all direct and 362 indirect branches target a safe instruction. 363 364The beauty of the Native Client sandbox is in reducing "safe" code to a 365few simple rules that can be verified by a small trusted validator: the 366compiler isn't trusted. The same applies to Portable Native Client where 367even the ``.pexe`` to ``.nexe`` translator, a simplified compiler 368backend, isn't trusted: it is validated before executing, and so is its 369output. 370 371In addition to static analysis of untrusted code, the Native Client runtime also 372includes an outer sandbox that mediates system calls. For more details about 373both sandboxes, see `Native Client: A Sandbox for Portable, Untrusted x86 Code`_ 374(PDF). 375 376How does Google know that the safety measures in Native Client are sufficient? 377------------------------------------------------------------------------------ 378 379Google has taken several steps to ensure that Native Client's security works, 380including: 381 382* Open source, peer-reviewed papers describing the design. 383* A :doc:`security contest <community/security-contest/index>`. 384* Multiple internal and external security reviews. 385* The ongoing vigilance of our engineering and developer community. 386 387Google is committed to making Native Client safer than JavaScript and other 388popular browser technologies. If you have suggestions for security improvements, 389let the team know, by way of the native-client-discuss_ mailing list. 390 391Development 392=========== 393 394How do I debug? 395--------------- 396 397Instructions on :ref:`debugging the SDK examples 398<debugging_the_sdk_examples>` using GDB are available. You can also 399debug Native Client modules with some :doc:`alternative approaches 400<devguide/devcycle/debugging>`. 401 402How do I build x86-32, x86-64 or ARM ``.nexes``? 403------------------------------------------------ 404 405By default, the applications in the ``/examples`` folder create 406architecture-independent ``.pexe`` for Portable Native Client. To 407generate a ``.nexe`` targetting one specific architecture using the 408Native Client or Portable Native Client toolchains, see the 409:doc:`Building instructions <devguide/devcycle/building>`. 410 411How can my web application determine which ``.nexe`` to load? 412------------------------------------------------------------- 413 414Your application does not need to make the decision of loading an 415x86-32, x86-64 or ARM ``.nexe`` explicitly---the Native Client runtime 416examines a manifest file (``.nmf``) to pick the right ``.nexe`` file for 417a given user. You can generate a manifest file using a Python script 418that's included in the SDK (see the ``Makefile`` in any of the SDK 419examples for an illustration of how to do so). Your HTML file specifies 420the manifest filename in the ``src`` attribute of the ``<embed>`` 421tag. You can see the way the pieces fit together by examining the 422examples included in the SDK. 423 424Is it possible to build a Native Client module with just plain C (not C++)? 425--------------------------------------------------------------------------- 426 427Yes. See the ``"Hello, World!"`` in C example in the SDK under 428``examples/tutorial/using_ppapi_simple/``, or the Game of Life example 429under ``examples/demo/life/life.c``. 430 431What UNIX system calls can I make through Native Client? 432-------------------------------------------------------- 433 434Native Client doesn't directly expose any system calls from the host OS 435because of the inherent security risks and because the resulting 436application would not be portable across operating systems. Instead, 437Native Client provides portable cross-OS abstractions wrapping or 438proxying OS functionality or emulating UNIX system calls. For example, 439Native Client provides an ``mmap()`` system call that behaves much like 440the standard UNIX ``mmap()`` system call. 441 442Is my favorite third-party library available for Native Client? 443--------------------------------------------------------------- 444 445Google has ported several third-party libraries to Native Client; such libraries 446are available in the naclports_ project. We encourage you to contribute 447libraries to naclports, and/or to host your own ported libraries, and to let the 448team know about it on native-client-discuss_ when you do. 449 450Do all the files in an application need to be served from the same domain? 451-------------------------------------------------------------------------- 452 453The ``.nmf``, and ``.nexe`` or ``.pexe`` files must either be served from the 454same origin as the embedding page or an origin that has been configured 455correctly using CORS_. 456 457For applications installed from the Chrome Web Store the Web Store manifest 458must include the correct, verified domain of the embedding page. 459 460Portability 461=========== 462 463Do I have to do anything special to make my application run on different operating systems? 464------------------------------------------------------------------------------------------- 465 466No. Native Client and Portable Native Client applications run without 467modification on all supported operating systems. 468 469However, to run on different instruction set architectures (such as 470x86-32, x86-64 or ARM), you currently have to either: 471 472* Use Portable Native Client. 473* Build and supply a separate ``.nexe`` file for each architecture, and 474 make them available on the Chrome Web Store. See :doc:`target 475 architectures <devguide/devcycle/building>` for details about which 476 ``.nexe`` files will run on which architectures. 477 478How easy is it to port my existing native code to Native Client? 479---------------------------------------------------------------- 480 481In most cases you won't have to rewrite much, if any, code. The Native 482Client-specific tools, such as ``pnacl-clang++`` or ``x86_64-nacl-g++``, 483take care of most of the necessary changes. You may need to make some 484changes to your operating system calls and interactions with external 485devices to work with the web. Porting existing Linux libraries is 486generally straightforward, with large libraries often requiring no 487source change. 488 489The following kinds of code may be more challenging to port: 490 491* Code that does direct TCP/IP or UDP networking. For security reasons 492 these APIs are only available to packaged applications, not on the 493 open web, after asking for the appropriate permissions. Native Client 494 is otherwise restricted to the networking APIs available in the 495 browser. 496* Code that creates processes, including UNIX forks. Creating processes 497 is not supported for security reasons. However, threads are supported. 498* Code that needs to do local file I/O. Native Client is restricted to 499 accessing URLs and to local storage in the browser (the Pepper file I/O API 500 has access to the same per-application storage that JavaScript has via Local 501 Storage). HTML5 File System can be used, among others. For POSIX compatabiliy 502 the Native Client SDK includes a library called nacl_io which allows the 503 application to interact with all these types of files via standard POSIX I/O 504 functions (e.g. open/fopen/read/write/...). See :doc:`Using NaCl I/O 505 <devguide/coding/nacl_io>` for more details. 506 507.. _faq_troubleshooting: 508 509Troubleshooting 510=============== 511 512My ``.pexe`` isn't loading, help! 513--------------------------------- 514 515* You must use Google Chrome version 31 or greater for Portable Native 516 Client. Make sure you have Portable Native Client installed in 517 ``about:nacl``; if not open ``about:components`` and "Check for 518 update" for PNaCl. 519* PNaCl ``.pexe`` must be compiled with pepper_31 SDK or higher (earlier 520 SDK versions had experimental support for PNaCl, now deprecated). 521* Your application can verify that Portable Native Client is supported 522 in JavaScript with ``navigator.mimeTypes['application/x-pnacl'] !== 523 undefined``. This is preferred over checking the Chrome version. 524 525My ``.nexe`` files never finish loading. What gives? 526---------------------------------------------------- 527 528Here are ways to resolve some common problems that can prevent loading: 529 530* You must use Google Chrome version 14 or greater for Native Client. 531* If you haven't already done so, enable the Native Client flag in 532 Google Chrome. Type ``about:flags`` in the Chrome address bar, scroll 533 down to "Native Client", click the "Enable" link, scroll down to the 534 bottom of the page, and click the "Relaunch Now" button (all browser 535 windows will restart). 536* Verify that the Native Client plugin is enabled in Google Chrome. Type 537 ``about:plugins`` in the Chrome address bar, scroll down to "Native 538 Client", and click the "Enable" link. (You do not need to relaunch 539 Chrome after you enable the Native Client plugin). 540* Make sure that the ``.nexe`` files are being served from a web 541 server. Native Client uses the same-origin security policy, which 542 means that modules will not load in pages opened with the ``file://`` 543 protocol. In particular, you can't run the examples in the SDK by 544 simply dragging the HTML files from the desktop into the browser. See 545 :doc:`Running Native Client Applications <devguide/devcycle/running>` 546 for instructions on how to run the httpd.py mini-server included in 547 the SDK. 548* The ``.nexe`` files must have been compiled using SDK version 0.5 or 549 greater. 550* You must load the correct ``.nexe`` file for your machine's specific 551 instruction set architecture (x86-32, x86-64 or ARM). You can ensure 552 you're loading the correct ``.nexe`` file by building a separate 553 ``.nexe`` for each architecture, and using a ``.nmf`` manifest file to 554 let the browser select the correct ``.nexe`` file. Note: the need to 555 select a processor-specific ``.nexe`` goes away with Portable Native 556 Client. 557* If things still aren't working, :doc:`ask for help <help>`! 558 559 560.. _`PNaCl SIMD: Speed on the Web`: https://www.youtube.com/watch?v=675znN6tntw&list=PLOU2XLYxmsIIwGK7v7jg3gQvIAWJzdat_ 561.. _Adapting Software Fault Isolation to Contemporary CPU Architectures: https://nativeclient.googlecode.com/svn/data/site/NaCl_SFI.pdf 562.. _`Native Client: A Sandbox for Portable, Untrusted x86 Code`: http://research.google.com/pubs/pub34913.html 563.. _Crouton: https://github.com/dnschneid/crouton 564.. _experimental development environment which runs within NaCl: https://www.youtube.com/watch?v=OzNuzBDEWzk&list=PLOU2XLYxmsIIwGK7v7jg3gQvIAWJzdat_ 565.. _introduction to GCC: https://www.google.com/search?q=gcc+introduction 566.. _Mono port: https://github.com/elijahtaylor/mono 567.. _naclports supports Lua, Python and Ruby: https://code.google.com/p/naclports/source/browse#svn%2Ftrunk%2Fsrc%2Fexamples%2Ftools 568.. _Halide: http://halide-lang.org/ 569.. _GHC: http://www.haskell.org/ghc/docs/latest/html/users_guide/code-generators.html 570.. _flang: https://flang-gsoc.blogspot.ie/2013/09/end-of-gsoc-report.html 571.. _native-client-discuss: https://groups.google.com/group/native-client-discuss 572.. _deprecated in Chrome: http://blog.chromium.org/2013/09/saying-goodbye-to-our-old-friend-npapi.html 573.. _OpenGL ES 2.0: https://www.khronos.org/opengles/ 574.. _GLES2 file: https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/lib/gl/gles2/gles2.c 575.. _Google Chrome privacy policy: https://www.google.com/chrome/intl/en/privacy.html 576.. _Google Chrome Terms of Service: https://www.google.com/chrome/intl/en/eula_text.html 577.. _naclports: https://code.google.com/p/naclports 578.. _CORS: http://en.wikipedia.org/wiki/Cross-origin_resource_sharing 579