Fix incorrect paths.

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

 .. _devcycle-building:
 
 ########
 Building
 ########
 
 .. contents:: Table Of Contents
   :local:
   :backlinks: none
   :depth: 2
@@ skipping 22 matching lines @@
 will run on Windows, Mac OS X, Linux, and ChromeOS and it will run on x86-32,
 x86-64, ARM and MIPS processors.
 
 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.
+includes a script for generating manifest files called ``create_nmf.py``.  This
+script is located in the ``pepper_<version>/tools/``, meaning under your

[JF, 2014/08/15 21:17:08]

in the ... directory

[jpmedley, 2014/08/18 14:58:23]

Done.

+installed pepper bundle. 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.
 
 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
@@ skipping 21 matching lines @@
 ``-std=gnu++11`` command line argument can be used to indicate which C++
 language standard to use (``-std=c++11`` often doesn't work well because newlib
 relies on some GNU extensions).
 
 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*)
+in a directory named ``pepper_<version>/toolchain/<OS_platform>_pnacl``,
+and the GCC-based toolchains are located in directories named
+``pepper_<version>/toolchain/<OS_platform>_<architecture>_<library>``.

[JF, 2014/08/15 21:17:08]

Replace "library" with "c_library" since the definition isn't there.

[jpmedley, 2014/08/18 14:58:23]

Done.

 
 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 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).
 
 SDK toolchains versus your hosted toolchain
 -------------------------------------------
 
 To build NaCl modules, you must use one of the Native Client toolchains
 included in the SDK. The SDK toolchains use a variety of techniques to
 ensure that your NaCl modules comply with the security constraints of
 the Native Client sandbox.
 
 During development, you have another choice: You can build modules using a
@@ skipping 23 matching lines @@
 ===================
 
 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).
 
-Each tool's name is preceded by the prefix "pnacl-". Some of the useful
-tools include:
+Some of the useful tools include:
 
 pnacl-abicheck
-  Check that the **pexe** follows the PNaCl ABI rules.
+  Checks that the **pexe** follows the PNaCl ABI rules.
 pnacl-ar
   Creates archives (i.e., static libraries)
 pnacl-clang
   C compiler and compiler driver
 pnacl-clang++
   C++ compiler and compiler driver
 pnacl-compress
-  Size compresses a finalized **pexe** file for deployment.
+  Compresses a finalized **pexe** file for deployment.
 pnacl-dis
   Disassembler for both **pexe** files and **nexe** files
 pnacl-finalize
   Finalizes **pexe** files for deployment
 pnacl-ld
   Bitcode linker
 pnacl-nm
   Lists symbols in bitcode files, native code, and libraries
 pnacl-ranlib
   Generates a symbol table for archives (i.e., static libraries)
 pnacl-translate
   Translates a **pexe** to a native architecture, outside of the browser
 
 For the full list of tools, see the
-``<NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin`` directory.
+``pepper_<version>/toolchain/<platform>_pnacl/bin`` directory.
 
 Using the PNaCl tools to compile, link, debug, and deploy
 =========================================================
 
 To build an application with the PNaCl SDK toolchain, you must compile
 your code, link it, test and debug it, and then deploy it. This section goes
 over some examples of how to use the tools.
 
 Compile
 -------
 
 To compile a simple application consisting of ``file1.cc`` and ``file2.cc`` into
-``hello_world.pexe`` with a single command, use the ``pnacl-clang++`` tool
+``hello_world.pexe`` use the ``pnacl-clang++`` tool
 
 .. naclcode::
   :prettyprint: 0
 
-  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ file1.cc file2.cc ^
-    -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/pnacl/Release ^
-    -o hello_world.pexe -g -O2 -lppapi_cpp -lppapi
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-clang++ \
+    file1.cc file2.cc -I<NACL_SDK_ROOT>/pepper_<version>/include \
+    -L<NACL_SDK_ROOT>/pepper_<version>/lib/pnacl/Release -o hello_world.pexe \
+    -g -O2 -lppapi_cpp -lppapi
 
-(The carat ``^`` allows the command to span multiple lines on Windows;
-to do the same on Mac and Linux use a backslash instead. Or you can
-simply type the command and all its arguments on one
-line. ``<NACL_SDK_ROOT>`` represents the path to the top-level
-directory of the bundle you are using, e.g.,
-``<location-where-you-installed-the-SDK>/pepper_31``.)
-
-However, the typical application consists of many files. In that case,
+The typical application consists of many files. In that case,
 each file can be compiled separately so that only files that are
 affected by a change need to be recompiled. To compile an individual
 file from your application, you must use either the ``pnacl-clang`` C
 compiler, or the ``pnacl-clang++`` C++ compiler. The compiler produces
 separate bitcode files. For example:
 
 .. naclcode::
   :prettyprint: 0
 
-  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ hello_world.cc ^
-    -I<NACL_SDK_ROOT>/include -c -o hello_world.o -g -O0
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-clang++ \
+    hello_world.cc -I<NACL_SDK_ROOT>/include -c -o hello_world.o -g -O0
 
 For a description of each command line flag, run ``pnacl-clang --help``.
 For convenience, here is a description of some of the flags used in
 the example.
 
 .. _compile_flags:
 
 ``-c``
   indicates that ``pnacl-clang++`` should only compile an individual file,
   rather than continue the build process and link together the
@@ skipping 19 matching lines @@
   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 to
   the server or to the Chrome Web Store. Optimizations that increase the size of
   an uncompressed **pexe** may not increase the size of the compressed **pexe**
   very much. You should also verify how optimization level affects on-device
   translation time, this can be tested locally with ``pnacl-translate``.
 
 ``-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.
+  Pepper (PPAPI) headers located at ``<NACL_SDK_ROOT>/pepper_<version>/
+  include``, so add that directory when compiling to be able to include the
+  headers.
 
 ``-mllvm -inline-threshold=n``
   change how much inlining is performed by LLVM (the default is 225, a smaller
   value will result in less inlining being performed). The right number to
   choose is 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.
 
 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
 
-  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ar cr libfoo.a ^
-    foo1.o foo2.o foo3.o
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-ar cr \
+    libfoo.a foo1.o foo2.o foo3.o
 
-  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a
 
 
 Link the application
 --------------------
 
 The ``pnacl-clang++`` tool is used to compile applications, but it can
 also be used link together compiled bitcode and libraries into a
 full application.
 
 .. naclcode::
   :prettyprint: 0
 
-  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
-    hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Debug ^
+  <NACL_SDK_ROOT>/pepper_<version>/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 ``<NACL_SDK_ROOT>/pepper_<version>/lib/pnacl/Debug``. If you wish to link
+against the *Release* version of the Pepper libraries, change the
+``-L<NACL_SDK_ROOT>/pepper_<version>/lib/pnacl/Debug`` to
+``-L<NACL_SDK_ROOT>/pepper_<version>/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.
 
 .. naclcode::
   :prettyprint: 0
 
-  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe ^
-    hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Release ^
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-clang++ \
+    -o hello_world.pexe hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Release \
     -lfoo -lppapi_cpp -lppapi -O2
 
 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.
 
 .. naclcode::
   :prettyprint: 0
 
-  <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-finalize ^
+  <NACL_SDK_ROOT>/pepper_<version>/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**
 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
@@ skipping 15 matching lines @@
 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,
 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 ^
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-compress \
     hello_world.final.pexe
 
 ``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.
 
 This compression step doesn't replace the gzip compression performed web servers
 configured for HTTP compression: both compressions are complementary. You'll
 want to configure your web server to gzip **pexe** files: the gzipped version of
@@ skipping 58 matching lines @@
 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:
 
 .. 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
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_x86_newlib/bin/i686-nacl-gcc \
+    hello_world.c -I<NACL_SDK_ROOT>/pepper_<version>/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
 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
 ------------------------------
@@ skipping 88 matching lines @@
 for each command.
 
 For details on how to use make, see the `GNU 'make' Manual
 <http://www.gnu.org/software/make/manual/make.html>`_.
 
 Libraries and header files provided with the SDK
 ================================================
 
 The Native Client SDK includes modified versions of standard toolchain-support
 libraries, such as libpthread and libc, plus the relevant header files.
-The standard libraries are located in the following directories:
+The standard libraries are located under the ``/pepper_<version>`` directory
+in the following locations:
 
 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/lib``
 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/lib32`` and
   ``/lib64`` (for the 32-bit and 64-bit target architectures, respectively)
 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/lib``

[JF, 2014/08/15 21:17:08]

Same here on c_library?

[jpmedley, 2014/08/18 14:58:23]

Done. Also did lines 559 and 560, below.

 
 For example, on Windows, the libraries for the x86-64 architecture in the
 newlib toolchain are in ``toolchain/win_x86_newlib/x86_64-nacl/lib64``.
 
 The header files are in:
 
 * PNaCl toolchain: ``toolchain/<platform>_pnacl/usr/include``
 * x86 toolchains: ``toolchain/<platform>_x86_<library>/x86_64-nacl/include``
 * ARM toolchain: ``toolchain/<platform>_arm_<library>/arm-nacl/include``
 
@@ skipping 48 matching lines @@
 .. Note::
   :class: note
 
   * Since the Native Client toolchains use their own library and header search
     paths, the tools won't find third-party libraries you use in your
     non-Native-Client development. If you want to use a specific third-party
     library for Native Client development, look for it in `naclports
     <http://code.google.com/p/naclports/>`_, or port the library yourself.
   * The order in which you list libraries in your build commands is important,
     since the linker searches and processes libraries in the order in which they
-    are specified. See the \*_LDFLAGS variables in the Makefiles of the SDK
+    are specified. See the ``\*_LDFLAGS`` variables in the Makefiles of the SDK
     examples for the order in which specific libraries should be listed.
 
 Troubleshooting
 ===============
 
 Some common problems, and how to fix them:
 
 "Undefined reference" error
 ---------------------------
 
@@ skipping 21 matching lines @@
 use URL loaders, or an in-memory filesystem).
 
 Can't find libraries containing necessary symbols
 -------------------------------------------------
 
 Here is one way to find the appropriate library for a given symbol:
 
 .. naclcode::
   :prettyprint: 0
 
-  <NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin/pnacl-nm -o \
-    toolchain/<platform>_pnacl/usr/lib/*.a | grep <MySymbolName>
+  <NACL_SDK_ROOT>/pepper_<version>/toolchain/<platform>_pnacl/bin/pnacl-nm -o \
+    <NACL_SDK_ROOT>/pepper_<version>toolchain/<platform>_pnacl/usr/lib/*.a | \
+    grep <MySymbolName>
 
 
 PNaCl ABI Verification errors
 -----------------------------
 
 PNaCl has restrictions on what is supported in bitcode. There is a bitcode
 ABI verifier which checks that the application conforms to the ABI restrictions,
 before it is translated and run in the browser. However, it is best to
 avoid runtime errors for users, so the verifier also runs on the developer's
 machine at link time.
@@ skipping 18 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/