[HN Gopher] Autodocumenting Makefiles
___________________________________________________________________
Autodocumenting Makefiles
Author : JNRowe
Score : 50 points
Date : 2022-01-30 14:01 UTC (1 days ago)
(HTM) web link (daniel.feldroy.com)
(TXT) w3m dump (daniel.feldroy.com)
| gegtik wrote:
| @sed -ne '/@sed/!s/## //p' $(MAKEFILE_LIST)
| bbkane wrote:
| Here's my starter Makefile with colored help :
| https://www.bbkane.com/blog/a-fancy-makefile/
|
| I don't use make often, so it also contains beginner friendly
| comments about the syntax
| donatj wrote:
| I've got a similar setup but just .PHONY: help
| help: ## Display this help @grep -E '^[ a-zA-
| Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS =
| ":.*?## "}; {printf "%-30s %s\n", $$1, $$2}'
|
| This was from HN a couple years ago
| technimad wrote:
| I've been doing that as well. Here [1] a more elaborate
| example, might be the original article.
|
| [1] https://www.thapaliya.com/en/writings/well-documented-
| makefi...
| giantrobot wrote:
| Ah yes, summon Cthulhu to explain the makefile to you. Seems
| extreme to me but some people have SAN to spare.
| urda wrote:
| Yeah I ended up with my own variant from here as well many
| moons ago: .PHONY: help help: # Show this
| help screen @ack '^[a-zA-Z_-]+:.*?# .*$$'
| $(MAKEFILE_LIST) |\ sort -k1,1 |\ awk
| 'BEGIN {FS = ":.*?# "}; {printf "\033[1m%-30s\033[0m %s\n",
| $$1, $$2}'
| coreyp_1 wrote:
| I've been on HN for years, but missed this. Thank you!
| [deleted]
| nerdponx wrote:
| I wouldn't exactly call replacing AWK with Sed a
| "simplification". And now you have a stew of escaped $s.
| Invoking `tput` is a good idea, though; maybe you can use the
| AWK `system()` function for that.
| andrewshadura wrote:
| Just grep would be enough
| andrewshadura wrote:
| Well, grep would look a bit uglier, sed would be better.
| cytzol wrote:
| If you're using Make as a command runner or a "standard entry
| point" to a project, instead of using it as a build system that
| tracks dependencies between files, I _highly_ recommend using
| `just` instead: https://github.com/casey/just
|
| It has this functionality built-in, and avoids a lot of Make's
| idiosyncrasies. (Not affiliated, just a fan.)
| delusional wrote:
| I think part of the appeal of make as a script runner is the
| ubiquity.
| Arnavion wrote:
| Also, if you add a new target that _would_ benefit from
| tracking dependencies between files, then make is already
| ready to do that.
|
| I use makefiles for my Rust code with just
| default+test+install targets that do no dependency tracking
| (since Rust's build system already does that much better).
| But if I need to add a target for, say, validating some
| OpenAPI spec that only needs to run if the spec file updates,
| then that can go in the same Makefile.
| 1vuio0pswjnm7 wrote:
| Another part might be parallel execution, running multiple
| shells at the same time
|
| https://github.com/rofl0r/jobflow
| davidjfelix wrote:
| Yeah, but if you follow the advice FTA, you now have to rely
| on a usable python version and make. Still fairly common, but
| what if I use node instead? I think the point is -- the more
| usability you add the more you potentially dilute how
| ubiquitous it is. I think it's okay to point to new tools in
| the space that shake things up and add usability for the
| purposes Make currently is used for. Ubiquity doesn't happen
| over night.
| Arnavion wrote:
| Even if I followed the advice in the article (I don't
| really plan to), python3 is very likely to already be there
| in a Linux distro for other reasons, whereas node.js is
| very likely to not be there.
|
| If you're on another OS where neither make nor python3 nor
| node.js are there by default, then sure you're already
| going to manually install make, so the choice of python3 or
| node.js is basically identical.
| GordonS wrote:
| Was going to say the same thing.
|
| Make is fiddly, has gotchas and is far from perfect, from the
| development side - but it's certainly "good enough", and it's
| great once you've got your Makefile done. And it's available,
| or at least easily attainable, pretty much everywhere. I even
| use it on Windows.
| [deleted]
| maxmcd wrote:
| We use this strategy at work:
| https://www.thapaliya.com/en/writings/well-documented-makefi...
|
| It has sections and categorization.
| Borkdude wrote:
| Babashka tasks has a :doc option for this:
|
| https://book.babashka.org/#_discoverability
| denibertovic wrote:
| I've been using this (different snippet though) for about 6 years
| now. It's great. "Poor man's CLI" is what I call my makefiles. :D
| Example:
| https://github.com/denibertovic/makefiles/blob/master/bare.m...
| WalterBright wrote:
| What I find interesting is programmers who are very scrupulous
| about documenting their code completely fail to document
| makefiles.
| kelseyfrog wrote:
| For historical reasons my team uses Makefiles for executing data
| science workflows[1]. They are auto-documenting which makes it
| not just helpful on me when I forget an underused target, but
| it's perhaps even more useful when onboarding new team members.
| Rather than directing them to some out of band docs, it's
| convenient to simply direct them to use make to get the help they
| need[2].
|
| 1. There are reasons, like consistency of interface which I value
| even more than autodocumentation, but that is outside the scope
| of this discussion.
|
| 2. For small orders of help.
| nerdponx wrote:
| For data science specifically, I would strongly suggest looking
| into DVC: https://dvc.org/.
|
| You can easily write DVC stage files by hand as a
| straightforward Makefile replacement, and integrate other
| features into your workflow as needed/desired.
| PeterWhittaker wrote:
| Clever! I like that....
|
| (Now if I could integrate that into the autotools we use for some
| of our stuff....)
| unfunco wrote:
| Throwing mine into the mix: .PHONY: help
| help: # Display this help message @awk 'BEGIN { \
| FS = ": #"; \ printf "App name\n\n"; \
| printf "Usage:\n make
| \033[38;5;141m<target>\033[0m\n\nTargets:\n" \ }
| /^(.+)\: #\ (.+)/ { \ printf "
| \033[38;5;141m%-11s\033[0m %s\n", $$1, $$2 \ }'
| $(MAKEFILE_LIST)
| tejtm wrote:
| A bit reluctant to share this as it is old (2005?) and would not
| support features I tend to use now. But if you are just starting,
| or stick to the most basic functionality it may be of use as a
| way to visualize the execution graph (DAG)
|
| https://github.com/TomConlin/MakefileViz
| Kimcha wrote:
| I have approached the problem in a similar way, but without
| python.
|
| I published my self-documenting docker Makefiles here:
|
| https://github.com/Infused-Insight/docker_makefiles
| jgrahamc wrote:
| Native GNU Make way to do this:
| https://www.cmcrossroads.com/article/self-documenting-makefi...
| JNRowe wrote:
| Which is also included in your _excellent_ GNU Make Book1,
| which you should 've pimped directly ;) It is both a fantastic
| general guide and an amazing source of usable little recipes,
| thanks!
|
| 1 https://nostarch.com/gnumake
___________________________________________________________________
(page generated 2022-01-31 23:01 UTC)