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 = foo

D

#####
#>    # 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

When writing a (GNU) Makefile, there are times when you need a particular target(s) to be run before anything else. That can be for example to check the environment, ensure variables are set or prepare a particular directory layout.

... take advantage of GNU Make's mechanism of includeing and makeing makefiles which is described in details in the manual:

I'm trying to gather requirements wrt a potential bmakelib feature linked in the post.

I'd appreciate your feedback around:

• What are the conventions you follow to document your Makefiles?
• How/where do you usually declare variables and how do you document them?

Please take a second to share your thoughts on the issue or simply reply to this post if you'd prefer 🙏

There are two major flavours of variables in GNU Make: "simple" and "recursive".

While simple variables are quite simple and easy to understand, they can be limiting at times. On the other hand, recursive variables are powerful yet tricky.

...

There is exactly one rule to recall when using recursive variables...

🧠 The value of a recursive variable is computed every time it is expanded.

A follow up on [DISCUSS] Website to monitor Lemmy servers' performance/availability

I wanted to experiment w/ Lemmy's APIs to, eventually, build a public-facing performance monitoring solution for Lemmy.

It started w/ a couple of shell commands which I found myself repeating. Then I recalled the saying "Don't repeat yourself - make Make make things happen for you!" and, well, stopped typing commands in bash.

Instead I, incrementally, wrote a makefile to do the crud work for me (esp thanks to its declarative style): https://github.com/bahmanm/lemmy-clerk/blob/v0.0.1/run-clerk

TBH there's nothing special about the file. But I thought I'd share this primarily b/c it is a demonstration of the patterns I usually use in my makefiles and I'd love some feedback on those.

Additionally, it's a real world use-case for bmakelib (a library that I maintain 😎 )