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