| {{+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="application-structure"> |
| <h1 id="application-structure">Application Structure</h1> |
| <div class="contents local" id="contents" style="display: none"> |
| <ul class="small-gap"> |
| <li><a class="reference internal" href="#application-components" id="id1">Application components</a></li> |
| <li><a class="reference internal" href="#html-file-and-the-embed-element" id="id2">HTML file and the <embed> element</a></li> |
| <li><a class="reference internal" href="#manifest-files" id="id3">Manifest Files</a></li> |
| <li><a class="reference internal" href="#modules-and-instances" id="id4">Modules and instances</a></li> |
| <li><a class="reference internal" href="#native-client-modules-a-closer-look" id="id5">Native Client modules: A closer look</a></li> |
| </ul> |
| |
| </div><p>This section of the Developer’s Guide describes the general structure of a |
| Native Client application. The section assumes you are familiar with the |
| material presented in the <a class="reference internal" href="/native-client/overview.html"><em>Technical Overview</em></a>.</p> |
| <aside class="note"> |
| The “Hello, World” example is used here to illustrate basic |
| Native Client programming techniques. You can find this code in the |
| <em>/getting_started/part1</em> directory in the Native Client SDK download. |
| </aside> |
| <h2 id="application-components">Application components</h2> |
| <p>A Native Client application typically contains the following components:</p> |
| <ul class="small-gap"> |
| <li>an HTML file;</li> |
| <li>JavaScript code, which can be included in the HTML file or contained in one or |
| more separate .js files;</li> |
| <li>CSS styles, which can be included in the HTML file or contained in one or more |
| separate .css files;</li> |
| <li>a Native Client manifest file (with a .nmf extension) that specifies how to |
| load a Native Client module for different processors; and</li> |
| <li>a Native Client module, written in C or C++, and compiled into a portable |
| executable file (with a .pexe extension) or (if using the Chrome Web Store), |
| architecture-specific executable files (with .nexe extensions).</li> |
| </ul> |
| <p>Applications that are published in the <a class="reference external" href="https://chrome.google.com/webstore/search?q=%22Native+Client%22+OR+NativeClient+OR+NaCl">Chrome Web Store</a> |
| also include a Chrome |
| Web Store manifest file <code>(manifest.json)</code> and one or more icon files.</p> |
| <h2 id="html-file-and-the-embed-element"><span id="html-file"></span>HTML file and the <embed> element</h2> |
| <p>The <code><embed></code> element in an HTML file triggers the loading of a Native Client |
| module and specifies the rectangle on the web page that is managed by the |
| module. Here is the <embed> element from the “Hello, World” application:</p> |
| <pre class="prettyprint"> |
| <embed id="hello_tutorial" |
| width=0 height=0 |
| src="hello_tutorial.nmf" |
| type="application/x-pnacl" /> |
| </pre> |
| <p>In the <code><embed></code> element:</p> |
| <dl class="docutils"> |
| <dt>name</dt> |
| <dd>is the DOM name attribute for the Native Client module |
| (“nacl_module” is often used as a convention)</dd> |
| <dt>id</dt> |
| <dd>specifies the DOM ID for the Native Client module</dd> |
| <dt>width, height</dt> |
| <dd>specify the size in pixels of the rectangle on the web page that is |
| managed by the Native Client module (if the module does not have a |
| visible area, these values can be 0)</dd> |
| <dt>src</dt> |
| <dd>refers to the Native Client manifest file that is used to determine |
| which version of a module to load based on the architecture of the |
| user’s computer (see the following section for more information)</dd> |
| <dt>type</dt> |
| <dd>specifies the MIME type of the embedded content; for Portable Native Client |
| modules the type must be “application/x-pnacl”. For architecture-specific |
| Native Client modules the type must be “application/x-nacl”</dd> |
| </dl> |
| <h2 id="manifest-files"><span id="manifest-file"></span>Manifest Files</h2> |
| <p>Native Client applications have two types of manifest files: a Chrome Web Store |
| manifest file and a Native Client manifest file.</p> |
| <p>A <strong>Chrome Web Store manifest file</strong> is a file with information about a web |
| application that is published in the Chrome Web Store. This file, named |
| <code>manifest.json</code>, is required for applications that are published in the |
| Chrome Web Store. For more information about this file see <a class="reference internal" href="/native-client/devguide/distributing.html"><em>Distributing |
| Your Application</em></a>. and the <a class="reference external" href="/extensions/manifest">Chrome Web Store manifest file |
| format</a>.</p> |
| <p>A <strong>Native Client manifest file</strong> is a file that specifies which Native Client |
| module (executable) to load. For PNaCl it specifies a single portable |
| executable; otherwise it specifies one for each of the supported end-user |
| computer architectures (for example x86-32, x86-64, or ARM). This file is |
| required for all Native Client applications. The extension for this file is |
| .nmf.</p> |
| <p>Manifest files for applications that use PNaCl are simple. Here is the manifest |
| for the hello world example:</p> |
| <pre class="prettyprint"> |
| { |
| "program": { |
| "portable": { |
| "pnacl-translate": { |
| "url": "hello_tutorial.pexe" |
| } |
| } |
| } |
| } |
| </pre> |
| <p>For Chrome Web Store applications that do not use PNaCl, a typical manifest file |
| contains a <a class="reference external" href="http://www.json.org/">JSON</a> dictionary with a single top-level |
| key/value pair: the “program” key and a value consisting of a nested |
| dictionary. The nested dictionary contains keys corresponding to the names of |
| the supported computer architectures, and values referencing the file to load |
| for a given architecture—specifically, the URL of the .nexe file, given by the |
| <code>"url"</code> key. URLs are specified relative to the location of the manifest file. |
| Here is an example:</p> |
| <pre class="prettyprint"> |
| { |
| "program": { |
| "x86-32": { |
| "url": "hello_tutorial_x86_32.nexe" |
| }, |
| "x86-64": { |
| "url": "hello_tutorial_x86_64.nexe" |
| }, |
| "arm": { |
| "url": "hello_tutorial_arm.nexe" |
| } |
| } |
| } |
| </pre> |
| <p>For applications that use the <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loading.html#c-libraries"><em>glibc</em></a> |
| library, the manifest file must also contain a “files” key that specifies the |
| shared libraries that the applications use. This is discussed in detail in |
| <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loading.html"><em>Dynamic Linking and Loading with glibc</em></a>. To |
| see some example manifest files, build some of the example applications in the |
| SDK (run <code>make</code> in the example subdirectories) and look at the generated |
| manifest files.</p> |
| <p>In most cases, you can simply use the Python script provided with the SDK, |
| <code>create_nmf.py</code>, to create a manifest file for your application as part of the |
| compilation step (see the Makefile in any of the SDK examples for an |
| illustration of how to do so). The manifest file format is also |
| <a class="reference internal" href="/native-client/reference/nacl-manifest-format.html"><em>documented</em></a>.</p> |
| <h2 id="modules-and-instances">Modules and instances</h2> |
| <p>A Native Client <strong>module</strong> is C or C++ code compiled into a PNaCl .pexe file or |
| a NaCl .nexe file.</p> |
| <p>An <strong>instance</strong> is a rectangle on a web page that is managed by a module. An |
| instance may have a dimension of width=0 and height=0, meaning that the instance |
| does not have any visible component on the web page. An instance is created by |
| including an <code><embed></code> element in a web page. The <code><embed></code> element |
| references a Native Client manifest file that loads the appropriate version of |
| the module (either portable, or specific to the end-user’s architecture). A |
| module may be included in a web page multiple times by using multiple |
| <code><embed></code> elements that refer to the module; in this case the Native Client |
| runtime system loads the module once and creates multiple instances that are |
| managed by the module.</p> |
| <h2 id="native-client-modules-a-closer-look">Native Client modules: A closer look</h2> |
| <p>A Native Client module must include three components:</p> |
| <ul class="small-gap"> |
| <li>a factory function called <code>CreateModule()</code></li> |
| <li>a Module class (derived from the <code>pp::Module</code> class)</li> |
| <li>an Instance class (derived from the <code>pp:Instance</code> class)</li> |
| </ul> |
| <p>In the “Hello tutorial” example (in the <code>getting_started/part1</code> directory of |
| the NaCl SDK), these three components are specified in the file |
| <code>hello_tutorial.cc</code>. Here is the factory function:</p> |
| <pre class="prettyprint"> |
| Module* CreateModule() { |
| return new HelloTutorialModule(); |
| } |
| </pre> |
| <p>Native Client modules do not have a <code>main()</code> function. The <code>CreateModule()</code> |
| factory function is the main binding point between a module and the browser, and |
| serves as the entry point into the module. The browser calls <code>CreateModule()</code> |
| when a module is first loaded; this function returns a Module object derived |
| from the <code>pp::Module</code> class. The browser keeps a singleton of the Module |
| object.</p> |
| <p>Below is the Module class from the “Hello tutorial” example:</p> |
| <pre class="prettyprint"> |
| class HelloTutorialModule : public pp::Module { |
| public: |
| HelloTutorialModule() : pp::Module() {} |
| virtual ~HelloTutorialModule() {} |
| |
| virtual pp::Instance* CreateInstance(PP_Instance instance) { |
| return new HelloTutorialInstance(instance); |
| } |
| }; |
| </pre> |
| <p>The Module class must include a <code>CreateInstance()</code> method. The browser calls |
| the <code>CreateInstance()</code> method every time it encounters an <code><embed></code> element |
| on a web page that references the same module. The <code>CreateInstance()</code> function |
| creates and returns an Instance object derived from the <code>pp::Instance</code> class.</p> |
| <p>Below is the Instance class from the “Hello tutorial” example:</p> |
| <pre class="prettyprint"> |
| class HelloTutorialInstance : public pp::Instance { |
| public: |
| explicit HelloTutorialInstance(PP_Instance instance) : pp::Instance(instance) {} |
| virtual ~HelloTutorialInstance() {} |
| |
| virtual void HandleMessage(const pp::Var& var_message) {} |
| }; |
| </pre> |
| <p>As in the example above, the Instance class for your module will likely include |
| an implementation of the <code>HandleMessage()</code> function. The browser calls an |
| instance’s <code>HandleMessage()</code> function every time the JavaScript code in an |
| application calls <code>postMessage()</code> to send a message to the instance. See the |
| <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Native Client messaging system</em></a> for more information about |
| how to send messages between JavaScript code and Native Client modules.</p> |
| <p>The NaCl code is only invoked to handle various browser-issued |
| events and callbacks. There is no need to shut down the NaCl instance by |
| calling the <code>exit()</code> function. NaCl modules will be shut down when the user |
| leaves the web page, or the NaCl module’s <code><embed></code> is otherwise destroyed. |
| If the NaCl module does call the <code>exit()</code> function, the instance will |
| issue a <code>crash</code> event |
| <a class="reference internal" href="/native-client/devguide/coding/progress-events.html"><em>which can be handled in Javascript</em></a>.</p> |
| <p>While the <code>CreateModule()</code> factory function, the <code>Module</code> class, and the |
| <code>Instance</code> class are required for a Native Client application, the code |
| samples shown above don’t actually do anything. Subsequent sections in the |
| Developer’s Guide build on these code samples and add more interesting |
| functionality.</p> |
| </section> |
| |
| {{/partials.standard_nacl_article}} |