[SyncFS] Build indexes from FileTracker entries on disk.
[chromium-blink-merge.git] / native_client_sdk / src / doc / devguide / devcycle / building.rst
blob080e2b87f50210e204cba4ca85d24558f1b793ec
1 .. _devcycle-building:
3 ########
4 Building
5 ########
7 .. contents:: Table Of Contents
8   :local:
9   :backlinks: none
10   :depth: 2
12 Introduction
13 ============
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
19 with those.
21 .. _target_architectures:
23 Target architectures
24 --------------------
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.
51 C libraries
52 -----------
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).
82 SDK toolchains
83 --------------
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
93    *linux*)
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++``.
103 .. Note::
104   :class: note
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
132 Client SDK.
134 .. Note::
135   :class: note
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
140   provided in the SDK.
143 The PNaCl toolchain
144 ===================
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
155 tools include:
157 pnacl-abicheck
158   Check that the **pexe** follows the PNaCl ABI rules.
159 pnacl-ar
160   Creates archives (i.e., static libraries)
161 pnacl-clang
162   C compiler and compiler driver
163 pnacl-clang++
164   C++ compiler and compiler driver
165 pnacl-compress
166   Size compresses a finalized **pexe** file for deployment.
167 pnacl-dis
168   Disassembler for both **pexe** files and **nexe** files
169 pnacl-finalize
170   Finalizes **pexe** files for deployment
171 pnacl-ld
172   Bitcode linker
173 pnacl-nm
174   Lists symbols in bitcode files, native code, and libraries
175 pnacl-ranlib
176   Generates a symbol table for archives (i.e., static libraries)
177 pnacl-translate
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.
190 Compile
191 -------
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
196 .. naclcode::
197   :prettyprint: 0
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:
217 .. naclcode::
218   :prettyprint: 0
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
225 the example.
227 .. _compile_flags:
229 ``-c``
230   indicates that ``pnacl-clang++`` should only compile an individual file,
231   rather than continue the build process and link together the
232   full application.
234 ``-o <output_file>``
235   indicates the **output** filename.
237 ``-g``
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
241   download size small.
243 ``-On``
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``.
259 ``-I<directory>``
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.
278 .. naclcode::
279   :prettyprint: 0
281   <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ar cr libfoo.a ^
282     foo1.o foo2.o foo3.o
284   <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a
287 Link the application
288 --------------------
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
292 full application.
294 .. naclcode::
295   :prettyprint: 0
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.
313 .. naclcode::
314   :prettyprint: 0
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.
336 .. naclcode::
337   :prettyprint: 0
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.
355 .. _pnacl_compress:
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
366 ``pnacl-compress``.
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.
372 .. naclcode::
373   :prettyprint: 0
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
413 **.nexe**.
415 The GNU-based SDK toolchains include the following tools:
417 * <prefix>addr2line
418 * <prefix>ar
419 * <prefix>as
420 * <prefix>c++
421 * <prefix>c++filt
422 * <prefix>cpp
423 * <prefix>g++
424 * <prefix>gcc
425 * <prefix>gcc-4.4.3
426 * <prefix>gccbug
427 * <prefix>gcov
428 * <prefix>gprof
429 * <prefix>ld
430 * <prefix>nm
431 * <prefix>objcopy
432 * <prefix>objdump
433 * <prefix>ranlib
434 * <prefix>readelf
435 * <prefix>size
436 * <prefix>strings
437 * <prefix>strip
440 Compiling
441 ---------
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:
451 .. naclcode::
452   :prettyprint: 0
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.
487 Using make
488 ==========
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
507     the newlib library
508   * generates a Native Client manifest (.nmf) file for the pnacl version of the
509     example
511 * If ``TOOLCHAIN=newlib`` creates a subdirectory called ``newlib``;
513   * builds **.nexes** for the x86-32, x86-64, and ARM architectures using the
514     newlib library
515   * generates a Native Client manifest (.nmf) file for the newlib version of
516     the example
518 * If ``TOOLCHAIN=glibc`` creates a subdirectory called ``glibc``;
520   * builds **.nexes** for the x86-32 and x86-64 architectures using the glibc
521     library
522   * generates a Native Client manifest (.nmf) file for the glibc version of the
523     example
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
534 .. Note::
535   :class: note
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
542 other examples.
544 .. naclcode::
545   :prettyprint: 0
547   set TOOLCHAIN=pnacl
548   set CONFIG=Release
549   make
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
555 for each command.
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
595 in the SDK.
597 .. _devcycle-building-nacl-io:
599 libppapi.a
600   Implements the Pepper (PPAPI) C interface. Needed for all applications that
601   use Pepper (even C++ applications).
603 libppapi_cpp.a
604   Implements the Pepper (PPAPI) C++ interface. Needed by C++ applications that
605   use Pepper.
607 libppapi_gles2.a
608   Implements the Pepper (PPAPI) GLES interface. Needed by applications
609   that use the 3D graphics API.
611 libnacl_io.a
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``.
620 libppapi_simple.a
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``.
629 .. Note::
630   :class: note
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.
642 Troubleshooting
643 ===============
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
653 reference errors.
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:
678 .. naclcode::
679   :prettyprint: 0
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:
699 .. naclcode::
701   typedef unsigned int uint128_t __attribute__((mode(TI)));
703   uint128_t foo(uint128_t x) {
704     return x;
705   }
707 With PNaCl you would get the following error at link time:
709 .. naclcode::
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/