1.. _sdk-examples-2: 2 3Running the SDK Examples 4======================== 5 6Every Native Client SDK bundle comes with a folder of example applications. 7Each example demonstrates one or two key Native Client programming concepts. 8After you've :doc:`downloaded the SDK <download>`, follow the instructions 9on this page to build and run the examples. 10 11Configure the Google Chrome Browser 12----------------------------------- 13 14#. Your version of Chrome must be equal to or greater than the version of 15 your SDK bundle. For example, if you're developing with the ``pepper_31`` 16 bundle, you must use Google Chrome version 31 or greater. To find out what 17 version of Chrome you're using, type ``about:chrome`` or ``about:version`` 18 in the Chrome address bar. 19 20#. For Portable Native Client, no extra Chrome flags are needed as of 21 Chrome version 31. 22 23 For other Native Client applications, or to **debug** Portable Native 24 Client applications by translating the **pexe** to a **nexe** ahead of 25 time, enable the Native Client flag. Native Client is enabled by default 26 only for applications distributed through the Chrome Web Store. To run 27 Native Client applications that are not distributed through the Chrome 28 Web Store, like the SDK examples, you must specifically enable the Native 29 Client flag in Chrome: 30 31 * Type ``about:flags`` in the Chrome address bar and scroll down to 32 "Native Client". 33 * If the link below "Native Client" says "Disable", then Native Client is 34 already enabled and you don't need to do anything else. 35 * If the link below "Native Client" says "Enable", click the "Enable" 36 link, scroll down to the bottom of the page, and click the "Relaunch 37 Now" button. All browser windows will restart when you relaunch Chrome. 38 39#. Disable the Chrome cache. Chrome caches resources aggressively; when you 40 are building a Native Client application you should disable the cache to 41 make sure that Chrome loads the latest version: 42 43 * Open Chrome's developer tools by clicking the menu icon |menu-icon| and 44 choosing Tools > Developer tools. 45 * Click the gear icon |gear-icon| in the bottom right corner of the 46 Chrome window. 47 * Under the "General" settings, check the box next to "Disable cache". 48 49Build the SDK examples 50---------------------- 51 52Starting with the ``pepper_24`` bundle, the Makefile scripts for the SDK 53examples build multiple versions of the examples using all three SDK 54toolchains (newlib, glibc, and PNaCl) and in both release and debug 55configurations. (Note that some examples build only with the particular 56toolchains). 57 58To build all the examples, go to the examples directory in a specific SDK 59bundle and run ``make``:: 60 61 $ cd pepper_31/examples 62 $ make 63 make -C api all 64 make[1]: Entering directory `pepper_31/examples/api' 65 make -C audio all 66 make[2]: Entering directory `pepper_31/examples/api/audio' 67 CXX newlib/Debug/audio_x86_32.o 68 LINK newlib/Debug/audio_x86_32.nexe 69 CXX newlib/Debug/audio_x86_64.o 70 LINK newlib/Debug/audio_x86_64.nexe 71 CXX newlib/Debug/audio_arm.o 72 LINK newlib/Debug/audio_arm.nexe 73 CREATE_NMF newlib/Debug/audio.nmf 74 make[2]: Leaving directory `pepper_31/examples/api/audio' 75 make -C url_loader all 76 make[2]: Entering directory `pepper_31/examples/api/url_loader' 77 CXX newlib/Debug/url_loader_x86_32.o 78 ... 79 80Calling ``make`` from inside a particular example's directory will build only 81that example:: 82 83 $ cd pepper_31/examples/api/core 84 $ make 85 CXX newlib/Debug/core_x86_32.o 86 LINK newlib/Debug/core_x86_32.nexe 87 CXX newlib/Debug/core_x86_64.o 88 LINK newlib/Debug/core_x86_64.nexe 89 CXX newlib/Debug/core_arm.o 90 LINK newlib/Debug/core_arm.nexe 91 CREATE_NMF newlib/Debug/core.nmf 92 93You can call ``make`` with the ``TOOLCHAIN`` and ``CONFIG`` parameters to 94override the defaults:: 95 96 $ make TOOLCHAIN=pnacl CONFIG=Release 97 CXX pnacl/Release/core_pnacl.o 98 LINK pnacl/Release/core.bc 99 FINALIZE pnacl/Release/core.pexe 100 CREATE_NMF pnacl/Release/core.nmf 101 102 103You can also set ``TOOLCHAIN`` to "all" to build one or more examples with 104all available toolchains:: 105 106 $ make TOOLCHAIN=all 107 make TOOLCHAIN=newlib 108 make[1]: Entering directory `pepper_31/examples/api/core' 109 CXX newlib/Debug/core_x86_32.o 110 LINK newlib/Debug/core_x86_32.nexe 111 CXX newlib/Debug/core_x86_64.o 112 LINK newlib/Debug/core_x86_64.nexe 113 CXX newlib/Debug/core_arm.o 114 LINK newlib/Debug/core_arm.nexe 115 CREATE_NMF newlib/Debug/core.nmf 116 make[1]: Leaving directory `pepper_31/examples/api/core' 117 make TOOLCHAIN=glibc 118 make[1]: Entering directory `pepper_31/examples/api/core' 119 CXX glibc/Debug/core_x86_32.o 120 LINK glibc/Debug/core_x86_32.nexe 121 CXX glibc/Debug/core_x86_64.o 122 LINK glibc/Debug/core_x86_64.nexe 123 CREATE_NMF glibc/Debug/core.nmf 124 make[1]: Leaving directory `pepper_31/examples/api/core' 125 make TOOLCHAIN=pnacl 126 make[1]: Entering directory `pepper_31/examples/api/core' 127 CXX pnacl/Debug/core_pnacl.o 128 LINK pnacl/Debug/core.bc 129 FINALIZE pnacl/Debug/core.pexe 130 TRANSLATE pnacl/Debug/core_x86_32.nexe 131 TRANSLATE pnacl/Debug/core_x86_64.nexe 132 TRANSLATE pnacl/Debug/core_arm.nexe 133 CREATE_NMF pnacl/Debug/core.nmf 134 make[1]: Leaving directory `pepper_31/examples/api/core' 135 make TOOLCHAIN=linux 136 make[1]: Entering directory `pepper_31/examples/api/core' 137 CXX linux/Debug/core.o 138 LINK linux/Debug/core.so 139 make[1]: Leaving directory `pepper_31/examples/api/core' 140 141 142After running ``make``, each example directory will contain one or more of 143the following subdirectories: 144 145* a ``newlib`` directory with subdirectories ``Debug`` and ``Release``; 146* a ``glibc`` directory with subdirectories ``Debug`` and ``Release``; 147* a ``pnacl`` directory with subdirectories ``Debug`` and ``Release``; 148 149For the newlib and glibc toolchains the Debug and Release subdirectories 150contain .nexe files for all target architectures. For the PNaCl toolchain 151they contain a single .pexe file. PNaCl debug also produces pre-translated 152.nexe files, for ease of debugging. All Debug and Release directories contain 153a manifest (.nmf) file that references the associated .nexe or .pexe files. 154For information about Native Client manifest files, see the :doc:`Technical 155Overview <../overview>`. 156 157For details on how to use ``make``, see the `GNU 'make' Manual 158<http://www.gnu.org/software/make/manual/make.html>`_. For details on how to 159use the SDK toolchain itself, see :doc:`Building Native Client Modules 160<../devguide/devcycle/building>`. 161 162.. _running_the_sdk_examples: 163 164Run the SDK examples 165-------------------- 166 167To run the SDK examples, you can use the ``make run`` command:: 168 169 $ cd pepper_31/examples/api/core 170 $ make run 171 172This will launch a local HTTP server which will serve the data for the 173example. It then launches Chrome with the address of this server, usually 174http://localhost:5103. After you close Chrome, the local HTTP server is 175automatically shutdown. 176 177This command will try to find an executable named ``google-chrome`` in your 178``PATH`` environment variable. If it can't, you'll get an error message like 179this:: 180 181 pepper_31/tools/common.mk:415: No valid Chrome found at CHROME_PATH= 182 pepper_31/tools/common.mk:415: *** Set CHROME_PATH via an environment variable, or command-line.. Stop. 183 184Set the CHROME_PATH environment variable to the location of your Chrome 185executable. 186 187* On Windows: 188 189 The default install location of Chrome is 190 ``C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`` for Chrome 191 stable and 192 ``C:\Users\<username>\AppData\Local\Google\Chrome SxS\Application\chrome.exe`` 193 for Chrome Canary; try looking in those directories first:: 194 195 > set CHROME_PATH=<Path to chrome.exe> 196 197* On Linux:: 198 199 $ export CHROME_PATH=<Path to google-chrome> 200 201* On Mac: 202 203 The default install location of Chrome is 204 ``/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`` for 205 Chrome Stable and 206 ``Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary`` 207 for Chrome Canary. Note that you have to reference the executable inside the 208 application bundle, not the top-level ``.app`` directory:: 209 210 $ export CHROME_PATH=<Path to Google Chrome> 211 212You can run via a different toolchain or configuration by using the 213``TOOLCHAIN`` and ``CONFIG`` parameters to make:: 214 215 $ make run TOOLCHAIN=pnacl CONFIG=Debug 216 217.. _run_sdk_examples_as_packaged: 218 219Run the SDK examples as packaged apps 220------------------------------------- 221 222Each example can also be launched as a packaged app. For more information about 223using Native Client for packaged apps, see :ref:`Packaged appliction 224<distributing_packaged>`. For general information about packaged apps, see the 225`Chrome apps documentation 226<http://developer.chrome.com/apps/about_apps.html>`_. 227 228Some Pepper features, such as TCP/UDP socket access, are only allowed in 229packaged apps. The examples that use these features must be run as packaged 230apps, by using the ``make run_package`` command:: 231 232 $ make run_package 233 234You can use ``TOOLCHAIN`` and ``CONFIG`` parameters as above to run with a 235different toolchain or configuration. 236 237 238.. _debugging_the_sdk_examples: 239 240Debugging the SDK examples 241-------------------------- 242 243The NaCl SDK uses `GDB <https://www.gnu.org/software/gdb/>`_ to debug Native 244Client code. The SDK includes a prebuilt version of GDB that is compatible with 245NaCl code. To use it, run the ``make debug`` command from an example directory:: 246 247 $ make debug 248 249This will launch Chrome with the ``--enable-nacl-debug`` flag set. This flag 250will cause Chrome to pause when a NaCl module is first loaded, waiting for a 251connection from gdb. The ``make debug`` command also simultaneously launches 252GDB and loads the symbols for that NEXE. To connect GDB to Chrome, in the GDB 253console, type:: 254 255 (gdb) target remote :4014 256 257This tells GDB to connect to a TCP port on localhost:4014--the port that 258Chrome is listening on. GDB will respond:: 259 260 Remote debugging using :4014 261 0x000000000fa00080 in ?? () 262 263At this point, you can use the standard GDB commands to debug your NaCl module. 264The most common commands you will use to debug are ``continue``, ``step``, 265``next``, ``break`` and ``backtrace``. See :doc:`Debugging 266<../devguide/devcycle/debugging>` for more information about debugging a Native Client 267application. 268 269 270.. |menu-icon| image:: /images/menu-icon.png 271.. |gear-icon| image:: /images/gear-icon.png 272
