doc/vim-erlang-compiler.txt

*vim-erlang-compiler.txt* Erlang compiler and flymake

CONTENTS                                                 *vim-erlang-compiler*

    1. Introduction........................|vim-erlang-compiler-intro|
    2. Commands............................|vim-erlang-compiler-commands|
    3. Configuration.......................|vim-erlang-compiler-config|
      3.1 Configuration Rebar3.............|vim-erlang-compiler-config-rebar3|
    4. Credits.............................|vim-erlang-compiler-credits|
    5. Contributing........................|vim-erlang-compiler-contributing|

==============================================================================
INTRODUCTION                                       *vim-erlang-compiler-intro*

vim-erlang-compiler is an Erlang compiler and flymake.

The plugin's behaviour is the following by default:

1. Each time an Erlang source file is saved, it is checked with the Erlang
compiler, and errors and warnings are shown using |signs|. No beam file is
generated.

2. When |:make| is used on an Erlang module, in case of successful compilation
the beam file is generated next to the Erlang module.

If you use rebar, the plugin will find the rebar.config file corresponding to
the module being compiled, and uses the compiler options and directories in
rebar.config. The plugin does not support rebar.script files though.

The plugin has a basic support for |rebar3|. It is aware of rebar3 when a
rebar.lock is found inside the project. In the moment of syntax check, the
plugin discovers all the dependencies invoking the "rebar3 as default path"
command in background. The rebar executable is looked up inside the root
directory of the project and, if it's not found, through the current execution
path.

==============================================================================
COMMANDS                                        *vim-erlang-compiler-commands*

                                                    *:ErlangDisableShowErrors*
:ErlangDisableShowErrors
        Disable syntax check when saving .erl files.

        The action performed as syntax check can be configured with the
        |g:erlang_flymake_options| and |g:erlang_flymake_options_rules|
        variables.

                                                     *:ErlangEnableShowErrors*
:ErlangEnableShowErrors
        Enable syntax check when saving .erl files.

                                                     *:ErlangToggleShowErrors*
:ErlangToggleShowErrors
        Toggle between the two modes above.

==============================================================================
CONFIGURATION                                     *vim-erlang-compiler-config*

CONFIGURATION OPTIONS                       *vim-erlang-configuration-options*

The vim-erlang-compiler plugin's behaviour can be configured by setting the
global variables below from the |vimrc| file and either restarting Vim. (Just
modifying a variable without restarting Vim is often not enough, but the
buffers with Erlang files will store information calculated from these
options. If you don't want to restart Vim, you can also unload these buffers
with |:bdelete|.)

g:erlang_show_errors                                    *g:erlang_show_errors*
        Determines whether the automatic syntax check on writing .erl files
        should be enabled or disabled when Vim starts. If `1`, it is enabled,
        if `0`, it is disabled. The default value is `1.`

g:erlang_make_options                                  *g:erlang_make_options*
        Options to be used when using |:make| to compile a module. The default
        value is "--outdir .". See all options at
        |vim-erlang-compilation-options|.

        The following setting makes xref to be executed when doing |:make|: >

            let g:erlang_make_options = '--outdir . --xref'

<        Loading and reloading: see |g:erlang_make_options_rules|.

g:erlang_make_options_rules                      *g:erlang_make_options_rules*
        Rules to determine which options to use when using |:make| to compile
        a module. The default value is []. For example: >

            let g:erlang_make_options_rules =
              \ [{'path_re': 'project_a', 'options': '--outdir . --xref'},
              \  {'path_re': 'project_b', 'options': '--outdir ../ebin'}]

<        Loading: When an .erl file is opened, the first rule whose "path_re"
        regexp matches the full path of the Erlang file is used to set the
        compilation options. If no rule matches, |g:erlang_make_options| is
        used.

        Reloading: If you change the value of |g:erlang_make_options_rules| or
        |g:erlang_make_options|, it will not automatically take effect in the
        already opened Erlang buffers. Type the following command to refresh
        the compiler settings of an existing Erlang buffer: >

            :set compiler=erlang

<        Example: The following example is a convenient setting for a typical
        project that uses rebar. It will load the compiled module into the
        running node and replace the old versions of the module in the release
        directory: >

            let g:erlang_make_options_rules =
              \ [{'path_re': '/path/to/myproj',
              \   'options':
              \     ' --outdir ../ebin --xref' .
              \     ' --load longnames vimerlang@127.0.0.1 myproj@127.0.0.1' .
              \     ' --copy /path/to/myproj/rel'}]

<        The above example uses |g:erlang_make_options_rules| instead of
        |g:erlang_make_options| in order to avoid affecting .erl files outside
        of this project.

g:erlang_flymake_options                            *g:erlang_flymake_options*
        Similar to |g:erlang_make_options|, but used when performing
        on-the-fly syntax check (a.k.a. flymake). The default value is "".

        Loading and reloading: This variable is read directly before it is
        used. This means that after it is modified, the new value immediately
        takes effect.

        Example: The following setting makes xref to be executed when
        performing a syntax check. >

            let g:erlang_flymake_options = '--outdir /var/tmp --xref'

<        Setting an outdir directory is necessary, because xref needs the BEAM
        file to analyze the module.

g:erlang_flymake_options_rules                *g:erlang_flymake_options_rules*
        Similar to |g:erlang_make_options_rules|, but used when performing
        on-the-fly syntax check (a.k.a. flymake). The default value is [].

        Loading and reloading: similar to |g:erlang_flymake_options|.

g:erlang_quickfix_support                          *g:erlang_quickfix_support*
        Enable |quickfix| support instead of |location-list|.  If `1`,
        it is enabled, if `0`, it is disabled. The default value is `0`.

COMPILATION OPTIONS                           *vim-erlang-compilation-options*

--outdir DIR
        Put the compiled beam file into the given directory. It is relative to
        directory containing the file to compile.

--xref
        Execute xref on the beam file and print undefined functions. (Other
        xref warnings are not printed, because those should be also printed by
        the compiler.) Works only if --outdir is specified.

--load NODE_NAME_TYPE MY_NODE_NAME TARGET_NODE_NAME
        After successful compilation, start a node with MY_NODE_NAME and load
        the module into the target node. NODE_NAME_TYPE must be either
        "shortnames" or "longnames". Works only if --outdir is specified. See
        an example at |g:erlang_make_options_rules|.

--cookie COOKIE
        When --load is used, this option can be used to set the cookie to be
        used towards the TARGET_NODE_NAME.

--copy DIR
        After successful compilation, all beam files with the same number
        (recursively) under DIR will be overwritten with the newly generated
        beam file. Works only with Erlang R16 and above.

==============================================================================
CONFIGURATION REBAR3                       *vim-erlang-compiler-config-rebar3*

If you want to make the syntax check of the current project under a different
profile (see rebar3 profiles), you can easily instruct rebar3 by adding a
special configuration item in your rebar.config file.

By default, if nothing is specified, the plugin will assume you chose the
|default| profile.

E.g. to use the "test" profile: >

    {vim_erlang_compiler, [
      {profile, "test"}
    ]}.
<
==============================================================================
CREDITS                                          *vim-erlang-compiler-credits*

Developed by the vim-erlang community. Distributed under Vim's |license|.

vim-erlang-compiler's original source code comes from vimerl
(https://github.com/jimenezrick/vimerl).

Author:       Pawel 'kTT' Salata <rockplayer.pl@gmail.com>
Contributors: Ricardo Catalinas Jiménez <jimenezrick@gmail.com>
              Jesse Gumm <sigmastar@gmail.com>
              Adam Rutkowski <hq@mtod.org>
              Michael Coles <michael.coles@gmail.com>
              James Fish <james@fishcakez.com>
              Csaba Hoch <csaba.hoch@gmail.com>
              Krister Svanlund <krister.svanlund@gmail.com>
              Leonardo Rossi <leonardo.rossi@studenti.unipr.it>
License:      Vim License (see |license|)

==============================================================================
CONTRIBUTING                                *vim-erlang-compiler-contributing*

Bug reports, suggestions and improvements encouraged at the project's github:

    https://github.com/vim-erlang/vim-erlang-compiler

==============================================================================