| Index: native_client_sdk/src/doc/devguide/devcycle/debugging.rst
|
| diff --git a/native_client_sdk/src/doc/devguide/devcycle/debugging.rst b/native_client_sdk/src/doc/devguide/devcycle/debugging.rst
|
| index 14cba307664a14e4c0b86c992ed75a562daad070..326ac22b6f379652e7634222c1c67d138a937e59 100644
|
| --- a/native_client_sdk/src/doc/devguide/devcycle/debugging.rst
|
| +++ b/native_client_sdk/src/doc/devguide/devcycle/debugging.rst
|
| @@ -27,15 +27,15 @@ application:
|
| 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
|
| @@ -52,9 +52,10 @@ 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
|
| ===============
|
| @@ -62,12 +63,12 @@ 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
|
| ---------------------
|
| @@ -88,10 +89,12 @@ calling fprintf() directly, or by using cover functions like these:
|
| 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``
|
| @@ -106,10 +109,10 @@ variable as follows:
|
| .. 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
|
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| @@ -119,15 +122,15 @@ 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:
|
| @@ -161,7 +164,7 @@ these steps:
|
| 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).
|
| @@ -201,8 +204,8 @@ 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,
|
| @@ -212,8 +215,8 @@ 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
|
| @@ -229,7 +232,7 @@ 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.
|
| @@ -293,10 +296,12 @@ pepper 35 or later.)
|
| .. 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/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
|
|
|
| For this, use the non-finalized ``pexe`` file produced by
|
| ``pnacl-clang``, not the ``pexe`` file produced by ``pnacl-finalize``.
|
| @@ -419,24 +424,25 @@ Follow the instructions below to debug your module with nacl-gdb:
|
| #. 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/pepper_<version>/examples/demo/drive
|
| + nacl_sdk/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>
|
| @@ -474,7 +480,7 @@ Follow the instructions below to debug your module with nacl-gdb:
|
| 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
|
| @@ -495,13 +501,13 @@ Follow the instructions below to debug your module with nacl-gdb:
|
| 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/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/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::
|
|
|