blob: 59f80a5ced7fd44852e859c025d2627a860eec00 [file] [log] [blame]
<section id="what-a-difference-python-makes-codelab">
<span id="cds2014-python"></span><h1 id="what-a-difference-python-makes-codelab"><span id="cds2014-python"></span>What a Difference Python Makes - Codelab</h1>
<h2 id="introduction">Introduction</h2>
<p>Learn how you can use client-side Python on your webpage.
Use the python <a href=""
target="_blank">difflib</a> module to generate attractive online
textual diffs.
Develop inside Google Chrome, using a hot off the presses version
of our NaCl Dev Environment, running on a webpage,
powered by Portable Native Client.
The techniques in this codelab also apply to other interpreted languages
we&#8217;ve ported to PNaCl, including: Python, Lua, Ruby, Tcl, Bash, and Forth.</p>
<dl class="docutils">
<dd><ul class="first last small-gap">
<li>A Desktop / Laptop Windows, Mac, Linux, or ChromeOS browser
<br/><span id="python_compat" style="color: #cccc00"
>Checking browser compatibility...</span><br/>
<i id="python_compat2"></i>
var tag = document.getElementById('python_compat');
var tag2 = document.getElementById('python_compat2');
if (!('application/x-pnacl' in navigator.mimeTypes)) {
tag.innerHTML =
'This codelab does not appear to be supported by your browser.'; = '#cc0000';
tag2.innerHTML =
'You do not appear to be running a browser such as ' +
'Google Chrome which supports Portable Native Client ' +
'or you have disabled Portable Native Client.';
} else {
tag.innerHTML = 'This codelab appears to be supported by your browser.'; = '#00cc00';
<li>A fast broadband connection (500MB download)</li>
<li>Can read and write Python</li>
<h2 id="setup">Setup</h2>
<p>For this codelab, you will need to point your web browser at
the Beta preview of our in-browser NaCl Dev Environment.</p>
<a href=""
target="_blank">Click here to open the environment.</a><p>While no installation is needed, the first load of the page will
require you to agree to allow the page unlimited storage
(Click &#8220;Ok&#8221; in the bar at the top of your browser window.)</p>
<p>The first run requires a large download. Please be patient.
Also, as PNaCl translates executables to native code on demand,
each program will also have a noticable load delay on first run.
We&#8217;re actively working to improve this.</p>
<p>NOTE: This environment will leave a substantial (800MB) payload in your
browser. See the cleanup section below to learn how to recover this space.</p>
<p>Once the download is complete, you should see a bash prompt (ignore
the gcc warning, our web C compiler is coming soon!):</p>
<pre class="prettyprint">
WARNING: gcc not yet available for your platform (coming soon).
<h3 id="our-web-based-tools">Our Web-based Tools</h3>
<p>These development tools are a <a class="reference external" href="nacldev">work in progress</a>.
At this point, they are a learning tool and demonstration of NaCl&#8217;s
flexibility, but are not the recommended tools for a production application.
In the future, that may change, but for the moment,
to develop a substantial application for Native Client /
Portable Native Client,
we recommend you use the
<a class="reference external" href="/native-client/sdk/download">Native Client SDK</a>.</p>
<b><font color="#880000">
NOTE: The NaCl Development Environment is not yet stable.
Ideally, user data is preserved, but currently it can be lost during updates
or sporadically. We're working to resolve this.
</font></b><h3 id="navigating-in-the-dev-environment">Navigating in the Dev Environment</h3>
<p>The NaCl Dev Environment behaves like a mini-UNIX system.
You start-up in bash command prompt.
Standard UNIX commands like cd, ls, mkdir, rm, rmdir, etc.
can be used to navigate and modify the Dev Environment&#8217;s
virtual filesystem.</p>
<p>There are 3 locations mounted by the environment:</p>
<div><ul class="small-gap">
<li>/tmp mounts the HTML5 Filesystem temporary storage area.</li>
<li>/mnt/html5 mounts the HTML5 Filesystem persistent storage area.</li>
<li>Your home directory ~/, located in /home/user,
mounts a portion of the HTML5 Filsystem persistent storage area
that corresponds to the /mnt/html5/home directory.</li>
<h3 id="clipboard">Clipboard</h3>
<p>Many of the steps in this tutorial will be easier to copy and paste
into the Dev Environment.
To copy and paste in the Dev Environment web page,
you can use the keyboard or the menu options (top right corner &#9776; &#8594; Edit).</p>
<p>On your platform use:</p>
<div><ul class="small-gap">
<li><span id="copy_key">Loading...</span>
var tag = document.getElementById('copy_key');
if (navigator.appVersion.indexOf('Mac') >= 0) {
tag.innerHTML = '&#8984;-C';
} else {
tag.innerHTML = 'Ctrl-C';
</script> to Copy</li>
<li><span id="paste_key">Loading...</span>
var tag = document.getElementById('paste_key');
if (navigator.appVersion.indexOf('Mac') >= 0) {
tag.innerHTML = '&#8984;-V';
} else {
tag.innerHTML = 'Ctrl-V';
</script> to Paste</li>
<h4 id="editing">Editing</h4>
<p>To follow along in this codelab, you&#8217;ll need to use a text editor to modify
various files in our development environment.
There are currently two editor options, nano or vim.
We have an Emacs port, but it is not yet available in the Dev Environment
(coming soon).
If you&#8217;re unsure what to pick, nano is simpler to start with and has on-screen
<ul class="small-gap">
<li><p class="first">You can open <strong>nano</strong> like this:</p>
<pre class="prettyprint">
$ nano &lt;filename&gt;
<p>Here&#8217;s an online <a class="reference external" href="">nano tutorial</a>.</p>
<li><p class="first">You can open <strong>vim</strong> like this:</p>
<pre class="prettyprint">
$ vim &lt;filename&gt;
<p>Here&#8217;s an online <a class="reference external" href="">vim tutorial</a>.</p>
<h3 id="git-setup">Git Setup</h3>
<p>This tutorial also uses a revision control program called
<a class="reference external" href="">git</a>.
In order to commit to a git repository,
you need to set up your identity.</p>
<p>Run these commands (with your info) to setup your <cite>~/.gitconfig</cite>
for use:</p>
<pre class="prettyprint">
git config --global &quot;John Doe&quot;
git config --global johndoe&#64;
<h2 id="get-the-code">Get the Code!</h2>
<p>Rather than start from nothing, for this codelab we&#8217;ve provided
you with a zip file containing a starting point.</p>
<p>Download the codelab:</p>
<pre class="prettyprint">
<p>Unzip it:</p>
<pre class="prettyprint">
<p>Go into the codelab directory:</p>
<pre class="prettyprint">
cd cds2014_python
<p>Create a new local git repo:</p>
<pre class="prettyprint">
git init
<p>Add everything:</p>
<pre class="prettyprint">
git add .
<p>Commit it:</p>
<pre class="prettyprint">
git commit -am &quot;initial&quot;
<p>While working, you can see what you&#8217;ve changed by running:</p>
<pre class="prettyprint">
git diff
<h2 id="your-challenge-should-you-choose-to-accept-it">Your challenge, should you choose to accept it...</h2>
<p>Javascript has many wonderful features out of the box.
Unfortunately, generating textual diffs is not one of them.
Python on the other hand has the <a href=""
target="_blank">difflib</a> module in its standard library.</p>
<p>The starting point you&#8217;ve just extracted contains the shell
of a web app using Portable Native Client Python to generate a diff.
Just one thing is missing, that whole diffing thing...</p>
<p>To see where things stand, deploy the sample like this:</p>
<pre class="prettyprint">
<p>This will attempt to open the sample, but will be blocked by
a popup blocker the first time. Click on the URL to accept the popup.
It also clobbers /tmp/differ for good measure.</p>
<p>As you can see, this isn&#8217;t quite what we&#8217;re going for.</p>
<p>You&#8217;ll want to modify, using the editor you selected earlier.
You&#8217;ll probably want to consult the <a href=""
target="_blank">difflib</a> documentation.
I would suggest you check out the HtmlDiff class and make use of
the make_file member function. Note our goal is to create a
full HTML diff, so the make_table function is insufficient.
The splitlines function may also come in handy.</p>
<p>You can test manually as you would in a normal UNIX environment.
It can be run like this:</p>
<pre class="prettyprint">
./ before.txt after.txt out.html
<p>Once everything is working, diff.html will contain an html diff.
After the initial <cite>make</cite> you can hit &#8220;Run&#8221; to test your changes.</p>
<p>Now get to it, and good luck!</p>
<h2 id="what-you-ve-learned">What you&#8217;ve learned</h2>
<p>While the details of building and packaging Python have been
insulated from you for the purpose of this exercise, the key take-home lesson
is how easy it is to leverage Python using PNaCl.
As you&#8217;ve likely experienced, the initial start time is non-trivial.
We&#8217;re working on improving this, both by improving PNaCl,
and our Python port.</p>
<p>The same approach to deploying Python apps can be used for the other
interpreted languages that have been ported to PNaCl.</p>
<p>Check out the range of interpreters, libraries, and tools
<a class="reference external" href="">already ported to PNaCl and ready to be integrated with your Web App</a>.</p>
<p>While our in-browser environment is rapidly evolving
to become a complete development solution,
for the broadest range of development options, check out the
<a class="reference external" href="">NaCl SDK</a>.</p>
<p>Send us comments and feedback on the <a class="reference external" href="!forum/native-client-discuss">native-client-discuss</a> mailing list,
or ask questions using Stack Overflow&#8217;s <a class="reference external" href="">google-nativeclient</a> tag.</p>
<p>Bring your interpreted app to PNaCl today!</p>
<h2 id="cleanup">Cleanup</h2>
<p>The Web-based version of the Chrome Dev Environment installs
package data (&gt;800MB) into the HTML5 Filesystem storage associated
with .
To recover this storage (i.e. uninstall),
enter <strong>chrome://settings/cookies</strong> in the Chrome URL bar.
In the cookies UI, search for &#8220;naclports&#8221;.
Then click the &#8220;x&#8221; next to the naclports entry.</p>