io2014.rst revision 116680a4aac90f2aa7413d9095a592090648e557
1.. _io2014: 2 3################### 4Building a NaCl App 5################### 6 7In the browser! 8--------------- 9 10Follow along with Brad Nelson's Google I/O 2014 talk. 11Explore our new in-browser development environment and debugger. 12 13Learn how easy it is to edit, build, and debug NaCl application 14all in your desktop web browser or on a Chromebook. 15Work 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 22Work in Progress 23================ 24 25These development tools are a work in progress, see `Feature Status`_. 26At this point, they are a learning tool and demonstration of NaCl's 27flexibility, but are not the recommended tools for a production application. 28To develop a substantial application for Native Client / 29Portable Native Client, 30we 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 41Installation 42============ 43 44The setup process currently requires several steps. 45We're working to reduce the number of steps in future releases. 46As the process gets easier, we'll update this page. 47 48To 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 60When initially experimenting with the development environment, 61at this time, we recommend you run it without the debugger activated. 62Once 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 77Editor 78====== 79 80To follow along in this tutorial, you'll need to use a text editor to modify 81various files in our development environment. 82There are currently two editor options, nano or vim. 83Emacs is coming soon... 84If you're unsure what to pick, nano is simpler to start with and has on-screen 85help. 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 100Git Setup 101========= 102 103This tutorial also uses a revision control program called 104`git <http://en.wikipedia.org/wiki/Git_(software)>`_. 105In order to commit to a git repository, 106you need to setup your environment to with your identity. 107 108You'll need to add these lines to `~/.bashrc` to cause them to be invoked each 109time 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 115You can reload you `~/.bashrc` by running: 116:: 117 118 source ~/.bashrc 119 120Tour (follow the video) 121======================= 122 123Create a working directory and go into it:: 124 125 $ mkdir work 126 $ cd work 127 128Download a zip file containing our sample:: 129 130 $ curl http://nacltools.storage.googleapis.com/io2014/voronoi.zip -O 131 $ ls -l 132 133Unzip the sample:: 134 135 $ unzip voronoi.zip 136 137Go into the sample and take a look at the files inside:: 138 139 $ cd voronoi 140 $ ls 141 142Our project combines voronoi.cc with several C++ libraries to produce a NEXE 143(or Native Client Executable). 144 145.. image:: /images/voronoi1.png 146 147The resulting application combines the NEXE with some Javascript to load 148the NaCl module, producing the complete application. 149 150.. image:: /images/voronoi2.png 151 152Let's use git (a revision control program) to track our changes. 153 154First, create a new repository:: 155 156 $ git init 157 158Add everything here:: 159 160 $ git add . 161 162Then commit our starting state:: 163 164 $ git commit -m "imported voronoi demo" 165 166Now, likes run **make** to compile our program (NOTE: Changed since video, 167we've got Makefiles!):: 168 169 $ make 170 171Oops, 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 176We'll need to start an editor to fix this. 177You'll want to change *hieght* to *height* on line 506. 178Then rebuild:: 179 180 $ make -j10 181 182Lets look at the diff:: 183 184 $ git diff 185 186And commit our fix:: 187 188 $ git commit -am "fixed build error" 189 190To test our application, we run a local web server, written in python. 191Run the server with this command (NOTE: Running through a Makefile 192now):: 193 194 $ make serve 195 196Then, navigate to http://localhost:5103/ to test the demo. 197 198If you follow along with the demo video, you will discover the sample crashes 199when you change the thread count. 200 201Debugging 202========= 203 204If you haven't installed the debugger at this point, skip to the next section. 205 206At this point, if you have the debugger installed, you should be able to open 207the developer console and view the resulting crash. 208 209You can see a backtrace with:: 210 211 bt 212 213You can see active threads with:: 214 215 info threads 216 217Currently, symbol information is limited for GLibC executables. 218We have improvements coming that will improve the experience further. 219 220For newlib and PNaCl executables you can retrieve full symbols information 221with:: 222 223 remote get irt irt 224 add-symbol-file irt 225 remote get nexe nexe 226 add-symbol-file nexe 227 228Fix it up 229========= 230 231Return to the development environment and stop the test server, 232by pressing Ctrl-C. 233 234Open your editor again, navigate to line 485 and change *valu* to *value*. 235 236Then rebuild:: 237 238 $ make -j10 239 240Check the diff and commit our fix:: 241 242 $ git diff 243 $ git commit -am "fixed thread ui bug" 244 245Now look at your commit history:: 246 247 $ git log 248 249Run the demo again. And everything now works:: 250 251 $ make serve 252 253Thanks 254====== 255 256Thanks for checking out our environment. 257Things are rapidly changing and in the coming months you can expect to see 258further improvements and filling out of our platform and library support. 259 260Check back at this page for the latest status. 261 262Feature Status 263============== 264 265Here is a summary of feature status. We hope to overcome these limitations 266in 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 301