12 ms·
Autodocumenting Makefiles
- PeterWhittaker 5y agoClever! I like that.... (Now if I could integrate that into the autotools we use for some of our stuff....)
- donatj 5y agoI'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
- coreyp_1 5y agoI've been on HN for years, but missed this. Thank you!
- giantrobot 5y agoAh yes, summon Cthulhu to explain the makefile to you. Seems extreme to me but some people have SAN to spare.
- deleted 5y ago[deleted]
- nerdponx 5y agoI 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 5y agoJust grep would be enough
- andrewshadura 5y agoWell, grep would look a bit uglier, sed would be better.
- urda 5y agoYeah 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}'
- technimad 5y agoI’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-makefiles/ https://www.thapaliya.com/en/writings/well-documented-makefi...
- maxmcd 5y agoWe use this strategy at work: https://www.thapaliya.com/en/writings/well-documented-makefiles/ https://www.thapaliya.com/en/writings/well-documented-makefi... It has sections and categorization.
- kelseyfrog 5y agoFor 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 5y agoFor data science specifically, I would strongly suggest looking into DVC: https://dvc.org/ 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.
- andreineculau 5y agoThis is exactly my experience which lead me to create https://github.com/ysoftwareab/yplatform https://github.com/ysoftwareab/yplatform - with a consistent make interface https://github.com/ysoftwareab/yplatform/tree/master/build.mk https://github.com/ysoftwareab/yplatform/tree/master/build.m... PS: quite feature complete but not yet well marketed so to speak. I'm actually recording an asciinema session this week in order for a visitor to grasp quicker the mentioned benefits.
- jgrahamc 5y agoNative GNU Make way to do this: https://www.cmcrossroads.com/article/self-documenting-makefiles https://www.cmcrossroads.com/article/self-documenting-makefi...
- JNRowe 5y agoWhich is also included in your excellent GNU Make Book¹, which you should've pimped directly ;) It is both a fantastic general guide and an amazing source of usable little recipes, thanks! ¹ https://nostarch.com/gnumake https://nostarch.com/gnumake
- jgrahamc 5y agoI try not to pimp my book. It’s unseemly :-)
- cytzol 5y agoIf 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 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 5y agoI think part of the appeal of make as a script runner is the ubiquity.
- GordonS 5y agoWas 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.
- davidjfelix 5y agoYeah, 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 5y agoEven 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.
- 5y ago
- gegtik 5y ago@sed -ne '/@sed/!s/## //p' $(MAKEFILE_LIST)
- Borkdude 5y agoBabashka tasks has a :doc option for this: https://book.babashka.org/#_discoverability https://book.babashka.org/#_discoverability
- denibertovic 5y agoI'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.makefile#L12-L22 https://github.com/denibertovic/makefiles/blob/master/bare.m...
- HenrikB 5y ago:thumbsup: This one allows you to put the '## help text' comments on the line just before the target. No need to put them after the prerequisite.
- unfunco 5y agoThrowing 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)
- deleted 5y ago[deleted]
- tejtm 5y agoA 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 https://github.com/TomConlin/MakefileViz
- bbkane 5y agoHere's my starter Makefile with colored help : https://www.bbkane.com/blog/a-fancy-makefile/ https://www.bbkane.com/blog/a-fancy-makefile/ I don't use make often, so it also contains beginner friendly comments about the syntax
- WalterBright 5y agoWhat I find interesting is programmers who are very scrupulous about documenting their code completely fail to document makefiles.
- Kimcha 5y agoI 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 https://github.com/Infused-Insight/docker_makefiles
- mongol 5y agoFeels like something Make would benefit to have out of the box.