native_client_sdk/src/doc/sdk/examples.rst

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