[[dialyzer]]
== Dialyzer

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.

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`.

=== Dialyzing beam files

By default Erlang.mk will run Dialyzer against the source
code. It is possible to configure Erlang.mk to use the
compiled source files instead. This is done using the
`DIALYZER_DIRS` variable:

[source,make]
DIALYZER_DIRS = -r ebin

This value must be set before including Erlang.mk to
function properly.