Adding development environment tutorial.

native_client_sdk/src/doc/io2014.rst

Index: native_client_sdk/src/doc/io2014.rst
diff --git a/native_client_sdk/src/doc/io2014.rst b/native_client_sdk/src/doc/io2014.rst
new file mode 100644
index 0000000000000000000000000000000000000000..8b97627aa5d8cda622e8ac6bf3798e4542a906d7
--- /dev/null
+++ b/native_client_sdk/src/doc/io2014.rst
@@ -0,0 +1,278 @@
+###################
+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:
+  ::
+
+    $ nano <filename>
+
+  Here's an online `nano tutorial <http://mintaka.sdsu.edu/reu/nano.html>`_.
+
+* You can open **vim** like this:
+  ::
+
+    $ 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.
+::
+
+  $ 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.
+::
+
+  $ mkdir work
+  $ cd work
+
+Download a zip file containing our sample.
+::
+
+  $ curl http://nacltools.sotrage.googlepapis.com/io2014/voronoi.zip -O
+  $ ls -l
+
+Unzip the sample.
+::
+
+  $ unzip voronoi.zip
+
+Go into the sample and take a look at the files inside.
+::
+
+  $ 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 17:37:26]

Shame about the raw html..  maybe we can find a way to do diagrams in a
render-neutral way at some point later on.

[binji, 2014/06/19 19:12:56]

We've been doing Google Docs diagrams and saving to .png elsewhere in the docs.

[bradn, 2014/06/19 21:52:36]

Did as binji suggests.

[bradn, 2014/06/19 21:52:36]

Done.

+
+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:
+::
+
+  $ git init
+
+Add everything here:
+::
+
+  $ git add .
+
+Then commit our starting state.
+::
+
+  $ git commit -m "imported voronoi demo"
+
+
+Now, lets invoke the bash build script to compile our program:
+::

[Sam Clegg, 2014/06/19 17:37:26]

You can combine these two lines into one.  Simple end the paragraph with ::
rather than :

Looks much cleaner that way I think.

[bradn, 2014/06/19 21:52:36]

Done.

+
+  $ ./build.sh
+
+Oops, we get this error:
+::
+
+  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:
+::
+
+  $ bash build.sh
+
+Lets look at the diff.
+::
+
+  $ git diff
+
+And commit our fix.
+::
+
+  $ git commit -am "fixed build error"
+
+We can now run the demo with this command.
+::
+
+  $ 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.
+::
+
+  $ bash build.sh
+
+
+Check the diff and commit our fix.
+::
+
+  $ git diff
+  $ git commit -am "fixed thread ui bug"
+
+Now look at your commit history.
+::
+
+  $ git log
+
+Run the demo again. And everything now works.
+::
+
+  $ python ${PWD}/demo.py