The Chromium Projects

Search this site

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.
Native Client‎ > ‎PNaCl‎ > ‎

Introduction to Portable Native Client

Introduction

Portable Native Client (PNaCl) is a toolchain for compiling Native Client applications to a subset of LLVM bitcode.
These bitcode files (known as "portable executables", or "pexe" files) represent an Native Client application
in a high-level format, which can be translated to native code for execution on any processor supported
by NaCl.

The PNaCl toolchain is currently available for Windows, Mac, and Linux.

PNaCl currently supports code generation on 3 architectures:
  • X86-32
  • X86-64
  • ARM

How does PNaCl work?

PNaCl is a cross-compiling toolchain, where the target architecture is bitcode. PNaCl recognizes three types of bitcode files:

.bc     - Bitcode object file. (Analogous to an ELF object file)
.a      - Archive of bitcode objects. (Analogous to a static library archive)
.pexe   - Bitcode executable. (Analogous to an executable file)

PNaCl provides the standard tools:
  pnacl-clang
  pnacl-clang++
  pnacl-ld
  pnacl-ar
  pnacl-nm
  pnacl-ranlib
  pnacl-strip
  pnacl-as

While chrome can load and translate a pexe directly, there is an additional tool pnacl-translate.
for generating native code from bitcode.


Installing the PNaCl Toolchain and Building Examples

PNaCl is now available in the naclsdk updater (https://developers.google.com/native-client/sdk/download).  It is available in pepper_24 and higher.

  1. Download the naclsdk updater, and run "naclsdk.bat update pepper_XX" (e.g., pepper_canary).
  2. Once downloaded, you can set your NACL_SDK_ROOT directory to pepper_XX.
  3. See pepper_canary/examples/ for various examples.  The makefiles in each example directory should be configured to build pnacl pexes and generate manifest files for those pexes.  Just set the "TOOLCHAIN" environment variable to be "pnacl".  E.g.,

     "(cd pepper_canary/examples/hello_world; TOOLCHAIN=pnacl CONFIG=Release make)".

  4. With the PNaCl sdk, you can also try compiling some of the naclports examples.  Once you have set the NACL_SDK_ROOT environment variable to point at the pepper directory with pnacl installed, you can run "make" to build a naclports target by setting the environment variable  NACL_ARCH to "pnacl". E.g., to build dosbox, run

    "NACL_ARCH=pnacl make dosbox".

    That will build the required libraries (e.g., SDL), and build dosbox as a pexe.  The resulting pexe can be found at "out/repository-pnacl/dosbox-0.74/dosbox-0.74-build/src/dosbox".


How to Run Examples in Chrome 29+
  1. Go to chrome://flags and enable the Portable Native Client flag.
  2. Restart the browser.
  3. After 10 seconds the Portable Native Client files should start downloading and installing in the background.  Check chrome://nacl after about 1 minute to see if it is installed.
  4. Once installed, visit a webpage with a PNaCl NMF file that points at your pexe application (the SDK has a create_nmf.py tool that will help you create one).  For example, try loading the samples here: https://chrome.google.com/webstore/detail/pnacl-examples/mblemkccghnfkjignlmgngmopopifacf.

Debugging
    PNaCl pexes can be loaded and translated directly in chrome.  However, for debugging,
    we recommend translating ahead of time with pnacl-translate to obtain a NaCl nexe.
    The NaCl nexe can be debugged with the NaCl gdb debugger or other techniques.

    We recommend debugging the nexe level, instead of the pexe because bitcode 
    debug metadata is not part of PNaCl's stable bitcode ABI and must be left out of
    published pexes.  To remove debug metadata, run pnacl-finalize on the pexe.

      How to report bugs / feedback for PNaCl

      1. Go to http://code.google.com/p/nativeclient/issues/list and file a New Issue.
      2. Describe the issue.
      3. Tag the issue as Component-PNaCl, and Arch-All (or a specific Arch if turns out that it is arch-specific)


      PNaCl Developers

      The section on developing PNaCl itself has moved to https://sites.google.com/a/chromium.org/dev/nativeclient/pnacl/developing-pnacl
      Comments