
Bug: 750830 Change-Id: I30baf7f3042d318e1d460b0af8628369c4fdfe10 Reviewed-on: https://chromium-review.googlesource.com/602246 Commit-Queue: Julien Brianceau <jbriance@cisco.com> Reviewed-by: Sam Clegg <sbc@chromium.org> Cr-Commit-Position: refs/heads/master@{#492085}
249 lines
17 KiB
HTML
249 lines
17 KiB
HTML
{{+bindTo:partials.standard_nacl_article}}
|
|
|
|
<b><font color="#cc0000">
|
|
NOTE:
|
|
Deprecation of the technologies described here has been announced
|
|
for platforms other than ChromeOS.<br/>
|
|
Please visit our
|
|
<a href="/native-client/migration">migration guide</a>
|
|
for details.
|
|
</font></b>
|
|
<hr/><section id="c-tutorial-getting-started-part-1">
|
|
<h1 id="c-tutorial-getting-started-part-1">C++ Tutorial: Getting Started (Part 1)</h1>
|
|
<div class="contents local" id="contents" style="display: none">
|
|
<ul class="small-gap">
|
|
<li><p class="first"><a class="reference internal" href="#overview" id="id1">Overview</a></p>
|
|
<ul class="small-gap">
|
|
<li><a class="reference internal" href="#what-the-application-in-this-tutorial-does" id="id2">What the application in this tutorial does</a></li>
|
|
<li><a class="reference internal" href="#communication-between-javascript-and-native-client-modules" id="id3">Communication between JavaScript and Native Client modules</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#step-1-download-and-install-the-native-client-sdk" id="id4">Step 1: Download and install the Native Client SDK</a></li>
|
|
<li><a class="reference internal" href="#step-2-start-a-local-server" id="id5">Step 2: Start a local server</a></li>
|
|
<li><a class="reference internal" href="#step-3-set-up-the-chrome-browser" id="id6">Step 3: Set up the Chrome browser</a></li>
|
|
<li><a class="reference internal" href="#step-4-stub-code-for-the-tutorial" id="id7">Step 4: Stub code for the tutorial</a></li>
|
|
<li><a class="reference internal" href="#step-5-compile-the-native-client-module-and-run-the-stub-application" id="id8">Step 5: Compile the Native Client module and run the stub application</a></li>
|
|
<li><a class="reference internal" href="#step-6-modify-the-javascript-code-to-send-a-message-to-the-native-client-module" id="id9">Step 6: Modify the JavaScript code to send a message to the Native Client module</a></li>
|
|
<li><a class="reference internal" href="#step-7-implement-a-message-handler-in-the-native-client-module" id="id10">Step 7: Implement a message handler in the Native Client module</a></li>
|
|
<li><a class="reference internal" href="#step-8-compile-the-native-client-module-and-run-the-application-again" id="id11">Step 8: Compile the Native Client module and run the application again</a></li>
|
|
<li><a class="reference internal" href="#troubleshooting" id="id12">Troubleshooting</a></li>
|
|
<li><a class="reference internal" href="#next-steps" id="id13">Next steps</a></li>
|
|
</ul>
|
|
|
|
</div><h2 id="overview">Overview</h2>
|
|
<p>This tutorial shows how to build and run a web application using Portable Native
|
|
Client (PNaCl). This is a client-side application that uses HTML, JavaScript and
|
|
a Native Client module written in C++. The PNaCl toolchain is used to enable
|
|
running the Native Client module directly from a web page.</p>
|
|
<p>It’s recommended that you read the <a class="reference internal" href="/native-client/overview.html"><em>Native Client Technical Overview</em></a> prior to going through this tutorial.</p>
|
|
<h3 id="what-the-application-in-this-tutorial-does">What the application in this tutorial does</h3>
|
|
<p>The application in this tutorial shows how to load a Native Client module in a
|
|
web page, and how to send messages between JavaScript and the Native Client
|
|
module. In this simple application, the JavaScript sends a <code>'hello'</code> message
|
|
to the Native Client module. When the Native Client module receives a message,
|
|
it checks whether the message is equal to the string <code>'hello'</code>. If it is, the
|
|
Native Client module returns a message saying <code>'hello from NaCl'</code>. A
|
|
JavaScript alert panel displays the message received from the Native Client
|
|
module.</p>
|
|
<h3 id="communication-between-javascript-and-native-client-modules">Communication between JavaScript and Native Client modules</h3>
|
|
<p>The Native Client programming model supports bidirectional communication between
|
|
JavaScript and the Native Client module. Both sides can initiate
|
|
and respond to messages. In all cases, the communication is asynchronous: The
|
|
caller (JavaScript or the Native Client module) sends a message, but the caller
|
|
does not wait for, or may not even expect, a response. This behavior is
|
|
analogous to client/server communication on the web, where the client posts a
|
|
message to the server and returns immediately. The Native Client messaging
|
|
system is part of the Pepper API, and is described in detail in
|
|
<a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Developer’s Guide: Messaging System</em></a>.
|
|
It is also similar to the way <a class="reference external" href="http://en.wikipedia.org/wiki/Web_worker">web workers</a> interact with the main document in
|
|
JavaScript.</p>
|
|
<h2 id="step-1-download-and-install-the-native-client-sdk">Step 1: Download and install the Native Client SDK</h2>
|
|
<p>Follow the instructions on the <a class="reference internal" href="/native-client/sdk/download.html"><em>Download</em></a> page to
|
|
download and install the Native Client SDK.</p>
|
|
<h2 id="step-2-start-a-local-server"><span id="tutorial-step-2"></span>Step 2: Start a local server</h2>
|
|
<p>To simulate a production environment, the SDK provides a simple web server that
|
|
can be used to serve the application on <code>localhost</code>. A convenience Makefile
|
|
rule called <code>serve</code> is the easiest way to invoke it:</p>
|
|
<pre>
|
|
$ cd pepper_$(VERSION)/getting_started
|
|
$ make serve
|
|
</pre>
|
|
<aside class="note">
|
|
The SDK may consist of several “bundles”, one per Chrome/Pepper version (see
|
|
<a class="reference internal" href="/native-client/version.html"><em>versioning information</em></a>). In the sample invocation above
|
|
<code>pepper_$(VERSION)</code> refers to the specific version you want to use. For
|
|
example, <code>pepper_37</code>. If you don’t know which version you need, use the
|
|
one labeled <code>(stable)</code> by the <code>naclsdk list</code> command. See
|
|
<a class="reference internal" href="/native-client/sdk/download.html"><em>Download the Native Client SDK</em></a> for more details.
|
|
</aside>
|
|
<p>If no port number is specified, the server defaults to port 5103, and can be
|
|
accessed at <code>http://localhost:5103</code>.</p>
|
|
<p>Any server can be used for the purpose of development. The one provided with the
|
|
SDK is just a convenience, not a requirement.</p>
|
|
<h2 id="step-3-set-up-the-chrome-browser"><span id="tutorial-step-3"></span>Step 3: Set up the Chrome browser</h2>
|
|
<p>PNaCl is enabled by default in Chrome. We recommend that you use a version of
|
|
Chrome that’s the same or newer than the SDK bundle used to build Native Client
|
|
modules. Older PNaCl modules will always work with newer versions of Chrome, but
|
|
the converse is not true.</p>
|
|
<aside class="note">
|
|
To find out the version of Chrome, type <code>about:chrome</code> in the address bar.
|
|
</aside>
|
|
<p>For a better development experience, it’s also recommended to disable the
|
|
Chrome cache. Chrome caches resources aggressively; disabling the cache helps
|
|
make sure that the latest version of the Native Client module is loaded during
|
|
development.</p>
|
|
<ul class="small-gap">
|
|
<li>Open Chrome’s developer tools by clicking the menu icon <img alt="menu-icon" src="/native-client/images/menu-icon.png" /> and
|
|
choosing <code>Tools > Developer tools</code>.</li>
|
|
<li>Click the gear icon <img alt="gear-icon" src="/native-client/images/gear-icon.png" /> in the bottom right corner of the Chrome
|
|
window.</li>
|
|
<li>Under the “General” settings, check the box next to “Disable cache (while
|
|
DevTools is open)”.</li>
|
|
<li>Keep the Developer Tools pane open while developing Native Client
|
|
applications.</li>
|
|
</ul>
|
|
<h2 id="step-4-stub-code-for-the-tutorial">Step 4: Stub code for the tutorial</h2>
|
|
<p>The stub code for the tutorial is available in the SDK, in
|
|
<code>pepper_$(VERSION)/getting_started/part1</code>. It contains the following files:</p>
|
|
<ul class="small-gap">
|
|
<li><p class="first"><code>index.html</code>: Contains the HTML layout of the page as well as the JavaScript
|
|
code that interacts with the Native Client module.</p>
|
|
<p>The Native Client module is included in the page with an <code><embed></code> tag that
|
|
points to a manifest file.</p>
|
|
</li>
|
|
<li><code>hello_tutorial.nmf</code>: A manifest file that’s used to point the HTML to the
|
|
Native Client module and optionally provide additional commands to the PNaCl
|
|
translator that is part of the Chrome browser.</li>
|
|
<li><code>hello_tutorial.cc</code>: C++ code for a simple Native Client module.</li>
|
|
<li><code>Makefile</code>: Compilation commands to build the <strong>pexe</strong> (portable executable)
|
|
from the C++ code in <code>hello_tutorial.cc</code>.</li>
|
|
</ul>
|
|
<p>It’s a good idea to take a look at these files now—they contain a large amount
|
|
of comments that help explain their structure and contents. For more details
|
|
on the structure of a typical Native Client application, see
|
|
<a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>Application Structure</em></a>.</p>
|
|
<p>The stub code is intentionally very minimal. The C++ code does not do anything
|
|
except correctly initialize itself. The JavaScript code waits for the Native
|
|
Client module to load and changes the status text on the web page accordingly.</p>
|
|
<h2 id="step-5-compile-the-native-client-module-and-run-the-stub-application"><span id="tutorial-step-5"></span>Step 5: Compile the Native Client module and run the stub application</h2>
|
|
<p>To compile the Native Client module, run <code>make</code>:</p>
|
|
<pre>
|
|
$ cd pepper_$(VERSION)/getting_started/part1
|
|
$ make
|
|
</pre>
|
|
<p>Since the sample is located within the SDK tree, the Makefile knows how to find
|
|
the PNaCl toolchain automatically and use it to build the module. If you’re
|
|
building applications outside the NaCl SDK tree, you should set the
|
|
<code>$NACL_SDK_ROOT</code> environment variable. See <a class="reference internal" href="/native-client/devguide/devcycle/building.html"><em>Building Native Client
|
|
Modules</em></a> for more details.</p>
|
|
<p>Assuming the local server was started according to the instructions in
|
|
<a class="reference internal" href="#tutorial-step-2"><em>Step 2</em></a>, you can now load the sample by pointing Chrome
|
|
to <code>http://localhost:5103/part1</code>. Chrome should load the Native Client module
|
|
successfully and the Status text should change from “LOADING...” to “SUCCESS”.
|
|
If you run into problems, check out the <a class="reference internal" href="#tutorial-troubleshooting"><em>Troubleshooting section</em></a> below.</p>
|
|
<h2 id="step-6-modify-the-javascript-code-to-send-a-message-to-the-native-client-module">Step 6: Modify the JavaScript code to send a message to the Native Client module</h2>
|
|
<p>In this step, you’ll modify the web page (<code>index.html</code>) to send a message to
|
|
the Native Client module after the page loads the module.</p>
|
|
<p>Look for the JavaScript function <code>moduleDidLoad()</code>, and add new code to send
|
|
a ‘hello’ message to the module. The new function should look as follows:</p>
|
|
<pre class="prettyprint">
|
|
function moduleDidLoad() {
|
|
HelloTutorialModule = document.getElementById('hello_tutorial');
|
|
updateStatus('SUCCESS');
|
|
// Send a message to the Native Client module
|
|
HelloTutorialModule.postMessage('hello');
|
|
}
|
|
</pre>
|
|
<h2 id="step-7-implement-a-message-handler-in-the-native-client-module">Step 7: Implement a message handler in the Native Client module</h2>
|
|
<p>In this step, you’ll modify the Native Client module (<code>hello_tutorial.cc</code>) to
|
|
respond to the message received from the JavaScript code in the application.
|
|
Specifically, you’ll:</p>
|
|
<ul class="small-gap">
|
|
<li>Implement the <code>HandleMessage()</code> member function of the module instance.</li>
|
|
<li>Use the <code>PostMessage()</code> member function to send a message from the module to
|
|
the JavaScript code.</li>
|
|
</ul>
|
|
<p>First, add code to define the variables used by the Native Client module (the
|
|
‘hello’ string you’re expecting to receive from JavaScript and the reply string
|
|
you want to return to JavaScript as a response). In the file
|
|
<code>hello_tutorial.cc</code>, add this code after the <code>#include</code> statements:</p>
|
|
<pre class="prettyprint">
|
|
namespace {
|
|
// The expected string sent by the browser.
|
|
const char* const kHelloString = "hello";
|
|
// The string sent back to the browser upon receipt of a message
|
|
// containing "hello".
|
|
const char* const kReplyString = "hello from NaCl";
|
|
} // namespace
|
|
</pre>
|
|
<p>Now, implement the <code>HandleMessage()</code> member function to check for
|
|
<code>kHelloString</code> and return <code>kReplyString.</code> Look for the following line:</p>
|
|
<pre class="prettyprint">
|
|
// TODO(sdk_user): 1. Make this function handle the incoming message.
|
|
</pre>
|
|
<p>Populate the member function with code, as follows:</p>
|
|
<pre class="prettyprint">
|
|
virtual void HandleMessage(const pp::Var& var_message) {
|
|
if (!var_message.is_string())
|
|
return;
|
|
std::string message = var_message.AsString();
|
|
pp::Var var_reply;
|
|
if (message == kHelloString) {
|
|
var_reply = pp::Var(kReplyString);
|
|
PostMessage(var_reply);
|
|
}
|
|
}
|
|
</pre>
|
|
<p>See the Pepper API documentation for additional information about the
|
|
<a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8">pp::Instance.HandleMessage</a>
|
|
and <a class="reference external" href="/native-client/pepper_stable/cpp/classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9">pp::Instance.PostMessage</a>
|
|
member functions.</p>
|
|
<h2 id="step-8-compile-the-native-client-module-and-run-the-application-again">Step 8: Compile the Native Client module and run the application again</h2>
|
|
<ol class="arabic">
|
|
<li><p class="first">Compile the Native Client module by running the <code>make</code> command again.</p>
|
|
</li>
|
|
<li><p class="first">Start the SDK web server by running <code>make server</code>.</p>
|
|
</li>
|
|
<li><p class="first">Re-run the application by reloading <code>http://localhost:5103/part1</code> in
|
|
Chrome.</p>
|
|
<p>After Chrome loads the Native Client module, you should see the message sent
|
|
from the module.</p>
|
|
</li>
|
|
</ol>
|
|
<h2 id="troubleshooting"><span id="tutorial-troubleshooting"></span>Troubleshooting</h2>
|
|
<p>If your application doesn’t run, see <a class="reference internal" href="#tutorial-step-3"><em>Step 3</em></a> above to
|
|
verify that you’ve set up your environment correctly, including both the Chrome
|
|
browser and the local server. Make sure that you’re running a correct version of
|
|
Chrome, which is also greater or equal than the SDK bundle version you are
|
|
using.</p>
|
|
<p>Another useful debugging aid is the Chrome JavaScript console (available via the
|
|
<code>Tools</code> menu in Chrome). Examine it for clues about what went wrong. For
|
|
example, if there’s a message saying “NaCl module crashed”, there is a
|
|
possibility that the Native Client module has a bug; <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html"><em>debugging</em></a> may be required.</p>
|
|
<p>There’s more information about troubleshooting in the documentation:</p>
|
|
<ul class="small-gap">
|
|
<li><a class="reference internal" href="/native-client/faq.html#faq-troubleshooting"><em>FAQ Troubleshooting</em></a>.</li>
|
|
<li>The <a class="reference internal" href="/native-client/devguide/coding/progress-events.html"><em>Progress Events</em></a> document
|
|
contains some useful information about handling error events.</li>
|
|
</ul>
|
|
<h2 id="next-steps">Next steps</h2>
|
|
<ul class="small-gap">
|
|
<li>See the <a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>Application Structure</em></a>
|
|
section in the Developer’s Guide for information about how to structure a
|
|
Native Client module.</li>
|
|
<li>Check the <a class="reference external" href="/native-client/pepper_stable/cpp">C++ Reference</a> for details
|
|
about how to use the Pepper APIs.</li>
|
|
<li>Browse through the source code of the SDK examples (in the <code>examples</code>
|
|
directory) to learn additional techniques for writing Native Client
|
|
applications and using the Pepper APIs.</li>
|
|
<li>See the <a class="reference internal" href="/native-client/devguide/devcycle/building.html"><em>Building</em></a>, <a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>Running</em></a>, and <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html"><em>Debugging pages</em></a> for information about how to build, run, and
|
|
debug Native Client applications.</li>
|
|
<li>Check the <a class="reference external" href="https://chromium.googlesource.com/webports">webports</a> project to
|
|
see what libraries have been ported for use with Native Client. If you port an
|
|
open-source library for your own use, we recommend adding it to webports
|
|
(see <a class="reference external" href="https://chromium.googlesource.com/webports/+/master/CONTRIBUTING.md">How to check code into webports</a>).</li>
|
|
</ul>
|
|
</section>
|
|
|
|
{{/partials.standard_nacl_article}}
|