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

native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/devcycle/vs-addin.html

Index: native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/devcycle/vs-addin.html
diff --git a/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/devcycle/vs-addin.html b/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/devcycle/vs-addin.html
new file mode 100644
index 0000000000000000000000000000000000000000..fb122c2b1ee376d1411838dc240b48ab6b1be009
--- /dev/null
+++ b/native_client_sdk/src/doc/_developer.chrome.com_generated/devguide/devcycle/vs-addin.html
@@ -0,0 +1,548 @@
+{{+bindTo:partials.standard_nacl_article}}
+
+<section id="debugging-with-visual-studio">
+<h1 id="debugging-with-visual-studio">Debugging With Visual Studio</h1>
+<div class="contents local topic" id="table-of-contents">
+<p class="topic-title first">Table Of Contents</p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><p class="first"><a class="reference internal" href="#platforms" id="id2">Platforms</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#the-ppapi-platform" id="id3">The PPAPI platform</a></li>
+<li><a class="reference internal" href="#the-native-client-platforms" id="id4">The Native Client platforms</a></li>
+</ul>
+</li>
+<li><p class="first"><a class="reference internal" href="#installing-the-add-in" id="id5">Installing the add-in</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#set-environment-variables" id="id6">Set environment variables</a></li>
+<li><a class="reference internal" href="#download-the-add-in" id="id7">Download the add-in</a></li>
+<li><a class="reference internal" href="#run-the-installer" id="id8">Run the installer</a></li>
+</ul>
+</li>
+<li><p class="first"><a class="reference internal" href="#try-the-hello-world-gles-sample-project" id="id9">Try the <code>hello_world_gles</code> sample project</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#select-the-nacl64-platform" id="id10">Select the NaCl64 platform</a></li>
+<li><a class="reference internal" href="#build-and-run-the-project" id="id11">Build and run the project</a></li>
+<li><a class="reference internal" href="#test-the-nacl-gdb-debugger" id="id12">Test the nacl-gdb debugger</a></li>
+<li><a class="reference internal" href="#test-the-visual-studio-debugger" id="id13">Test the Visual Studio debugger</a></li>
+<li><a class="reference internal" href="#inspect-the-platform-properties" id="id14">Inspect the platform properties</a></li>
+</ul>
+</li>
+<li><p class="first"><a class="reference internal" href="#developing-for-native-client-in-visual-studio" id="id15">Developing for Native Client in Visual Studio</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#adding-platforms-to-a-project" id="id16">Adding platforms to a project</a></li>
+<li><a class="reference internal" href="#selecting-a-toolchain" id="id17">Selecting a toolchain</a></li>
+<li><a class="reference internal" href="#adding-libraries-to-a-project" id="id18">Adding libraries to a project</a></li>
+<li><a class="reference internal" href="#running-a-web-server" id="id19">Running a web server</a></li>
+<li><a class="reference internal" href="#keeping-track-of-all-the-pieces" id="id20">Keeping track of all the pieces</a></li>
+<li><a class="reference internal" href="#using-the-debuggers" id="id21">Using the debuggers</a></li>
+<li><a class="reference internal" href="#disable-chrome-caching" id="id22">Disable Chrome caching</a></li>
+<li><a class="reference internal" href="#a-warning-about-postmessage" id="id23">A warning about PostMessage</a></li>
+<li><a class="reference internal" href="#porting-windows-applications-to-native-client-in-visual-studio" id="id24">Porting Windows applications to Native Client in Visual Studio</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<p>Whether you&#8217;re porting an existing project or starting from scratch, the Native
+Client Visual Studio add-in makes it easier to set up, build, run and debug
+your Native Client app by integrating the Native Client SDK development tools
+into the Visual Studio environment.</p>
+<aside class="note">
+The Native Client add-in requires Visual Studio 2010 with Service Pack 1. No
+other versions of Visual Studio are currently supported. Visual Studio
+Express is also not supported.
+</aside>
+<section id="introduction">
+<h2 id="introduction">Introduction</h2>
+<p>The Native Client add-in for Visual Studio helps you develop your application
+more efficiently in many ways:</p>
+<ul class="small-gap">
+<li>Organize and maintain your code as a Visual Studio project.</li>
+<li>Iteratively write and test your application more easily. Visual Studio
+handles the details of launching a web server to serve your module and run
+the module in Chrome with a debugger attached.</li>
+<li>Compile your module into a dynamically-linked library (DLL) using Visual
+Studio&#8217;s C/C++ compiler and run it as a Pepper plugin. This allows you to
+develop code incrementally, coding and/or porting one feature at a time into
+the Pepper APIs while continuing to use native Windows APIs that would
+otherwise be unavailable in an actual Native Client module.</li>
+<li>Use Visual Studio&#8217;s built-in debugger to debug your code while it’s running
+as a Pepper plugin.</li>
+<li>Compile your module into a .nexe or .pexe file using the Native Client SDK
+tools and run it as a bona fide Native Client module.</li>
+<li>Use the Native Client debugger, nacl-gdb, to test your code when it’s running
+as a Native Client object.</li>
+</ul>
+<p>The add-in defines five new Visual Studio platforms: <code>PPAPI</code>, <code>NaCl32</code>,
+<code>NaCl64</code>, <code>NaClARM</code>, and <code>PNaCl</code>. These platforms can be applied to the
+debug configuration of solutions and projects. The platforms configure the
+properties of your project so it can be built and run as either a Pepper plugin
+or a Native Client module. The platforms also define the behavior associated
+with the debug command so you can test your code while running in Visual
+Studio.</p>
+</section><section id="platforms">
+<h2 id="platforms">Platforms</h2>
+<p>It is helpful to consider the Visual Studio add-in platforms in two groups. One
+contains the PPAPI platform only. The other group, which we&#8217;ll call the Native
+Client platforms, contains platforms that all have &#8220;NaCl&#8221; in their names:
+<code>NaCl32</code>, <code>NaCl64</code>, <code>NaClARM</code>, and <code>PNaCl</code>. The diagram below shows the
+platforms, the ways they are normally used, and the build products they produce.</p>
+<img alt="/native-client/images/visualstudio4.png" src="/native-client/images/visualstudio4.png" />
+<p>Using platforms, your workflow is faster and more efficient. You can compile,
+start, and debug your code with one click or key-press. When you press F5, the
+“start debugging” command, Visual Studio automatically launches a web server to
+serve your module (if necessary) along with an instance of Chrome that runs
+your Native Client module, and also attaches an appropriate debugger.</p>
+<p>You can switch between platforms as you work to compare the behavior of your
+code.</p>
+<p>When you run your project, Visual Studio launches the PPAPI and Native Client
+platforms in different ways, as explained in the next sections.</p>
+<section id="the-ppapi-platform">
+<h3 id="the-ppapi-platform">The PPAPI platform</h3>
+<p>The PPAPI platform builds your module as a dynamic library and launches a
+version of Chrome that’s configured to run the library as a plugin when it
+encounters an <code>&lt;embed&gt;</code> element with <code>type=application/x-nacl</code> (ignoring
+the information in the manifest file). When running in the PPAPI platform, you
+can use Windows system calls that are unavailable in a regular Native Client
+module built and running as a .nexe file. This offers the ability to port
+existing code incrementally, rewriting functions using the PPAPI interfaces one
+piece at a time. Since the module is built with Visual Studio’s native compiler
+(MSBuild) you can use the Visual Studio debugger to control and inspect your
+code.</p>
+</section><section id="the-native-client-platforms">
+<h3 id="the-native-client-platforms">The Native Client platforms</h3>
+<p>There are four Native Client platforms. All of them can be used to build Native
+Client modules. When you run one of the Native Client platforms Visual Studio
+builds the corresponding type of Native Client module (either a .nexe or
+.pexe), starts a web server to serve it up, and launches a copy of Chrome that
+fetches the module from the server and runs it. Visual Studio will also open a
+terminal window, launch an instance of nacl-gdb, and attach it to your module&#8217;s
+process so you can use gdb commands to debug.</p>
+<section id="nacl32-and-nacl64">
+<h4 id="nacl32-and-nacl64">NaCl32 and NaCl64</h4>
+<p>The platforms named NaCl32 and NaCl64 are targeted at x86 32-bit and 64-bit
+systems respectively. You need both platforms to build a full set of .nexe
+files when you are ready to distribute your application. Note, however, that
+when you are testing in Visual Studio you must select the NaCl64 platform
+(because Chrome for Windows runs Native Client in a 64-bit process). If you try
+to run from the NaCl32 platform you will get an error message.</p>
+</section><section id="naclarm">
+<h4 id="naclarm">NaClARM</h4>
+<p>The NaClARM platform is targeted at ARM-based processors. You can build .nexe
+files with the NaClARM platform in Visual Studio but you cannot run them from
+there. You can use Visual Studio to create a Native Client module that includes
+an ARM-based .nexe file and then run the module from a Chrome browser on an ARM
+device, such as one of the newer Chromebook computers. See the instructions at
+<a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>Running Native Client Applications</em></a> for more information on
+testing your module in Chrome.</p>
+<aside class="note">
+Note: The NaClARM platform currently supports the newlib toolchain only.
+</aside>
+</section><section id="pnacl">
+<h4 id="pnacl">PNaCl</h4>
+<p>The PNaCl (portable NaCl) platform is included in the Visual Studio Native
+Client add-in versions 1.1 and higher. It supports the .pexe file format. A
+.pexe file encodes your application as bitcode for a low level virtual machine
+(LLVM). When you deliver a Native Client application as a PNaCl module, the
+manifest file will contain a single .pexe file rather than multiple .nexe
+files. The Chrome client transforms the LLVM bitcode into machine instructions
+for the local system.</p>
+<p>When you run the PNaCl platform from Visual Studio, Visual Studio uses the
+Native Client SDK to transform the .pexe file into a NaCl64 .nexe file and runs
+it as if you were working with a NaCl64 platform.</p>
+<aside class="note">
+Note: The PNaCl platform currently supports the newlib toolchain only.
+</aside>
+</section></section></section><section id="installing-the-add-in">
+<h2 id="installing-the-add-in">Installing the add-in</h2>
+<p>In order to use the Native Client Visual Studio add-in, your development
+environment should include:</p>
+<ul class="small-gap">
+<li>A 64-bit version of Windows Vista or Windows 7.</li>
+<li>Visual Studio 2010 with Service Pack 1.</li>
+<li><a class="reference external" href="https://www.google.com/intl/en/chrome/browser/">Chrome</a> version 23 or
+greater. You can choose to develop using the latest <a class="reference external" href="https://www.google.com/intl/en/chrome/browser/canary.html">canary</a> build of
+Chrome, running the canary version side-by-side with (and separately from)
+your regular version of Chrome.</li>
+<li><a class="reference internal" href="/native-client/sdk/download.html"><em>The Native Client SDK</em></a> with the <code>pepper_23</code>
+bundle or greater. The version of Chrome that you use must be equal or
+greater than the version of the SDK bundle.</li>
+</ul>
+<section id="set-environment-variables">
+<h3 id="set-environment-variables">Set environment variables</h3>
+<p>Before you run the installer you must define two Windows environment variables.
+They point to the bundle in the Native Client SDK that you use to build your
+module, and to the Chrome browser that you choose to use for debugging.</p>
+<p>To set environment variables in Windows 7, go to the Start menu and search for
+&#8220;environment.&#8221; One of the links in the results is &#8220;Edit environment variables
+for your account.&#8221; (You can also reach this link from the <code>Control Panel</code>
+under <code>User Accounts</code>.) Click on the link and use the buttons in the window
+to create or change these user variables (the values shown below are only for
+example):</p>
+<table border="1" class="docutils">
+<colgroup>
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Variable Name</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>NACL_SDK_ROOT</td>
+<td>The path to the pepper directory in the SDK. Example:
+<code>C:\nacl_sdk\pepper_23</code></td>
+</tr>
+<tr class="row-odd"><td>CHROME_PATH</td>
+<td>The path to the .exe file for the version of Chrome you are
+testing with. Example:
+<code>C:\Users\fred\AppData\Local\Google\Chrome
+SxS\Application\chrome.exe</code></td>
+</tr>
+</tbody>
+</table>
+</section><section id="download-the-add-in">
+<h3 id="download-the-add-in">Download the add-in</h3>
+<p>The Native Client Visual Studio add-in is a separate bundle in the SDK named
+<code>vs_addin</code>. Open a command prompt window, go to the top-level SDK directory,
+and run the update command, specifying the add-in bundle:</p>
+<pre class="prettyprint">
+naclsdk update vs_addin
+</pre>
+<p>This creates a folder named <code>vs_addin</code>, containing the add-in itself, its
+installer files, and a directory of examples.</p>
+<aside class="note">
+Note: The vs_addin bundle is only visible when you run <code>naclsdk</code> on a
+Windows system.
+</aside>
+</section><section id="run-the-installer">
+<h3 id="run-the-installer">Run the installer</h3>
+<p>The installer script is located inside the <code>vs_addin</code> folder in the SDK.
+Right click on the file <code>install.bat</code> and run it as administrator.</p>
+<p>The script always installs the NativeClient platforms, and asks you if you’d
+like to install the PPAPI platform as well. You can skip the PPAPI step and run
+the installer again later to add the PPAPI platform.</p>
+<p>You can usually run the installer successfully with no arguments. The new
+platforms are installed in <code>C:\Program Files
+(x86)\MSBuild\Microsoft.Cpp\v4.0\Platforms</code>.</p>
+<p>In some cases system resources may not be in their default locations. You might
+need to use these command line arguments when you run <code>install.bat</code>:</p>
+<ul class="small-gap">
+<li>The MSBuild folder is assumed to be at <code>C:\Program Files (x86)\MSBuild</code>.
+You can specify an alternate path with the flag <code>--ms-build-path=&lt;path&gt;</code>.
+The installer assumes Visual Studio has created a user folder at</li>
+<li><code>%USERPROFILE%\My Documents\Visual Studio 2010</code>. You can specify an
+alternate path with the flag <code>--vsuser-path=path</code>.</li>
+</ul>
+<p>From time to time an update to the Visual Studio add-in may become available.
+Updates are performed just like an installation. Download the new add-in using
+naclsdk update and run <code>install.bat</code> as administrator.</p>
+<p>To uninstall the add-in, run <code>install.bat</code> as administrator and add the
+<code>--uninstall</code> flag. You&#8217;ll need to run the Command Prompt program as
+administrator in order to add the flag. Go the to the Windows start menu,
+search for &#8220;Command Prompt,&#8221; right click on the program and run it as
+administrator.</p>
+<p>You can verify that the add-in has been installed and determine its version by
+selecting Add-in Manager in the Visual Studio Tools menu. If the add-in has
+been installed it will appear in the list of available add-ins. Select it and
+read its description.</p>
+</section></section><section id="try-the-hello-world-gles-sample-project">
+<h2 id="try-the-hello-world-gles-sample-project">Try the <code>hello_world_gles</code> sample project</h2>
+<p>The add-in comes with an examples directory. Open the sample project
+<code>examples\hello_world_gles\hello_world_gles.sln</code>. This project is an
+application that displays a spinning cube.</p>
+<section id="select-the-nacl64-platform">
+<h3 id="select-the-nacl64-platform">Select the NaCl64 platform</h3>
+<p>Open the sample project in Visual Studio, select the <code>Configuration Manager</code>,
+and confirm that the active solution configuration is <code>Debug</code> and the active
+project platform is <code>NaCl64</code>. Note that the platform for the
+<code>hello_world_gles</code> project is also <code>NaCl64</code>. (You can get to the
+<code>Configuration Manager</code> from the <code>Build</code> menu or the project’s
+<code>Properties</code> window.)</p>
+<img alt="/native-client/images/visualstudio1.png" src="/native-client/images/visualstudio1.png" />
+</section><section id="build-and-run-the-project">
+<h3 id="build-and-run-the-project">Build and run the project</h3>
+<p>Use the debugging command (F5) to build and run the project. As the wheels
+start to turn, you may be presented with one or more alerts. They are benign;
+you can accept them and set options to ignore them when that’s possible. Some
+of the messages you might see include:</p>
+<ul class="small-gap">
+<li>&#8220;This project is out of date, would you like to build it?&#8221;</li>
+<li>&#8220;Please specify the name of the executable file to be used for the debug
+session.&#8221; This should be the value of the environment variable CHROME_PATH,
+which is usually supplied as the default value in the dialog.</li>
+<li>&#8220;Debugging information for chrome.exe cannot be found.&#8221; This is to be
+expected, you are debugging your module&#8217;s code, not Chrome.</li>
+<li>&#8220;Open file - security warning. The publisher could not be verified.&#8221; If
+Visual Studio is complaining about x86_64-nacl-gdb.exe, that’s our debugger.
+Let it be.</li>
+</ul>
+<p>Once you’ve passed these hurdles, the application starts to run and you’ll see
+activity in three places:</p>
+<ol class="arabic simple">
+<li>A terminal window opens running <code>nacl-gdb</code>.</li>
+<li>Chrome launches running your module in a tab.</li>
+<li>The Visual Studio output window displays debugging messages when you select
+the debug output item.
+Stop the debugging session by closing the Chrome window, or select the stop
+debugging command from the debug menu. The nacl-gdb window will close when
+you stop running the program.</li>
+</ol>
+</section><section id="test-the-nacl-gdb-debugger">
+<h3 id="test-the-nacl-gdb-debugger">Test the nacl-gdb debugger</h3>
+<p>Add a breakpoint at the SwapBuffers call in the function MainLoop, which is in
+hello_world.cc.</p>
+<img alt="/native-client/images/visualstudio2.png" src="/native-client/images/visualstudio2.png" />
+<p>Start the debugger again (F5). This time the existing breakpoint is loaded into
+nacl-gcb and the program will pause there. Type c to continue running. You can
+use gdb commands to set more breakpoints and step through the application. For
+details, see <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html#using-gdb"><em>Debugging with nacl-gdb</em></a> (scroll down to the end
+of the section to see some commonly used gdb commands).</p>
+</section><section id="test-the-visual-studio-debugger">
+<h3 id="test-the-visual-studio-debugger">Test the Visual Studio debugger</h3>
+<p>If you’ve installed the <code>PPAPI</code> platform, go back to the <code>Configuration
+Manager</code> and select the <code>PPAPI</code> platform. This time when Chrome launches the
+<code>nacl-gdb</code> window will not appear; the Visual Studio debugger is fully
+engaged and on the job.</p>
+</section><section id="inspect-the-platform-properties">
+<h3 id="inspect-the-platform-properties">Inspect the platform properties</h3>
+<p>At this point, it may be helpful to take a look at the properties that are
+associated with the PPAPI and Native Client platforms&#8212;see the settings in the
+sample project as an example.</p>
+</section></section><section id="developing-for-native-client-in-visual-studio">
+<h2 id="developing-for-native-client-in-visual-studio">Developing for Native Client in Visual Studio</h2>
+<p>After you’ve installed the add-in and tried the sample project, you’re ready to
+start working with your own code. You can reuse the sample project and the
+PPAPI and Native Client platforms it already has by replacing the source code
+with your own. More likely, you will add the platforms to an existing project,
+or to a new project that you create from scratch.</p>
+<section id="adding-platforms-to-a-project">
+<h3 id="adding-platforms-to-a-project">Adding platforms to a project</h3>
+<p>Follow these steps to add the Native Client and PPAPI platforms to a project:</p>
+<ol class="arabic simple">
+<li>Open the Configuration Manager.</li>
+<li>On the row corresponding to your project, click the Platform column dropdown
+menu and select <code>&lt;New...&gt;</code>.</li>
+<li>Select <code>PPAPI</code>, <code>NaCl32</code>, <code>NaCl64</code>, or <code>PNaCl</code> from the New platform
+menu.</li>
+<li>In most cases, you should select <code>&lt;Empty&gt;</code> in the “Copy settings from”
+menu.  <strong>Never copy settings between ``PPAPI``, ``NaCl32``, ``NaCl64``,
+``NaClARM``, or ``PNaCl`` platforms</strong>. You can copy settings from a Win32
+platform, if one exists, but afterwards be sure that the project properties
+are properly set for the new platform, as mentioned in step 6 below.</li>
+<li>If you like, check the “Create new solutions platform” box to create a
+solution platform in addition to a project platform. (This is optional, but
+it can be convenient since it lets you switch project platforms from the
+Visual Studio main window by selecting the solution platform that has the
+same name.)</li>
+<li>Review the project properties for the new platform you just added. In most
+cases, the default properties for each platform should be correct, but it
+pays to check. Be especially careful about custom properties you may have
+set beforehand, or copied from a Win32 platform. Also confirm that the
+Configuration type is correct:<ul class="small-gap">
+<li><code>Dynamic Library</code> for <code>PPAPI</code></li>
+<li><code>Application (.pexe)</code> for <code>PNaCl</code></li>
+<li><code>Application (.nexe)</code> for <code>NaCl32</code>, <code>NaCl64</code>, and <code>NaClARM</code></li>
+</ul>
+</li>
+</ol>
+</section><section id="selecting-a-toolchain">
+<h3 id="selecting-a-toolchain">Selecting a toolchain</h3>
+<p>When you build a Native Client module directly from the SDK you can use two
+different toolchains, newlib or glibc. See <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loading.html"><em>Dynamic Linking and Loading
+with glibc</em></a> for a description of the two toolchains and
+instructions on how to build and deploy an application with the glibc
+toolchain. The Native Client platforms offer you the same toolchain choice. You
+can specify which toolchain to use in the project properties, under
+<code>Configuration Properties &gt; General &gt; Native Client &gt; Toolchain</code>.</p>
+<aside class="note">
+Currently, the NaClARM and PNaCl platforms only support the newlib toolchain.
+</aside>
+<p>There is no toolchain property for the PPAPI platform. The PPAPI platform uses
+the toolchain and libraries that come with Visual Studio.</p>
+</section><section id="adding-libraries-to-a-project">
+<h3 id="adding-libraries-to-a-project">Adding libraries to a project</h3>
+<p>If your Native Client application requires libraries that are not included in
+the SDK you must add them to the project properties (under <code>Configuration
+Properties &gt; Linker &gt; Input &gt; Additional Dependencies</code>), just like any other
+Visual Studio project. This list of dependencies is a semi-colon delimited
+list. On the PPAPI platform the library names include the .lib extension (e.g.,
+<code>ppapi_cpp.lib;ppapi.lib</code>). On the Native Client platforms the extension is
+excluded (e.g., <code>ppapi_cpp;ppapi</code>).</p>
+</section><section id="running-a-web-server">
+<h3 id="running-a-web-server">Running a web server</h3>
+<p>In order for the Visual Studio add-in to test your Native Client module, you
+must serve the module from a web server. There are two options:</p>
+<section id="running-your-own-server">
+<h4 id="running-your-own-server">Running your own server</h4>
+<p>When you start a debug run Visual Studio launches Chrome and tries to connect
+to the web server at the address found in the Chrome command arguments (see the
+project’s Debugging &gt; Command configuration property), which is usually
+<code>localhost:$(NaClWebServerPort)</code>. If you are using your own server be sure to
+specify its address in the command arguments property, and confirm that your
+server is running before starting a debug session. Also be certain that the
+server has all the files it needs to deliver a Native Client module (see
+“Keeping track of all the pieces”, below).</p>
+</section><section id="running-the-sdk-server">
+<h4 id="running-the-sdk-server">Running the SDK server</h4>
+<p>If there is no web server running at the specified port, Visual Studio will try
+to launch the simple Python web server that comes with the Native Client SDK.
+It looks for a copy of the server in the SDK itself (at
+<code>%NACL_SDK_ROOT%\tools\httpd.py</code>), and in the project directory
+(<code>$(ProjectDir)/httpd.py</code>). If the server exists in one of those locations,
+Visual Studio launches the server. The server output appears in Visual Studio’s
+Output window, in the pane named “Native Client Web Server Output”. A server
+launched in this way is terminated when the debugging session ends.</p>
+</section></section><section id="keeping-track-of-all-the-pieces">
+<h3 id="keeping-track-of-all-the-pieces">Keeping track of all the pieces</h3>
+<p>No matter where the web server lives or how it’s launched you must make sure
+that it has all the files that your application needs:</p>
+<ul class="small-gap">
+<li>All Native Client applications must have an <a class="reference internal" href="/native-client/devguide/coding/application-structure.html#html-file"><em>html host page</em></a>. This file is typically called <code>index.html</code>. The host page
+must have an embed tag with its type attribute set to
+<code>application-type/x-nacl</code>. If you plan to use a Native Client platform the
+embed tag must also include a src attribute pointing to a Native Client
+manifest (.mnf) file.</li>
+<li>If you are using a Native Client platform you must include a valid
+<a class="reference internal" href="/native-client/devguide/coding/application-structure.html#manifest-file"><em>manifest file</em></a>. The manifest file points to the .pexe
+or .nexe files that Visual Studio builds. These will be placed in the
+directory specified in the project’s <code>General &gt; Output Directory</code>
+configuration property, which is usually <code>$(ProjectDir)$(ToolchainName)</code>.
+Visual Studio can use the Native Client SDK script create_nmf.py to
+automatically generate the manifest file for you.  To use this script set the
+project&#8217;s <code>Linker &gt; General &gt; Create NMF Automatically</code> property to &#8220;yes.&#8221;</li>
+</ul>
+<p>If you are letting Visual Studio discover and run the SDK server, these files
+should be placed in the project directory. If you are running your own server,
+you must be sure that the host page <code>index.html</code> is placed in your server’s
+root directory. Remember, if you’re using one of the Native Client platforms
+the paths for the manifest file and .pexe or .nexe files must be reachable from
+the server.</p>
+<p>The structure of the manifest file can be more complicated if your application
+uses Native Client&#8217;s ability to dynamically link libraries. You may have to add
+additional information about dynamically linked libraries to the manifest file
+even if you create it automatically. The use and limitations of the create_nmf
+tool are explained in <a class="reference internal" href="/native-client/devguide/devcycle/dynamic-loading.html#dynamic-loading-manifest"><em>Generating a Native Client manifest file for a
+dynamically linked application</em></a>.</p>
+<p>You can look at the example projects in the SDK to see how the index and
+manifest files are organized. The example project <code>hello_nacl</code> has a
+subdirectory also called <code>hello_nacl</code>. That folder contains <code>index.html</code>
+and <code>hello_nacl.nmf</code>. The nexe file is found in
+<code>NaCl64\newlib\Debug\hello_nacl_64.nexe</code>. The <code>hello_world_gles</code> example
+project contains a subdirectory called <cite>hello_world_gles`</cite>. That directory
+contains html files built with both toolchains (<code>index_glibc.html</code> and
+<code>index_newlib.html</code>). The .nexe and .nmf files are found in the newlib and
+glibc subfolders. For additional information about the parts of a Native Client
+application, see <a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>Application Structure</em></a>.</p>
+</section><section id="using-the-debuggers">
+<h3 id="using-the-debuggers">Using the debuggers</h3>
+<p>PPAPI plugins are built natively by Visual Studio’s compiler (MSBuild), and
+work with Visual Studio’s debugger in the usual way. You can set breakpoints in
+the Visual Studio source code files before you begin debugging, and on-the-fly
+while running the program.</p>
+<p>NaCl32 and NaClARM executables (.nexe files) cannot be run or debugged from
+Visual Studio.</p>
+<p>NaCl64 executables (.nexe files) are compiled using one of the Native Client
+toolchains in the SDK, which create an <a class="reference external" href="`http://en.wikipedia.org/wiki/Executable_and_Linkable_Format">ELF-formatted</a> executable. To
+debug a running .nexe you must use nacl-gdb, which is a command line debugger
+that is not directly integrated with Visual Studio. When you start a debugging
+session running from a NaCl64 platform, Visual Studio automatically launches
+nacl-gdb for you and attaches it to the nexe. Breakpoints that you set in
+Visual Studio before you start debugging are transferred to nacl-gdb
+automatically. During a NaCl debugging session you can only use nacl-gdb
+commands.</p>
+<p>The PNaCl platform generates a .pexe file. When you run the debugger add-in
+translates the .pexe file to a .nexe file and runs the resulting binary with
+nacl-gdb attached.</p>
+<p>For additional information about nacl-gdb, see <a class="reference internal" href="/native-client/devguide/devcycle/debugging.html#using-gdb"><em>Debugging with nacl-gdb</em></a> (scroll down to the end of the section to see some commonly used
+gdb commands).</p>
+<p>Note that you can’t use the Start Without Debugging command (Ctrl+F5) with a
+project in the Debug configuration. If you do, Chrome will hang because the
+Debug platform launches Chrome with the command argument
+<code>--wait-for-debugger-children</code> (in PPAPI) or <code>--enable-nacl-debug</code> (in a
+Native Client platform). These flags cause Chrome to pause and wait for a
+debugger to attach. If you use the Start Without Debugging command, no debugger
+attaches and Chrome just waits patiently. To use Start Without Debugging,
+switch to the Release configuration, or manually remove the offending argument
+from the <code>Command Arguments</code> property.</p>
+</section><section id="disable-chrome-caching">
+<h3 id="disable-chrome-caching">Disable Chrome caching</h3>
+<p>When you debug with a Native Client platform you might want to <a class="reference internal" href="/native-client/devguide/devcycle/running.html#cache"><em>disable
+Chrome&#8217;s cache</em></a> to be sure you are testing your latest and greatest
+code.</p>
+</section><section id="a-warning-about-postmessage">
+<h3 id="a-warning-about-postmessage">A warning about PostMessage</h3>
+<p>Some Windows libraries define the symbol <code>PostMessage</code> as <code>PostMessageW</code>.
+This can cause havoc if you are working with the PPAPI platform and you use the
+Pepper <code>PostMessage()</code> call in your module. Some Pepper API header files
+contain a self-defensive fix that you might need yourself, while you are
+testing on the PPAPI platform. Here it is:</p>
+<pre class="prettyprint">
+// If Windows defines PostMessage, undef it.
+#ifdef PostMessage
+#undef PostMessage
+#endif
+</pre>
+</section><section id="porting-windows-applications-to-native-client-in-visual-studio">
+<h3 id="porting-windows-applications-to-native-client-in-visual-studio">Porting Windows applications to Native Client in Visual Studio</h3>
+<p>At Google I/O 2012 we demonstrated how to port a Windows desktop application to
+Native Client in 60 minutes. The <a class="reference external" href="http://www.youtube.com/watch?v=1zvhs5FR0X8&amp;feature=plcp">video</a> is available to
+watch on YouTube. The <code>vs_addin/examples</code> folder contains a pair of simple
+examples that demonstrate porting process.  They are designed to be completed
+in just 5 minutes. The two examples are called <code>hello_nacl</code> and
+<code>hello_nacl_cpp</code>. They are essentially the same, but the former uses the C
+PPAPI interface while the latter uses the C++ API.  The application is the
+familiar &#8220;Hello, World.&#8221;</p>
+<p>Each example begins with the Windows desktop version running in the <code>Win32</code>
+platform. From there you move to the <code>PPAPI</code> platform, where you perform a
+series of steps to set up the Native Client framework, use it to run the
+desktop version, and then port the behavior from Windows calls to the PPAPI
+interface.  You wind up with a program that uses no Windows functions, which
+can run in either the <code>PPAPI</code> or the <code>NaCl64</code> platform.</p>
+<p>The example projects use a single source file (<code>hello_nacl.c</code> or
+<code>hello_nacl_cpp.cpp</code>). Each step in the porting process is accomplished by
+progressively defining the symbols STEP1 through STEP6 in the source. Inline
+comments explain how each successive step changes the code. View the example
+code to see how it&#8217;s actually done. Here is a summary of the process:</p>
+<section id="win32-platform">
+<h4 id="win32-platform">Win32 Platform</h4>
+<dl class="docutils">
+<dt>STEP1 Run the desktop application</dt>
+<dd>Begin by running the original Windows application in the Win32 platform.</dd>
+</dl>
+</section><section id="ppapi-platform">
+<h4 id="ppapi-platform">PPAPI Platform</h4>
+<dl class="docutils">
+<dt>STEP2 Launch Chrome with an empty Native Client module</dt>
+<dd>Switch to the PPAPI platform and include the code required to initialize a
+Native Module instance. The code is bare-boned, it does nothing but
+initialize the module. This step illustrates how Visual Studio handles all
+the details of launching a web-server and Chrome, and running the Native
+Client module as a Pepper plugin.</dd>
+<dt>STEP3 Run the desktop application synchronously from the Native Client module</dt>
+<dd>The Native Client creates the window directly and then calls WndProc to run
+the desktop application. Since WndProc spins in its message loop, the call to
+initialize the module never returns. Close the Hello World window and the
+module initialization will finish.</dd>
+<dt>STEP4 Running the desktop application and Native Client asynchronously</dt>
+<dd>In WndProc replace the message loop with a callback function. Now the app
+window and the Native Client module are running concurrently.</dd>
+<dt>STEP5 Redirect output to the web page</dt>
+<dd>The module initialization code calls initInstanceInBrowserWindow rather than
+initInstanceInPCWindow. WndProc is no longer used. Instead, postMessage is
+called to place text (now &#8220;Hello, Native Client&#8221;) in the web page rather than
+opening and writing to a window. Once you&#8217;ve reached this step you can start
+porting pieces of the application one feature at a time.</dd>
+<dt>STEP6 Remove all the Windows code</dt>
+<dd>All the Windows code is def&#8217;d out, proving we are PPAPI-compliant. The
+functional code that is running is the same as STEP5.</dd>
+</dl>
+</section><section id="nacl64-platform">
+<h4 id="nacl64-platform">NaCl64 Platform</h4>
+<dl class="docutils">
+<dt>Run the Native Client Module in the NaCl64 platform</dt>
+<dd>You are still running the STEP6 code, but as a Native Client module rather
+than a Pepper plugin.</dd>
+</dl>
+</section></section></section></section>
+
+{{/partials.standard_nacl_article}}