Release Notes

Portable Native Client

• PNaCl’s default C++ standard library is now LLVM’s own libc++, based on LLVM 3.3. This library now supports optional setjmp/longjmp exception handling (see announcement for details).

SDK

• The nacl_io library now includes a FUSE mount.
• In the SDK examples, common.js now loads the Release version of the nexes/pexes that are built (by default).
• “make debug” and “make run” have been fixed on Mac.

Libraries

• A number of libraries from the naclports project have been incorporated directly into the Native Client SDK. These libraries include:

  • image encoding/decoding: jpeg, tiff, png, webp
  • multimedia: openal, freealut, ogg, vorbis
  • XML parsing: tinyxml, xml2
  • miscellaneous: zlib (general purpose compression), freetype (font rendering), lua (Lua interpreter)

  The libraries are located in ports/lib, and the header files are in ports/include.

• The httpfs filesystem in the nacl_io library now caches content in memory by default; this improves performance considerably.
• For applications compiled with a glibc toolchain, dlopen() can now be used to open shared libraries that are not specified in an application’s Native Client manifest (.nmf) file. This allows applications, for example, to download a shared object and then use dlopen() to access the shared object. The dlopen example has been modified to demonstrate this functionality: reverse.cc is built into a shared object (.so) file, which is downloaded and opened using an httpfs mount.

Examples

• Each example now has a single index.html file, instead of multiple HTML files corresponding to NaCl modules built using different toolchains and configurations. By default, most examples are built using one toolchain (newlib) and one configuration (Debug). If you build an example using multiple toolchains or configurations, you can specify which version to run in Chrome using the query parameters tc and config. For example, assuming you are serving an example from the local server localhost:5103, you can run a version of the example built with the glibc toolchain in the Release configuration by specifying the following URL in Chrome: http://localhost:5103/index.html?tc=glibc&config=Release. For additional information about how different NaCl modules are loaded into index.html, see the common.js file in each example.

Build tools and toolchains

• Common makefiles, including tools/common.mk, can now handle source files located outside of an application’s root directory. For example, a Makefile for an application can specify a source file to compile such as ../../some/other/place.cpp.

Build tools and toolchains

• Makefiles have been changed significantly:

  • Build commands are now specified in a number of common files (tools/*.mk), which are included in the Makefiles in the examples.
  • By default, make displays a simplified list of build steps (e.g., CC newlib/Debug/hello_world_x86_32.o) rather than the actual build commands. To see the actual build commands, run make V=1.
  • By default, most examples are built using one toolchain (newlib) and one configuration (Debug). To build an example using a different toolchain or configuration, run make with the parameters TOOLCHAIN=<x> or CONFIG=<y>. You can also run make all_versions to build an example with all toolchains.
• Header files have been moved out of the toolchains. All toolchains now share the same set of header files as host builds. Previously host and NaCl builds used different headers, which could cause build problems.

Libraries

• The nacl_mounts library has been renamed nacl_io, and has been expanded with a new type of mount, httpfs, which can be used to read URLs via HTTP. For details see include/nacl_io/nacl_io.h, as well as the hello_nacl_io example.

Examples

• A new example, hello_world_instance3d, has been added to demonstrate a simplified 3D app.
• The file_io example has been rewritten to do all file operations on a thread. The example demonstrates how to use the MessageLoop API and blocking callbacks on a thread.

General

• Old bundles (pepper_20 and earlier) have been removed from the Native Client SDK Manifest, and will no longer be updated by the naclsdk command.

Build tools and toolchains

• The SDK includes a new toolchain to build Native Client executables (.nexe files) for ARM devices.

  • Currently the ARM toolchain can only be used to compile modules that use the newlib C library. You cannot use the ARM toolchain to compile modules that use the glibc library.
  • The ARM toolchain is in the directory pepper_25/toolchain/<host>_arm_newlib. The bin subdirectory contains the compiler (arm-nacl-gcc), the linker (arm-nacl-g++), and the other tools in the toolchain.
  • Take a look at the hello_world example to see how to use the ARM toolchain. Go to examples/hello_world and run make. When the build finishes, the newlib/Debug and newlib/Release subdirectories will contain .nexe files for the x86-32, x86-64, and ARM target architecutes, and a Native Client manifest (.nmf file) that references those three .nexe files.
• The simple web server included in the SDK, httpd.py, has been moved from the examples/ directory to the tools/ directory. On Windows, you can run httpd.cmd (in the examples/ directory) to start the server.

PPAPI

Pepper 25 includes two new APIs:

• The Console API lets your module log messages to the JavaScript console in the Chrome browser.
• The MessageLoop API lets your module make PPAPI calls on a background thread. Once you’ve created a message loop resource, attached it to a thread, and run it, you can post work to the thread, including completion callbacks for asynchronous operations. For a C++ example of how to use the MessageLoop API, see pepper_25/include/ppapi/utility/threading/simple_thread.h. Note that you cannot make asynchronous PPAPI calls on a background thread without creating and using a message loop.

Libraries

The SDK includes two new libraries:

• The nacl_mounts library provides a virtual file system that your module can “mount” in a given directory tree. The file system can be one of several types:

  • “memfs” is an in-memory file system,
  • “dev” is a file system with various utility nodes (e.g., /dev/null, /dev/console[0-3], /dev/tty), and
  • “html5fs” is a persistent file system.

  Once you’ve mounted a file system in your module, you can use standard C library file operations: fopen, fread, fwrite, fseek, and fclose. How those operations are performed depends on the type of file system (e.g., for html5fs, the operations are performed using the Pepper FileIO API). For a list of the types of file systems you can mount, see include/nacl_mounts/nacl_mounts.h. For an example of how to use nacl_mounts, see examples/hello_nacl_mounts. Note that html5fs is subject to the same constraints as persistent local file IO in Chrome (for example, prior to using an html5fs file system, you must enable local file IO).

• The ppapi_main library simplifies the creation of a NaCl module by providing a familiar C programming environment. With this library, your module can have a simple entry point called ppapi_main(), which is similar to the standard C main() function, complete with argc and argv[] parameters. Your module can also use standard C functions such as printf(), fopen(), and fwrite(). For details see include/ppapi_main/ppapi_main.h. For an example of how to use ppapi_main, see examples/hello_world_stdio.

Header files for the new libraries are in the include/ directory, source files are in the src/ directory, and compiled libraries are in the lib/ directory.

Examples

• The SDK includes two new examples:

  • hello_nacl_mounts illustrates how to use standard C library file operations in a Native Client module through the use of the nacl_mounts library.
  • hello_world_stdio illustrates how to implement a Native Client module with a ppapi_main() function, and how to write to STDOUT and STDERR in a module, through the use of the nacl_mounts and ppapi_main libraries. This example makes it easy for new users to get started with Native Client by letting them start making changes in a familiar C environment.

• With a few exceptions, the Makefile for each example now builds the following versions of each example:

  • glibc toolchain: 32-bit and 64-bit .nexes for the x86 target architecture
  • newlib toolchain: 32-bit and 64-bit .nexes for the x86 target architecture, and ARM .nexe for the ARM architecture
  • pnacl toolchain: .pexe (which is subsequently tranlsated to .nexes for the x86-32, x86-64, and ARM architectures)
  • hosted toolchain: .so or .dll (to be executed as a Pepper plug-in in Chrome)
• Additionally, each version is built in both a Debug and a Release configuration.
• The Makefile for each example includes two new targets: make RUN and make LAUNCH. These targets, which are interchangeable, launch a local server and an instance of Chrome to run an example. When the instance of Chrome is closed, the local server is shut down as well.
• The hello_world_stdio example includes a simplified Makefile that only lists source dependencies, and invokes the build rules in a separate file (common.mk).

Build tools and toolchains

• The SDK includes a new, experimental toolchain called PNaCl (pronounced “pinnacle”). The PNaCl toolchain produces architecture-independent executable files (.pexe files). Chrome doesn’t yet support .pexe files directly, but if you want to experiment with this early preview of PNaCl, the toolchain includes a tool to translate .pexe files into architecture-specific .nexe files. Take a look at the hello_world example to see how to build a .pexe file and translate it into multiple .nexe files. Note that PNaCl is currently restricted to the newlib C standard library – if your application uses glibc, you can’t build it with PNaCl.
• The create_nmf.py script uses ELF headers (rather than file names) to determine the architecture of .nexe files. That means you can change the names of your .nexe files and create_nmf.py will still be able to generate the appropriate Native Client manifest file for your application.

Examples

• The SDK examples now build with four toolchains: the glibc and newlib toolchains, the experimental PNaCl toolchain, and the hosted toolchain on your development machine. Within each toolchain build, each example also builds both a debug and a release version.
• The example Makefiles use dependency (.d) files to enable incremental builds.
• The pong example has been cleaned up and modified to run more smoothly. The drawing function is now set up as the Flush() callback, which allows 2D drawing to occur as quickly as possible.

PPAPI

• When creating a 3D rendering context, the attribute list for the context can specify whether to prefer low power or performance for the GPU. Contexts with a low power preference may be created on an integrated GPU; contexts with a performance preference may be created on a discrete GPU.

Windows SDK

• The Windows SDK includes the pthreads-win32 library to assist in porting from win32 code. You can use this library when developing your module as a Pepper plug-in (.dll). See pepper_24/include/win/pthread.h and pepper_24/src/pthread/README for additional information.
• The update utility naclsdk.bat works when it is run from a path with spaces.

Tools

• The nacl-gdb debugger now works on all systems (Mac, Windows, and Linux).
• The output of the SDK update utility has been simplified. When you run the command naclsdk list, the utility displays one line for each available bundle, annotated with an “I” if the bundle is already installed on your system, and a “*” if the bundle has an update available. To see full information about a bundle, use the command naclsdk info <bundle> (for example, naclsdk info pepper_28).

Linux SDK

• Developers using the Linux SDK now have resources, including pre-built libraries and example Makefiles, that make it easier to build a module as a Pepper plugin (sometimes called a “trusted” or “in-process” plugin) using the native C/C++ compiler on their development system. In essence this makes developing a Native Client module a two-step process:

  1. Build the module into a shared library (.so file) using your system’s C/C++ compiler. Test and debug the .so file using the tools in your normal development environment.
  2. Build the module into a .nexe file using the compiler from one of the Native Client toolchains in the SDK (nacl-gcc or nacl-g++). Test and debug the .nexe file using nacl-gdb.

  This two step development process has many benefits—in particular, you can use the compilers, debuggers, profilers, and other tools that you’re already familiar with. But there are a few potential issues to keep in mind:

  • Chrome uses different threading models for trusted plugins and Native Client modules.
  • Certain operations such as platform-specific library calls and system calls may succeed during trusted development, but fail in Native Client.

  Here are the resources you can use to build your module into a Pepper plugin:

  • header files are in pepper_23/include
  • source files are in pepper_23/src
  • pre-built libraries are in pepper_23/lib

  You can now build and run most of the examples in the SDK as Pepper plugins.

  • Look at the example Makefiles or run make in the example directories to see the commands and flags used to build modules as Pepper plugins.
  • Run make LAUNCH in the example directories to see how to use the --register-pepper-plugins argument to load a Pepper plugin in Chrome. Note that you must set the CHROME_PATH environment variable and start a local server prior to running this command.

Examples

• On Linux and Windows systems, most of the examples now build with three toolchains: the Native Client glibc and newlib toolchains, and the native toolchain on the host system. Modules built with the native toolchain on the host system can only run as Pepper plugins.
• All examples in the SDK now comply with version 2 of the Chrome Web Store manifest file format. By default, applications that use version 2 of the manifest file format apply a strict content security policy, which includes a restriction against inline JavaScript. This restriction prohibits both inline <script> blocks and inline event handlers (e.g., <button onclick="...">). See Manifest Version for a list of changes between version 1 and version 2 of the manifest file format, and a support schedule for applications that use version 1.

PPAPI

• PP_InputEvent_Modifier has two new enum values (_ISLEFT and _ISRIGHT).
• The memory leak in the WebSocket API has been fixed.

Tools

• The SDK now includes a command-line debugger that you can use to debug Native Client modules. See Debugging with nacl-gdb for instructions on how to use this debugger. For now, nacl-gdb only works on 64-bit Windows, 64-bit Linux, and 32-bit Linux systems. Support for Mac and 32-bit Windows systems will be added soon.

Windows SDK

• Developers using the Windows SDK can now build a module as a Pepper plugin (sometimes called a “trusted” or “in-process” plugin) using the native C/C++ compiler on their development system. In essence this makes developing a Native Client module a two-step process:

  1. Build the module into a DLL using your system’s C/C++ compiler. Test and debug the DLL using the tools in your normal development environment.
  2. Build the module into a .nexe using the compiler from one of the Native Client toolchains in the SDK (nacl-gcc or nacl-g++). Test and debug the .nexe using nacl-gdb.

  This two step development process has many benefits—in particular, you can use the compilers, debuggers, profilers, and other tools that you’re already familiar with. But there are a few potential issues to keep in mind:

  • Some libraries that are commonly used with Native Client may not build easily on Windows.
  • You may need to put in extra effort to get source code to compile with multiple compilers, e.g., Microsoft Visual Studio and GCC.
  • Chrome uses different threading models for trusted plugins and Native Client modules.
  • Certain operations such as platform-specific library calls and system calls may succeed during trusted development, but fail in Native Client.

  Here are the resources you can use to build your module into a DLL:

  • header files are in pepper_22\include
  • source files are in pepper_22\src
  • pre-built libraries are in pepper_22\lib
• A Visual Studio add-in will be available in the near future with configurations that include platforms for both Pepper plugins and NaCl modules.

Examples

• Each example in the SDK now builds both a debug and a release version. As before, most examples also build newlib and glibc versions, which means that there are now four versions for each example. Take a look at the Makefiles in the examples to see the compiler flags that are used for debug and release versions. For a description of those flags, see Compile flags for different development scenarios.
• Comments have been added to common.js, which is used in all the examples. The JavaScript in common.js inserts an <embed> element that loads the NaCl module in each example’s web page, attaches event listeners to monitor the loading of the module, and implements handleMessage() to respond to messages sent from the NaCl module to the JavaScript side of the application

PPAPI

• The CompletionCallbackFactory class template now takes a thread traits class as its second parameter. For details see the CompletionCallbackFactory class template reference.