src/native_client_sdk/src/doc/sdk/examples.rst

   1 .. _sdk-examples-2:
   2
   3 Running the SDK Examples
   4 ========================
   5
   6 Every Native Client SDK bundle comes with a folder of example applications.
   7 Each example demonstrates one or two key Native Client programming concepts.
   8 After you've :doc:`downloaded the SDK <download>`, follow the instructions
   9 on this page to build and run the examples.
  10
  11 Configure 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
  49 Build the SDK examples
  50 ----------------------
  51
  52 Starting with the ``pepper_24`` bundle, the Makefile scripts for the SDK
  53 examples build multiple versions of the examples using all three SDK
  54 toolchains (newlib, glibc, and PNaCl) and in both release and debug
  55 configurations.  (Note that some examples build only with the particular
  56 toolchains).
  57
  58 To build all the examples, go to the examples directory in a specific SDK
  59 bundle 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
  80 Calling ``make`` from inside a particular example's directory will build only
  81 that 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
  93 You can call ``make`` with the ``TOOLCHAIN`` and ``CONFIG`` parameters to
  94 override 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
 103 You can also set ``TOOLCHAIN`` to "all" to build one or more examples with
 104 all 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
 142 After running ``make``, each example directory will contain one or more of
 143 the 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
 149 For the newlib and glibc toolchains the Debug and Release subdirectories
 150 contain .nexe files for all target architectures. For the PNaCl toolchain
 151 they contain a single .pexe file. PNaCl debug also produces pre-translated
 152 .nexe files, for ease of debugging. All Debug and Release directories contain
 153 a manifest (.nmf) file that references the associated .nexe or .pexe files.
 154 For information about Native Client manifest files, see the :doc:`Technical
 155 Overview <../overview>`.
 156
 157 For 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
 159 use the SDK toolchain itself, see :doc:`Building Native Client Modules
 160 <../devguide/devcycle/building>`.
 161
 162 .. _running_the_sdk_examples:
 163
 164 Run the SDK examples
 165 --------------------
 166
 167 To run the SDK examples, you can use the ``make run`` command::
 168
 169   $ cd pepper_31/examples/api/core
 170   $ make run
 171
 172 This will launch a local HTTP server which will serve the data for the
 173 example. It then launches Chrome with the address of this server, usually
 174 http://localhost:5103. After you close Chrome, the local HTTP server is
 175 automatically shutdown.
 176
 177 This 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
 179 this::
 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
 184 Set the CHROME_PATH environment variable to the location of your Chrome
 185 executable.
 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
 212 You 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
 219 Run the SDK examples as packaged apps
 220 -------------------------------------
 221
 222 Each example can also be launched as a packaged app. For more information about
 223 using 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
 228 Some Pepper features, such as TCP/UDP socket access, are only allowed in
 229 packaged apps. The examples that use these features must be run as packaged
 230 apps, by using the ``make run_package`` command::
 231
 232   $ make run_package
 233
 234 You can use ``TOOLCHAIN`` and ``CONFIG`` parameters as above to run with a
 235 different toolchain or configuration.
 236
 237
 238 .. _debugging_the_sdk_examples:
 239
 240 Debugging the SDK examples
 241 --------------------------
 242
 243 The NaCl SDK uses `GDB <https://www.gnu.org/software/gdb/>`_ to debug Native
 244 Client code. The SDK includes a prebuilt version of GDB that is compatible with
 245 NaCl code. To use it, run the ``make debug`` command from an example directory::
 246
 247   $ make debug
 248
 249 This will launch Chrome with the ``--enable-nacl-debug`` flag set. This flag
 250 will cause Chrome to pause when a NaCl module is first loaded, waiting for a
 251 connection from gdb. The ``make debug`` command also simultaneously launches
 252 GDB and loads the symbols for that NEXE. To connect GDB to Chrome, in the GDB
 253 console, type::
 254
 255   (gdb) target remote :4014
 256
 257 This tells GDB to connect to a TCP port on localhost:4014--the port that
 258 Chrome is listening on. GDB will respond::
 259
 260   Remote debugging using :4014
 261   0x000000000fa00080 in ?? ()
 262
 263 At this point, you can use the standard GDB commands to debug your NaCl module.
 264 The 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
 267 application.
 268
 269
 270 .. |menu-icon| image:: /images/menu-icon.png
 271 .. |gear-icon| image:: /images/gear-icon.png