1 files changed, 138 insertions, 8 deletions
diff --git a/doc/src/guide/app.asciidoc b/doc/src/guide/app.asciidoc
index a04c5a9..5c097f6 100644
--- a/doc/src/guide/app.asciidoc
+++ b/doc/src/guide/app.asciidoc
@@ -165,6 +165,36 @@ key from dependencies automatically, which means you need to
 add them to Erlang.mk and to the '.app.src' at the same time,
 duplicating the work.
 
+If you really can't live without the legacy method, for one
+reason or another, worry not; Erlang.mk will support it. And
+if you need to create a new project that uses this method, you
+just have to say so when bootstrapping:
+
+[source,bash]
+$ make -f erlang.mk bootstrap-lib LEGACY=1
+
+=== Automatic application resource file values
+
+When building the application resource file, Erlang.mk may
+automatically add an `id` key with information about the
+Git commit (if using Git), or an empty string otherwise.
+It will only do this under specific conditions:
+
+* The application was built as a dependency of another, or
+* The legacy method was used, and the '.app.src' file contained `{id, "git"}`
+
+This value is most useful when you need to help your users,
+as it allows you to know which version they run exactly by
+asking them to look in the file, or by running a simple
+command on their production server:
+
+[source,erlang]
+----
+1> application:get_all_key(cowboy).
+{ok,[{description,"Small, fast, modular HTTP server."},
+     {id,"2.0.0-pre.2-25-g0ffde50-dirty"},
+----
+
 === File formats
 
 Erlang.mk supports a variety of different source file formats.
@@ -201,6 +231,56 @@ Erlang.mk also comes with plugins for the following formats:
 | .proto    | src/       | Protocol buffers | ebin/*.beam
 |===
 
+=== Compilation options
+
+Erlang.mk provides a few variables that you can use to customize
+the build process and the resulting files.
+
+==== ERLC_OPTS
+
+`ERLC_OPTS` can be used to pass some options to `erlc`, the Erlang
+compiler. Erlang.mk does not restrict any option. Please refer to
+the http://www.erlang.org/doc/man/erlc.html[erlc Manual] for the
+full list.
+
+By default, Erlang.mk will set the following options:
+
+[source,make]
+ERLC_OPTS = -Werror +debug_info +warn_export_vars +warn_shadow_vars +warn_obsolete_guard
+
+In other words: warnings as errors, debug info (recommended) and
+enable warnings for exported variables, shadow variables and
+obsolete guard functions.
+
+You can redefine this variable in your Makefile to change it
+completely, either before or after including Erlang.mk:
+
+[source,make]
+ERLC_OPTS = +debug_info
+
+You can also filter out some options from the defaults Erlang.mk
+sets, by defining ERLC_OPTS after including Erlang.mk using the
+`:=` operator.
+
+[source,make]
+----
+include erlang.mk
+
+ERLC_OPTS := $(filter-out -Werror,$(ERLC_OPTS))
+----
+
+==== ERLC_EXCLUDE
+
+`ERLC_EXCLUDE` can be used to exclude some modules from the
+compilation. It's there for handling special cases, you should
+not normally need it.
+
+To exclude a module, simply list it in the variable, either
+before or after including Erlang.mk:
+
+[source,make]
+ERLC_EXCLUDE = cowboy_http2
+
 === Cold and hot builds
 
 The first time you run `make`, Erlang.mk will build everything.
@@ -235,10 +315,64 @@ 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 ===
+If your project is stable, you may want to disable generating
+the dependency tracking file every time you compile. You can
+do this by adding the following line to your 'Makefile':
+
+[source,make]
+NO_MAKEDEP ?= 1
+
+As you can see, the snippet above uses `?=` instead of a
+simple equal sign. This is to allow you to temporarily override
+this value when you do make substantial changes to your project
+(including a new header file, new module with dependencies, etc.)
+and want to rebuild the dependency tracking file. You'll be
+able to use the following command:
+
+[source,bash]
+$ NO_MAKEDEP= make
+
+Otherwise, `make clean app` will of course force the
+recompilation of your project.
+
+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.
+
+=== 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:
 
-Generated source files are supported: they should be listed as
-dependencies to `$(PROJECT).d`:
+[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 +384,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