Debugging
=========

With *justbuild* striving to ensure that only our own project's code is needed
to be available locally, and not any of our dependencies (especially in
conjunction with our [serve service](./just-serve.md)) or any on-the-fly patches
or generated files, it might seem that debugging is not a straight-forward
endeavor. However, *justbuild* always knows exactly what source files are needed
to build a target and therefore they can be staged locally and made available to
a debugger, such as `gdb(1)`.

In the following we will show how to use the `["CC", "install-with-deps"]` rule
to stage all the needed sources for debugging a program with `gdb(1)`.
As example we use the *hello_world* program employing high-level target caching
from the section on
[*Building Third-party dependencies*](./third-party-software.md), which depends
on the open-source project [fmtlib](https://github.com/fmtlib/fmt).

The debugging process
---------------------

The first step is to define a set of debugging defaults (toolchain and compile
flags) for our example project. This can be done by extending the existing
`tutorial-defaults/CC/TARGETS` file as

``` {.jsonc srcname="tutorial-defaults/CC/TARGETS"}
{ "defaults":
  { "type": ["CC", "defaults"]
  , "CC": ["cc"]
  , "CXX": ["c++"]
  , "ADD_COMPILE_FLAGS": ["-O2", "-Wall"]
  , "ADD_DEBUGFLAGS": ["-O2", "-Wall", "-g"]
  , "AR": ["ar"]
  , "DWP": ["dwp"]
  , "PATH": ["/bin", "/usr/bin"]
  }
}
```

This states that when in debug mode a different set of C/C++ flags should be
used, in this case the ones from release mode plus the `-g` flag to generate
debug information for `gdb(1)`. As this updated `TARGETS` file is under version
control, we need to commit the changes:

``` sh
$ git add tutorial-defaults
$ git commit -m "update compile flags for debugging"
[master 642f739] update compile flags for debugging
 1 file changed, 1 insertions(+)
```

Now we need to configure the actual target we want to debug. The `TARGETS` file
of our *hello-world* program currently contains only the release version, so we
need to add a new target, configured in debug mode.

``` {.jsonc srcname="TARGETS"}
...
, "helloworld-debug":
  { "type": "configure"
  , "target": "helloworld"
  , "config": {"type": "'", "$1": {"DEBUG": {"USE_DEBUG_FISSION": false}}}
  }
...
```

This describes the debug version of *hello-world*, configured by setting the
`"DEBUG"` map to enable regular (non-fission) debug mode, which in turn will
instruct the updated toolchain defaults, which honor the `"DEBUG"` argument, to
compile all actions with the `"-g"` flag.

To actually collect the artifacts needed to run the debugger, we use the
`["CC", "install-with-deps"]` rule, contained in the `rules-cc` repository.

``` {.jsonc srcname="TARGETS"}
...
, "helloworld-debug staged":
  { "type": ["@", "rules", "CC", "install-with-deps"]
  , "targets": ["helloworld-debug"]
  }
...
```

Now this target can be installed to a location of our choice provided by the
`-o` argument.

``` sh
$ just-mr install "helloworld-debug staged" -o .ext/debug
INFO: Performing repositories setup
INFO: Found 5 repositories involved
INFO: Setup finished, exec ["just","install","-C","...","helloworld-debug staged","-o",".ext/debug"]
INFO: Requested target is [["@","tutorial","","helloworld-debug install"],{}]
INFO: Analysed target [["@","tutorial","","helloworld-debug install"],{}]
INFO: Export targets found: 0 cached, 1 uncached, 0 not eligible for caching
INFO: Discovered 7 actions, 0 tree overlays, 3 trees, 0 blobs
INFO: Building [["@","tutorial","","helloworld-debug install"],{}].
INFO: Processed 7 actions, 0 cache hits.
INFO: Artifacts can be found in:
        /tmp/tutorial/.ext/debug/bin/helloworld [5f0ce4ed97000af42902c41f9d3b7d51343534a6:1570896:x]
        /tmp/tutorial/.ext/debug/include/fmt [3a5cb60e63f7480b150fdef0883d7a76e8a57a00:464:t]
        /tmp/tutorial/.ext/debug/include/greet/greet.hpp [63815ae1b5a36ab29efa535141fee67f3b7769de:53:f]
        /tmp/tutorial/.ext/debug/work/fmt [3a5cb60e63f7480b150fdef0883d7a76e8a57a00:464:t]
        /tmp/tutorial/.ext/debug/work/format.cc [ecb8cc79a6e9ff277db43876a11eccde40814ece:5697:f]
        /tmp/tutorial/.ext/debug/work/greet/greet.cpp [8c56239aabd4e23b9d170333d03f222e6938dcef:115:f]
        /tmp/tutorial/.ext/debug/work/greet/greet.hpp [63815ae1b5a36ab29efa535141fee67f3b7769de:53:f]
        /tmp/tutorial/.ext/debug/work/main.cpp [92f9b55228774b3d3066652253499395d9ebef31:76:f]
        /tmp/tutorial/.ext/debug/work/os.cc [04b4dc506005d38250803cfccbd9fd3b6ab30599:10897:f]
INFO: Backing up artifacts of 1 export targets
```

To now debug the *helloworld* executable, we simply need to switch to the
specified directory and run `gdb(1)`.

``` sh
$ cd .ext/debug
$ gdb bin/helloworld
```

This works out-of-the-box specifically because our tool keeps track of the
logical staging of the artifacts (from direct and transitive dependencies) of
targets, meaning it can easily mirror this staging in the install folder, thus
ensuring a debugger finds all the symbols in the places it looks for by default.
As such, this install directory can also be directly provided to an IDE (such as
VSCode) as search location for debug symbols.

Finally, note that not only the artifacts of the first-party library `greet` get
staged, but also the artifacts of the third-party dependency `fmtlib`. This is
due to the fact that the `"fmtlib"` export target is already configured (see its
`TARGETS` file) to inherit the `"DEBUG"` flag from the environment, meaning that
the `true` value set by the `"helloworld-debug"` target gets honored.
In general, we recommend that export targets always allow the `"DEBUG"` flag
through, specifically to ensure consumers have access to and can build the
target library also in debug mode.