| .. _faq: |
| |
| ########################## |
| Frequently Asked Questions |
| ########################## |
| |
| .. contents:: |
| :local: |
| :backlinks: none |
| :depth: 2 |
| |
| This document answers some frequently asked questions about Native |
| Client (NaCl) and Portable Native Client (PNaCl, pronounced |
| "pinnacle"). For a high-level overview of Native Client, see the |
| :doc:`Technical Overview <overview>`. |
| |
| If you have questions that aren't covered in this FAQ: |
| |
| * Scan through the :doc:`Release Notes <sdk/release-notes>`. |
| * Search through or ask on the :doc:`Native Client Forums <help>`. |
| |
| |
| What is Native Client Good For? |
| =============================== |
| |
| Why did Google build Native Client? |
| ----------------------------------- |
| |
| * **Performance:** Native Client modules run nearly as fast as native |
| compiled code. |
| * **Security:** Native Client lets users run native compiled code in the |
| browser with the same level of security and privacy as traditional web |
| applications. |
| * **Convenience:** |
| |
| * Developers can leverage existing code, written in C/C++ or other |
| languages, in their applications without forcing users to install a |
| plugin. |
| * This code can interact with the embedding web page as part of an |
| HTML and JavaScript web application, or it can be a self-contained |
| and immersive experience. |
| |
| * **Portability:** Native Client and Portable Native Client applications |
| can execute on: |
| |
| * The Windows, Mac, Linux or ChromeOS operating systems. |
| * Processors with the x86-32, x86-64, or ARM instruction set |
| architectures. Native Client also has experimental support for MIPS. |
| |
| Portable Native client further enhances the above: |
| |
| * **Performance:** Each PNaCl release brings with it more performance |
| enhancements. Already-released applications get faster over time, |
| conserving user's battery. |
| * **Security:** Users are kept secure with an ever-improving sandbox |
| model which adapts to novel attacks, without affecting |
| already-released applications. |
| * **Convenience:** Developers only need to ship a single ``.pexe`` file, |
| not one ``.nexe`` file per supported architecture. |
| * **Portability:** Developers and users don't need to worry about |
| already-released applications not working on new hardware: PNaCl |
| already supports all architectures NaCl does, and as PNaCl evolves it |
| gains support for new processors and fully uses their capabilities. |
| |
| .. TODO Expand on the PNaCl performance section in another document, and |
| .. link to it here. |
| |
| For more details, refer to the :doc:`history behind and comparison of |
| NaCl and PNaCl <nacl-and-pnacl>`. |
| |
| When should I use Native Client? |
| -------------------------------- |
| |
| The following are some typical use cases. For details, see the |
| :doc:`Technical Overview <overview>`. |
| |
| * Porting existing software components for use in a web application. |
| * Porting legacy desktop applications. |
| * Handling browser-side encryption and decryption for an enterprise |
| application. |
| * Handling multimedia for a web application. |
| * Handling various aspects of web-based games, including physics engines |
| and AI. |
| |
| Native Client is a versatile technology; we expect that it will also be |
| used in many other contexts outside of Chrome. |
| |
| When should I use Portable Native Client? |
| ----------------------------------------- |
| |
| See :doc:`NaCl and PNaCl <nacl-and-pnacl>`. In short: PNaCl works on the |
| open web whereas NaCl only works on the Chrome Web Store. |
| |
| How fast does code run in Native Client? |
| ---------------------------------------- |
| |
| Fast! Benchmarks on x86-32 measured an average performance overhead of |
| less than 5% compared to native C/C++ on applications such as Quake, |
| bzip2, and Google Earth. For details of those benchmarks, see `Native |
| Client: A Sandbox for Portable, Untrusted x86 Code |
| <https://src.chromium.org/viewvc/native_client/data/docs_tarball/nacl/googleclient/native_client/documentation/nacl_paper.pdf>`_ |
| (PDF). |
| |
| Benchmarks on x86-64 and ARM measured an average performance overhead of |
| less than 5% on ARM and 7% on x86-64; however, benchmark performance was |
| bimodal for x86-64, so different use cases are likely to achieve either |
| significantly better or significantly worse performance than that |
| average. For details, see `Adapting Software Fault Isolation to |
| Contemporary CPU Architectures |
| <https://nativeclient.googlecode.com/svn/data/site/NaCl_SFI.pdf>`_ (PDF). |
| |
| .. TODO Update performance numbers. |
| |
| If your code isn't performing as close to native speed as you'd expect, |
| :doc:`let us know <help>`! |
| |
| Why use Portable Native Client instead of *<technology X>*? |
| ----------------------------------------------------------- |
| |
| Many other technologies can be compared to Portable Native Client: |
| Flash, Java, Silverlight, ActiveX, .NET, asm.js, etc... |
| |
| Different technologies have different strengths and weaknesses. In |
| appropriate contexts, Portable Native Client can be faster, more secure, |
| and/or more compatible across operating systems and architectures than |
| other technologies. |
| |
| Portable Native Client complement other technologies by giving web |
| developers a new capability: the ability to run fast, secure native code |
| from a web browser in an architecture-independent way. |
| |
| If I want direct access to the OS, should I use Native Client? |
| -------------------------------------------------------------- |
| |
| No---Native Client does not provide direct access to the OS or devices, |
| or otherwise bypass the JavaScript security model. For more information, |
| see later sections of this FAQ. |
| |
| |
| Development Environments and Tools |
| ================================== |
| |
| What development environment and development operating system do you recommend? |
| ------------------------------------------------------------------------------- |
| |
| You can develop on Windows, Mac, or Linux, and the resulting Native |
| Client or Portable Native Client application will run inside the Google |
| Chrome browser on all those platforms as well as ChromeOS. You can also |
| develop on ChromeOS with `Crouton |
| <https://github.com/dnschneid/crouton>`_, and we're working on |
| self-hosting a full development environment on Portable Native Client. |
| |
| Any editor+shell combination should work as well as IDEs like Eclipse, |
| Visual Studio with the `Native Client Add-In |
| <https://developers.google.com/native-client/dev/devguide/devcycle/vs-addin>`_ |
| on Windows, or Xcode on Mac OSX. |
| |
| .. TODO: update link to Visual Studio when ReST-ified. |
| |
| I'm not familiar with native development tools, can I still use the Native Client SDK? |
| -------------------------------------------------------------------------------------- |
| |
| You may find our :doc:`Tutorial <devguide/tutorial/index>` and :doc:`Building |
| instructions <devguide/devcycle/building>` useful, and you can look at |
| the code and Makefiles for the SDK examples to understand how the |
| examples are built and run. |
| |
| You'll need to learn how to use some tools (like GCC, LLVM, make, |
| Eclipse, Visual Studio, or Xcode) before you can get very far with the |
| SDK. Try seaching for an `introduction to GCC |
| <https://www.google.com/search?q=gcc+introduction>`_. |
| |
| |
| Openness, and Supported Architectures and Languages |
| =================================================== |
| |
| Is Native Client open? Is it a standard? |
| ---------------------------------------- |
| |
| Native Client is completely open: the executable format is open and the |
| `source code is open <https://code.google.com/p/nativeclient/>`_. Right |
| now the Native Client project is in its early stages, so it's premature |
| to consider Native Client for standardization. |
| |
| We consistenly try to document our design and implementation and hope to |
| standardize Portable Native Client when it gains more traction. A good |
| example is our `PNaCl bitcode reference manual |
| <http://www.chromium.org/nativeclient/pnacl/bitcode-abi>`_. |
| |
| .. TODO Update the above bitcode-abi link to a :doc: once 3693 is fixed. |
| |
| What are the supported instruction set architectures? |
| ----------------------------------------------------- |
| |
| Portable Native Client uses an architecture-independent format (the |
| ``.pexe``) which can currently be translated to execute on processors |
| with the x86-32, x86-64, and ARM instruction set architectures, as well |
| as experimental support for MIPS. As new architectures come along and |
| become popular we expect Portable Native Client to support them without |
| developers having to recompile their code. |
| |
| Native Client can currently execute on the same architectures as |
| Portable Native Client but is only supported on the Chrome Web |
| Store. Native Client's ``.nexe`` files are architecture-dependent and |
| cannot adapt to new architectures without recompilation, we therefore |
| deem them better suited to a web store than to the open web. |
| |
| With Portable Native Client we deliver a system that has comparable |
| portability to JavaScript and can adapt to new instruction set |
| architectures without requiring recompilation. The web is better when |
| it's platform-independent, and we'd like it to stay that way. |
| |
| Do I have to use C or C++? I'd really like to use another language. |
| ------------------------------------------------------------------- |
| |
| Right now only C and C++ are supported directly by the toolchain in the |
| SDK. C# and other languages in the .NET family are supported via the |
| `Mono port <https://github.com/elijahtaylor/mono>`_ for Native |
| Client. Moreover, there are several ongoing projects to support |
| additional language runtimes (e.g. `naclports supports Lua, Python and |
| Ruby |
| <https://code.google.com/p/naclports/source/browse#svn%2Ftrunk%2Fsrc%2Fexamples%2Ftools>`_) |
| as well as to compile more languages to LLVM's intermediate |
| representation (e.g. support Haskell with `GHC |
| <http://www.haskell.org/ghc/docs/latest/html/users_guide/code-generators.html>`_ |
| or support Fortran with `flang |
| <https://flang-gsoc.blogspot.ie/2013/09/end-of-gsoc-report.html>`_), or |
| transpile languages to C/C++ (source-to-source compilation). |
| |
| If you're interested in getting other languages working, please contact |
| the Native Client team by way of the `native-client-discuss mailing list |
| <https://groups.google.com/group/native-client-discuss>`_. |
| |
| Will you only support Chrome? What about other browsers? |
| -------------------------------------------------------- |
| |
| We aim to support multiple browsers. However, a number of features that |
| we consider requirements for a production-quality system that keeps the |
| user safe are difficult to implement without help from the |
| browser. Specific examples are an out-of-process plugin architecture and |
| appropriate interfaces for integrated 3D graphics. We have worked |
| closely with Chromium developers to deliver these features and we are |
| eager to collaborate with developers from other browsers. |
| |
| What's the difference between NPAPI and Pepper? |
| ----------------------------------------------- |
| |
| :doc:`Pepper <peppercpp/index>` (also known as PPAPI) is a new API that |
| lets Native Client modules communicate with the browser. Pepper supports |
| various features that don't have robust support in NPAPI, such as event |
| handling, out-of-process plugins, and asynchronous interfaces. Native |
| Client has transitioned from using NPAPI to using Pepper. |
| |
| Is NPAPI part of the Native Client SDK? |
| --------------------------------------- |
| |
| NPAPI is not supported by the Native Client SDK, and is `deprecated in |
| Chrome |
| <http://blog.chromium.org/2013/09/saying-goodbye-to-our-old-friend-npapi.html>`_. |
| |
| Does Native Client support SIMD vector instructions? |
| ---------------------------------------------------- |
| |
| Native Client currently supports SSE on x86 and NEON on ARM. Support for |
| AVX on x86 is under way. |
| |
| Portable Native Client should support SIMD vectors in the near future. |
| |
| Can I use Native Client for 3D graphics? |
| ---------------------------------------- |
| |
| Yes. Native Client supports `OpenGL ES 2.0 |
| <https://www.khronos.org/opengles/>`_. |
| |
| |
| To alert the user regarding their hardware platform's 3D feature set |
| before loading a large NaCl application, see `Vetting the driver in |
| Javascript |
| <https://developers.google.com/native-client/devguide/coding/3D-graphics>`_. |
| |
| .. TODO Update link to point to the right place in the document once |
| .. it's ReST-ified. |
| |
| Some GL extensions are exposed to Native Client applications, see the |
| `GL ES 2 file |
| <https://src.chromium.org/viewvc/chrome/trunk/src/ppapi/lib/gl/gles2/gles2.c>`_. |
| This file is part of the GL wrapper supplied by the library |
| ``ppapi_gles2`` which you'll want to include in your project. In most |
| cases extensions map to extensions available on other platforms, or |
| differ very slightly (if they differ, the extension is usually CHROMIUM |
| or ANGLE instead of EXT). |
| |
| .. TODO Improve documentation for GL extensions. |
| |
| Does Native Client support concurrency/parallelism? |
| --------------------------------------------------- |
| |
| Native Client and Portable Native Client both support pthreads, |
| C11/C++11 threads, and low-level synchronization primitives (mutex, |
| barriers, atomic read/modify/write, compare-and-exchange, etc...), thus |
| allowing your Native Client application to utilize several CPU cores. |
| Note that this allows you to modify datastructures concurrently without |
| needing to copy them, which is often a limitation of shared-nothing |
| systems. |
| |
| Native Client doesn't support HTML5 Web Workers directly but can |
| interact with JavaScript code which does. |
| |
| .. TODO Add link to relevant documentation, once written. |
| |
| |
| Coming Soon |
| =========== |
| |
| Do Native Client modules have access to external devices? |
| --------------------------------------------------------- |
| |
| At this time Native Client modules do not have access to serial ports, |
| camera devices, or microphones: Native Client can only use native |
| resources that today's browsers can access. However, we intend to |
| recommend such features to the standards bodies and piggyback on their |
| efforts to make these resources available inside the browser. |
| |
| You can generally think of Pepper as the C/C++ bindings to the |
| capabilities of HTML5. The goal is for Pepper and JavaScript to evolve |
| together and stay on par with each other with respect to features and |
| capabilities. |
| |
| |
| Security and Privacy |
| ==================== |
| |
| What happens to my data when I use Native Client? |
| ------------------------------------------------- |
| |
| Users can opt-in to sending usage statistics and crash information in |
| Chrome, which includes usage statistics and crash information about |
| Native Client. Crashes in your code won't otherwise send your |
| information to Google: Google counts the number of such crashes, but |
| does so anonymously without sending your application's data or its debug |
| information. |
| |
| For additional information about privacy and Chrome, see the `Google |
| Chrome privacy policy |
| <https://www.google.com/chrome/intl/en/privacy.html>`_ and the `Google |
| Chrome Terms of Service |
| <https://www.google.com/chrome/intl/en/eula_text.html>`_. |
| |
| How does Native Client prevent sandboxed code from doing Bad Things? |
| -------------------------------------------------------------------- |
| |
| Native Client's sandbox works by validating the untrusted code (the |
| compiled Native Client module) before running it. The validator checks |
| the following: |
| |
| * **Data integrity:** No loads or stores are permitted outside of the |
| data sandbox. In particular this means that once loaded into memory, |
| the binary is not writable. This is enforced by operating system |
| protection mechanisms. While new instructions can be inserted at |
| runtime to support things like JIT compilers, such instructions will |
| be subject to runtime verification according to the following |
| constraints before they are executed. |
| * **No unsafe instructions:** The validator ensures that the Native |
| Client application does not contain any unsafe instructions. Examples |
| of unsafe instructions are ``syscall``, ``int``, and ``lds``. |
| * **Control flow integrity:** The validator ensures that all direct and |
| indirect branches target a safe instruction. |
| |
| The beauty of the Native Client sandbox is in reducing "safe" code to a |
| few simple rules that can be verified by a small trusted validator: the |
| compiler isn't trusted. The same applies to Portable Native Client where |
| even the ``.pexe`` to ``.nexe`` translator, a simplified compiler |
| backend, isn't trusted: it is validated before executing, and so is its |
| output. |
| |
| In addition to static analysis of untrusted code, the Native Client |
| runtime also includes an outer sandbox that mediates system calls. For |
| more details about both sandboxes, see `Native Client: A Sandbox for |
| Portable, Untrusted x86 Code |
| <https://src.chromium.org/viewvc/native_client/data/docs_tarball/nacl/googleclient/native_client/documentation/nacl_paper.pdf>`_ |
| (PDF). |
| |
| How does Google know that the safety measures in Native Client are sufficient? |
| ------------------------------------------------------------------------------ |
| |
| Google has taken several steps to ensure that Native Client's security |
| works, including: |
| |
| * Open source, peer-reviewed papers describing the design. |
| * A `security contest |
| <https://developers.google.com/native-client/community/security-contest/>`_. |
| * Multiple internal and external security reviews. |
| * The ongoing vigilance of our engineering and developer community. |
| |
| .. TODO: Fix security contest link once ReST-ified. |
| |
| Google is committed to making Native Client safer than JavaScript and |
| other popular browser technologies. If you have suggestions for security |
| improvements, let the team know, by way of the `native-client-discuss |
| mailing list <https://groups.google.com/group/native-client-discuss>`_. |
| |
| |
| Development |
| =========== |
| |
| How do I debug? |
| --------------- |
| |
| Instructions on :ref:`debugging the SDK examples |
| <debugging_the_sdk_examples>` using GDB are available. You can also |
| debug Native Client modules with some :doc:`alternative approaches |
| <devguide/devcycle/debugging>`. |
| |
| How do I build x86-32, x86-64 or ARM ``.nexes``? |
| ------------------------------------------------ |
| |
| By default, the applications in the ``/examples`` folder create |
| architecture-independent ``.pexe`` for Portable Native Client. To |
| generate a ``.nexe`` targetting one specific architecture using the |
| Native Client or Portable Native Client toolchains, see the |
| :doc:`Building instructions <devguide/devcycle/building>`. |
| |
| How can my web application determine which ``.nexe`` to load? |
| ------------------------------------------------------------- |
| |
| Your application does not need to make the decision of loading an |
| x86-32, x86-64 or ARM ``.nexe`` explicitly---the Native Client runtime |
| examines a manifest file (``.nmf``) to pick the right ``.nexe`` file for |
| a given user. You can generate a manifest file using a Python script |
| that's included in the SDK (see the ``Makefile`` in any of the SDK |
| examples for an illustration of how to do so). Your HTML file specifies |
| the manifest filename in the ``src`` attribute of the ``<embed>`` |
| tag. You can see the way the pieces fit together by examining the |
| examples included in the SDK. |
| |
| Is it possible to build a Native Client module with just plain C (not C++)? |
| --------------------------------------------------------------------------- |
| |
| Yes. See the ``"Hello, World!"`` in C example in the SDK under |
| ``examples/tutorial/using_ppapi_simple/``, or the Game of Life example |
| under ``examples/demo/life/life.c``. |
| |
| What UNIX system calls can I make through Native Client? |
| -------------------------------------------------------- |
| |
| Native Client doesn't directly expose any system calls from the host OS |
| because of the inherent security risks and because the resulting |
| application would not be portable across operating systems. Instead, |
| Native Client provides portable cross-OS abstractions wrapping or |
| proxying OS functionality or emulating UNIX system calls. For example, |
| Native Client provides an ``mmap()`` system call that behaves much like |
| the standard UNIX ``mmap()`` system call. |
| |
| Is my favorite third-party library available for Native Client? |
| --------------------------------------------------------------- |
| |
| Google has ported several third-party libraries to Native Client; such |
| libraries are available in the `naclports |
| <https://code.google.com/p/naclports>`_ project. We encourage you to |
| contribute libraries to naclports, and/or to host your own ported |
| libraries, and to `let the team know about it |
| <https://groups.google.com/group/native-client-discuss>`_ when you do. |
| |
| Do all the files in an application need to be served from the same domain? |
| -------------------------------------------------------------------------- |
| |
| The ``.html``, ``.nmf``, and ``.nexe`` or ``.pexe`` files must be served |
| from the same domain and the Chrome Web Store manifest file (for |
| applications installed from the Chrome Web Store) must include the |
| correct, verified domain. Other files can be served from the same or |
| another domain. |
| |
| .. TODO This isn't the case anymore. +ncbray? |
| |
| |
| Portability |
| =========== |
| |
| Do I have to do anything special to make my application run on different operating systems? |
| ------------------------------------------------------------------------------------------- |
| |
| No. Native Client and Portable Native Client applications run without |
| modification on all supported operating systems. |
| |
| However, to run on different instruction set architectures (such as |
| x86-32, x86-64 or ARM), you currently have to either: |
| |
| * Use Portable Native Client. |
| * Build and supply a separate ``.nexe`` file for each architecture, and |
| make them available on the Chrome Web Store. See :doc:`target |
| architectures <devguide/devcycle/building>` for details about which |
| ``.nexe`` files will run on which architectures. |
| |
| How easy is it to port my existing native code to Native Client? |
| ---------------------------------------------------------------- |
| |
| In most cases you won't have to rewrite much, if any, code. The Native |
| Client-specific tools, such as ``pnacl-clang++`` or ``x86_64-nacl-g++``, |
| take care of most of the necessary changes. You may need to make some |
| changes to your operating system calls and interactions with external |
| devices to work with the web. Porting existing Linux libraries is |
| generally straightforward, with large libraries often requiring no |
| source change. |
| |
| The following kinds of code may be more challenging to port: |
| |
| * Code that does direct TCP/IP or UDP networking. For security reasons |
| these APIs are only available to packaged applications, not on the |
| open web, after asking for the appropriate permissions. Native Client |
| is otherwise restricted to the networking APIs available in the |
| browser. |
| * Code that creates processes, including UNIX forks. Creating processes |
| is not supported for security reasons. However, threads are supported. |
| * Code that needs to do local file I/O. Native Client is restricted to |
| accessing URLs and to local storage in the browser (the Pepper file |
| I/O API has access to the same per-application storage that JavaScript |
| has via Local Storage). HTML5 File System can be used, among |
| others. You can also use nacl_io. |
| |
| .. TODO More on nacl_io, and a link. |
| |
| |
| .. _faq_troubleshooting: |
| |
| Troubleshooting |
| =============== |
| |
| My ``.pexe`` isn't loading, help! |
| --------------------------------- |
| |
| * You must use Google Chrome version 31 or greater for Portable Native |
| Client. Make sure you have Portable Native Client installed in |
| ``about:nacl``; if not open ``about:components`` and "Check for |
| update" for PNaCl. |
| * PNaCl ``.pexe`` must be compiled with pepper_31 SDK or higher (earlier |
| SDK versions had experimental support for PNaCl, now deprecated). |
| * Your application can verify that Portable Native Client is supported |
| in JavaScript with ``navigator.mimeTypes['application/x-pnacl'] !== |
| undefined``. This is preferred over checking the Chrome version. |
| |
| My ``.nexe`` files never finish loading. What gives? |
| ---------------------------------------------------- |
| |
| Here are ways to resolve some common problems that can prevent loading: |
| |
| * You must use Google Chrome version 14 or greater for Native Client. |
| * If you haven't already done so, enable the Native Client flag in |
| Google Chrome. Type ``about:flags`` in the Chrome address bar, scroll |
| down to "Native Client", click the "Enable" link, scroll down to the |
| bottom of the page, and click the "Relaunch Now" button (all browser |
| windows will restart). |
| * Verify that the Native Client plugin is enabled in Google Chrome. Type |
| ``about:plugins`` in the Chrome address bar, scroll down to "Native |
| Client", and click the "Enable" link. (You do not need to relaunch |
| Chrome after you enable the Native Client plugin). |
| * Make sure that the ``.nexe`` files are being served from a web |
| server. Native Client uses the same-origin security policy, which |
| means that modules will not load in pages opened with the ``file://`` |
| protocol. In particular, you can't run the examples in the SDK by |
| simply dragging the HTML files from the desktop into the browser. See |
| :doc:`Running Native Client Applications <devguide/devcycle/running>` |
| for instructions on how to run the httpd.py mini-server included in |
| the SDK. |
| * The ``.nexe`` files must have been compiled using SDK version 0.5 or |
| greater. |
| * You must load the correct ``.nexe`` file for your machine's specific |
| instruction set architecture (x86-32, x86-64 or ARM). You can ensure |
| you're loading the correct ``.nexe`` file by building a separate |
| ``.nexe`` for each architecture, and using a ``.nmf`` manifest file to |
| let the browser select the correct ``.nexe`` file. Note: the need to |
| select a processor-specific ``.nexe`` goes away with Portable Native |
| Client. |
| * If things still aren't working, :doc:`ask for help <help>`! |