native_client_sdk/doc_generated/devguide/devcycle/building.html - Issue 356573003: NaCl documentation: improve building documentation

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

Issue 356573003: NaCl documentation: improve building documentation (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src

Patch Set: Created 6 years, 6 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

Download patch

« no previous file with comments | « no previous file | native_client_sdk/doc_generated/reference/pnacl-c-cpp-language-support.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 f613f66b4fa93182f517df645215997d7fab8a2e..7065571213f921c9e49d93e0dc7157fbfcd221f1 100644

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

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

@@ -55,9 +55,9 @@ into an executable file ending in a .pexe extension using the P

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

+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

@@ -70,7 +70,7 @@ 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.

</section><section id="c-libraries">

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

The PNaCl SDK has a single choice of C library: <a class="reference external" href="http://sourceware.org/newlib/">newlib</a>.

@@ -89,7 +89,7 @@ choose which standard library to use.

language features should work regardless of which standard library is

used. The <code>-std=[c++98|c++11]</code> command line argument can be used to

indicate which C++ language standard to use (or <code>-std=gnu++11</code> to

-access non-standard extensions).

+access non-standard extensions which newlib often relies on).

</section><section id="sdk-toolchains">

<h3 id="sdk-toolchains">SDK toolchains</h3>

The Native Client SDK includes multiple toolchains. It has one PNaCl toolchain

@@ -99,14 +99,18 @@ in a directory named <code>toolchain/<OS_platform>_pnacl</code>, and the G

toolchains are located in directories named

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

-<li><platform> is the platform of your development machine (win, mac, or linux)</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>

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

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 the x86 and uses the

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

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

@@ -146,9 +150,9 @@ provided in the SDK.

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

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

@@ -223,23 +227,28 @@ This debug information can be used during development, and then stripped

before actually deploying the application to keep the application’s

download size small.</dd>

-<dd>sets the optimization level to n. Use 0 when debugging, and -O2 or -O3

-for profiling and deployment.

-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

-<code>-O3</code> optimizations are not desirable due to increased pexe

+<dd>sets the optimization level to n. Use <code>-O0</code> when debugging, and <code>-O2</code> or

+<code>-O3</code> for profiling and deployment.

+The main difference between <code>-O2</code> and <code>-O3</code> is whether the compiler

+performs optimizations that involve a space-speed tradeoff. It could be the

+case that <code>-O3</code> 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

+<code>pnacl-clang</code>, 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.

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

+<dt><code>-mllvm -inline-threshold=5</code></dt>

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

</dl>

</section><section id="create-a-static-library">

<h3 id="create-a-static-library">Create a static library</h3>

@@ -267,21 +276,29 @@ in <code><NACL_SDK_ROOT>/lib/pnacl/Debug</code>. If you wish to link again

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

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

+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

+<code>--pnacl-exceptions=sjlj</code> linker flag as explained in the <a class="reference internal" href="/native-client/reference/pnacl-c-cpp-language-support.html#exception-handling">exception

+handling</a> section of the C++ language support reference.

</section><section id="finalizing-the-pexe-for-deployment">

<h3 id="finalizing-the-pexe-for-deployment">Finalizing the pexe for deployment</h3>

-Typically you would run the application to test it and debug it if needed

-before deploying. See the <a class="reference internal" href="/native-client/devguide/devcycle/running.html">running</a> documentation for how

-to run a PNaCl application, and see the <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html">debugging</a>

-documentation for debugging techniques and workflow. After testing a PNaCl

-application, you must “finalize” it. The <code>pnacl-finalize</code>

-tool handles this.

+Typically you would run the application to test it and debug it if needed before

+deploying. See the <a class="reference internal" href="/native-client/devguide/devcycle/running.html">running</a> documentation for how to run a PNaCl

+application, and see the <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html">debugging</a> documentation for

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

hello_world.pexe -o hello_world.final.pexe

</pre>

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.

@@ -292,28 +309,29 @@ files can also be written by hand.

</section><section id="compressing-the-pexe-for-deployment">

<h3 id="compressing-the-pexe-for-deployment">Compressing the pexe for deployment</h3>

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

<code>pnacl-compress</code> 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 <code>pnacl-compress</code>.

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

<pre>

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

hello_world.final.pexe

</pre>

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

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

for deployment (via <code>pnacl-finalize</code>). Alternatively, you can apply this

step as part of the finalizing step by adding the <code>--compress</code> flag

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

+to the <code>pnacl-finalize</code> command line.

+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

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

</section></section><section id="the-gnu-based-toolchains">

<h2 id="the-gnu-based-toolchains">The GNU-based toolchains</h2>

Besides the PNaCl toolchain, the Native Client SDK also includes modified

@@ -328,14 +346,14 @@ 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 <code>i686-nacl-gcc</code> to compile 32-bit

-.nexes, and <code>x86_64-nacl-gcc</code> to compile 64-bit .nexes. Note that you can

-typically override a tool’s default target architecture with command line

+.nexes, and <code>x86_64-nacl-gcc</code> 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 <code>x86_64-nacl-gcc -m32</code> to compile a 32-bit

-.nexe.

+.nexe.

The GNU-based SDK toolchains include the following tools:

@@ -366,15 +384,15 @@ flags, e.g., you can specify <code>x86_64-nacl-gcc -m32</code> to compile a 32-b

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:

<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

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

+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., <code>x86_64-nacl-gcc</code>.

You should name executable modules with a .nexe filename extension,

regardless of what platform you’re using.

@@ -389,9 +407,9 @@ section on how to create shared libraries.

</section><section id="finalizing-a-nexe-for-deployment">

<h3 id="finalizing-a-nexe-for-deployment">Finalizing a nexe for deployment</h3>

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

<code><prefix>strip</code> tool to strip out debug information.

</section></section><section id="using-make">

@@ -411,7 +429,7 @@ depending on the setting of the environment variables.

<li>If <code>TOOLCHAIN=pnacl</code> creates a subdirectory called <code>pnacl</code>;

-<li>builds a .pexe (architecture-independent Native Client executable) using

+<li>builds a .pexe (architecture-independent Native Client executable) using

the newlib library</li>

<li>generates a Native Client manifest (.nmf) file for the pnacl version of the

example</li>

@@ -419,7 +437,7 @@ example</li>

</li>

<li>If <code>TOOLCHAIN=newlib</code> creates a subdirectory called <code>newlib</code>;

-<li>builds .nexes for the x86-32, x86-64, and ARM architectures using the

+<li>builds .nexes for the x86-32, x86-64, and ARM architectures using the

newlib library</li>

<li>generates a Native Client manifest (.nmf) file for the newlib version of

the example</li>

@@ -427,7 +445,7 @@ the example</li>

</li>

<li>If <code>TOOLCHAIN=glibc</code> creates a subdirectory called <code>glibc</code>;

-<li>builds .nexes for the x86-32 and x86-64 architectures using the glibc

+<li>builds .nexes for the x86-32 and x86-64 architectures using the glibc

library</li>

<li>generates a Native Client manifest (.nmf) file for the glibc version of the

example</li>