From cf8f820267afa18cc3647224f46a7a307f58f289 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sun, 6 Sep 2015 13:52:16 +0200
Subject: Add tests for user generated Erlang source files

---
 doc/src/guide/app.asciidoc | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)

(limited to 'doc/src/guide/app.asciidoc')

diff --git a/doc/src/guide/app.asciidoc b/doc/src/guide/app.asciidoc
index a04c5a9..df23f76 100644
--- a/doc/src/guide/app.asciidoc
+++ b/doc/src/guide/app.asciidoc
@@ -235,10 +235,44 @@ transforms have changed. Erlang.mk also automatically keeps
 track of which files should be compiled first, for example
 when you have behaviors used by other modules in your project.
 
-=== Generated source files ===
+Erlang.mk can also keep track of the source files generated
+by other means, for example if you generate code from a data
+file in your repository.
 
-Generated source files are supported: they should be listed as
-dependencies to `$(PROJECT).d`:
+=== Generating Erlang source
+
+Erlang.mk provides hooks at different stages of the build process.
+When your goal is to generate Erlang source files, you can
+add your own rules before or after the dependency tracking
+file is generated. To do this, you would add your hook before
+or after including the 'erlang.mk' file.
+
+The easiest way is after:
+
+[source,make]
+----
+PROJECT = example
+
+include erlang.mk
+
+$(PROJECT).d:: src/generated_mod.erl
+
+src/generated_mod.erl:: gen-mod.sh
+	$(gen_verbose) ./gen-mod.sh $@
+----
+
+In this case we use `$(gen_verbose)` to hide the details of
+the build by default. Erlang.mk will simply say what file
+is it currently generating.
+
+When using an external script to generate the Erlang source
+file, it is recommended to depend on that script, so that
+the source file gets generated again when the script gets
+modified.
+
+If for whatever reason you prefer to hook before including
+Erlang.mk, don't forget to set the `.DEFAULT_GOAL` variable,
+otherwise nothing will get built:
 
 [source,make]
 ----
@@ -250,14 +284,10 @@ $(PROJECT).d:: src/generated_mod.erl
 
 include erlang.mk
 
-src/generated_mod.erl::
+src/generated_mod.erl:: gen-mod.sh
 	$(gen_verbose) ./gen-mod.sh $@
 ----
 
-Note how `.DEFAULT_GOAL` is set to `all` near the beginning. Without
-this, `$(PROJECT).d` would become the default target, changing the
-expected behavior of this `Makefile`.
-
 === Cleaning
 
 Building typically involves creating a lot of new files. Some
-- 
cgit v1.2.3