| OLD | NEW |
|---|
| (Empty) | |
| 1 {{+bindTo:partials.standard_nacl_article}} |
| 2 |
| 3 <section id="building"> |
| 4 <span id="devcycle-building"></span><h1 id="building"><span id="devcycle-buildin
g"></span>Building</h1> |
| 5 <div class="contents local topic" id="table-of-contents"> |
| 6 <p class="topic-title first">Table Of Contents</p> |
| 7 <ul class="small-gap"> |
| 8 <li><p class="first"><a class="reference internal" href="#introduction" id="id4"
>Introduction</a></p> |
| 9 <ul class="small-gap"> |
| 10 <li><a class="reference internal" href="#target-architectures" id="id5">Target a
rchitectures</a></li> |
| 11 <li><a class="reference internal" href="#c-libraries" id="id6">C libraries</a></
li> |
| 12 <li><a class="reference internal" href="#c-standard-libraries" id="id7">C++ stan
dard libraries</a></li> |
| 13 <li><a class="reference internal" href="#sdk-toolchains" id="id8">SDK toolchains
</a></li> |
| 14 <li><a class="reference internal" href="#sdk-toolchains-versus-your-hosted-toolc
hain" id="id9">SDK toolchains versus your hosted toolchain</a></li> |
| 15 </ul> |
| 16 </li> |
| 17 <li><a class="reference internal" href="#the-pnacl-toolchain" id="id10">The PNaC
l toolchain</a></li> |
| 18 <li><p class="first"><a class="reference internal" href="#using-the-pnacl-tools-
to-compile-link-debug-and-deploy" id="id11">Using the PNaCl tools to compile, li
nk, debug, and deploy</a></p> |
| 19 <ul class="small-gap"> |
| 20 <li><a class="reference internal" href="#compile" id="id12">Compile</a></li> |
| 21 <li><a class="reference internal" href="#create-a-static-library" id="id13">Crea
te a static library</a></li> |
| 22 <li><a class="reference internal" href="#link-the-application" id="id14">Link th
e application</a></li> |
| 23 <li><a class="reference internal" href="#finalizing-the-pexe-for-deployment" id=
"id15">Finalizing the <strong>pexe</strong> for deployment</a></li> |
| 24 </ul> |
| 25 </li> |
| 26 <li><p class="first"><a class="reference internal" href="#the-gnu-based-toolchai
ns" id="id16">The GNU-based toolchains</a></p> |
| 27 <ul class="small-gap"> |
| 28 <li><a class="reference internal" href="#compiling" id="id17">Compiling</a></li> |
| 29 <li><a class="reference internal" href="#creating-libraries-and-linking" id="id1
8">Creating libraries and Linking</a></li> |
| 30 <li><a class="reference internal" href="#finalizing-a-nexe-for-deployment" id="i
d19">Finalizing a <strong>nexe</strong> for deployment</a></li> |
| 31 </ul> |
| 32 </li> |
| 33 <li><a class="reference internal" href="#using-make" id="id20">Using make</a></l
i> |
| 34 <li><a class="reference internal" href="#libraries-and-header-files-provided-wit
h-the-sdk" id="id21">Libraries and header files provided with the SDK</a></li> |
| 35 <li><p class="first"><a class="reference internal" href="#troubleshooting" id="i
d22">Troubleshooting</a></p> |
| 36 <ul class="small-gap"> |
| 37 <li><a class="reference internal" href="#undefined-reference-error" id="id23">&#
8220;Undefined reference” error</a></li> |
| 38 <li><a class="reference internal" href="#can-t-find-libraries-containing-necessa
ry-symbols" id="id24">Can’t find libraries containing necessary symbols</a
></li> |
| 39 <li><a class="reference internal" href="#pnacl-abi-verification-errors" id="id25
">PNaCl ABI Verification errors</a></li> |
| 40 </ul> |
| 41 </li> |
| 42 </ul> |
| 43 </div> |
| 44 <section id="introduction"> |
| 45 <h2 id="introduction">Introduction</h2> |
| 46 <p>This document describes how to build Native Client modules. It is intended fo
r |
| 47 developers who have experience writing, compiling, and linking C and C++ code. |
| 48 If you haven’t read the Native Client <a class="reference internal" href="
/native-client/overview.html"><em>Technical Overview</em></a> and <a class="refe
rence internal" href="/native-client/devguide/tutorial/index.html"><em>Tutorial<
/em></a>, we recommend starting |
| 49 with those.</p> |
| 50 <section id="target-architectures"> |
| 51 <span id="id1"></span><h3 id="target-architectures"><span id="id1"></span>Target
architectures</h3> |
| 52 <p>Portable Native Client (PNaCl) modules are written in C or C++ and compiled |
| 53 into an executable file ending in a <strong>.pexe</strong> extension using the P
NaCl |
| 54 toolchain in the Native Client SDK. Chrome can load <strong>pexe</strong> files |
| 55 embedded in web pages and execute them as part of a web application.</p> |
| 56 <p>As explained in the Technical Overview, PNaCl modules are |
| 57 operating-system-independent <strong>and</strong> processor-independent. The sam
e |
| 58 <strong>pexe</strong> will run on Windows, Mac, Linux, and ChromeOS and it will
run on |
| 59 any processor, e.g., x86-32, x86-64, and ARM.</p> |
| 60 <p>Native Client also supports architecture-specific <strong>nexe</strong> files
. |
| 61 These <strong>nexe</strong> files are <strong>also</strong> operating-system-ind
ependent, |
| 62 but they are <strong>not</strong> processor-independent. To support a wide varie
ty of |
| 63 devices you must compile separate versions of your Native Client module |
| 64 for different processors on end-user machines. A |
| 65 <a class="reference internal" href="/native-client/overview.html#application-fil
es"><em>manifest file</em></a> will then specify which version |
| 66 of the module to load based on the end-user’s architecture. The SDK |
| 67 includes a script—<code>create_nmf.py</code> (in the <code>tools/</code> d
irectory)—to |
| 68 generate manifest files. For examples of how to compile modules |
| 69 for multiple target architectures and how to generate manifest files, see the |
| 70 Makefiles included with the SDK examples.</p> |
| 71 <p>This section will mostly cover PNaCl, but also describes how to build |
| 72 nexe applications.</p> |
| 73 </section><section id="c-libraries"> |
| 74 <h3 id="c-libraries">C libraries</h3> |
| 75 <p>The PNaCl SDK has a single choice of C library: <a class="reference external"
href="http://sourceware.org/newlib/">newlib</a>.</p> |
| 76 <p>The Native Client SDK also has a GCC-based toolchain for building |
| 77 <strong>nexes</strong>. The GCC-based toolchain has support for two C libraries: |
| 78 <a class="reference external" href="http://sourceware.org/newlib/">newlib</a> an
d <a class="reference external" href="http://www.gnu.org/software/libc/">glibc</
a>. See <a class="reference internal" href="/native-client/devguide/devcycle/dy
namic-loading.html"><em>Dynamic Linking & Loading with glibc</em></a> for in
formation about these libraries, including factors to |
| 79 help you decide which to use.</p> |
| 80 </section><section id="c-standard-libraries"> |
| 81 <span id="building-cpp-libraries"></span><h3 id="c-standard-libraries"><span id=
"building-cpp-libraries"></span>C++ standard libraries</h3> |
| 82 <p>The PNaCl SDK can use either LLVM’s <a class="reference external" href=
"http://libcxx.llvm.org/">libc++</a> |
| 83 (the current default) or GCC’s <a class="reference external" href="http://
gcc.gnu.org/libstdc++">libstdc++</a> (deprecated). The |
| 84 <code>-stdlib=[libc++|libstdc++]</code> command line argument can be used to |
| 85 choose which standard library to use.</p> |
| 86 <p>The GCC-based Native Client SDK only has support for GCC’s <a class="re
ference external" href="http://gcc.gnu.org/libstdc++">libstdc++</a>.</p> |
| 87 <p>C++11 library support is only complete in libc++ but other non-library |
| 88 language features should work regardless of which standard library is |
| 89 used. The <code>-std=[c++98|c++11]</code> command line argument can be used to |
| 90 indicate which C++ language standard to use (or <code>-std=gnu++11</code> to |
| 91 access non-standard extensions).</p> |
| 92 </section><section id="sdk-toolchains"> |
| 93 <h3 id="sdk-toolchains">SDK toolchains</h3> |
| 94 <p>The Native Client SDK includes multiple toolchains. It has one PNaCl toolchai
n |
| 95 and it has multiple GCC-based toolchains that are differentiated by target |
| 96 architectures and C libraries. The single PNaCl toolchain is located |
| 97 in a directory named <code>toolchain/<OS_platform>_pnacl</code>, and the G
CC-based |
| 98 toolchains are located in directories named |
| 99 <code>toolchain/<OS_platform>_<architecture>_<library></code>,
where:</p> |
| 100 <ul class="small-gap"> |
| 101 <li><em><platform></em> is the platform of your development machine (win,
mac, or linux)</li> |
| 102 <li><em><architecture></em> is your target architecture (x86 or arm)</li> |
| 103 <li><em><library></em> is the C library you are compiling with (newlib or
glibc)</li> |
| 104 </ul> |
| 105 <p>The compilers, linkers, and other tools are located in the <code>bin/</code> |
| 106 subdirectory in each toolchain. For example, the tools in the Windows SDK |
| 107 for PNaCl has a C++ compiler in <code>toolchain/win_pnacl/bin/pnacl-clang++</cod
e>. |
| 108 As another example, the GCC-based C++ compiler that targets the x86 and uses the |
| 109 newlib library, is located at <code>toolchain/win_x86_newlib/bin/x86_64-nacl-g++
</code>.</p> |
| 110 <aside class="note"> |
| 111 The SDK toolchains descend from the <code>toolchain/</code> directory. The SDK a
lso |
| 112 has a <code>tools/</code> directory; this directory contains utilities that are
not |
| 113 properly part of the toolchains but that you may find helpful in building and |
| 114 testing your application (e.g., the <code>create_nmf.py</code> script, which you
can |
| 115 use to create a manifest file). |
| 116 </aside> |
| 117 </section><section id="sdk-toolchains-versus-your-hosted-toolchain"> |
| 118 <h3 id="sdk-toolchains-versus-your-hosted-toolchain">SDK toolchains versus your
hosted toolchain</h3> |
| 119 <p>To build NaCl modules, you must use one of the Native Client toolchains |
| 120 included in the SDK. The SDK toolchains use a variety of techniques to |
| 121 ensure that your NaCl modules comply with the security constraints of |
| 122 the Native Client sandbox.</p> |
| 123 <p>During development, you have another choice: You can build modules using a |
| 124 <em>standard</em> toolchain, such as the hosted toolchain on your development |
| 125 machine. This can be Visual Studio’s standard compiler, XCode, LLVM, or |
| 126 GNU-based compilers on your development machine. These standard toolchains |
| 127 will not produce executables that comply with the Native Client sandbox |
| 128 security constraints. They are also not portable across operating systems |
| 129 and not portable across different processors. However, using a standard |
| 130 toolchain allows you to develop modules in your favorite IDE and use |
| 131 your favorite debugging and profiling tools. The drawback is that modules |
| 132 compiled in this manner can only run as Pepper (PPAPI) plugins in Chrome. |
| 133 To publish and distribute Native Client modules as part of a web |
| 134 application, you must eventually use a toolchain in the Native |
| 135 Client SDK.</p> |
| 136 <aside 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. |
| 141 </aside> |
| 142 </section></section><section id="the-pnacl-toolchain"> |
| 143 <h2 id="the-pnacl-toolchain">The PNaCl toolchain</h2> |
| 144 <p>The PNaCl toolchain contains modified versions of the tools in the |
| 145 LLVM toolchain, as well as linkers and other tools from binutils. |
| 146 To determine which version of LLVM or binutils the tools are based upon, |
| 147 run the tool with the <code>--version</code> command line flag. These tools |
| 148 are used to compile and link applications into .pexe files. The toolchain |
| 149 also contains a tool to translate a .pexe file into a |
| 150 architecture-specific .nexe (e.g., for debugging purposes).</p> |
| 151 <p>Each tool’s name is preceded by the prefix “pnacl-”. Some o
f the useful |
| 152 tools include:</p> |
| 153 <dl class="docutils"> |
| 154 <dt>pnacl-abicheck</dt> |
| 155 <dd>Check that the <strong>pexe</strong> follows the PNaCl ABI rules.</dd> |
| 156 <dt>pnacl-ar</dt> |
| 157 <dd>Creates archives (i.e., static libraries)</dd> |
| 158 <dt>pnacl-clang</dt> |
| 159 <dd>C compiler and compiler driver</dd> |
| 160 <dt>pnacl-clang++</dt> |
| 161 <dd>C++ compiler and compiler driver</dd> |
| 162 <dt>pnacl-dis</dt> |
| 163 <dd>Disassembler for both <strong>pexe</strong> files and <strong>nexe</strong>
files</dd> |
| 164 <dt>pnacl-finalize</dt> |
| 165 <dd>Finalizes <strong>pexe</strong> files for deployment</dd> |
| 166 <dt>pnacl-ld</dt> |
| 167 <dd>Bitcode linker</dd> |
| 168 <dt>pnacl-nm</dt> |
| 169 <dd>Lists symbols in bitcode files, native code, and libraries</dd> |
| 170 <dt>pnacl-ranlib</dt> |
| 171 <dd>Generates a symbol table for archives (i.e., static libraries)</dd> |
| 172 <dt>pnacl-translate</dt> |
| 173 <dd>Translates a <strong>pexe</strong> to a native architecture, outside of the
browser</dd> |
| 174 </dl> |
| 175 <p>For the full list of tools, see the |
| 176 <code><NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin</code> director
y.</p> |
| 177 </section><section id="using-the-pnacl-tools-to-compile-link-debug-and-deploy"> |
| 178 <h2 id="using-the-pnacl-tools-to-compile-link-debug-and-deploy">Using the PNaCl
tools to compile, link, debug, and deploy</h2> |
| 179 <p>To build an application with the PNaCl SDK toolchain, you must compile |
| 180 your code, link it, test and debug it, and then deploy it. This section goes |
| 181 over some examples of how to use the tools.</p> |
| 182 <section id="compile"> |
| 183 <h3 id="compile">Compile</h3> |
| 184 <p>To compile a simple application consisting of <code>file1.cc</code> and <code
>file2.cc</code> into |
| 185 <code>hello_world.pexe</code> with a single command, use the <code>pnacl-clang++
</code> tool</p> |
| 186 <pre> |
| 187 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ file1.cc file2.cc ^ |
| 188 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/pnacl/Release ^ |
| 189 -o hello_world.pexe -g -O2 -lppapi_cpp -lppapi |
| 190 </pre> |
| 191 <p>(The carat <code>^</code> allows the command to span multiple lines on Window
s; |
| 192 to do the same on Mac and Linux use a backslash instead. Or you can |
| 193 simply type the command and all its arguments on one |
| 194 line. <code><NACL_SDK_ROOT></code> represents the path to the top-level |
| 195 directory of the bundle you are using, e.g., |
| 196 <code><location-where-you-installed-the-SDK>/pepper_31</code>.)</p> |
| 197 <p>However, the typical application consists of many files. In that case, |
| 198 each file can be compiled separately so that only files that are |
| 199 affected by a change need to be recompiled. To compile an individual |
| 200 file from your application, you must use either the <code>pnacl-clang</code> C |
| 201 compiler, or the <code>pnacl-clang++</code> C++ compiler. The compiler produces |
| 202 separate bitcode files. For example:</p> |
| 203 <pre> |
| 204 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ hello_world.cc ^ |
| 205 -I<NACL_SDK_ROOT>/include -c -o hello_world.o -g -O0 |
| 206 </pre> |
| 207 <p>For a description of each command line flag, run <code>pnacl-clang --help</co
de>. |
| 208 For convenience, here is a description of some of the flags used in |
| 209 the example.</p> |
| 210 <dl class="docutils" id="compile-flags"> |
| 211 <dt><code>-c</code></dt> |
| 212 <dd>indicates that <code>pnacl-clang++</code> should only compile an individual
file, |
| 213 rather than continue the build process and link together the |
| 214 full application.</dd> |
| 215 <dt><code>-o <output_file></code></dt> |
| 216 <dd>indicates the <strong>output</strong> filename.</dd> |
| 217 <dt><code>-g</code></dt> |
| 218 <dd>tells the compiler to include debug information in the result. |
| 219 This debug information can be used during development, and then <strong>stripped
</strong> |
| 220 before actually deploying the application to keep the application’s |
| 221 download size small.</dd> |
| 222 <dt><code>-On</code></dt> |
| 223 <dd><p class="first">sets the optimization level to n. Use 0 when debugging, and
-O2 or -O3 |
| 224 for profiling and deployment.</p> |
| 225 <p class="last">The main difference between -O2 and -O3 is whether the compiler
performs |
| 226 optimizations that involve a space-speed tradeoff. It could be the case that |
| 227 <code>-O3</code> optimizations are not desirable due to increased <strong>pexe</
strong> |
| 228 download size; you should make your own performance measurements to determine |
| 229 which level of optimization is right for you. When looking at code size, |
| 230 note that what you generally care about is not the size of the pexe |
| 231 produced by pnacl-clang, but the size of the compressed pexe that you upload |
| 232 your application to the server or to the Chrome Web Store. |
| 233 Optimizations that increase the size of a pexe may not increase the size of |
| 234 the compressed pexe that much.</p> |
| 235 </dd> |
| 236 <dt><code>-I<directory></code></dt> |
| 237 <dd>adds a directory to the search path for <strong>include</strong> files. The
SDK has |
| 238 Pepper (PPAPI) headers located at <code><NACL_SDK_ROOT>/include</code>, so
add |
| 239 that directory when compiling to be able to include the headers.</dd> |
| 240 </dl> |
| 241 </section><section id="create-a-static-library"> |
| 242 <h3 id="create-a-static-library">Create a static library</h3> |
| 243 <p>The <code>pnacl-ar</code> and <code>pnacl-ranlib</code> tools allow you to cr
eate a |
| 244 <strong>static</strong> library from a set of bitcode files, which can later be
linked |
| 245 into the full application.</p> |
| 246 <pre> |
| 247 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ar cr libfoo.a ^ |
| 248 foo1.o foo2.o foo3.o |
| 249 |
| 250 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-ranlib libfoo.a |
| 251 </pre> |
| 252 </section><section id="link-the-application"> |
| 253 <h3 id="link-the-application">Link the application</h3> |
| 254 <p>The <code>pnacl-clang++</code> tool is used to compile applications, but it c
an |
| 255 also be used link together compiled bitcode and libraries into a |
| 256 full application.</p> |
| 257 <pre> |
| 258 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-clang++ -o hello_world.pexe
^ |
| 259 hello_world.o -L<NACL_SDK_ROOT>/lib/pnacl/Debug -lfoo -lppapi_cpp -lppap
i |
| 260 </pre> |
| 261 <p>This links the hello world bitcode with the <code>foo</code> library in the e
xample |
| 262 as well as the <em>Debug</em> version of the Pepper libraries which are located |
| 263 in <code><NACL_SDK_ROOT>/lib/pnacl/Debug</code>. If you wish to link again
st the |
| 264 <em>Release</em> version of the Pepper libraries, change the |
| 265 <code>-L<NACL_SDK_ROOT>/lib/pnacl/Debug</code> to |
| 266 <code>-L<NACL_SDK_ROOT>/lib/pnacl/Release</code>.</p> |
| 267 </section><section id="finalizing-the-pexe-for-deployment"> |
| 268 <h3 id="finalizing-the-pexe-for-deployment">Finalizing the <strong>pexe</strong>
for deployment</h3> |
| 269 <p>Typically you would run the application to test it and debug it if needed |
| 270 before deploying. See the <a class="reference internal" href="/native-client/dev
guide/devcycle/running.html"><em>running</em></a> documentation for how |
| 271 to run a PNaCl application, and see the <a class="reference internal" href="/nat
ive-client/devguide/devcycle/debugging.html"><em>debugging</em></a> |
| 272 documentation for debugging techniques and workflow. After testing a PNaCl |
| 273 application, you must <strong>“finalize”</strong> it. The <code>pnac
l-finalize</code> |
| 274 tool handles this.</p> |
| 275 <pre> |
| 276 <NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-finalize ^ |
| 277 hello_world.pexe -o hello_world.final.pexe |
| 278 </pre> |
| 279 <p>Prior to finalization, the application <strong>pexe</strong> is stored in a b
inary |
| 280 format that is subject to change. After finalization, the application |
| 281 pexe is <strong>rewritten</strong> into a different binary format that is <stron
g>stable</strong> |
| 282 and will be supported by future versions of PNaCl. The finalization step |
| 283 also helps minimize the size of your application for distribution by |
| 284 stripping out debug information and other metadata.</p> |
| 285 <p>Once the application is finalized, be sure to adjust the manifest file to |
| 286 refer to the final version of the application before deployment. |
| 287 The <code>create_nmf.py</code> tool helps generate an <code>.nmf</code> file, bu
t <code>.nmf</code> |
| 288 files can also be written by hand.</p> |
| 289 </section></section><section id="the-gnu-based-toolchains"> |
| 290 <h2 id="the-gnu-based-toolchains">The GNU-based toolchains</h2> |
| 291 <p>Besides the PNaCl toolchain, the Native Client SDK also includes modified |
| 292 versions of the tools in the standard GNU toolchain, including the GCC |
| 293 compilers and the linkers and other tools from binutils. These tools only |
| 294 support building <strong>nexe</strong> files. Run the tool with the <code>--vers
ion</code> |
| 295 command line flag to determine the current version of the tools.</p> |
| 296 <p>Each tool in the toolchain is prefixed with the name of the target |
| 297 architecture. In the toolchain for the ARM target architecture, each |
| 298 tool’s name is preceded by the prefix “arm-nacl-”. In the tool
chains for |
| 299 the x86 target architecture, there are actually two versions of each |
| 300 tool—one to build Native Client modules for the x86-32 |
| 301 target architecture, and one to build modules for the x86-64 target |
| 302 architecture. “i686-nacl-” is the prefix for tools used to build |
| 303 32-bit .nexes, and “x86_64-nacl-” is the prefix for tools used to |
| 304 build 64-bit .nexes</p> |
| 305 <p>These prefixes conform to gcc naming standards and make it easy to use tools |
| 306 like autoconf. As an example, you can use <code>i686-nacl-gcc</code> to compile
32-bit |
| 307 .nexes, and <code>x86_64-nacl-gcc</code> to compile 64-bit .nexes. Note that you
can |
| 308 typically override a tool’s default target architecture with command line |
| 309 flags, e.g., you can specify <code>x86_64-nacl-gcc -m32</code> to compile a 32-b
it |
| 310 .nexe.</p> |
| 311 <p>The GNU-based SDK toolchains include the following tools:</p> |
| 312 <ul class="small-gap"> |
| 313 <li><prefix>addr2line</li> |
| 314 <li><prefix>ar</li> |
| 315 <li><prefix>as</li> |
| 316 <li><prefix>c++</li> |
| 317 <li><prefix>c++filt</li> |
| 318 <li><prefix>cpp</li> |
| 319 <li><prefix>g++</li> |
| 320 <li><prefix>gcc</li> |
| 321 <li><prefix>gcc-4.4.3</li> |
| 322 <li><prefix>gccbug</li> |
| 323 <li><prefix>gcov</li> |
| 324 <li><prefix>gprof</li> |
| 325 <li><prefix>ld</li> |
| 326 <li><prefix>nm</li> |
| 327 <li><prefix>objcopy</li> |
| 328 <li><prefix>objdump</li> |
| 329 <li><prefix>ranlib</li> |
| 330 <li><prefix>readelf</li> |
| 331 <li><prefix>size</li> |
| 332 <li><prefix>strings</li> |
| 333 <li><prefix>strip</li> |
| 334 </ul> |
| 335 <section id="compiling"> |
| 336 <h3 id="compiling">Compiling</h3> |
| 337 <p>Compiling files with the GNU-based toolchain is similar to compiling |
| 338 files with the PNaCl-based toolchain, except that the output is |
| 339 architecture specific.</p> |
| 340 <p>For example, assuming you’re developing on a Windows machine, targeting
the x86 |
| 341 architecture, and using the newlib library, you can compile a 32-bit .nexe for |
| 342 the hello_world example with the following command:</p> |
| 343 <pre> |
| 344 <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/i686-nacl-gcc hello_world.c ^ |
| 345 -I<NACL_SDK_ROOT>/include -L<NACL_SDK_ROOT>/lib/newlib/Release ^ |
| 346 -o hello_world_x86_32.nexe -m32 -g -O2 -lppapi |
| 347 </pre> |
| 348 <p>To compile a 64-bit .nexe, you can run the same command but use -m64 instead
of |
| 349 -m32. Alternatively, you could also use the version of the compiler that |
| 350 targets the x86-64 architecture, i.e., <code>x86_64-nacl-gcc</code>.</p> |
| 351 <p>You should name executable modules with a <strong>.nexe</strong> filename ext
ension, |
| 352 regardless of what platform you’re using.</p> |
| 353 </section><section id="creating-libraries-and-linking"> |
| 354 <h3 id="creating-libraries-and-linking">Creating libraries and Linking</h3> |
| 355 <p>Creating libraries and linking with the GNU-based toolchain is similar |
| 356 to doing the same with the PNaCl toolchain. The relevant tools |
| 357 for creating <strong>static</strong> libraries are <code><prefix>ar</code>
and <code><prefix>ranlib</code>. |
| 358 Linking can be done with <code><prefix>g++</code>. See the |
| 359 <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loa
ding.html"><em>Dynamic Linking & Loading with glibc</em></a> |
| 360 section on how to create <strong>shared</strong> libraries.</p> |
| 361 </section><section id="finalizing-a-nexe-for-deployment"> |
| 362 <h3 id="finalizing-a-nexe-for-deployment">Finalizing a <strong>nexe</strong> for
deployment</h3> |
| 363 <p>Unlike the PNaCl toolchain, no separate finalization step is required |
| 364 for <strong>nexe</strong> files. The nexe files are always in a <strong>stable</
strong> format. |
| 365 However, the nexe file may contain debug information and symbol information |
| 366 which may make the nexe file larger than needed for distribution. |
| 367 To minimize the size of the distributed file, you can run the |
| 368 <code><prefix>strip</code> tool to strip out debug information.</p> |
| 369 </section></section><section id="using-make"> |
| 370 <h2 id="using-make">Using make</h2> |
| 371 <p>This document doesn’t cover how to use <code>make</code>, but if you wa
nt to use |
| 372 <code>make</code> to build your Native Client module, you can base your Makefile
on the |
| 373 ones in the SDK examples.</p> |
| 374 <p>The Makefiles for the SDK examples build most of the examples in multiple |
| 375 configurations (using PNaCl vs NaCl, using different C libraries, |
| 376 targeting different architectures, and using different levels of optimization). |
| 377 To select a specific toolchain, set the <strong>environment variable</strong> |
| 378 <code>TOOLCHAIN</code> to either <code>pnacl</code>, <code>newlib</code>, <code>
glibc</code>, or <code>host</code>. |
| 379 To select a specific level of optimization set the <strong>environment |
| 380 variable</strong> <code>CONFIG</code> to either <code>Debug</code>, or <code>Rel
ease</code>. Running |
| 381 <code>make</code> in each example’s directory does <strong>one</strong> of
the following, |
| 382 depending on the setting of the environment variables.</p> |
| 383 <ul class="small-gap"> |
| 384 <li><p class="first">If <code>TOOLCHAIN=pnacl</code> creates a subdirectory call
ed <code>pnacl</code>;</p> |
| 385 <ul class="small-gap"> |
| 386 <li>builds a .pexe (architecture-independent Native Client executable) using |
| 387 the newlib library</li> |
| 388 <li>generates a Native Client manifest (.nmf) file for the pnacl version of the |
| 389 example</li> |
| 390 </ul> |
| 391 </li> |
| 392 <li><p class="first">If <code>TOOLCHAIN=newlib</code> creates a subdirectory cal
led <code>newlib</code>;</p> |
| 393 <ul class="small-gap"> |
| 394 <li>builds .nexes for the x86-32, x86-64, and ARM architectures using the |
| 395 newlib library</li> |
| 396 <li>generates a Native Client manifest (.nmf) file for the newlib version of |
| 397 the example</li> |
| 398 </ul> |
| 399 </li> |
| 400 <li><p class="first">If <code>TOOLCHAIN=glibc</code> creates a subdirectory call
ed <code>glibc</code>;</p> |
| 401 <ul class="small-gap"> |
| 402 <li>builds .nexes for the x86-32 and x86-64 architectures using the glibc |
| 403 library</li> |
| 404 <li>generates a Native Client manifest (.nmf) file for the glibc version of the |
| 405 example</li> |
| 406 </ul> |
| 407 </li> |
| 408 <li><p class="first">If <code>TOOLCHAIN=host</code> creates a subdirectory calle
d <code>windows</code>, <code>linux</code>, |
| 409 or <code>mac</code> (depending on your development machine);</p> |
| 410 <ul class="small-gap"> |
| 411 <li>builds a Pepper plugin (.dll for Windows, .so for Linux/Mac) using the |
| 412 hosted toolchain on your development machine</li> |
| 413 <li>generates a Native Client manifest (.nmf) file for the host Pepper plugin |
| 414 version of the example</li> |
| 415 </ul> |
| 416 </li> |
| 417 </ul> |
| 418 <aside class="note"> |
| 419 The glibc library is not yet available for the ARM and PNaCl toolchains. |
| 420 </aside> |
| 421 <p>Here is how to build the examples with PNaCl in Release mode on Windows. |
| 422 The resulting files for <code>examples/api/audio</code> will be in |
| 423 <code>examples/api/audio/pnacl/Release</code>, and the directory layout is simil
ar for |
| 424 other examples.</p> |
| 425 <pre> |
| 426 set TOOLCHAIN=pnacl |
| 427 set CONFIG=Release |
| 428 make |
| 429 </pre> |
| 430 <p>Your Makefile can be simpler since you will not likely want to build so many |
| 431 different configurations of your module. The example Makefiles define |
| 432 numerous variables near the top (e.g., <code>CFLAGS</code>) that make it easy |
| 433 to customize the commands that are executed for your project and the options |
| 434 for each command.</p> |
| 435 <p>For details on how to use make, see the <a class="reference external" href="h
ttp://www.gnu.org/software/make/manual/make.html">GNU ‘make’ Manual<
/a>.</p> |
| 436 </section><section id="libraries-and-header-files-provided-with-the-sdk"> |
| 437 <h2 id="libraries-and-header-files-provided-with-the-sdk">Libraries and header f
iles provided with the SDK</h2> |
| 438 <p>The Native Client SDK includes modified versions of standard toolchain-suppor
t |
| 439 libraries, such as libpthread and libc, plus the relevant header files. |
| 440 The standard libraries are located in the following directories:</p> |
| 441 <ul class="small-gap"> |
| 442 <li>PNaCl toolchain: <code>toolchain/<platform>_pnacl/usr/lib</code></li> |
| 443 <li>x86 toolchains: <code>toolchain/<platform>_x86_<library>/x86_64-
nacl/lib32</code> and |
| 444 <code>/lib64</code> (for the 32-bit and 64-bit target architectures, respectivel
y)</li> |
| 445 <li>ARM toolchain: <code>toolchain/<platform>_arm_<library>/arm-nacl
/lib</code></li> |
| 446 </ul> |
| 447 <p>For example, on Windows, the libraries for the x86-64 architecture in the |
| 448 newlib toolchain are in <code>toolchain/win_x86_newlib/x86_64-nacl/lib64</code>.
</p> |
| 449 <p>The header files are in:</p> |
| 450 <ul class="small-gap"> |
| 451 <li>PNaCl toolchain: <code>toolchain/<platform>_pnacl/usr/include</code></
li> |
| 452 <li>x86 toolchains: <code>toolchain/<platform>_x86_<library>/x86_64-
nacl/include</code></li> |
| 453 <li>ARM toolchain: <code>toolchain/<platform>_arm_<library>/arm-nacl
/include</code></li> |
| 454 </ul> |
| 455 <p>Many other libraries have been ported for use with Native Client; for more |
| 456 information, see the <a class="reference external" href="http://code.google.com/
p/naclports/">naclports</a> |
| 457 project. If you port an open-source library for your own use, we recommend |
| 458 adding it to naclports.</p> |
| 459 <p>Besides the standard libraries, the SDK includes Pepper libraries. |
| 460 The PNaCl Pepper libraries are located in the the |
| 461 <code><NACL_SDK_ROOT>/lib/pnacl/<Release or Debug></code> directory. |
| 462 The GNU-based toolchain has Pepper libraries in |
| 463 <code><NACL_SDK_ROOT>/lib/newlib_<arch>/<Release or Debug></co
de> |
| 464 and <code><NACL_SDK_ROOT>/lib/glibc_<arch>/<Release or Debug><
/code>. |
| 465 The libraries provided by the SDK allow the application to use Pepper, |
| 466 as well as convenience libraries to simplify porting an application that |
| 467 uses POSIX functions. Here are descriptions of the Pepper libraries provided |
| 468 in the SDK.</p> |
| 469 <dl class="docutils" id="devcycle-building-nacl-io"> |
| 470 <dt>libppapi.a</dt> |
| 471 <dd>Implements the Pepper (PPAPI) C interface. Needed for all applications that |
| 472 use Pepper (even C++ applications).</dd> |
| 473 <dt>libppapi_cpp.a</dt> |
| 474 <dd>Implements the Pepper (PPAPI) C++ interface. Needed by C++ applications that |
| 475 use Pepper.</dd> |
| 476 <dt>libppapi_gles2.a</dt> |
| 477 <dd>Implements the Pepper (PPAPI) GLES interface. Needed by applications |
| 478 that use the 3D graphics API.</dd> |
| 479 <dt>libnacl_io.a</dt> |
| 480 <dd>Provides a POSIX layer for NaCl. In particular, the library provides a |
| 481 virtual file system and support for sockets. The virtual file system |
| 482 allows a module to “mount” a given directory tree. Once a module has |
| 483 mounted a file system, it can use standard C library file operations: |
| 484 <code>fopen</code>, <code>fread</code>, <code>fwrite</code>, <code>fseek</code>,
and <code>fclose</code>. |
| 485 For more detail, see the header <code>include/nacl_io/nacl_io.h</code>. |
| 486 For an example of how to use nacl_io, see <code>examples/demo/nacl_io</code>.</d
d> |
| 487 <dt>libppapi_simple.a</dt> |
| 488 <dd>Provides a familiar C programming environment by letting a module have a |
| 489 simple entry point that is registered by <code>PPAPI_SIMPLE_REGISTER_MAIN</code>
. |
| 490 The entry point is similar to the standard C <code>main()</code> function, compl
ete |
| 491 with <code>argc</code> and <code>argv[]</code> parameters. For details see |
| 492 <code>include/ppapi_simple/ps.h</code>. For an example of |
| 493 how to use ppapi_simple, <code>see examples/tutorial/using_ppapi_simple</code>.<
/dd> |
| 494 </dl> |
| 495 <aside class="note"> |
| 496 <ul class="small-gap"> |
| 497 <li>Since the Native Client toolchains use their own library and header search |
| 498 paths, the tools won’t find third-party libraries you use in your |
| 499 non-Native-Client development. If you want to use a specific third-party |
| 500 library for Native Client development, look for it in <a class="reference extern
al" href="http://code.google.com/p/naclports/">naclports</a>, or port the librar
y yourself.</li> |
| 501 <li>The order in which you list libraries in your build commands is important, |
| 502 since the linker searches and processes libraries in the order in which they |
| 503 are specified. See the *_LDFLAGS variables in the Makefiles of the SDK |
| 504 examples for the order in which specific libraries should be listed.</li> |
| 505 </ul> |
| 506 |
| 507 </aside> |
| 508 </section><section id="troubleshooting"> |
| 509 <h2 id="troubleshooting">Troubleshooting</h2> |
| 510 <p>Some common problems, and how to fix them:</p> |
| 511 <section id="undefined-reference-error"> |
| 512 <h3 id="undefined-reference-error">“Undefined reference” error</h3> |
| 513 <p>An “undefined reference” error may indicate incorrect link order
and/or |
| 514 missing libraries. For example, if you leave out <code>-lppapi</code> when |
| 515 compiling Pepper applications you’ll see a series of undefined |
| 516 reference errors.</p> |
| 517 <p>One common type of “undefined reference” error is with respect to
certain |
| 518 system calls, e.g., “undefined reference to ‘mkdir’”. Fo
r security reasons, |
| 519 Native Client does not support a number of system calls. Depending on how |
| 520 your code uses such system calls, you have a few options:</p> |
| 521 <ol class="arabic simple"> |
| 522 <li>Link with the <code>-lnosys</code> flag to provide empty/always-fail version
s of |
| 523 unsupported system calls. This will at least get you past the link stage.</li> |
| 524 <li>Find and remove use of the unsupported system calls.</li> |
| 525 <li>Create your own implementation of the unsupported system calls to do |
| 526 something useful for your application.</li> |
| 527 </ol> |
| 528 <p>If your code uses mkdir or other file system calls, you might find the |
| 529 <a class="reference internal" href="#devcycle-building-nacl-io"><em>nacl_io</em>
</a> library useful. |
| 530 The nacl_io library essentially does option (3) for you: It lets your |
| 531 code use POSIX-like file system calls, and implements the calls using |
| 532 various technologies (e.g., HTML5 file system, read-only filesystems that |
| 533 use URL loaders, or an in-memory filesystem).</p> |
| 534 </section><section id="can-t-find-libraries-containing-necessary-symbols"> |
| 535 <h3 id="can-t-find-libraries-containing-necessary-symbols">Can’t find libr
aries containing necessary symbols</h3> |
| 536 <p>Here is one way to find the appropriate library for a given symbol:</p> |
| 537 <pre> |
| 538 <NACL_SDK_ROOT>/toolchain/<platform>_pnacl/bin/pnacl-nm -o \ |
| 539 toolchain/<platform>_pnacl/usr/lib/*.a | grep <MySymbolName> |
| 540 </pre> |
| 541 </section><section id="pnacl-abi-verification-errors"> |
| 542 <h3 id="pnacl-abi-verification-errors">PNaCl ABI Verification errors</h3> |
| 543 <p>PNaCl has restrictions on what is supported in bitcode. There is a bitcode |
| 544 ABI verifier which checks that the application conforms to the ABI restrictions, |
| 545 before it is translated and run in the browser. However, it is best to |
| 546 avoid runtime errors for users, so the verifier also runs on the developer’
;s |
| 547 machine at link time.</p> |
| 548 <p>For example, the following program which uses 128-bit integers |
| 549 would compile with NaCl GCC for the x86-64 target. However, it is not |
| 550 portable and would not compile with NaCl GCC for the i686 target. |
| 551 With PNaCl, it would fail to pass the ABI verifier:</p> |
| 552 <pre class="prettyprint"> |
| 553 typedef unsigned int uint128_t __attribute__((mode(TI))); |
| 554 |
| 555 uint128_t foo(uint128_t x) { |
| 556 return x; |
| 557 } |
| 558 </pre> |
| 559 <p>With PNaCl you would get the following error at link time:</p> |
| 560 <pre class="prettyprint"> |
| 561 Function foo has disallowed type: i128 (i128) |
| 562 LLVM ERROR: PNaCl ABI verification failed |
| 563 </pre> |
| 564 <p>When faced with a PNaCl ABI verification error, check the list of features |
| 565 that are <a class="reference internal" href="/native-client/nacl-and-pnacl.html#
when-to-use-nacl"><em>not supported by PNaCl</em></a>. |
| 566 If the problem you face is not listed as restricted, |
| 567 <a class="reference internal" href="/native-client/help.html#help"><em>let us kn
ow</em></a>!</p> |
| 568 </section></section></section> |
| 569 |
| 570 {{/partials.standard_nacl_article}} |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 140993006:
[NaCl SDK Docs] Check in the generated NaCl SDK Documentation. (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src