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