Native client-development Cycle Building

Introduction

This document describes how to build Native Client modules. It is intended for developers who has experience writing, compiling, and linking C and C + + code. If you haven ' t read the Native Client Technical Overview and Tutorial, we recommend starting with those. Target Architectures

Portable Native Client (PNACL) modules is written in C or C + + and compiled into an executable file ending in a. Pexe exte Nsion using the Pnacl 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 is operating-system-independent and processor-independent. The same pexe would run on Windows, Mac OS X, Linux, and ChromeOS and it'll run on x86-32, x86-64, ARM and MIPS processor S.

Native Client also supports architecture-specific nexe files. These nexe files is also operating-system-independent, but they is not processor-independent. To support a wide variety of devices you must compile separate versions of your Native Client module for different process ORS on End-User machines. A manifest Filewill then specify which version of the module to load based on the end-user ' s architecture. The SDK includes a script for generating manifest files called create_nmf.py. This script was located in Thepepper_<version>/tools/directory, meaning under your installed pepper bundle. For examples of what compile modules for multiple target architectures and how to generate manifest files, see the MAKEF Iles included with the SDK examples.

This section would mostly cover Pnacl, but also describes what to build Nexe applications. C Libraries

The Pnacl Toolchain uses the Newlib C library and can be used to build portable Pexe files (using Pnacl-clang) or Nexe fil ES (using, for example, X86_64-nacl-clang). The Native Client SDK also have a gcc-based toolchain for building nexe files which uses the GLIBC C library. See the Dynamic linking & Loading with glibc for information on these libraries, including factors to help you decide W Hich to use. C + + standard libraries

The Pnacl SDK can use either LLVM's libc++ (the current default) or GCC ' s libstdc++ (deprecated). The-stdlib=[libc++|libstdc++] Command line argument can is used to choose which the library to use.

The gcc-based toolchain only have support for GCC ' s libstdc++.

C++11 Library support is libc++ the Non-library language features should work regardless of which s Tandard Library is used. the-std=gnu++11 Command line argument can is used to indicate which C + + language standard to use (-std=c++11 often doesn ' t work well because newlib relies on some GNU extensions). SDK toolchains

The Native Client SDK includes multiple toolchains. It has one pnacl toolchain and it have multiple gcc-based toolchains that is differentiated by target architectures and C Libraries. The single Pnacl toolchain are located in a directory named Pepper_<version>/toolchain/<os_platform>_pnacl, an D The gcc-based Toolchains is located in directories namedpepper_<version>/toolchain/<os_platform>_< Architecture>_<c_library>.

The compilers, linkers, and other tools is located in the bin/subdirectory in each toolchain. For example, the tools in the Windows SDK for Pnacl have a C + + compiler in toolchain/win_pnacl/bin/pnacl-clang++. SDK Toolchains versus your hosted toolchain

To build NaCl modules, you must use one of the Native Client Toolchains included in the SDK. The SDK toolchains use a variety of techniques to ensure that your NACL modules comply with the security constraints of th E Native Client Sandbox.

During Development, you have another choice:you can build modules using A standard toolchain, such as the host Ed Toolchain on your development machine. This can is Visual Studio ' s standard compiler, XCode, LLVM, or gnu-based compilers on your development machine. These standard toolchains won't produce executables that comply with the Native Client sandbox security constraints. They is also not portable across operating systems and not portable across different processors. However, using a standard toolchain allows-develop modules in your favorite IDE and use your favorite debugging and Profiling Tools. The drawback is, modules compiled in this manner can only run as Pepper (PPAPI) plugins in Chrome. To publish and distribute Native Client modules as part of a Web application, you must eventually use a toolchain in the N Ative Client SDK. In the future, additional tools would be available to compile Native Client modules written in other programming languages,such as C #. But this document covers only compiling C and C + + code, using the Toolchains provided in the SDK.The pnacl toolchain

The Pnacl toolchain contains modified versions of the tools in the LLVM toolchain, as well as linkers and other tools from Binutils. To determine which version of LLVM or binutils the tools is based upon, run the tool with the--version command line flag . These tools is 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 Purpos ES).

Some of the useful tools Include:pnacl-abicheck Checks that the  pexe follows the Pnacl ABI rules. Pnacl-ar Creates archives (i.e., static libraries) Pnacl-bcdis Object dumper for pnacl bitcode files. Pnacl-clang C compiler and compiler driver pnacl-clang++ C + + compiler and compiler driver pnacl-compress compresses a FINA lized  pexe file for deployment. Pnacl-dis disassembler for both  pexe files and  nexe files pnacl-finalize Finalizes  Pexe  files for Deployment PNACL-LD BITCODE linker pnacl-nm Lists symbols in bitcode files, native code, and libraries PNA Cl-ranlib generates a symbol table for archives (i.e., static libraries) Pnacl-translate translates a  pexe to a Native architecture, outside of the browser

For the full list of tools, see the Pepper_<version>/toolchain/<platform>_pnacl/bin directory. Using the Pnacl tools to compile, link, debug, and deploy

To build a application with the Pnacl SDK toolchain, you must compile your code, link it, test and debug it, and then DEP Loy it. This section goes over some examples of the tools. Compile

To compile a simple application consisting of file1.cc and file2.cc into Hello_world.pexe use thepnacl-clang++ tool

nacl_sdk/pepper_<version>/toolchain/win_pnacl/bin/pnacl-clang++ \
  file1.cc file2.cc-inacl_sdk/pepper_ <version>/include \
  -lnacl_sdk/pepper_<version>/lib/pnacl/release-o hello_world.pexe \
  -g-o2- Lppapi_cpp-lppapi

The typical application consists of many files. In the case, the each file can is compiled separately so, and the files that is affected by a change need to be recompiled.  To compile a individual file from your application, your must use either the Pnacl-clang C compiler, or the pnacl-clang++ C + + compiler. The compiler produces separate bitcode files. For example:

nacl_sdk/pepper_<version>/toolchain/win_pnacl/bin/pnacl-clang++ \
  Hello_world.cc-inacl_sdk/pepper_ <VERSION>/INCLUDE-C \-
  o hello_world.o-g-o0

For a description The command line flag, run Pnacl-clang--help. For convenience, this is a description of some of the flags used in the example. -C indicates that pnacl-clang++ should only compile an individual file, rather than continue the build process and link t Ogether the full application. -O <output_file> indicates the output filename. -G tells the compiler to include debug information in the result. This debug information can is used during development, and then stripped before actually deploying the application to Kee P The application ' s download size small. -on

Sets the optimization level to N. Use -o0 when debugging, And -o2 or -o3 for Deployment.

The main difference Between -o2 and -o3 is whether the compiler performs optimizations that involve a Space-speed tradeoff. It could is the case that -o3 optimizations is not desirable due to increasedpexe download size; You should make your own performance measurements to determine which level of optimization are right for you. When looking at code size, note the generally care about is not the size of the pexe produced by  Pnacl-clang, but the size of the Compressed pexe that your upload to the server or to the Chrome Web Store. Optimizations that increase the size of a uncompressed pexemay not increase the size of the Compressed pexe&nbs P;very much. should also verify how optimization level affects on-device translation time, this can be tested locally With pna Cl-translate. -i<directory> adds a directory to the search path for  include files. The SDK has Pepper (PPAPI) headers located at nacl_sdk/pepper_<version>/include, so add this directory when compiling to is able to include the headers. -mllvm-inline-threshold=n change how much inlining was performed by LLVM (the default is 225, a smaller value would result In less inlining being performed). The right number to choose are application-specific, you'll therefore want to experiment with the value of this you pass In:y Ou ' ll be trading off potential performance with  pexe size and on-device translation speed.