src/native_client_sdk/doc_generated/devguide/coding/application-structure.html

   1 {{+bindTo:partials.standard_nacl_article}}
   2
   3 <section id="application-structure">
   4 <span id="devcycle-application-structure"></span><h1 id="application-structure"><span id="devcycle-application-structure"></span>Application Structure</h1>
   5 <div class="contents local" id="contents" style="display: none">
   6 <ul class="small-gap">
   7 <li><a class="reference internal" href="#application-components" id="id1">Application components</a></li>
   8 <li><a class="reference internal" href="#html-file-and-the-embed-element" id="id2">HTML file and the &lt;embed&gt; element</a></li>
   9 <li><a class="reference internal" href="#manifest-files" id="id3">Manifest Files</a></li>
  10 <li><a class="reference internal" href="#modules-and-instances" id="id4">Modules and instances</a></li>
  11 <li><a class="reference internal" href="#native-client-modules-a-closer-look" id="id5">Native Client modules: A closer look</a></li>
  12 </ul>
  13
  14 </div><p>This section of the Developer&#8217;s Guide describes the general structure of a
  15 Native Client application. The section assumes you are familiar with the
  16 material presented in the <a class="reference internal" href="/native-client/overview.html"><em>Technical Overview</em></a>.</p>
  17 <aside class="note">
  18 The &#8220;Hello, World&#8221; example is used here to illustrate basic
  19 Native Client programming techniques. You can find this code in the
  20 <em>/getting_started/part1</em> directory in the Native Client SDK download.
  21 </aside>
  22 <h2 id="application-components">Application components</h2>
  23 <p>A Native Client application typically contains the following components:</p>
  24 <ul class="small-gap">
  25 <li>an HTML file;</li>
  26 <li>JavaScript code, which can be included in the HTML file or contained in one or
  27 more separate .js files;</li>
  28 <li>CSS styles, which can be included in the HTML file or contained in one or more
  29 separate .css files;</li>
  30 <li>a Native Client manifest file (with a .nmf extension) that specifies how to
  31 load a Native Client module for different processors; and</li>
  32 <li>a Native Client module, written in C or C++, and compiled into a portable
  33 executable file (with a .pexe extension) or (if using the Chrome Web Store),
  34 architecture-specific executable files (with .nexe extensions).</li>
  35 </ul>
  36 <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>
  37 also include a Chrome
  38 Web Store manifest file <code>(manifest.json)</code> and one or more icon files.</p>
  39 <h2 id="html-file-and-the-embed-element"><span id="html-file"></span>HTML file and the &lt;embed&gt; element</h2>
  40 <p>The <code>&lt;embed&gt;</code> element in an HTML file triggers the loading of a Native Client
  41 module and specifies the rectangle on the web page that is managed by the
  42 module. Here is the &lt;embed&gt; element from the &#8220;Hello, World&#8221; application:</p>
  43 <pre class="prettyprint">
  44 &lt;embed id=&quot;hello_tutorial&quot;
  45   width=0 height=0
  46   src=&quot;hello_tutorial.nmf&quot;
  47   type=&quot;application/x-pnacl&quot; /&gt;
  48 </pre>
  49 <p>In the <code>&lt;embed&gt;</code> element:</p>
  50 <dl class="docutils">
  51 <dt>name</dt>
  52 <dd>is the DOM name attribute for the Native Client module
  53 (&#8220;nacl_module&#8221; is often used as a convention)</dd>
  54 <dt>id</dt>
  55 <dd>specifies the DOM ID for the Native Client module</dd>
  56 <dt>width, height</dt>
  57 <dd>specify the size in pixels of the rectangle on the web page that is
  58 managed by the Native Client module (if the module does not have a
  59 visible area, these values can be 0)</dd>
  60 <dt>src</dt>
  61 <dd>refers to the Native Client manifest file that is used to determine
  62 which version of a module to load based on the architecture of the
  63 user&#8217;s computer (see the following section for more information)</dd>
  64 <dt>type</dt>
  65 <dd>specifies the MIME type of the embedded content; for Portable Native Client
  66 modules the type must be &#8220;application/x-pnacl&#8221;. For architecture-specific
  67 Native Client modules the type must be &#8220;application/x-nacl&#8221;</dd>
  68 </dl>
  69 <h2 id="manifest-files"><span id="manifest-file"></span>Manifest Files</h2>
  70 <p>Native Client applications have two types of manifest files: a Chrome Web Store
  71 manifest file and a Native Client manifest file.</p>
  72 <p>A <strong>Chrome Web Store manifest file</strong> is a file with information about a web
  73 application that is published in the Chrome Web Store. This file, named
  74 <code>manifest.json</code>, is required for applications that are published in the
  75 Chrome Web Store. For more information about this file see <a class="reference internal" href="/native-client/devguide/distributing.html"><em>Distributing
  76 Your Application</em></a>.  and the <a class="reference external" href="/extensions/manifest">Chrome Web Store manifest file
  77 format</a>.</p>
  78 <p>A <strong>Native Client manifest file</strong> is a file that specifies which Native Client
  79 module (executable) to load. For PNaCl it specifies a single portable
  80 executable; otherwise it specifies one for each of the supported end-user
  81 computer architectures (for example x86-32, x86-64, or ARM). This file is
  82 required for all Native Client applications. The extension for this file is
  83 .nmf.</p>
  84 <p>Manifest files for applications that use PNaCl are simple. Here is the manifest
  85 for the hello world example:</p>
  86 <pre class="prettyprint">
  87 {
  88   &quot;program&quot;: {
  89     &quot;portable&quot;: {
  90       &quot;pnacl-translate&quot;: {
  91         &quot;url&quot;: &quot;hello_tutorial.pexe&quot;
  92       }
  93     }
  94   }
  95 }
  96 </pre>
  97 <p>For Chrome Web Store applications that do not use PNaCl, a typical manifest file
  98 contains a <a class="reference external" href="http://www.json.org/">JSON</a> dictionary with a single top-level
  99 key/value pair: the &#8220;program&#8221; key and a value consisting of a nested
 100 dictionary. The nested dictionary contains keys corresponding to the names of
 101 the supported computer architectures, and values referencing the file to load
 102 for a given architecture—specifically, the URL of the .nexe file, given by the
 103 <code>&quot;url&quot;</code> key. URLs are specified relative to the location of the manifest file.
 104 Here is an example:</p>
 105 <pre class="prettyprint">
 106 {
 107   &quot;program&quot;: {
 108     &quot;x86-32&quot;: {
 109       &quot;url&quot;: &quot;hello_tutorial_x86_32.nexe&quot;
 110     },
 111     &quot;x86-64&quot;: {
 112       &quot;url&quot;: &quot;hello_tutorial_x86_64.nexe&quot;
 113     },
 114     &quot;arm&quot;: {
 115       &quot;url&quot;: &quot;hello_tutorial_arm.nexe&quot;
 116     }
 117   }
 118 }
 119 </pre>
 120 <p>For applications that use the <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loading.html#c-libraries"><em>glibc</em></a>
 121 library, the manifest file must also contain a &#8220;files&#8221; key that specifies the
 122 shared libraries that the applications use. This is discussed in detail in
 123 <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loading.html"><em>Dynamic Linking and Loading with glibc</em></a>. To
 124 see some example manifest files, build some of the example applications in the
 125 SDK (run <code>make</code> in the example subdirectories) and look at the generated
 126 manifest files.</p>
 127 <p>In most cases, you can simply use the Python script provided with the SDK,
 128 <code>create_nmf.py</code>, to create a manifest file for your application as part of the
 129 compilation step (see the Makefile in any of the SDK examples for an
 130 illustration of how to do so). The manifest file format is also
 131 <a class="reference internal" href="/native-client/reference/nacl-manifest-format.html"><em>documented</em></a>.</p>
 132 <h2 id="modules-and-instances">Modules and instances</h2>
 133 <p>A Native Client <strong>module</strong> is C or C++ code compiled into a PNaCl .pexe file or
 134 a NaCl .nexe file.</p>
 135 <p>An <strong>instance</strong> is a rectangle on a web page that is managed by a module. An
 136 instance may have a dimension of width=0 and height=0, meaning that the instance
 137 does not have any visible component on the web page. An instance is created by
 138 including an <code>&lt;embed&gt;</code> element in a web page. The <code>&lt;embed&gt;</code> element
 139 references a Native Client manifest file that loads the appropriate version of
 140 the module (either portable, or specific to the end-user&#8217;s architecture).  A
 141 module may be included in a web page multiple times by using multiple
 142 <code>&lt;embed&gt;</code> elements that refer to the module; in this case the Native Client
 143 runtime system loads the module once and creates multiple instances that are
 144 managed by the module.</p>
 145 <h2 id="native-client-modules-a-closer-look">Native Client modules: A closer look</h2>
 146 <p>A Native Client module must include three components:</p>
 147 <ul class="small-gap">
 148 <li>a factory function called <code>CreateModule()</code></li>
 149 <li>a Module class (derived from the <code>pp::Module</code> class)</li>
 150 <li>an Instance class (derived from the <code>pp:Instance</code> class)</li>
 151 </ul>
 152 <p>In the &#8220;Hello tutorial&#8221; example (in the <code>getting_started/part1</code> directory of
 153 the NaCl SDK), these three components are specified in the file
 154 <code>hello_tutorial.cc</code>. Here is the factory function:</p>
 155 <pre class="prettyprint">
 156 Module* CreateModule() {
 157   return new HelloTutorialModule();
 158 }
 159 </pre>
 160 <p>Native Client modules do not have a <code>main()</code> function. The <code>CreateModule()</code>
 161 factory function is the main binding point between a module and the browser, and
 162 serves as the entry point into the module. The browser calls <code>CreateModule()</code>
 163 when a module is first loaded; this function returns a Module object derived
 164 from the <code>pp::Module</code> class. The browser keeps a singleton of the Module
 165 object.</p>
 166 <p>Below is the Module class from the &#8220;Hello tutorial&#8221; example:</p>
 167 <pre class="prettyprint">
 168 class HelloTutorialModule : public pp::Module {
 169  public:
 170   HelloTutorialModule() : pp::Module() {}
 171   virtual ~HelloTutorialModule() {}
 172
 173   virtual pp::Instance* CreateInstance(PP_Instance instance) {
 174     return new HelloTutorialInstance(instance);
 175   }
 176 };
 177 </pre>
 178 <p>The Module class must include a <code>CreateInstance()</code> method. The browser calls
 179 the <code>CreateInstance()</code> method every time it encounters an <code>&lt;embed&gt;</code> element
 180 on a web page that references the same module. The <code>CreateInstance()</code> function
 181 creates and returns an Instance object derived from the <code>pp::Instance</code> class.</p>
 182 <p>Below is the Instance class from the &#8220;Hello tutorial&#8221; example:</p>
 183 <pre class="prettyprint">
 184 class HelloTutorialInstance : public pp::Instance {
 185  public:
 186   explicit HelloTutorialInstance(PP_Instance instance) : pp::Instance(instance) {}
 187   virtual ~HelloTutorialInstance() {}
 188
 189   virtual void HandleMessage(const pp::Var&amp; var_message) {}
 190 };
 191 </pre>
 192 <p>As in the example above, the Instance class for your module will likely include
 193 an implementation of the <code>HandleMessage()</code> function. The browser calls an
 194 instance&#8217;s <code>HandleMessage()</code> function every time the JavaScript code in an
 195 application calls <code>postMessage()</code> to send a message to the instance. See the
 196 <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Native Client messaging system</em></a> for more information about
 197 how to send messages between JavaScript code and Native Client modules.</p>
 198 <p>The NaCl code is only invoked to handle various browser-issued
 199 events and callbacks. There is no need to shut down the NaCl instance by
 200 calling the <code>exit()</code> function. NaCl modules will be shut down when the user
 201 leaves the web page, or the NaCl module&#8217;s <code>&lt;embed&gt;</code> is otherwise destroyed.
 202 If the NaCl module does call the <code>exit()</code> function, the instance will
 203 issue a <code>crash</code> event
 204 <a class="reference internal" href="/native-client/devguide/coding/progress-events.html"><em>which can be handled in Javascript</em></a>.</p>
 205 <p>While the <code>CreateModule()</code> factory function, the <code>Module</code> class, and the
 206 <code>Instance</code> class are required for a Native Client application, the code
 207 samples shown above don&#8217;t actually do anything. Subsequent sections in the
 208 Developer&#8217;s Guide build on these code samples and add more interesting
 209 functionality.</p>
 210 </section>
 211
 212 {{/partials.standard_nacl_article}}