[tracker/sam/functional-tests-quiet: 18/22] Add HACKING.md

[Sam Thursfield <sthursfield src gnome org>]

commit 5173d9a524d5f4111e020ba9c402ec02075f1d4c
Author: Sam Thursfield <sam afuera me uk>
Date:   Thu Aug 29 17:30:23 2019 +0300

    Add HACKING.md
    
    This talks about how to enable different kinds of logging output from
    the functional tests, now that the previous commit has introduced some
    sanity into the logging.
    
    Attaching debugger is also discussed.

 HACKING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 README.md  |  2 +-
 2 files changed, 45 insertions(+), 1 deletion(-)
---
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 000000000..e8d3dcf62
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,44 @@
+# Logging
+
+The following environment variables control logging from Tracker daemons:
+
+  * `TRACKER_VERBOSITY`: takes a value of 1, 2 or 3 and causes increasing
+    amounts of log output from Tracker code to be written to stdout.
+  * `G_MESSAGES_DEBUG`: controls log output from GLib-based libraries that
+    are used in the Tracker process. Use `G_MESSAGES_DEBUG=all` for maximal
+    log output.
+
+Internally, Tracker will set `G_MESSAGES_DEBUG=Tracker` if `TRACKER_VERBOSITY`
+is set and `G_MESSAGES_DEBUG` is not set, to enable printing of its own log
+messages to stdout.
+
+You can set these variables when using `tracker-sandbox`, and when running the
+Tracker test suite. Note that Meson will not print log output from tests by
+default, use `meson test --verbose` or `meson test --print-errorlogs` to
+enable.
+
+The functional tests understand an additional variable, `TRACKER_TESTS_VERBOSE`
+with can be set to `1` or `yes` to see detailed logging from the test harness
+itself, and full log output from the internal D-Bus daemon. By default, these
+tests filter output from the D-Bus daemon to only show log messages from
+Tracker processes. Anything written directly to stdout, for example by
+`g_print()` or by the dbus-daemon itself, will not be displayed unless
+`TRACKER_TESTS_VERBOSE` is set.
+
+# Attaching a debugger to Tracker daemons
+
+Tracker daemons are not started directly. Instead they are started by the D-Bus
+daemon by request. When using tracker-sandbox or the functional-tests, it's
+difficult to start the daemon manually under `gdb`.
+
+Instead, we recommend adding a 10 second timeout at the top of the daemon's
+main() function. In Vala code, try this:
+
+    print("Pausing to attach debugger. Run: gdb attach %i\n", Posix.getpid());
+    Posix.usleep(10 * 1000 * 1000);
+    print("Waking up again\n");
+
+Run the test, using the `meson build --timeout-multiplier=10000`
+option to avoid your process being killed by the test runner. When you see
+the 'Pausing' message, run the `gdb attach``command in another terminal within
+10 seconds.
diff --git a/README.md b/README.md
index f1ec0f855..c94639b87 100644
--- a/README.md
+++ b/README.md
@@ -131,4 +131,4 @@ interactive shell inside the sandbox. From here you can use debugging tools
 such as GDB.
 
 For more information about developing Tracker, look at
-https://wiki.gnome.org/Projects/Tracker.
+https://wiki.gnome.org/Projects/Tracker and HACKING.md.