Extending rebar

In its standard release, rebar provides for most Erlang development needs. Should you encounter a need to extend rebar's capabilities, then its implementation allows easy inclusion of further functionality.

Contexts

The key to understanding how to extend rebar is, the role of contexts within the rebar core machinery. Contexts determine which commands (rebar modules) should be considered for execution within the project's directory structure.

Any directory context

Any commands (rebar modules) associated with the any directory context are allowed to be performed within any directory of the project.

The association is made in the any_dir_modules configuration parameter of the rebar.app resource file. For example, to have the rebar_exemplar module be considered for performing for all project directories, you would add the following to rebar.app:

{application, rebar,
 [{description, "Rebar: Erlang Build Tool"},
  %% ...
  {env, [
         %% ...

         %% any_dir processing modules
         {any_dir_modules, [
		                    %% ...
                            rebar_exemplar
                           ]},

		 %% ...
        ]}
]}.

Module context

The module context allows rebar commands to be associated with either the application directory, or with the release directory.

You can see this within the rebar.app resource file, and noting the use of app_dir and rel_dir within the modules configuration parameter.

Example: EDoc command

Changing rebar.app:

{application, rebar,
 [{description, "Rebar: Erlang Build Tool"},
  {vsn, "2"},
  {modules, [ rebar,
              %% ...
              rebar_edoc,
              %% ...
              mustache ]},
  {registered, []},
  {applications, [kernel,
                  stdlib,
                  sasl]},
  {env, [
         %% ...

         %% Dir specific processing modules
         {modules, [
                    {app_dir, [
                               %% ...
                               rebar_edoc,
                               %% ...
                              ]},

                    {rel_dir, [
                               rebar_reltool
                              ]}
                   ]}
        ]}
]}.

Introducing the rebar_edoc module:

-module(rebar_edoc).

-export([doc/2, clean/2]).

-include("rebar.hrl").

%% @doc Generate Erlang program documentation.
%% @spec doc(#config{}, string()) -> ok
-spec(doc(Config::#config{}, File::string()) -> ok).
doc(Config, File) ->
    {ok, AppName, _AppData} = rebar_app_utils:load_app_file(File),
    EDocOpts = rebar_config:get(Config, edoc_opts, []),
    ok = edoc:application(AppName, ".", EDocOpts),
    ok.

%% @doc Remove the generated Erlang program documentation.
%% @spec clean(#config{}, string()) -> ok
-spec(clean(Config::#config{}, File::string()) -> ok).
clean(Config, _File) ->
    EDocOpts = rebar_config:get(Config, edoc_opts, []),
    DocDir = proplists:get_value(dir, EDocOpts, "doc"),
    rebar_file_utils:rm_rf(DocDir).