Self-documenting Makefiles - by Julio Merino
Make, as arcane as a build tool can be, may still be a good first fit for certain scenarios. “Heresy!”, you say, as you hear a so-called “Bazel expert” utter these words.
The specific problem I’m facing is that I need to glue together the NetBSD build system, a quilt patch set, EndBASIC’s Cargo-based Rust build, and a couple of QEMU invocations to produce a Frankenstein disk image for a Raspberry Pi. And the thing is: Make allows doing this sort of stitching with relative ease. Sure, Make is not the best option because the overall build performance is “meh” and because incremental builds are almost-impossible to get right… but adopting Bazel for this project would be an almost-infinite time sink.
Anyway. When using Make in this manner, you often end up with what’s essentially a “command dispatcher” and, over time, the number of commands grows and it’s hard to make sense of which one to use for what. Sure, you can write a README.md with instructions, but I guarantee you that the text will get out of sync faster than you can read this article. There is a better way, though.
What if we could provide a make help command that showed an overview of the project’s “build interface”? And what if we could embed such information inside the Makefiles themselves, close to the entities that they document? This idea is neither new nor mine, and it has been written about before by different people. However, I bet that most of you haven’t heard about it before so it’s worth for me to repeat it. And I think that that my solution is a bit more comprehensive than others I’ve found. So here you go.
