blob: 6e053d427f3461083e4fd17b9f1424038f1e5db2 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
# GNU Make quality of life extensions
Makext is a collection of useful extensions for Makefiles, aimed at
simplifying and enhancing the functionality of Make-based projects. These
extensions provide additional features and convenience functions to
improve the build process, manage dependencies, and streamline common
tasks.
> [!NOTE]
> This extensions are abusing GNU Make in some sense since it was not
> meant to really be a task runner. Keep that in mind. However, dispite
> that, I constantly find myself using it as such.
Features include:
- Enhanced help message generation with support for custom descriptions.
- Automatic description inclusion in help message.
- Automatic license inclusion in help message.
## How to use
First you will need to download `makext.mk` file from the repository to
the same directory where you have `Makefile`.
```sh
wget -O makext.mk https://github.com/mitjafelicijan/makext/raw/master/makext.mk
```
Now you can include it in your `Makefile`.
```make
include makext.mk
help: .help
```
> [!IMPORTANT]
> Make sure you create first target `help: .help` before any other
> targets in your `Makefile`. GNU Make will execute first target if
> no target provided as an argument when calling `make`.
## Help extension
This is all that is needed to start using `makext`. One of the extensions
is `.help` which displays all the targets in the `Makefile` and their
descriptions which are provided as comments next to the target definition.
Lets check how and example `Makefile` would look. It
is recommended to use `.PHONY` for targets that are not
actual files. In the example below I am not doing that
though, but it is wise to follow that rule. Check [4.6 Phony
Targets](https://www.gnu.org/software/make/manual/make.html#Phony-Targets)
section in the GNU Make manual.
```make
include makext.mk
help: .help
build-app: clean-cache # Build the application
@echo "Building the application..."
clean-cache: # Clean the cache
@echo "Cleaning the cache..."
deploy-prod: # Deploy to production
@echo "Deploying to production..."
run-tests:
@echo "Running tests..."
```
This will give us under we execute command `make` the following result.
```text
$ make
Targets:
build-app Build the application
clean-cache Clean the cache
deploy-prod Deploy to production
```
- Targets without defined comment next to the target will be ignored
from help list. In this case `run-tests` is missing from the list.
- Targets that start with `.` will also be ignored.
- Prerequisites in targets will be ommited from the result.
## Description & License information
You can provide description for the project that will be displayed
together with `help`. To do this provide this information in the
`MK_DESCRIPTION` variable.
Same goes for license information. Provide this information by creating
`MK_LICENSE` variable.
If these variables are not present this information will not be displayed
in the help.
> [!IMPORTANT]
> Variables `MK_DESCRIPTION` and `MK_LICENSE` must be defined before you
> include `makext.mk` to your `Makefile`. This is needed because the way
> GNU Make is parsing Makefiles.
```make
MK_DESCRIPTION="This provides some additional tools for makefiles."
MK_LICENSE="Released under the BSD two-clause license, see the LICENSE file for more information."
include makext.mk
help: .help
build-app: clean-cache # Build the application
@echo "Building the application..."
clean-cache: # Clean the cache
@echo "Cleaning the cache..."
```
The following example will produce the following result.
```text
$ make
This provides some additional tools for makefiles.
Targets:
build-app Build the application
clean-cache Clean the cache
Released under the BSD two-clause license, see the LICENSE file for
more information.
```
## Acknowledgement
- https://stackoverflow.com/a/59087509
## License
[makext](https://github.com/mitjafelicijan/makext) was written by [Mitja
Felicijan](https://mitjafelicijan.com) and is released under the BSD
two-clause license, see the LICENSE file for more information.
|
