<li><p class="first"><a class="reference internal" href="#debugging-with-printf" id="id7">Debugging with printf</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#redirecting-output-to-log-files" id="id8">Redirecting output to log files</a></li>
-<li><a class="reference internal" href="#redirecting-output-to-the-javascript-console" id="id9">Redirecting output to the JavaScript console</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#logging-calls-to-pepper-interfaces" id="id10">Logging calls to Pepper interfaces</a></li>
-<li><a class="reference internal" href="#debugging-with-visual-studio" id="id11">Debugging with Visual Studio</a></li>
-<li><p class="first"><a class="reference internal" href="#debugging-with-nacl-gdb" id="id12">Debugging with nacl-gdb</a></p>
+<li><a class="reference internal" href="#logging-calls-to-pepper-interfaces" id="id9">Logging calls to Pepper interfaces</a></li>
+<li><a class="reference internal" href="#debugging-with-visual-studio" id="id10">Debugging with Visual Studio</a></li>
+<li><p class="first"><a class="reference internal" href="#debugging-with-nacl-gdb" id="id11">Debugging with nacl-gdb</a></p>
<ul class="small-gap">
-<li><a class="reference internal" href="#debugging-pnacl-pexes-with-pepper-35" id="id13">Debugging PNaCl pexes (with Pepper 35+)</a></li>
-<li><a class="reference internal" href="#debugging-pnacl-pexes-with-older-pepper-toolchains" id="id14">Debugging PNaCl pexes (with older Pepper toolchains)</a></li>
-<li><a class="reference internal" href="#running-nacl-gdb" id="id15">Running nacl-gdb</a></li>
+<li><a class="reference internal" href="#debugging-pnacl-pexes-pepper-35-or-later" id="id12">Debugging PNaCl pexes (Pepper 35 or later)</a></li>
+<li><a class="reference internal" href="#debugging-pnacl-pexes-with-older-pepper-toolchains" id="id13">Debugging PNaCl pexes (with older Pepper toolchains)</a></li>
+<li><a class="reference internal" href="#running-nacl-gdb" id="id14">Running nacl-gdb</a></li>
</ul>
</li>
</ul>
</li>
-<li><p class="first"><a class="reference internal" href="#debugging-with-other-tools" id="id16">Debugging with other tools</a></p>
-<ul class="small-gap">
-<li><a class="reference internal" href="#open-source-profiling-tools" id="id17">Open source profiling tools</a></li>
-</ul>
-</li>
+<li><a class="reference internal" href="#debugging-with-other-tools" id="id15">Debugging with other tools</a></li>
</ul>
-</div><section id="diagnostic-information">
-<h2 id="diagnostic-information">Diagnostic information</h2>
-<section id="viewing-process-statistics-with-the-task-manager">
+</div><h2 id="diagnostic-information">Diagnostic information</h2>
<h3 id="viewing-process-statistics-with-the-task-manager">Viewing process statistics with the task manager</h3>
<p>You can use Chrome’s Task Manager to display information about a Native Client
application:</p>
memory information are visible. If they are not, right click in the header
row and select the memory items from the popup menu that appears.</li>
</ol>
-<p>A browser window running a Native Client application will have at least two
-processes associated with it: a process for the app’s top level (the render
-process managing the page including its HTML and any JavaScript) and one or
-more processes for each instance of a Native Client module embedded in the page
-(each process running native code from one nexe file). The top-level process
-appears with the application’s icon and begins with the text “App:”. A Native
-Client process appears with a Chrome extension icon (a jigsaw puzzle piece
-<img alt="puzzle" src="/native-client/images/puzzle.png" />) and begins with the text “Native Client module” followed by the URL
-of its manifest file.</p>
+<p>A browser window running a Native Client application has at least two processes
+associated with it: a process for the app’s top level (the render process
+managing the page including its HTML and JavaScript) and one or more
+processes for each instance of a Native Client module embedded in the page
+(each process running native code from one nexe or pexe file). The top-level
+process appears with the application’s icon and begins with the text “Tab:”.
+A Native Client process appears with a Chrome extension icon (a jigsaw puzzle
+piece <img alt="puzzle" src="/native-client/images/puzzle.png" />) and begins with the text “Native Client module:” followed by the
+URL of its manifest file.</p>
<p>From the Task Manager you can view the changing memory allocations of all the
processes associated with a Native Client application. Each process has its own
memory footprint. You can also see the rendering rate displayed as frames per
second (FPS). Note that the computation of render frames can be performed in
any process, but the rendering itself is always done in the top level
application process, so look for the rendering rate there.</p>
-</section><section id="controlling-the-level-of-native-client-error-and-warning-messages">
<h3 id="controlling-the-level-of-native-client-error-and-warning-messages">Controlling the level of Native Client error and warning messages</h3>
<p>Native Client prints warning and error messages to stdout and stderr. You can
increase the amount of Native Client’s diagnostic output by setting the
following <a class="reference external" href="http://en.wikipedia.org/wiki/Environment_variable">environment variables</a>:</p>
<ul class="small-gap">
-<li>NACL_DEBUG_ENABLE=1</li>
-<li>PPAPI_BROWSER_DEBUG=1</li>
-<li>NACL_PLUGIN_DEBUG=1</li>
-<li>NACL_PPAPI_PROXY_DEBUG=1</li>
-<li>NACL_SRPC_DEBUG=[1-255] (use a higher number for more verbose debug output)</li>
-<li>NACLVERBOSITY=[1-255]</li>
+<li><code>NACL_PLUGIN_DEBUG=1</code></li>
+<li><code>NACL_SRPC_DEBUG=[1-255]</code> (use a higher number for more verbose debug
+output)</li>
+<li><code>NACLVERBOSITY=[1-255]</code></li>
</ul>
-</section></section><section id="basic-debugging">
<h2 id="basic-debugging">Basic debugging</h2>
-<section id="writing-messages-to-the-javascript-console">
<h3 id="writing-messages-to-the-javascript-console">Writing messages to the JavaScript console</h3>
-<p>You can send messages from your C/C++ code to JavaScript using the PostMessage
-call in the <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Pepper messaging system</em></a>. When the
-JavaScript code receives a message, its message event handler can call
-<a class="reference external" href="https://developer.mozilla.org/en/DOM/console.log">console.log()</a> to write
-the message to the JavaScript <a class="reference external" href="/devtools/docs/console-api">console</a> in
-Chrome’s Developer Tools.</p>
-</section><section id="debugging-with-printf">
+<p>You can send messages from your C/C++ code to JavaScript using the
+<code>PostMessage()</code> call in the <a class="reference internal" href="/native-client/devguide/coding/message-system.html"><em>Pepper messaging system</em></a>. When the JavaScript code receives a message, its
+message event handler can call <a class="reference external" href="https://developer.mozilla.org/en/DOM/console.log">console.log()</a> to write the message to the
+JavaScript <a class="reference external" href="/devtools/docs/console-api">console</a> in Chrome’s Developer Tools.</p>
<h3 id="debugging-with-printf">Debugging with printf</h3>
<p>Your C/C++ code can perform inline printf debugging to stdout and stderr by
calling fprintf() directly, or by using cover functions like these:</p>
</pre>
<p>By default stdout and stderr will appear in Chrome’s stdout and stderr stream
but they can also be redirected as described below.</p>
-<section id="redirecting-output-to-log-files">
<h4 id="redirecting-output-to-log-files">Redirecting output to log files</h4>
-<p>You can redirect stdout and stderr to output files by setting these environment variables:</p>
+<p>You can redirect stdout and stderr to output files by setting these environment
+variables:</p>
<ul class="small-gap">
<li><code>NACL_EXE_STDOUT=c:\nacl_stdout.log</code></li>
<li><code>NACL_EXE_STDERR=c:\nacl_stderr.log</code></li>
<li><code>NACLLOG=c:\nacl.log</code></li>
</ul>
<aside class="note">
-<strong>Note:</strong> If you set the NACL_EXE_STDOUT, NACL_EXE_STDERR, or NACLLOG
-variables to redirect output to a file, you must run Chrome with the
-<code>--no-sandbox</code> flag. You must also be careful that each variable points to
-a different file.
+<strong>Note:</strong> If you set the <code>NACL_EXE_STDOUT</code>, <code>NACL_EXE_STDERR</code>, or
+<code>NACLLOG</code> variables to redirect output to a file, you must run Chrome with
+the <code>--no-sandbox</code> flag. You must also be careful that each variable points
+to a different file.
</aside>
-</section><section id="redirecting-output-to-the-javascript-console">
-<h4 id="redirecting-output-to-the-javascript-console">Redirecting output to the JavaScript console</h4>
-<p>You can also cause output from printf statements in your C/C++ code to be
-relayed to the JavaScript side of your application through the Pepper messaging
-system, where you can then write the output to the JavaScript console. Follow
-these steps:</p>
-<ol class="arabic">
-<li><p class="first">Set the NACL_EXE_STDOUT and NACL_EXE_STDERR environment variables as
-follows:</p>
-<ul class="small-gap">
-<li><p class="first">NACL_EXE_STDOUT=DEBUG_ONLY:dev://postmessage</p>
-</li>
-<li><p class="first">NACL_EXE_STDERR=DEBUG_ONLY:dev://postmessage</p>
-</li>
-</ul>
-<p>These settings tell Native Client to use PostMessage() to send output that
-your Native Client module writes to stdout and stderr to the JavaScript side
-of your application.</p>
-</li>
-<li><p class="first">Register a JavaScript handler to receive messages from your Native Client
-module:</p>
-<pre class="prettyprint">
-<div id="nacl_container">
- <script type="text/javascript">
- var container = document.getElementById('nacl_container');
- container.addEventListener('message', handleMessage, true);
- </script>
- <embed id="nacl_module"
- src="my_application.nmf"
- type="application/x-nacl" />
-</div>
-</pre>
-</li>
-<li><p class="first">Implement a simple JavaScript handler that logs the messages it receives to
-the JavaScript console:</p>
-<pre class="prettyprint">
-function handleMessage(message_event) {
- console.log(message_event.data);
-}
-</pre>
-<p>This handler works in the simple case where the only messages your Native
-Client module sends to JavaScript are messages with the output from stdout
-and stderr. If your Native Client module also sends other messages to
-JavaScript, your handler will need to be more complex.</p>
-<p>Once you’ve implemented a message handler and set up the environment
-variables as described above, you can check the JavaScript console to see
-output that your Native Client module prints to stdout and stderr. Keep in
-mind that your module makes a call to PostMessage() every time it flushes
-stdout or stderr. Your application’s performance will degrade considerably
-if your module prints and flushes frequently, or if it makes frequent Pepper
-calls to begin with (e.g., to render).</p>
-</li>
-</ol>
-</section></section><section id="logging-calls-to-pepper-interfaces">
<h3 id="logging-calls-to-pepper-interfaces">Logging calls to Pepper interfaces</h3>
<p>You can log all Pepper calls your module makes by passing the following flags
to Chrome on startup:</p>
begin with “ppb” (that is, the interfaces that are implemented by the browser
and that your module calls). The <code>enable-logging</code> flag tells Chrome to log
the calls to stderr.</p>
-</section><section id="debugging-with-visual-studio">
-<span id="visual-studio"></span><h3 id="debugging-with-visual-studio"><span id="visual-studio"></span>Debugging with Visual Studio</h3>
+<h3 id="debugging-with-visual-studio"><span id="visual-studio"></span>Debugging with Visual Studio</h3>
<p>If you develop on a Windows platform you can use the <a class="reference internal" href="/native-client/devguide/devcycle/vs-addin.html"><em>Native Client Visual
Studio add-in</em></a> to write and debug your code. The add-in defines new
project platforms that let you run your module in two different modes: As a
you can use the built-in Visual Studio debugger. When running as a Native
Client module Visual Studio will launch an instance of nacl-gdb for you and
link it to the running code.</p>
-</section><section id="debugging-with-nacl-gdb">
-<span id="using-gdb"></span><h3 id="debugging-with-nacl-gdb"><span id="using-gdb"></span>Debugging with nacl-gdb</h3>
+<h3 id="debugging-with-nacl-gdb"><span id="using-gdb"></span>Debugging with nacl-gdb</h3>
<p>The Native Client SDK includes a command-line debugger that you can use to
debug Native Client modules. The debugger is based on the GNU debugger <a class="reference external" href="http://www.gnu.org/software/gdb/">gdb</a>, and is located at
-<code>toolchain/<platform>_x86_newlib/bin/x86_64-nacl-gdb</code> (where <em><platform></em>
-is the platform of your development machine: <code>win</code>, <code>mac</code>, or
+<code>pepper_<version>/toolchain/<platform>_x86_newlib/bin/x86_64-nacl-gdb</code> (where
+<em><platform></em> is the platform of your development machine: <code>win</code>, <code>mac</code>, or
<code>linux</code>).</p>
<p>Note that this same copy of GDB can be used to debug any NaCl program,
whether built using newlib or glibc for x86-32, x86-64 or ARM. In the SDK,
<code>i686-nacl-gdb</code> is an alias for <code>x86_64-nacl-gdb</code>, and the <code>newlib</code>
and <code>glibc</code> toolchains both contain the same version of GDB.</p>
-<section id="debugging-pnacl-pexes-with-pepper-35">
-<span id="debugging-pnacl-pexes"></span><h4 id="debugging-pnacl-pexes-with-pepper-35"><span id="debugging-pnacl-pexes"></span>Debugging PNaCl pexes (with Pepper 35+)</h4>
+<h4 id="debugging-pnacl-pexes-pepper-35-or-later"><span id="debugging-pnacl-pexes"></span>Debugging PNaCl pexes (Pepper 35 or later)</h4>
<p>If you want to use GDB to debug a program that is compiled with the PNaCl
toolchain, you must have a copy of the pexe from <strong>before</strong> running
<code>pnacl-finalize</code>. The <code>pnacl-finalize</code> tool converts LLVM bitcode
to the stable PNaCl bitcode format, but it also strips out debug
-metadata, which we need for debugging.</p>
+metadata, which we need for debugging. In this section we’ll give the
+LLVM bitcode file a <code>.bc</code> file extension, and the PNaCl bitcode file
+a <code>.pexe</code> file extension. The actual extension should not matter, but
+it helps distinguish between the two types of files.</p>
<p><strong>Note</strong> unlike the finalized copy of the pexe, the non-finalized debug copy
is not considered stable. This means that a debug copy of the PNaCl
application created by a Pepper N SDK is only guaranteed to run
with a matching Chrome version N. If the version of the debug bitcode pexe
does not match that of Chrome then the translation process may fail, and
-you will see and error message in the JavaScript console.</p>
+you will see an error message in the JavaScript console.</p>
<p>Also, make sure you are passing the <code>-g</code> <a class="reference internal" href="/native-client/devguide/devcycle/building.html#compile-flags"><em>compile option</em></a> to <code>pnacl-clang</code> to enable generating debugging info.
You might also want to omit <code>-O2</code> from the compile-time and link-time
options, otherwise GDB not might be able to print variables’ values when
<pre class="prettyprint">
{
"program": {
- "pnacl-translate": {
- "url": "release_version.pexe",
- "optlevel": 2
- },
- "pnacl-debug": {
- "url": "debug_version.bc",
- "optlevel": 0
+ "portable": {
+ "pnacl-translate": {
+ "url": "release_version.pexe",
+ "optlevel": 2
+ },
+ "pnacl-debug": {
+ "url": "debug_version.bc",
+ "optlevel": 0
+ }
}
}
}
the SDK version. Developers who may have left the <code>--enable-nacl-debug</code>
flag turned on may end up loading the debug copy of your application
(which may or may not work, depending on their version of Chrome).</p>
-</section><section id="debugging-pnacl-pexes-with-older-pepper-toolchains">
<h4 id="debugging-pnacl-pexes-with-older-pepper-toolchains">Debugging PNaCl pexes (with older Pepper toolchains)</h4>
<p>If you want to use GDB to debug a program that is compiled with the PNaCl
toolchain, you must convert the <code>pexe</code> file to a <code>nexe</code>. (You can skip
<li><p class="first">Secondly, use <code>pnacl-translate</code> to convert your <code>pexe</code> to one or more
<code>nexe</code> files. For example:</p>
<pre>
-<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-translate ^
- --allow-llvm-bitcode-input hello_world.pexe -arch x86-32 -o hello_world_x86_32.nexe
-<NACL_SDK_ROOT>/toolchain/win_pnacl/bin/pnacl-translate ^
- --allow-llvm-bitcode-input hello_world.pexe -arch x86-64 -o hello_world_x86_64.nexe
+nacl_sdk/pepper_<version>/toolchain/win_pnacl/bin/pnacl-translate \
+ --allow-llvm-bitcode-input hello_world.pexe -arch x86-32 \
+ -o hello_world_x86_32.nexe
+nacl_sdk/pepper_<version>/toolchain/win_pnacl/bin/pnacl-translate \
+ --allow-llvm-bitcode-input hello_world.pexe -arch x86-64 \
+ -o hello_world_x86_64.nexe
</pre>
<p>For this, use the non-finalized <code>pexe</code> file produced by
<code>pnacl-clang</code>, not the <code>pexe</code> file produced by <code>pnacl-finalize</code>.
might find it easier to translate the <code>pexe</code> to both <code>nexe</code>
formats as described above.
</aside>
-</section><section id="running-nacl-gdb">
-<span id="id1"></span><h4 id="running-nacl-gdb"><span id="id1"></span>Running nacl-gdb</h4>
+<h4 id="running-nacl-gdb"><span id="id1"></span>Running nacl-gdb</h4>
<p>Before you start using nacl-gdb, make sure you can <a class="reference internal" href="/native-client/devguide/devcycle/building.html"><em>build</em></a> your
module and <a class="reference internal" href="/native-client/devguide/devcycle/running.html"><em>run</em></a> your application normally. This will verify
that you have created all the required <a class="reference internal" href="/native-client/devguide/coding/application-structure.html"><em>application parts</em></a> (.html, .nmf, and .nexe files, shared
<li><p class="first">Go to the directory with your source code, and run nacl-gdb from there. For
example:</p>
<pre class="prettyprint">
-cd <NACL_SDK_ROOT>/examples/hello_world_gles
-<NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb
+cd nacl_sdk/pepper_<version>/examples/demo/drive
+nacl_sdk/pepper_<version>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb
</pre>
<p>The debugger will start and show you a gdb prompt:</p>
<pre class="prettyprint">
(gdb)
</pre>
</li>
-<li><p class="first">For debugging PNaCl pexes run the following gdb command lines
-(skip to the next item if you are using NaCl instead of PNaCl):</p>
+<li><p class="first">Run the debugging command lines.</p>
+<p><strong>For PNaCl</strong>:</p>
<pre class="prettyprint">
(gdb) target remote localhost:4014
(gdb) remote get nexe <path-to-save-translated-nexe-with-debug-info>
(gdb) remote get irt <path-to-save-NaCl-integrated-runtime>
(gdb) nacl-irt <path-to-saved-NaCl-integrated-runtime>
</pre>
-</li>
-<li><p class="first">For NaCl nexes, run the following commands from the gdb command line:</p>
+<p><strong>For NaCl</strong>:</p>
<pre class="prettyprint">
(gdb) target remote localhost:4014
(gdb) nacl-manifest <path-to-your-.nmf-file>
SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe</code>.
The <code>remote get irt <path></code> saves that to the current working
directory so that you do not need to find where exactly the IRT
-is stored alongside Chrome.</p>
+is stored.</p>
</dd>
<dt><code>nacl-irt <path></code></dt>
<dd><p class="first last">Tells the debugger where to find the Native Client Integrated Runtime
Windows:</p>
<pre class="prettyprint">
target remote localhost:4014
-nacl-manifest "C:/<NACL_SDK_ROOT>/examples/hello_world_gles/newlib/Debug/hello_world_gles.nmf"
+nacl-manifest "C:/nacl_sdk/pepper_<version>/examples/hello_world_gles/newlib/Debug/hello_world_gles.nmf"
nacl-irt "C:/Users/<username>/AppData/Local/Google/Chrome SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe"
</pre>
<p>To save yourself some typing, you can put put these nacl-gdb commands in a
script file, and execute the file when you run nacl-gdb, like so:</p>
<pre class="prettyprint">
-<NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb -x <nacl-script-file>
+nacl_sdk/pepper_<version>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb -x <nacl-script-file>
</pre>
<p>If nacl-gdb connects successfully to Chrome, it displays a message such as
the one below, followed by a gdb prompt:</p>
to just their first letter (<code>b</code> for break, <code>c</code> for continue, and so on).</p>
<p>To interrupt execution of your module, press <Ctrl-c>. When you’re done
debugging, close the Chrome window and type <code>q</code> to quit gdb.</p>
-</section></section></section><section id="debugging-with-other-tools">
<h2 id="debugging-with-other-tools">Debugging with other tools</h2>
<p>If you cannot use the <a class="reference internal" href="#visual-studio"><em>Visual Studio add-in</em></a>, or you want
to use a debugger other than nacl-gdb, you must manually build your module as a
Note that starting with the <code>pepper_22</code> bundle, the NaCl SDK for Windows
includes pre-built libraries and library source code, making it much easier to
build a module into a .DLL.</p>
-<section id="open-source-profiling-tools">
-<h3 id="open-source-profiling-tools">Open source profiling tools</h3>
-<p>For the brave-hearted there are open source tools at <a class="reference external" href="http://www.chromium.org/nativeclient">Chromium.org</a> that describe how to do profiling on
-<a class="reference external" href="https://sites.google.com/a/chromium.org/dev/nativeclient/how-tos/profiling-nacl-apps-on-64-bit-windows">64-bit Windows</a>
-and <a class="reference external" href="http://www.chromium.org/nativeclient/how-tos/limited-profiling-with-oprofile-on-x86-64">Linux</a>
-machines.</p>
-</section></section></section>
+</section>
{{/partials.standard_nacl_article}}