| OLD | NEW |
|---|
| (Empty) | |
| 1 {{+bindTo:partials.standard_nacl_article}} |
| 2 |
| 3 <section id="debugging-with-visual-studio"> |
| 4 <h1 id="debugging-with-visual-studio">Debugging With Visual Studio</h1> |
| 5 <div class="contents local topic" id="table-of-contents"> |
| 6 <p class="topic-title first">Table Of Contents</p> |
| 7 <ul class="small-gap"> |
| 8 <li><a class="reference internal" href="#introduction" id="id1">Introduction</a>
</li> |
| 9 <li><p class="first"><a class="reference internal" href="#platforms" id="id2">Pl
atforms</a></p> |
| 10 <ul class="small-gap"> |
| 11 <li><a class="reference internal" href="#the-ppapi-platform" id="id3">The PPAPI
platform</a></li> |
| 12 <li><a class="reference internal" href="#the-native-client-platforms" id="id4">T
he Native Client platforms</a></li> |
| 13 </ul> |
| 14 </li> |
| 15 <li><p class="first"><a class="reference internal" href="#installing-the-add-in"
id="id5">Installing the add-in</a></p> |
| 16 <ul class="small-gap"> |
| 17 <li><a class="reference internal" href="#set-environment-variables" id="id6">Set
environment variables</a></li> |
| 18 <li><a class="reference internal" href="#download-the-add-in" id="id7">Download
the add-in</a></li> |
| 19 <li><a class="reference internal" href="#run-the-installer" id="id8">Run the ins
taller</a></li> |
| 20 </ul> |
| 21 </li> |
| 22 <li><p class="first"><a class="reference internal" href="#try-the-hello-world-gl
es-sample-project" id="id9">Try the <code>hello_world_gles</code> sample project
</a></p> |
| 23 <ul class="small-gap"> |
| 24 <li><a class="reference internal" href="#select-the-nacl64-platform" id="id10">S
elect the NaCl64 platform</a></li> |
| 25 <li><a class="reference internal" href="#build-and-run-the-project" id="id11">Bu
ild and run the project</a></li> |
| 26 <li><a class="reference internal" href="#test-the-nacl-gdb-debugger" id="id12">T
est the nacl-gdb debugger</a></li> |
| 27 <li><a class="reference internal" href="#test-the-visual-studio-debugger" id="id
13">Test the Visual Studio debugger</a></li> |
| 28 <li><a class="reference internal" href="#inspect-the-platform-properties" id="id
14">Inspect the platform properties</a></li> |
| 29 </ul> |
| 30 </li> |
| 31 <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> |
| 32 <ul class="small-gap"> |
| 33 <li><a class="reference internal" href="#adding-platforms-to-a-project" id="id16
">Adding platforms to a project</a></li> |
| 34 <li><a class="reference internal" href="#selecting-a-toolchain" id="id17">Select
ing a toolchain</a></li> |
| 35 <li><a class="reference internal" href="#adding-libraries-to-a-project" id="id18
">Adding libraries to a project</a></li> |
| 36 <li><a class="reference internal" href="#running-a-web-server" id="id19">Running
a web server</a></li> |
| 37 <li><a class="reference internal" href="#keeping-track-of-all-the-pieces" id="id
20">Keeping track of all the pieces</a></li> |
| 38 <li><a class="reference internal" href="#using-the-debuggers" id="id21">Using th
e debuggers</a></li> |
| 39 <li><a class="reference internal" href="#disable-chrome-caching" id="id22">Disab
le Chrome caching</a></li> |
| 40 <li><a class="reference internal" href="#a-warning-about-postmessage" id="id23">
A warning about PostMessage</a></li> |
| 41 <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> |
| 42 </ul> |
| 43 </li> |
| 44 </ul> |
| 45 </div> |
| 46 <p>Whether you’re porting an existing project or starting from scratch, th
e Native |
| 47 Client Visual Studio add-in makes it easier to set up, build, run and debug |
| 48 your Native Client app by integrating the Native Client SDK development tools |
| 49 into the Visual Studio environment.</p> |
| 50 <aside class="note"> |
| 51 The Native Client add-in requires Visual Studio 2010 with Service Pack 1. No |
| 52 other versions of Visual Studio are currently supported. Visual Studio |
| 53 Express is also not supported. |
| 54 </aside> |
| 55 <section id="introduction"> |
| 56 <h2 id="introduction">Introduction</h2> |
| 57 <p>The Native Client add-in for Visual Studio helps you develop your application |
| 58 more efficiently in many ways:</p> |
| 59 <ul class="small-gap"> |
| 60 <li>Organize and maintain your code as a Visual Studio project.</li> |
| 61 <li>Iteratively write and test your application more easily. Visual Studio |
| 62 handles the details of launching a web server to serve your module and run |
| 63 the module in Chrome with a debugger attached.</li> |
| 64 <li>Compile your module into a dynamically-linked library (DLL) using Visual |
| 65 Studio’s C/C++ compiler and run it as a Pepper plugin. This allows you to |
| 66 develop code incrementally, coding and/or porting one feature at a time into |
| 67 the Pepper APIs while continuing to use native Windows APIs that would |
| 68 otherwise be unavailable in an actual Native Client module.</li> |
| 69 <li>Use Visual Studio’s built-in debugger to debug your code while it’s ru
nning |
| 70 as a Pepper plugin.</li> |
| 71 <li>Compile your module into a .nexe or .pexe file using the Native Client SDK |
| 72 tools and run it as a bona fide Native Client module.</li> |
| 73 <li>Use the Native Client debugger, nacl-gdb, to test your code when it’s runnin
g |
| 74 as a Native Client object.</li> |
| 75 </ul> |
| 76 <p>The add-in defines five new Visual Studio platforms: <code>PPAPI</code>, <cod
e>NaCl32</code>, |
| 77 <code>NaCl64</code>, <code>NaClARM</code>, and <code>PNaCl</code>. These platfor
ms can be applied to the |
| 78 debug configuration of solutions and projects. The platforms configure the |
| 79 properties of your project so it can be built and run as either a Pepper plugin |
| 80 or a Native Client module. The platforms also define the behavior associated |
| 81 with the debug command so you can test your code while running in Visual |
| 82 Studio.</p> |
| 83 </section><section id="platforms"> |
| 84 <h2 id="platforms">Platforms</h2> |
| 85 <p>It is helpful to consider the Visual Studio add-in platforms in two groups. O
ne |
| 86 contains the PPAPI platform only. The other group, which we’ll call the Na
tive |
| 87 Client platforms, contains platforms that all have “NaCl” in their n
ames: |
| 88 <code>NaCl32</code>, <code>NaCl64</code>, <code>NaClARM</code>, and <code>PNaCl<
/code>. The diagram below shows the |
| 89 platforms, the ways they are normally used, and the build products they produce.
</p> |
| 90 <img alt="/native-client/images/visualstudio4.png" src="/native-client/images/vi
sualstudio4.png" /> |
| 91 <p>Using platforms, your workflow is faster and more efficient. You can compile, |
| 92 start, and debug your code with one click or key-press. When you press F5, the |
| 93 “start debugging” command, Visual Studio automatically launches a web server to |
| 94 serve your module (if necessary) along with an instance of Chrome that runs |
| 95 your Native Client module, and also attaches an appropriate debugger.</p> |
| 96 <p>You can switch between platforms as you work to compare the behavior of your |
| 97 code.</p> |
| 98 <p>When you run your project, Visual Studio launches the PPAPI and Native Client |
| 99 platforms in different ways, as explained in the next sections.</p> |
| 100 <section id="the-ppapi-platform"> |
| 101 <h3 id="the-ppapi-platform">The PPAPI platform</h3> |
| 102 <p>The PPAPI platform builds your module as a dynamic library and launches a |
| 103 version of Chrome that’s configured to run the library as a plugin when it |
| 104 encounters an <code><embed></code> element with <code>type=application/x-n
acl</code> (ignoring |
| 105 the information in the manifest file). When running in the PPAPI platform, you |
| 106 can use Windows system calls that are unavailable in a regular Native Client |
| 107 module built and running as a .nexe file. This offers the ability to port |
| 108 existing code incrementally, rewriting functions using the PPAPI interfaces one |
| 109 piece at a time. Since the module is built with Visual Studio’s native compiler |
| 110 (MSBuild) you can use the Visual Studio debugger to control and inspect your |
| 111 code.</p> |
| 112 </section><section id="the-native-client-platforms"> |
| 113 <h3 id="the-native-client-platforms">The Native Client platforms</h3> |
| 114 <p>There are four Native Client platforms. All of them can be used to build Nati
ve |
| 115 Client modules. When you run one of the Native Client platforms Visual Studio |
| 116 builds the corresponding type of Native Client module (either a .nexe or |
| 117 .pexe), starts a web server to serve it up, and launches a copy of Chrome that |
| 118 fetches the module from the server and runs it. Visual Studio will also open a |
| 119 terminal window, launch an instance of nacl-gdb, and attach it to your module
217;s |
| 120 process so you can use gdb commands to debug.</p> |
| 121 <section id="nacl32-and-nacl64"> |
| 122 <h4 id="nacl32-and-nacl64">NaCl32 and NaCl64</h4> |
| 123 <p>The platforms named NaCl32 and NaCl64 are targeted at x86 32-bit and 64-bit |
| 124 systems respectively. You need both platforms to build a full set of .nexe |
| 125 files when you are ready to distribute your application. Note, however, that |
| 126 when you are testing in Visual Studio you must select the NaCl64 platform |
| 127 (because Chrome for Windows runs Native Client in a 64-bit process). If you try |
| 128 to run from the NaCl32 platform you will get an error message.</p> |
| 129 </section><section id="naclarm"> |
| 130 <h4 id="naclarm">NaClARM</h4> |
| 131 <p>The NaClARM platform is targeted at ARM-based processors. You can build .nexe |
| 132 files with the NaClARM platform in Visual Studio but you cannot run them from |
| 133 there. You can use Visual Studio to create a Native Client module that includes |
| 134 an ARM-based .nexe file and then run the module from a Chrome browser on an ARM |
| 135 device, such as one of the newer Chromebook computers. See the instructions at |
| 136 <a class="reference internal" href="/native-client/devguide/devcycle/running.htm
l"><em>Running Native Client Applications</em></a> for more information on |
| 137 testing your module in Chrome.</p> |
| 138 <aside class="note"> |
| 139 Note: The NaClARM platform currently supports the newlib toolchain only. |
| 140 </aside> |
| 141 </section><section id="pnacl"> |
| 142 <h4 id="pnacl">PNaCl</h4> |
| 143 <p>The PNaCl (portable NaCl) platform is included in the Visual Studio Native |
| 144 Client add-in versions 1.1 and higher. It supports the .pexe file format. A |
| 145 .pexe file encodes your application as bitcode for a low level virtual machine |
| 146 (LLVM). When you deliver a Native Client application as a PNaCl module, the |
| 147 manifest file will contain a single .pexe file rather than multiple .nexe |
| 148 files. The Chrome client transforms the LLVM bitcode into machine instructions |
| 149 for the local system.</p> |
| 150 <p>When you run the PNaCl platform from Visual Studio, Visual Studio uses the |
| 151 Native Client SDK to transform the .pexe file into a NaCl64 .nexe file and runs |
| 152 it as if you were working with a NaCl64 platform.</p> |
| 153 <aside class="note"> |
| 154 Note: The PNaCl platform currently supports the newlib toolchain only. |
| 155 </aside> |
| 156 </section></section></section><section id="installing-the-add-in"> |
| 157 <h2 id="installing-the-add-in">Installing the add-in</h2> |
| 158 <p>In order to use the Native Client Visual Studio add-in, your development |
| 159 environment should include:</p> |
| 160 <ul class="small-gap"> |
| 161 <li>A 64-bit version of Windows Vista or Windows 7.</li> |
| 162 <li>Visual Studio 2010 with Service Pack 1.</li> |
| 163 <li><a class="reference external" href="https://www.google.com/intl/en/chrome/br
owser/">Chrome</a> version 23 or |
| 164 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> bu
ild of |
| 165 Chrome, running the canary version side-by-side with (and separately from) |
| 166 your regular version of Chrome.</li> |
| 167 <li><a class="reference internal" href="/native-client/sdk/download.html"><em>Th
e Native Client SDK</em></a> with the <code>pepper_23</code> |
| 168 bundle or greater. The version of Chrome that you use must be equal or |
| 169 greater than the version of the SDK bundle.</li> |
| 170 </ul> |
| 171 <section id="set-environment-variables"> |
| 172 <h3 id="set-environment-variables">Set environment variables</h3> |
| 173 <p>Before you run the installer you must define two Windows environment variable
s. |
| 174 They point to the bundle in the Native Client SDK that you use to build your |
| 175 module, and to the Chrome browser that you choose to use for debugging.</p> |
| 176 <p>To set environment variables in Windows 7, go to the Start menu and search fo
r |
| 177 “environment.” One of the links in the results is “Edit enviro
nment variables |
| 178 for your account.” (You can also reach this link from the <code>Control Pa
nel</code> |
| 179 under <code>User Accounts</code>.) Click on the link and use the buttons in the
window |
| 180 to create or change these user variables (the values shown below are only for |
| 181 example):</p> |
| 182 <table border="1" class="docutils"> |
| 183 <colgroup> |
| 184 </colgroup> |
| 185 <thead valign="bottom"> |
| 186 <tr class="row-odd"><th class="head">Variable Name</th> |
| 187 <th class="head">Description</th> |
| 188 </tr> |
| 189 </thead> |
| 190 <tbody valign="top"> |
| 191 <tr class="row-even"><td>NACL_SDK_ROOT</td> |
| 192 <td>The path to the pepper directory in the SDK. Example: |
| 193 <code>C:\nacl_sdk\pepper_23</code></td> |
| 194 </tr> |
| 195 <tr class="row-odd"><td>CHROME_PATH</td> |
| 196 <td>The path to the .exe file for the version of Chrome you are |
| 197 testing with. Example: |
| 198 <code>C:\Users\fred\AppData\Local\Google\Chrome |
| 199 SxS\Application\chrome.exe</code></td> |
| 200 </tr> |
| 201 </tbody> |
| 202 </table> |
| 203 </section><section id="download-the-add-in"> |
| 204 <h3 id="download-the-add-in">Download the add-in</h3> |
| 205 <p>The Native Client Visual Studio add-in is a separate bundle in the SDK named |
| 206 <code>vs_addin</code>. Open a command prompt window, go to the top-level SDK dir
ectory, |
| 207 and run the update command, specifying the add-in bundle:</p> |
| 208 <pre class="prettyprint"> |
| 209 naclsdk update vs_addin |
| 210 </pre> |
| 211 <p>This creates a folder named <code>vs_addin</code>, containing the add-in itse
lf, its |
| 212 installer files, and a directory of examples.</p> |
| 213 <aside class="note"> |
| 214 Note: The vs_addin bundle is only visible when you run <code>naclsdk</code> on a |
| 215 Windows system. |
| 216 </aside> |
| 217 </section><section id="run-the-installer"> |
| 218 <h3 id="run-the-installer">Run the installer</h3> |
| 219 <p>The installer script is located inside the <code>vs_addin</code> folder in th
e SDK. |
| 220 Right click on the file <code>install.bat</code> and run it as administrator.</p
> |
| 221 <p>The script always installs the NativeClient platforms, and asks you if you’d |
| 222 like to install the PPAPI platform as well. You can skip the PPAPI step and run |
| 223 the installer again later to add the PPAPI platform.</p> |
| 224 <p>You can usually run the installer successfully with no arguments. The new |
| 225 platforms are installed in <code>C:\Program Files |
| 226 (x86)\MSBuild\Microsoft.Cpp\v4.0\Platforms</code>.</p> |
| 227 <p>In some cases system resources may not be in their default locations. You mig
ht |
| 228 need to use these command line arguments when you run <code>install.bat</code>:<
/p> |
| 229 <ul class="small-gap"> |
| 230 <li>The MSBuild folder is assumed to be at <code>C:\Program Files (x86)\MSBuild<
/code>. |
| 231 You can specify an alternate path with the flag <code>--ms-build-path=<path&g
t;</code>. |
| 232 The installer assumes Visual Studio has created a user folder at</li> |
| 233 <li><code>%USERPROFILE%\My Documents\Visual Studio 2010</code>. You can specify
an |
| 234 alternate path with the flag <code>--vsuser-path=path</code>.</li> |
| 235 </ul> |
| 236 <p>From time to time an update to the Visual Studio add-in may become available. |
| 237 Updates are performed just like an installation. Download the new add-in using |
| 238 naclsdk update and run <code>install.bat</code> as administrator.</p> |
| 239 <p>To uninstall the add-in, run <code>install.bat</code> as administrator and ad
d the |
| 240 <code>--uninstall</code> flag. You’ll need to run the Command Prompt progr
am as |
| 241 administrator in order to add the flag. Go the to the Windows start menu, |
| 242 search for “Command Prompt,” right click on the program and run it a
s |
| 243 administrator.</p> |
| 244 <p>You can verify that the add-in has been installed and determine its version b
y |
| 245 selecting Add-in Manager in the Visual Studio Tools menu. If the add-in has |
| 246 been installed it will appear in the list of available add-ins. Select it and |
| 247 read its description.</p> |
| 248 </section></section><section id="try-the-hello-world-gles-sample-project"> |
| 249 <h2 id="try-the-hello-world-gles-sample-project">Try the <code>hello_world_gles<
/code> sample project</h2> |
| 250 <p>The add-in comes with an examples directory. Open the sample project |
| 251 <code>examples\hello_world_gles\hello_world_gles.sln</code>. This project is an |
| 252 application that displays a spinning cube.</p> |
| 253 <section id="select-the-nacl64-platform"> |
| 254 <h3 id="select-the-nacl64-platform">Select the NaCl64 platform</h3> |
| 255 <p>Open the sample project in Visual Studio, select the <code>Configuration Mana
ger</code>, |
| 256 and confirm that the active solution configuration is <code>Debug</code> and the
active |
| 257 project platform is <code>NaCl64</code>. Note that the platform for the |
| 258 <code>hello_world_gles</code> project is also <code>NaCl64</code>. (You can get
to the |
| 259 <code>Configuration Manager</code> from the <code>Build</code> menu or the proje
ct’s |
| 260 <code>Properties</code> window.)</p> |
| 261 <img alt="/native-client/images/visualstudio1.png" src="/native-client/images/vi
sualstudio1.png" /> |
| 262 </section><section id="build-and-run-the-project"> |
| 263 <h3 id="build-and-run-the-project">Build and run the project</h3> |
| 264 <p>Use the debugging command (F5) to build and run the project. As the wheels |
| 265 start to turn, you may be presented with one or more alerts. They are benign; |
| 266 you can accept them and set options to ignore them when that’s possible. Some |
| 267 of the messages you might see include:</p> |
| 268 <ul class="small-gap"> |
| 269 <li>“This project is out of date, would you like to build it?”</li> |
| 270 <li>“Please specify the name of the executable file to be used for the deb
ug |
| 271 session.” This should be the value of the environment variable CHROME_PATH
, |
| 272 which is usually supplied as the default value in the dialog.</li> |
| 273 <li>“Debugging information for chrome.exe cannot be found.” This is
to be |
| 274 expected, you are debugging your module’s code, not Chrome.</li> |
| 275 <li>“Open file - security warning. The publisher could not be verified.
221; If |
| 276 Visual Studio is complaining about x86_64-nacl-gdb.exe, that’s our debugger. |
| 277 Let it be.</li> |
| 278 </ul> |
| 279 <p>Once you’ve passed these hurdles, the application starts to run and you’ll se
e |
| 280 activity in three places:</p> |
| 281 <ol class="arabic simple"> |
| 282 <li>A terminal window opens running <code>nacl-gdb</code>.</li> |
| 283 <li>Chrome launches running your module in a tab.</li> |
| 284 <li>The Visual Studio output window displays debugging messages when you select |
| 285 the debug output item. |
| 286 Stop the debugging session by closing the Chrome window, or select the stop |
| 287 debugging command from the debug menu. The nacl-gdb window will close when |
| 288 you stop running the program.</li> |
| 289 </ol> |
| 290 </section><section id="test-the-nacl-gdb-debugger"> |
| 291 <h3 id="test-the-nacl-gdb-debugger">Test the nacl-gdb debugger</h3> |
| 292 <p>Add a breakpoint at the SwapBuffers call in the function MainLoop, which is i
n |
| 293 hello_world.cc.</p> |
| 294 <img alt="/native-client/images/visualstudio2.png" src="/native-client/images/vi
sualstudio2.png" /> |
| 295 <p>Start the debugger again (F5). This time the existing breakpoint is loaded in
to |
| 296 nacl-gcb and the program will pause there. Type c to continue running. You can |
| 297 use gdb commands to set more breakpoints and step through the application. For |
| 298 details, see <a class="reference internal" href="/native-client/devguide/devcycl
e/debugging.html#using-gdb"><em>Debugging with nacl-gdb</em></a> (scroll down to
the end |
| 299 of the section to see some commonly used gdb commands).</p> |
| 300 </section><section id="test-the-visual-studio-debugger"> |
| 301 <h3 id="test-the-visual-studio-debugger">Test the Visual Studio debugger</h3> |
| 302 <p>If you’ve installed the <code>PPAPI</code> platform, go back to the <code>Con
figuration |
| 303 Manager</code> and select the <code>PPAPI</code> platform. This time when Chrome
launches the |
| 304 <code>nacl-gdb</code> window will not appear; the Visual Studio debugger is full
y |
| 305 engaged and on the job.</p> |
| 306 </section><section id="inspect-the-platform-properties"> |
| 307 <h3 id="inspect-the-platform-properties">Inspect the platform properties</h3> |
| 308 <p>At this point, it may be helpful to take a look at the properties that are |
| 309 associated with the PPAPI and Native Client platforms—see the settings in
the |
| 310 sample project as an example.</p> |
| 311 </section></section><section id="developing-for-native-client-in-visual-studio"> |
| 312 <h2 id="developing-for-native-client-in-visual-studio">Developing for Native Cli
ent in Visual Studio</h2> |
| 313 <p>After you’ve installed the add-in and tried the sample project, you’re ready
to |
| 314 start working with your own code. You can reuse the sample project and the |
| 315 PPAPI and Native Client platforms it already has by replacing the source code |
| 316 with your own. More likely, you will add the platforms to an existing project, |
| 317 or to a new project that you create from scratch.</p> |
| 318 <section id="adding-platforms-to-a-project"> |
| 319 <h3 id="adding-platforms-to-a-project">Adding platforms to a project</h3> |
| 320 <p>Follow these steps to add the Native Client and PPAPI platforms to a project:
</p> |
| 321 <ol class="arabic simple"> |
| 322 <li>Open the Configuration Manager.</li> |
| 323 <li>On the row corresponding to your project, click the Platform column dropdown |
| 324 menu and select <code><New...></code>.</li> |
| 325 <li>Select <code>PPAPI</code>, <code>NaCl32</code>, <code>NaCl64</code>, or <cod
e>PNaCl</code> from the New platform |
| 326 menu.</li> |
| 327 <li>In most cases, you should select <code><Empty></code> in the “Copy set
tings from” |
| 328 menu. <strong>Never copy settings between ``PPAPI``, ``NaCl32``, ``NaCl64``, |
| 329 ``NaClARM``, or ``PNaCl`` platforms</strong>. You can copy settings from a Win32 |
| 330 platform, if one exists, but afterwards be sure that the project properties |
| 331 are properly set for the new platform, as mentioned in step 6 below.</li> |
| 332 <li>If you like, check the “Create new solutions platform” box to create a |
| 333 solution platform in addition to a project platform. (This is optional, but |
| 334 it can be convenient since it lets you switch project platforms from the |
| 335 Visual Studio main window by selecting the solution platform that has the |
| 336 same name.)</li> |
| 337 <li>Review the project properties for the new platform you just added. In most |
| 338 cases, the default properties for each platform should be correct, but it |
| 339 pays to check. Be especially careful about custom properties you may have |
| 340 set beforehand, or copied from a Win32 platform. Also confirm that the |
| 341 Configuration type is correct:<ul class="small-gap"> |
| 342 <li><code>Dynamic Library</code> for <code>PPAPI</code></li> |
| 343 <li><code>Application (.pexe)</code> for <code>PNaCl</code></li> |
| 344 <li><code>Application (.nexe)</code> for <code>NaCl32</code>, <code>NaCl64</code
>, and <code>NaClARM</code></li> |
| 345 </ul> |
| 346 </li> |
| 347 </ol> |
| 348 </section><section id="selecting-a-toolchain"> |
| 349 <h3 id="selecting-a-toolchain">Selecting a toolchain</h3> |
| 350 <p>When you build a Native Client module directly from the SDK you can use two |
| 351 different toolchains, newlib or glibc. See <a class="reference internal" href="/
native-client/devguide/devcycle/dynamic-loading.html"><em>Dynamic Linking and Lo
ading |
| 352 with glibc</em></a> for a description of the two toolchains and |
| 353 instructions on how to build and deploy an application with the glibc |
| 354 toolchain. The Native Client platforms offer you the same toolchain choice. You |
| 355 can specify which toolchain to use in the project properties, under |
| 356 <code>Configuration Properties > General > Native Client > Toolchain</c
ode>.</p> |
| 357 <aside class="note"> |
| 358 Currently, the NaClARM and PNaCl platforms only support the newlib toolchain. |
| 359 </aside> |
| 360 <p>There is no toolchain property for the PPAPI platform. The PPAPI platform use
s |
| 361 the toolchain and libraries that come with Visual Studio.</p> |
| 362 </section><section id="adding-libraries-to-a-project"> |
| 363 <h3 id="adding-libraries-to-a-project">Adding libraries to a project</h3> |
| 364 <p>If your Native Client application requires libraries that are not included in |
| 365 the SDK you must add them to the project properties (under <code>Configuration |
| 366 Properties > Linker > Input > Additional Dependencies</code>), just lik
e any other |
| 367 Visual Studio project. This list of dependencies is a semi-colon delimited |
| 368 list. On the PPAPI platform the library names include the .lib extension (e.g., |
| 369 <code>ppapi_cpp.lib;ppapi.lib</code>). On the Native Client platforms the extens
ion is |
| 370 excluded (e.g., <code>ppapi_cpp;ppapi</code>).</p> |
| 371 </section><section id="running-a-web-server"> |
| 372 <h3 id="running-a-web-server">Running a web server</h3> |
| 373 <p>In order for the Visual Studio add-in to test your Native Client module, you |
| 374 must serve the module from a web server. There are two options:</p> |
| 375 <section id="running-your-own-server"> |
| 376 <h4 id="running-your-own-server">Running your own server</h4> |
| 377 <p>When you start a debug run Visual Studio launches Chrome and tries to connect |
| 378 to the web server at the address found in the Chrome command arguments (see the |
| 379 project’s Debugging > Command configuration property), which is usually |
| 380 <code>localhost:$(NaClWebServerPort)</code>. If you are using your own server be
sure to |
| 381 specify its address in the command arguments property, and confirm that your |
| 382 server is running before starting a debug session. Also be certain that the |
| 383 server has all the files it needs to deliver a Native Client module (see |
| 384 “Keeping track of all the pieces”, below).</p> |
| 385 </section><section id="running-the-sdk-server"> |
| 386 <h4 id="running-the-sdk-server">Running the SDK server</h4> |
| 387 <p>If there is no web server running at the specified port, Visual Studio will t
ry |
| 388 to launch the simple Python web server that comes with the Native Client SDK. |
| 389 It looks for a copy of the server in the SDK itself (at |
| 390 <code>%NACL_SDK_ROOT%\tools\httpd.py</code>), and in the project directory |
| 391 (<code>$(ProjectDir)/httpd.py</code>). If the server exists in one of those loca
tions, |
| 392 Visual Studio launches the server. The server output appears in Visual Studio’s |
| 393 Output window, in the pane named “Native Client Web Server Output”. A server |
| 394 launched in this way is terminated when the debugging session ends.</p> |
| 395 </section></section><section id="keeping-track-of-all-the-pieces"> |
| 396 <h3 id="keeping-track-of-all-the-pieces">Keeping track of all the pieces</h3> |
| 397 <p>No matter where the web server lives or how it’s launched you must make sure |
| 398 that it has all the files that your application needs:</p> |
| 399 <ul class="small-gap"> |
| 400 <li>All Native Client applications must have an <a class="reference internal" hr
ef="/native-client/devguide/coding/application-structure.html#html-file"><em>htm
l host page</em></a>. This file is typically called <code>index.html</code>. The
host page |
| 401 must have an embed tag with its type attribute set to |
| 402 <code>application-type/x-nacl</code>. If you plan to use a Native Client platfor
m the |
| 403 embed tag must also include a src attribute pointing to a Native Client |
| 404 manifest (.mnf) file.</li> |
| 405 <li>If you are using a Native Client platform you must include a valid |
| 406 <a class="reference internal" href="/native-client/devguide/coding/application-s
tructure.html#manifest-file"><em>manifest file</em></a>. The manifest file point
s to the .pexe |
| 407 or .nexe files that Visual Studio builds. These will be placed in the |
| 408 directory specified in the project’s <code>General > Output Directory</code> |
| 409 configuration property, which is usually <code>$(ProjectDir)$(ToolchainName)</co
de>. |
| 410 Visual Studio can use the Native Client SDK script create_nmf.py to |
| 411 automatically generate the manifest file for you. To use this script set the |
| 412 project’s <code>Linker > General > Create NMF Automatically</code> p
roperty to “yes.”</li> |
| 413 </ul> |
| 414 <p>If you are letting Visual Studio discover and run the SDK server, these files |
| 415 should be placed in the project directory. If you are running your own server, |
| 416 you must be sure that the host page <code>index.html</code> is placed in your se
rver’s |
| 417 root directory. Remember, if you’re using one of the Native Client platforms |
| 418 the paths for the manifest file and .pexe or .nexe files must be reachable from |
| 419 the server.</p> |
| 420 <p>The structure of the manifest file can be more complicated if your applicatio
n |
| 421 uses Native Client’s ability to dynamically link libraries. You may have t
o add |
| 422 additional information about dynamically linked libraries to the manifest file |
| 423 even if you create it automatically. The use and limitations of the create_nmf |
| 424 tool are explained in <a class="reference internal" href="/native-client/devguid
e/devcycle/dynamic-loading.html#dynamic-loading-manifest"><em>Generating a Nativ
e Client manifest file for a |
| 425 dynamically linked application</em></a>.</p> |
| 426 <p>You can look at the example projects in the SDK to see how the index and |
| 427 manifest files are organized. The example project <code>hello_nacl</code> has a |
| 428 subdirectory also called <code>hello_nacl</code>. That folder contains <code>ind
ex.html</code> |
| 429 and <code>hello_nacl.nmf</code>. The nexe file is found in |
| 430 <code>NaCl64\newlib\Debug\hello_nacl_64.nexe</code>. The <code>hello_world_gles<
/code> example |
| 431 project contains a subdirectory called <cite>hello_world_gles`</cite>. That dire
ctory |
| 432 contains html files built with both toolchains (<code>index_glibc.html</code> an
d |
| 433 <code>index_newlib.html</code>). The .nexe and .nmf files are found in the newli
b and |
| 434 glibc subfolders. For additional information about the parts of a Native Client |
| 435 application, see <a class="reference internal" href="/native-client/devguide/cod
ing/application-structure.html"><em>Application Structure</em></a>.</p> |
| 436 </section><section id="using-the-debuggers"> |
| 437 <h3 id="using-the-debuggers">Using the debuggers</h3> |
| 438 <p>PPAPI plugins are built natively by Visual Studio’s compiler (MSBuild), and |
| 439 work with Visual Studio’s debugger in the usual way. You can set breakpoints in |
| 440 the Visual Studio source code files before you begin debugging, and on-the-fly |
| 441 while running the program.</p> |
| 442 <p>NaCl32 and NaClARM executables (.nexe files) cannot be run or debugged from |
| 443 Visual Studio.</p> |
| 444 <p>NaCl64 executables (.nexe files) are compiled using one of the Native Client |
| 445 toolchains in the SDK, which create an <a class="reference external" href="`http
://en.wikipedia.org/wiki/Executable_and_Linkable_Format">ELF-formatted</a> execu
table. To |
| 446 debug a running .nexe you must use nacl-gdb, which is a command line debugger |
| 447 that is not directly integrated with Visual Studio. When you start a debugging |
| 448 session running from a NaCl64 platform, Visual Studio automatically launches |
| 449 nacl-gdb for you and attaches it to the nexe. Breakpoints that you set in |
| 450 Visual Studio before you start debugging are transferred to nacl-gdb |
| 451 automatically. During a NaCl debugging session you can only use nacl-gdb |
| 452 commands.</p> |
| 453 <p>The PNaCl platform generates a .pexe file. When you run the debugger add-in |
| 454 translates the .pexe file to a .nexe file and runs the resulting binary with |
| 455 nacl-gdb attached.</p> |
| 456 <p>For additional information about nacl-gdb, see <a class="reference internal"
href="/native-client/devguide/devcycle/debugging.html#using-gdb"><em>Debugging w
ith nacl-gdb</em></a> (scroll down to the end of the section to see some commonl
y used |
| 457 gdb commands).</p> |
| 458 <p>Note that you can’t use the Start Without Debugging command (Ctrl+F5) with a |
| 459 project in the Debug configuration. If you do, Chrome will hang because the |
| 460 Debug platform launches Chrome with the command argument |
| 461 <code>--wait-for-debugger-children</code> (in PPAPI) or <code>--enable-nacl-debu
g</code> (in a |
| 462 Native Client platform). These flags cause Chrome to pause and wait for a |
| 463 debugger to attach. If you use the Start Without Debugging command, no debugger |
| 464 attaches and Chrome just waits patiently. To use Start Without Debugging, |
| 465 switch to the Release configuration, or manually remove the offending argument |
| 466 from the <code>Command Arguments</code> property.</p> |
| 467 </section><section id="disable-chrome-caching"> |
| 468 <h3 id="disable-chrome-caching">Disable Chrome caching</h3> |
| 469 <p>When you debug with a Native Client platform you might want to <a class="refe
rence internal" href="/native-client/devguide/devcycle/running.html#cache"><em>d
isable |
| 470 Chrome’s cache</em></a> to be sure you are testing your latest and greates
t |
| 471 code.</p> |
| 472 </section><section id="a-warning-about-postmessage"> |
| 473 <h3 id="a-warning-about-postmessage">A warning about PostMessage</h3> |
| 474 <p>Some Windows libraries define the symbol <code>PostMessage</code> as <code>Po
stMessageW</code>. |
| 475 This can cause havoc if you are working with the PPAPI platform and you use the |
| 476 Pepper <code>PostMessage()</code> call in your module. Some Pepper API header fi
les |
| 477 contain a self-defensive fix that you might need yourself, while you are |
| 478 testing on the PPAPI platform. Here it is:</p> |
| 479 <pre class="prettyprint"> |
| 480 // If Windows defines PostMessage, undef it. |
| 481 #ifdef PostMessage |
| 482 #undef PostMessage |
| 483 #endif |
| 484 </pre> |
| 485 </section><section id="porting-windows-applications-to-native-client-in-visual-s
tudio"> |
| 486 <h3 id="porting-windows-applications-to-native-client-in-visual-studio">Porting
Windows applications to Native Client in Visual Studio</h3> |
| 487 <p>At Google I/O 2012 we demonstrated how to port a Windows desktop application
to |
| 488 Native Client in 60 minutes. The <a class="reference external" href="http://www.
youtube.com/watch?v=1zvhs5FR0X8&feature=plcp">video</a> is available to |
| 489 watch on YouTube. The <code>vs_addin/examples</code> folder contains a pair of s
imple |
| 490 examples that demonstrate porting process. They are designed to be completed |
| 491 in just 5 minutes. The two examples are called <code>hello_nacl</code> and |
| 492 <code>hello_nacl_cpp</code>. They are essentially the same, but the former uses
the C |
| 493 PPAPI interface while the latter uses the C++ API. The application is the |
| 494 familiar “Hello, World.”</p> |
| 495 <p>Each example begins with the Windows desktop version running in the <code>Win
32</code> |
| 496 platform. From there you move to the <code>PPAPI</code> platform, where you perf
orm a |
| 497 series of steps to set up the Native Client framework, use it to run the |
| 498 desktop version, and then port the behavior from Windows calls to the PPAPI |
| 499 interface. You wind up with a program that uses no Windows functions, which |
| 500 can run in either the <code>PPAPI</code> or the <code>NaCl64</code> platform.</p
> |
| 501 <p>The example projects use a single source file (<code>hello_nacl.c</code> or |
| 502 <code>hello_nacl_cpp.cpp</code>). Each step in the porting process is accomplish
ed by |
| 503 progressively defining the symbols STEP1 through STEP6 in the source. Inline |
| 504 comments explain how each successive step changes the code. View the example |
| 505 code to see how it’s actually done. Here is a summary of the process:</p> |
| 506 <section id="win32-platform"> |
| 507 <h4 id="win32-platform">Win32 Platform</h4> |
| 508 <dl class="docutils"> |
| 509 <dt>STEP1 Run the desktop application</dt> |
| 510 <dd>Begin by running the original Windows application in the Win32 platform.</dd
> |
| 511 </dl> |
| 512 </section><section id="ppapi-platform"> |
| 513 <h4 id="ppapi-platform">PPAPI Platform</h4> |
| 514 <dl class="docutils"> |
| 515 <dt>STEP2 Launch Chrome with an empty Native Client module</dt> |
| 516 <dd>Switch to the PPAPI platform and include the code required to initialize a |
| 517 Native Module instance. The code is bare-boned, it does nothing but |
| 518 initialize the module. This step illustrates how Visual Studio handles all |
| 519 the details of launching a web-server and Chrome, and running the Native |
| 520 Client module as a Pepper plugin.</dd> |
| 521 <dt>STEP3 Run the desktop application synchronously from the Native Client modul
e</dt> |
| 522 <dd>The Native Client creates the window directly and then calls WndProc to run |
| 523 the desktop application. Since WndProc spins in its message loop, the call to |
| 524 initialize the module never returns. Close the Hello World window and the |
| 525 module initialization will finish.</dd> |
| 526 <dt>STEP4 Running the desktop application and Native Client asynchronously</dt> |
| 527 <dd>In WndProc replace the message loop with a callback function. Now the app |
| 528 window and the Native Client module are running concurrently.</dd> |
| 529 <dt>STEP5 Redirect output to the web page</dt> |
| 530 <dd>The module initialization code calls initInstanceInBrowserWindow rather than |
| 531 initInstanceInPCWindow. WndProc is no longer used. Instead, postMessage is |
| 532 called to place text (now “Hello, Native Client”) in the web page ra
ther than |
| 533 opening and writing to a window. Once you’ve reached this step you can sta
rt |
| 534 porting pieces of the application one feature at a time.</dd> |
| 535 <dt>STEP6 Remove all the Windows code</dt> |
| 536 <dd>All the Windows code is def’d out, proving we are PPAPI-compliant. The |
| 537 functional code that is running is the same as STEP5.</dd> |
| 538 </dl> |
| 539 </section><section id="nacl64-platform"> |
| 540 <h4 id="nacl64-platform">NaCl64 Platform</h4> |
| 541 <dl class="docutils"> |
| 542 <dt>Run the Native Client Module in the NaCl64 platform</dt> |
| 543 <dd>You are still running the STEP6 code, but as a Native Client module rather |
| 544 than a Pepper plugin.</dd> |
| 545 </dl> |
| 546 </section></section></section></section> |
| 547 |
| 548 {{/partials.standard_nacl_article}} |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 140993006:
[NaCl SDK Docs] Check in the generated NaCl SDK Documentation. (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src