Add debugging information for nacl_io library.

native_client_sdk/doc_generated/devguide/devcycle/debugging.html

 {{+bindTo:partials.standard_nacl_article}}
 
 <section id="debugging">
 <span id="devcycle-debugging"></span><h1 id="debugging"><span id="devcycle-debugging"></span>Debugging</h1>
 <p>This document describes tools and techniques you can use to debug, monitor,
 and measure your application&#8217;s performance.</p>
 <div class="contents local" id="table-of-contents" style="display: none">
 <p class="topic-title first">Table Of Contents</p>
 <ul class="small-gap">
 <li><p class="first"><a class="reference internal" href="#diagnostic-information" id="id2">Diagnostic information</a></p>
@@ skipping 73 matching lines @@
 #include &lt;stdio.h&gt;
 void logmsg(const char* pMsg){
   fprintf(stdout,&quot;logmsg: %s\n&quot;,pMsg);
 }
 void errormsg(const char* pMsg){
   fprintf(stderr,&quot;logerr: %s\n&quot;,pMsg);
 }
 </pre>
 <p>By default stdout and stderr will appear in Chrome&#8217;s stdout and stderr stream
 but they can also be redirected as described below.</p>
-<h4 id="redirecting-output-to-log-files">Redirecting output to log files</h4>
+<p>The stderr from the process is by default visible in the terminal that launched
+chrome (at least on mac and linux). Be sure that when you launch chrome it
+doesn&#8217;t attach to an existing instance. One simple way to do this is to pass a
+new directory to chrome as your user data directory (<code>chrome
+--user-data-dir=&lt;newdir&gt;</code>). It&#8217;s also possible to redirect the NaCl&#8217;s stderr to
+other places such as, for example, <a class="reference internal" href="#redirecting-output-to-log"><em>log files</em></a>.</p>
+<h4 id="redirecting-output-to-log-files"><span id="redirecting-output-to-log"></span>Redirecting output to log files</h4>
 <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>
 </ul>
 <p>There is another variable, <code>NACLLOG</code>, that you can use to redirect Native
 Client&#8217;s internally-generated messages. This variable is set to stderr by
 default; you can redirect these messages to an output file by setting the
 variable as follows:</p>
 <ul class="small-gap">
 <li><code>NACLLOG=c:\nacl.log</code></li>
 </ul>
+<p>The exception to this is the <a class="reference internal" href="/native-client/devguide/coding/nacl_io.html"><em>nacl_io library</em></a> which
+logs directly to the stderr stream.</p>
 <aside class="note">
 <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>
 <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>
 <pre class="prettyprint">
@@ skipping 29 matching lines @@
 metadata, which we need for debugging. In this section we&#8217;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 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&#8217; values when
-debugging (this is more of a problem with the PNaCl/LLVM toolchain than
-with GCC).</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&#8217; values when debugging (this is more of a
+problem with the PNaCl/LLVM toolchain than with GCC).</p>
 <p>Once you have built a non-stable debug copy of the pexe, list the URL of
 that copy in your application&#8217;s manifest file:</p>
 <pre class="prettyprint">
 {
   &quot;program&quot;: {
     &quot;portable&quot;: {
       &quot;pnacl-translate&quot;: {
         &quot;url&quot;: &quot;release_version.pexe&quot;,
         &quot;optlevel&quot;: 2
       },
       &quot;pnacl-debug&quot;: {
         &quot;url&quot;: &quot;debug_version.bc&quot;,
         &quot;optlevel&quot;: 0
       }
     }
   }
 }
 </pre>
 <p>Copy the <code>debug_version.bc</code> and <code>nmf</code> files to the location that
 your local web server serves files from.</p>
 <p>When you run Chrome with <code>--enable-nacl-debug</code>, Chrome will translate
 and run the <code>debug_version.bc</code> instead of <code>release_version.pexe</code>.
 Once the debug version is loaded, you are ready to <a class="reference internal" href="#running-nacl-gdb"><em>run nacl-gdb</em></a></p>
-<p>Whether you publish the NMF file containing the debug URL to the release
-web server, is up to you. One reason to avoid publishing the debug URL
-is that it is only guaranteed to work for the Chrome version that matches
-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>
+<p>Whether you publish the NMF file containing the debug URL to the
+release web server, is up to you. One reason to avoid publishing the
+debug URL is that it is only guaranteed to work for the Chrome version
+that matches 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>
 <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
 this step if you are using the GCC toolchain, or if you are using
 pepper 35 or later.)</p>
 <ul class="small-gap">
 <li>Firstly, 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.</li>
-<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>
+<li><p class="first">Secondly, use <code>pnacl-translate</code> to convert your <code>pexe</code> to one or more</p>
+<p><code>nexe</code> files.  For example:</p>
 <pre>
 nacl_sdk/pepper_&lt;version&gt;/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_&lt;version&gt;/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>.
@@ skipping 247 matching lines @@
 debugging, close the Chrome window and type <code>q</code> to quit gdb.</p>
 <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
 Pepper plugin (sometimes referred to as a &#8220;<a class="reference external" href="http://www.chromium.org/nativeclient/getting-started/getting-started-background-and-basics#TOC-Trusted-vs-Untrusted">trusted</a>&#8221;
 or &#8220;in-process&#8221; plugin).  Pepper plugins (.DLL files on Windows; .so files on
 Linux; .bundle files on Mac) are loaded directly in either the Chrome renderer
 process or a separate plugin process, rather than in Native Client. Building a
 module as a trusted Pepper plugin allows you to use standard debuggers and
 development tools on your system, but when you&#8217;re finished developing the
-plugin, you need to port it to Native Client (i.e., build the module with one
-of the toolchains in the NaCl SDK so that the module runs in Native Client).
-For details on this advanced development technique, see <a class="reference external" href="http://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin">Debugging a Trusted
-Plugin</a>.
+plugin, you need to port it to Native Client (i.e., build the module with one of
+the toolchains in the NaCl SDK so that the module runs in Native Client).  For
+details on this advanced development technique, see <a class="reference external" href="http://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-a-trusted-plugin">Debugging a Trusted Plugin</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>
 
 {{/partials.standard_nacl_article}}