NaCl documentation: improve building documentation

native_client_sdk/src/doc/devguide/devcycle/building.rst

 .. _devcycle-building:
 
 ########
 Building
 ########
 
 .. contents:: Table Of Contents
   :local:
   :backlinks: none
   :depth: 2
@@ skipping 11 matching lines @@
 
 Target architectures
 --------------------
 
 Portable Native Client (PNaCl) modules are written in C or C++ and compiled
 into an executable file ending in a **.pexe** extension using the PNaCl
 toolchain in the Native Client SDK. Chrome can load **pexe** files
 embedded in web pages and execute them as part of a web application.
 
 As explained in the Technical Overview, PNaCl modules are
-operating-system-independent **and** processor-independent. The same
-**pexe**  will run on Windows, Mac, Linux, and ChromeOS and it will run on
-any processor, e.g., x86-32, x86-64, and ARM.
+operating-system-independent **and** processor-independent. The same **pexe**
+will run on Windows, Mac OS X, Linux, and ChromeOS and it will run on processor

[Derek Schuff, 2014/06/24 18:33:42]

did you mean to remove "any" here?
Maybe just say "and it will run on x86-32, x86-64, ARM, and MIPS processors"

[JF, 2014/06/25 01:27:46]

Done.

[Derek Schuff, 2014/06/25 17:27:02]

Now it says "will run on processor x86-32 ..."

[JF, 2014/06/25 17:44:01]

Done.

[binji, 2014/06/25 17:58:15]

processors :)

[JF, 2014/06/25 18:03:04]

Dones.

+such as x86-32, x86-64, ARM and MIPS.
 
 Native Client also supports architecture-specific **nexe** files.
 These **nexe** files are **also** operating-system-independent,
 but they are **not** processor-independent. To support a wide variety of
 devices you must compile separate versions of your Native Client module
 for different processors on end-user machines. A
 :ref:`manifest file <application_files>` will then specify which version
 of the module to load based on the end-user's architecture. The SDK
 includes a script---``create_nmf.py`` (in the ``tools/`` directory)---to
 generate manifest files. For examples of how to compile modules
 for multiple target architectures and how to generate manifest files, see the
 Makefiles included with the SDK examples.
 
 This section will mostly cover PNaCl, but also describes how to build
-nexe applications.
+**nexe** applications.
 
 C libraries
 -----------
 
 The PNaCl SDK has a single choice of C library: newlib_.
 
 The Native Client SDK also has a GCC-based toolchain for building
 **nexes**. The GCC-based toolchain has support for two C libraries:
 newlib_ and glibc_.  See :doc:`Dynamic Linking & Loading with glibc
 <dynamic-loading>` for information about these libraries, including factors to
@@ skipping 10 matching lines @@
 ``-stdlib=[libc++|libstdc++]`` command line argument can be used to
 choose which standard library to use.
 
 The GCC-based Native Client SDK only has support for GCC's `libstdc++
 <http://gcc.gnu.org/libstdc++>`_.
 
 C++11 library support is only complete in libc++ but other non-library
 language features should work regardless of which standard library is
 used. The ``-std=[c++98|c++11]`` command line argument can be used to
 indicate which C++ language standard to use (or ``-std=gnu++11`` to
-access non-standard extensions).
+access non-standard extensions which newlib often relies on).

[Derek Schuff, 2014/06/24 18:33:42]

I assume this is a response to the recent reports about build failures? I wonder
if its worth making gnu++11 the primary recommendation since a lot of code from
the posix world just assumes gnu extensions (including newlib) Similarly to how
the default C and C++ standards are gnu.

[JF, 2014/06/25 01:27:46]

Done.

[Derek Schuff, 2014/06/25 17:27:02]

saying that newlib relies on gnu extensions rather than isn't always compatible
might make it sound a little more positive.

[JF, 2014/06/25 17:44:01]

Done.

 
 SDK toolchains
 --------------
 
 The Native Client SDK includes multiple toolchains. It has one PNaCl toolchain
 and it has multiple GCC-based toolchains that are differentiated by target
 architectures and C libraries. The single PNaCl toolchain is located
 in a directory named ``toolchain/<OS_platform>_pnacl``, and the GCC-based
 toolchains are located in directories named
 ``toolchain/<OS_platform>_<architecture>_<library>``, where:
 
-* *<platform>* is the platform of your development machine (win, mac, or linux)
-* *<architecture>* is your target architecture (x86 or arm)
-* *<library>* is the C library you are compiling with (newlib or glibc)
+* *<platform>* is the platform of your development machine (*win*, *mac*, or
+   *linux*)
+* *<architecture>* is your target architecture (*x86* or *arm*)
+* *<library>* is the C library you are compiling with (*newlib* or *glibc*)
 
 The compilers, linkers, and other tools are located in the ``bin/``
 subdirectory in each toolchain. For example, the tools in the Windows SDK
 for PNaCl has a C++ compiler in ``toolchain/win_pnacl/bin/pnacl-clang++``.
-As another example, the GCC-based C++ compiler that targets the x86 and uses the
+As another example, the GCC-based C++ compiler that targets x86 and uses the
 newlib library, is located at ``toolchain/win_x86_newlib/bin/x86_64-nacl-g++``.
 
 .. Note::
   :class: note
 
   The SDK toolchains descend from the ``toolchain/`` directory. The SDK also
   has a ``tools/`` directory; this directory contains utilities that are not
   properly part of the toolchains but that you may find helpful in building and
   testing your application (e.g., the ``create_nmf.py`` script, which you can
   use to create a manifest file).
@@ skipping 29 matching lines @@
   provided in the SDK.
 
 
 The PNaCl toolchain
 ===================
 
 The PNaCl toolchain contains modified versions of the tools in the
 LLVM toolchain, as well as linkers and other tools from binutils.
 To determine which version of LLVM or binutils the tools are based upon,
 run the tool with the ``--version`` command line flag. These tools
-are used to compile and link applications into .pexe files. The toolchain
-also contains a tool to translate a .pexe file into a
-architecture-specific .nexe (e.g., for debugging purposes).
+are used to compile and link applications into **.pexe** files. The toolchain
+also contains a tool to translate a **pexe** file into a
+architecture-specific **.nexe** (e.g., for debugging purposes).
 
 Each tool's name is preceded by the prefix "pnacl-". Some of the useful
 tools include:
 
 pnacl-abicheck
   Check that the **pexe** follows the PNaCl ABI rules.
 pnacl-ar
   Creates archives (i.e., static libraries)
 pnacl-clang
   C compiler and compiler driver
@@ skipping 71 matching lines @@
 ``-o <output_file>``
   indicates the **output** filename.
 
 ``-g``
   tells the compiler to include debug information in the result.
   This debug information can be used during development, and then **stripped**
   before actually deploying the application to keep the application's
   download size small.
 
 ``-On``
-  sets the optimization level to n. Use 0 when debugging, and -O2 or -O3
-  for profiling and deployment.
+  sets the optimization level to n. Use ``-O0`` when debugging, and ``-O2`` or
+  ``-O3`` for profiling and deployment.

[Derek Schuff, 2014/06/24 18:33:42]

maybe we shouldn't refer to profiling if there's no useful way to actually do
it.

[JF, 2014/06/25 01:27:46]

Done.

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

[Derek Schuff, 2014/06/24 18:33:42]

maybe even make it a little more clear and say "Optimizations that increase the
size of the uncompressed pexe". Also "very much" sounds better than "that much"

[JF, 2014/06/25 01:27:46]

Done.

+  **pexe** that much.
 
 ``-I<directory>``
   adds a directory to the search path for **include** files. The SDK has
   Pepper (PPAPI) headers located at ``<NACL_SDK_ROOT>/include``, so add
   that directory when compiling to be able to include the headers.
 
+``-mllvm -inline-threshold=5``
+  change how much inlining is performed by LLVM. The right number to choose is
+  often application-specific, you'll therefore want to experiment with the value
+  that you pass in: you'll be trading off potential performance with **pexe**
+  size and on-device translation speed.

[Derek Schuff, 2014/06/24 18:33:42]

Mention that the particular value of 5 turns the inliner way down. Not sure if
it's worth mentioning that the default is 225. Maybe even make it 'n' as in On

[binji, 2014/06/24 20:51:47]

Agreed, I wouldn't have guessed the valid range would be so large.

[JF, 2014/06/25 01:27:46]

Done.

 
 Create a static library
 -----------------------
 
 The ``pnacl-ar`` and ``pnacl-ranlib`` tools allow you to create a
 **static** library from a set of bitcode files, which can later be linked
 into the full application.
 
 .. naclcode::
   :prettyprint: 0
@@ skipping 17 matching lines @@
   <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
     hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Debug -lfoo -lppapi_cpp -lppapi
 
 This links the hello world bitcode with the ``foo`` library in the example
 as well as the *Debug* version of the Pepper libraries which are located
 in ``<NACL_SDK_ROOT>/lib/pnacl/Debug``. If you wish to link against the
 *Release* version of the Pepper libraries, change the
 ``-L<NACL_SDK_ROOT>/lib/pnacl/Debug`` to
 ``-L<NACL_SDK_ROOT>/lib/pnacl/Release``.
 
+In a release build you'll want to pass ``-O2`` to the compiler *as well as to
+the linker* to enable link-time optimizations. This reduces the size and
+increases the performance of the final **pexe**, and leads to faster downloads
+and on-device translation.

[binji, 2014/06/24 20:51:47]

We have an example link line for debug, maybe it would be good to add one for
release too (including -O2)

[JF, 2014/06/25 01:27:47]

Done.

+
+By default the link step will turn all C++ exceptions into calls to ``abort()``
+to reduce the size of the final **pexe** as well as making it translate and run
+faster. If you want to use C++ exceptions you should use the
+``--pnacl-exceptions=sjlj`` linker flag as explained in the :ref:`exception
+handling <exception_handling>` section of the C++ language support reference.
+
 
 Finalizing the **pexe** for deployment
 --------------------------------------
 
-Typically you would run the application to test it and debug it if needed
-before deploying. See the :doc:`running <running>` documentation for how
-to run a PNaCl application, and see the :doc:`debugging <debugging>`
-documentation for debugging techniques and workflow. After testing a PNaCl
-application, you must **"finalize"** it. The ``pnacl-finalize``
-tool handles this.
+Typically you would run the application to test it and debug it if needed before
+deploying. See the :doc:`running <running>` documentation for how to run a PNaCl
+application, and see the :doc:`debugging <debugging>` documentation for
+debugging techniques and workflow. After testing a PNaCl application, you must
+**finalize** it. The ``pnacl-finalize`` tool handles this.
 
 .. naclcode::
   :prettyprint: 0
 
   <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-finalize ^
     hello_world.pexe -o hello_world.final.pexe
 
 Prior to finalization, the application **pexe** is stored in a binary
 format that is subject to change.  After finalization, the application
-pexe is **rewritten** into a different binary format that is **stable**
+**pexe** is **rewritten** into a different binary format that is **stable**
 and will be supported by future versions of PNaCl. The finalization step
 also helps minimize the size of your application for distribution by
 stripping out debug information and other metadata.
 
 Once the application is finalized, be sure to adjust the manifest file to
 refer to the final version of the application before deployment.
 The ``create_nmf.py`` tool helps generate an ``.nmf`` file, but ``.nmf``
 files can also be written by hand.
 
 
 .. _pnacl_compress:
 
 Compressing the **pexe** for deployment
 ---------------------------------------
 
 Size compression is an optional step for deployment, and reduces the
-size of the pexe file that must be transmitted over the wire. The tool
+size of the **pexe** file that must be transmitted over the wire. The tool
 ``pnacl-compress`` applies compression strategies that are already built
-into the **stable** binary format of a pexe application. As such,
-compressed pexe files do not need any extra time to be decompressed on
+into the **stable** binary format of a **pexe** application. As such,
+compressed **pexe** files do not need any extra time to be decompressed on
 the client's side. All costs are upfront when you call ``pnacl-compress``.
 
-Currently, this tool will compress pexe files by about 25%. However,
+Currently, this tool will compress **pexe** files by about 25%. However,
 it is somewhat slow (can take from seconds to minutes on large
 appications). Hence, this step is optional.
 
 .. naclcode::
   :prettyprint: 0
 
   <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-compress ^
     hello_world.final.pexe
 
-Tool ``pnacl-compress`` must be called after a pexe file has been finalized
+Tool ``pnacl-compress`` must be called after a **pexe** file has been finalized
 for deployment (via ``pnacl-finalize``). Alternatively, you can apply this
 step as part of the finalizing step by adding the ``--compress`` flag
-to the pnacl-finalize command line.
+to the ``pnacl-finalize`` command line.
 
-Note that this compression step doesn't replace gzip. This compression
-step is in addition to gzipping a file for deployment. One should note
-that while the gzipped version of a compressed pexe file is still
-smaller than the corresponding uncompressed pexe file, the gains is
-somewhat smaller after being gzipped. Expected reduction in size
-(after being gzipped) is more like 7.5% to 10%.
+Note that this compression step doesn't replace the gzip compression performed
+by most web servers as part of HTTP compression. This compression step is in

[Derek Schuff, 2014/06/24 18:33:42]

This seems to imply that the compression is automatic, although the next
sentence implies that gzipping for deployment is something the developer would
do. I guess it depends on the server configuration, maybe we could make that
more clear.

[JF, 2014/06/25 01:27:47]

Done.

+addition to gzipping a file for deployment. One should note that while the
+gzipped version of a compressed **pexe** file is still smaller than the
+corresponding uncompressed **pexe** file, the gains is somewhat smaller after
+being gzipped. Expected reduction in size (after being gzipped) is closer to
+7.5% to 10%.
 
 The GNU-based toolchains
 ========================
 
 Besides the PNaCl toolchain, the Native Client SDK also includes modified
 versions of the tools in the standard GNU toolchain, including the GCC
 compilers and the linkers and other tools from binutils. These tools only
 support building **nexe** files. Run the tool with the ``--version``
 command line flag to determine the current version of the tools.
 
 Each tool in the toolchain is prefixed with the name of the target
 architecture. In the toolchain for the ARM target architecture, each
 tool's name is preceded by the prefix "arm-nacl-". In the toolchains for
 the x86 target architecture, there are actually two versions of each
 tool---one to build Native Client modules for the x86-32
 target architecture, and one to build modules for the x86-64 target
 architecture. "i686-nacl-" is the prefix for tools used to build
-32-bit .nexes, and "x86_64-nacl-" is the prefix for tools used to
-build 64-bit .nexes
+32-bit **.nexes**, and "x86_64-nacl-" is the prefix for tools used to
+build 64-bit **.nexes**.
 
 These prefixes conform to gcc naming standards and make it easy to use tools
 like autoconf. As an example, you can use ``i686-nacl-gcc`` to compile 32-bit
-.nexes, and ``x86_64-nacl-gcc`` to compile 64-bit .nexes. Note that you can
-typically override a tool's default target architecture with command line
+**.nexes**, and ``x86_64-nacl-gcc`` to compile 64-bit **.nexes**. Note that you
+can typically override a tool's default target architecture with command line
 flags, e.g., you can specify ``x86_64-nacl-gcc -m32`` to compile a 32-bit
-.nexe.
+**.nexe**.
 
 The GNU-based SDK toolchains include the following tools:
 
 * <prefix>addr2line
 * <prefix>ar
 * <prefix>as
 * <prefix>c++
 * <prefix>c++filt
 * <prefix>cpp
 * <prefix>g++
@@ skipping 14 matching lines @@
 
 
 Compiling
 ---------
 
 Compiling files with the GNU-based toolchain is similar to compiling
 files with the PNaCl-based toolchain, except that the output is
 architecture specific.
 
 For example, assuming you're developing on a Windows machine, targeting the x86
-architecture, and using the newlib library, you can compile a 32-bit .nexe for
-the hello_world example with the following command:
+architecture, and using the newlib library, you can compile a 32-bit **.nexe**
+for the hello_world example with the following command:
 
 .. naclcode::
   :prettyprint: 0
 
   <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/i686-nacl-gcc hello_world.c ^
     -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/newlib/Release ^
     -o hello_world_x86_32.nexe -m32 -g -O2 -lppapi
 
-To compile a 64-bit .nexe, you can run the same command but use -m64 instead of
--m32. Alternatively, you could also use the version of the compiler that
+To compile a 64-bit **.nexe**, you can run the same command but use -m64 instead
+of -m32. Alternatively, you could also use the version of the compiler that
 targets the x86-64 architecture, i.e., ``x86_64-nacl-gcc``.
 
 You should name executable modules with a **.nexe** filename extension,
 regardless of what platform you're using.
 
 Creating libraries and Linking
 ------------------------------
 
 Creating libraries and linking with the GNU-based toolchain is similar
 to doing the same with the PNaCl toolchain.  The relevant tools
 for creating **static** libraries are ``<prefix>ar`` and ``<prefix>ranlib``.
 Linking can be done with ``<prefix>g++``. See the
 :doc:`Dynamic Linking & Loading with glibc <dynamic-loading>`
 section on how to create **shared** libraries.
 
 
 Finalizing a **nexe** for deployment
 ------------------------------------
 
 Unlike the PNaCl toolchain, no separate finalization step is required
-for **nexe** files. The nexe files are always in a **stable** format.
-However, the nexe file may contain debug information and symbol information
-which may make the nexe file larger than needed for distribution.
+for **nexe** files. The **nexe** files are always in a **stable** format.
+However, the **nexe** file may contain debug information and symbol information
+which may make the **nexe** file larger than needed for distribution.
 To minimize the size of the distributed file, you can run the
 ``<prefix>strip`` tool to strip out debug information.
 
 
 Using make
 ==========
 
 This document doesn't cover how to use ``make``, but if you want to use
 ``make`` to build your Native Client module, you can base your Makefile on the
 ones in the SDK examples.
 
 The Makefiles for the SDK examples build most of the examples in multiple
 configurations (using PNaCl vs NaCl, using different C libraries,
 targeting different architectures, and using different levels of optimization).
 To select a specific toolchain, set the **environment variable**
 ``TOOLCHAIN`` to either ``pnacl``, ``newlib``, ``glibc``, or ``host``.
 To select a specific level of optimization set the **environment
 variable** ``CONFIG`` to either ``Debug``, or ``Release``. Running
 ``make`` in each example's directory does **one** of the following,
 depending on the setting of the environment variables.
 
 * If ``TOOLCHAIN=pnacl`` creates a subdirectory called ``pnacl``;
 
-  * builds a .pexe (architecture-independent Native Client executable) using
+  * builds a **.pexe** (architecture-independent Native Client executable) using
     the newlib library
   * generates a Native Client manifest (.nmf) file for the pnacl version of the
     example
 
 * If ``TOOLCHAIN=newlib`` creates a subdirectory called ``newlib``;
 
-  * builds .nexes for the x86-32, x86-64, and ARM architectures using the
+  * builds **.nexes** for the x86-32, x86-64, and ARM architectures using the
     newlib library
   * generates a Native Client manifest (.nmf) file for the newlib version of
     the example
 
 * If ``TOOLCHAIN=glibc`` creates a subdirectory called ``glibc``;
 
-  * builds .nexes for the x86-32 and x86-64 architectures using the glibc
+  * builds **.nexes** for the x86-32 and x86-64 architectures using the glibc
     library
   * generates a Native Client manifest (.nmf) file for the glibc version of the
     example
 
 * If ``TOOLCHAIN=host`` creates a subdirectory called ``windows``, ``linux``,
   or ``mac`` (depending on your development machine);
 
   * builds a Pepper plugin (.dll for Windows, .so for Linux/Mac) using the
     hosted toolchain on your development machine
   * generates a Native Client manifest (.nmf) file for the host Pepper plugin
@@ skipping 180 matching lines @@
   Function foo has disallowed type: i128 (i128)
   LLVM ERROR: PNaCl ABI verification failed
 
 When faced with a PNaCl ABI verification error, check the list of features
 that are :ref:`not supported by PNaCl <when-to-use-nacl>`.
 If the problem you face is not listed as restricted,
 :ref:`let us know <help>`!
 
 .. _glibc: http://www.gnu.org/software/libc/
 .. _newlib: http://sourceware.org/newlib/