Man Linux: Main Page and Category List

NAME

       dialyzer - The Dialyzer, a DIscrepancy AnalYZer for ERlang programs

DESCRIPTION

       The  Dialyzer  is  a  static  analysis  tool  that  identifies software
       discrepancies such as definite type errors, code which has become  dead
       or  unreachable  due to some programming error, unnecessary tests, etc.
       in single Erlang modules or entire  (sets  of)  applications.  Dialyzer
       starts  its  analysis  from either debug-compiled BEAM bytecode or from
       Erlang source code. The file  and  line  number  of  a  discrepancy  is
       reported  along  with  an  indication of what the discrepancy is about.
       Dialyzer bases its analysis on the concept  of  success  typings  which
       allows for sound warnings (no false positives).

       Read  more  about  Dialyzer  and  about  how  to use it from the GUI in
       Dialyzer Users Guide.

USING THE DIALYZER FROM THE COMMAND LINE

       Dialyzer also has a command line version for automated use. Below is  a
       brief  description of the list of its options. The same information can
       be obtained by writing

             dialyzer --help

       in a shell. Please refer to the GUI description for more details on the
       operation of Dialyzer.

       The exit status of the command line version is:

             0 - No problems were encountered during the analysis and no
                 warnings were emitted.
             1 - Problems were encountered during the analysis.
             2 - No problems were encountered, but warnings were emitted.

       Usage:

          dialyzer [--help] [--version] [--shell] [--quiet] [--verbose]
                 [-pa dir]* [--plt plt] [-Ddefine]* [-I include_dir]*
                 [--output_plt file] [-Wwarn]* [--src]
                 [-c applications] [-r applications] [-o outfile]
                 [--build_plt] [--add_to_plt] [--remove_from_plt]
                 [--check_plt] [--no_check_plt] [--plt_info] [--get_warnings]

       Options:

          -c applications(or  --command-line applications)
             use  Dialyzer from the command line (no GUI) to detect defects in
             the
                    specified applications (directories  or   .erl  or   .beam
             files)

          -r applications
             same as  -c only that directories are searched recursively for
                    subdirectories containing  .erl or  .beam files (depending
             on the
                    type of analysis)

          -o outfile(or  --output outfile)
             when using Dialyzer from the command line, send the analysis
                    results in the specified  outfile rather than in stdout

          --src
             override the default, which is to analyze debug compiled BEAM
                    bytecode, and analyze starting  from  Erlang  source  code
             instead

          --raw
             When  using  Dialyzer  from  the  command  line,  output  the raw
             analysis
                    results (Erlang terms) instead of the formatted result.
                    The raw format is easier to post-process (for instance, to
             filter
                    warnings or to output HTML pages).

          -Dname(or  -Dname=value)
             when analyzing from source, pass the define to Dialyzer (**)

          -I include_dir
             when  analyzing  from  source,  pass the  include_dir to Dialyzer
             (**)

          -pa dir
             Include  dir in the path for Erlang. Useful when analyzing files
                    that have  -include_lib() directives.

          --output_plt file
             Store the PLT at the specified location after building it.

          --plt plt
             Use the specified plt as the initial persistent lookup table.

          -Wwarn
             a family of option which selectively turn on/off warnings.
                    (for help on the names of warnings use  dialyzer -Whelp)

          --shell
             do not disable the Erlang shell while running the GUI

          --version (or -v)
             prints the Dialyzer version and some more information and exits

          --help (or -h)
             prints this message and exits

          --quiet (or -q)
             makes Dialyzer a bit more quiet

          --verbose
             makes Dialyzer a bit more verbose

          --check_plt
             Only checks if the initial PLT is up to date and rebuilds  it  if
             this is not the case

          --no_check_plt (or -n)
             Skip the PLT integrity check when running Dialyzer.
                    Useful when working with installed PLTs that never change.

          --build_plt
             The analysis starts from an empty PLT and creates a new one from
                    the files specified with -c and -r. Only  works  for  beam
             files.
                    Use  --plt  or  --output_plt  to  override the default PLT
             location.

          --add_to_plt
              The PLT is extended to also include the files specified with
                    -c and -r. Use --plt to specify which PLT to  start  from,
             and --output_plt
                    to  specify  where  to put the PLT. Note that the analysis
             might include
                    files from the PLT if they depend on the new files.
                    This option only works with beam files.

          --remove_from_plt
             The information from the  files  specified  with  -c  and  -r  is
             removed
                    from  the  PLT.  Note that this may cause a re-analysis of
             the remaining
                    dependent files.

          --get_warnings
             Makes Dialyzer emit warnings even when manipulating the PLT. Only
                    emits  warnings  for files that are actually analyzed. The
             default is to
                    not emit any warnings  when  manipulating  the  PLT.  This
             option has no
                    effect when performing a normal analysis.

       Note:
           *  denotes that multiple occurrences of these options are possible.

       ** options -D and -I work both from command-line and  in  the  Dialyzer
       GUI;  the  syntax  of  defines and includes is the same as that used by
       erlc.

       Warning options:

          -Wno_return
             Suppress warnings for functions of no return.

          -Wno_unused
             Suppress warnings for unused functions.

          -Wno_improper_lists
             Suppress warnings for construction of improper lists.

          -Wno_fun_app
             Suppress warnings for fun applications that will fail.

          -Wno_match
             Suppress warnings for patterns that are unused or cannot
                    match.

          -Werror_handling***
             Include warnings for functions that only return by means of an
                    exception.

          -Wunmatched_returns***
             Include warnings for function calls  which  ignore  a  structured
             return
                    value  or do not match against one of many possible return
             value(s).

          -Wunderspecs***
             Warn about underspecified functions
                   (the -spec is  strictly  more  allowing  than  the  success
             typing)

          -Woverspecs***
             Warn about overspecified functions
                   (the  -spec  is  strictly  less  allowing  than the success
             typing)

          -Wspecdiffs***
             Warn when the -spec is different than the success typing

       Note:
           *** These are options that turn on  warnings  rather  than  turning
           them off.

USING THE DIALYZER FROM ERLANG

       You  can  also  use Dialyzer directly from Erlang. Both the GUI and the
       command line versions are available. The options  are  similar  to  the
       ones given from the command line, so please refer to the sections above
       for a description of these.

EXPORTS

       gui() -> ok | {error, Msg}
       gui(OptList) -> ok | {error, Msg}

              Types  OptList -- see below

              Dialyzer GUI version.

              OptList  : [Option]
              Option   : {files,          [Filename : string()]}
                       | {files_rec,      [DirName : string()]}
                       | {defines,        [{Macro: atom(), Value : term()}]}
                       | {from,           src_code | byte_code} %% Defaults to byte_code
                       | {init_plt,       FileName : string()}  %% If changed from default
                       | {include_dirs,   [DirName : string()]}
                       | {output_file,    FileName : string()}
                       | {output_plt,     FileName :: string()}
                       | {analysis_type,  ’success_typings’ | ’plt_add’ | ’plt_build’ | ’plt_check’ | ’plt_remove’}
                       | {warnings,       [WarnOpts]}
                       | {get_warnings,   bool()}

              WarnOpts : no_return
                       | no_unused
                       | no_improper_lists
                       | no_fun_app
                       | no_match
                       | no_fail_call
                       | error_handling
                       | unmatched_returns
                       | overspecs
                       | underspecs
                       | specdiffs

       run(OptList) -> Warnings

              Types  OptList -- see gui/0,1
                     Warnings -- see below

              Dialyzer command line version.

              Warnings :: [{Tag, Id, Msg}]
              Tag : ’warn_return_no_exit’ | ’warn_return_only_exit’
                  | ’warn_not_called’ | ’warn_non_proper_list’
                  | ’warn_fun_app’ | ’warn_matching’
                  | ’warn_failing_call’ | ’warn_contract_types’
                  | ’warn_contract_syntax’ | ’warn_contract_not_equal’
                  | ’warn_contract_subtype’ | ’warn_contract_supertype’
              Id = {File :: string(), Line :: integer()}
              Msg = msg() -- Undefined

       format_warning(Msg) -> string()

              Types  Msg = {Tag, Id, msg()} -- See run/1

              Get a string from warnings as returned by dialyzer:run/1.

       plt_info(string()) -> {ok, [{atom(), any()}]} | {error, atom()}

              Returns information about the specified plt.