Skip to content

Configuration

The erlang_ls.config file

It is possible to customize the behaviour of the erlang_ls server via a configuration file, named erlang_ls.config. The erlang_ls.config file should be placed in the root directory of a given project to store the configuration for that project.

A sample erlang_ls.config file would look like the following:

otp_path: "/path/to/otp/lib/erlang"
deps_dirs:
  - "lib/*"
diagnostics:
  enabled:
    - crossref
  disabled:
    - dialyzer
include_dirs:
  - "include"
  - "_build/default/lib"
lenses:
  enabled:
    - ct-run-test
  disabled:
    - show-behaviour-usages
macros:
  - name: DEFINED_WITH_VALUE
    value: 42
  - name: DEFINED_WITHOUT_VALUE
code_reload:
  node: node@example
providers:
  enabled:
    - signature-help

The file format is yaml.

The following customizations are possible:

Parameter Description
apps_dirs List of directories containing project applications. It supports wildcards.
code_reload Whether or not an rpc call should be made to a remote node to compile and reload a module
deps_dirs List of directories containing dependencies. It supports wildcards.
diagnostics Customize the list of active diagnostics. See below for a list of available diagnostics.
include_dirs List of directories provided to the compiler as include dirs. It supports wildcards.
incremental_sync Whether or not to support incremental synchronization of text changes in the client. Enabled by default.
lenses Customize the list of active code lenses
macros List of cusom macros to be passed to the compiler, expressed as a name/value pair. If the value is omitted or is invalid, 'true' is used.
otp_apps_exclude List of OTP applications that will not be indexed (default: megaco, diameter, snmp, wx)
otp_path Path to the OTP installation
plt_path Path to the dialyzer PLT file. When none is provided the dialyzer diagnostics will not be available.
code_path_extra_dirs List of wildcard Paths erlang_ls will add with code:add_path/1
elvis_config_path Path to the elvis.config file. Defaults to ROOT_DIR/elvis.config
exclude_unused_includes List of includes files that are excluded from the UnusedIncludes warnings.
compiler_telemetry_enabled When enabled, send telemetry/event LSP messages containing the code field of any diagnostics present in a file. Defaults to false.
providers Which LSP providers should be advertised to clients

Diagnostics

When a file is open or saved, a list of diagnostics are run in the background, reporting eventual issues with the code base to the editor. The following diagnostics are available:

Diagnostic Name Purpose Default
bound_var_in_pattern Report already bound variables in patterns (inspired by the pinning operator) enabled
compiler Report in-line warnings and errors from the Erlang compiler enabled
crossref Use information from the Erlang LS Database to find out about undefined functions disabled
dialyzer Use the dialyzer static analysis tool to find discrepancies in your code enabled
elvis Use elvis to review the style of your Erlang code enabled
unused_includes Warn about header files which are included but not utilized enabled
unused_macros Warn about macros which are defined but not utilized enabled

It is possible to customize diagnostics for a specific project. For example:

diagnostics:
  disabled:
    - dialyzer
  enabled:
    - crossref

Automatic Code Reloading

The code_reload takes the following options:

Parameter Description
node The node to be called for code reloading. Example erlang_ls@hostname

Code Lenses

Code Lenses are also available in Erlang LS. The following lenses are available in Erlang LS:

Code Lens Name Purpose
ct-run-test Display a run button next to a Common Test testcase
function-references Show the number of references to a function
server-info Display some Erlang LS server information on the top of each module. For debug only.
show-behaviour-usages Show the number of modules implementing a behaviour
suggest-spec Use information from dialyzer to suggest a spec

The following lenses are enabled by default:

  • show-behaviour-usages

It is possible to customize lenses for a specific project. For example:

lenses:
  enabled:
    - ct-run-test
  disabled:
    - show-behaviour-usages

Providers

Which LSP Providers are advertised to the client may be configured. The following providers are available in Erlang LS:

Provider Name Purpose Default
text-document-sync Synchronize the document state between client and server enabled
hover Provide docmuentation for the symbol under the cursor on hover enabled
completion Provide auto-completion candidates for partial symbols enabled
signature-help Provide documentation for the current function and parameters on-type disabled
definition Jump to the definition of a given symbol enabled
references Jump to references of a given symbol enabled
document-highlight Highlight all other references to a symbol in scope enabled
document-symbol Provide all positions of a symbol in the current document enabled
workspace-symbol Provide all positions of a symbol across the workspace enabled
code-action Find commands to execute enabled
execute-command Execute code-action commands, returning edits to the client enabled
document-formatting Format an entire document enabled
document-range-formatting Format a given range of a document disabled
document-on-type-formatting Format parts of a document while typing disabled
folding-range Return all folding ranges in a document enabled
implementation Jump to the implementations of a callback enabled
code-lens Provide reference text and a command for position of interest in a document enabled
rename Rename a symbol across a workspace enabled
call-hierarchy Find the incoming and outgoing calls of the given position enabled
semantic-token Add additional highlighting information based on context-specific information enabled

Providers may be customized with the providers key. For example:

providers:
  enabled:
    - signature-help
  disabled:
    - hover

Global Configuration

It is also possible to store a system-wide default configuration in an erlang_ls.config file located in the User Config directory. The exact location of the User Config directory depends on the operating system used and it can be identified by executing the following command on an Erlang shell:

> filename:basedir(user_config, "erlang_ls").

Normally, the location of the User Config directory is:

Operating System User Config Directory
Linux /home/USER/.config/erlang_ls
OS X /Users/USER/Library/Application\ Support/erlang_ls
Windows c:/Users/USER/AppData/Local/erlang_ls

Thus on Linux, for example, the full path to the default configuation file would be /home/USER/.config/erlang_ls/erlang_ls.config

Common configurations

Many Erlang repositories follow the same structure. We include common Erlang LS configurations in this section, for easy reuse.

rebar3 project

The following configuration can be used for most rebar3 based projects.

apps_dirs:
  - "_build/default/lib/*"
include_dirs:
  - "_build/default/lib/*/include"
  - "include"

rebar3 umbrella project

If your rebar3 project includes multiple application (e.g. in an apps folder), you may want to adapt your Erlang LS configuration as follows.

apps_dirs:
  - "apps/*"
deps_dirs:
  - "_build/default/lib/*"
include_dirs:
  - "apps"
  - "apps/*/include"
  - "_build/default/lib/"
  - "_build/default/lib/*/include"

The erlang/otp repository

To be able to use the major Erlang LS features with the erlang/otp repository, the following minimal configuration should suffice.

otp_path: "/path/to/otp"
apps_dirs:
  - "lib/*"
include_dirs:
  - "lib"
  - "lib/*/include"