Custom Compiler Modules

This is a new feature in rebar3 3.7.0 which allows to write custom compilers to be used with Rebar3. It is useful whenever you have files of a different language that you want to build alongside Erlang resources.

This interface is currently used internally for .xrl, .yrl, and .mib files, but currently few plugins have tried it.

🚧This is an unstable interface

Since we have not had many plugin authors try this interface yet, it is marked as unstable and is suspect to change.

We are looking for help of contributors to further stabilize it before marking it stable. You should use this if you are willing to enter in contact with us to help iterate on the features available in Custom Compiler Plugins

It is possible that your custom compiler requires something more complex. For example, the facilities provided by this interface are insufficient to build projects that run with mix as a buildtool, and the plugin for that uses a custom compiler plugin

Current Interface

The following callbacks are defined:

  1. -type extension() :: string().
  2. -type out_mappings() :: [{extension(), file:filename()}].
  4. %% Returns context that the rebar3 compiler needs regarding the project
  5. %% and files supported by this compiler
  6. -callback context(rebar_app_info:t()) ->
  7.             %% source directories to look into for files
  8.             #{src_dirs     => [file:dirname()],
  9.             %% directory for include files
  10.               include_dirs => [file:dirname()],
  11.             %% file extension for the source files (".yrl")
  12.               src_ext      => extension(),
  13.             %% mapping of output extensions to output directories.
  14.             %% For example, .yrl files are compiled to .erl files
  15.             %% and so the outmapping is [{".erl", "path/to/app/src/"}]
  16.               out_mappings => out_mappings()}.
  18. %% Files required to be built in any specific priority before others
  19.                     %% directed graph of application names
  20. -callback needed_files(digraph:graph(),
  21.                     %% files found by the rebar3 compiler matching the context
  22.                        [file:filename()],
  23.                     %% previously provided filetype to directory mappings
  24.                        out_mappings(),
  25.                     %% Information about the current OTP app
  26.                        rebar_app_info:t()) ->
  27.             %% list of files that need to be built first, with their options.
  28.             %% used for things like parse transforms, for example
  29.             {{[file:filename()], term()},
  30.             %% list of files that can be built last, with their options
  31.              {[file:filename()], term()}}.
  33. %% Specify file which are required dependencies of the current file,
  34. %% allowing the compiler to build a graph of build order required.
  35. %% An example for this might be include files.
  36. %% If no specific dependencies exist (any order is good), return
  37. %% an empty list.
  38. -callback dependencies(Source :: file:filename(),
  39.                        SourceDir :: file:dirname(), 
  40.                        Directories :: [file:dirname()]) ->
  41.             [file:filename()].
  43. %% Compile the actual file
  44.                   %% file to compile
  45. -callback compile(file:filename(),
  46.                   %% mappings defined earlier for directories for each file type
  47.                   out_mappings(),
  48.                   %% a dictionary of rebar3 configuration values
  49.                   rebar_dict(),
  50.                   %% compiler-specific options list
  51.                   list()) ->
  52.             ok
  53.           | {ok, [string()]} % same but with filenames
  54.           | {ok, [string()], [string()]}. % same but with filenames & warnings
  56. %% Clean up after built files
  57. %%        files found by compiler,  app-specific info
  58. -callback clean([file:filename()], rebar_app_info:t()) -> _.

Initializing a Compiler Module as a Plugin

Register the compiler module in the same place where you would register a custom compiler plugin:

  1. %% Note: the name of the module matches the name of the plugin application
  2. -module(my_compiler_plugin).
  3. -export([init/1]).
  5. %% Called when rebar3 first boots, before even parsing the arguments
  6. %% or commands to be run. Purely initiates the provider, and nothing
  7. %% else should be done here.
  8. -spec init(rebar_state:t()) -> {ok, rebar_state:t()}.
  9. init(State) ->
  10.     %% Optional:
  11.     %% Provider = providers:create([Options]),
  12.     %% State1 = rebar_state:add_provider(State, Provider),
  14.     %% This adds the new compiler module:
  15.     State1 = rebar_state:append_compilers(State, [my_compiler_mod]),
  16.     %% If needing the new compiler module to take precedence over
  17.     %% other ones (i.e. generating .erl files from another format):
  18.     State2 = rebar_state:append_compilers(State1, [translator_mod]),
  19.     {ok, State2}.