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