Added description for License and Description information to readme

Author Mitja Felicijan <mitja.felicijan@gmail.com> 2024-05-12 02:46:14 +0200
Committer Mitja Felicijan <mitja.felicijan@gmail.com> 2024-05-12 02:46:14 +0200
Commit b2b43079186fe5d845c0781e564f5c2352e36110 (patch)
-rw-r--r-- README.md 62
-rw-r--r-- makext.mk 6
2 files changed, 62 insertions, 6 deletions
diff --git a/README.md b/README.md
...
39 
> targets in your `Makefile`. GNU Make will execute first target if
 39 
> targets in your `Makefile`. GNU Make will execute first target if
40 
> no target provided as an argument when calling `make`.
 40 
> no target provided as an argument when calling `make`.
41 
  
 41 
  
42 
### Help extension
 42 
## Help extension
43 
  
 43 
  
44 
This is all that is needed to start using `makext`. One of the extensions
 44 
This is all that is needed to start using `makext`. One of the extensions
45 
is `.help` which displays all the targets in the `Makefile` and their
 45 
is `.help` which displays all the targets in the `Makefile` and their
46 
descriptions which are provided as comments next to the target definition.
 46 
descriptions which are provided as comments next to the target definition.
47 
  
 47 
  
48 
Lets check how and example `Makefile` would look.
 48 
Lets check how and example `Makefile` would look. It
 
  
 49 
is recommended to use `.PHONY` for targets that are not
 
  
 50 
actual files. In the example below I am not doing that
 
  
 51 
though, but it is wise to follow that rule. Check [4.6 Phony
 
  
 52 
Targets](https://www.gnu.org/software/make/manual/make.html#Phony-Targets)
 
  
 53 
section in the GNU Make manual.
49 
  
 54 
  
50 
```make
 55 
```make
51 
include makext.mk
 56 
include makext.mk
...
67 
  
 72 
  
68 
This will give us under we execute command `make` the following result.
 73 
This will give us under we execute command `make` the following result.
69 
  
 74 
  
70 
```
 75 
```text
71 
Targets:
 76 
Targets:
72 
  build-app                 Build the application
 77 
  build-app                 Build the application
73 
  clean-cache               Clean the cache
 78 
  clean-cache               Clean the cache
74 
  deploy-prod               Deploy to production
 79 
  deploy-prod               Deploy to production
75 
  run-tests                 Run tests
 
  
76 
```
 80 
```
77 
  
 81 
  
78 
- Targets without defined comments next to the target will be ignored
 82 
- Targets without defined comment next to the target will be ignored
79 
  from help list.
 83 
  from help list. In this case `run-tests` is missing from the list.
80 
- Targets that start with `.` will also be ignored.
 84 
- Targets that start with `.` will also be ignored.
 
  
 85 
- Prerequisites in targets will be ommited from the result.
 
  
 86 
  
 
  
 87 
## Description & License information
 
  
 88 
  
 
  
 89 
You can provide description for the project that will be displayed
 
  
 90 
together with `help`. To do this provide this information in the
 
  
 91 
`MK_DESCRIPTION` variable.
 
  
 92 
  
 
  
 93 
Same goes for license information. Provide this information by creating
 
  
 94 
`MK_LICENSE` variable.
 
  
 95 
  
 
  
 96 
If these variables are not present this information will not be displayed
 
  
 97 
in the help.
 
  
 98 
  
 
  
 99 
> [!IMPORTANT]
 
  
 100 
> Variables `MK_DESCRIPTION` and `MK_LICENSE` must be defined before you
 
  
 101 
> include `makext.mk` to your `Makefile`. This is needed because the way
 
  
 102 
> GNU Make is parsing Makefiles.
 
  
 103 
  
 
  
 104 
```make
 
  
 105 
MK_DESCRIPTION="This provides some additional tools for makefiles."
 
  
 106 
MK_LICENSE="Released under the BSD two-clause license, see the LICENSE file for more information."
 
  
 107 
  
 
  
 108 
include makext.mk
 
  
 109 
  
 
  
 110 
help: .help
 
  
 111 
  
 
  
 112 
build-app: clean-cache # Build the application
 
  
 113 
	@echo "Building the application..."
 
  
 114 
  
 
  
 115 
clean-cache: # Clean the cache
 
  
 116 
	@echo "Cleaning the cache..."
 
  
 117 
```
 
  
 118 
  
 
  
 119 
The following example will produce the following result.
 
  
 120 
  
 
  
 121 
```text
 
  
 122 
This provides some additional tools for makefiles.
 
  
 123 
  
 
  
 124 
Targets:
 
  
 125 
  build-app                 Build the application
 
  
 126 
  clean-cache               Clean the cache
 
  
 127 
  
 
  
 128 
Released under the BSD two-clause license, see the LICENSE file for
 
  
 129 
more information.
 
  
 130 
```
81 
  
 131 
  
82 
## Acknowledgement
 132 
## Acknowledgement
83 
  
 133 
  
...
diff --git a/makext.mk b/makext.mk
...
11 
#
 11 
#
12 
# Visit the GitHub repository at https://github.com/mitjafelicijan/makext
 12 
# Visit the GitHub repository at https://github.com/mitjafelicijan/makext
13 
# to learn more and contribute to the project.
 13 
# to learn more and contribute to the project.
 
  
 14 
#
 
  
 15 
# `makext` was written by Mitja Felicijan and is released under the BSD
 
  
 16 
# two-clause license, see the LICENSE file for more information.
14 
  
 17 
  
 
  
 18 
# Help extension that lists all the targets with descriptions
 
  
 19 
# and adds description and license information if data provided.
 
  
 20 
.PHONY: .help
15 
.help:
 21 
.help:
16 
ifdef MK_DESCRIPTION
 22 
ifdef MK_DESCRIPTION
17 
	@echo "$(MK_DESCRIPTION)\n" | fmt
 23 
	@echo "$(MK_DESCRIPTION)\n" | fmt
...