How do you comment your makefiles?
How do you comment your makefiles?
cross-posted from: https://lemmy.ml/post/6863402
Fed up w/ my ad-hoc scripts to display the targets and variables in a makefile(s), I've decided to write a reusable piece of code to do that: https://github.com/bahmanm/bmakelib/issues/81
The first step toward that would be to understand the common commenting styles. So far I have identified 4 patterns in the wild which you can find below.
Are there any style guides/conventions around this topic? Any references to well-written makefiles I can get inspiration from?
A
VAR1 = foo ## short one-liner comment my-target: ## short one-liner comment …B
# longer comment which # may span # several lines VAR1 = foo ## comments can be prefixed w/ more than # ## lorem ipsum dolor my-target: …C
##### # a comment block which is marked w/ several #s on # an otherwise blank line ##### VAR1 = fooD
##### #> # heading 1 # This is a variation to have markdown comments # inside makefile comments. # # ## It's a made-up style! # I came up w/ this style and used it to document `bmakelib`. # For example: https://is.gd/QtiqyA (opens github) #< ##### VAR1 = foo
The GNU Coding Standards has a section on Make, which I would think is the most prominent Make style guide.
The doc itself doesn't have a section on comments, but in the few examples given in that doc, they use style B.
https://www.gnu.org/prep/standards/html_node/Makefile-Conventions.html
That's a great starting point - and a good read anyways!
Thanks 🙏
We're supposed to be commenting Makefiles?
I usually capture all my development-time "automation" in Make and Ansible files. I also use makefiles to provide a consisent set of commands for the CI/CD pipelines to work w/ in case different projects use different build tools. That way CI/CD only needs to know about
make build,make test,make package, ... instead of Gradle/Maven/... specific commands.Most of the times, the makefiles are quite simple and don't need much comments. However, there are times that's not the case and hence the need to write a line of comment on particular targets and variables.