doc: Completed debug docs with how the debugging mode works w.r.t. the debugging server
@@ -3,6 +3,11 @@ Debugging and Coverage information
.. _gdb-ref:
+.. note::
+
+ The following section assumes you have the relevant debugging server
+ installed on your server. For instance, if you're debugging with gdb,
+ you'll need to have ``gdbserver`` installed and available in your PATH.
Debugging with GDB
------------------
@@ -11,10 +16,16 @@ In one terminal do:
.. code-block:: bash
- $ ./simple.c.bin --debug
- Process simple.c.bin created; pid = 20803
+ $ ./test --debug=gdb
+ Process test created; pid = 20803
Listening on port 1234
+.. note::
+
+ If no argument is passed to --debug, criterion will fall back to the
+ appropriate debugging server for your compiler: gdbserver with gcc,
+ lldb-server with clang, windbg with msvc.
+
In another terminal connect to this debug session:
.. code-block:: bash
@@ -35,7 +46,7 @@ After ``continue`` the first test is run:
Remote debugging from host 127.0.0.1
[RUN ] misc::failing
- [----] /media/data/devel/Criterion/samples/simple.c:4: Assertion failed: The expression 0 is false.
+ [----] /path/to/test.c:4: Assertion failed: The expression 0 is false.
[FAIL] misc::failing: (0,00s)
Child exited with status 0
@@ -44,7 +55,7 @@ And a new process is created for the next test:
.. code-block:: bash
- Process /media/data/devel/Criterion/build/samples/simple.c.bin created; pid = 26414
+ Process /path/to/test created; pid = 26414
Listening on port 1234
Connect your remote debugger to this test with ``remote target localhost:1234``
@@ -52,6 +63,37 @@ and run the test with ``continue``
To use a different port use ``--debug --debug-transport=<protocol>:<port>``
+Debugging with an unsupported debugger
+--------------------------------------
+
+If you want to use a debugger that criterion doesn't natively support,
+you may use the ``idle`` debugging mode: In this mode, the PID of the
+test will be printed, and the test itself will suspend all operations
+until a debugger resumes it.
+
+.. code-block:: bash
+
+ $ ./test --debug=idle
+ <snip>
+ [----] misc::failing: Started test has PID 30587.
+
+On unices, once attached, simply signal the process with SIGCONT to resume
+it.
+
+.. code-block:: bash
+
+ $ sudo gdb ./test -p 30587
+ Attaching to process 30587
+ 0x00007f9ea3780f3d in raise () from /usr/lib/libpthread.so.0
+ (gdb) signal SIGCONT
+ Continuing with signal SIGCONT.
+
+ Program received signal SIGCONT, Continued.
+ 0x00007f9ea3780f5f in raise () from /usr/lib/libpthread.so.0
+ (gdb) c
+ ...
+ (gdb) q
+
.. _coverage-ref:
Coverage of Criterion tests
