1 {{+bindTo:partials.standard_nacl_article}}
3 <section id="c-tutorial-getting-started-part-2">
4 <span id="tutorial2"></span><h1 id="c-tutorial-getting-started-part-2"><span id="tutorial2"></span>C++ Tutorial: Getting Started (Part 2)</h1>
5 <div class="contents local" id="contents" style="display: none">
7 <li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
8 <li><p class="first"><a class="reference internal" href="#using-the-native-client-sdk-build-system" id="id2">Using the Native Client SDK build system</a></p>
10 <li><a class="reference internal" href="#simplifying-the-makefile" id="id3">Simplifying the Makefile</a></li>
11 <li><a class="reference internal" href="#choosing-valid-toolchains-and-including-common-mk" id="id4">Choosing valid toolchains, and including common.mk</a></li>
12 <li><a class="reference internal" href="#configuring-your-project" id="id5">Configuring your project</a></li>
13 <li><a class="reference internal" href="#build-macros" id="id6">Build macros</a></li>
16 <li><p class="first"><a class="reference internal" href="#making-index-html-work-for-chrome-apps" id="id7">Making index.html work for Chrome Apps</a></p>
17 <ul class="small-gap">
18 <li><a class="reference internal" href="#csp-rules" id="id8">CSP rules</a></li>
19 <li><a class="reference internal" href="#making-index-html-csp-compliant" id="id9">Making index.html CSP-compliant</a></li>
20 <li><a class="reference internal" href="#making-index-html-support-different-toolchains-and-configurations" id="id10">Making index.html support different toolchains and configurations</a></li>
23 <li><p class="first"><a class="reference internal" href="#sharing-common-code-with-common-js" id="id11">Sharing common code with common.js</a></p>
24 <ul class="small-gap">
25 <li><a class="reference internal" href="#loading-the-page-and-creating-the-module" id="id12">Loading the page and creating the module</a></li>
28 <li><a class="reference internal" href="#example-specific-behavior-with-example-js" id="id13">Example-specific behavior with example.js</a></li>
31 </div><section id="overview">
32 <h2 id="overview">Overview</h2>
33 <p>This tutorial shows how to convert the finished PNaCl web application from
34 <a class="reference internal" href="/native-client/devguide/tutorial/tutorial-part1.html"><em>Part 1</em></a> to use the Native Client SDK build system and
35 common JavaScript files. It also demonstrates some techniques to make your web
36 application <a class="reference external" href="/apps/contentSecurityPolicy">Content Security Policy (CSP)-compliant</a>, which is necessary for <a class="reference external" href="/apps/about_apps">Chrome Apps</a>.</p>
37 <p>Using the Native Client SDK build system makes it easy to build with all of the
38 SDK toolchains, and switch between the Debug and Release configurations. It
39 also simplifies the makefiles for your project, as we’ll see in the next
40 section. Finally, it adds some useful commands for <a class="reference internal" href="/native-client/sdk/examples.html#id1"><em>running</em></a> and <a class="reference internal" href="/native-client/sdk/examples.html#debugging-the-sdk-examples"><em>debugging</em></a>
42 <p>The finished code for this example can be found in the
43 <code>pepper_$(VERSION)/getting_started/part2</code> directory in the Native Client SDK
45 </section><section id="using-the-native-client-sdk-build-system">
46 <h2 id="using-the-native-client-sdk-build-system">Using the Native Client SDK build system</h2>
47 <p>This section describes how to use the SDK build system. To do so, we’ll make
48 changes in the makefile. Because the makefile in part1 and part2 are so
49 different, it is easier to start from scratch. Here is the contents of the new
50 makefile. The following sections will describe it in more detail.</p>
51 <section id="simplifying-the-makefile">
52 <h3 id="simplifying-the-makefile">Simplifying the Makefile</h3>
53 <p>The makefile from part1 only supports one toolchain (PNaCl) and one
54 configuration (Release). It also only supports one source file. It’s relatively
55 simple, but if we want to add support for multiple toolchains, configurations,
56 source files, or build steps, it would grow increasingly complex. The SDK build
57 system uses a set of variables and macros to make this possible, without
58 significantly increasing the complexity of the makefile.</p>
59 <p>Here is the new makefile, supporting three toolchains (PNaCl, Newlib NaCl,
60 Glibc NaCl) and two configurations (Debug, Release).</p>
61 <pre class="prettyprint">
62 VALID_TOOLCHAINS := pnacl newlib glibc
64 NACL_SDK_ROOT ?= $(abspath $(CURDIR)/../..)
65 include $(NACL_SDK_ROOT)/tools/common.mk
68 LIBS = ppapi_cpp ppapi
71 SOURCES = hello_tutorial.cc
73 # Build rules generated by macros from common.mk:
75 $(foreach src,$(SOURCES),$(eval $(call COMPILE_RULE,$(src),$(CFLAGS))))
77 # The PNaCl workflow uses both an unstripped and finalized/stripped binary.
78 # On NaCl, only produce a stripped binary for Release configs (not Debug).
79 ifneq (,$(or $(findstring pnacl,$(TOOLCHAIN)),$(findstring Release,$(CONFIG))))
80 $(eval $(call LINK_RULE,$(TARGET)_unstripped,$(SOURCES),$(LIBS),$(DEPS)))
81 $(eval $(call STRIP_RULE,$(TARGET),$(TARGET)_unstripped))
83 $(eval $(call LINK_RULE,$(TARGET),$(SOURCES),$(LIBS),$(DEPS)))
86 $(eval $(call NMF_RULE,$(TARGET),))
88 </section><section id="choosing-valid-toolchains-and-including-common-mk">
89 <h3 id="choosing-valid-toolchains-and-including-common-mk">Choosing valid toolchains, and including common.mk</h3>
90 <p>The makefile begins by specifying the toolchains that are valid for this
91 project. The Native Client SDK build system supports multi-toolchain projects
92 for its examples and libraries, but generally you will choose one toolchain
93 when you begin your project and never change it. Please see the
94 <a class="reference internal" href="/native-client/overview.html#toolchains"><em>Toolchains section of the Native Client overview</em></a> for more
96 <p>For this example, we support the <code>pnacl</code>, <code>newlib</code> and <code>glibc</code> toolchains.</p>
97 <pre class="prettyprint">
98 VALID_TOOLCHAINS := pnacl newlib glibc
100 <p>Next, as a convenience, we specify where to find <code>NACL_SDK_ROOT</code>. Because
101 this example is located in <code>pepper_$(VERSION)/getting_started/part2</code>, the
102 root of the SDK is two directories up.</p>
103 <pre class="prettyprint">
104 NACL_SDK_ROOT ?= $(abspath $(CURDIR)/../..)
108 <div>In your own projects, you can use the absolute path to your installed SDK
109 here. You can also override this default by setting the <code>NACL_SDK_ROOT</code>
110 environment variable. See <a class="reference internal" href="/native-client/devguide/tutorial/tutorial-part1.html#tutorial-step-5"><em>Step 5 of Part 1 of this tutorial</em></a> for more details.</div></blockquote>
113 <p>Next, we include the file <code>tools/common.mk</code>. This file provides the
114 functionality for the Native Client SDK build system, including new build rules
115 to compile and link a project, which we’ll use below.</p>
116 <pre class="prettyprint">
117 include $(NACL_SDK_ROOT)/tools/common.mk
119 </section><section id="configuring-your-project">
120 <h3 id="configuring-your-project">Configuring your project</h3>
121 <p>After including <code>tools/common.mk</code>, we configure the project by specifying its
122 name, the sources and libraries it uses:</p>
123 <pre class="prettyprint">
125 LIBS = ppapi_cpp ppapi
128 SOURCES = hello_tutorial.cc
130 <p>These variable names are not required and not used by the SDK build system;
131 they are only used in the rules described below. By convention, all SDK
132 makefiles use the following variables:</p>
133 <dl class="docutils">
135 <dd>The name of the project to build. This variable determines the name of the
136 library or executable that will be generated. In the above example, we call
137 the target <code>part2</code>, which will generate an executable called
138 <code>part2.pexe</code> for PNaCl. For NaCl toolchains, the executable’s file name
139 will be given a suffix for its architecture. For example, the ARM executable
140 is called <code>part2_arm.nexe</code>.</dd>
142 <dd>A list of libraries that this executable needs to link against. The library
143 search path is already set up to only look in the directory for the current
144 toolchain and architecture. In this example, we link against <code>ppapi_cpp</code>
145 and <code>ppapi</code>. <code>ppapi_cpp</code> is needed to use the <a class="reference external" href="/native-client/pepper_stable/cpp/">Pepper C++ interface</a>. <code>ppapi</code> is needed for communicating
146 with the browser.</dd>
148 <dd>A list of extra flags to pass to the compiler. In this example, we pass
149 <code>-Wall</code>, which turns on all warnings.</dd>
151 <dd>A list of additional flags to pass to the linker. This example does not need
152 any special linker flags, so this variable is omitted.</dd>
154 <dd>A list of C or C++ sources to compile, separated by spaces. If you have a
155 long list of sources, it may be easier to read if you put each file on its
156 own line, and use <code>\</code> as a line-continuation character. Here’s an example:</dd>
158 <pre class="prettyprint">
164 </section><section id="build-macros">
165 <h3 id="build-macros">Build macros</h3>
166 <p>For many projects, the following build macros do not need to be changed; they
167 will use the variables we’ve defined above.</p>
168 <pre class="prettyprint">
169 $(foreach src,$(SOURCES),$(eval $(call COMPILE_RULE,$(src),$(CFLAGS))))
171 ifneq (,$(or $(findstring pnacl,$(TOOLCHAIN)),$(findstring Release,$(CONFIG))))
172 $(eval $(call LINK_RULE,$(TARGET)_unstripped,$(SOURCES),$(LIBS),$(DEPS)))
173 $(eval $(call STRIP_RULE,$(TARGET),$(TARGET)_unstripped))
175 $(eval $(call LINK_RULE,$(TARGET),$(SOURCES),$(LIBS),$(DEPS)))
178 $(eval $(call NMF_RULE,$(TARGET),))
180 <p>The first line defines rules to compile each source in <code>SOURCES</code>, using the
181 flags in <code>CFLAGS</code>:</p>
182 <pre class="prettyprint">
183 $(foreach src,$(SOURCES),$(eval $(call COMPILE_RULE,$(src),$(CFLAGS))))
185 <p>The next six lines define rules to link the object files into one or more
186 executables. When <code>TOOLCHAIN</code> is <code>pnacl</code>, there is only one executable
187 generated: in the example above, <code>part2.pexe</code>. When using a NaCl toolchain,
188 there will be three executables generated, one for each architecture: in the
189 example above, <code>part2_arm.nexe</code>, <code>part2_x86_32.nexe</code> and
190 <code>part2_x86_64.nexe</code>.</p>
191 <p>When <code>CONFIG</code> is <code>Release</code>, each executable is also stripped to remove
192 debug information and reduce the file size. Otherwise, when the <code>TOOLCHAIN</code>
193 is <code>pnacl</code>, the workflow involves creating an unstripped binary for debugging
194 and then finalizing it and stripping it for publishing.</p>
195 <pre class="prettyprint">
196 ifneq (,$(or $(findstring pnacl,$(TOOLCHAIN)),$(findstring Release,$(CONFIG))))
197 $(eval $(call LINK_RULE,$(TARGET)_unstripped,$(SOURCES),$(LIBS),$(DEPS)))
198 $(eval $(call STRIP_RULE,$(TARGET),$(TARGET)_unstripped))
200 $(eval $(call LINK_RULE,$(TARGET),$(SOURCES),$(LIBS),$(DEPS)))
203 <p>Finally, the NMF rule generates a NaCl manifest file (<code>.nmf</code>) that references
204 each executable generated in the previous step:</p>
205 <pre class="prettyprint">
206 $(eval $(call NMF_RULE,$(TARGET),))
208 </section></section><section id="making-index-html-work-for-chrome-apps">
209 <h2 id="making-index-html-work-for-chrome-apps">Making index.html work for Chrome Apps</h2>
210 <p>This section describes the changes necessary to make the HTML and JavaScript in
211 part1 CSP-compliant. This is required if you want to build a <a class="reference external" href="/apps/about_apps">Chrome App</a>, but is not necessary if you want to use PNaCl on the open
213 <section id="csp-rules">
214 <h3 id="csp-rules">CSP rules</h3>
215 <p><a class="reference external" href="/apps/contentSecurityPolicy#what">Chrome Apps CSP</a> restricts you from doing
217 <ul class="small-gap">
218 <li>You can’t use inline scripting in your Chrome App pages. The restriction
219 bans both <code><script></code> blocks and event handlers (<code><button onclick="..."></code>).</li>
220 <li>You can’t reference any external resources in any of your app files (except
221 for video and audio resources). You can’t embed external resources in an
223 <li>You can’t use string-to-JavaScript methods like <code>eval()</code> and <code>new
224 Function()</code>.</li>
226 </section><section id="making-index-html-csp-compliant">
227 <h3 id="making-index-html-csp-compliant">Making index.html CSP-compliant</h3>
228 <p>To make our application CSP-compliant, we have to remove inline scripting. As
229 described above, we can’t use inline <code><script></code> blocks or event handlers. This
230 is easy to do—we’ll just reference some new files from our script tag, and
231 remove all of our inlined scripts:</p>
232 <pre class="prettyprint">
235 <script type="text/javascript" src="common.js"></script>
236 <script type="text/javascript" src="example.js"></script>
239 <p><code>common.js</code> has shared code used by all SDK examples, and is described
240 later in this document. <code>example.js</code> is a script that has code specific to
242 <p>We also need to remove the inline event handler on the body tag:</p>
243 <pre class="prettyprint">
244 <body onload="pageDidLoad()">
247 <p>This logic is now handled by <code>common.js</code>.</p>
248 </section><section id="making-index-html-support-different-toolchains-and-configurations">
249 <h3 id="making-index-html-support-different-toolchains-and-configurations">Making index.html support different toolchains and configurations</h3>
250 <p>Finally, there are a few changes to <code>index.html</code> that are not necessary for
251 CSP-compliance, but help make the SDK examples more generic.</p>
252 <p>First, we add some <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_data_attributes">data attributes</a>
253 to the body element to specify the name, supported toolchains, supported
254 configurations, and path to the <code>.nmf</code> file:</p>
255 <pre class="prettyprint">
256 <body data-name="part2"
257 data-tools="newlib glibc pnacl"
258 data-configs="Debug Release"
259 data-path="{tc}/{config}">
262 <p><code>common.js</code> will read these data attributes to allow you to load the same
263 example with different toolchains by changing the URL’s <a class="reference external" href="http://en.wikipedia.org/wiki/Query_string">query string</a>. For example, you can load the
264 glibc Debug version of this example by navigating to
265 <code>index.html?tc=glibc&config=Debug</code>.</p>
266 <p>Next, we remove the <code>embed</code> element that is described in HTML. This will be
267 automatically added for us by <code>common.js</code>, based on the current
268 toolchain/configuration combination:</p>
269 <pre class="prettyprint">
271 Just as in part1, the <embed> element will be wrapped inside the <div>
272 element with the id "listener". In part1, the embed was specified in HTML,
273 here the common.js module creates a new <embed> element and adds it to the
276 <div id="listener"></div>
278 </section></section><section id="sharing-common-code-with-common-js">
279 <h2 id="sharing-common-code-with-common-js">Sharing common code with common.js</h2>
280 <p><code>common.js</code> contains JavaScript code that each example uses to create a
281 NaCl module, handle messages from that module and other common tasks like
282 displaying the module load status and logging messages. Explaining all of
283 <code>common.js</code> is outside the scope of this document, but please look at the
284 documentation in that file for more information.</p>
285 <section id="loading-the-page-and-creating-the-module">
286 <h3 id="loading-the-page-and-creating-the-module">Loading the page and creating the module</h3>
287 <p>Since we’ve added <code><script></code> tags for <code>common.js</code> and <code>example.js</code> to the
288 <code>head</code> element, they will be loaded and executed before the rest of the
289 document has been parsed. As a result, we have to wait for the page to finish
290 loading before we try to create the embed element and add it to the page.</p>
291 <p>We can do that by calling <code>addEventListener</code> and listening for the
292 <code>DOMContentLoaded</code> event:</p>
293 <pre class="prettyprint">
294 // Listen for the DOM content to be loaded. This event is fired when parsing of
295 // the page's document has finished.
296 document.addEventListener('DOMContentLoaded', function() {
300 <p>Inside this function, we parse the URL query string, and compare that to the
302 <pre class="prettyprint">
303 // From https://developer.mozilla.org/en-US/docs/DOM/window.location
305 if (window.location.search.length > 1) {
306 var pairs = window.location.search.substr(1).split('&');
307 for (var key_ix = 0; key_ix < pairs.length; key_ix++) {
308 var keyValue = pairs[key_ix].split('=');
309 searchVars[unescape(keyValue[0])] =
310 keyValue.length > 1 ? unescape(keyValue[1]) : '';
316 var toolchains = body.dataset.tools.split(' ');
317 var configs = body.dataset.configs.split(' ');
321 var tc = toolchains.indexOf(searchVars.tc) !== -1 ?
322 searchVars.tc : toolchains[0];
324 // If the config value is included in the search vars, use that.
325 // Otherwise default to Release if it is valid, or the first value if
326 // Release is not valid.
327 if (configs.indexOf(searchVars.config) !== -1)
328 var config = searchVars.config;
329 else if (configs.indexOf('Release') !== -1)
330 var config = 'Release';
332 var config = configs[0];
334 <p>Then <code>domContentLoaded</code> is called, which performs some checks to see if the
335 browser supports Native Client, then creates the NaCl module.</p>
336 <pre class="prettyprint">
337 function domContentLoaded(name, tool, path, width, height, attrs) {
338 updateStatus('Page loaded.');
339 if (!browserSupportsNaCl(tool)) {
341 'Browser does not support NaCl (' + tool + '), or NaCl is disabled');
342 } else if (common.naclModule == null) {
343 updateStatus('Creating embed: ' + tool);
345 // We use a non-zero sized embed to give Chrome space to place the bad
346 // plug-in graphic, if there is a problem.
347 width = typeof width !== 'undefined' ? width : 200;
348 height = typeof height !== 'undefined' ? height : 200;
349 attachDefaultListeners();
350 createNaClModule(name, tool, path, width, height, attrs);
352 // It's possible that the Native Client module onload event fired
353 // before the page's onload event. In this case, the status message
354 // will reflect 'SUCCESS', but won't be displayed. This call will
355 // display the current message.
356 updateStatus('Waiting.');
360 <p><code>attachDefaultListeners</code> is added before the creation of the module, to make
361 sure that no messages are lost. Note that <code>window.attachListeners</code> is also
362 called; this is the way that <code>common.js</code> allows each example to configure
363 itself differently. If an example defines the <code>attachListeners</code> function, it
364 will be called by <code>common.js</code>.</p>
365 <pre class="prettyprint">
366 function attachDefaultListeners() {
367 var listenerDiv = document.getElementById('listener');
368 listenerDiv.addEventListener('load', moduleDidLoad, true);
369 listenerDiv.addEventListener('message', handleMessage, true);
370 listenerDiv.addEventListener('crash', handleCrash, true);
371 if (typeof window.attachListeners !== 'undefined') {
372 window.attachListeners();
376 <p>Finally, <code>createNaClModule</code> actually creates the <code>embed</code>, and appends it as
377 a child of the element with id <code>listener</code>:</p>
378 <pre class="prettyprint">
379 function createNaClModule(name, tool, path, width, height, attrs) {
380 var moduleEl = document.createElement('embed');
381 moduleEl.setAttribute('name', 'nacl_module');
382 moduleEl.setAttribute('id', 'nacl_module');
383 moduleEl.setAttribute('width', width);
384 moduleEl.setAttribute('height', height);
385 moduleEl.setAttribute('path', path);
386 moduleEl.setAttribute('src', path + '/' + name + '.nmf');
390 var mimetype = mimeTypeForTool(tool);
391 moduleEl.setAttribute('type', mimetype);
393 var listenerDiv = document.getElementById('listener');
394 listenerDiv.appendChild(moduleEl);
398 <p>When the module finishes loading, it will dispatch a <code>load</code> event, and the
399 event listener function that was registered above (<code>moduleDidLoad</code>) will be
400 called. Note that <code>common.js</code> allows each example to define a
401 <code>window.moduleDidLoad</code> function, that will be called here as well.</p>
402 <pre class="prettyprint">
403 function moduleDidLoad() {
404 common.naclModule = document.getElementById('nacl_module');
405 updateStatus('RUNNING');
407 if (typeof window.moduleDidLoad !== 'undefined') {
408 window.moduleDidLoad();
412 </section></section><section id="example-specific-behavior-with-example-js">
413 <h2 id="example-specific-behavior-with-example-js">Example-specific behavior with example.js</h2>
414 <p>As described in the previous section, <code>common.js</code> will call certain functions
415 during the module loading process. This example only needs to respond to two:
416 <code>moduleDidLoad</code> and <code>handleMessage</code>.</p>
417 <pre class="prettyprint">
418 // This function is called by common.js when the NaCl module is
420 function moduleDidLoad() {
421 // Once we load, hide the plugin. In this example, we don't display anything
422 // in the plugin, so it is fine to hide it.
425 // After the NaCl module has loaded, common.naclModule is a reference to the
426 // NaCl module's <embed> element.
428 // postMessage sends a message to it.
429 common.naclModule.postMessage('hello');
432 // This function is called by common.js when a message is received from the
434 function handleMessage(message) {
435 var logEl = document.getElementById('log');
436 logEl.textContent += message.data;
441 {{/partials.standard_nacl_article}}