One of the aims of the Mandrel team is to pass on knowledge that would enable Quarkus developers to better debug native issues. To do this, we have been working on training material that we're hoping to deliver in the near future.
We're now at a stage that we feel the training material is ready to be part of the Quarkus upstream documentation. We think it'd be best added as a tutorial that developers can run through at their own pace.
Given the complexity of issues, and differences in toolchain compared to debugging Java/JVM issues, we consider the audience for the tutorial to be advanced Quarkus users.
Please note that the tutorial is not a generic GraalVM native-image tutorial. Instead, it focuses exclusively on working with Quarkus applications from the start, so the users don't need to interact with native-image binary directly. The tutorial builds Quarkus native executables in container using Mandrel.
The agenda for the tutorial looks something like this:
First Native Executable
Call Tree Reports
Used Packages/Classes/Methods Reports
Build-time vs Run-time Initialization
Profile Runtime Behaviour
Debugging Native Crashes
While we worked on this material, we also also compiled a list of FAQs related to the tutorial and Quarkus Native applications. Where could we add those upstream? They could go into the tutorial itself, or maybe a separate guide, e.g. https://quarkus.io/guides/native-faqs
? Here's the list of FAQs we have so far:
Q. Why is generating a native executable slow?
Q. Why is runtime performance of natives slower compared to JVM mode?
Q. Why are native executables “big”?
Q. What version of Mandrel was used to generate a binary?
Q. How do I enable GC logging in native executables?
Q. Can I get a heap dump of a native executable? e.g. if it runs out of memory
Q. Can I use JFR to profile the native executable at runtime?
Q. Can I create native executables for Windows?
Q. Can I follow this tutorial if I’m running MacOS or Windows?
Q. Generating flame graphs is slow, or produces errors, what can I do?
Q. I think I’ve found a bug in native-image, how can I debug it with the IDE?
Q. Can I use JFR/JMC to debug to profile native binaries?
Once the locations have been agreed, I'll work on the PR and we can refine the content there.