[NaCl SDK Docs] Check in the generated NaCl SDK Documentation.

native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/application-structure.html

Index: native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/application-structure.html
diff --git a/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/application-structure.html b/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/application-structure.html
new file mode 100644
index 0000000000000000000000000000000000000000..89ee9790bc1b23b1c37cd0076343163db098f0c7
--- /dev/null
+++ b/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/coding/application-structure.html
@@ -0,0 +1,216 @@
+{{+bindTo:partials.standard_nacl_article}}
+
+<section id="application-structure">
+<span id="devcycle-application-structure"></span><h1 id="application-structure"><span id="devcycle-application-structure"></span>Application Structure</h1>

[Andy, 2014/01/22 00:24:14]

The two <span> tags on this line have the same ID, and they're not necessary but
they don't hurt anything.  Most of the generated docs seem to have these two
<span> tags at the top.

+<div class="contents local topic" id="contents">
+<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 &lt;embed&gt; 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 chapter of the Developer&#8217;s Guide describes the general structure of a
+Native Client application. The chapter 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 &#8220;Hello, World&#8221; 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>
+<section id="application-components">
+<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>
+</section><section id="html-file-and-the-embed-element">
+<span id="html-file"></span><h2 id="html-file-and-the-embed-element"><span id="html-file"></span>HTML file and the &lt;embed&gt; element</h2>
+<p>The <code>&lt;embed&gt;</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 &lt;embed&gt; element from the &#8220;Hello, World&#8221; application:</p>
+<pre class="prettyprint">
+&lt;embed id=&quot;hello_tutorial&quot;
+  width=0 height=0
+  src=&quot;hello_tutorial.nmf&quot;
+  type=&quot;application/x-pnacl&quot; /&gt;
+</pre>
+<p>In the <code>&lt;embed&gt;</code> element:</p>
+<dl class="docutils">
+<dt>name</dt>
+<dd>is the DOM name attribute for the Native Client module
+(&#8220;nacl_module&#8221; 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&#8217;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 &#8220;application/x-pnacl&#8221;. For architecture-specific
+Native Client modules the type must be &#8220;application/x-nacl&#8221;</dd>
+</dl>
+</section><section id="manifest-files">
+<span id="manifest-file"></span><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="http://code.google.com/chrome/extensions/manifest.html">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">
+{
+  &quot;program&quot;: {
+    &quot;portable&quot;: {
+      &quot;pnacl-translate&quot;: {
+        &quot;url&quot;: &quot;hello_tutorial.pexe&quot;
+      }
+    }
+  }
+}
+</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 &#8220;program&#8221; 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>&quot;url&quot;</code> key. URLs are specified relative to the location of the manifest file.
+Here is an example:</p>
+<pre class="prettyprint">
+{
+  &quot;program&quot;: {
+    &quot;x86-32&quot;: {
+      &quot;url&quot;: &quot;hello_tutorial_x86_32.nexe&quot;
+    },
+    &quot;x86-64&quot;: {
+      &quot;url&quot;: &quot;hello_tutorial_x86_64.nexe&quot;
+    },
+    &quot;arm&quot;: {
+      &quot;url&quot;: &quot;hello_tutorial_arm.nexe&quot;
+    }
+  }
+}
+</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 &#8220;files&#8221; 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>
+</section><section id="modules-and-instances">
+<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>&lt;embed&gt;</code> element in a web page. The <code>&lt;embed&gt;</code> element
+references a Native Client manifest file that loads the appropriate version of
+the module (either portable, or specific to the end-user&#8217;s architecture).  A
+module may be included in a web page multiple times by using multiple
+<code>&lt;embed&gt;</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>
+</section><section id="native-client-modules-a-closer-look">
+<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 &#8220;Hello tutorial&#8221; 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 &#8220;Hello tutorial&#8221; 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>&lt;embed&gt;</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 &#8220;Hello tutorial&#8221; 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&amp; 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&#8217;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&#8217;s <code>&lt;embed&gt;</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&#8217;t actually do anything. Subsequent chapters in the
+Developer&#8217;s Guide build on these code samples and add more interesting
+functionality.</p>
+</section></section>
+
+{{/partials.standard_nacl_article}}