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