src/native_client_sdk/src/doc/io2014.rst

   1 .. _io2014:
   2
   3 ###################
   4 Building a NaCl App
   5 ###################
   6
   7 In the browser!
   8 ---------------
   9
  10 Follow along with Brad Nelson's Google I/O 2014 talk.
  11 Explore our new in-browser development environment and debugger.
  12
  13 Learn how easy it is to edit, build, and debug NaCl application
  14 all in your desktop web browser or on a Chromebook.
  15 Work either on-line or off-line!
  16
  17 .. raw:: html
  18
  19   <iframe class="video" width="500" height="281"
  20   src="//www.youtube.com/embed/OzNuzBDEWzk?rel=0" frameborder="0"></iframe>
  21
  22 Work in Progress
  23 ================
  24
  25 These development tools are a work in progress, see `Feature Status`_.
  26 At this point, they are a learning tool and demonstration of NaCl's
  27 flexibility, but are not the recommended tools for a production application.
  28 To develop a substantial application for Native Client /
  29 Portable Native Client,
  30 we currently recommend you use the
  31 `Native Client SDK </native-client/sdk/download>`_.
  32
  33 .. raw:: html
  34
  35   <b><font color="#880000">
  36   NOTE: The NaCl Development Environment is not yet stable.
  37   Ideally user data is preserved, but currently it can be lost during updates
  38   or sporadically. We're working to resolve this.
  39   </font></b>
  40
  41 Installation
  42 ============
  43
  44 The setup process currently requires several steps.
  45 We're working to reduce the number of steps in future releases.
  46 As the process gets easier, we'll update this page.
  47
  48 To install the development environment:
  49
  50   * Install the `NaCl Development Environment <https://chrome.google.com/webstore/detail/nacl-development-environm/aljpgkjeipgnmdpikaajmnepbcfkglfa>`_.
  51
  52   * Navigate to: chrome://flags and:
  53
  54     * Enable **Native Client**.
  55     * Restart your browser by clicking **Relaunch Now**.
  56
  57   * First run is slow (as it downloads and installs packages). Launch and allow
  58     initial install to complete before first use.
  59
  60 When initially experimenting with the development environment,
  61 at this time, we recommend you run it without the debugger activated.
  62 Once you're ready to apply the debugger, follow these steps:
  63
  64   * Install a usable version of
  65     `Chrome Linux (M36+, Dev or Beta channel) <http://www.chromium.org/getting-involved/dev-channel>`_.
  66   * Install the `Native Client Debugger Extension <https://chrome.google.com/webstore/detail/nacl-debugger/ncpkkhabohglmhjibnloicgdfjmojkfd>`_.
  67   * Install `Native Client GDB <https://chrome.google.com/webstore/detail/gdb/gkjoooooiaohiceibmdleokniplmbahe>`_.
  68
  69   * Navigate to: chrome://flags and:
  70
  71     * Enable **Native Client GDB-based debugging**.
  72     * Restart your browser by clicking **Relaunch Now**.
  73
  74   * NOTE: If you experience unexplained hangs, disable GDB-based debugging
  75     temporarily and try again.
  76
  77 Editor
  78 ======
  79
  80 To follow along in this tutorial, you'll need to use a text editor to modify
  81 various files in our development environment.
  82 There are currently two editor options, nano or vim.
  83 Emacs is coming soon...
  84 If you're unsure what to pick, nano is simpler to start with and has on-screen
  85 help.
  86
  87 * You can open **nano** like this::
  88
  89     $ nano <filename>
  90
  91   Here's an online `nano tutorial <http://mintaka.sdsu.edu/reu/nano.html>`_.
  92
  93 * You can open **vim** like this::
  94
  95     $ vim <filename>
  96
  97   Here's an online `vim tutorial <http://www.openvim.com/tutorial.html>`_.
  98
  99
 100 Git Setup
 101 =========
 102
 103 This tutorial also uses a revision control program called
 104 `git <http://en.wikipedia.org/wiki/Git_(software)>`_.
 105 In order to commit to a git repository,
 106 you need to setup your environment to with your identity.
 107
 108 You'll need to add these lines to `~/.bashrc` to cause them to be invoked each
 109 time you start the development environment.
 110 ::
 111
 112   git config --global user.name "John Doe"
 113   git config --global user.email johndoe@example.com
 114
 115 You can reload you `~/.bashrc` by running:
 116 ::
 117
 118   source ~/.bashrc
 119
 120 Tour (follow the video)
 121 =======================
 122
 123 Create a working directory and go into it::
 124
 125   $ mkdir work
 126   $ cd work
 127
 128 Download a zip file containing our sample::
 129
 130   $ curl http://nacltools.storage.googleapis.com/io2014/voronoi.zip -O
 131   $ ls -l
 132
 133 Unzip the sample::
 134
 135   $ unzip voronoi.zip
 136
 137 Go into the sample and take a look at the files inside::
 138
 139   $ cd voronoi
 140   $ ls
 141
 142 Our project combines voronoi.cc with several C++ libraries to produce a NEXE
 143 (or Native Client Executable).
 144
 145 .. image:: /images/voronoi1.png
 146
 147 The resulting application combines the NEXE with some Javascript to load
 148 the NaCl module, producing the complete application.
 149
 150 .. image:: /images/voronoi2.png
 151
 152 Let's use git (a revision control program) to track our changes.
 153
 154 First, create a new repository::
 155
 156   $ git init
 157
 158 Add everything here::
 159
 160   $ git add .
 161
 162 Then commit our starting state::
 163
 164   $ git commit -m "imported voronoi demo"
 165
 166 Now, likes run **make** to compile our program (NOTE: Changed since video,
 167 we've got Makefiles!)::
 168
 169   $ make
 170
 171 Oops, we get this error::
 172
 173   voronoi.cc: In member function 'void Voronoi::Update()':
 174   voronoi.cc:506: error: 'struct PSContext2D_t' has no member named 'hieght'
 175
 176 We'll need to start an editor to fix this.
 177 You'll want to change *hieght* to *height* on line 506.
 178 Then rebuild::
 179
 180   $ make -j10
 181
 182 Lets look at the diff::
 183
 184   $ git diff
 185
 186 And commit our fix::
 187
 188   $ git commit -am "fixed build error"
 189
 190 To test our application, we run a local web server, written in python.
 191 Run the server with this command (NOTE: Running through a Makefile
 192 now)::
 193
 194   $ make serve
 195
 196 Then, navigate to http://localhost:5103/ to test the demo.
 197
 198 If you follow along with the demo video, you will discover the sample crashes
 199 when you change the thread count.
 200
 201 Debugging
 202 =========
 203
 204 If you haven't installed the debugger at this point, skip to the next section.
 205
 206 At this point, if you have the debugger installed, you should be able to open
 207 the developer console and view the resulting crash.
 208
 209 You can see a backtrace with::
 210
 211   bt
 212
 213 You can see active threads with::
 214
 215   info threads
 216
 217 Currently, symbol information is limited for GLibC executables.
 218 We have improvements coming that will improve the experience further.
 219
 220 For newlib and PNaCl executables you can retrieve full symbols information
 221 with::
 222
 223   remote get irt irt
 224   add-symbol-file irt
 225   remote get nexe nexe
 226   add-symbol-file nexe
 227
 228 Fix it up
 229 =========
 230
 231 Return to the development environment and stop the test server,
 232 by pressing Ctrl-C.
 233
 234 Open your editor again, navigate to line 485 and change *valu* to *value*.
 235
 236 Then rebuild::
 237
 238   $ make -j10
 239
 240 Check the diff and commit our fix::
 241
 242   $ git diff
 243   $ git commit -am "fixed thread ui bug"
 244
 245 Now look at your commit history::
 246
 247   $ git log
 248
 249 Run the demo again. And everything now works::
 250
 251   $ make serve
 252
 253 Thanks
 254 ======
 255
 256 Thanks for checking out our environment.
 257 Things are rapidly changing and in the coming months you can expect to see
 258 further improvements and filling out of our platform and library support.
 259
 260 Check back at this page for the latest status.
 261
 262 Feature Status
 263 ==============
 264
 265 Here is a summary of feature status. We hope to overcome these limitations
 266 in the near future:
 267
 268   * NaCl Development Environment
 269
 270     * General
 271
 272       * Supported:
 273
 274         * Python (built-in)
 275         * GCC w/ GLibC (x86-32 and x86-64 only)
 276         * Lua (install with: `package -i lua && . setup-environment`)
 277         * Ruby (install with: `package -i ruby && . setup-environment`)
 278         * Nethack! (install with: `package -i nethack && . setup-environment`)
 279
 280       * Unsupported:
 281
 282         * Targeting Newlib
 283         * Targeting PNaCl
 284         * Forking in bash
 285         * Pipes / Redirection
 286         * Symbolic and hard links
 287
 288     * Missing / broken on ARM:
 289
 290       * Git (broken)
 291       * GCC (unsupported)
 292
 293   * Debugger
 294
 295     * Runs reliably only on a recent Beta or Dev Channel (M36+) build.
 296     * Currently unreliable on some platforms:
 297
 298       * ChromeOS
 299       * Mac OSX
 300       * Windows