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 **pexe**
33 will run on Windows, Mac OS X, Linux, and ChromeOS and it will run on x86-32,
34 x86-64, ARM and MIPS processors.
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
49 **nexe** applications.
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 language
77 features should work regardless of which standard library is used. The
78 ``-std=gnu++11`` command line argument can be used to indicate which C++
79 language standard to use (``-std=c++11`` often doesn't work well because newlib
80 relies on some GNU 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
94 * *<architecture>* is your target architecture (*x86* or *arm*)
95 * *<library>* is the C library you are compiling with (*newlib* or *glibc*)
97 The compilers, linkers, and other tools are located in the ``bin/``
98 subdirectory in each toolchain. For example, the tools in the Windows SDK
99 for PNaCl has a C++ compiler in ``toolchain/win_pnacl/bin/pnacl-clang++``.
100 As another example, the GCC-based C++ compiler that targets x86 and uses the
101 newlib library, is located at ``toolchain/win_x86_newlib/bin/x86_64-nacl-g++``.
106 The SDK toolchains descend from the ``toolchain/`` directory. The SDK also
107 has a ``tools/`` directory; this directory contains utilities that are not
108 properly part of the toolchains but that you may find helpful in building and
109 testing your application (e.g., the ``create_nmf.py`` script, which you can
110 use to create a manifest file).
112 SDK toolchains versus your hosted toolchain
113 -------------------------------------------
115 To build NaCl modules, you must use one of the Native Client toolchains
116 included in the SDK. The SDK toolchains use a variety of techniques to
117 ensure that your NaCl modules comply with the security constraints of
118 the Native Client sandbox.
120 During development, you have another choice: You can build modules using a
121 *standard* toolchain, such as the hosted toolchain on your development
122 machine. This can be Visual Studio's standard compiler, XCode, LLVM, or
123 GNU-based compilers on your development machine. These standard toolchains
124 will not produce executables that comply with the Native Client sandbox
125 security constraints. They are also not portable across operating systems
126 and not portable across different processors. However, using a standard
127 toolchain allows you to develop modules in your favorite IDE and use
128 your favorite debugging and profiling tools. The drawback is that modules
129 compiled in this manner can only run as Pepper (PPAPI) plugins in Chrome.
130 To publish and distribute Native Client modules as part of a web
131 application, you must eventually use a toolchain in the Native
137 In the future, additional tools will be available to compile Native Client
138 modules written in other programming languages, such as C#. But this
139 document covers only compiling C and C++ code, using the toolchains
146 The PNaCl toolchain contains modified versions of the tools in the
147 LLVM toolchain, as well as linkers and other tools from binutils.
148 To determine which version of LLVM or binutils the tools are based upon,
149 run the tool with the ``--version`` command line flag. These tools
150 are used to compile and link applications into **.pexe** files. The toolchain
151 also contains a tool to translate a **pexe** file into a
152 architecture-specific **.nexe** (e.g., for debugging purposes).
154 Each tool's name is preceded by the prefix "pnacl-". Some of the useful
158 Check that the **pexe** follows the PNaCl ABI rules.
160 Creates archives (i.e., static libraries)
162 C compiler and compiler driver
164 C++ compiler and compiler driver
166 Size compresses a finalized **pexe** file for deployment.
168 Disassembler for both **pexe** files and **nexe** files
170 Finalizes **pexe** files for deployment
174 Lists symbols in bitcode files, native code, and libraries
176 Generates a symbol table for archives (i.e., static libraries)
178 Translates a **pexe** to a native architecture, outside of the browser
180 For the full list of tools, see the
181 ``<NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin`` directory.
183 Using the PNaCl tools to compile, link, debug, and deploy
184 =========================================================
186 To build an application with the PNaCl SDK toolchain, you must compile
187 your code, link it, test and debug it, and then deploy it. This section goes
188 over some examples of how to use the tools.
193 To compile a simple application consisting of ``file1.cc`` and ``file2.cc`` into
194 ``hello_world.pexe`` with a single command, use the ``pnacl-clang++`` tool
199 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ file1.cc file2.cc ^
200 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/pnacl/Release ^
201 -o hello_world.pexe -g -O2 -lppapi_cpp -lppapi
203 (The carat ``^`` allows the command to span multiple lines on Windows;
204 to do the same on Mac and Linux use a backslash instead. Or you can
205 simply type the command and all its arguments on one
206 line. ``<NACL_SDK_ROOT>`` represents the path to the top-level
207 directory of the bundle you are using, e.g.,
208 ``<location-where-you-installed-the-SDK>/pepper_31``.)
210 However, the typical application consists of many files. In that case,
211 each file can be compiled separately so that only files that are
212 affected by a change need to be recompiled. To compile an individual
213 file from your application, you must use either the ``pnacl-clang`` C
214 compiler, or the ``pnacl-clang++`` C++ compiler. The compiler produces
215 separate bitcode files. For example:
220 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ hello_world.cc ^
221 -I<NACL_SDK_ROOT>/include -c -o hello_world.o -g -O0
223 For a description of each command line flag, run ``pnacl-clang --help``.
224 For convenience, here is a description of some of the flags used in
230 indicates that ``pnacl-clang++`` should only compile an individual file,
231 rather than continue the build process and link together the
235 indicates the **output** filename.
238 tells the compiler to include debug information in the result.
239 This debug information can be used during development, and then **stripped**
240 before actually deploying the application to keep the application's
244 sets the optimization level to n. Use ``-O0`` when debugging, and ``-O2`` or
245 ``-O3`` for deployment.
247 The main difference between ``-O2`` and ``-O3`` is whether the compiler
248 performs optimizations that involve a space-speed tradeoff. It could be the
249 case that ``-O3`` optimizations are not desirable due to increased **pexe**
250 download size; you should make your own performance measurements to determine
251 which level of optimization is right for you. When looking at code size, note
252 that what you generally care about is not the size of the **pexe** produced by
253 ``pnacl-clang``, but the size of the compressed **pexe** that you upload to
254 the server or to the Chrome Web Store. Optimizations that increase the size of
255 an uncompressed **pexe** may not increase the size of the compressed **pexe**
256 very much. You should also verify how optimization level affects on-device
257 translation time, this can be tested locally with ``pnacl-translate``.
260 adds a directory to the search path for **include** files. The SDK has
261 Pepper (PPAPI) headers located at ``<NACL_SDK_ROOT>/include``, so add
262 that directory when compiling to be able to include the headers.
264 ``-mllvm -inline-threshold=n``
265 change how much inlining is performed by LLVM (the default is 225, a smaller
266 value will result in less inlining being performed). The right number to
267 choose is application-specific, you'll therefore want to experiment with the
268 value that you pass in: you'll be trading off potential performance with
269 **pexe** size and on-device translation speed.
271 Create a static library
272 -----------------------
274 The ``pnacl-ar`` and ``pnacl-ranlib`` tools allow you to create a
275 **static** library from a set of bitcode files, which can later be linked
276 into the full application.
281 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ar cr libfoo.a ^
284 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a
290 The ``pnacl-clang++`` tool is used to compile applications, but it can
291 also be used link together compiled bitcode and libraries into a
297 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
298 hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Debug ^
299 -lfoo -lppapi_cpp -lppapi
301 This links the hello world bitcode with the ``foo`` library in the example
302 as well as the *Debug* version of the Pepper libraries which are located
303 in ``<NACL_SDK_ROOT>/lib/pnacl/Debug``. If you wish to link against the
304 *Release* version of the Pepper libraries, change the
305 ``-L<NACL_SDK_ROOT>/lib/pnacl/Debug`` to
306 ``-L<NACL_SDK_ROOT>/lib/pnacl/Release``.
308 In a release build you'll want to pass ``-O2`` to the compiler *as well as to
309 the linker* to enable link-time optimizations. This reduces the size and
310 increases the performance of the final **pexe**, and leads to faster downloads
311 and on-device translation.
316 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
317 hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Release ^
318 -lfoo -lppapi_cpp -lppapi -O2
320 By default the link step will turn all C++ exceptions into calls to ``abort()``
321 to reduce the size of the final **pexe** as well as making it translate and run
322 faster. If you want to use C++ exceptions you should use the
323 ``--pnacl-exceptions=sjlj`` linker flag as explained in the :ref:`exception
324 handling <exception_handling>` section of the C++ language support reference.
327 Finalizing the **pexe** for deployment
328 --------------------------------------
330 Typically you would run the application to test it and debug it if needed before
331 deploying. See the :doc:`running <running>` documentation for how to run a PNaCl
332 application, and see the :doc:`debugging <debugging>` documentation for
333 debugging techniques and workflow. After testing a PNaCl application, you must
334 **finalize** it. The ``pnacl-finalize`` tool handles this.
339 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-finalize ^
340 hello_world.pexe -o hello_world.final.pexe
342 Prior to finalization, the application **pexe** is stored in a binary
343 format that is subject to change. After finalization, the application
344 **pexe** is **rewritten** into a different binary format that is **stable**
345 and will be supported by future versions of PNaCl. The finalization step
346 also helps minimize the size of your application for distribution by
347 stripping out debug information and other metadata.
349 Once the application is finalized, be sure to adjust the manifest file to
350 refer to the final version of the application before deployment.
351 The ``create_nmf.py`` tool helps generate an ``.nmf`` file, but ``.nmf``
352 files can also be written by hand.
357 Compressing the **pexe** for deployment
358 ---------------------------------------
360 Size compression is an optional step for deployment, and reduces the size of the
361 **pexe** file that must be transmitted over the wire, resulting in faster
362 download speed. The tool ``pnacl-compress`` applies compression strategies that
363 are already built into the **stable** binary format of a **pexe**
364 application. As such, compressed **pexe** files do not need any extra time to be
365 decompressed on the client's side. All costs are upfront when you call
368 Currently, this tool will compress **pexe** files by about 25%. However,
369 it is somewhat slow (can take from seconds to minutes on large
370 appications). Hence, this step is optional.
375 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-compress ^
376 hello_world.final.pexe
378 ``pnacl-compress`` must be called after a **pexe** file has been finalized for
379 deployment (via ``pnacl-finalize``). Alternatively, you can apply this step as
380 part of the finalizing step by adding the ``--compress`` flag to the
381 ``pnacl-finalize`` command line.
383 This compression step doesn't replace the gzip compression performed web servers
384 configured for HTTP compression: both compressions are complementary. You'll
385 want to configure your web server to gzip **pexe** files: the gzipped version of
386 a compressed **pexe** file is smaller than the corresponding uncompressed
387 **pexe** file by 7.5% to 10%.
389 The GNU-based toolchains
390 ========================
392 Besides the PNaCl toolchain, the Native Client SDK also includes modified
393 versions of the tools in the standard GNU toolchain, including the GCC
394 compilers and the linkers and other tools from binutils. These tools only
395 support building **nexe** files. Run the tool with the ``--version``
396 command line flag to determine the current version of the tools.
398 Each tool in the toolchain is prefixed with the name of the target
399 architecture. In the toolchain for the ARM target architecture, each
400 tool's name is preceded by the prefix "arm-nacl-". In the toolchains for
401 the x86 target architecture, there are actually two versions of each
402 tool---one to build Native Client modules for the x86-32
403 target architecture, and one to build modules for the x86-64 target
404 architecture. "i686-nacl-" is the prefix for tools used to build
405 32-bit **.nexes**, and "x86_64-nacl-" is the prefix for tools used to
406 build 64-bit **.nexes**.
408 These prefixes conform to gcc naming standards and make it easy to use tools
409 like autoconf. As an example, you can use ``i686-nacl-gcc`` to compile 32-bit
410 **.nexes**, and ``x86_64-nacl-gcc`` to compile 64-bit **.nexes**. Note that you
411 can typically override a tool's default target architecture with command line
412 flags, e.g., you can specify ``x86_64-nacl-gcc -m32`` to compile a 32-bit
415 The GNU-based SDK toolchains include the following tools:
443 Compiling files with the GNU-based toolchain is similar to compiling
444 files with the PNaCl-based toolchain, except that the output is
445 architecture specific.
447 For example, assuming you're developing on a Windows machine, targeting the x86
448 architecture, and using the newlib library, you can compile a 32-bit **.nexe**
449 for the hello_world example with the following command:
454 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/i686-nacl-gcc hello_world.c ^
455 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/newlib/Release ^
456 -o hello_world_x86_32.nexe -m32 -g -O2 -lppapi
458 To compile a 64-bit **.nexe**, you can run the same command but use -m64 instead
459 of -m32. Alternatively, you could also use the version of the compiler that
460 targets the x86-64 architecture, i.e., ``x86_64-nacl-gcc``.
462 You should name executable modules with a **.nexe** filename extension,
463 regardless of what platform you're using.
465 Creating libraries and Linking
466 ------------------------------
468 Creating libraries and linking with the GNU-based toolchain is similar
469 to doing the same with the PNaCl toolchain. The relevant tools
470 for creating **static** libraries are ``<prefix>ar`` and ``<prefix>ranlib``.
471 Linking can be done with ``<prefix>g++``. See the
472 :doc:`Dynamic Linking & Loading with glibc <dynamic-loading>`
473 section on how to create **shared** libraries.
476 Finalizing a **nexe** for deployment
477 ------------------------------------
479 Unlike the PNaCl toolchain, no separate finalization step is required
480 for **nexe** files. The **nexe** files are always in a **stable** format.
481 However, the **nexe** file may contain debug information and symbol information
482 which may make the **nexe** file larger than needed for distribution.
483 To minimize the size of the distributed file, you can run the
484 ``<prefix>strip`` tool to strip out debug information.
490 This document doesn't cover how to use ``make``, but if you want to use
491 ``make`` to build your Native Client module, you can base your Makefile on the
492 ones in the SDK examples.
494 The Makefiles for the SDK examples build most of the examples in multiple
495 configurations (using PNaCl vs NaCl, using different C libraries,
496 targeting different architectures, and using different levels of optimization).
497 To select a specific toolchain, set the **environment variable**
498 ``TOOLCHAIN`` to either ``pnacl``, ``newlib``, ``glibc``, or ``host``.
499 To select a specific level of optimization set the **environment
500 variable** ``CONFIG`` to either ``Debug``, or ``Release``. Running
501 ``make`` in each example's directory does **one** of the following,
502 depending on the setting of the environment variables.
504 * If ``TOOLCHAIN=pnacl`` creates a subdirectory called ``pnacl``;
506 * builds a **.pexe** (architecture-independent Native Client executable) using
508 * generates a Native Client manifest (.nmf) file for the pnacl version of the
511 * If ``TOOLCHAIN=newlib`` creates a subdirectory called ``newlib``;
513 * builds **.nexes** for the x86-32, x86-64, and ARM architectures using the
515 * generates a Native Client manifest (.nmf) file for the newlib version of
518 * If ``TOOLCHAIN=glibc`` creates a subdirectory called ``glibc``;
520 * builds **.nexes** for the x86-32 and x86-64 architectures using the glibc
522 * generates a Native Client manifest (.nmf) file for the glibc version of the
525 * If ``TOOLCHAIN=host`` creates a subdirectory called ``windows``, ``linux``,
526 or ``mac`` (depending on your development machine);
528 * builds a Pepper plugin (.dll for Windows, .so for Linux/Mac) using the
529 hosted toolchain on your development machine
530 * generates a Native Client manifest (.nmf) file for the host Pepper plugin
531 version of the example
537 The glibc library is not yet available for the ARM and PNaCl toolchains.
539 Here is how to build the examples with PNaCl in Release mode on Windows.
540 The resulting files for ``examples/api/audio`` will be in
541 ``examples/api/audio/pnacl/Release``, and the directory layout is similar for
551 Your Makefile can be simpler since you will not likely want to build so many
552 different configurations of your module. The example Makefiles define
553 numerous variables near the top (e.g., ``CFLAGS``) that make it easy
554 to customize the commands that are executed for your project and the options
557 For details on how to use make, see the `GNU 'make' Manual
558 <http://www.gnu.org/software/make/manual/make.html>`_.
560 Libraries and header files provided with the SDK
561 ================================================
563 The Native Client SDK includes modified versions of standard toolchain-support
564 libraries, such as libpthread and libc, plus the relevant header files.
565 The standard libraries are located in the following directories:
567 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/lib``
568 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/lib32`` and
569 ``/lib64`` (for the 32-bit and 64-bit target architectures, respectively)
570 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/lib``
572 For example, on Windows, the libraries for the x86-64 architecture in the
573 newlib toolchain are in ``toolchain/win_x86_newlib/x86_64-nacl/lib64``.
575 The header files are in:
577 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/include``
578 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/include``
579 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/include``
581 Many other libraries have been ported for use with Native Client; for more
582 information, see the `naclports <http://code.google.com/p/naclports/>`_
583 project. If you port an open-source library for your own use, we recommend
584 adding it to naclports.
586 Besides the standard libraries, the SDK includes Pepper libraries.
587 The PNaCl Pepper libraries are located in the the
588 ``<NACL_SDK_ROOT>/lib/pnacl/<Release or Debug>`` directory.
589 The GNU-based toolchain has Pepper libraries in
590 ``<NACL_SDK_ROOT>/lib/newlib_<arch>/<Release or Debug>``
591 and ``<NACL_SDK_ROOT>/lib/glibc_<arch>/<Release or Debug>``.
592 The libraries provided by the SDK allow the application to use Pepper,
593 as well as convenience libraries to simplify porting an application that
594 uses POSIX functions. Here are descriptions of the Pepper libraries provided
597 .. _devcycle-building-nacl-io:
600 Implements the Pepper (PPAPI) C interface. Needed for all applications that
601 use Pepper (even C++ applications).
604 Implements the Pepper (PPAPI) C++ interface. Needed by C++ applications that
608 Implements the Pepper (PPAPI) GLES interface. Needed by applications
609 that use the 3D graphics API.
612 Provides a POSIX layer for NaCl. In particular, the library provides a
613 virtual file system and support for sockets. The virtual file system
614 allows a module to "mount" a given directory tree. Once a module has
615 mounted a file system, it can use standard C library file operations:
616 ``fopen``, ``fread``, ``fwrite``, ``fseek``, and ``fclose``.
617 For more detail, see the header ``include/nacl_io/nacl_io.h``.
618 For an example of how to use nacl_io, see ``examples/demo/nacl_io_demo``.
621 Provides a familiar C programming environment by letting a module have a
622 simple entry point that is registered by ``PPAPI_SIMPLE_REGISTER_MAIN``.
623 The entry point is similar to the standard C ``main()`` function, complete
624 with ``argc`` and ``argv[]`` parameters. For details see
625 ``include/ppapi_simple/ps.h``. For an example of
626 how to use ppapi_simple, ``see examples/tutorial/using_ppapi_simple``.
632 * Since the Native Client toolchains use their own library and header search
633 paths, the tools won't find third-party libraries you use in your
634 non-Native-Client development. If you want to use a specific third-party
635 library for Native Client development, look for it in `naclports
636 <http://code.google.com/p/naclports/>`_, or port the library yourself.
637 * The order in which you list libraries in your build commands is important,
638 since the linker searches and processes libraries in the order in which they
639 are specified. See the \*_LDFLAGS variables in the Makefiles of the SDK
640 examples for the order in which specific libraries should be listed.
645 Some common problems, and how to fix them:
647 "Undefined reference" error
648 ---------------------------
650 An "undefined reference" error may indicate incorrect link order and/or
651 missing libraries. For example, if you leave out ``-lppapi`` when
652 compiling Pepper applications you'll see a series of undefined
655 One common type of "undefined reference" error is with respect to certain
656 system calls, e.g., "undefined reference to 'mkdir'". For security reasons,
657 Native Client does not support a number of system calls. Depending on how
658 your code uses such system calls, you have a few options:
660 #. Link with the ``-lnosys`` flag to provide empty/always-fail versions of
661 unsupported system calls. This will at least get you past the link stage.
662 #. Find and remove use of the unsupported system calls.
663 #. Create your own implementation of the unsupported system calls to do
664 something useful for your application.
666 If your code uses mkdir or other file system calls, you might find the
667 :ref:`nacl_io <devcycle-building-nacl-io>` library useful.
668 The nacl_io library essentially does option (3) for you: It lets your
669 code use POSIX-like file system calls, and implements the calls using
670 various technologies (e.g., HTML5 file system, read-only filesystems that
671 use URL loaders, or an in-memory filesystem).
673 Can't find libraries containing necessary symbols
674 -------------------------------------------------
676 Here is one way to find the appropriate library for a given symbol:
681 <NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin/pnacl-nm -o \
682 toolchain/<platform>_pnacl/usr/lib/*.a | grep <MySymbolName>
685 PNaCl ABI Verification errors
686 -----------------------------
688 PNaCl has restrictions on what is supported in bitcode. There is a bitcode
689 ABI verifier which checks that the application conforms to the ABI restrictions,
690 before it is translated and run in the browser. However, it is best to
691 avoid runtime errors for users, so the verifier also runs on the developer's
692 machine at link time.
694 For example, the following program which uses 128-bit integers
695 would compile with NaCl GCC for the x86-64 target. However, it is not
696 portable and would not compile with NaCl GCC for the i686 target.
697 With PNaCl, it would fail to pass the ABI verifier:
701 typedef unsigned int uint128_t __attribute__((mode(TI)));
703 uint128_t foo(uint128_t x) {
707 With PNaCl you would get the following error at link time:
711 Function foo has disallowed type: i128 (i128)
712 LLVM ERROR: PNaCl ABI verification failed
714 When faced with a PNaCl ABI verification error, check the list of features
715 that are :ref:`not supported by PNaCl <when-to-use-nacl>`.
716 If the problem you face is not listed as restricted,
717 :ref:`let us know <help>`!
719 .. _glibc: http://www.gnu.org/software/libc/
720 .. _newlib: http://sourceware.org/newlib/