1 .. _sdk-release-notes: 2 3 ############# 4 Release Notes 5 ############# 6 7 This page provides notes for all releases of the Native Client SDK (including 8 releases that have been or will be published subsequent to Pepper 28). 9 10 PNaCl enabled by default in Chrome 31 (12 Nov 2013) 11 =================================================== 12 13 * Portable Native Client (PNaCl) is enabled by default in Chrome 31. See 14 :doc:`NaCl and PNaCl </nacl-and-pnacl>` for details on the differences between 15 PNaCl and NaCl. 16 * The PNaCl ABI has changed from the preview release in Chrome 17 version 30. If you have pexes built with the Native Client SDK version 30, 18 please recompile them with the newest SDK to run in Chrome 31. As a general 19 rule, it is always recommended to build applications with the latest Native 20 Client SDK. The PNaCl ABI will remain stable starting with the release of 21 Chrome 31. 22 23 Additional changes: 24 25 * Updates to the Pepper API, including socket and network support. 26 * Improved socket support in nacl_io. 27 28 PNaCl in Chrome 30 Dev channel (01 Aug 2013) 29 ============================================ 30 31 * Portable Native Client (PNaCl) is currently available for preview in Chrome 32 30 (currently in the Dev channel). Apps and sites built with PNaCl can run in 33 Chrome 30 without an explicit flag. 34 * See `Introduction to Portable Native Client 35 <http://www.chromium.org/nativeclient/pnacl/introduction-to-portable-native-client>`_ 36 for information on developing for PNaCl. More documentation will be available 37 soon. 38 * Please note that the `PNaCl bitcode ABI 39 <http://www.chromium.org/nativeclient/pnacl/bitcode-abi>`_ may still change 40 before the official public release; if you're developing a PNaCl-based 41 application, be sure to build your code with the latest version of the Native 42 Client SDK. 43 * Update: PNaCl is not enabled by default in beta or stable versions of M30. 44 45 PNaCl (15 May 2013) 46 =================== 47 48 * Portable Native Client (PNaCl) is currently available for developer preview 49 in Chrome 29 or higher. 50 * To produce a PNaCl executable (.pexe) file, you must use the pnacl toolchain 51 in the current ``pepper_canary`` bundle. Chrome 29 does not support .pexe 52 files produced by earlier versions of the pnacl toolchain (that is, 53 executables compiled with the ``pepper_28`` bundle or earlier). 54 * To run an application with a PNaCl module, you must launch Chrome 29 with the 55 ``--enable-pnacl`` flag (for `packaged apps 56 <http://developer.chrome.com/apps/about_apps.html>`_), or the 57 ``--enable-nacl`` flag (for other apps). 58 * When you launch Chrome with the ``--enable-pnacl`` flag, Chrome loads a PNaCl 59 translator in the background. Wait about a minute after you launch Chrome and 60 check `chrome://nacl <chrome://nacl>`_ to verify that the translator loaded. 61 * PNaCl translators are currently available for 32-bit x86, 64-bit x86, and ARM 62 architectures. 63 * PNaCl applications must use the newlib C library (glibc and dynamic linking 64 are not supported yet). 65 * The intermediate representation (IR) format may change prior to the release 66 of PNaCl. If so, you will need to recompile your application with the pnacl 67 toolchain in a new SDK bundle. 68 69 Pepper 27 (12 April 2013) 70 ========================= 71 72 The Pepper 27 bundle features a significant number of new libraries that have 73 been incorporated directly into the SDK. 74 75 Libraries 76 --------- 77 78 * A number of libraries from the naclports project have been incorporated 79 directly into the Native Client SDK. These libraries include: 80 81 * image encoding/decoding: jpeg, tiff, png, webp 82 * multimedia: openal, freealut, ogg, vorbis 83 * XML parsing: tinyxml, xml2 84 * miscellaneous: zlib (general purpose compression), freetype (font 85 rendering), lua (Lua interpreter) 86 87 The libraries are located in ``ports/lib``, and the header files are in 88 ``ports/include``. 89 90 * The ``httpfs`` filesystem in the nacl_io library now caches content in memory 91 by default; this improves performance considerably. 92 * For applications compiled with a glibc toolchain, ``dlopen()`` can now be 93 used to open shared libraries that are not specified in an application's 94 Native Client manifest (.nmf) file. This allows applications, for example, to 95 download a shared object and then use ``dlopen()`` to access the shared 96 object. The ``dlopen`` example has been modified to demonstrate this 97 functionality: reverse.cc is built into a shared object (.so) file, which is 98 downloaded and opened using an ``httpfs`` mount. 99 100 Examples 101 -------- 102 103 * Each example now has a single ``index.html`` file, instead of multiple HTML 104 files corresponding to NaCl modules built using different toolchains and 105 configurations. By default, most examples are built using one toolchain 106 (newlib) and one configuration (Debug). If you build an example using 107 multiple toolchains or configurations, you can specify which version to run 108 in Chrome using the query parameters ``tc`` and ``config``. For example, 109 assuming you are serving an example from the local server localhost:5103, you 110 can run a version of the example built with the glibc toolchain in the 111 Release configuration by specifying the following URL in Chrome: 112 ``http://localhost:5103/index.html?tc=glibc&config=Release``. For additional 113 information about how different NaCl modules are loaded into ``index.html``, 114 see the ``common.js`` file in each example. 115 116 Build tools and toolchains 117 -------------------------- 118 119 * Common makefiles, including ``tools/common.mk``, can now handle source files 120 located outside of an application's root directory. For example, a Makefile 121 for an application can specify a source file to compile such as 122 ``../../some/other/place.cpp``. 123 124 Pepper 26 (29 March 2013) 125 ========================= 126 127 The Pepper 26 bundle includes a new HTTP filesystem type in the nacl_mounts 128 library (which has been renamed nacl_io), changes to the example Makefiles, a 129 simple new 3D example, and a threaded file IO example. 130 131 Build tools and toolchains 132 -------------------------- 133 134 * Makefiles have been changed significantly: 135 136 * Build commands are now specified in a number of common files 137 (``tools/*.mk``), which are included in the Makefiles in the examples. 138 * By default, make displays a simplified list of build steps (e.g., ``CC 139 newlib/Debug/hello_world_x86_32.o``) rather than the actual build commands. 140 To see the actual build commands, run ``make V=1``. 141 * By default, most examples are built using one toolchain (newlib) and one 142 configuration (Debug). To build an example using a different toolchain or 143 configuration, run ``make`` with the parameters ``TOOLCHAIN=<x>`` or 144 ``CONFIG=<y>``. You can also run make ``all_versions`` to build an example 145 with all toolchains. 146 147 * Header files have been moved out of the toolchains. All toolchains now share 148 the same set of header files as host builds. Previously host and NaCl builds 149 used different headers, which could cause build problems. 150 151 Libraries 152 --------- 153 154 * The nacl_mounts library has been renamed **nacl_io**, and has been expanded 155 with a new type of mount, httpfs, which can be used to read URLs via HTTP. 156 For details see ``include/nacl_io/nacl_io.h``, as well as the 157 ``hello_nacl_io`` example. 158 159 Examples 160 -------- 161 162 * A new example, **hello_world_instance3d**, has been added to demonstrate a 163 simplified 3D app. 164 * The **file_io** example has been rewritten to do all file operations on a 165 thread. The example demonstrates how to use the MessageLoop API and blocking 166 callbacks on a thread. 167 168 General 169 ------- 170 171 * Old bundles (``pepper_20`` and earlier) have been removed from the Native 172 Client SDK Manifest, and will no longer be updated by the ``naclsdk`` 173 command. 174 175 Pepper 25 (21 December 2012) 176 ============================ 177 178 The Pepper 25 bundle features an ARM toolchain to build Native Client modules 179 for ARM devices, two new Pepper APIs (including the MessageLoop API, which lets 180 you make Pepper calls on background threads), two new libraries (nacl_mounts, 181 which provides a virtual file system that you can use with standard C file 182 operations, and ppapi_main, which lets you implement a Native Client module 183 using a simple ppapi_main function), and two new examples that demonstrate how 184 to use the nacl_mounts and ppapi_main libraries. 185 186 Build tools and toolchains 187 -------------------------- 188 189 * The SDK includes a new toolchain to build Native Client executables (.nexe 190 files) for **ARM devices**. 191 192 * Currently the ARM toolchain can only be used to compile modules that use 193 the :ref:`newlib C library <c_libraries>`. You cannot use the ARM toolchain 194 to compile modules that use the glibc library. 195 * The ARM toolchain is in the directory 196 ``pepper_25/toolchain/<host>_arm_newlib``. The bin subdirectory contains 197 the compiler (``arm-nacl-gcc``), the linker (``arm-nacl-g++``), and the 198 other tools in the toolchain. 199 * Take a look at the ``hello_world`` example to see how to use the ARM 200 toolchain. Go to ``examples/hello_world`` and run ``make``. When the build 201 finishes, the newlib/Debug and newlib/Release subdirectories will contain 202 .nexe files for the x86-32, x86-64, and ARM target architecutes, and a 203 Native Client manifest (.nmf file) that references those three .nexe files. 204 205 * The simple web server included in the SDK, ``httpd.py``, has been moved from 206 the ``examples/`` directory to the ``tools/`` directory. On Windows, you can 207 run ``httpd.cmd`` (in the ``examples/`` directory) to start the server. 208 209 PPAPI 210 ----- 211 212 Pepper 25 includes two new APIs: 213 214 * The `Console API 215 <https://developers.google.com/native-client/dev/pepperc/struct_p_p_b___console__1__0>`_ 216 lets your module log messages to the JavaScript console in the Chrome browser. 217 * The `MessageLoop 218 <https://developers.google.com/native-client/dev/peppercpp/classpp_1_1_message_loop>`_ 219 API lets your module make PPAPI calls on a background thread. Once you've 220 created a message loop resource, attached it to a thread, and run it, you can 221 post work to the thread, including completion callbacks for asynchronous 222 operations. For a C++ example of how to use the MessageLoop API, 223 see ``pepper_25/include/ppapi/utility/threading/simple_thread.h``. Note that 224 you cannot make asynchronous PPAPI calls on a background thread without 225 creating and using a message loop. 226 227 Libraries 228 --------- 229 230 The SDK includes two new libraries: 231 232 * The **nacl_mounts** library provides a virtual file system that your module 233 can "mount" in a given directory tree. The file system can be one of several 234 types: 235 236 * "memfs" is an in-memory file system, 237 * "dev" is a file system with various utility nodes (e.g., ``/dev/null``, 238 ``/dev/console[0-3]``, ``/dev/tty``), and 239 * "html5fs" is a persistent file system. 240 241 Once you've mounted a file system in your module, you can use standard C 242 library file operations: fopen, fread, fwrite, fseek, and fclose. How those 243 operations are performed depends on the type of file system (e.g., for 244 html5fs, the operations are performed using the Pepper FileIO API). For a 245 list of the types of file systems you can mount, see 246 include/nacl_mounts/nacl_mounts.h. For an example of how to use nacl_mounts, 247 see examples/hello_nacl_mounts. Note that html5fs is subject to the same 248 constraints as persistent :ref:`local file IO <devguide-coding-fileio>` in 249 Chrome (for example, prior to using an html5fs file system, you must `enable 250 local file IO <enabling_file_access>`_). 251 252 * The **ppapi_main** library simplifies the creation of a NaCl module by 253 providing a familiar C programming environment. With this library, your 254 module can have a simple entry point called ppapi_main(), which is similar to 255 the standard C main() function, complete with argc and argv[] parameters. 256 Your module can also use standard C functions such as printf(), fopen(), and 257 fwrite(). For details see include/ppapi_main/ppapi_main.h. For an example of 258 how to use ppapi_main, see examples/hello_world_stdio. 259 260 Header files for the new libraries are in the ``include/`` directory, source 261 files are in the ``src/`` directory, and compiled libraries are in the ``lib/`` 262 directory. 263 264 Examples 265 -------- 266 267 * The SDK includes two new examples: 268 269 * **hello_nacl_mounts** illustrates how to use standard C library file 270 operations in a Native Client module through the use of the nacl_mounts 271 library. 272 * **hello_world_stdio** illustrates how to implement a Native Client module 273 with a ppapi_main() function, and how to write to STDOUT and STDERR in a 274 module, through the use of the nacl_mounts and ppapi_main libraries. This 275 example makes it easy for new users to get started with Native Client by 276 letting them start making changes in a familiar C environment. 277 278 * With a few exceptions, the Makefile for each example now builds the following 279 versions of each example: 280 281 * glibc toolchain: 32-bit and 64-bit .nexes for the x86 target architecture 282 * newlib toolchain: 32-bit and 64-bit .nexes for the x86 target architecture, 283 and ARM .nexe for the ARM architecture 284 * pnacl toolchain: .pexe (which is subsequently tranlsated to .nexes for the 285 x86-32, x86-64, and ARM architectures) 286 * hosted toolchain: .so or .dll (to be executed as a Pepper plug-in in 287 Chrome) 288 289 * Additionally, each version is built in both a Debug and a Release 290 configuration. 291 * The Makefile for each example includes two new targets: ``make RUN`` and 292 ``make LAUNCH``. These targets, which are interchangeable, launch a local 293 server and an instance of Chrome to run an example. When the instance of 294 Chrome is closed, the local server is shut down as well. 295 * The hello_world_stdio example includes a simplified Makefile that only lists 296 source dependencies, and invokes the build rules in a separate file 297 (common.mk). 298 299 Pepper 24 (5 December 2012) 300 =========================== 301 302 The Pepper 24 bundle features a new, experimental toolchain called PNaCl (short 303 for "Portable Native Client"), a new library (pthreads-win32) for the Windows 304 SDK, and an expanded list of attributes for Pepper 3D contexts that lets 305 applications specify a GPU preference for low power or performance. 306 307 Build tools and toolchains 308 -------------------------- 309 310 * The SDK includes a new, experimental toolchain called `PNaCl 311 <http://nativeclient.googlecode.com/svn/data/site/pnacl.pdf>`_ (pronounced 312 "pinnacle"). The PNaCl toolchain produces architecture-independent executable 313 files (.pexe files). Chrome doesn't yet support .pexe files directly, but if 314 you want to experiment with this early preview of PNaCl, the toolchain 315 includes a tool to translate .pexe files into architecture-specific .nexe 316 files. Take a look at the ``hello_world`` example to see how to build a .pexe 317 file and translate it into multiple .nexe files. Note that PNaCl is currently 318 restricted to the newlib C standard library if your application uses glibc, 319 you can't build it with PNaCl. 320 * The ``create_nmf.py`` script uses ELF headers (rather than file names) to 321 determine the architecture of .nexe files. That means you can change the 322 names of your .nexe files and ``create_nmf.py`` will still be able to 323 generate the appropriate Native Client manifest file for your application. 324 325 Examples 326 -------- 327 328 * The SDK examples now build with four toolchains: the glibc and newlib 329 toolchains, the experimental PNaCl toolchain, and the hosted toolchain on 330 your development machine. Within each toolchain build, each example also 331 builds both a debug and a release version. 332 * The example Makefiles use dependency (.d) files to enable incremental builds. 333 * The pong example has been cleaned up and modified to run more smoothly. The 334 drawing function is now set up as the Flush() callback, which allows 2D 335 drawing to occur as quickly as possible. 336 337 PPAPI 338 ----- 339 340 * When creating a 3D rendering context, the `attribute list 341 <https://developers.google.com/native-client/dev/pepperc/group___enums#ga7df48e1c55f6401beea2a1b9c07967e8>`_ 342 for the context can specify whether to prefer low power or performance for 343 the GPU. Contexts with a low power preference may be created on an integrated 344 GPU; contexts with a performance preference may be created on a discrete GPU. 345 346 Windows SDK 347 ----------- 348 349 * The Windows SDK includes the pthreads-win32 library to assist in porting from 350 win32 code. You can use this library when developing your module as a Pepper 351 plug-in (.dll). See pepper_24/include/win/pthread.h and 352 pepper_24/src/pthread/README for additional information. 353 * The update utility naclsdk.bat works when it is run from a path with spaces. 354 355 Pepper 23 (15 October 2012) 356 =========================== 357 358 The Pepper 23 bundle includes support for the nacl-gdb debugger on Mac and 359 32-bit Windows, resources to enable hosted development on Linux, and changes to 360 make the SDK examples compliant with version 2 of the Chrome Web Store manifest 361 file format. 362 363 Tools 364 ----- 365 366 * The `nacl-gdb debugger 367 <https://developers.google.com/native-client/pepper23/devguide/devcycle/debugging#gdb>`_ 368 now works on all systems (Mac, Windows, and Linux). 369 370 * The output of the SDK update utility has been simplified. When you run the 371 command ``naclsdk list``, the utility displays one line for each available 372 bundle, annotated with an "``I``" if the bundle is already installed on your 373 system, and a "``*``" if the bundle has an update available. To see full 374 information about a bundle, use the command ``naclsdk info <bundle>`` (for 375 example, ``naclsdk info pepper_28``). 376 377 Linux SDK 378 --------- 379 380 * Developers using the Linux SDK now have resources, including pre-built 381 libraries and example Makefiles, that make it easier to **build a module as a 382 Pepper plugin** (sometimes called a "trusted" or "in-process" plugin) using 383 the native C/C++ compiler on their development system. In essence this makes 384 developing a Native Client module a two-step process: 385 386 #. Build the module into a shared library (.so file) using your system's 387 C/C++ compiler. Test and debug the .so file using the tools in your normal 388 development environment. 389 #. Build the module into a .nexe file using the compiler from one of the 390 Native Client toolchains in the SDK (nacl-gcc or nacl-g++). Test and debug 391 the .nexe file using nacl-gdb. 392 393 This two step development process has many benefitsin particular, you can 394 use the compilers, debuggers, profilers, and other tools that you're already 395 familiar with. But there are a few potential issues to keep in mind: 396 397 * Chrome uses different threading models for trusted plugins and Native 398 Client modules. 399 * Certain operations such as platform-specific library calls and system calls 400 may succeed during trusted development, but fail in Native Client. 401 402 Here are the resources you can use to build your module into a Pepper plugin: 403 404 * header files are in ``pepper_23/include`` 405 * source files are in ``pepper_23/src`` 406 * pre-built libraries are in ``pepper_23/lib`` 407 408 You can now build and run most of the examples in the SDK as Pepper plugins. 409 410 * Look at the example Makefiles or run ``make`` in the example directories to 411 see the commands and flags used to build modules as Pepper plugins. 412 * Run ``make LAUNCH`` in the example directories to see how to use the 413 ``--register-pepper-plugins`` argument to load a Pepper plugin in Chrome. 414 Note that you must set the ``CHROME_PATH`` environment variable and start a 415 :ref:`local server <web_server>` prior to running this command. 416 417 Examples 418 -------- 419 420 * On Linux and Windows systems, most of the examples now build with three 421 toolchains: the Native Client glibc and newlib toolchains, and the native 422 toolchain on the host system. Modules built with the native toolchain on the 423 host system can only run as Pepper plugins. 424 * All examples in the SDK now comply with version 2 of the Chrome Web Store 425 `manifest file format 426 <http://developer.chrome.com/extensions/manifest.html>`_. By default, 427 applications that use version 2 of the manifest file format apply a strict 428 `content security policy 429 <http://developer.chrome.com/extensions/contentSecurityPolicy.html>`_, which 430 includes a restriction against inline JavaScript. This restriction prohibits 431 both inline ``<script>`` blocks and inline event handlers (e.g., ``<button 432 onclick="...">``). See `Manifest Version 433 <http://developer.chrome.com/extensions/manifestVersion.html>`_ for a list of 434 changes between version 1 and version 2 of the manifest file format, and a 435 support schedule for applications that use version 1. 436 437 PPAPI 438 ----- 439 440 * `PP_InputEvent_Modifier 441 <https://developers.google.com/native-client/pepper23/pepperc/group___enums#ga21b811ac0484a214a8751aa3e1c959d9>`_ 442 has two new enum values (_ISLEFT and _ISRIGHT). 443 * The memory leak in the `WebSocket 444 <https://developers.google.com/native-client/pepper23/pepperc/struct_p_p_b___web_socket__1__0>`_ 445 API has been fixed. 446 447 Pepper 22 (22 August 2012) 448 ========================== 449 450 The Pepper 22 bundle includes a **command-line debugger**, resources to enable 451 **hosted development on Windows**, and changes to the example Makefiles (each 452 example now builds both a debug and a release version). 453 454 Tools 455 ----- 456 457 * The SDK now includes a **command-line debugger** that you can use to debug 458 Native Client modules. See :ref:`Debugging with nacl-gdb 459 <devcycle-debugging>` for instructions on how to use this debugger. For now, 460 nacl-gdb only works on 64-bit Windows, 64-bit Linux, and 32-bit Linux 461 systems. Support for Mac and 32-bit Windows systems will be added soon. 462 463 Windows SDK 464 ----------- 465 466 * Developers using the Windows SDK can now **build a module as a Pepper 467 plugin** (sometimes called a "trusted" or "in-process" plugin) using the 468 native C/C++ compiler on their development system. In essence this makes 469 developing a Native Client module a two-step process: 470 471 #. Build the module into a DLL using your system's C/C++ compiler. Test and 472 debug the DLL using the tools in your normal development environment. 473 #. Build the module into a .nexe using the compiler from one of the Native 474 Client toolchains in the SDK (nacl-gcc or nacl-g++). Test and debug the 475 .nexe using nacl-gdb. 476 477 This two step development process has many benefitsin particular, you can 478 use the compilers, debuggers, profilers, and other tools that you're already 479 familiar with. But there are a few potential issues to keep in mind: 480 481 * Some libraries that are commonly used with Native Client may not build 482 easily on Windows. 483 * You may need to put in extra effort to get source code to compile with 484 multiple compilers, e.g., Microsoft Visual Studio and GCC. 485 * Chrome uses different threading models for trusted plugins and Native 486 Client modules. 487 * Certain operations such as platform-specific library calls and system calls 488 may succeed during trusted development, but fail in Native Client. 489 490 Here are the resources you can use to build your module into a DLL: 491 492 * header files are in ``pepper_22\include`` 493 * source files are in ``pepper_22\src`` 494 * pre-built libraries are in ``pepper_22\lib`` 495 496 * A Visual Studio add-in will be available in the near future with 497 configurations that include platforms for both Pepper plugins and NaCl 498 modules. 499 500 .. Note:: 501 :class: note 502 503 **Note:** It's also possible to build a module as a trusted plugin on Mac and 504 Linux systems, but doing so requires more work because the SDK does not yet 505 include the above resources (library source files and pre-built libraries) 506 for Mac and Linux systems. To build and debug a trusted plugin on Mac and 507 Linux systems, you need to `get the Chromium code 508 <http://dev.chromium.org/developers/how-tos/get-the-code>`_ and then follow 509 the `Mac instructions 510 <http://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/trusted-debugging-on-mac>`_ 511 or `Linux instructions 512 <http://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin/debugging-a-trusted-plugin-on-linux>`_. 513 In the future, the SDK will include resources for hosted development on Mac 514 and Linux as well as Windows. 515 516 Examples 517 -------- 518 519 * Each example in the SDK now builds both a debug and a release version. As 520 before, most examples also build newlib and glibc versions, which means that 521 there are now four versions for each example. Take a look at the Makefiles in 522 the examples to see the compiler flags that are used for debug and release 523 versions. For a description of those flags, see :ref:`Compile flags for 524 different development scenarios <compile_flags>`. 525 * Comments have been added to common.js, which is used in all the examples. The 526 JavaScript in common.js inserts an <embed> element that loads the NaCl module 527 in each example's web page, attaches event listeners to monitor the loading 528 of the module, and implements handleMessage() to respond to messages sent 529 from the NaCl module to the JavaScript side of the application 530 531 PPAPI 532 ----- 533 534 * The ``CompletionCallbackFactory`` class template now takes a thread traits 535 class as its second parameter. For details see the `CompletionCallbackFactory 536 class template reference 537 <https://developers.google.com/native-client/pepper22/peppercpp/classpp_1_1_completion_callback_factory#details>`_. 538 539 .. TODO: Port release notes for older releases 540