7 .. contents:: Table Of Contents
15 This document describes how to build Native Client modules. It is intended for
16 developers who have experience writing, compiling, and linking C and C++ code.
17 If you haven't read the Native Client :doc:`Technical Overview
18 <../../overview>` and :doc:`Tutorial <../tutorial/index>`, we recommend starting
21 .. _target_architectures:
26 Portable Native Client (PNaCl) modules are written in C or C++ and compiled
27 into an executable file ending in a **.pexe** extension using the PNaCl
28 toolchain in the Native Client SDK. Chrome can load **pexe** files
29 embedded in web pages and execute them as part of a web application.
31 As explained in the Technical Overview, PNaCl modules are
32 operating-system-independent **and** processor-independent. The same
33 **pexe** will run on Windows, Mac, Linux, and ChromeOS and it will run on
34 any processor, e.g., x86-32, x86-64, and ARM.
36 Native Client also supports architecture-specific **nexe** files.
37 These **nexe** files are **also** operating-system-independent,
38 but they are **not** processor-independent. To support a wide-variety of
39 devices you must compile separate versions of your Native Client module
40 for different processors on end-user machines. A
41 :ref:`manifest file <application_files>` will then specify which version
42 of the module to load based on the end-user's architecture. The SDK
43 includes a script---``create_nmf.py`` (in the ``tools/`` directory)---to
44 generate manifest files. For examples of how to compile modules
45 for multiple target architectures and how to generate manifest files, see the
46 Makefiles included with the SDK examples.
48 This section will mostly cover PNaCl, but also describes how to build
54 The PNaCl SDK has a single choice of C library: newlib_.
56 The Native Client SDK also has a GCC-based toolchain for building
57 **nexes**. The GCC-based toolchain has support for two C libraries:
58 newlib_ and glibc_. See :doc:`Dynamic Linking & Loading with glibc
59 <dynamic-loading>` for information about these libraries, including factors to
60 help you decide which to use.
62 .. _building_cpp_libraries:
67 The PNaCl SDK can use either `libstdc++ <http://gcc.gnu.org/libstdc++>`_ (the
68 current default) or LLVM's `libc++ <http://libcxx.llvm.org/>`_ (experimental
69 support). The ``-stdlib=[libstdc++|libc++]`` command line argument can be used
70 to choose which standard library to use.
72 The GCC-based Native Client SDK only has support for `libstdc++
73 <http://gcc.gnu.org/libstdc++>`_.
75 C++11 library support is only complete in libc++ but other non-library
76 language features should work regardless of which standard library is
77 used. The ``-std=[c++98|c++11]`` command line argument can be used to
78 indicate which C++ language standard to use (or ``-std=gnu++11`` with
79 non-standard extensions).
84 The Native Client SDK includes multiple toolchains. It has one PNaCl toolchain
85 and it has multiple GCC-based toolchains that are differentiated by target
86 architectures and C libraries. The single PNaCl toolchain is located
87 in a directory named ``toolchain/<OS_platform>_pnacl``, and the GCC-based
88 toolchains are located in directories named
89 ``toolchain/<OS_platform>_<architecture>_<library>``, where:
91 * *<platform>* is the platform of your development machine (win, mac, or linux)
92 * *<architecture>* is your target architecture (x86 or arm)
93 * *<library>* is the C library you are compiling with (newlib or glibc)
95 The compilers, linkers, and other tools are located in the ``bin/``
96 subdirectory in each toolchain. For example, the tools in the Windows SDK
97 for PNaCl has a C++ compiler in ``toolchain/win_pnacl/bin/pnacl-clang++``.
98 As another example, the GCC-based C++ compiler that targets the x86 and uses the
99 newlib library, is located at ``toolchain/win_x86_newlib/bin/x86_64-nacl-g++``.
104 The SDK toolchains descend from the ``toolchain/`` directory. The SDK also
105 has a ``tools/`` directory; this directory contains utilities that are not
106 properly part of the toolchains but that you may find helpful in building and
107 testing your application (e.g., the ``create_nmf.py`` script, which you can
108 use to create a manifest file).
110 SDK toolchains versus your hosted toolchain
111 -------------------------------------------
113 To build NaCl modules, you must use one of the Native Client toolchains
114 included in the SDK. The SDK toolchains use a variety of techniques to
115 ensure that your NaCl modules comply with the security constraints of
116 the Native Client sandbox.
118 During development, you have another choice: You can build modules using a
119 *standard* toolchain, such as the hosted toolchain on your development
120 machine. This can be Visual Studio's standard compiler, XCode, LLVM, or
121 GNU-based compilers on your development machine. These standard toolchains
122 will not produce executables that comply with the Native Client sandbox
123 security constraints. They are also not portable across operating systems
124 and not portable across different processors. However, using a standard
125 toolchain allows you to develop modules in your favorite IDE and use
126 your favorite debugging and profiling tools. The drawback is that modules
127 compiled in this manner can only run as Pepper (PPAPI) plugins in Chrome.
128 To publish and distribute Native Client modules as part of a web
129 application, you must eventually use a toolchain in the Native
135 In the future, additional tools will be available to compile Native Client
136 modules written in other programming languages, such as C#. But this
137 document covers only compiling C and C++ code, using the toolchains
144 The PNaCl toolchain contains modified versions of the tools in the
145 LLVM toolchain, as wells as linkers and other tools from binutils.
146 To determine which version of LLVM or binutils the tools are based upon,
147 run the tool with the ``--version`` commandline flag. These tools
148 are used to compile and link applications into .pexe files. The toolchain
149 also contains a tool to translate a .pexe file into a
150 architecture-specific .nexe (e.g., for debugging purposes).
152 Each tool's name is preceded by the prefix "pnacl-". Some of the useful
156 Check that the **pexe** follows the PNaCl ABI rules.
158 Creates archives (e.g., static libraries)
160 C-compiler and compiler driver
162 C++-compiler and compiler driver
164 Disassembler for both **pexe** files and **nexe** files
166 Finalizes **pexe** files for deployment
170 Lists symbols in bitcode files, native code, and libraries
172 Generates a symbol table for archives (e.g., static libraries)
174 Translates a **pexe** to a native architecture, outside of the browser
176 For the full list of tools, see the
177 ``<NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin`` directory.
179 Using the PNaCl tools to compile, link, debug, and deploy
180 =========================================================
182 To build an application with the PNaCl SDK toolchain, you must compile
183 your code, link it, test and debug it, and then deploy it. This section goes
184 over some examples of how to use the tools.
189 To compile a simple application consisting of ``file1.cc`` and ``file2.cc`` into
190 ``hello_world.pexe`` with a single command, use the ``pnacl-clang++`` tool
195 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ file1.cc file2.cc ^
196 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/pnacl/Release ^
197 -o hello_world.pexe -g -O2 -lppapi_cpp -lppapi
199 (The carat ``^`` allows the command to span multiple lines on Windows;
200 to do the same on Mac and Linux use a backslash instead. Or you can
201 simply type the command and all its arguments on one
202 line. ``<NACL_SDK_ROOT>`` represents the path to the top-level
203 directory of the bundle you are using, e.g.,
204 ``<location-where-you-installed-the-SDK>/pepper_31``.)
206 However, the typical application consists of many files. In that case,
207 each file can be compiled separately so that only files that are
208 affected by a change need to be recompiled. To compile an individual
209 file from your application, you must use either the ``pnacl-clang`` C
210 compiler, or the ``pnacl-clang++`` C++ compiler. The compiler produces
211 separate bitcode files. For example:
216 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ hello_world.cc ^
217 -I<NACL_SDK_ROOT>/include -c -o hello_world.o -g -O0
219 For a description of each commandline flag, run ``pnacl-clang --help``.
220 For convenience, here is a description of some of the flags used in
226 indicates that ``pnacl-clang++`` should only compile an individual file,
227 rather than continue the build process and link together the
231 indicates the **output** filename.
234 tells the compiler to include debug information in the result.
235 This debug information can be used during development, and then **stripped**
236 before actually deploying the application to keep the application's
240 sets the optimization level to n. Use 0 when debugging, and -O2 or -O3
241 for profiling and deployment.
243 The main difference between -O2 and -O3 is whether the compiler performs
244 optimizations that involve a space-speed tradeoff. It could be the case that
245 ``-O3`` optimizations are not desirable due to increased **pexe**
246 download size; you should make your own performance measurements to determine
247 which level of optimization is right for you. When looking at code size,
248 note that what you generally care about is not the size of the pexe
249 produced by pnacl-clang, but the size of the compressed pexe that you upload
250 your application to the server or to the Chrome Web Store.
251 Optimizations that increase the size of a pexe may not increase the size of
252 the compressed pexe that much.
255 adds a directory to the search path for **include** files. The SDK has
256 Pepper (PPAPI) headers located at ``<NACL_SDK_ROOT>/include``, so add
257 that directory when compiling to be able to include the headers.
260 Create a static library
261 -----------------------
263 The ``pnacl-ar`` and ``pnacl-ranlib`` tools allow you to create a
264 **static** library from a set of bitcode files, which can later be linked
265 into the full application.
270 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ar cr libfoo.a ^
273 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a
279 The ``pnacl-clang++`` tool is used to compile applications, but it can
280 also be used link together compiled bitcode and libraries into a
286 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
287 hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Debug -lfoo -lppapi_cpp -lppapi
289 This links the hello world bitcode with the ``foo`` library in the example
290 as well as the *Debug* version of the Pepper libraries which are located
291 in ``<NACL_SDK_ROOT>/lib/pnacl/Debug``. If you wish to link against the
292 *Release* version of the Pepper libraries, change the
293 ``-L<NACL_SDK_ROOT>/lib/pnacl/Debug`` to
294 ``-L<NACL_SDK_ROOT>/lib/pnacl/Release``.
297 Finalizing the **pexe** for deployment
298 --------------------------------------
300 Typically you would run the application to test it and debug it if needed
301 before deploying. See the :doc:`running <running>` documentation for how
302 to run a PNaCl application, and see the :doc:`debugging <debugging>`
303 documentation for debugging techniques and workflow. After testing a PNaCl
304 application, you must **"finalize"** it. The ``pnacl-finalize``
310 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-finalize ^
311 hello_world.pexe -o hello_world.final.pexe
313 Prior to finalization, the application **pexe** is stored in a binary
314 format that is subject to change. After finalization, the application
315 pexe is **rewritten** into a different binary format that is **stable**
316 and will be supported by future versions of PNaCl. The finalization step
317 also helps minimize the size of your application for distribution by
318 stripping out debug information and other metadata.
320 Once the application is finalized, be sure to adjust the manifest file to
321 refer to the final version of the application before deployment.
322 The ``create_nmf.py`` tool helps generate an ``.nmf`` file, but ``.nmf``
323 files can also be written by hand.
326 The GNU-based toolchains
327 ========================
329 Besides the PNaCl toolchain, the Native Client SDK also includes modified
330 versions of the tools in the standard GNU toolchain, including the GCC
331 compilers and the linkers and other tools from binutils. These tools only
332 support building **nexe** files. Run the tool with the ``--version``
333 commandline flag to determine the current version of the tools.
335 Each tool in the toolchain is prefixed with the name of the target
336 architecture. In the toolchain for the ARM target architecture, each
337 tool's name is preceded by the prefix "arm-nacl-". In the toolchains for
338 the x86 target architecture, there are actually two versions of each
339 tool---one to build Native Client modules for the x86-32
340 target architecture, and one to build modules for the x86-64 target
341 architecture. "i686-nacl-" is the prefix for tools used to build
342 32-bit .nexes, and "x86_64-nacl-" is the prefix for tools used to
345 These prefixes conform to gcc naming standards and make it easy to use tools
346 like autoconf. As an example, you can use ``i686-nacl-gcc`` to compile 32-bit
347 .nexes, and ``x86_64-nacl-gcc`` to compile 64-bit .nexes. Note that you can
348 typically override a tool's default target architecture with command line
349 flags, e.g., you can specify ``x86_64-nacl-gcc -m32`` to compile a 32-bit
352 The GNU-based SDK toolchains include the following tools:
380 Compiling files with the GNU-based toolchain is similar to compiling
381 files with the PNaCl-based toolchain, except that the output is
382 architecture specific.
384 For example, assuming you're developing on a Windows machine, targeting the x86
385 architecture, and using the newlib library, you can compile a 32-bit .nexe for
386 the hello_world example with the following command:
391 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/i686-nacl-gcc hello_world.c ^
392 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/newlib/Release ^
393 -o hello_world_x86_32.nexe -m32 -g -O2 -lppapi
395 To compile a 64-bit .nexe, you can run the same command but use -m64 instead of
396 -m32. Alternatively, you could also use the version of the compiler that
397 targets the x86-64 architecture, i.e., ``x86_64-nacl-gcc``.
399 You should name executable modules with a **.nexe** filename extension,
400 regardless of what platform you're using.
402 Creating libraries and Linking
403 ------------------------------
405 Creating libraries and linking with the GNU-based toolchain is similar
406 to doing the same with the PNaCl toolchain. The relevant tools
407 for creating **static** libraries are ``<prefix>ar`` and ``<prefix>ranlib``.
408 Linking can be done with ``<prefix>g++``. See the
409 :doc:`Dynamic Linking & Loading with glibc <dynamic-loading>`
410 section on how to create **shared** libraries.
413 Finalizing a **nexe** for deployment
414 ------------------------------------
416 Unlike the PNaCl toolchain, no separate finalization step is required
417 for **nexe** files. The nexe files are always in a **stable** format.
418 However, the nexe file may contain debug information and symbol information
419 which may make the nexe file larger than needed for distribution.
420 To minimize the size of the distributed file, you can run the
421 ``<prefix>strip`` tool to strip out debug information.
427 This document doesn't cover how to use ``make``, but if you want to use
428 ``make`` to build your Native Client module, you can base your Makefile on the
429 ones in the SDK examples.
431 The Makefiles for the SDK examples build most of the examples in multiple
432 configurations (using PNaCl vs NaCl, using different C libraries,
433 targeting different architectures, and using different levels of optimization).
434 To select a specific toolchain, set the **environment variable**
435 ``TOOLCHAIN`` to either ``pnacl``, ``newlib``, ``glibc``, or ``host``.
436 To select a specific level of optimization set the **environment
437 variable** ``CONFIG`` to either ``Debug``, or ``Release``. Running
438 ``make`` in each example's directory does **one** of the following,
439 depending on the setting of the environment variables.
441 * If ``TOOLCHAIN=pnacl`` creates a subdirectory called ``pnacl``;
443 * builds a .pexe (architecture-independent Native Client executable) using
445 * generates a Native Client manifest (.nmf) file for the pnacl version of the
448 * If ``TOOLCHAIN=newlib`` creates a subdirectory called ``newlib``;
450 * builds .nexes for the x86-32, x86-64, and ARM architectures using the
452 * generates a Native Client manifest (.nmf) file for the newlib version of
455 * If ``TOOLCHAIN=glibc`` creates a subdirectory called ``glibc``;
457 * builds .nexes for the x86-32 and x86-64 architectures using the glibc
459 * generates a Native Client manifest (.nmf) file for the glibc version of the
462 * If ``TOOLCHAIN=host`` creates a subdirectory called ``windows``, ``linux``,
463 or ``mac`` (depending on your development machine);
465 * builds a Pepper plugin (.dll for Windows, .so for Linux/Mac) using the
466 hosted toolchain on your development machine
467 * generates a Native Client manifest (.nmf) file for the host Pepper plugin
468 version of the example
474 The glibc library is not yet available for the ARM and PNaCl toolchains.
476 Here is how to build the examples with PNaCl in Release mode on Windows.
477 The resulting files for ``examples/api/audio`` will be in
478 ``examples/api/audio/pnacl/Release``, and the directory layout is similar for
488 Your Makefile can be simpler since you will not likely want to build so many
489 different configurations of your module. The example Makefiles define
490 numerous variables near the top (e.g., ``CFLAGS``) that make it easy
491 to customize the commands that are executed for your project and the options
494 For details on how to use make, see the `GNU 'make' Manual
495 <http://www.gnu.org/software/make/manual/make.html>`_.
497 Libraries and header files provided with the SDK
498 ================================================
500 The Native Client SDK includes modified versions of standard toolchain-support
501 libraries, such as libpthread and libc, plus the relevant header files.
502 The standard libraries are located in the following directories:
504 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/lib``
505 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/lib32`` and
506 ``/lib64`` (for the 32-bit and 64-bit target architectures, respectively)
507 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/lib``
509 For example, on Windows, the libraries for the x86-64 architecture in the
510 newlib toolchain are in ``toolchain/win_x86_newlib/x86_64-nacl/lib64``.
512 The header files are in:
514 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/include``
515 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/include``
516 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/include``
518 Many other libraries have been ported for use with Native Client; for more
519 information, see the `naclports <http://code.google.com/p/naclports/>`_
520 project. If you port an open-source library for your own use, we recommend
521 adding it to naclports.
523 Besides the standard libraries, the SDK includes Pepper libraries.
524 The PNaCl Pepper libraries are located in the the
525 ``<NACL_SDK_ROOT>/lib/pnacl/<Release or Debug>`` directory.
526 The GNU-based toolchain has Pepper libraries in
527 ``<NACL_SDK_ROOT>/lib/newlib_<arch>/<Release or Debug>``
528 and ``<NACL_SDK_ROOT>/lib/glibc_<arch>/<Release or Debug>``.
529 The libraries provided by the SDK allow the application to use Pepper,
530 as well as convenience libraries to simplify porting an application that
531 uses POSIX functions. Here are descriptions of the Pepper libraries provided
534 .. _devcycle-building-nacl-io:
537 Implements the Pepper (PPAPI) C interface. Needed for all applications that
538 use Pepper (even C++ applications).
541 Implements the Pepper (PPAPI) C++ interface. Needed by C++ applications that
545 Implements the Pepper (PPAPI) GLES interface. Needed by applications
546 that use the 3D graphics API.
549 Provides a POSIX layer for NaCl. In particular, the library provides a
550 virtual file system and support for sockets. The virtual file system
551 allows a module to "mount" a given directory tree. Once a module has
552 mounted a file system, it can use standard C library file operations:
553 ``fopen``, ``fread``, ``fwrite``, ``fseek``, and ``fclose``.
554 For more detail, see the header ``include/nacl_io/nacl_io.h``.
555 For an example of how to use nacl_io, see ``examples/demo/nacl_io``.
558 Provides a familiar C programming environment by letting a module have a
559 simple entry point that is registered by ``PPAPI_SIMPLE_REGISTER_MAIN``.
560 The entry point is similar to the standard C ``main()`` function, complete
561 with ``argc`` and ``argv[]`` parameters. For details see
562 ``include/ppapi_simple/ps.h``. For an example of
563 how to use ppapi_simple, ``see examples/tutorial/using_ppapi_simple``.
569 * Since the Native Client toolchains use their own library and header search
570 paths, the tools won't find third-party libraries you use in your
571 non-Native-Client development. If you want to use a specific third-party
572 library for Native Client development, look for it in `naclports
573 <http://code.google.com/p/naclports/>`_, or port the library yourself.
574 * The order in which you list libraries in your build commands is important,
575 since the linker searches and processes libraries in the order in which they
576 are specified. See the \*_LDFLAGS variables in the Makefiles of the SDK
577 examples for the order in which specific libraries should be listed.
582 Some common problems, and how to fix them:
584 "Undefined reference" error
585 ---------------------------
587 An "undefined reference" error may indicate incorrect link order and/or
588 missing libraries. For example, if you leave out ``-lppapi`` when
589 compiling Pepper applications you'll see a series of undefined
592 One common type of "undefined reference" error is with respect to certain
593 system calls, e.g., "undefined reference to 'mkdir'". For security reasons,
594 Native Client does not support a number of system calls. Depending on how
595 your code uses such system calls, you have a few options:
597 #. Link with the ``-lnosys`` flag to provide empty/always-fail versions of
598 unsupported system calls. This will at least get you past the link stage.
599 #. Find and remove use of the unsupported system calls.
600 #. Create your own implementation of the unsupported system calls to do
601 something useful for your application.
603 If your code uses mkdir or other file system calls, you might find the
604 :ref:`nacl_io <devcycle-building-nacl-io>` library useful.
605 The nacl_io library essentially does option (3) for you: It lets your
606 code use POSIX-like file system calls, and implements the calls using
607 various technologies (e.g., HTML5 file system, read-only filesystems that
608 use URL loaders, or an in-memory filesystem).
610 Can't find libraries containing necessary symbols
611 -------------------------------------------------
613 Here is one way to find the appropriate library for a given symbol:
618 <NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin/pnacl-nm -o \
619 toolchain/<platform>_pnacl/usr/lib/*.a | grep <MySymbolName>
622 PNaCl ABI Verification errors
623 -----------------------------
625 PNaCl has restrictions on what is supported in bitcode. There is a bitcode
626 ABI verifier which checks that the application conforms to the ABI restrictions,
627 before it is translated and run in the browser. However, it is best to
628 avoid runtime errors for users, so the verifier also runs on the developer's
629 machine at link time.
631 For example, the following program which uses 128-bit integers
632 would compile with NaCl GCC for the x86-64 target. However, it is not
633 portable and would not compile with NaCl GCC for the i686 target.
634 With PNaCl, it would fail to pass the ABI verifier:
638 typedef unsigned int uint128_t __attribute__((mode(TI)));
640 uint128_t foo(uint128_t x) {
644 With PNaCl you would get the following error at link time:
648 Function foo has disallowed type: i128 (i128)
649 LLVM ERROR: PNaCl ABI verification failed
651 When faced with a PNaCl ABI verification error, check the list of features
652 that are :ref:`not supported by PNaCl <when-to-use-nacl>`.
653 If the problem you face is not listed as restricted,
654 :ref:`let us know <help>`!
656 .. _glibc: http://www.gnu.org/software/libc/
657 .. _newlib: http://sourceware.org/newlib/