Custom Dep Resources

Resources Compatible with versions 3.7.0 and Above

Starting with version 3.7.0, Rebar3 published a new API for custom resources, which gives access to the project’s local configuration to enable more powerful custom dependency formats. They can use contextual information from the current build to customize how dependencies might be fetched.

🚧The new Interface is not backwards compatible

This new interface is unknown and unsupported in versions prior to 3.7.0. If you are writing libraries that should work with all rebar3 copies, skip to the next section, where resources compatible with all rebar3 versions are documented. Old interfaces however are still compatible with all versions and no support for existing project has been broken in adding the new API.

The new callback API is defined as follows:

  1. %% Type declarations
  2. -type resource() :: #resource{}. % an opaque record generated by an API call described below
  3. -type source() :: {type(), location(), ref()} | {type(), location(), ref(), binary()}.
  4. -type type() :: atom().
  5. -type location() :: string().
  6. -type ref() :: any().
  7. -type resource_state() :: term().
  9. %% and the following callbacks
  10. -callback init(type(), rebar_state:t()) -> {ok, resource()}.
  11. -callback lock(rebar_app_info:t(), resource_state()) -> source().
  12. -callback download(file:filename_all(), rebar_app_info:t(), resource_state(), rebar_state:t()) ->
  13.     ok | {error, any()}.
  14. -callback needs_update(rebar_app_info:t(), resource_state()) -> boolean().
  15. -callback make_vsn(rebar_app_info:t(), resource_state()) ->
  16.     {plain, string()} | {error, string()}.

The callbacks allow the resource plugin to have access to the rebar_state:t() data structure, which lets you access and manipulate the rebar3 state, find application state, and generally work with the rebar_state, rebar_app_info, rebar_dir, and the new rebar_paths modules.

An example of a plugin making use of this functionality is rebar3_path_deps. Rebar3’s own hex package resource uses this API.

A resource plugin is initialized the same way as any other plugin would:

  1. -module(my_rebar_plugin).
  3. -export([init/1]).
  5. -spec init(rebar_state:t()) -> {ok, rebar_state:t()}.
  6. init(State) ->
  7.     {ok, rebar_state:add_resource(State, {Tag, Module})}.

Where Tag stands for the type in the deps configuration value (git, hg, etc.), and Module is the callback module.

The callback module may look as follows:

  1. -module(my_rebar_plugin_resource).
  3. -export([init/2,
  4.          lock/2,
  5.          download/4, download/3,
  6.          needs_update/2,
  7.          make_vsn/1]).
  9. %% Initialize the custom dep resource plugin
  10. init(Type, _RebarState) ->
  11.    CustomState = #{},
  12.    Resource = rebar_resource_v2:new(
  13.        Type,         % type tag such as 'git' or 'hg'
  14.        ?MODULE,      % this callback module
  15.        CustomState   % anything you want to carry around for next calls
  16.    ),
  17.    {ok, Resource}.
  19. lock(AppInfo, CustomState) ->
  20.   %% Extract info such as {Type, ResourcePath, ...} as declared
  21.   %% in rebar.config
  22.   SourceTuple = rebar_app_info:source(AppInfo)),
  23.   %% Annotate and modify the source tuple to make it absolutely
  24.   %% and indeniably unambiguous (for example, with git this means
  25.   %% transforming a branch name into an immutable ref)
  26.   ...
  27.   %% Return the unambiguous source tuple
  28.   ModifiedSource.
  30. download(TmpDir, AppInfo, CustomState, RebarState) ->
  31.   %% Extract info such as {Type, ResourcePath, ...} as declared
  32.   %% in rebar.config
  33.   SourceTuple = rebar_app_info:source(AppInfo)),
  34.   %% Download the resource defined by SourceTuple, which should be
  35.   %% an OTP application or library, into TmpDir
  36.   ...
  37.   ok.
  39. make_vsn(Dir, ResourceState) ->
  40.   %% Extract a version number from the application. This is useful
  41.   %% when defining the version in the .app.src file as `{version, Type}',
  42.   %% which means it should be derived from the build information. For
  43.   %% the `git' resource, this means looking for the last tag and adding
  44.   %% commit-specific information
  45.   ...
  46.   {plain, "0.1.2"}.
  49. needs_update(AppInfo, ResourceState) ->
  50.   %% Extract the Source tuple if needed
  51.   SourceTuple = rebar_app_info:source(AppInfo),
  52.   %% Base version in the current file
  53.   OriginalVsn = rebar_app_info:original_vsn(AppInfo)
  54.   %% Check if the copy in the current install matches
  55.   %% the defined value in the source tuple. On a conflict,
  56.   %% return `true', otherwise `false'
  57.   ...,
  58.     Bool.

Resources Compatible with all versions

Prior to version 3.7.0, the dependency resource framework was a bit more restricted. It had to essentially work context-free, with only the deps information from the rebar.config and rebar.lock to work from. It was not possible to have any information relative to the project configuration, which essentially restricted what could be done by each resource.

These custom resources are still supported in Rebar3 versions higher than 3.7.0, and so if you have users running older build, we recommend that you develop this kind of resources only.

Each dependency resource must implement the rebar_resource behaviour.

  1. -module(rebar_resource).
  3. -export_type([resource/0
  4.              ,type/0
  5.              ,location/0
  6.              ,ref/0]).
  8. -type resource() :: {type(), location(), ref()}.
  9. -type type() :: atom().
  10. -type location() :: string().
  11. -type ref() :: any().
  13. -callback lock(file:filename_all(), tuple()) ->
  14.     rebar_resource:resource().
  15. -callback download(file:filename_all(), tuple(), rebar_state:t()) ->
  16.     {tarball, file:filename_all()} | {ok, any()} | {error, any()}.
  17. -callback needs_update(file:filename_all(), tuple()) ->
  18.     boolean().
  19. -callback make_vsn(file:filename_all()) ->
  20.     {plain, string()} | {error, string()}.

Included with rebar3 are rebar_git_resource, rebar_hg_resource and rebar_pkg_resource.

A custom resource can be included the same way as a plugin. An example of this can be seen in Kelly McLaughlin’s rebar3_tidy_deps resource:

  1. -module(rebar_tidy_deps).
  3. -export([init/1]).
  5. -spec init(rebar_state:t()) -> {ok, rebar_state:t()}.
  6. init(State) ->
  7.     {ok, rebar_state:add_resource(State, {github, rebar_github_resource})}.

This resource rebar_github_resource which implements the rebar3 resource behaviour is added to the list of resources available in rebar_state. Adding the repo as a plugin to rebar.config allows this resource to be used:

  1. {mydep, {github, "kellymclauglin/mydep.git", {tag, "1.0.1"}}}.
  3. {plugins, [
  4.     {rebar_tidy_deps, ".*", {git, "https://github.com/kellymclaughlin/rebar3-tidy-deps-plugin.git", {tag, "0.0.2"}}}
  5. ]}.

Writing a Plugin working with both versions

If you want to write a custom resource plugin that works with both versions, you can dynamically detect arguments to provide backwards-compatible functionality. In the example below, the new API disregards all new information and just plugs itself back in the old API:

  1. -module(my_rebar_plugin_resource).
  3. -export([init/2,
  4.          lock/2,
  5.          download/4, download/3,
  6.          needs_update/2,
  7.          make_vsn/1]).
  9. init(Type, _RebarState) ->
  10.    CustomState = #{},
  11.    Resource = rebar_resource_v2:new(Type, ?MODULE, CustomState),
  12.    {ok, Resource}.
  14. %% Old API
  15. lock(Dir, Source) when is_tuple(Source) ->
  16.   lock_(Dir, Source);
  17. %% New API
  18. lock(AppInfo, _ResourceState) ->
  19.   %%      extract info for dir               extract info for source
  20.   lock_(rebar_app_info:dir(AppInfo), rebar_app_info:source(AppInfo)).
  22. %% Function handling normalized case
  23. lock_(Dir, Path) ->
  24.   ...
  26. %% Old Version
  27. download(TmpDir, SourceTuple, RebarState) ->
  28.   download_(TmpDir, SourceTuple, State).
  30. %% New Version
  31. download(TmpDir, AppInfo, _ResourceState, RebarState) ->
  32.   %%                            extract source tuple
  33.   download_(TmpDir, rebar_app_info:source(AppInfo), RebarState).
  35. %% Function handling normalized case
  36. download_(TmpDir, {MyTag, ...}, _State) ->
  37.   ...
  39. %% Old version
  40. make_vsn(Dir) ->
  41.   ...
  42. %% New version
  43. make_vsn(Dir, _ResourceState) ->
  44.   make_vsn(Dir).
  46. %% Old Version
  47. needs_update(Dir, {MyTag, Path, _}) ->
  48.   needs_update_(Dir, {MyTag, Path});
  49. %% New Version
  50. needs_update(AppInfo, _) ->
  51.   needs_update_(rebar_app_info:dir(AppInfo), rebar_app_info:source(AppInfo)).
  53. %% Function handling normalized case
  54. needs_update_(Dir, {Tag, Path}) ->
  55.   ...

Note that if you resource really needs the new API to work, backwards compatibility will be difficult to achieve since whenever it will be called, it won’t have all the information of the new API.

This approach is mostly useful when you can provide an acceptable (even if degraded) user experience with the old API.