Debugging Buck2

This page contains generic debugging advice for developers of Buck2; this advice is descriptive (based on what people usually do today) not prescriptive (you're welcome to come up with your own ideas).

Normal logic bugs

We usually debug normal logic bugs by looking at the code, writing finer grained tests, or standard println! debugging.

Use of a traditional debugger is not common, but it probably works using standard tools in OSS.

Buck2 has many commands to retrieve information about the build, particularly buck2 log, buck2 audit and buck2 debug, which can be helpful.

Running builds

./buck2.py <command> builds buck2 from source and runs <command> using that buck2. The command is run in a different isolation dir, to prevent the command from stepping on your existing buck daemon. This means large builds will get no cache hits and be very slow.

Alternatively, buck2 build @fbcode//mode/opt fbcode//buck2:buck2 --out /tmp/buck2 to build buck2 on its own. Then, use /tmp/buck2 to run builds in a different checkout of fbsource from the one you're editing code in.

Logging

buck2 emits most of its logs in a structured form that is best interacted with via buck2 logs commands.

We additionally have some tracing logging, though it's sparse and not in very widespread use. Use the BUCK_LOG environment variable to enable trace logging. Requires daemon restart:

buck2 kill
BUCK_LOG=module_name=trace buck2 <command>
# Example
BUCK_LOG=starlark=trace buck2 uquery cell//path/to:target
BUCK_LOG=buck2_execute_impl::materializers=trace buck2 build cell//path/to:target

Or use ./buck2.py instead of buck2 to run local changes

See tracing-subscriber docs for filter syntax.