Second batch of corrections for incorrect paths.

native_client_sdk/src/doc/devguide/devcycle/debugging.rst

 .. _devcycle-debugging:
 
 #########
 Debugging
 #########
 
 This document describes tools and techniques you can use to debug, monitor,
 and measure your application's performance.
 
 .. contents:: Table Of Contents
   :local:
   :backlinks: none
   :depth: 3
 
 Diagnostic information
 ======================
 
 Viewing process statistics with the task manager
 ------------------------------------------------
 
 You can use Chrome's Task Manager to display information about a Native Client
 application:
 
 #. Open the Task Manager by clicking the menu icon |menu-icon| and choosing
    **Tools > Task manager**.
 #. When the Task Manager window appears, verify that the columns displaying
    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.
 
-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
-|puzzle|) and begins with the text "Native Client module" followed by the URL
-of its manifest file.
+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 |puzzle|) and begins with the text "Native Client module:" followed by the
+URL of its manifest file.
 
 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.
 
 Controlling the level of Native Client error and warning messages
 -----------------------------------------------------------------
 
 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 `environment variables
 <http://en.wikipedia.org/wiki/Environment_variable>`_:
 
-* NACL_PLUGIN_DEBUG=1
-* NACL_SRPC_DEBUG=[1-255] (use a higher number for more verbose debug output)
-* NACLVERBOSITY=[1-255]
+* ``NACL_PLUGIN_DEBUG=1``
+* ``NACL_SRPC_DEBUG=[1-255]`` (use a higher number for more verbose debug
+  output)
+* ``NACLVERBOSITY=[1-255]``
 
 Basic debugging
 ===============
 
 Writing messages to the JavaScript console
 ------------------------------------------
 
-You can send messages from your C/C++ code to JavaScript using the PostMessage
-call in the :doc:`Pepper messaging system <../coding/message-system>`. When the
-JavaScript code receives a message, its message event handler can call
-`console.log() <https://developer.mozilla.org/en/DOM/console.log>`_ to write
-the message to the JavaScript `console </devtools/docs/console-api>`_ in
-Chrome's Developer Tools.
+You can send messages from your C/C++ code to JavaScript using the 
+``PostMessage()`` call in the :doc:`Pepper messaging system 
+<../coding/message-system>`. When the JavaScript code receives a message, its 
+message event handler can call `console.log() 
+<https://developer.mozilla.org/en/DOM/console.log>`_ to write the message to the
+JavaScript `console </devtools/docs/console-api>`_ in Chrome's Developer Tools.
 
 Debugging with printf
 ---------------------
 
 Your C/C++ code can perform inline printf debugging to stdout and stderr by
 calling fprintf() directly, or by using cover functions like these:
 
 .. naclcode::
 
   #include <stdio.h>
   void logmsg(const char* pMsg){
     fprintf(stdout,"logmsg: %s\n",pMsg);
   }
   void errormsg(const char* pMsg){
     fprintf(stderr,"logerr: %s\n",pMsg);
   }
 
 By default stdout and stderr will appear in Chrome's stdout and stderr stream
 but they can also be redirected as described below.
 
+
 Redirecting output to log files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can redirect stdout and stderr to output files by setting these environment variables:
+You can redirect stdout and stderr to output files by setting these environment
+variables:
 
 * ``NACL_EXE_STDOUT=c:\nacl_stdout.log``
 * ``NACL_EXE_STDERR=c:\nacl_stderr.log``
 
 There is another variable, ``NACLLOG``, that you can use to redirect Native
 Client'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:
 
 * ``NACLLOG=c:\nacl.log``
 
 .. Note::
   :class: note
 
-  **Note:** 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
-  ``--no-sandbox`` flag.  You must also be careful that each variable points to
-  a different file.
+  **Note:** 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 ``--no-sandbox`` flag.  You must also be careful that each variable points
+  to a different file.
 
 Redirecting output to the JavaScript console
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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:
 
-#. Set the NACL_EXE_STDOUT and NACL_EXE_STDERR environment variables as
+#. Set the ``NACL_EXE_STDOUT`` and ``NACL_EXE_STDERR`` environment variables as
    follows:
 
-   * NACL_EXE_STDOUT=DEBUG_ONLY:dev://postmessage
-   * NACL_EXE_STDERR=DEBUG_ONLY:dev://postmessage
+   * ``NACL_EXE_STDOUT=DEBUG_ONLY:dev://postmessage``
+   * ``NACL_EXE_STDERR=DEBUG_ONLY:dev://postmessage``
 
-   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.
+   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.
 
 #. Register a JavaScript handler to receive messages from your Native Client
    module:
 
    .. naclcode::
 
      <div id="nacl_container">
        <script type="text/javascript">
          var container = document.getElementById('nacl_container');
          container.addEventListener('message', handleMessage, true);
@@ skipping 13 matching lines @@
      }
 
    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.
 
    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
+   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).
 
 Logging calls to Pepper interfaces
 ----------------------------------
 
 You can log all Pepper calls your module makes by passing the following flags
 to Chrome on startup::
 
@@ skipping 19 matching lines @@
 link it to the running code.
 
 .. _using_gdb:
 
 Debugging with nacl-gdb
 -----------------------
 
 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 `gdb
 <http://www.gnu.org/software/gdb/>`_, and is located at
-``toolchain/<platform>_x86_newlib/bin/x86_64-nacl-gdb`` (where *<platform>*
-is the platform of your development machine: ``win``, ``mac``, or
+``pepper_<version>/toolchain/<platform>_x86_newlib/bin/x86_64-nacl-gdb`` (where
+*<platform>* is the platform of your development machine: ``win``, ``mac``, or
 ``linux``).
 
 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,
 ``i686-nacl-gdb`` is an alias for ``x86_64-nacl-gdb``, and the ``newlib``
 and ``glibc`` toolchains both contain the same version of GDB.
 
 .. _debugging_pnacl_pexes:
 
-Debugging PNaCl pexes (with Pepper 35+)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Debugging PNaCl pexes (Pepper 35 or later)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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 **before** running
 ``pnacl-finalize``. The ``pnacl-finalize`` tool converts LLVM bitcode
 to the stable PNaCl bitcode format, but it also strips out debug
 metadata, which we need for debugging. In this section we'll give the
 LLVM bitcode file a ``.bc`` file extension, and the PNaCl bitcode file
 a ``.pexe`` file extension. The actual extension should not matter, but
 it helps distinguish between the two types of files.
 
 **Note** 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.
+you will see an error message in the JavaScript console.
 
 Also, make sure you are passing the ``-g`` :ref:`compile option
 <compile_flags>` to ``pnacl-clang`` to enable generating debugging info.
 You might also want to omit ``-O2`` from the compile-time and link-time
 options, otherwise GDB not might be able to print variables' values when
 debugging (this is more of a problem with the PNaCl/LLVM toolchain than
 with GCC).
 
 Once you have built a non-stable debug copy of the pexe, list the URL of
 that copy in your application's manifest file:
@@ skipping 43 matching lines @@
   <compile_flags>` to ``pnacl-clang`` to enable generating debugging info.
   You might also want to omit ``-O2`` from the compile-time and link-time
   options.
 
 * Secondly, use ``pnacl-translate`` to convert your ``pexe`` to one or more
   ``nexe`` files.  For example:
 
   .. naclcode::
     :prettyprint: 0
 
-    <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_ROOT>/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_ROOT>/pepper_<version>/toolchain/win_pnacl/bin/pnacl-translate \
+      --allow-llvm-bitcode-input hello_world.pexe -arch x86-64 \
+      -o hello_world_x86_64.nexe
 
   For this, use the non-finalized ``pexe`` file produced by
   ``pnacl-clang``, not the ``pexe`` file produced by ``pnacl-finalize``.
   The latter ``pexe`` has debugging info stripped out.  The option
   ``--allow-llvm-bitcode-input`` tells ``pnacl-translate`` to accept a
   non-finalized ``pexe``.
 
 * Replace the ``nmf`` :ref:`manifest file <manifest_file>` that points to
   your ``pexe`` file with one that points to the ``nexe`` files.  For the
   example ``nexe`` filenames above, the new ``nmf`` file would contain:
@@ skipping 102 matching lines @@
      in the directory where that page is located).
 
 #. Navigate to your application's page in Chrome. (You don't need to do this if
    you specified a URL when you launched Chrome in the previous step.) Chrome
    will start loading the application, then pause and wait until you start
    nacl-gdb and run the ``continue`` command.
 
 #. Go to the directory with your source code, and run nacl-gdb from there. For
    example::
 
-     cd <NACL_SDK_ROOT>/examples/hello_world_gles
-     <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb
+     cd <NACL_SDK_ROOT>/pepper_<version>/examples/demo/drive

[binji, 2014/08/20 19:09:34]

same as before, NACL_SDK_ROOT in the code is expected to already have
pepper_<version>. Maybe we should use a different name here.

[jpmedley, 2014/08/20 20:15:01]

Somebody was worried that nacl_sdk/ would change. Probably not a good trade-off
now that you mention it.

+     <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb
 
    The debugger will start and show you a gdb prompt::
 
      (gdb)
 
-#. For debugging PNaCl pexes run the following gdb command lines
-   (skip to the next item if you are using NaCl instead of PNaCl)::
+#. Run the debugging command lines.
 
+   **For PNaCl**::
+   
      (gdb) target remote localhost:4014
      (gdb) remote get nexe <path-to-save-translated-nexe-with-debug-info>
      (gdb) file <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>
 
-#. For NaCl nexes, run the following commands from the gdb command line::
-
+   **For NaCl**::
+   
      (gdb) target remote localhost:4014
      (gdb) nacl-manifest <path-to-your-.nmf-file>
      (gdb) remote get irt <path-to-save-NaCl-integrated-runtime>
      (gdb) nacl-irt <path-to-saved-NaCl-integrated-runtime>
 
 #. The command used for PNaCl and NaCl are described below:
 
    ``target remote localhost:4014``
      Tells the debugger how to connect to the debug stub in the Native Client
      application loader. This connection occurs through TCP port 4014 (note
@@ skipping 17 matching lines @@
 
    ``remote get irt <path>``
      This saves the Native Client Integrated Runtime (IRT). Normally,
      the IRT is located in the same directory as the Chrome executable,
      or in a subdirectory named after the Chrome version. For example, if
      you're running Chrome canary on Windows, the path to the IRT typically
      looks something like ``C:/Users/<username>/AppData/Local/Google/Chrome
      SxS/Application/23.0.1247.1/nacl_irt_x86_64.nexe``.
      The ``remote get irt <path>`` saves that to the current working
      directory so that you do not need to find where exactly the IRT
-     is stored alongside Chrome.
+     is stored.
 
    ``nacl-irt <path>``
      Tells the debugger where to find the Native Client Integrated Runtime
      (IRT). ``<path>`` can either be the location of the copy saved by
      ``remote get irt <path>`` or the copy that is installed alongside Chrome.
 
    A couple of notes on how to specify path names in the nacl-gdb commands
    above:
 
    * You can use a forward slash to separate directories on Linux, Mac, and
      Windows. If you use a backslash to separate directories on Windows, you
      must escape the backslash by using a double backslash "\\" between
      directories.
    * If any directories in the path have spaces in their name, you must put
      quotation marks around the path.
 
    As an example, here is a what these nacl-gdb commands might look like on
    Windows::
 
      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_ROOT>/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"
 
    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::
 
-     <NACL_SDK_ROOT>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb -x <nacl-script-file>
+     <NACL_SDK_ROOT>/pepper_<version>/toolchain/win_x86_newlib/bin/x86_64-nacl-gdb -x <nacl-script-file>
 
    If nacl-gdb connects successfully to Chrome, it displays a message such as
    the one below, followed by a gdb prompt::
 
      0x000000000fc00200 in _start ()
      (gdb)
 
    If nacl-gdb can't connect to Chrome, it displays a message such as
    "``localhost:4014: A connection attempt failed``" or "``localhost:4014:
    Connection timed out.``" If you see a message like that, make sure that you
@@ skipping 75 matching lines @@
 <http://www.chromium.org/nativeclient>`_ that describe how to do profiling on
 `64-bit Windows
 <https://sites.google.com/a/chromium.org/dev/nativeclient/how-tos/profiling-nacl-apps-on-64-bit-windows>`_
 and `Linux
 <http://www.chromium.org/nativeclient/how-tos/limited-profiling-with-oprofile-on-x86-64>`_
 machines.
 
 
 .. |menu-icon| image:: /images/menu-icon.png
 .. |puzzle| image:: /images/puzzle.png