glenux/makefiles-forever
glenux/makefiles-forever
1
1
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

doc: improve README content

Browse source
This commit is contained in:
Glenn Y. Rolland 2024-01-05 23:08:25 +01:00
parent 88543836ce
commit f95d28d72e
1 changed files with 69 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

92
README.md
View file

@ -1,60 +1,106 @@
<!--
# SPDX-License-Identifier: LGPL-3.0-or-later
#
# SPDX-FileCopyrightText: 2023 Glenn Y. Rolland <glenux@glenux.net>
# Copyright © 2023 Glenn Y. Rolland <glenux@glenux.net>
-->
# Makefiles Forever # Makefiles Forever
A drop-in collection of makefiles libraries for your projects A drop-in collection of makefiles libraries for your projects
## Description ## Description
* plantuml.makefile — Build [plantuml](https://plantuml.com/) diagrams * plantuml.makefile — Automate the building [plantuml](https://plantuml.com/) diagrams.
* dot.mk — Build [graphviz](https://graphviz.org/) graph diagrams * graphviz.mk — Streamline the creation of [graphviz](https://graphviz.org/) graph diagrams.
* mocodo.mk — Build [mocodo](http://mocodo.wingi.net/) entity-relation and logical diagrams * mocodo.mk — Facilitate the development of [mocodo](http://mocodo.wingi.net/) entity-relation and logical diagrams.
* mypaint.mk - Automate the conversion of [mypaint](https://mypaint.app/) openraster images to usual image formats.
## Usage ## Usage
Add this repository as a GIT submodule of your project ### Adding to your project
To include 'Makefiles Forever' in your project, add this repository as a GIT
submodule:
```shell-session ```shell-session
$ git submodule add https://github.com/glenux/makefiles-forever .makefiles $ git submodule add https://github.com/glenux/makefiles-forever .makefiles
``` ```
Include needed features in the end of your makefile ### Configuring your makefiles
In your project's makefile, include the necessary modules. __The `include` instructions must be located
__before your existing targets__.
```makefile ```makefile
# [...] # [... variable definitions ...]
-include .makefiles/featureA.mk # Include as many Makefiles Forever features as your want
-include .makefiles/featureB.mk include .makefiles/plantuml.mk
include .makefiles/mocodo.mk
include .makefiles/graphviz.mk
# [... targets definitions ...]
``` ```
Declare API variables (ex: `*_SRC_DIR`, `*_DEST_DIR`) for each module Declare API variables (ex: `*_SRC_DIR`, `*_DEST_DIR`) for each module
```makefile ```makefile
# Configuration for featureA from Makefiles Forever # PlantUML Configuration
FEATUREA_SRC_DIR=/path/to/somewhere PLANTUML_SRC_DIR=/path/to/plantuml/files
FEATUREA_DEST_DIR=/some/other/path PLANTUML_DEST_DIR=/path/to/output/directory
# Configuration for featureB from Makefiles Forever # Mocodo Configuration
FEATUREA_SRC_DIR=/another/path MOCODO_SRC_DIR=/path/to/mocodo/files
FEATUREB_DEST_DIR=/a/different/one MOCODO_DEST_DIR=/path/to/output/directory
# Graphviz Configuration
GRAPHVIZ_SRC_DIR=/path/to/mocodo/files
GRAPHVIZ_DEST_DIR=/path/to/output/directory
# [ ... etc ...]
``` ```
Use pre-defined targets as dependencies of your targets: Use pre-defined targets in your build process, as dependencies of your existing
targets:
```makefile ```makefile
build: featureA-build
build: featureB-build
clean: featureA-clean build: plantuml-build mocodo-build graphviz-build
clean: featureB-clean
clean: plantuml-clean mocodo-clean graphviz-clean
``` ```
Feature files usually define more targets than just build and clean, and you Feature files usually define more targets than just build and clean, and you
can use those too! can use those too!
## Good practices for coding .mk files ## Best practices used in our .mk modules
* Keep task parallelism in mind * Parallel Execution: We ensure targets are available from the root makefile and avoid descending into subdirectories for parallel execution.
* Make all targets available from root makefile * Modular Design: We keep our makefiles modular for easy maintenance and scalability.
* Do not descend in subdirectories * Documentation: We comment our makefiles for clarity and ease of use by others.
## Contributing
Contributions are what make the open-source community such an amazing place to
learn, inspire, and create. Any contributions you make are **greatly
appreciated**.
## Troubleshooting and Support
If you encounter any issues or need support, please open an issue in
[the project's issue tracker](https://code.apps.glenux.net/glenux/makefiles-forever/issues).
We strive to be responsive and helpful.
## License
Distributed under the LGPL-3.0-or-later License. See `LICENSE` file for more
information.
## Acknowledgments
* A special thanks to all contributors and users of this project for their
valuable feedback and support.