Skip to content

GitLab

T
tangled
Commit 3e1df835 authored by jmedley's avatar jmedley Committed by Commit bot
Browse files
Options

Copy edit Learn Basics section. Includes first group of new illustrations to... 

Copy edit Learn Basics section. Includes first group of new illustrations to make overall site images look googly and at the same time part of a single design process.

BUG=none
R=
TEST=none
NOTRY=true
(documentation only change)

Review URL: https://codereview.chromium.org/581643004

Cr-Commit-Position: refs/heads/master@{#296017}
parent f3777e5f
Hide whitespace changes
Inline Side-by-side
Showing with 460 additions and 405 deletions
chrome/common/extensions/docs/templates/json/chrome_sidenav.json
View file @ 3e1df835
...@@ -693,7 +693,7 @@ ...@@ -693,7 +693,7 @@
"href": "/native-client/overview", "href": "/native-client/overview",
"items": [ "items": [
{ {
"title": "What Is Native Client?", "title": "Technical Overview",
"href": "/native-client/overview" "href": "/native-client/overview"
}, },
{ {
......
native_client_sdk/doc_generated/nacl-and-pnacl.html
View file @ 3e1df835
...@@ -6,93 +6,84 @@ ...@@ -6,93 +6,84 @@
<strong>Portable Native Client</strong>, and provides recommendations for when to use each.</p> <strong>Portable Native Client</strong>, and provides recommendations for when to use each.</p>
<div class="contents local" id="contents" style="display: none"> <div class="contents local" id="contents" style="display: none">
<ul class="small-gap"> <ul class="small-gap">
<li><a class="reference internal" href="#native-client-nacl" id="id3">Native Client (NaCl)</a></li> <li><a class="reference internal" href="#native-client-nacl" id="id6">Native Client (NaCl)</a></li>
<li><a class="reference internal" href="#portable-native-client-pnacl" id="id4">Portable Native Client (PNaCl)</a></li> <li><a class="reference internal" href="#portable-native-client-pnacl" id="id7">Portable Native Client (PNaCl)</a></li>
<li><a class="reference internal" href="#when-to-use-pnacl" id="id5">When to use PNaCl</a></li> <li><a class="reference internal" href="#when-to-use-pnacl" id="id8">When to use PNaCl</a></li>
<li><a class="reference internal" href="#when-to-use-nacl" id="id6">When to use NaCl</a></li> <li><a class="reference internal" href="#when-to-use-nacl" id="id9">When to use NaCl</a></li>
</ul> </ul>
</div><h2 id="native-client-nacl">Native Client (NaCl)</h2> </div><h2 id="native-client-nacl"><span id="id2"></span>Native Client (NaCl)</h2>
<p>Native Client enables the execution of native code securely inside web <p>Native Client enables the execution of native code securely inside web
applications through the use of advanced <a class="reference external" href="http://research.google.com/pubs/pub35649.html">Software Fault Isolation (SFI) applications through the use of advanced <a class="reference external" href="http://research.google.com/pubs/pub35649.html">Software Fault Isolation (SFI)
techniques</a>. Since its launch in techniques</a>. Native Client
2011, Native Client has provided developers with the ability to harness a allows you to harness a client machine&#8217;s computational power to a fuller extent
client machine&#8217;s computational power to a much fuller extent than traditional than traditional web technologies. It does this by running compiled C and C++
web technologies, by running compiled C and C++ code at near-native speeds and code at near-native speeds, and exposing a CPU&#8217;s full capabilities, including
taking advantage of multiple cores with shared memory.</p> SIMD vectors and multiple-core processing with shared memory.</p>
<p>While Native Client provides operating system independence, it requires <p>While Native Client provides operating system independence, it requires you to
developers to generate architecture-specific executable generate architecture-specific executables (<strong>nexe</strong>) for each hardware
(<strong>nexe</strong>) modules for each hardware platform. This is not only inconvenient platform. This is neither portable nor convenient, making it ill-suited for the
for developers, but architecture-specific machine code is not portable and thus open web.</p>
not well-suited for the open web. The traditional method of application <p>The traditional method of application distribution on the web is through self-
distribution on the web is through a self-contained bundle of HTML, CSS, contained bundles of HTML, CSS, JavaScript, and other resources (images, etc.)
JavaScript, and other resources (images, etc.) that can be hosted on a server that can be hosted on a server and run inside a web browser. With this type of
and run inside a web browser. With this type of distribution, a website distribution, a website created today should still work years later, on all
created today should still work years later, on all platforms. platforms. Architecture-specific executables are clearly not a good fit for
Architecture-specific executables are clearly not a good fit for distribution distribution on the web. Consequently, Native Client has been until recently
on the web. As a consequence, Native Client has been restricted to restricted to applications and browser extensions that are installed through the
applications and browser extensions that are installed through the
Chrome Web Store.</p> Chrome Web Store.</p>
<h2 id="portable-native-client-pnacl">Portable Native Client (PNaCl)</h2> <h2 id="portable-native-client-pnacl"><span id="id3"></span>Portable Native Client (PNaCl)</h2>
<p>PNaCl solves the portability problem by splitting the compilation process <p>PNaCl solves the portability problem by splitting the compilation process
into two parts:</p> into two parts:</p>
<ol class="arabic simple"> <ol class="arabic simple">
<li>compiling the source code to a portable bitcode format, and</li> <li>compiling the source code to a bitcode executable (pexe), and</li>
<li>translating the bitcode to a host-specific executable just before execution.</li> <li>translating the bitcode to a host-specific executable as soon as the module
loads in the browser but before any code execution.</li>
</ol> </ol>
<p>PNaCl enables developers to distribute <strong>portable executables</strong> (<strong>pexe</strong>) <p>This portability aligns Native Client with existing open web technologies such
modules that the hosting environment (in other words, the Chrome browser) can as JavaScript. You can distribute a pexe as part of an application (along with
translate to native code before executing. This portability aligns Native Client HTML, CSS, and JavaScript), and the user&#8217;s machine is simply able to run it.</p>
with existing open web technologies such as JavaScript. A developer can <p>With PNaCl, you&#8217;ll generate a single pexe, rather than multiple platform-
distribute a <strong>pexe</strong> as part of an application (along with HTML, CSS, and specific nexes. Since the pexe uses an abstract, architecture- and OS-
JavaScript), and the user&#8217;s machine is simply able to run it.</p> independent format, it does not suffer from the portability problem described
<p>With PNaCl, a developer generates a single <strong>pexe</strong> from source code, above. Although, PNaCl can be more efficient on some operating systems than on
rather than multiple platform-specific nexes. The <strong>pexe</strong> provides both others. PNaCl boasts the same level of security as NaCl. Future versions of
architecture- and OS-independence. Since the <strong>pexe</strong> uses an abstract, hosting environments should have no problem executing the pexe, even on new
architecture-independent format, it does not suffer from the portability architectures. Moreover, if an existing architecture is enhanced, the pexe
problem described above. Future versions of hosting environments should doesn&#8217;t need to be recompiled. In some cases the client-side translation will
have no problem executing the <strong>pexe</strong>, even on new architectures. automatically take advantage of new capabilities. A pexe can be part of any web
Moreover, if an existing architecture is subsequently enhanced, the application. It does not have to be distributed through the Chrome Web Store. In
<strong>pexe</strong> doesn&#8217;t even have to be recompiled. In some cases the short, PNaCl combines the portability of existing web technologies with the
client-side translation will automatically be able to take advantage of performance and security benefits of Native Client.</p>
the new capabilities. A <strong>pexe</strong> module can be part of any web
application. It does not have to be distributed through the Chrome Web
Store. In short, PNaCl combines the portability of existing web technologies
with the performance and security benefits of Native Client.</p>
<p>PNaCl is a new technology, and as such it still has a few limitations <p>PNaCl is a new technology, and as such it still has a few limitations
as compared to NaCl. These limitations are described below.</p> as compared to NaCl. These limitations are described below.</p>
<h2 id="when-to-use-pnacl">When to use PNaCl</h2> <h2 id="when-to-use-pnacl"><span id="id4"></span>When to use PNaCl</h2>
<p>PNaCl is the preferred toolchain for Native Client, and the only way to deploy <p>PNaCl is the preferred toolchain for Native Client, and the only way to deploy
Native Client modules on the open web. Unless your project is subject to one Native Client modules without the Google Web Store. Unless your project is
of the narrow limitations described below subject to one of the narrow limitations described under &#8220;<a class="reference internal" href="#when-to-use-nacl"><em>When to use
(see <a class="reference internal" href="#when-to-use-nacl"><em>When to use NaCl</em></a>), you should use PNaCl.</p> NaCl</em></a>&#8221;, you should use PNaCl.</p>
<p>Beginning with version 31, the Chrome browser supports translation of <p>Since version 31, Chrome supports translation of pexe
<strong>pexe</strong> modules and their use in web applications, without requiring modules and their use in web applications without requiring installation either
any installation (either of a browser plugin or of the applications of a browser plug-in or of the applications themselves. Native Client and PNaCl
themselves). Native Client and PNaCl are open-source technologies, and are open-source technologies, and our hope is that they will be added to other
our hope is that they will be added to other hosting platforms in the hosting platforms in the future.</p>
future.</p> <p>If controlled distribution through the Chrome Web Store is an important part of
<p>If controlled distribution through the Chrome Web Store is an important part your product plan, the benefits of PNaCl are less critical for you. But you can
of your product plan, the benefits of PNaCl are less critical for you. But still use the PNaCl toolchain and distribute your application through the Chrome
you can still use the PNaCl toolchain and distribute your application Web Store, and thereby take advantage of the conveniences of PNaCl, such as not
through the Chrome Web Store, and thereby take advantage of the having to explicitly compile your application for all supported architectures.</p>
conveniences of PNaCl, such as not having to explicitly compile your application <h2 id="when-to-use-nacl"><span id="id5"></span>When to use NaCl</h2>
for all supported architectures.</p> <p>Use NaCl if any of the following apply to your application:</p>
<h2 id="when-to-use-nacl"><span id="id2"></span>When to use NaCl</h2>
<p>The limitations below apply to the current release of PNaCl. If any of
these limitations are critical for your application, you should use
non-portable NaCl:</p>
<ul class="small-gap"> <ul class="small-gap">
<li>PNaCl does not support architecture-specific <li>Your application requires architecture-specific instructions such as, for
instructions in an application (i.e., inline assembly), but tries to example, inline assembly. PNaCl tries to offer high-performance portable
offer high-performance portable equivalents. One such example is equivalents. One such example is PNaCl&#8217;s <a class="reference internal" href="/native-client/reference/pnacl-c-cpp-language-support.html#portable-simd-vectors"><em>Portable SIMD Vectors</em></a>.</li>
PNaCl&#8217;s <a class="reference internal" href="/native-client/reference/pnacl-c-cpp-language-support.html#portable-simd-vectors"><em>Portable SIMD Vectors</em></a>.</li> <li>Your application uses dynamic linking. PNaCl only supports static linking
<li>PNaCl only supports static linking with the <code>newlib</code> with a PNaCl port of the <code>newlib</code> C standard library. Dynamic linking and
C standard library (the Native Client SDK provides a PNaCl port of <code>glibc</code> are not yet supported in PNaCl. Work is under way to enable dynamic
<code>newlib</code>). Dynamic linking and <code>glibc</code> are not yet supported. linking in future versions of PNaCl.</li>
Work is under way to enable dynamic linking in future versions of PNaCl.</li> <li>Your application uses certain GNU extensions not supported by PNaCl&#8217;s LLVM
<li>PNaCl does not support some GNU extensions toolchain, like taking the address of a label for computed <code>goto</code>, or nested
like taking the address of a label for computed <code>goto</code>, or nested
functions.</li> functions.</li>
</ul> </ul>
</section> </section>
......
native_client_sdk/doc_generated/overview.html
View file @ 3e1df835
...@@ -4,77 +4,93 @@ ...@@ -4,77 +4,93 @@
<span id="overview"></span><h1 id="technical-overview"><span id="overview"></span>Technical Overview</h1> <span id="overview"></span><h1 id="technical-overview"><span id="overview"></span>Technical Overview</h1>
<div class="contents local" id="contents" style="display: none"> <div class="contents local" id="contents" style="display: none">
<ul class="small-gap"> <ul class="small-gap">
<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li> <li><a class="reference internal" href="#why-use-native-client" id="id9">Why use Native Client?</a></li>
<li><a class="reference internal" href="#why-use-native-client" id="id3">Why use Native Client?</a></li> <li><a class="reference internal" href="#benefits-of-native-client" id="id10">Benefits of Native Client</a></li>
<li><a class="reference internal" href="#common-use-cases" id="id4">Common use cases</a></li> <li><a class="reference internal" href="#common-use-cases" id="id11">Common use cases</a></li>
<li><p class="first"><a class="reference internal" href="#how-native-client-works" id="id5">How Native Client works</a></p> <li><p class="first"><a class="reference internal" href="#how-native-client-works" id="id12">How Native Client works</a></p>
<ul class="small-gap"> <ul class="small-gap">
<li><a class="reference internal" href="#security" id="id6">Security</a></li> <li><a class="reference internal" href="#toolchains" id="id13">Toolchains</a></li>
<li><a class="reference internal" href="#portability" id="id7">Portability</a></li> <li><a class="reference internal" href="#security" id="id14">Security</a></li>
<li><a class="reference internal" href="#toolchains" id="id8">Toolchains</a></li> <li><a class="reference internal" href="#portability" id="id15">Portability</a></li>
</ul> </ul>
</li> </li>
<li><p class="first"><a class="reference internal" href="#native-client-in-a-web-application" id="id9">Native Client in a web application</a></p> <li><p class="first"><a class="reference internal" href="#structure-of-a-web-application" id="id16">Structure of a web application</a></p>
<ul class="small-gap"> <ul class="small-gap">
<li><a class="reference internal" href="#pepper-plugin-api" id="id10">Pepper Plugin API</a></li> <li><a class="reference internal" href="#pepper-plug-in-api" id="id17">Pepper plug-in API</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#versioning" id="id11">Versioning</a></li> <li><a class="reference internal" href="#versioning" id="id18">Versioning</a></li>
<li><a class="reference internal" href="#where-to-start" id="id12">Where to start</a></li> <li><a class="reference internal" href="#where-to-start" id="id19">Where to start</a></li>
</ul> </ul>
</div><h2 id="introduction">Introduction</h2> </div><p><strong>Native Client</strong> (NaCl) is an open-source technology for running native
<p><strong>Native Client</strong> (NaCl) is an open-source technology for running native
compiled code in the browser, with the goal of maintaining the portability compiled code in the browser, with the goal of maintaining the portability
and safety that users expect from web applications. Native Client expands web and safety that users expect from web applications. Native Client expands web
programming beyond JavaScript, enabling developers to enhance their web programming beyond JavaScript, enabling you to enhance your web applications
applications using their preferred language. This document describes some of using your preferred language. This document describes some of the key benefits
the key benefits and common use cases of Native Client.</p> and common use cases of Native Client.</p>
<p>Google has implemented the open-source <a class="reference external" href="http://www.chromium.org/nativeclient">Native Client project</a> in the Chrome browser on Windows, Mac, <p>Google has implemented the open-source <a class="reference external" href="http://www.chromium.org/nativeclient">Native Client project</a> in the Chrome browser on Windows, Mac,
Linux, and Chrome OS. The <a class="reference internal" href="/native-client/sdk/download.html"><em>Native Client Software Development Kit (SDK)</em></a>, itself an open-source project, lets developers create web Linux, and Chrome OS. The <a class="reference internal" href="/native-client/sdk/download.html"><em>Native Client Software Development Kit (SDK)</em></a>, itself an open-source project, lets you create web applications
applications that use NaCl and run in Chrome across multiple platforms.</p> that use NaCl and run in Chrome across multiple platforms.</p>
<p>A web application that uses Native Client generally consists of a combination of <p>A Native Client web application consists of JavaScript, HTML, CSS, and a NaCl
JavaScript, HTML, CSS, and a NaCl module that is written in a language supported module written in a language supported by the SDK. The NaCl SDK currently
by the SDK. The NaCl SDK currently supports C and C++; as compilers for supports C and C++; as compilers for additional languages are developed, the SDK
additional languages are developed, the SDK will be updated to support those will be updated.</p>
languages as well.</p> <div class="figure">
<img alt="/native-client/images/web-app-with-nacl.png" src="/native-client/images/web-app-with-nacl.png" /> <img alt="A web application with and without Native Client" src="/native-client/images/web-app-with-nacl.png" />
<h2 id="why-use-native-client">Why use Native Client?</h2> <p class="caption">A web application with and without Native Client</p>
</div>
<p>Native Client comes in two flavors: traditional (NaCl) and portable (PNaCl).
Traditional, which must be distributed through the Chrome Web Store lets you
target a specific hardware platform. Portable can run on the open web. A
bitcode file that can be loaded from any web server is downloaded to a client
machine and converted to hardware-specific code before any execution. For
details, see <a class="reference internal" href="/native-client/nacl-and-pnacl.html"><em>NaCl and PNaCl</em></a>.</p>
<h2 id="why-use-native-client"><span id="id1"></span>Why use Native Client?</h2>
<p>Native Client open-source technology is designed to run compiled code <p>Native Client open-source technology is designed to run compiled code
securely inside a browser at near-native speeds. Native Client puts web securely inside a browser at near-native speeds. Native Client gives web
applications on the same playing field as desktop software&#8212;it provides the applications some advantages of desktop software. Specifically, it provides the
means to fully harness the client&#8217;s computational resources for applications means to fully harness the client&#8217;s computational resources for applications
such as 3D games, multimedia editors, CAD modeling, such as:</p>
client-side data analytics, and interactive simulations. <ul class="small-gap">
Native Client also aims to give C and C++ (and eventually other languages) the <li>3D games</li>
same level of portability and safety that JavaScript provides on the web today.</p> <li>multimedia editors</li>
<p>Important benefits of Native Client include:</p> <li>CAD modeling</li>
<li>client-side data analytics</li>
<li>interactive simulations.</li>
</ul>
<p>Native Client gives C and C++ (and other languages targeting it) the same level
of portability and safety as JavaScript.</p>
<h2 id="benefits-of-native-client"><span id="id2"></span>Benefits of Native Client</h2>
<p>Benefits of Native Client include:</p>
<ul class="small-gap"> <ul class="small-gap">
<li><strong>Graphics, audio, and much more:</strong> Running native code modules that render 2D <li><strong>Graphics, audio, and much more:</strong> Running native code modules that render 2D
and 3D graphics, play audio, respond to mouse and keyboard events, run on and 3D graphics, play audio, respond to mouse and keyboard events, run on
multiple threads, and access memory directly&#8212;all without requiring multiple threads, and access memory directly&#8212;all without requiring the user
the user to install a plugin.</li> to install a plug-in.</li>
<li><strong>Portability:</strong> Writing your applications once and running them on operating <li><strong>Portability:</strong> Writing your applications once and running them on multiple
systems (Windows, Linux, Mac, and Chrome OS) and CPU architectures (x86 and operating systems (Windows, Linux, Mac, and Chrome OS) and CPU architectures
ARM).</li> (x86 and ARM).</li>
<li><strong>Easy migration path to the web:</strong> Leveraging years of work in existing <li><strong>Easy migration path to the web:</strong> Leveraging years of work in existing
desktop applications. Native Client makes the transition from the desktop to a desktop applications. Native Client makes the transition from the desktop to
web application significantly easier because it supports C and C++.</li> a web application significantly easier because it supports C and C++.</li>
<li><strong>Security:</strong> Protecting the user&#8217;s system from malicious or buggy <li><strong>Security:</strong> Protecting the user&#8217;s system from malicious or buggy
applications through Native Client&#8217;s double sandbox model. This model offers applications through Native Client&#8217;s double sandbox model. This model offers
the safety of traditional web applications without sacrificing performance and the safety of traditional web applications without sacrificing performance
without requiring users to install a plugin.</li> and without requiring users to install a plug-in.</li>
<li><strong>Performance:</strong> Running at speeds comparable to desktop applications (within <li><strong>Performance:</strong> Running at speeds within 5% to 15% of a native desktop
5-15% of native speed). Native Client also allows applications to harness all application. Native Client also allows applications to harness all available
available CPU cores via a threading API; this enables demanding applications CPU cores via a threading API. This enables demanding applications such as
such as console-quality games to run inside the browser.</li> console-quality games to run inside the browser.</li>
</ul> </ul>
<h2 id="common-use-cases">Common use cases</h2> <h2 id="common-use-cases"><span id="id3"></span>Common use cases</h2>
<p>Typical use cases for Native Client include the following:</p> <p>Typical use cases for Native Client include the following:</p>
<ul class="small-gap"> <ul class="small-gap">
<li><strong>Existing software components:</strong> With support for C and C++, Native <li><strong>Existing software components:</strong> Native Client lets you repurpose existing
Client lets you to reuse existing software modules in web applications. You C and C++ software in web applications. You don&#8217;t need to rewrite and debug
don&#8217;t need to rewrite and debug code that already works.</li> code that already works. It also lets your application take advantage of
things the browser does well such as handling user interaction and processing
events. You can also take advantage of the latest developments in HTML5.</li>
<li><strong>Legacy desktop applications:</strong> Native Client provides a smooth migration <li><strong>Legacy desktop applications:</strong> Native Client provides a smooth migration
path from desktop applications to the web. You can port and recompile existing path from desktop applications to the web. You can port and recompile existing
code for the computation engine of your application directly to Native Client, code for the computation engine of your application directly to Native Client,
...@@ -82,9 +98,9 @@ and need rebuild only the user interface and event handling portions for the ...@@ -82,9 +98,9 @@ and need rebuild only the user interface and event handling portions for the
browser.</li> browser.</li>
<li><strong>Heavy computation in enterprise applications:</strong> Native Client can handle the <li><strong>Heavy computation in enterprise applications:</strong> Native Client can handle the
number crunching required by large-scale enterprise applications. To ensure number crunching required by large-scale enterprise applications. To ensure
protection of user data, Native Client enables you to build complex protection of user data, Native Client lets you run complex cryptographic
cryptographic algorithms directly into the browser so that unencrypted data algorithms directly in the browser so that unencrypted data never goes out
never goes out over the network.</li> over the network.</li>
<li><strong>Multimedia applications:</strong> Codecs for processing sounds, images, and movies <li><strong>Multimedia applications:</strong> Codecs for processing sounds, images, and movies
can be added to the browser in a Native Client module.</li> can be added to the browser in a Native Client module.</li>
<li><strong>Games:</strong> Native Client lets web applications run at close to native <li><strong>Games:</strong> Native Client lets web applications run at close to native
...@@ -94,51 +110,64 @@ shaders. Native Client is a natural fit for running a physics engine or ...@@ -94,51 +110,64 @@ shaders. Native Client is a natural fit for running a physics engine or
artificial intelligence module that powers a sophisticated web game. artificial intelligence module that powers a sophisticated web game.
Native Client also enables applications to run unchanged across Native Client also enables applications to run unchanged across
many platforms.</li> many platforms.</li>
<li><strong>Any application that requires acceleration</strong>: Native Client fits seamlessly <li><strong>Any application that requires acceleration:</strong> Native Client fits seamlessly
into web applications&#8212;it&#8217;s up to you to decide to what extent to use it. into web applications. It&#8217;s up to you to decide to what extent to use it.
Use of Native Client covers the full spectrum from complete applications to Use of Native Client covers the full spectrum from complete applications to
small optimized routines that accelerate vital parts of web applications.</li> small optimized routines that accelerate vital parts of web applications.</li>
</ul> </ul>
<h2 id="how-native-client-works"><span id="link-how-nacl-works"></span>How Native Client works</h2> <h2 id="how-native-client-works"><span id="link-how-nacl-works"></span>How Native Client works</h2>
<p>Native Client is an umbrella name for a set of related software components that <p>Native Client is an umbrella name for a set of related software components for
provide a way to develop C/C++ applications and run them securely on the web.</p> developing C/C++ applications and running them securely on the web. At a high
<p>At a high level, Native Client consists of:</p> level, Native Client consists of:</p>
<ul class="small-gap"> <ul class="small-gap">
<li><strong>Toolchains</strong>: Collections of development tools (compilers, linkers, etc.) <li><strong>Toolchains:</strong> collections of development tools (compilers, linkers, etc.)
that transform C/C++ code to Native Client modules.</li> that transform C/C++ code to Portable Native Client modules or Native Client
<li><strong>Runtime components</strong>: components embedded in the browser or other modules.</li>
host platforms that allow execution of Native Client modules <li><strong>Runtime components:</strong> components embedded in the browser or other host
securely and efficiently.</li> platforms that allow execution of Native Client modules securely and
efficiently.</li>
</ul> </ul>
<p>The following diagram shows how these components interact:</p> <p>The following diagram shows how these components interact:</p>
<img alt="/native-client/images/nacl-pnacl-component-diagram.png" src="/native-client/images/nacl-pnacl-component-diagram.png" /> <div class="figure">
<p>The left side of the diagram shows how to use Portable Native Client <img alt="The Native Client toolchains and their outputs" src="/native-client/images/nacl-pnacl-component-diagram.png" />
(PNaCl, pronounced &#8220;pinnacle&#8221;). Developers use the PNaCl toolchain <p class="caption">The Native Client toolchains and their outputs</p>
to produce a single, portable (<strong>pexe</strong>) module. At runtime, a translator </div>
built into the browser translates the pexe into native code for the <h3 id="toolchains"><span id="id4"></span>Toolchains</h3>
relevant client architecture. Translation occurs before any code is executed.</p> <p>A Native Client toolchain consists of a compiler, a linker, an assembler and
<p>The right side of the diagram shows how to use (non-portable) Native Client. other tools that are used to convert C/C++ source code into a module that is
Developers use a nacl-gcc based toolchain to produce multiple loadable by a browser.</p>
architecture-dependent (<strong>nexe</strong>) modules, which are packaged into an <p>The Native Client SDK provides two toolchains:</p>
application. At runtime, the browser decides which nexe to load based <ul class="small-gap">
on the architecture of the client machine.</p> <li>The left side of the diagram shows <strong>Portable Native Client</strong> (PNaCl,
<h3 id="security">Security</h3> pronounced &#8220;pinnacle&#8221;). An LLVM based toolchain produces a single, portable
(<strong>pexe</strong>) module. At runtime an ahead-of-time (AOT) translator, built into
the browser, translates the pexe into native code for the relevant client
architecture.</li>
<li>The right side of the diagram shows <strong>(non-portable) Native Client</strong>. A GCC
based toolchain produces multiple architecture-dependent (<strong>nexe</strong>) modules,
which are packaged into an application. At runtime the browser determines
which nexe to load based on the architecture of the client machine.</li>
</ul>
<p>The PNaCl toolchain is recommended for most applications. The NaCl-GCC
toolchain should only be used for applications that won&#8217;t be distributed on the
open web.</p>
<h3 id="security"><span id="id5"></span>Security</h3>
<p>Since Native Client permits the execution of native code on client machines, <p>Since Native Client permits the execution of native code on client machines,
special security measures have to be implemented:</p> special security measures have to be implemented:</p>
<ul class="small-gap"> <ul class="small-gap">
<li>The NaCl sandbox ensures that code accesses system resources only through <li>The NaCl sandbox ensures that code accesses system resources only through
safe, whitelisted APIs, and operates within its limits without attempting to safe, whitelisted APIs, and operates within its limits without attempting to
interfere with other code running either within the browser or outside it.</li> interfere with other code running either within the browser or outside it.</li>
<li>The NaCl validator statically analyzes code prior to running it <li>The NaCl validator statically analyzes code before running it to make sure it
to make sure it only uses code and data patterns that are permitted and safe.</li> only uses code and data patterns that are permitted and safe.</li>
</ul> </ul>
<p>The above security measures are in addition to the existing sandbox in the <p>These security measures are in addition to the existing sandbox in the
Chrome browser&#8212;the Native Client module always executes in a process with Chrome browser. The Native Client module always executes in a process with
restricted permissions. The only interaction between this process and the restricted permissions. The only interaction between this process and the
outside world is through sanctioned browser interfaces. Because of the outside world is through defined browser interfaces. Because of the
combination of the NaCl sandbox and the Chrome sandbox, we say that combination of the NaCl sandbox and the Chrome sandbox, we say that
Native Client employs a double sandbox design.</p> Native Client employs a <strong>double sandbox</strong> design.</p>
<h3 id="portability">Portability</h3> <h3 id="portability"><span id="id6"></span>Portability</h3>
<p>Portable Native Client (PNaCl, prounounced &#8220;pinnacle&#8221;) employs state-of-the-art <p>Portable Native Client (PNaCl, prounounced &#8220;pinnacle&#8221;) employs state-of-the-art
compiler technology to compile C/C++ source code to a portable bitcode compiler technology to compile C/C++ source code to a portable bitcode
executable (<strong>pexe</strong>). PNaCl bitcode is an OS- and architecture-independent executable (<strong>pexe</strong>). PNaCl bitcode is an OS- and architecture-independent
...@@ -146,53 +175,49 @@ format that can be freely distributed on the web and <a class="reference interna ...@@ -146,53 +175,49 @@ format that can be freely distributed on the web and <a class="reference interna
applications</em></a>.</p> applications</em></a>.</p>
<p>The PNaCl translator is a component embedded in the Chrome browser; its task is <p>The PNaCl translator is a component embedded in the Chrome browser; its task is
to run pexe modules. Internally, the translator compiles a pexe to a nexe to run pexe modules. Internally, the translator compiles a pexe to a nexe
(a native executable for the client platform&#8217;s architecture), and then executes (described above), and then executes the nexe within the Native Client sandbox
the nexe within the Native Client sandbox as described above. It also uses as described above. The translator uses intelligent caching to avoid
intelligent caching to avoid re-compiling the pexe if it was previously compiled re-compiling the pexe if it was previously compiled on the client&#8217;s browser.</p>
on the client&#8217;s browser.</p>
<p>Native Client also supports the execution of nexe modules directly in the <p>Native Client also supports the execution of nexe modules directly in the
browser. However, since nexes contain architecture-specific machine code, browser. However, since nexes contain architecture-specific machine code, they
they are not allowed to be distributed on the open web&#8212;they can only be are not allowed to be distributed on the open web. They can only be used as part
used as part of applications and extensions that are installed from the of applications and extensions that are installed from the Chrome Web Store.</p>
Chrome Web Store.</p>
<p>For more details on the difference between NaCl and PNaCl, see <p>For more details on the difference between NaCl and PNaCl, see
<a class="reference internal" href="/native-client/nacl-and-pnacl.html"><em>NaCl and PNaCl</em></a>.</p> <a class="reference internal" href="/native-client/nacl-and-pnacl.html"><em>NaCl and PNaCl</em></a>.</p>
<h3 id="toolchains"><span id="id1"></span>Toolchains</h3> <h2 id="structure-of-a-web-application"><span id="link-nacl-in-web-apps"></span>Structure of a web application</h2>
<p>A toolchain is a set of tools used to create an application from a set of
source files. In the case of Native Client, a toolchain consists of a compiler,
linker, assembler and other tools that are used to convert an
application written in C/C++ into a module that is loadable by the browser.</p>
<p>The Native Client SDK provides two toolchains:</p>
<ul class="small-gap">
<li>a <strong>PNaCl toolchain</strong> for generating portable NaCl modules (pexe files)</li>
<li>a <strong>gcc-based toolchain (nacl-gcc)</strong> for generating non-portable NaCl modules
(nexe files)</li>
</ul>
<p>The PNaCl toolchain is recommended for most applications. The nacl-gcc
toolchain should only be used for applications that will not be distributed
on the open web.</p>
<h2 id="native-client-in-a-web-application"><span id="link-nacl-in-web-apps"></span>Native Client in a web application</h2>
<p id="application-files">A Native Client application consists of a set of files:</p> <p id="application-files">A Native Client application consists of a set of files:</p>
<ul class="small-gap"> <ul class="small-gap">
<li><strong>HTML</strong>, <strong>CSS</strong>, and <strong>JavaScript</strong> files, as in any modern web <li><p class="first"><strong>HTML and CSS:</strong> The HTML file tells the browser where to find the manifest
application. The JavaScript code is responsible for communicating with the (nmf file) through the embed tag.</p>
NaCl module.</li> <pre class="prettyprint">
<li>A <strong>pexe</strong> (portable NaCl) file. This module uses the <a class="reference internal" href="#link-pepper"><em>Pepper</em></a> API, which provides the bridge to JavaScript and &lt;embed name=&quot;mygame&quot; src=&quot;mygame.nmf&quot; type=&quot;application/x-pnacl&quot; /&gt;
browser resources.</li> </pre>
<li>A Native Client <strong>manifest</strong> file that specifies the pexe to load, along with </li>
some loading options. This manifest file is embedded into the HTML page <li><p class="first"><strong>Manifest:</strong> The manifest identifies the module to load and specifies
through an <code>&lt;embed&gt;</code> tag, as shown in the figure below.</li> options. For example, &#8220;mygame.nmf&#8221; might look like this:</p>
<pre class="prettyprint">
{...
...
&quot;url&quot;: &quot;mygame.pexe&quot;,
}
</pre>
</li>
<li><strong>pexe (portable NaCl file):</strong> A compiled Native Client module. It uses the
<a class="reference internal" href="#link-pepper"><em>Pepper API</em></a>, which provides a bridge to JavaScript and
other browser resources.</li>
</ul> </ul>
<img alt="/native-client/images/nacl-in-a-web-app.png" src="/native-client/images/nacl-in-a-web-app.png" /> <div class="figure">
<img alt="Structure of a web application" src="/native-client/images/nacl-in-a-web-app.png" />
<p class="caption">Structure of a web application</p>
</div>
<p>For more details, see <a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>Application Structure</em></a>.</p> <p>For more details, see <a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>Application Structure</em></a>.</p>
<h3 id="pepper-plugin-api"><span id="link-pepper"></span>Pepper Plugin API</h3> <h3 id="pepper-plug-in-api"><span id="link-pepper"></span>Pepper plug-in API</h3>
<p>The Pepper Plugin API (PPAPI), called <strong>Pepper</strong> for convenience, is an <p>The Pepper plug-in API (PPAPI), called <strong>Pepper</strong> for convenience, is an
open-source, cross-platform C/C++ API for web browser plugins. From the point open-source, cross-platform C/C++ API for web browser plug-ins. Pepper allows a
of view of Native Client, Pepper allows a C/C++ module to communicate with C/C++ module to communicate with the hosting browser and to access system-level
the hosting browser and get access to system-level functions in a safe and functions in a safe and portable way. One of the security constraints in Native
portable way. One of the security constraints in Native Client is that modules Client is that modules cannot make OS-level calls. Pepper provides analogous
cannot make any OS-level calls directly. Pepper provides analogous APIs that APIs that modules can use instead.</p>
modules can target instead.</p>
<p>You can use the Pepper APIs to gain access to the full array of browser <p>You can use the Pepper APIs to gain access to the full array of browser
capabilities, including:</p> capabilities, including:</p>
<ul class="small-gap"> <ul class="small-gap">
...@@ -201,22 +226,22 @@ capabilities, including:</p> ...@@ -201,22 +226,22 @@ capabilities, including:</p>
<li><a class="reference internal" href="/native-client/devguide/coding/audio.html"><em>Playing audio</em></a>.</li> <li><a class="reference internal" href="/native-client/devguide/coding/audio.html"><em>Playing audio</em></a>.</li>
<li><a class="reference internal" href="/native-client/devguide/coding/3D-graphics.html"><em>Rendering 3D graphics</em></a>.</li> <li><a class="reference internal" href="/native-client/devguide/coding/3D-graphics.html"><em>Rendering 3D graphics</em></a>.</li>
</ul> </ul>
<p>Pepper includes both a C API and a C++ API. The C++ API is a set of bindings <p>Pepper includes both a <a class="reference internal" href="/native-client/c-api.html"><em>C API</em></a> and a <a class="reference internal" href="/native-client/cpp-api.html"><em>C++ API</em></a>.
written on top of the C API. For additional information about Pepper, see The C++ API is a set of bindings written on top of the C API. For additional
<a class="reference external" href="http://code.google.com/p/ppapi/wiki/Concepts">Pepper Concepts</a>.</p> information about Pepper, see <a class="reference external" href="http://code.google.com/p/ppapi/wiki/Concepts">Pepper Concepts</a>.</p>
<h2 id="versioning">Versioning</h2> <h2 id="versioning"><span id="id7"></span>Versioning</h2>
<p>Chrome is released on a six week cycle, and developer versions of Chrome are <p>Chrome is released on a six week cycle, and developer versions of Chrome are
pushed to the public beta channel three weeks before each release. As with any pushed to the public beta channel three weeks before each release. As with any
software, each release of Chrome may include changes to Native Client and the software, each release of Chrome may include changes to Native Client and the
Pepper interfaces that may require modification to existing applications. Pepper interfaces that may require modification to existing applications.
However, modules compiled for one version of Pepper/Chrome should work with However, modules compiled for one version of Pepper/Chrome should work with
subsequent versions of Pepper/Chrome. The SDK includes multiple versions of the subsequent versions of Pepper/Chrome. The SDK includes multiple versions of the
Pepper APIs to help developers make adjustments to API changes and take Pepper APIs to help you make adjustments to API changes and take
advantage of new features: <a class="reference external" href="/native-client/pepper_stable">stable</a>, <a class="reference external" href="/native-client/pepper_beta">beta</a> and <a class="reference external" href="/native-client/pepper_dev">dev</a>.</p> advantage of new features: <a class="reference external" href="/native-client/pepper_stable">stable</a>, <a class="reference external" href="/native-client/pepper_beta">beta</a> and <a class="reference external" href="/native-client/pepper_dev">dev</a>.</p>
<h2 id="where-to-start">Where to start</h2> <h2 id="where-to-start"><span id="id8"></span>Where to start</h2>
<p>The <a class="reference internal" href="/native-client/quick-start.html"><em>Quick Start</em></a> document provides links to downloads and <p>The <a class="reference internal" href="/native-client/quick-start.html"><em>Quick Start</em></a> document provides links to downloads and
documentation that should help you get started with developing and distributing documentation to help you get started with developing and distributing Native
Native Client applications.</p> Client applications.</p>
</section> </section>
{{/partials.standard_nacl_article}} {{/partials.standard_nacl_article}}
native_client_sdk/doc_generated/sitemap.html
View file @ 3e1df835
...@@ -6,11 +6,11 @@ ...@@ -6,11 +6,11 @@
<div class="toctree-wrapper compound"> <div class="toctree-wrapper compound">
<ul class="small-gap"> <ul class="small-gap">
<li class="toctree-l1"><a class="reference internal" href="/native-client/overview.html">Technical Overview</a><ul class="small-gap"> <li class="toctree-l1"><a class="reference internal" href="/native-client/overview.html">Technical Overview</a><ul class="small-gap">
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#why-use-native-client">Why use Native Client?</a></li> <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#why-use-native-client">Why use Native Client?</a></li>
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#benefits-of-native-client">Benefits of Native Client</a></li>
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#common-use-cases">Common use cases</a></li> <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#common-use-cases">Common use cases</a></li>
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#how-native-client-works">How Native Client works</a></li> <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#how-native-client-works">How Native Client works</a></li>
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#native-client-in-a-web-application">Native Client in a web application</a></li> <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#structure-of-a-web-application">Structure of a web application</a></li>
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#versioning">Versioning</a></li> <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#versioning">Versioning</a></li>
<li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#where-to-start">Where to start</a></li> <li class="toctree-l2"><a class="reference internal" href="/native-client/overview.html#where-to-start">Where to start</a></li>
</ul> </ul>
......
native_client_sdk/src/doc/nacl-and-pnacl.rst
View file @ 3e1df835
...@@ -12,103 +12,102 @@ This document describes the differences between **Native Client** and ...@@ -12,103 +12,102 @@ This document describes the differences between **Native Client** and
:backlinks: none :backlinks: none
:depth: 2 :depth: 2
.. _native-client-nacl:
Native Client (NaCl) Native Client (NaCl)
==================== ====================
Native Client enables the execution of native code securely inside web Native Client enables the execution of native code securely inside web
applications through the use of advanced `Software Fault Isolation (SFI) applications through the use of advanced `Software Fault Isolation (SFI)
techniques <http://research.google.com/pubs/pub35649.html>`_. Since its launch in techniques <http://research.google.com/pubs/pub35649.html>`_. Native Client
2011, Native Client has provided developers with the ability to harness a allows you to harness a client machine's computational power to a fuller extent
client machine's computational power to a much fuller extent than traditional than traditional web technologies. It does this by running compiled C and C++
web technologies, by running compiled C and C++ code at near-native speeds and code at near-native speeds, and exposing a CPU's full capabilities, including
taking advantage of multiple cores with shared memory. SIMD vectors and multiple-core processing with shared memory.
While Native Client provides operating system independence, it requires While Native Client provides operating system independence, it requires you to
developers to generate architecture-specific executable generate architecture-specific executables (**nexe**) for each hardware
(**nexe**) modules for each hardware platform. This is not only inconvenient platform. This is neither portable nor convenient, making it ill-suited for the
for developers, but architecture-specific machine code is not portable and thus open web.
not well-suited for the open web. The traditional method of application
distribution on the web is through a self-contained bundle of HTML, CSS, The traditional method of application distribution on the web is through self-
JavaScript, and other resources (images, etc.) that can be hosted on a server contained bundles of HTML, CSS, JavaScript, and other resources (images, etc.)
and run inside a web browser. With this type of distribution, a website that can be hosted on a server and run inside a web browser. With this type of
created today should still work years later, on all platforms. distribution, a website created today should still work years later, on all
Architecture-specific executables are clearly not a good fit for distribution platforms. Architecture-specific executables are clearly not a good fit for
on the web. As a consequence, Native Client has been restricted to distribution on the web. Consequently, Native Client has been until recently
applications and browser extensions that are installed through the restricted to applications and browser extensions that are installed through the
Chrome Web Store. Chrome Web Store.
.. _portable-native-client-pnacl:
Portable Native Client (PNaCl) Portable Native Client (PNaCl)
============================== ==============================
PNaCl solves the portability problem by splitting the compilation process PNaCl solves the portability problem by splitting the compilation process
into two parts: into two parts:
#. compiling the source code to a portable bitcode format, and #. compiling the source code to a bitcode executable (pexe), and
#. translating the bitcode to a host-specific executable just before execution. #. translating the bitcode to a host-specific executable as soon as the module
loads in the browser but before any code execution.
PNaCl enables developers to distribute **portable executables** (**pexe**)
modules that the hosting environment (in other words, the Chrome browser) can This portability aligns Native Client with existing open web technologies such
translate to native code before executing. This portability aligns Native Client as JavaScript. You can distribute a pexe as part of an application (along with
with existing open web technologies such as JavaScript. A developer can HTML, CSS, and JavaScript), and the user's machine is simply able to run it.
distribute a **pexe** as part of an application (along with HTML, CSS, and
JavaScript), and the user's machine is simply able to run it. With PNaCl, you'll generate a single pexe, rather than multiple platform-
specific nexes. Since the pexe uses an abstract, architecture- and OS-
With PNaCl, a developer generates a single **pexe** from source code, independent format, it does not suffer from the portability problem described
rather than multiple platform-specific nexes. The **pexe** provides both above. Although, PNaCl can be more efficient on some operating systems than on
architecture- and OS-independence. Since the **pexe** uses an abstract, others. PNaCl boasts the same level of security as NaCl. Future versions of
architecture-independent format, it does not suffer from the portability hosting environments should have no problem executing the pexe, even on new
problem described above. Future versions of hosting environments should architectures. Moreover, if an existing architecture is enhanced, the pexe
have no problem executing the **pexe**, even on new architectures. doesn't need to be recompiled. In some cases the client-side translation will
Moreover, if an existing architecture is subsequently enhanced, the automatically take advantage of new capabilities. A pexe can be part of any web
**pexe** doesn't even have to be recompiled. In some cases the application. It does not have to be distributed through the Chrome Web Store. In
client-side translation will automatically be able to take advantage of short, PNaCl combines the portability of existing web technologies with the
the new capabilities. A **pexe** module can be part of any web performance and security benefits of Native Client.
application. It does not have to be distributed through the Chrome Web
Store. In short, PNaCl combines the portability of existing web technologies
with the performance and security benefits of Native Client.
PNaCl is a new technology, and as such it still has a few limitations PNaCl is a new technology, and as such it still has a few limitations
as compared to NaCl. These limitations are described below. as compared to NaCl. These limitations are described below.
.. _when-to-use-pnacl:
When to use PNaCl When to use PNaCl
================= =================
PNaCl is the preferred toolchain for Native Client, and the only way to deploy PNaCl is the preferred toolchain for Native Client, and the only way to deploy
Native Client modules on the open web. Unless your project is subject to one Native Client modules without the Google Web Store. Unless your project is
of the narrow limitations described below subject to one of the narrow limitations described under ":ref:`When to use
(see :ref:`When to use NaCl<when-to-use-nacl>`), you should use PNaCl. NaCl<when-to-use-nacl>`", you should use PNaCl.
Beginning with version 31, the Chrome browser supports translation of Since version 31, Chrome supports translation of pexe
**pexe** modules and their use in web applications, without requiring modules and their use in web applications without requiring installation either
any installation (either of a browser plugin or of the applications of a browser plug-in or of the applications themselves. Native Client and PNaCl
themselves). Native Client and PNaCl are open-source technologies, and are open-source technologies, and our hope is that they will be added to other
our hope is that they will be added to other hosting platforms in the hosting platforms in the future.
future.
If controlled distribution through the Chrome Web Store is an important part of
If controlled distribution through the Chrome Web Store is an important part your product plan, the benefits of PNaCl are less critical for you. But you can
of your product plan, the benefits of PNaCl are less critical for you. But still use the PNaCl toolchain and distribute your application through the Chrome
you can still use the PNaCl toolchain and distribute your application Web Store, and thereby take advantage of the conveniences of PNaCl, such as not
through the Chrome Web Store, and thereby take advantage of the having to explicitly compile your application for all supported architectures.
conveniences of PNaCl, such as not having to explicitly compile your application
for all supported architectures.
.. _when-to-use-nacl: .. _when-to-use-nacl:
When to use NaCl When to use NaCl
================ ================
The limitations below apply to the current release of PNaCl. If any of Use NaCl if any of the following apply to your application:
these limitations are critical for your application, you should use
non-portable NaCl: * Your application requires architecture-specific instructions such as, for
example, inline assembly. PNaCl tries to offer high-performance portable
* PNaCl does not support architecture-specific equivalents. One such example is PNaCl's :ref:`Portable SIMD Vectors
instructions in an application (i.e., inline assembly), but tries to <portable_simd_vectors>`.
offer high-performance portable equivalents. One such example is * Your application uses dynamic linking. PNaCl only supports static linking
PNaCl's :ref:`Portable SIMD Vectors <portable_simd_vectors>`. with a PNaCl port of the ``newlib`` C standard library. Dynamic linking and
* PNaCl only supports static linking with the ``newlib`` ``glibc`` are not yet supported in PNaCl. Work is under way to enable dynamic
C standard library (the Native Client SDK provides a PNaCl port of linking in future versions of PNaCl.
``newlib``). Dynamic linking and ``glibc`` are not yet supported. * Your application uses certain GNU extensions not supported by PNaCl's LLVM
Work is under way to enable dynamic linking in future versions of PNaCl. toolchain, like taking the address of a label for computed ``goto``, or nested
* PNaCl does not support some GNU extensions
like taking the address of a label for computed ``goto``, or nested
functions. functions.
native_client_sdk/src/doc/overview.rst
View file @ 3e1df835
...@@ -9,71 +9,94 @@ Technical Overview ...@@ -9,71 +9,94 @@ Technical Overview
:backlinks: none :backlinks: none
:depth: 2 :depth: 2
Introduction
============
**Native Client** (NaCl) is an open-source technology for running native **Native Client** (NaCl) is an open-source technology for running native
compiled code in the browser, with the goal of maintaining the portability compiled code in the browser, with the goal of maintaining the portability
and safety that users expect from web applications. Native Client expands web and safety that users expect from web applications. Native Client expands web
programming beyond JavaScript, enabling developers to enhance their web programming beyond JavaScript, enabling you to enhance your web applications
applications using their preferred language. This document describes some of using your preferred language. This document describes some of the key benefits
the key benefits and common use cases of Native Client. and common use cases of Native Client.
Google has implemented the open-source `Native Client project Google has implemented the open-source `Native Client project
<http://www.chromium.org/nativeclient>`_ in the Chrome browser on Windows, Mac, <http://www.chromium.org/nativeclient>`_ in the Chrome browser on Windows, Mac,
Linux, and Chrome OS. The :doc:`Native Client Software Development Kit (SDK) Linux, and Chrome OS. The :doc:`Native Client Software Development Kit (SDK)
<sdk/download>`, itself an open-source project, lets developers create web <sdk/download>`, itself an open-source project, lets you create web applications
applications that use NaCl and run in Chrome across multiple platforms. that use NaCl and run in Chrome across multiple platforms.
A Native Client web application consists of JavaScript, HTML, CSS, and a NaCl
module written in a language supported by the SDK. The NaCl SDK currently
supports C and C++; as compilers for additional languages are developed, the SDK
will be updated.
.. figure:: /images/web-app-with-nacl.png
:alt: A web application with and without Native Client
A web application with and without Native Client
A web application that uses Native Client generally consists of a combination of Native Client comes in two flavors: traditional (NaCl) and portable (PNaCl).
JavaScript, HTML, CSS, and a NaCl module that is written in a language supported Traditional, which must be distributed through the Chrome Web Store lets you
by the SDK. The NaCl SDK currently supports C and C++; as compilers for target a specific hardware platform. Portable can run on the open web. A
additional languages are developed, the SDK will be updated to support those bitcode file that can be loaded from any web server is downloaded to a client
languages as well. machine and converted to hardware-specific code before any execution. For
details, see :doc:`NaCl and PNaCl </nacl-and-pnacl>`.
.. image:: /images/web-app-with-nacl.png .. _why-use-native-client:
Why use Native Client? Why use Native Client?
====================== ======================
Native Client open-source technology is designed to run compiled code Native Client open-source technology is designed to run compiled code
securely inside a browser at near-native speeds. Native Client puts web securely inside a browser at near-native speeds. Native Client gives web
applications on the same playing field as desktop software---it provides the applications some advantages of desktop software. Specifically, it provides the
means to fully harness the client's computational resources for applications means to fully harness the client's computational resources for applications
such as 3D games, multimedia editors, CAD modeling, such as:
client-side data analytics, and interactive simulations.
Native Client also aims to give C and C++ (and eventually other languages) the - 3D games
same level of portability and safety that JavaScript provides on the web today. - multimedia editors
- CAD modeling
- client-side data analytics
- interactive simulations.
Native Client gives C and C++ (and other languages targeting it) the same level
of portability and safety as JavaScript.
Important benefits of Native Client include: .. _benefits-of-native-client:
Benefits of Native Client
=========================
Benefits of Native Client include:
* **Graphics, audio, and much more:** Running native code modules that render 2D * **Graphics, audio, and much more:** Running native code modules that render 2D
and 3D graphics, play audio, respond to mouse and keyboard events, run on and 3D graphics, play audio, respond to mouse and keyboard events, run on
multiple threads, and access memory directly---all without requiring multiple threads, and access memory directly---all without requiring the user
the user to install a plugin. to install a plug-in.
* **Portability:** Writing your applications once and running them on operating * **Portability:** Writing your applications once and running them on multiple
systems (Windows, Linux, Mac, and Chrome OS) and CPU architectures (x86 and operating systems (Windows, Linux, Mac, and Chrome OS) and CPU architectures
ARM). (x86 and ARM).
* **Easy migration path to the web:** Leveraging years of work in existing * **Easy migration path to the web:** Leveraging years of work in existing
desktop applications. Native Client makes the transition from the desktop to a desktop applications. Native Client makes the transition from the desktop to
web application significantly easier because it supports C and C++. a web application significantly easier because it supports C and C++.
* **Security:** Protecting the user's system from malicious or buggy * **Security:** Protecting the user's system from malicious or buggy
applications through Native Client's double sandbox model. This model offers applications through Native Client's double sandbox model. This model offers
the safety of traditional web applications without sacrificing performance and the safety of traditional web applications without sacrificing performance
without requiring users to install a plugin. and without requiring users to install a plug-in.
* **Performance:** Running at speeds comparable to desktop applications (within * **Performance:** Running at speeds within 5% to 15% of a native desktop
5-15% of native speed). Native Client also allows applications to harness all application. Native Client also allows applications to harness all available
available CPU cores via a threading API; this enables demanding applications CPU cores via a threading API. This enables demanding applications such as
such as console-quality games to run inside the browser. console-quality games to run inside the browser.
.. _common-use-cases:
Common use cases Common use cases
================ ================
Typical use cases for Native Client include the following: Typical use cases for Native Client include the following:
* **Existing software components:** With support for C and C++, Native * **Existing software components:** Native Client lets you repurpose existing
Client lets you to reuse existing software modules in web applications. You C and C++ software in web applications. You don't need to rewrite and debug
don't need to rewrite and debug code that already works. code that already works. It also lets your application take advantage of
things the browser does well such as handling user interaction and processing
events. You can also take advantage of the latest developments in HTML5.
* **Legacy desktop applications:** Native Client provides a smooth migration * **Legacy desktop applications:** Native Client provides a smooth migration
path from desktop applications to the web. You can port and recompile existing path from desktop applications to the web. You can port and recompile existing
code for the computation engine of your application directly to Native Client, code for the computation engine of your application directly to Native Client,
...@@ -81,9 +104,9 @@ Typical use cases for Native Client include the following: ...@@ -81,9 +104,9 @@ Typical use cases for Native Client include the following:
browser. browser.
* **Heavy computation in enterprise applications:** Native Client can handle the * **Heavy computation in enterprise applications:** Native Client can handle the
number crunching required by large-scale enterprise applications. To ensure number crunching required by large-scale enterprise applications. To ensure
protection of user data, Native Client enables you to build complex protection of user data, Native Client lets you run complex cryptographic
cryptographic algorithms directly into the browser so that unencrypted data algorithms directly in the browser so that unencrypted data never goes out
never goes out over the network. over the network.
* **Multimedia applications:** Codecs for processing sounds, images, and movies * **Multimedia applications:** Codecs for processing sounds, images, and movies
can be added to the browser in a Native Client module. can be added to the browser in a Native Client module.
* **Games:** Native Client lets web applications run at close to native * **Games:** Native Client lets web applications run at close to native
...@@ -93,8 +116,8 @@ Typical use cases for Native Client include the following: ...@@ -93,8 +116,8 @@ Typical use cases for Native Client include the following:
artificial intelligence module that powers a sophisticated web game. artificial intelligence module that powers a sophisticated web game.
Native Client also enables applications to run unchanged across Native Client also enables applications to run unchanged across
many platforms. many platforms.
* **Any application that requires acceleration**: Native Client fits seamlessly * **Any application that requires acceleration:** Native Client fits seamlessly
into web applications---it's up to you to decide to what extent to use it. into web applications. It's up to you to decide to what extent to use it.
Use of Native Client covers the full spectrum from complete applications to Use of Native Client covers the full spectrum from complete applications to
small optimized routines that accelerate vital parts of web applications. small optimized routines that accelerate vital parts of web applications.
...@@ -103,32 +126,51 @@ Typical use cases for Native Client include the following: ...@@ -103,32 +126,51 @@ Typical use cases for Native Client include the following:
How Native Client works How Native Client works
======================= =======================
Native Client is an umbrella name for a set of related software components that Native Client is an umbrella name for a set of related software components for
provide a way to develop C/C++ applications and run them securely on the web. developing C/C++ applications and running them securely on the web. At a high
level, Native Client consists of:
At a high level, Native Client consists of:
* **Toolchains**: Collections of development tools (compilers, linkers, etc.) * **Toolchains:** collections of development tools (compilers, linkers, etc.)
that transform C/C++ code to Native Client modules. that transform C/C++ code to Portable Native Client modules or Native Client
* **Runtime components**: components embedded in the browser or other modules.
host platforms that allow execution of Native Client modules * **Runtime components:** components embedded in the browser or other host
securely and efficiently. platforms that allow execution of Native Client modules securely and
efficiently.
The following diagram shows how these components interact: The following diagram shows how these components interact:
.. image:: /images/nacl-pnacl-component-diagram.png .. figure:: /images/nacl-pnacl-component-diagram.png
:alt: The Native Client toolchains and their outputs
The Native Client toolchains and their outputs
.. _toolchains:
Toolchains
----------
A Native Client toolchain consists of a compiler, a linker, an assembler and
other tools that are used to convert C/C++ source code into a module that is
loadable by a browser.
The Native Client SDK provides two toolchains:
The left side of the diagram shows how to use Portable Native Client * The left side of the diagram shows **Portable Native Client** (PNaCl,
(PNaCl, pronounced "pinnacle"). Developers use the PNaCl toolchain pronounced "pinnacle"). An LLVM based toolchain produces a single, portable
to produce a single, portable (**pexe**) module. At runtime, a translator (**pexe**) module. At runtime an ahead-of-time (AOT) translator, built into
built into the browser translates the pexe into native code for the the browser, translates the pexe into native code for the relevant client
relevant client architecture. Translation occurs before any code is executed. architecture.
The right side of the diagram shows how to use (non-portable) Native Client. * The right side of the diagram shows **(non-portable) Native Client**. A GCC
Developers use a nacl-gcc based toolchain to produce multiple based toolchain produces multiple architecture-dependent (**nexe**) modules,
architecture-dependent (**nexe**) modules, which are packaged into an which are packaged into an application. At runtime the browser determines
application. At runtime, the browser decides which nexe to load based which nexe to load based on the architecture of the client machine.
on the architecture of the client machine.
The PNaCl toolchain is recommended for most applications. The NaCl-GCC
toolchain should only be used for applications that won't be distributed on the
open web.
.. _security:
Security Security
-------- --------
...@@ -137,17 +179,19 @@ Since Native Client permits the execution of native code on client machines, ...@@ -137,17 +179,19 @@ Since Native Client permits the execution of native code on client machines,
special security measures have to be implemented: special security measures have to be implemented:
* The NaCl sandbox ensures that code accesses system resources only through * The NaCl sandbox ensures that code accesses system resources only through
safe, whitelisted APIs, and operates within its limits without attempting to safe, whitelisted APIs, and operates within its limits without attempting to
interfere with other code running either within the browser or outside it. interfere with other code running either within the browser or outside it.
* The NaCl validator statically analyzes code prior to running it * The NaCl validator statically analyzes code before running it to make sure it
to make sure it only uses code and data patterns that are permitted and safe. only uses code and data patterns that are permitted and safe.
The above security measures are in addition to the existing sandbox in the These security measures are in addition to the existing sandbox in the
Chrome browser---the Native Client module always executes in a process with Chrome browser. The Native Client module always executes in a process with
restricted permissions. The only interaction between this process and the restricted permissions. The only interaction between this process and the
outside world is through sanctioned browser interfaces. Because of the outside world is through defined browser interfaces. Because of the
combination of the NaCl sandbox and the Chrome sandbox, we say that combination of the NaCl sandbox and the Chrome sandbox, we say that
Native Client employs a double sandbox design. Native Client employs a **double sandbox** design.
.. _portability:
Portability Portability
----------- -----------
...@@ -160,76 +204,67 @@ applications<link_nacl_in_web_apps>`. ...@@ -160,76 +204,67 @@ applications<link_nacl_in_web_apps>`.
The PNaCl translator is a component embedded in the Chrome browser; its task is The PNaCl translator is a component embedded in the Chrome browser; its task is
to run pexe modules. Internally, the translator compiles a pexe to a nexe to run pexe modules. Internally, the translator compiles a pexe to a nexe
(a native executable for the client platform's architecture), and then executes (described above), and then executes the nexe within the Native Client sandbox
the nexe within the Native Client sandbox as described above. It also uses as described above. The translator uses intelligent caching to avoid
intelligent caching to avoid re-compiling the pexe if it was previously compiled re-compiling the pexe if it was previously compiled on the client's browser.
on the client's browser.
Native Client also supports the execution of nexe modules directly in the Native Client also supports the execution of nexe modules directly in the
browser. However, since nexes contain architecture-specific machine code, browser. However, since nexes contain architecture-specific machine code, they
they are not allowed to be distributed on the open web---they can only be are not allowed to be distributed on the open web. They can only be used as part
used as part of applications and extensions that are installed from the of applications and extensions that are installed from the Chrome Web Store.
Chrome Web Store.
For more details on the difference between NaCl and PNaCl, see For more details on the difference between NaCl and PNaCl, see
:doc:`NaCl and PNaCl <nacl-and-pnacl>`. :doc:`NaCl and PNaCl <nacl-and-pnacl>`.
.. _toolchains:
Toolchains
----------
A toolchain is a set of tools used to create an application from a set of
source files. In the case of Native Client, a toolchain consists of a compiler,
linker, assembler and other tools that are used to convert an
application written in C/C++ into a module that is loadable by the browser.
The Native Client SDK provides two toolchains:
* a **PNaCl toolchain** for generating portable NaCl modules (pexe files)
* a **gcc-based toolchain (nacl-gcc)** for generating non-portable NaCl modules
(nexe files)
The PNaCl toolchain is recommended for most applications. The nacl-gcc
toolchain should only be used for applications that will not be distributed
on the open web.
.. _link_nacl_in_web_apps: .. _link_nacl_in_web_apps:
Native Client in a web application Structure of a web application
================================== ==============================
.. _application_files: .. _application_files:
A Native Client application consists of a set of files: A Native Client application consists of a set of files:
* **HTML**, **CSS**, and **JavaScript** files, as in any modern web * **HTML and CSS:** The HTML file tells the browser where to find the manifest
application. The JavaScript code is responsible for communicating with the (nmf file) through the embed tag.
NaCl module.
* A **pexe** (portable NaCl) file. This module uses the :ref:`Pepper .. naclcode::
<link_pepper>` API, which provides the bridge to JavaScript and
browser resources. <embed name="mygame" src="mygame.nmf" type="application/x-pnacl" />
* A Native Client **manifest** file that specifies the pexe to load, along with
some loading options. This manifest file is embedded into the HTML page * **Manifest:** The manifest identifies the module to load and specifies
through an ``<embed>`` tag, as shown in the figure below. options. For example, "mygame.nmf" might look like this:
.. image:: /images/nacl-in-a-web-app.png .. naclcode::
{...
...
"url": "mygame.pexe",
}
* **pexe (portable NaCl file):** A compiled Native Client module. It uses the
:ref:`Pepper API <link_pepper>`, which provides a bridge to JavaScript and
other browser resources.
.. figure:: /images/nacl-in-a-web-app.png
:alt: Structure of a web application
Structure of a web application
For more details, see :doc:`Application Structure For more details, see :doc:`Application Structure
<devguide/coding/application-structure>`. <devguide/coding/application-structure>`.
.. _link_pepper: .. _link_pepper:
Pepper Plugin API Pepper plug-in API
----------------- ------------------
The Pepper Plugin API (PPAPI), called **Pepper** for convenience, is an The Pepper plug-in API (PPAPI), called **Pepper** for convenience, is an
open-source, cross-platform C/C++ API for web browser plugins. From the point open-source, cross-platform C/C++ API for web browser plug-ins. Pepper allows a
of view of Native Client, Pepper allows a C/C++ module to communicate with C/C++ module to communicate with the hosting browser and to access system-level
the hosting browser and get access to system-level functions in a safe and functions in a safe and portable way. One of the security constraints in Native
portable way. One of the security constraints in Native Client is that modules Client is that modules cannot make OS-level calls. Pepper provides analogous
cannot make any OS-level calls directly. Pepper provides analogous APIs that APIs that modules can use instead.
modules can target instead.
You can use the Pepper APIs to gain access to the full array of browser You can use the Pepper APIs to gain access to the full array of browser
capabilities, including: capabilities, including:
...@@ -240,9 +275,12 @@ capabilities, including: ...@@ -240,9 +275,12 @@ capabilities, including:
* :doc:`Playing audio <devguide/coding/audio>`. * :doc:`Playing audio <devguide/coding/audio>`.
* :doc:`Rendering 3D graphics <devguide/coding/3D-graphics>`. * :doc:`Rendering 3D graphics <devguide/coding/3D-graphics>`.
Pepper includes both a C API and a C++ API. The C++ API is a set of bindings Pepper includes both a :doc:`C API </c-api>` and a :doc:`C++ API </cpp-api>`.
written on top of the C API. For additional information about Pepper, see The C++ API is a set of bindings written on top of the C API. For additional
`Pepper Concepts <http://code.google.com/p/ppapi/wiki/Concepts>`_. information about Pepper, see `Pepper Concepts
<http://code.google.com/p/ppapi/wiki/Concepts>`_.
.. _versioning:
Versioning Versioning
========== ==========
...@@ -253,13 +291,15 @@ software, each release of Chrome may include changes to Native Client and the ...@@ -253,13 +291,15 @@ software, each release of Chrome may include changes to Native Client and the
Pepper interfaces that may require modification to existing applications. Pepper interfaces that may require modification to existing applications.
However, modules compiled for one version of Pepper/Chrome should work with However, modules compiled for one version of Pepper/Chrome should work with
subsequent versions of Pepper/Chrome. The SDK includes multiple versions of the subsequent versions of Pepper/Chrome. The SDK includes multiple versions of the
Pepper APIs to help developers make adjustments to API changes and take Pepper APIs to help you make adjustments to API changes and take
advantage of new features: `stable </native-client/pepper_stable>`_, `beta advantage of new features: `stable </native-client/pepper_stable>`_, `beta
</native-client/pepper_beta>`_ and `dev </native-client/pepper_dev>`_. </native-client/pepper_beta>`_ and `dev </native-client/pepper_dev>`_.
.. _where-to-start:
Where to start Where to start
============== ==============
The :doc:`Quick Start <quick-start>` document provides links to downloads and The :doc:`Quick Start <quick-start>` document provides links to downloads and
documentation that should help you get started with developing and distributing documentation to help you get started with developing and distributing Native
Native Client applications. Client applications.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment