Building

Target architectures

Portable Native Client (PNaCl) modules are written in C or C++ and compiled into an executable file ending in a .pexe extension using the PNaCl toolchain in the Native Client SDK. Chrome can load pexe files embedded in web pages and execute them as part of a web application.

As explained in the Technical Overview, PNaCl modules are operating-system-independent and processor-independent. The same pexe will run on Windows, Mac, Linux, and ChromeOS and it will run on any processor, e.g., x86-32, x86-64, and ARM.

Native Client also supports architecture-specific nexe files. These nexe files are also operating-system-independent, but they are not processor-independent. To support a wide variety of devices you must compile separate versions of your Native Client module for different processors on end-user machines. A manifest file will then specify which version of the module to load based on the end-user’s architecture. The SDK includes a script—create_nmf.py (in the tools/ directory)—to generate manifest files. For examples of how to compile modules for multiple target architectures and how to generate manifest files, see the Makefiles included with the SDK examples.

This section will mostly cover PNaCl, but also describes how to build nexe applications.

C libraries

The PNaCl SDK has a single choice of C library: newlib.

The Native Client SDK also has a GCC-based toolchain for building nexes. The GCC-based toolchain has support for two C libraries: newlib and glibc. See Dynamic Linking & Loading with glibc for information about these libraries, including factors to help you decide which to use.

C++ standard libraries

The PNaCl SDK can use either LLVM’s libc++ (the current default) or GCC’s libstdc++ (deprecated). The -stdlib=[libc++|libstdc++] command line argument can be used to choose which standard library to use.

The GCC-based Native Client SDK only has support for GCC’s libstdc++.

C++11 library support is only complete in libc++ but other non-library language features should work regardless of which standard library is used. The -std=[c++98|c++11] command line argument can be used to indicate which C++ language standard to use (or -std=gnu++11 to access non-standard extensions).

SDK toolchains

The Native Client SDK includes multiple toolchains. It has one PNaCl toolchain and it has multiple GCC-based toolchains that are differentiated by target architectures and C libraries. The single PNaCl toolchain is located in a directory named toolchain/<OS_platform>_pnacl, and the GCC-based toolchains are located in directories named toolchain/<OS_platform>_<architecture>_<library>, where:

• <platform> is the platform of your development machine (win, mac, or linux)
• <architecture> is your target architecture (x86 or arm)
• <library> is the C library you are compiling with (newlib or glibc)

The compilers, linkers, and other tools are located in the bin/ subdirectory in each toolchain. For example, the tools in the Windows SDK for PNaCl has a C++ compiler in toolchain/win_pnacl/bin/pnacl-clang++. As another example, the GCC-based C++ compiler that targets the x86 and uses the newlib library, is located at toolchain/win_x86_newlib/bin/x86_64-nacl-g++.

SDK toolchains versus your hosted toolchain

To build NaCl modules, you must use one of the Native Client toolchains included in the SDK. The SDK toolchains use a variety of techniques to ensure that your NaCl modules comply with the security constraints of the Native Client sandbox.

During development, you have another choice: You can build modules using a standard toolchain, such as the hosted toolchain on your development machine. This can be Visual Studio’s standard compiler, XCode, LLVM, or GNU-based compilers on your development machine. These standard toolchains will not produce executables that comply with the Native Client sandbox security constraints. They are also not portable across operating systems and not portable across different processors. However, using a standard toolchain allows you to develop modules in your favorite IDE and use your favorite debugging and profiling tools. The drawback is that modules compiled in this manner can only run as Pepper (PPAPI) plugins in Chrome. To publish and distribute Native Client modules as part of a web application, you must eventually use a toolchain in the Native Client SDK.

Compile

To compile a simple application consisting of file1.cc and file2.cc into hello_world.pexe with a single command, use the pnacl-clang++ tool

<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ file1.cc file2.cc ^
  -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/pnacl/Release ^
  -o hello_world.pexe -g -O2 -lppapi_cpp -lppapi

(The carat ^ allows the command to span multiple lines on Windows; to do the same on Mac and Linux use a backslash instead. Or you can simply type the command and all its arguments on one line. <NACL_SDK_ROOT> represents the path to the top-level directory of the bundle you are using, e.g., <location-where-you-installed-the-SDK>/pepper_31.)

However, the typical application consists of many files. In that case, each file can be compiled separately so that only files that are affected by a change need to be recompiled. To compile an individual file from your application, you must use either the pnacl-clang C compiler, or the pnacl-clang++ C++ compiler. The compiler produces separate bitcode files. For example:

<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ hello_world.cc ^
  -I<NACL_SDK_ROOT>/include -c -o hello_world.o -g -O0

For a description of each command line flag, run pnacl-clang --help. For convenience, here is a description of some of the flags used in the example.

-c

indicates that pnacl-clang++ should only compile an individual file, rather than continue the build process and link together the full application.

-o <output_file>

indicates the output filename.

-g

tells the compiler to include debug information in the result. This debug information can be used during development, and then stripped before actually deploying the application to keep the application’s download size small.

-On

sets the optimization level to n. Use 0 when debugging, and -O2 or -O3 for profiling and deployment.

The main difference between -O2 and -O3 is whether the compiler performs optimizations that involve a space-speed tradeoff. It could be the case that -O3 optimizations are not desirable due to increased pexe download size; you should make your own performance measurements to determine which level of optimization is right for you. When looking at code size, note that what you generally care about is not the size of the pexe produced by pnacl-clang, but the size of the compressed pexe that you upload your application to the server or to the Chrome Web Store. Optimizations that increase the size of a pexe may not increase the size of the compressed pexe that much.

-I<directory>

adds a directory to the search path for include files. The SDK has Pepper (PPAPI) headers located at <NACL_SDK_ROOT>/include, so add that directory when compiling to be able to include the headers.

Create a static library

The pnacl-ar and pnacl-ranlib tools allow you to create a static library from a set of bitcode files, which can later be linked into the full application.

<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ar cr libfoo.a ^
  foo1.o foo2.o foo3.o

<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a

Link the application

The pnacl-clang++ tool is used to compile applications, but it can also be used link together compiled bitcode and libraries into a full application.

<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
  hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Debug -lfoo -lppapi_cpp -lppapi

This links the hello world bitcode with the foo library in the example as well as the Debug version of the Pepper libraries which are located in <NACL_SDK_ROOT>/lib/pnacl/Debug. If you wish to link against the Release version of the Pepper libraries, change the -L<NACL_SDK_ROOT>/lib/pnacl/Debug to -L<NACL_SDK_ROOT>/lib/pnacl/Release.

Finalizing the pexe for deployment

Typically you would run the application to test it and debug it if needed before deploying. See the running documentation for how to run a PNaCl application, and see the debugging documentation for debugging techniques and workflow. After testing a PNaCl application, you must “finalize” it. The pnacl-finalize tool handles this.

<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-finalize ^
  hello_world.pexe -o hello_world.final.pexe

Prior to finalization, the application pexe is stored in a binary format that is subject to change. After finalization, the application pexe is rewritten into a different binary format that is stable and will be supported by future versions of PNaCl. The finalization step also helps minimize the size of your application for distribution by stripping out debug information and other metadata.

Once the application is finalized, be sure to adjust the manifest file to refer to the final version of the application before deployment. The create_nmf.py tool helps generate an .nmf file, but .nmf files can also be written by hand.

Compressing the pexe for deployment

Size compression is an optional step for deployment, and reduces the size of the pexe file that must be transmitted over the wire. The tool pnacl-compress applies compression strategies that are already built into the stable binary format of a pexe application. As such, compressed pexe files do not need any extra time to be decompressed on the client’s side. All costs are upfront when you call pnacl-compress.

Currently, this tool will compress pexe files by about 25%. However, it is somewhat slow (can take from seconds to minutes on large appications). Hence, this step is optional.

<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-compress ^
  hello_world.final.pexe

Tool pnacl-compress must be called after a pexe file has been finalized for deployment (via pnacl-finalize). Alternatively, you can apply this step as part of the finalizing step by adding the --compress flag to the pnacl-finalize command line.

Note that this compression step doesn’t replace gzip. This compression step is in addition to gzipping a file for deployment. One should note that while the gzipped version of a compressed pexe file is still smaller than the corresponding uncompressed pexe file, the gains is somewhat smaller after being gzipped. Expected reduction in size (after being gzipped) is more like 7.5% to 10%.

Compiling

Compiling files with the GNU-based toolchain is similar to compiling files with the PNaCl-based toolchain, except that the output is architecture specific.

For example, assuming you’re developing on a Windows machine, targeting the x86 architecture, and using the newlib library, you can compile a 32-bit .nexe for the hello_world example with the following command:

<NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/i686-nacl-gcc hello_world.c ^
  -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/newlib/Release ^
  -o hello_world_x86_32.nexe -m32 -g -O2 -lppapi

To compile a 64-bit .nexe, you can run the same command but use -m64 instead of -m32. Alternatively, you could also use the version of the compiler that targets the x86-64 architecture, i.e., x86_64-nacl-gcc.

You should name executable modules with a .nexe filename extension, regardless of what platform you’re using.

Creating libraries and Linking

Creating libraries and linking with the GNU-based toolchain is similar to doing the same with the PNaCl toolchain. The relevant tools for creating static libraries are <prefix>ar and <prefix>ranlib. Linking can be done with <prefix>g++. See the Dynamic Linking & Loading with glibc section on how to create shared libraries.

Finalizing a nexe for deployment

Unlike the PNaCl toolchain, no separate finalization step is required for nexe files. The nexe files are always in a stable format. However, the nexe file may contain debug information and symbol information which may make the nexe file larger than needed for distribution. To minimize the size of the distributed file, you can run the <prefix>strip tool to strip out debug information.

“Undefined reference” error

An “undefined reference” error may indicate incorrect link order and/or missing libraries. For example, if you leave out -lppapi when compiling Pepper applications you’ll see a series of undefined reference errors.

One common type of “undefined reference” error is with respect to certain system calls, e.g., “undefined reference to ‘mkdir’”. For security reasons, Native Client does not support a number of system calls. Depending on how your code uses such system calls, you have a few options:

1. Link with the -lnosys flag to provide empty/always-fail versions of unsupported system calls. This will at least get you past the link stage.
2. Find and remove use of the unsupported system calls.
3. Create your own implementation of the unsupported system calls to do something useful for your application.

If your code uses mkdir or other file system calls, you might find the nacl_io library useful. The nacl_io library essentially does option (3) for you: It lets your code use POSIX-like file system calls, and implements the calls using various technologies (e.g., HTML5 file system, read-only filesystems that use URL loaders, or an in-memory filesystem).

Can’t find libraries containing necessary symbols

Here is one way to find the appropriate library for a given symbol:

<NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin/pnacl-nm -o \
  toolchain/<platform>_pnacl/usr/lib/*.a | grep <MySymbolName>

PNaCl ABI Verification errors

PNaCl has restrictions on what is supported in bitcode. There is a bitcode ABI verifier which checks that the application conforms to the ABI restrictions, before it is translated and run in the browser. However, it is best to avoid runtime errors for users, so the verifier also runs on the developer’s machine at link time.

For example, the following program which uses 128-bit integers would compile with NaCl GCC for the x86-64 target. However, it is not portable and would not compile with NaCl GCC for the i686 target. With PNaCl, it would fail to pass the ABI verifier:

typedef unsigned int uint128_t __attribute__((mode(TI)));

uint128_t foo(uint128_t x) {
  return x;
}

With PNaCl you would get the following error at link time:

Function foo has disallowed type: i128 (i128)
LLVM ERROR: PNaCl ABI verification failed

When faced with a PNaCl ABI verification error, check the list of features that are not supported by PNaCl. If the problem you face is not listed as restricted, let us know!