Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / native_client_sdk / src / doc / io2014.rst
blobec083a895ea2971dbf04e7cb791659e8d0c80c0a
1 .. _io2014:
3 ###################
4 Building a NaCl App
5 ###################
7 In the browser!
8 ---------------
10 Follow along with Brad Nelson's Google I/O 2014 talk.
11 Explore our new in-browser development environment and debugger.
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!
17 .. raw:: html
19   <iframe class="video" width="500" height="281"
20   src="//www.youtube.com/embed/OzNuzBDEWzk?rel=0" frameborder="0"></iframe>
22 .. include:: nacldev/web_tools_note.inc
24 Installation
25 ============
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.
31 To install the development environment:
33   * Install the `NaCl Development Environment <https://chrome.google.com/webstore/detail/nacl-development-environm/aljpgkjeipgnmdpikaajmnepbcfkglfa>`_.
35   * Navigate to: chrome://flags and:
37     * Enable **Native Client**.
38     * Restart your browser by clicking **Relaunch Now**.
40   * First run is slow (as it downloads and installs packages). Launch and allow
41     initial install to complete before first use.
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:
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>`_.
52   * Navigate to: chrome://flags and:
54     * Enable **Native Client GDB-based debugging**.
55     * Restart your browser by clicking **Relaunch Now**.
57   * NOTE: If you experience unexplained hangs, disable GDB-based debugging
58     temporarily and try again.
61 .. include:: nacldev/editing.inc
63 .. include:: nacldev/git.inc
66 Tour (follow the video)
67 =======================
69 Create a working directory and go into it::
71   $ mkdir work
72   $ cd work
74 Download a zip file containing our sample::
76   $ curl http://nacltools.storage.googleapis.com/io2014/voronoi.zip -O
77   $ ls -l
79 Unzip the sample::
81   $ unzip voronoi.zip
83 Go into the sample and take a look at the files inside::
85   $ cd voronoi
86   $ ls
88 Our project combines voronoi.cc with several C++ libraries to produce a NEXE
89 (or Native Client Executable).
91 .. image:: /images/voronoi1.png
93 The resulting application combines the NEXE with some Javascript to load
94 the NaCl module, producing the complete application.
96 .. image:: /images/voronoi2.png
98 Let's use git (a revision control program) to track our changes.
100 First, create a new repository::
102   $ git init
104 Add everything here::
106   $ git add .
108 Then commit our starting state::
110   $ git commit -m "imported voronoi demo"
112 Now, likes run **make** to compile our program (NOTE: Changed since video,
113 we've got Makefiles!)::
115   $ make
117 Oops, we get this error::
119   voronoi.cc: In member function 'void Voronoi::Update()':
120   voronoi.cc:506: error: 'struct PSContext2D_t' has no member named 'hieght'
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::
126   $ make -j10
128 Lets look at the diff::
130   $ git diff
132 And commit our fix::
134   $ git commit -am "fixed build error"
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)::
140   $ make serve
142 Then, navigate to http://localhost:5103/ to test the demo.
144 If you follow along with the demo video, you will discover the sample crashes
145 when you change the thread count.
147 Debugging
148 =========
150 If you haven't installed the debugger at this point, skip to the next section.
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.
155 You can see a backtrace with::
157   bt
159 You can see active threads with::
161   info threads
163 Currently, symbol information is limited for GLibC executables.
164 We have improvements coming that will improve the experience further.
166 For newlib and PNaCl executables you can retrieve full symbols information
167 with::
169   remote get irt irt
170   add-symbol-file irt
171   remote get nexe nexe
172   add-symbol-file nexe
174 Fix it up
175 =========
177 Return to the development environment and stop the test server,
178 by pressing Ctrl-C.
180 Open your editor again, navigate to line 485 and change *valu* to *value*.
182 Then rebuild::
184   $ make -j10
186 Check the diff and commit our fix::
188   $ git diff
189   $ git commit -am "fixed thread ui bug"
191 Now look at your commit history::
193   $ git log
195 Run the demo again. And everything now works::
197   $ make serve
199 Thanks
200 ======
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.
206 Follow the status of the NaCl Dev Environment at :doc:`this page <nacldev>`.