Test and document Dialyzer

One bug was fixed: now Erlang.mk will properly pass relevant
ERLC_OPTS values to Dialyzer.

One bug still exists when using multi-application repositories:
dependencies are not detected automatically. We need list-deps
before this can work.

1 files changed, 69 insertions, 2 deletions

diff --git a/doc/src/guide/dialyzer.asciidoc b/doc/src/guide/dialyzer.asciidoc
index 7377c82..d58afbc 100644
--- a/doc/src/guide/dialyzer.asciidoc
+++ b/doc/src/guide/dialyzer.asciidoc
@@ -1,5 +1,72 @@
 == Dialyzer
 
-// @todo Write it.
+Dialyzer is a tool that will detect discrepancies in your
+program. It does so using a technique known as success
+typing analysis which has the advantage of providing no
+false positives. Dialyzer is able to detect type errors,
+dead code and more.
 
-Placeholder chapter.
+Erlang.mk provides a wrapper around Dialyzer.
+
+=== How it works
+
+Dialyzer requires a PLT file to work. The PLT file contains
+the analysis information from all applications which are not
+expected to change, or rarely do. These would be all the
+dependencies of the application or applications you are
+currently working on, including standard applications in
+Erlang/OTP itself.
+
+Dialyzer can generate this PLT file. Erlang.mk includes rules
+to automatically generate the PLT file when it is missing.
+
+Once the PLT file is generated, Dialyzer can perform the
+analysis in record time.
+
+=== Configuration
+
+In a typical usage scenario, no variable needs to be set.
+The defaults should be enough. Do note however that the
+dependencies need to be set properly using the `DEPS` and
+`LOCAL_DEPS` variables.
+
+The `DIALYZER_PLT` file indicates where the PLT file will
+be written to (and read from). By default this is
+'$(PROJECT).plt' in the project's directory. Note that
+the `DIALYZER_PLT` variable is exported and is understood
+by Dialyzer directly.
+
+The `PLT_APPS` variable can be used to add additional
+applications to the PLT. You can either list application
+names or paths to these applications.
+
+Erlang.mk defines two variables for specifying options
+for the analysis: `DIALYZER_DIRS` and `DIALYZER_OPTS`.
+The former one defines which directories should be part
+of the analysis. The latter defines what extra warnings
+Dialyzer should report.
+
+Note that Erlang.mk enables the race condition warnings
+by default. As it can take considerably large resources
+to run, you may want to disable it on larger projects.
+
+=== Usage
+
+To perform an analysis, run the following command:
+
+[source,bash]
+$ make dialyze
+
+This will create the PLT file if it doesn't exist.
+
+The analysis will also be performed when you run the
+following command, alongside tests:
+
+[source,bash]
+$ make check
+
+You can use the `plt` target to create the PLT file if
+it doesn't exist. This is normally not necessary as
+Dialyzer creates it automatically.
+
+The PLT file will be removed when you run `make distclean`.