This directory contains all test applications and libraries developed for testing and debugging the debug agent. This means utilities for things like spawning processes, keeping threads looping and having a .so that is also linked to generated binary.
Every new functionality that is not meant to be consumed by the end users but rather by the developers of zxdb should put that code in here.
There are some constructs in this directory:
This suite of programs and helpers are mostly packed as part of the “debug_agent_helpers” package, which is defined in src/developer/debug/debug_agent/BUILD.gn. That package does all the job of adding the correct dependencies and doing all the packaging/meta files managing.
The process to add a new executable is to:
Add a new executble to src/developer/debug/debug_agent/test_data/BUILD.gn
Add it as a dependency to the :helpers_executable
group within the test_data BUILD.gn.
In the debug agent BUILD.gn (src/developer/debug/debug_agent/BUILD.gn), you need to specify that the debug_agent_helpers package exports this new executable. For that, look for the
binaries` array and add the exported name of the executable in (1) and add it there.
If there is a .cmx file (meant to be run as a component), remember to also add the meta file translation in there. See limbo_caller
or test_suite
as an example of a test executable that also can get called as a component.
If your .cmx file requires the fuchsia.kernel.RootJob service, update the policy file at //src/security/policy/root_job_allowlist_eng.txt file, otherwise it will fail to launch at runtime with a mysterious error like the one below (and nothing in the system log!):
fuchsia-pkg://fuchsia.com/...#meta/your.cmx: failed to create component (8)
The “Debug Agent Test Suite” is a more elaborate program that is used to create more complicated scenerios, such as adding several watchpoints on another process, send multiple channel calls, etc.
To build an update and run:
fx run debug_agent_test_suite.cmx
The suite has CLI instructions about to execute the different test cases. Each test case is documented so you can refer to the source to see what each test case is supposed to do.
The test suite has a set of helpers (test_suite_helpers.h) that facilitate the creation of test cases (hence the name test suite). Normally if more intricate examples need to be written to try out a behaviour, it's very probable that adding it to the test suite is the easiest way to go about it developing and deploying it, as adding a new test case is very easy (see the last part of test_suite.cc).
The test suite can be run directly (/pkgfs/packages/debug_agent_helpers/bin/test_suite) or as a component (run debug_agent_test_suite.cmx).