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 .. include:: nacldev/web_tools_note.inc
  23
  24 Installation
  25 ============
  26
  27 The setup process currently requires several steps.
  28 We're working to reduce the number of steps in future releases.
  29 As the process gets easier, we'll update this page.
  30
  31 To install the development environment:
  32
  33   * Install the `NaCl Development Environment <https://chrome.google.com/webstore/detail/nacl-development-environm/aljpgkjeipgnmdpikaajmnepbcfkglfa>`_.
  34
  35   * Navigate to: chrome://flags and:
  36
  37     * Enable **Native Client**.
  38     * Restart your browser by clicking **Relaunch Now**.
  39
  40   * First run is slow (as it downloads and installs packages). Launch and allow
  41     initial install to complete before first use.
  42
  43 When initially experimenting with the development environment,
  44 at this time, we recommend you run it without the debugger activated.
  45 Once you're ready to apply the debugger, follow these steps:
  46
  47   * Install a usable version of
  48     `Chrome Linux (M36+, Dev or Beta channel) <http://www.chromium.org/getting-involved/dev-channel>`_.
  49   * Install the `Native Client Debugger Extension <https://chrome.google.com/webstore/detail/nacl-debugger/ncpkkhabohglmhjibnloicgdfjmojkfd>`_.
  50   * Install `Native Client GDB <https://chrome.google.com/webstore/detail/gdb/gkjoooooiaohiceibmdleokniplmbahe>`_.
  51
  52   * Navigate to: chrome://flags and:
  53
  54     * Enable **Native Client GDB-based debugging**.
  55     * Restart your browser by clicking **Relaunch Now**.
  56
  57   * NOTE: If you experience unexplained hangs, disable GDB-based debugging
  58     temporarily and try again.
  59
  60
  61 .. include:: nacldev/editing.inc
  62
  63 .. include:: nacldev/git.inc
  64
  65
  66 Tour (follow the video)
  67 =======================
  68
  69 Create a working directory and go into it::
  70
  71   $ mkdir work
  72   $ cd work
  73
  74 Download a zip file containing our sample::
  75
  76   $ curl http://nacltools.storage.googleapis.com/io2014/voronoi.zip -O
  77   $ ls -l
  78
  79 Unzip the sample::
  80
  81   $ unzip voronoi.zip
  82
  83 Go into the sample and take a look at the files inside::
  84
  85   $ cd voronoi
  86   $ ls
  87
  88 Our project combines voronoi.cc with several C++ libraries to produce a NEXE
  89 (or Native Client Executable).
  90
  91 .. image:: /images/voronoi1.png
  92
  93 The resulting application combines the NEXE with some Javascript to load
  94 the NaCl module, producing the complete application.
  95
  96 .. image:: /images/voronoi2.png
  97
  98 Let's use git (a revision control program) to track our changes.
  99
 100 First, create a new repository::
 101
 102   $ git init
 103
 104 Add everything here::
 105
 106   $ git add .
 107
 108 Then commit our starting state::
 109
 110   $ git commit -m "imported voronoi demo"
 111
 112 Now, likes run **make** to compile our program (NOTE: Changed since video,
 113 we've got Makefiles!)::
 114
 115   $ make
 116
 117 Oops, we get this error::
 118
 119   voronoi.cc: In member function 'void Voronoi::Update()':
 120   voronoi.cc:506: error: 'struct PSContext2D_t' has no member named 'hieght'
 121
 122 We'll need to start an editor to fix this.
 123 You'll want to change *hieght* to *height* on line 506.
 124 Then rebuild::
 125
 126   $ make -j10
 127
 128 Lets look at the diff::
 129
 130   $ git diff
 131
 132 And commit our fix::
 133
 134   $ git commit -am "fixed build error"
 135
 136 To test our application, we run a local web server, written in python.
 137 Run the server with this command (NOTE: Running through a Makefile
 138 now)::
 139
 140   $ make serve
 141
 142 Then, navigate to http://localhost:5103/ to test the demo.
 143
 144 If you follow along with the demo video, you will discover the sample crashes
 145 when you change the thread count.
 146
 147 Debugging
 148 =========
 149
 150 If you haven't installed the debugger at this point, skip to the next section.
 151
 152 At this point, if you have the debugger installed, you should be able to open
 153 the developer console and view the resulting crash.
 154
 155 You can see a backtrace with::
 156
 157   bt
 158
 159 You can see active threads with::
 160
 161   info threads
 162
 163 Currently, symbol information is limited for GLibC executables.
 164 We have improvements coming that will improve the experience further.
 165
 166 For newlib and PNaCl executables you can retrieve full symbols information
 167 with::
 168
 169   remote get irt irt
 170   add-symbol-file irt
 171   remote get nexe nexe
 172   add-symbol-file nexe
 173
 174 Fix it up
 175 =========
 176
 177 Return to the development environment and stop the test server,
 178 by pressing Ctrl-C.
 179
 180 Open your editor again, navigate to line 485 and change *valu* to *value*.
 181
 182 Then rebuild::
 183
 184   $ make -j10
 185
 186 Check the diff and commit our fix::
 187
 188   $ git diff
 189   $ git commit -am "fixed thread ui bug"
 190
 191 Now look at your commit history::
 192
 193   $ git log
 194
 195 Run the demo again. And everything now works::
 196
 197   $ make serve
 198
 199 Thanks
 200 ======
 201
 202 Thanks for checking out our environment.
 203 Things are rapidly changing and in the coming months you can expect to see
 204 further improvements and filling out of our platform and library support.
 205
 206 Follow the status of the NaCl Dev Environment at :doc:`this page <nacldev>`.