Adding development environment tutorial.

native_client_sdk/src/doc/io2014.rst

+###################
+Building a NaCl App
+###################
+In the browser!
+---------------
+
+Follow along with Brad Nelson's Google I/O 2014 talk.
+Explore our new in-browser development environment and debugger.
+
+Learn how easy it is to edit, build, and debug NaCl application
+all in your desktop web browser or on a Chromebook.
+Work either on-line or off-line!
+
+.. raw:: html
+
+  <iframe class="video" width="640" height="360"
+  src="//www.youtube.com/embed/MvKEomoiKBA?rel=0" frameborder="0"></iframe>
+
+
+Installation
+============
+
+The setup process currently requires several steps.
+We're working to reduce the number of steps in future releases.
+As the process gets easier, we'll update this page.
+
+You currently need to:
+
+* Navigate to: chrome://flags and:
+
+  * Enable **Native Client**.
+  * Enable **Native Client GDB-based debugging**.  (For the debugger)
+
+* Follow these instructions to
+  `Setup GDB <https://nacltools.storage.googleapis.com/install.html>`_
+
+* Install the `NaCl Development Environment <https://chrome.google.com/webstore/detail/nacl-development-environm/aljpgkjeipgnmdpikaajmnepbcfkglfa>`_.
+
+  * First run is slow (as it downloads and installs packages).
+
+
+Editor
+======
+
+To follow along in this tutorial, you'll need to use a text editor to modify
+various files in our development environment.
+There are currently two editor options, nano or vim.
+Emacs is coming soon...
+If you're unsure what to pick, nano is simpler to start with and has on-screen
+help.
+
+* You can open **nano** like this:
+  .. naclcode::
+
+    nano <filename>
+
+  Here's an online `nano tutorial <http://mintaka.sdsu.edu/reu/nano.html>`_.
+
+* You can open **vim** like this:
+  .. naclcode::
+
+    vim <filename>
+
+  Here's an online `vim tutorial <http://www.openvim.com/tutorial.html>`_.
+
+
+Git Setup
+=========
+
+This tutorial also uses a revision control program called
+`git <http://en.wikipedia.org/wiki/Git_(software)>`_.
+In order to commit to a git repository,
+you need to setup your environment to with your identity.
+
+You'll need to add these lines to `~/.bashrc` to cause them to be invoked each
+time you start the development environment.
+
+.. naclcode::
+
+  git config --global user.name "John Doe"
+  git config --global user.email johndoe@example.com
+
+
+Tour (follow the video)
+=======================
+
+Create a working directory and go into it.
+
+.. naclcode::
+
+  mkdir work
+  cd work
+
+Download a zip file containing our sample.
+
+.. naclcode::
+
+  curl http://nacltools.sotrage.googlepapis.com/io2014/voronoi.zip -O
+  ls -l
+
+Unzip the sample.
+
+.. naclcode::
+
+  unzip voronoi.zip
+
+Go into the sample and take a look at the files inside.
+
+.. naclcode::
+
+  cd voronoi
+  ls
+
+Our project combines voronoi.cc with several C++ libraries to produce a NEXE
+(or Native Client Executable).
+
+.. raw:: html
+
+  <svg width="600" height="200">
+    <defs>
+      <marker id="markerArrow" markerWidth="13" markerHeight="13"
+       refx="2" refy="6" orient="auto">
+        <path d="M2,2 L2,11 L10,6 L2,2" style="fill: #000000;" />
+      </marker>
+    </defs>
+
+    <g transform="translate(10,10)">
+      <rect x="0" y="0" rx="20" ry="20" width="100" height="50"
+       style="fill:#cc0000;stroke:black;stroke-width:3" />
+      <text x="50" y="25" fill="white" text-anchor="middle"
+       alignment-baseline="middle">voronoi.cc</text>
+    </g>
+    <g transform="translate(10,70)">
+      <rect x="0" y="0" rx="20" ry="20" width="100" height="50"
+       style="fill:#cccc00;stroke:black;stroke-width:3" />
+      <text x="50" y="25" fill="white" text-anchor="middle"
+       alignment-baseline="middle">libraries</text>
+    </g>
+    <g transform="translate(210,10)">
+      <rect x="0" y="0" rx="20" ry="20" width="100" height="50"
+       style="fill:#0000cc;stroke:black;stroke-width:3" />
+      <text x="50" y="25" fill="white" text-anchor="middle"
+       alignment-baseline="middle">voronoi.nexe</text>
+    </g>
+    <path d="M110,35 L195,30"
+     style="stroke:black; stroke-width: 2px; marker-end: url(#markerArrow);"/>
+    <path d="M110,95 L195,50"
+     style="stroke:black; stroke-width: 2px; marker-end: url(#markerArrow);"/>
+
+    <text x="50" y="155" fill="black" text-anchor="middle"
+     alignment-baseline="middle">build.sh</text>
+    <path d="M80,155 L300,155"
+     stroke-dasharray="5,5" d="M5 20 l215 0"
+     style="stroke:black; stroke-width: 2px; marker-end: url(#markerArrow);"/>
+  </svg>

[Sam Clegg, 2014/06/19 01:09:52]

Woah.. what is this?  Some kind of diagram?

[bradn, 2014/06/19 17:22:55]

Yeah there are two, similar to the ones from the talk.
basically just this:

voronoi.cc + libraries -> voronoi.nexe
build.sh ---------------------------->

and

voronoi.nexe + javascript -> webapp
demo.py -------------------------->

+
+The resulting application combines some Javascript to load the module with
+voronoi.nexe, producing the complete application.
+
+.. raw:: html
+
+  <svg width="600" height="200">
+    <defs>
+      <marker id="markerArrow" markerWidth="13" markerHeight="13"
+       refx="2" refy="6" orient="auto">
+        <path d="M2,2 L2,11 L10,6 L2,2" style="fill: #000000;" />
+      </marker>
+    </defs>
+
+    <g transform="translate(10,10)">
+      <rect x="0" y="0" rx="20" ry="20" width="100" height="50"
+       style="fill:#cc0000;stroke:black;stroke-width:3" />
+      <text x="50" y="25" fill="white" text-anchor="middle"
+       alignment-baseline="middle">voronoi.nexe</text>
+    </g>
+    <g transform="translate(10,70)">
+      <rect x="0" y="0" rx="20" ry="20" width="100" height="50"
+       style="fill:#cccc00;stroke:black;stroke-width:3" />
+      <text x="50" y="25" fill="white" text-anchor="middle"
+       alignment-baseline="middle">example.js</text>
+    </g>
+    <g transform="translate(210,10)">
+      <rect x="0" y="0" rx="20" ry="20" width="100" height="50"
+       style="fill:#0000cc;stroke:black;stroke-width:3" />
+      <text x="50" y="25" fill="white" text-anchor="middle"
+       alignment-baseline="middle">Web App</text>
+    </g>
+    <path d="M110,35 L195,30"
+     style="stroke:black; stroke-width: 2px; marker-end: url(#markerArrow);"/>
+    <path d="M110,95 L195,50"
+     style="stroke:black; stroke-width: 2px; marker-end: url(#markerArrow);"/>
+
+    <text x="50" y="155" fill="black" text-anchor="middle"
+     alignment-baseline="middle">demo.py</text>
+    <path d="M80,155 L300,155"
+     stroke-dasharray="5,5" d="M5 20 l215 0"
+     style="stroke:black; stroke-width: 2px; marker-end: url(#markerArrow);"/>
+  </svg>
+
+Let's use git (a revision control program) to track our changes.
+
+First, create a new repository:
+
+.. naclcode::
+
+  git init
+
+Add everything here:
+
+.. naclcode::
+
+  git add .
+
+Then commit our starting state.
+
+.. naclcode::
+
+  git commit -m "imported voronoi demo"
+
+
+Now, lets invoke the bash build script to compile our program:
+
+.. naclcode::
+
+  ./build.sh
+
+Oops, we get this error:
+
+.. naclcode::
+
+  voronoi.cc: In member function 'void Voronoi::Update()':
+  voronoi.cc:506: error: 'struct PSContext2D_t' has no member named 'hieght'
+
+We'll need to start an editor to fix this.
+You'll want to change *hieght* to *height* on line 506.
+
+Then rebuild:
+
+.. naclcode::
+
+  bash build.sh
+
+Lets look at the diff.
+
+.. naclcode::

[Sam Clegg, 2014/06/19 01:09:52]

I don't like all this use of naclcode:: for things that are not code.  Can you
just putting the :: at the end of the paragraph of text?

[bradn, 2014/06/19 17:22:55]

Done.

+
+  git diff
+
+And commit our fix.
+
+.. naclcode::
+
+  git commit -am "fixed build error"
+
+We can now run the demo with this command.
+
+.. naclcode::
+
+  python ${PWD}/demo.py
+
+Navigate to http://localhost:5103/ to test the demo.
+
+If you follow along with the demo video, you will discover the sample crashes
+when you change the thread count.
+
+*Debugger walk-thru coming soon.*
+
+Once you've identified the problem. You'll want to stop the test server.
+Press enter to halt it.
+
+Open your editor again, navigate to line 485 and change *valu* to *value*.
+
+Then rebuild.
+
+.. naclcode::
+
+  bash build.sh
+
+Check the diff and commit our fix.
+
+.. naclcode::
+
+  git diff
+  git commit -am "fixed thread ui bug"
+
+Now look at your commit history.
+
+.. naclcode::
+
+  git log
+
+Run the demo again. And everything now works.
+
+.. naclcode::
+
+  python ${PWD}/demo.py

[Sam Clegg, 2014/06/19 01:09:52]

Sometgimes is nice to include the leading "$ " in commands so you know its a
prompt.  Up to you though.

[bradn, 2014/06/19 17:22:55]

Thought about doing that.
Done.