src/native_client_sdk/doc_generated/io2014.html

   1 {{+bindTo:partials.standard_nacl_article}}
   2
   3 <section id="building-a-nacl-app">
   4 <span id="io2014"></span><h1 id="building-a-nacl-app"><span id="io2014"></span>Building a NaCl App</h1>
   5 <h2 id="in-the-browser">In the browser!</h2>
   6 <p>Follow along with Brad Nelson&#8217;s Google I/O 2014 talk.
   7 Explore our new in-browser development environment and debugger.</p>
   8 <p>Learn how easy it is to edit, build, and debug NaCl application
   9 all in your desktop web browser or on a Chromebook.
  10 Work either on-line or off-line!</p>
  11 <iframe class="video" width="500" height="281"
  12 src="//www.youtube.com/embed/OzNuzBDEWzk?rel=0" frameborder="0"></iframe><h3 id="work-in-progress">Work in Progress</h3>
  13 <p>These development tools are a work in progress, see <a class="reference internal" href="#feature-status">Feature Status</a>.
  14 At this point, they are a learning tool and demonstration of NaCl&#8217;s
  15 flexibility, but are not the recommended tools for a production application.
  16 To develop a substantial application for Native Client /
  17 Portable Native Client,
  18 we currently recommend you use the
  19 <a class="reference external" href="/native-client/sdk/download">Native Client SDK</a>.</p>
  20 <b><font color="#880000">
  21 NOTE: The NaCl Development Environment is not yet stable.
  22 Ideally user data is preserved, but currently it can be lost during updates
  23 or sporadically. We're working to resolve this.
  24 </font></b><h3 id="installation">Installation</h3>
  25 <p>The setup process currently requires several steps.
  26 We&#8217;re working to reduce the number of steps in future releases.
  27 As the process gets easier, we&#8217;ll update this page.</p>
  28 <p>To install the development environment:</p>
  29 <blockquote>
  30 <div><ul class="small-gap">
  31 <li>Install the <a class="reference external" href="https://chrome.google.com/webstore/detail/nacl-development-environm/aljpgkjeipgnmdpikaajmnepbcfkglfa">NaCl Development Environment</a>.</li>
  32 <li><p class="first">Navigate to: chrome://flags and:</p>
  33 <ul class="small-gap">
  34 <li>Enable <strong>Native Client</strong>.</li>
  35 <li>Restart your browser by clicking <strong>Relaunch Now</strong>.</li>
  36 </ul>
  37 </li>
  38 <li>First run is slow (as it downloads and installs packages). Launch and allow
  39 initial install to complete before first use.</li>
  40 </ul>
  41 </div></blockquote>
  42 <p>When initially experimenting with the development environment,
  43 at this time, we recommend you run it without the debugger activated.
  44 Once you&#8217;re ready to apply the debugger, follow these steps:</p>
  45 <blockquote>
  46 <div><ul class="small-gap">
  47 <li>Install a usable version of
  48 <a class="reference external" href="http://www.chromium.org/getting-involved/dev-channel">Chrome Linux (M36+, Dev or Beta channel)</a>.</li>
  49 <li>Install the <a class="reference external" href="https://chrome.google.com/webstore/detail/nacl-debugger/ncpkkhabohglmhjibnloicgdfjmojkfd">Native Client Debugger Extension</a>.</li>
  50 <li>Install <a class="reference external" href="https://chrome.google.com/webstore/detail/gdb/gkjoooooiaohiceibmdleokniplmbahe">Native Client GDB</a>.</li>
  51 <li><p class="first">Navigate to: chrome://flags and:</p>
  52 <ul class="small-gap">
  53 <li>Enable <strong>Native Client GDB-based debugging</strong>.</li>
  54 <li>Restart your browser by clicking <strong>Relaunch Now</strong>.</li>
  55 </ul>
  56 </li>
  57 <li>NOTE: If you experience unexplained hangs, disable GDB-based debugging
  58 temporarily and try again.</li>
  59 </ul>
  60 </div></blockquote>
  61 <h3 id="editor">Editor</h3>
  62 <p>To follow along in this tutorial, you&#8217;ll need to use a text editor to modify
  63 various files in our development environment.
  64 There are currently two editor options, nano or vim.
  65 Emacs is coming soon...
  66 If you&#8217;re unsure what to pick, nano is simpler to start with and has on-screen
  67 help.</p>
  68 <ul class="small-gap">
  69 <li><p class="first">You can open <strong>nano</strong> like this:</p>
  70 <pre class="prettyprint">
  71 $ nano &lt;filename&gt;
  72 </pre>
  73 <p>Here&#8217;s an online <a class="reference external" href="http://mintaka.sdsu.edu/reu/nano.html">nano tutorial</a>.</p>
  74 </li>
  75 <li><p class="first">You can open <strong>vim</strong> like this:</p>
  76 <pre class="prettyprint">
  77 $ vim &lt;filename&gt;
  78 </pre>
  79 <p>Here&#8217;s an online <a class="reference external" href="http://www.openvim.com/tutorial.html">vim tutorial</a>.</p>
  80 </li>
  81 </ul>
  82 <h3 id="git-setup">Git Setup</h3>
  83 <p>This tutorial also uses a revision control program called
  84 <a class="reference external" href="http://en.wikipedia.org/wiki/Git_(software)">git</a>.
  85 In order to commit to a git repository,
  86 you need to setup your environment to with your identity.</p>
  87 <p>You&#8217;ll need to add these lines to <cite>~/.bashrc</cite> to cause them to be invoked each
  88 time you start the development environment.</p>
  89 <pre class="prettyprint">
  90 git config --global user.name &quot;John Doe&quot;
  91 git config --global user.email johndoe&#64;example.com
  92 </pre>
  93 <p>You can reload you <cite>~/.bashrc</cite> by running:</p>
  94 <pre class="prettyprint">
  95 source ~/.bashrc
  96 </pre>
  97 <h3 id="tour-follow-the-video">Tour (follow the video)</h3>
  98 <p>Create a working directory and go into it:</p>
  99 <pre class="prettyprint">
 100 $ mkdir work
 101 $ cd work
 102 </pre>
 103 <p>Download a zip file containing our sample:</p>
 104 <pre class="prettyprint">
 105 $ curl http://nacltools.storage.googleapis.com/io2014/voronoi.zip -O
 106 $ ls -l
 107 </pre>
 108 <p>Unzip the sample:</p>
 109 <pre class="prettyprint">
 110 $ unzip voronoi.zip
 111 </pre>
 112 <p>Go into the sample and take a look at the files inside:</p>
 113 <pre class="prettyprint">
 114 $ cd voronoi
 115 $ ls
 116 </pre>
 117 <p>Our project combines voronoi.cc with several C++ libraries to produce a NEXE
 118 (or Native Client Executable).</p>
 119 <img alt="/native-client/images/voronoi1.png" src="/native-client/images/voronoi1.png" />
 120 <p>The resulting application combines the NEXE with some Javascript to load
 121 the NaCl module, producing the complete application.</p>
 122 <img alt="/native-client/images/voronoi2.png" src="/native-client/images/voronoi2.png" />
 123 <p>Let&#8217;s use git (a revision control program) to track our changes.</p>
 124 <p>First, create a new repository:</p>
 125 <pre class="prettyprint">
 126 $ git init
 127 </pre>
 128 <p>Add everything here:</p>
 129 <pre class="prettyprint">
 130 $ git add .
 131 </pre>
 132 <p>Then commit our starting state:</p>
 133 <pre class="prettyprint">
 134 $ git commit -m &quot;imported voronoi demo&quot;
 135 </pre>
 136 <p>Now, likes run <strong>make</strong> to compile our program (NOTE: Changed since video,
 137 we&#8217;ve got Makefiles!):</p>
 138 <pre class="prettyprint">
 139 $ make
 140 </pre>
 141 <p>Oops, we get this error:</p>
 142 <pre class="prettyprint">
 143 voronoi.cc: In member function 'void Voronoi::Update()':
 144 voronoi.cc:506: error: 'struct PSContext2D_t' has no member named 'hieght'
 145 </pre>
 146 <p>We&#8217;ll need to start an editor to fix this.
 147 You&#8217;ll want to change <em>hieght</em> to <em>height</em> on line 506.
 148 Then rebuild:</p>
 149 <pre class="prettyprint">
 150 $ make -j10
 151 </pre>
 152 <p>Lets look at the diff:</p>
 153 <pre class="prettyprint">
 154 $ git diff
 155 </pre>
 156 <p>And commit our fix:</p>
 157 <pre class="prettyprint">
 158 $ git commit -am &quot;fixed build error&quot;
 159 </pre>
 160 <p>To test our application, we run a local web server, written in python.
 161 Run the server with this command (NOTE: Running through a Makefile
 162 now):</p>
 163 <pre class="prettyprint">
 164 $ make serve
 165 </pre>
 166 <p>Then, navigate to <a class="reference external" href="http://localhost:5103/">http://localhost:5103/</a> to test the demo.</p>
 167 <p>If you follow along with the demo video, you will discover the sample crashes
 168 when you change the thread count.</p>
 169 <h3 id="debugging">Debugging</h3>
 170 <p>If you haven&#8217;t installed the debugger at this point, skip to the next section.</p>
 171 <p>At this point, if you have the debugger installed, you should be able to open
 172 the developer console and view the resulting crash.</p>
 173 <p>You can see a backtrace with:</p>
 174 <pre class="prettyprint">
 175 bt
 176 </pre>
 177 <p>You can see active threads with:</p>
 178 <pre class="prettyprint">
 179 info threads
 180 </pre>
 181 <p>Currently, symbol information is limited for GLibC executables.
 182 We have improvements coming that will improve the experience further.</p>
 183 <p>For newlib and PNaCl executables you can retrieve full symbols information
 184 with:</p>
 185 <pre class="prettyprint">
 186 remote get irt irt
 187 add-symbol-file irt
 188 remote get nexe nexe
 189 add-symbol-file nexe
 190 </pre>
 191 <h3 id="fix-it-up">Fix it up</h3>
 192 <p>Return to the development environment and stop the test server,
 193 by pressing Ctrl-C.</p>
 194 <p>Open your editor again, navigate to line 485 and change <em>valu</em> to <em>value</em>.</p>
 195 <p>Then rebuild:</p>
 196 <pre class="prettyprint">
 197 $ make -j10
 198 </pre>
 199 <p>Check the diff and commit our fix:</p>
 200 <pre class="prettyprint">
 201 $ git diff
 202 $ git commit -am &quot;fixed thread ui bug&quot;
 203 </pre>
 204 <p>Now look at your commit history:</p>
 205 <pre class="prettyprint">
 206 $ git log
 207 </pre>
 208 <p>Run the demo again. And everything now works:</p>
 209 <pre class="prettyprint">
 210 $ make serve
 211 </pre>
 212 <h3 id="thanks">Thanks</h3>
 213 <p>Thanks for checking out our environment.
 214 Things are rapidly changing and in the coming months you can expect to see
 215 further improvements and filling out of our platform and library support.</p>
 216 <p>Check back at this page for the latest status.</p>
 217 <h3 id="feature-status">Feature Status</h3>
 218 <p>Here is a summary of feature status. We hope to overcome these limitations
 219 in the near future:</p>
 220 <blockquote>
 221 <div><ul class="small-gap">
 222 <li><p class="first">NaCl Development Environment</p>
 223 <ul class="small-gap">
 224 <li><p class="first">General</p>
 225 <ul class="small-gap">
 226 <li><p class="first">Supported:</p>
 227 <ul class="small-gap">
 228 <li>Python (built-in)</li>
 229 <li>GCC w/ GLibC (x86-32 and x86-64 only)</li>
 230 <li>Lua (install with: <cite>package -i lua &amp;&amp; . setup-environment</cite>)</li>
 231 <li>Ruby (install with: <cite>package -i ruby &amp;&amp; . setup-environment</cite>)</li>
 232 <li>Nethack! (install with: <cite>package -i nethack &amp;&amp; . setup-environment</cite>)</li>
 233 </ul>
 234 </li>
 235 <li><p class="first">Unsupported:</p>
 236 <ul class="small-gap">
 237 <li>Targeting Newlib</li>
 238 <li>Targeting PNaCl</li>
 239 <li>Forking in bash</li>
 240 <li>Pipes / Redirection</li>
 241 <li>Symbolic and hard links</li>
 242 </ul>
 243 </li>
 244 </ul>
 245 </li>
 246 <li><p class="first">Missing / broken on ARM:</p>
 247 <ul class="small-gap">
 248 <li>Git (broken)</li>
 249 <li>GCC (unsupported)</li>
 250 </ul>
 251 </li>
 252 </ul>
 253 </li>
 254 <li><p class="first">Debugger</p>
 255 <ul class="small-gap">
 256 <li>Runs reliably only on a recent Beta or Dev Channel (M36+) build.</li>
 257 <li><p class="first">Currently unreliable on some platforms:</p>
 258 <ul class="small-gap">
 259 <li>ChromeOS</li>
 260 <li>Mac OSX</li>
 261 <li>Windows</li>
 262 </ul>
 263 </li>
 264 </ul>
 265 </li>
 266 </ul>
 267 </div></blockquote>
 268 </section>
 269
 270 {{/partials.standard_nacl_article}}