native_client_sdk/doc_generated/devguide/devcycle/building.html - Issue 479623002: Fix incorrect paths.

Unified Diff: native_client_sdk/doc_generated/devguide/devcycle/building.html

Issue 479623002: Fix incorrect paths. (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master

Patch Set: Created 6 years, 4 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

« native_client_sdk/doc_generated/_static/pygments.css ('K') | « native_client_sdk/doc_generated/community/index.html ('k') | native_client_sdk/doc_generated/devguide/devcycle/running.html » ('j') | native_client_sdk/src/doc/devguide/devcycle/building.rst » ('J')
Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

Index: native_client_sdk/doc_generated/devguide/devcycle/building.html

diff --git a/native_client_sdk/doc_generated/devguide/devcycle/building.html b/native_client_sdk/doc_generated/devguide/devcycle/building.html

index 93b307ce76ad88cbebfb5911b3b76d0e17075e21..4624ab755e37d2d8e8a617803e249e372c90fabc 100644

--- a/native_client_sdk/doc_generated/devguide/devcycle/building.html

+++ b/native_client_sdk/doc_generated/devguide/devcycle/building.html

@@ -63,10 +63,11 @@ devices you must compile separate versions of your Native Client module

for different processors on end-user machines. A

<a class="reference internal" href="/native-client/overview.html#application-files">manifest file</a> will then specify which version

of the module to load based on the end-user’s architecture. The SDK

-includes a script—<code>create_nmf.py</code> (in the <code>tools/</code> 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 <code>create_nmf.py</code>. This

+script is located in the <code>pepper_<version>/tools/</code>, meaning under your

+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.

<h3 id="c-libraries">C libraries</h3>

@@ -90,30 +91,12 @@ relies on some GNU extensions).

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 <code>toolchain/<OS_platform>_pnacl</code>, and the GCC-based

-toolchains are located in directories named

-<code>toolchain/<OS_platform>_<architecture>_<library></code>, where:

-<ul class="small-gap">

-<li><dl class="first docutils">

-<dt><platform> is the platform of your development machine (win, mac, or</dt>

-<dd>linux)</dd>

-</dl>

-</li>

-<li><architecture> is your target architecture (x86 or arm)</li>

-<li><library> is the C library you are compiling with (newlib or glibc)</li>

-</ul>

+in a directory named <code>pepper_<version>/toolchain/<OS_platform>_pnacl</code>,

+and the GCC-based toolchains are located in directories named

+<code>pepper_<version>/toolchain/<OS_platform>_<architecture>_<library></code>.

The compilers, linkers, and other tools are located in the <code>bin/</code>

subdirectory in each toolchain. For example, the tools in the Windows SDK

-for PNaCl has a C++ compiler in <code>toolchain/win_pnacl/bin/pnacl-clang++</code>.

-As another example, the GCC-based C++ compiler that targets x86 and uses the

-newlib library, is located at <code>toolchain/win_x86_newlib/bin/x86_64-nacl-g++</code>.

-<aside class="note">

-The SDK toolchains descend from the <code>toolchain/</code> directory. The SDK also

-has a <code>tools/</code> 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 <code>create_nmf.py</code> script, which you can

-use to create a manifest file).

-</aside>

+for PNaCl has a C++ compiler in <code>toolchain/win_pnacl/bin/pnacl-clang++</code>.

<h3 id="sdk-toolchains-versus-your-hosted-toolchain">SDK toolchains versus your hosted toolchain</h3>

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

@@ -146,11 +129,10 @@ run the tool with the <code>--version</code> 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:

<dt>pnacl-abicheck</dt>

-<dd>Check that the pexe follows the PNaCl ABI rules.</dd>

+<dd>Checks that the pexe follows the PNaCl ABI rules.</dd>

<dt>pnacl-ar</dt>

<dd>Creates archives (i.e., static libraries)</dd>

<dt>pnacl-clang</dt>

@@ -158,7 +140,7 @@ tools include:

<dt>pnacl-clang++</dt>

<dd>C++ compiler and compiler driver</dd>

<dt>pnacl-compress</dt>

-<dd>Size compresses a finalized pexe file for deployment.</dd>

+<dd>Compresses a finalized pexe file for deployment.</dd>

<dt>pnacl-dis</dt>

<dd>Disassembler for both pexe files and nexe files</dd>

<dt>pnacl-finalize</dt>

@@ -173,34 +155,29 @@ tools include:

<dd>Translates a pexe to a native architecture, outside of the browser</dd>

</dl>

For the full list of tools, see the

-<code><NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin</code> directory.

+<code>pepper_<version>/toolchain/<platform>_pnacl/bin</code> directory.

<h2 id="using-the-pnacl-tools-to-compile-link-debug-and-deploy">Using the PNaCl tools to compile, link, debug, and deploy</h2>

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.

<h3 id="compile">Compile</h3>

To compile a simple application consisting of <code>file1.cc</code> and <code>file2.cc</code> into

-<code>hello_world.pexe</code> with a single command, use the <code>pnacl-clang++</code> tool

+<code>hello_world.pexe</code> use the <code>pnacl-clang++</code> tool

<pre>

-<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

</pre>

-(The carat <code>^</code> 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. <code><NACL_SDK_ROOT></code> represents the path to the top-level

-directory of the bundle you are using, e.g.,

-<code><location-where-you-installed-the-SDK>/pepper_31</code>.)

-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 <code>pnacl-clang</code> C

compiler, or the <code>pnacl-clang++</code> C++ compiler. The compiler produces

separate bitcode files. For example:

<pre>

-<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

</pre>

For a description of each command line flag, run <code>pnacl-clang --help</code>.

For convenience, here is a description of some of the flags used in

@@ -234,8 +211,9 @@ translation time, this can be tested locally with <code>pnacl-translate</code>.<

</dd>

<dd>adds a directory to the search path for include files. The SDK has

-Pepper (PPAPI) headers located at <code><NACL_SDK_ROOT>/include</code>, so add

-that directory when compiling to be able to include the headers.</dd>

+Pepper (PPAPI) headers located at <code><NACL_SDK_ROOT>/pepper_<version>/

+include</code>, so add that directory when compiling to be able to include the

+headers.</dd>

<dt><code>-mllvm -inline-threshold=n</code></dt>

<dd>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

@@ -248,33 +226,33 @@ value that you pass in: you’ll be trading off potential performance with

static library from a set of bitcode files, which can later be linked

into the full application.

<pre>

-<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

</pre>

<h3 id="link-the-application">Link the application</h3>

The <code>pnacl-clang++</code> tool is used to compile applications, but it can

also be used link together compiled bitcode and libraries into a

full application.

<pre>

-<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

</pre>

This links the hello world bitcode with the <code>foo</code> library in the example

as well as the Debug version of the Pepper libraries which are located

-in <code><NACL_SDK_ROOT>/lib/pnacl/Debug</code>. If you wish to link against the

-Release version of the Pepper libraries, change the

-<code>-L<NACL_SDK_ROOT>/lib/pnacl/Debug</code> to

-<code>-L<NACL_SDK_ROOT>/lib/pnacl/Release</code>.

+in <code><NACL_SDK_ROOT>/pepper_<version>/lib/pnacl/Debug</code>. If you wish to link

+against the Release version of the Pepper libraries, change the

+<code>-L<NACL_SDK_ROOT>/pepper_<version>/lib/pnacl/Debug</code> to

+<code>-L<NACL_SDK_ROOT>/pepper_<version>/lib/pnacl/Release</code>.

In a release build you’ll want to pass <code>-O2</code> 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.

<pre>

-<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

</pre>

By default the link step will turn all C++ exceptions into calls to <code>abort()</code>

@@ -289,7 +267,7 @@ application, and see the <a class="reference internal" href="/native-client/devg

debugging techniques and workflow. After testing a PNaCl application, you must

finalize it. The <code>pnacl-finalize</code> tool handles this.

<pre>

-<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

</pre>

Prior to finalization, the application pexe is stored in a binary

@@ -314,7 +292,7 @@ decompressed on the client’s side. All costs are upfront when you call

it is somewhat slow (can take from seconds to minutes on large

appications). Hence, this step is optional.

<pre>

-<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-compress ^

+<NACL_SDK_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-compress \

hello_world.final.pexe

</pre>

<code>pnacl-compress</code> must be called after a pexe file has been finalized for

@@ -379,9 +357,10 @@ architecture specific.

architecture, and using the newlib library, you can compile a 32-bit .nexe

for the hello_world example with the following command:

<pre>

-<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

</pre>

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

@@ -471,7 +450,8 @@ for each command.

<h2 id="libraries-and-header-files-provided-with-the-sdk">Libraries and header files provided with the SDK</h2>

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 <code>/pepper_<version></code> directory

+in the following locations:

<li>PNaCl toolchain: <code>toolchain/<platform>_pnacl/usr/lib</code></li>

<li>x86 toolchains: <code>toolchain/<platform>_x86_<library>/x86_64-nacl/lib32</code> and

@@ -534,7 +514,7 @@ non-Native-Client development. If you want to use a specific third-party

library for Native Client development, look for it in <a class="reference external" href="http://code.google.com/p/naclports/">naclports</a>, or port the library yourself.</li>

<li>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 <code>\*_LDFLAGS</code> variables in the Makefiles of the SDK

examples for the order in which specific libraries should be listed.</li>

</ul>

@@ -566,8 +546,9 @@ use URL loaders, or an in-memory filesystem).

<h3 id="can-t-find-libraries-containing-necessary-symbols">Can’t find libraries containing necessary symbols</h3>

Here is one way to find the appropriate library for a given symbol:

<pre>

-<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>

</pre>

<h3 id="pnacl-abi-verification-errors">PNaCl ABI Verification errors</h3>

PNaCl has restrictions on what is supported in bitcode. There is a bitcode