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:
64 C++ standard libraries
65 ----------------------
67 The PNaCl SDK can use either LLVM's `libc++ <http://libcxx.llvm.org/>`_
68 (the current default) or GCC's `libstdc++
69 <http://gcc.gnu.org/libstdc++>`_ (deprecated). The
70 ``-stdlib=[libc++|libstdc++]`` command line argument can be used to
71 choose which standard library to use.
73 The GCC-based Native Client SDK only has support for GCC's `libstdc++
74 <http://gcc.gnu.org/libstdc++>`_.
76 C++11 library support is only complete in libc++ but other non-library
77 language features should work regardless of which standard library is
78 used. The ``-std=[c++98|c++11]`` command line argument can be used to
79 indicate which C++ language standard to use (or ``-std=gnu++11`` to
80 access non-standard extensions).
85 The Native Client SDK includes multiple toolchains. It has one PNaCl toolchain
86 and it has multiple GCC-based toolchains that are differentiated by target
87 architectures and C libraries. The single PNaCl toolchain is located
88 in a directory named ``toolchain/<OS_platform>_pnacl``, and the GCC-based
89 toolchains are located in directories named
90 ``toolchain/<OS_platform>_<architecture>_<library>``, where:
92 * *<platform>* is the platform of your development machine (win, mac, or linux)
93 * *<architecture>* is your target architecture (x86 or arm)
94 * *<library>* is the C library you are compiling with (newlib or glibc)
96 The compilers, linkers, and other tools are located in the ``bin/``
97 subdirectory in each toolchain. For example, the tools in the Windows SDK
98 for PNaCl has a C++ compiler in ``toolchain/win_pnacl/bin/pnacl-clang++``.
99 As another example, the GCC-based C++ compiler that targets the x86 and uses the
100 newlib library, is located at ``toolchain/win_x86_newlib/bin/x86_64-nacl-g++``.
105 The SDK toolchains descend from the ``toolchain/`` directory. The SDK also
106 has a ``tools/`` directory; this directory contains utilities that are not
107 properly part of the toolchains but that you may find helpful in building and
108 testing your application (e.g., the ``create_nmf.py`` script, which you can
109 use to create a manifest file).
111 SDK toolchains versus your hosted toolchain
112 -------------------------------------------
114 To build NaCl modules, you must use one of the Native Client toolchains
115 included in the SDK. The SDK toolchains use a variety of techniques to
116 ensure that your NaCl modules comply with the security constraints of
117 the Native Client sandbox.
119 During development, you have another choice: You can build modules using a
120 *standard* toolchain, such as the hosted toolchain on your development
121 machine. This can be Visual Studio's standard compiler, XCode, LLVM, or
122 GNU-based compilers on your development machine. These standard toolchains
123 will not produce executables that comply with the Native Client sandbox
124 security constraints. They are also not portable across operating systems
125 and not portable across different processors. However, using a standard
126 toolchain allows you to develop modules in your favorite IDE and use
127 your favorite debugging and profiling tools. The drawback is that modules
128 compiled in this manner can only run as Pepper (PPAPI) plugins in Chrome.
129 To publish and distribute Native Client modules as part of a web
130 application, you must eventually use a toolchain in the Native
136 In the future, additional tools will be available to compile Native Client
137 modules written in other programming languages, such as C#. But this
138 document covers only compiling C and C++ code, using the toolchains
145 The PNaCl toolchain contains modified versions of the tools in the
146 LLVM toolchain, as well as linkers and other tools from binutils.
147 To determine which version of LLVM or binutils the tools are based upon,
148 run the tool with the ``--version`` command line flag. These tools
149 are used to compile and link applications into .pexe files. The toolchain
150 also contains a tool to translate a .pexe file into a
151 architecture-specific .nexe (e.g., for debugging purposes).
153 Each tool's name is preceded by the prefix "pnacl-". Some of the useful
157 Check that the **pexe** follows the PNaCl ABI rules.
159 Creates archives (i.e., static libraries)
161 C compiler and compiler driver
163 C++ compiler and compiler driver
165 Size compresses a finalized **pexe** file for deployment.
167 Disassembler for both **pexe** files and **nexe** files
169 Finalizes **pexe** files for deployment
173 Lists symbols in bitcode files, native code, and libraries
175 Generates a symbol table for archives (i.e., static libraries)
177 Translates a **pexe** to a native architecture, outside of the browser
179 For the full list of tools, see the
180 ``<NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin`` directory.
182 Using the PNaCl tools to compile, link, debug, and deploy
183 =========================================================
185 To build an application with the PNaCl SDK toolchain, you must compile
186 your code, link it, test and debug it, and then deploy it. This section goes
187 over some examples of how to use the tools.
192 To compile a simple application consisting of ``file1.cc`` and ``file2.cc`` into
193 ``hello_world.pexe`` with a single command, use the ``pnacl-clang++`` tool
198 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ file1.cc file2.cc ^
199 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/pnacl/Release ^
200 -o hello_world.pexe -g -O2 -lppapi_cpp -lppapi
202 (The carat ``^`` allows the command to span multiple lines on Windows;
203 to do the same on Mac and Linux use a backslash instead. Or you can
204 simply type the command and all its arguments on one
205 line. ``<NACL_SDK_ROOT>`` represents the path to the top-level
206 directory of the bundle you are using, e.g.,
207 ``<location-where-you-installed-the-SDK>/pepper_31``.)
209 However, the typical application consists of many files. In that case,
210 each file can be compiled separately so that only files that are
211 affected by a change need to be recompiled. To compile an individual
212 file from your application, you must use either the ``pnacl-clang`` C
213 compiler, or the ``pnacl-clang++`` C++ compiler. The compiler produces
214 separate bitcode files. For example:
219 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ hello_world.cc ^
220 -I<NACL_SDK_ROOT>/include -c -o hello_world.o -g -O0
222 For a description of each command line flag, run ``pnacl-clang --help``.
223 For convenience, here is a description of some of the flags used in
229 indicates that ``pnacl-clang++`` should only compile an individual file,
230 rather than continue the build process and link together the
234 indicates the **output** filename.
237 tells the compiler to include debug information in the result.
238 This debug information can be used during development, and then **stripped**
239 before actually deploying the application to keep the application's
243 sets the optimization level to n. Use 0 when debugging, and -O2 or -O3
244 for profiling and deployment.
246 The main difference between -O2 and -O3 is whether the compiler performs
247 optimizations that involve a space-speed tradeoff. It could be the case that
248 ``-O3`` optimizations are not desirable due to increased **pexe**
249 download size; you should make your own performance measurements to determine
250 which level of optimization is right for you. When looking at code size,
251 note that what you generally care about is not the size of the pexe
252 produced by pnacl-clang, but the size of the compressed pexe that you upload
253 your application to the server or to the Chrome Web Store.
254 Optimizations that increase the size of a pexe may not increase the size of
255 the compressed pexe that much.
258 adds a directory to the search path for **include** files. The SDK has
259 Pepper (PPAPI) headers located at ``<NACL_SDK_ROOT>/include``, so add
260 that directory when compiling to be able to include the headers.
263 Create a static library
264 -----------------------
266 The ``pnacl-ar`` and ``pnacl-ranlib`` tools allow you to create a
267 **static** library from a set of bitcode files, which can later be linked
268 into the full application.
273 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ar cr libfoo.a ^
276 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a
282 The ``pnacl-clang++`` tool is used to compile applications, but it can
283 also be used link together compiled bitcode and libraries into a
289 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
290 hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Debug -lfoo -lppapi_cpp -lppapi
292 This links the hello world bitcode with the ``foo`` library in the example
293 as well as the *Debug* version of the Pepper libraries which are located
294 in ``<NACL_SDK_ROOT>/lib/pnacl/Debug``. If you wish to link against the
295 *Release* version of the Pepper libraries, change the
296 ``-L<NACL_SDK_ROOT>/lib/pnacl/Debug`` to
297 ``-L<NACL_SDK_ROOT>/lib/pnacl/Release``.
300 Finalizing the **pexe** for deployment
301 --------------------------------------
303 Typically you would run the application to test it and debug it if needed
304 before deploying. See the :doc:`running <running>` documentation for how
305 to run a PNaCl application, and see the :doc:`debugging <debugging>`
306 documentation for debugging techniques and workflow. After testing a PNaCl
307 application, you must **"finalize"** it. The ``pnacl-finalize``
313 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-finalize ^
314 hello_world.pexe -o hello_world.final.pexe
316 Prior to finalization, the application **pexe** is stored in a binary
317 format that is subject to change. After finalization, the application
318 pexe is **rewritten** into a different binary format that is **stable**
319 and will be supported by future versions of PNaCl. The finalization step
320 also helps minimize the size of your application for distribution by
321 stripping out debug information and other metadata.
323 Once the application is finalized, be sure to adjust the manifest file to
324 refer to the final version of the application before deployment.
325 The ``create_nmf.py`` tool helps generate an ``.nmf`` file, but ``.nmf``
326 files can also be written by hand.
331 Compressing the **pexe** for deployment
332 ---------------------------------------
334 Size compression is an optional step for deployment, and reduces the
335 size of the pexe file that must be transmitted over the wire. The tool
336 ``pnacl-compress`` applies compression strategies that are already built
337 into the **stable** binary format of a pexe application. As such,
338 compressed pexe files do not need any extra time to be decompressed on
339 the client's side. All costs are upfront when you call ``pnacl-compress``.
341 Currently, this tool will compress pexe files by about 25%. However,
342 it is somewhat slow (can take from seconds to minutes on large
343 appications). Hence, this step is optional.
348 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-compress ^
349 hello_world.final.pexe
351 Tool ``pnacl-compress`` must be called after a pexe file has been finalized
352 for deployment (via ``pnacl-finalize``). Alternatively, you can apply this
353 step as part of the finalizing step by adding the ``--compress`` flag
354 to the pnacl-finalize command line.
356 Note that this compression step doesn't replace gzip. This compression
357 step is in addition to gzipping a file for deployment. One should note
358 that while the gzipped version of a compressed pexe file is still
359 smaller than the corresponding uncompressed pexe file, the gains is
360 somewhat smaller after being gzipped. Expected reduction in size
361 (after being gzipped) is more like 7.5% to 10%.
363 The GNU-based toolchains
364 ========================
366 Besides the PNaCl toolchain, the Native Client SDK also includes modified
367 versions of the tools in the standard GNU toolchain, including the GCC
368 compilers and the linkers and other tools from binutils. These tools only
369 support building **nexe** files. Run the tool with the ``--version``
370 command line flag to determine the current version of the tools.
372 Each tool in the toolchain is prefixed with the name of the target
373 architecture. In the toolchain for the ARM target architecture, each
374 tool's name is preceded by the prefix "arm-nacl-". In the toolchains for
375 the x86 target architecture, there are actually two versions of each
376 tool---one to build Native Client modules for the x86-32
377 target architecture, and one to build modules for the x86-64 target
378 architecture. "i686-nacl-" is the prefix for tools used to build
379 32-bit .nexes, and "x86_64-nacl-" is the prefix for tools used to
382 These prefixes conform to gcc naming standards and make it easy to use tools
383 like autoconf. As an example, you can use ``i686-nacl-gcc`` to compile 32-bit
384 .nexes, and ``x86_64-nacl-gcc`` to compile 64-bit .nexes. Note that you can
385 typically override a tool's default target architecture with command line
386 flags, e.g., you can specify ``x86_64-nacl-gcc -m32`` to compile a 32-bit
389 The GNU-based SDK toolchains include the following tools:
417 Compiling files with the GNU-based toolchain is similar to compiling
418 files with the PNaCl-based toolchain, except that the output is
419 architecture specific.
421 For example, assuming you're developing on a Windows machine, targeting the x86
422 architecture, and using the newlib library, you can compile a 32-bit .nexe for
423 the hello_world example with the following command:
428 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/i686-nacl-gcc hello_world.c ^
429 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/newlib/Release ^
430 -o hello_world_x86_32.nexe -m32 -g -O2 -lppapi
432 To compile a 64-bit .nexe, you can run the same command but use -m64 instead of
433 -m32. Alternatively, you could also use the version of the compiler that
434 targets the x86-64 architecture, i.e., ``x86_64-nacl-gcc``.
436 You should name executable modules with a **.nexe** filename extension,
437 regardless of what platform you're using.
439 Creating libraries and Linking
440 ------------------------------
442 Creating libraries and linking with the GNU-based toolchain is similar
443 to doing the same with the PNaCl toolchain. The relevant tools
444 for creating **static** libraries are ``<prefix>ar`` and ``<prefix>ranlib``.
445 Linking can be done with ``<prefix>g++``. See the
446 :doc:`Dynamic Linking & Loading with glibc <dynamic-loading>`
447 section on how to create **shared** libraries.
450 Finalizing a **nexe** for deployment
451 ------------------------------------
453 Unlike the PNaCl toolchain, no separate finalization step is required
454 for **nexe** files. The nexe files are always in a **stable** format.
455 However, the nexe file may contain debug information and symbol information
456 which may make the nexe file larger than needed for distribution.
457 To minimize the size of the distributed file, you can run the
458 ``<prefix>strip`` tool to strip out debug information.
464 This document doesn't cover how to use ``make``, but if you want to use
465 ``make`` to build your Native Client module, you can base your Makefile on the
466 ones in the SDK examples.
468 The Makefiles for the SDK examples build most of the examples in multiple
469 configurations (using PNaCl vs NaCl, using different C libraries,
470 targeting different architectures, and using different levels of optimization).
471 To select a specific toolchain, set the **environment variable**
472 ``TOOLCHAIN`` to either ``pnacl``, ``newlib``, ``glibc``, or ``host``.
473 To select a specific level of optimization set the **environment
474 variable** ``CONFIG`` to either ``Debug``, or ``Release``. Running
475 ``make`` in each example's directory does **one** of the following,
476 depending on the setting of the environment variables.
478 * If ``TOOLCHAIN=pnacl`` creates a subdirectory called ``pnacl``;
480 * builds a .pexe (architecture-independent Native Client executable) using
482 * generates a Native Client manifest (.nmf) file for the pnacl version of the
485 * If ``TOOLCHAIN=newlib`` creates a subdirectory called ``newlib``;
487 * builds .nexes for the x86-32, x86-64, and ARM architectures using the
489 * generates a Native Client manifest (.nmf) file for the newlib version of
492 * If ``TOOLCHAIN=glibc`` creates a subdirectory called ``glibc``;
494 * builds .nexes for the x86-32 and x86-64 architectures using the glibc
496 * generates a Native Client manifest (.nmf) file for the glibc version of the
499 * If ``TOOLCHAIN=host`` creates a subdirectory called ``windows``, ``linux``,
500 or ``mac`` (depending on your development machine);
502 * builds a Pepper plugin (.dll for Windows, .so for Linux/Mac) using the
503 hosted toolchain on your development machine
504 * generates a Native Client manifest (.nmf) file for the host Pepper plugin
505 version of the example
511 The glibc library is not yet available for the ARM and PNaCl toolchains.
513 Here is how to build the examples with PNaCl in Release mode on Windows.
514 The resulting files for ``examples/api/audio`` will be in
515 ``examples/api/audio/pnacl/Release``, and the directory layout is similar for
525 Your Makefile can be simpler since you will not likely want to build so many
526 different configurations of your module. The example Makefiles define
527 numerous variables near the top (e.g., ``CFLAGS``) that make it easy
528 to customize the commands that are executed for your project and the options
531 For details on how to use make, see the `GNU 'make' Manual
532 <http://www.gnu.org/software/make/manual/make.html>`_.
534 Libraries and header files provided with the SDK
535 ================================================
537 The Native Client SDK includes modified versions of standard toolchain-support
538 libraries, such as libpthread and libc, plus the relevant header files.
539 The standard libraries are located in the following directories:
541 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/lib``
542 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/lib32`` and
543 ``/lib64`` (for the 32-bit and 64-bit target architectures, respectively)
544 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/lib``
546 For example, on Windows, the libraries for the x86-64 architecture in the
547 newlib toolchain are in ``toolchain/win_x86_newlib/x86_64-nacl/lib64``.
549 The header files are in:
551 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/include``
552 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/include``
553 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/include``
555 Many other libraries have been ported for use with Native Client; for more
556 information, see the `naclports <http://code.google.com/p/naclports/>`_
557 project. If you port an open-source library for your own use, we recommend
558 adding it to naclports.
560 Besides the standard libraries, the SDK includes Pepper libraries.
561 The PNaCl Pepper libraries are located in the the
562 ``<NACL_SDK_ROOT>/lib/pnacl/<Release or Debug>`` directory.
563 The GNU-based toolchain has Pepper libraries in
564 ``<NACL_SDK_ROOT>/lib/newlib_<arch>/<Release or Debug>``
565 and ``<NACL_SDK_ROOT>/lib/glibc_<arch>/<Release or Debug>``.
566 The libraries provided by the SDK allow the application to use Pepper,
567 as well as convenience libraries to simplify porting an application that
568 uses POSIX functions. Here are descriptions of the Pepper libraries provided
571 .. _devcycle-building-nacl-io:
574 Implements the Pepper (PPAPI) C interface. Needed for all applications that
575 use Pepper (even C++ applications).
578 Implements the Pepper (PPAPI) C++ interface. Needed by C++ applications that
582 Implements the Pepper (PPAPI) GLES interface. Needed by applications
583 that use the 3D graphics API.
586 Provides a POSIX layer for NaCl. In particular, the library provides a
587 virtual file system and support for sockets. The virtual file system
588 allows a module to "mount" a given directory tree. Once a module has
589 mounted a file system, it can use standard C library file operations:
590 ``fopen``, ``fread``, ``fwrite``, ``fseek``, and ``fclose``.
591 For more detail, see the header ``include/nacl_io/nacl_io.h``.
592 For an example of how to use nacl_io, see ``examples/demo/nacl_io``.
595 Provides a familiar C programming environment by letting a module have a
596 simple entry point that is registered by ``PPAPI_SIMPLE_REGISTER_MAIN``.
597 The entry point is similar to the standard C ``main()`` function, complete
598 with ``argc`` and ``argv[]`` parameters. For details see
599 ``include/ppapi_simple/ps.h``. For an example of
600 how to use ppapi_simple, ``see examples/tutorial/using_ppapi_simple``.
606 * Since the Native Client toolchains use their own library and header search
607 paths, the tools won't find third-party libraries you use in your
608 non-Native-Client development. If you want to use a specific third-party
609 library for Native Client development, look for it in `naclports
610 <http://code.google.com/p/naclports/>`_, or port the library yourself.
611 * The order in which you list libraries in your build commands is important,
612 since the linker searches and processes libraries in the order in which they
613 are specified. See the \*_LDFLAGS variables in the Makefiles of the SDK
614 examples for the order in which specific libraries should be listed.
619 Some common problems, and how to fix them:
621 "Undefined reference" error
622 ---------------------------
624 An "undefined reference" error may indicate incorrect link order and/or
625 missing libraries. For example, if you leave out ``-lppapi`` when
626 compiling Pepper applications you'll see a series of undefined
629 One common type of "undefined reference" error is with respect to certain
630 system calls, e.g., "undefined reference to 'mkdir'". For security reasons,
631 Native Client does not support a number of system calls. Depending on how
632 your code uses such system calls, you have a few options:
634 #. Link with the ``-lnosys`` flag to provide empty/always-fail versions of
635 unsupported system calls. This will at least get you past the link stage.
636 #. Find and remove use of the unsupported system calls.
637 #. Create your own implementation of the unsupported system calls to do
638 something useful for your application.
640 If your code uses mkdir or other file system calls, you might find the
641 :ref:`nacl_io <devcycle-building-nacl-io>` library useful.
642 The nacl_io library essentially does option (3) for you: It lets your
643 code use POSIX-like file system calls, and implements the calls using
644 various technologies (e.g., HTML5 file system, read-only filesystems that
645 use URL loaders, or an in-memory filesystem).
647 Can't find libraries containing necessary symbols
648 -------------------------------------------------
650 Here is one way to find the appropriate library for a given symbol:
655 <NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin/pnacl-nm -o \
656 toolchain/<platform>_pnacl/usr/lib/*.a | grep <MySymbolName>
659 PNaCl ABI Verification errors
660 -----------------------------
662 PNaCl has restrictions on what is supported in bitcode. There is a bitcode
663 ABI verifier which checks that the application conforms to the ABI restrictions,
664 before it is translated and run in the browser. However, it is best to
665 avoid runtime errors for users, so the verifier also runs on the developer's
666 machine at link time.
668 For example, the following program which uses 128-bit integers
669 would compile with NaCl GCC for the x86-64 target. However, it is not
670 portable and would not compile with NaCl GCC for the i686 target.
671 With PNaCl, it would fail to pass the ABI verifier:
675 typedef unsigned int uint128_t __attribute__((mode(TI)));
677 uint128_t foo(uint128_t x) {
681 With PNaCl you would get the following error at link time:
685 Function foo has disallowed type: i128 (i128)
686 LLVM ERROR: PNaCl ABI verification failed
688 When faced with a PNaCl ABI verification error, check the list of features
689 that are :ref:`not supported by PNaCl <when-to-use-nacl>`.
690 If the problem you face is not listed as restricted,
691 :ref:`let us know <help>`!
693 .. _glibc: http://www.gnu.org/software/libc/
694 .. _newlib: http://sourceware.org/newlib/