From d70b96a071a1e2bf919d57464c9e1ba1d0d8db56 Mon Sep 17 00:00:00 2001
From: "Glenn Y. Rolland" <glenux@glenux.net>
Date: Fri, 23 Jul 2021 15:46:18 +0200
Subject: [PATCH] Improve usage documentation

---
 README.md | 52 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index d2a0386..6ab2e52 100644
--- a/README.md
+++ b/README.md
@@ -10,18 +10,48 @@ A drop-in collection of makefiles libraries for your projects
 
 ## Usage
 
-* Add this repository as a GIT submodule of your project
-  ```
-  git submodule add https://github.com/glenux/makefiles-forever .makefiles
-  ```
-* Include needed features in the end of your makefile
-  ```
-  # [...]
+Add this repository as a GIT submodule of your project
 
-  -include .makefiles/featureA.mk
-  -include .makefiles/featureB.mk  
-  ```
-## Good practices
+```shell-session
+$ git submodule add https://github.com/glenux/makefiles-forever .makefiles
+```
+
+Include needed features in the end of your makefile
+
+```makefile
+# [...]
+
+-include .makefiles/featureA.mk
+-include .makefiles/featureB.mk  
+```
+
+Declare API variables (ex: `*_SRC_DIR`, `*_DEST_DIR`) for each module
+
+```makefile
+# Configuration for featureA from Makefiles Forever
+FEATUREA_SRC_DIR=/path/to/somewhere
+FEATUREA_DEST_DIR=/some/other/path
+
+# Configuration for featureB from Makefiles Forever
+FEATUREA_SRC_DIR=/another/path
+FEATUREB_DEST_DIR=/a/different/one
+```
+
+Use pre-defined targets as dependencies of your targets:
+
+```makefile
+build: featureA-build
+build: featureB-build
+
+clean: featureA-clean
+clean: featureB-clean
+```
+
+Feature files usually define more targets than just build and clean, and you
+can use those too!
+
+
+## Good practices for coding .mk files
 
 * Keep task parallelism in mind
   * Make all targets available from root makefile