Debugging

Debugging

Note

This section is in progress, and needs instructions and examples for using "debug" from container builds using Earthly.

There are two targets for debugging:

• Your code
• Your build

Wait, what? What does it mean to "debug" your build?

Debugging your build

It is unusually challenging to debug your build in the same way as your code. How do you "step through" your build in a debugger or IDE? Gradle is programmed in Groovy or Kotlin, and Maven is purely declarative in XML (or other structured data via build plugins).

So the typical fallback for debugging builds is to:

1. Capture output from the build.
2. Diff the "old" and "new" outputs contrasting changes to your build.

Building with a container shines here! While changing your build (especially versions of tooling and dependencies), you can directly compare your local "direct" build (./gradlew build and ./mvn verify) against what CI does using Earthly or similar containerized build tools. This avoids the problem of "my build works, but CI fails" (modulo environment issues such as database connectivity).

Capturing build output

Typically this comes down to two main approaches:

• Build on the command line and capture output, for example:

  $ ./gradlew build 2>&1 | tee old.out  # Or: ./mvn verify
  # Make changes to the build script or configuration
  $ ./gradlew build 2>&1 | tee new.out  # Or: ./mvn verify
  

• Build in an IDE or a command line lacking the tee program. Then you copy/paste the output to a file.

Comparing build outputs between changes

A frequent source of false positive changes is measuring time, typically either build run times (duration times; "Time elapsed" in Maven, for example), or timestamps in logging (absolute times).

When possible, you should disable outputs from the build unless warnings or errors. And your tests should not print timestamps unless you are specifically testing logging or similar features. Otherwise, you will need to filter your build outputs when comparing old/new builds across changes.

Tips

TODO: Placeholder section

Going further

TODO: Placeholder section