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"