summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/r3.erl7
-rw-r--r--src/rebar3.erl76
-rw-r--r--src/rebar_agent.erl59
-rw-r--r--src/rebar_api.erl38
-rw-r--r--src/rebar_app_discover.erl83
-rw-r--r--src/rebar_app_info.erl131
-rw-r--r--src/rebar_app_utils.erl79
-rw-r--r--src/rebar_base_compiler.erl108
-rw-r--r--src/rebar_config.erl86
-rw-r--r--src/rebar_core.erl34
-rw-r--r--src/rebar_digraph.erl22
-rw-r--r--src/rebar_dir.erl111
-rw-r--r--src/rebar_dist_utils.erl11
-rw-r--r--src/rebar_file_utils.erl6
-rw-r--r--src/rebar_pkg_resource.erl6
-rw-r--r--src/rebar_prv_install_deps.erl9
-rw-r--r--src/rebar_utils.erl23
17 files changed, 792 insertions, 97 deletions
diff --git a/src/r3.erl b/src/r3.erl
index 5e8b26d..d0d6c47 100644
--- a/src/r3.erl
+++ b/src/r3.erl
@@ -1,7 +1,12 @@
-%%% external alias for rebar_agent
+%%% @doc external alias for `rebar_agent' for more convenient
+%%% calls from a shell.
-module(r3).
-export([do/1, do/2]).
+%% @doc alias for `rebar_agent:do/1'
+-spec do(atom()) -> ok | {error, term()}.
do(Command) -> rebar_agent:do(Command).
+%% @doc alias for `rebar_agent:do/2'
+-spec do(atom(), atom()) -> ok | {error, term()}.
do(Namespace, Command) -> rebar_agent:do(Namespace, Command).
diff --git a/src/rebar3.erl b/src/rebar3.erl
index 1059904..56bf3e8 100644
--- a/src/rebar3.erl
+++ b/src/rebar3.erl
@@ -24,6 +24,16 @@
%% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
%% THE SOFTWARE.
%% -------------------------------------------------------------------
+%%
+%% @doc Main module for rebar3. Supports two interfaces; one for escripts,
+%% and one for usage as a library (although rebar3 makes a lot of
+%% assumptions about its environment, making it a bit tricky to use as
+%% a lib).
+%%
+%% This module's job is mostly to set up the root environment for rebar3
+%% and handle global options (mostly all from the ENV) and make them
+%% accessible to the rest of the run.
+%% @end
-module(rebar3).
-export([main/0,
@@ -43,14 +53,14 @@
%% Public API
%% ====================================================================
-%% For running with:
+%% @doc For running with:
%% erl +sbtu +A0 -noinput -mode minimal -boot start_clean -s rebar3 main -extra "$@"
-spec main() -> no_return().
main() ->
List = init:get_plain_arguments(),
main(List).
-%% escript Entry point
+%% @doc escript Entry point
-spec main(list()) -> no_return().
main(Args) ->
try run(Args) of
@@ -63,7 +73,8 @@ main(Args) ->
handle_error(Error)
end.
-%% Erlang-API entry point
+%% @doc Erlang-API entry point
+-spec run(rebar_state:t(), [string()]) -> {ok, rebar_state:t()} | {error, term()}.
run(BaseState, Commands) ->
start_and_load_apps(api),
BaseState1 = rebar_state:set(BaseState, task, Commands),
@@ -78,6 +89,10 @@ run(BaseState, Commands) ->
%% Internal functions
%% ====================================================================
+%% @private sets up the rebar3 environment based on the command line
+%% arguments passed, if they have any relevance; used to translate
+%% from the escript call-site into a common one with the library
+%% usage.
run(RawArgs) ->
start_and_load_apps(command_line),
@@ -95,7 +110,13 @@ run(RawArgs) ->
{BaseState2, _Args1} = set_options(BaseState1, {[], []}),
run_aux(BaseState2, RawArgs).
+%% @private Junction point between the CLI and library entry points.
+%% From here on the module's role is a shared path here to finish
+%% up setting the environment for the run.
+-spec run_aux(rebar_state:t(), [string()]) ->
+ {ok, rebar_state:t()} | {error, term()}.
run_aux(State, RawArgs) ->
+ %% Profile override; can only support one profile
State1 = case os:getenv("REBAR_PROFILE") of
false ->
State;
@@ -108,6 +129,7 @@ run_aux(State, RawArgs) ->
rebar_utils:check_min_otp_version(rebar_state:get(State1, minimum_otp_vsn, undefined)),
rebar_utils:check_blacklisted_otp_versions(rebar_state:get(State1, blacklisted_otp_vsns, undefined)),
+ %% Change the default hex CDN
State2 = case os:getenv("HEX_CDN") of
false ->
State1;
@@ -144,6 +166,9 @@ run_aux(State, RawArgs) ->
rebar_core:init_command(rebar_state:command_args(State10, Args), Task).
+%% @doc set up base configuration having to do with verbosity, where
+%% to find config files, and so on, and return an internal rebar3 state term.
+-spec init_config() -> rebar_state:t().
init_config() ->
rebar_utils:set_httpc_options(),
@@ -190,6 +215,17 @@ init_config() ->
%% Initialize vsn cache
rebar_state:set(State1, vsn_cache, dict:new()).
+%% @doc Parse basic rebar3 arguments to find the top-level task
+%% to be run; this parsing is only partial from the point of view that
+%% runs done with arguments like `as $PROFILE do $TASK' will just
+%% return `as', which is then in charge of doing a more dynamic
+%% dispatch.
+%% If no arguments are given, the `help' task is returned.
+%% If special arguments like `-h' or `-v' are translated to `help'
+%% and `version' tasks.
+%% The unparsed parts of arguments are returned in:
+%% `{Task, Rest}'.
+-spec parse_args([string()]) -> {atom(), [string()]}.
parse_args([]) ->
parse_args(["help"]);
parse_args([H | Rest]) when H =:= "-h"
@@ -201,6 +237,7 @@ parse_args([H | Rest]) when H =:= "-v"
parse_args([Task | RawRest]) ->
{list_to_atom(Task), RawRest}.
+%% @private actually not too sure what this does anymore.
set_options(State, {Options, NonOptArgs}) ->
GlobalDefines = proplists:get_all_values(defines, Options),
@@ -213,9 +250,8 @@ set_options(State, {Options, NonOptArgs}) ->
{rebar_state:set(State2, task, Task), NonOptArgs}.
-%%
-%% get log level based on getopt option
-%%
+%% @doc get log level based on getopt options and ENV
+-spec log_level() -> integer().
log_level() ->
case os:getenv("QUIET") of
Q when Q == false; Q == "" ->
@@ -230,18 +266,16 @@ log_level() ->
rebar_log:error_level()
end.
-%%
-%% show version information and halt
-%%
+%% @doc show version information
+-spec version() -> ok.
version() ->
{ok, Vsn} = application:get_key(rebar, vsn),
?CONSOLE("rebar ~s on Erlang/OTP ~s Erts ~s",
[Vsn, erlang:system_info(otp_release), erlang:system_info(version)]).
+%% @private set global flag based on getopt option boolean value
%% TODO: Actually make it 'global'
-%%
-%% set global flag based on getopt option boolean value
-%%
+-spec set_global_flag(rebar_state:t(), list(), term()) -> rebar_state:t().
set_global_flag(State, Options, Flag) ->
Value = case proplists:get_bool(Flag, Options) of
true ->
@@ -251,9 +285,9 @@ set_global_flag(State, Options, Flag) ->
end,
rebar_state:set(State, Flag, Value).
-%%
-%% options accepted via getopt
-%%
+
+%% @doc options accepted via getopt
+-spec global_option_spec_list() -> [{atom(), char(), string(), atom(), string()}, ...].
global_option_spec_list() ->
[
%% {Name, ShortOpt, LongOpt, ArgSpec, HelpMsg}
@@ -262,6 +296,9 @@ global_option_spec_list() ->
{task, undefined, undefined, string, "Task to run."}
].
+%% @private translate unhandled errors and internal return codes into proper
+%% erroneous program exits.
+-spec handle_error(term()) -> no_return().
handle_error(rebar_abort) ->
erlang:halt(1);
handle_error({error, rebar_abort}) ->
@@ -295,6 +332,11 @@ handle_error(Error) ->
?INFO("When submitting a bug report, please include the output of `rebar3 report \"your command\"`", []),
erlang:halt(1).
+%% @private Boot Erlang dependencies; problem is that escripts don't auto-boot
+%% stuff the way releases do and we have to do it by hand.
+%% This also lets us detect and show nicer errors when a critical lib is
+%% not supported
+-spec start_and_load_apps(command_line|api) -> term().
start_and_load_apps(Caller) ->
_ = application:load(rebar),
%% Make sure crypto is running
@@ -305,6 +347,9 @@ start_and_load_apps(Caller) ->
inets:start(),
inets:start(httpc, [{profile, rebar}]).
+%% @doc Make sure a required app is running, or display an error message
+%% and abort if there's a problem.
+-spec ensure_running(atom(), command_line|api) -> ok | no_return().
ensure_running(App, Caller) ->
case application:start(App) of
ok -> ok;
@@ -321,6 +366,7 @@ ensure_running(App, Caller) ->
throw(rebar_abort)
end.
+-spec state_from_global_config([term()], file:filename()) -> rebar_state:t().
state_from_global_config(Config, GlobalConfigFile) ->
GlobalConfigTerms = rebar_config:consult_file(GlobalConfigFile),
GlobalConfig = rebar_state:new(GlobalConfigTerms),
diff --git a/src/rebar_agent.erl b/src/rebar_agent.erl
index 4b0fc5f..ed9e45d 100644
--- a/src/rebar_agent.erl
+++ b/src/rebar_agent.erl
@@ -1,3 +1,5 @@
+%%% @doc Runs a process that holds a rebar3 state and can be used
+%%% to statefully maintain loaded project state into a running VM.
-module(rebar_agent).
-export([start_link/1, do/1, do/2]).
-export([init/1,
@@ -10,19 +12,34 @@
cwd,
show_warning=true}).
+%% @doc boots an agent server; requires a full rebar3 state already.
+%% By default (within rebar3), this isn't called; `rebar_prv_shell'
+%% enters and transforms into this module
+-spec start_link(rebar_state:t()) -> {ok, pid()}.
start_link(State) ->
gen_server:start_link({local, ?MODULE}, ?MODULE, State, []).
+%% @doc runs a given command in the agent's context.
+-spec do(atom()) -> ok | {error, term()}.
do(Command) when is_atom(Command) ->
gen_server:call(?MODULE, {cmd, Command}, infinity).
+%% @doc runs a given command in the agent's context, under a given
+%% namespace.
+-spec do(atom(), atom()) -> ok | {error, term()}.
do(Namespace, Command) when is_atom(Namespace), is_atom(Command) ->
gen_server:call(?MODULE, {cmd, Namespace, Command}, infinity).
+%%%%%%%%%%%%%%%%%
+%%% CALLBACKS %%%
+%%%%%%%%%%%%%%%%%
+
+%% @private
init(State) ->
Cwd = rebar_dir:get_cwd(),
{ok, #state{state=State, cwd=Cwd}}.
+%% @private
handle_call({cmd, Command}, _From, State=#state{state=RState, cwd=Cwd}) ->
MidState = maybe_show_warning(State),
{Res, NewRState} = run(default, Command, RState, Cwd),
@@ -34,18 +51,29 @@ handle_call({cmd, Namespace, Command}, _From, State = #state{state=RState, cwd=C
handle_call(_Call, _From, State) ->
{noreply, State}.
+%% @private
handle_cast(_Cast, State) ->
{noreply, State}.
+%% @private
handle_info(_Info, State) ->
{noreply, State}.
+%% @private
code_change(_OldVsn, State, _Extra) ->
{ok, State}.
+%% @private
terminate(_Reason, _State) ->
ok.
+%%%%%%%%%%%%%%%
+%%% PRIVATE %%%
+%%%%%%%%%%%%%%%
+
+%% @private runs the actual command and maintains the state changes
+-spec run(atom(), atom(), rebar_state:t(), file:filename()) ->
+ {ok, rebar_state:t()} | {{error, term()}, rebar_state:t()}.
run(Namespace, Command, RState, Cwd) ->
try
case rebar_dir:get_cwd() of
@@ -74,12 +102,17 @@ run(Namespace, Command, RState, Cwd) ->
{{error, {Type, Reason}}, RState}
end.
+%% @private function to display a warning for the feature only once
+-spec maybe_show_warning(#state{}) -> #state{}.
maybe_show_warning(S=#state{show_warning=true}) ->
?WARN("This feature is experimental and may be modified or removed at any time.", []),
S#state{show_warning=false};
maybe_show_warning(State) ->
State.
+%% @private based on a rebar3 state term, reload paths in a way
+%% that makes sense.
+-spec refresh_paths(rebar_state:t()) -> ok.
refresh_paths(RState) ->
ToRefresh = (rebar_state:code_paths(RState, all_deps)
++ [filename:join([rebar_app_info:out_dir(App), "test"])
@@ -116,6 +149,9 @@ refresh_paths(RState) ->
end
end, ToRefresh).
+%% @private from a disk config, reload and reapply with the current
+%% profiles; used to find changes in the config from a prior run.
+-spec refresh_state(rebar_state:t(), file:filename()) -> rebar_state:t().
refresh_state(RState, _Dir) ->
lists:foldl(
fun(F, State) -> F(State) end,
@@ -123,26 +159,28 @@ refresh_state(RState, _Dir) ->
[fun(S) -> rebar_state:apply_profiles(S, rebar_state:current_profiles(RState)) end]
).
+%% @private takes a list of modules and reloads them
+-spec reload_modules([module()]) -> term().
reload_modules([]) -> noop;
-reload_modules(Modules) ->
+reload_modules(Modules) ->
reload_modules(Modules, erlang:function_exported(code, prepare_loading, 1)).
-%% OTP 19 and later -- use atomic loading and ignore unloadable mods
+%% @private reloading modules, when there are modules to actually reload
reload_modules(Modules, true) ->
+ %% OTP 19 and later -- use atomic loading and ignore unloadable mods
case code:prepare_loading(Modules) of
{ok, Prepared} ->
[code:purge(M) || M <- Modules],
code:finish_loading(Prepared);
-
{error, ModRsns} ->
- Blacklist =
+ Blacklist =
lists:foldr(fun({ModError, Error}, Acc) ->
case Error of
- %perhaps cover other cases of failure?
+ % perhaps cover other cases of failure?
on_load_not_allowed ->
reload_modules([ModError], false),
[ModError|Acc];
- _ ->
+ _ ->
?DEBUG("Module ~p failed to atomic load because ~p", [ModError, Error]),
[ModError|Acc]
end
@@ -151,16 +189,15 @@ reload_modules(Modules, true) ->
),
reload_modules(Modules -- Blacklist, true)
end;
-
-%% Older versions, use a more ad-hoc mechanism.
reload_modules(Modules, false) ->
+ %% Older versions, use a more ad-hoc mechanism.
lists:foreach(fun(M) ->
- code:delete(M),
- code:purge(M),
+ code:delete(M),
+ code:purge(M),
case code:load_file(M) of
{module, M} -> ok;
{error, Error} ->
?DEBUG("Module ~p failed to load because ~p", [M, Error])
end
end, Modules
- ). \ No newline at end of file
+ ).
diff --git a/src/rebar_api.erl b/src/rebar_api.erl
index 6ebc500..9d9071e 100644
--- a/src/rebar_api.erl
+++ b/src/rebar_api.erl
@@ -1,4 +1,4 @@
-%%% Packages rebar.hrl features and macros into a more generic API
+%%% @doc Packages rebar.hrl features and macros into a more generic API
%%% that can be used by plugin builders.
-module(rebar_api).
-include("rebar.hrl").
@@ -30,42 +30,62 @@ abort() -> ?FAIL.
abort(Str, Args) -> ?ABORT(Str, Args).
%% @doc Prints to the console, including a newline
+-spec console(string(), list()) -> ok.
console(Str, Args) -> ?CONSOLE(Str, Args).
%% @doc logs with severity `debug'
+-spec debug(string(), list()) -> ok.
debug(Str, Args) -> ?DEBUG(Str, Args).
+
%% @doc logs with severity `info'
+-spec info(string(), list()) -> ok.
info(Str, Args) -> ?INFO(Str, Args).
+
%% @doc logs with severity `warn'
+-spec warn(string(), list()) -> ok.
warn(Str, Args) -> ?WARN(Str, Args).
+
%% @doc logs with severity `error'
+-spec error(string(), list()) -> ok.
error(Str, Args) -> ?ERROR(Str, Args).
-%%
-%% Given env. variable FOO we want to expand all references to
-%% it in InStr. References can have two forms: $FOO and ${FOO}
-%% The end of form $FOO is delimited with whitespace or eol
-%%
+%% @doc Given env. variable `FOO' we want to expand all references to
+%% it in `InStr'. References can have two forms: `$FOO' and `${FOO}'
+%% The end of form `$FOO' is delimited with whitespace or EOL
+-spec expand_env_variable(string(), string(), term()) -> string().
expand_env_variable(InStr, VarName, RawVarValue) ->
rebar_utils:expand_env_variable(InStr, VarName, RawVarValue).
+%% @doc returns the sytem architecture, in strings like
+%% `"19.0.4-x86_64-unknown-linux-gnu-64"'.
+-spec get_arch() -> string().
get_arch() ->
rebar_utils:get_arch().
+%% @doc returns the size of a word on the system, as a string
+-spec wordsize() -> string().
wordsize() ->
rebar_utils:wordsize().
-
-%% Add deps to the code path
+%% @doc Add deps to the code path
+-spec add_deps_to_path(rebar_state:t()) -> ok.
add_deps_to_path(State) ->
code:add_pathsa(rebar_state:code_paths(State, all_deps)).
-%% Revert to only having the beams necessary for running rebar3 and plugins in the path
+%% @doc Revert to only having the beams necessary for running rebar3 and
+%% plugins in the path
+-spec restore_code_path(rebar_state:t()) -> true | {error, term()}.
restore_code_path(State) ->
rebar_utils:cleanup_code_path(rebar_state:code_paths(State, default)).
+%% @doc checks if the current working directory is the base directory
+%% for the project.
+-spec processing_base_dir(rebar_state:t()) -> boolean().
processing_base_dir(State) ->
rebar_dir:processing_base_dir(State).
+%% @doc returns the SSL options adequate for the project based on
+%% its configuration, including for validation of certs.
+-spec ssl_opts(string()) -> [term()].
ssl_opts(Url) ->
rebar_pkg_resource:ssl_opts(Url).
diff --git a/src/rebar_app_discover.erl b/src/rebar_app_discover.erl
index 67acf54..fd55960 100644
--- a/src/rebar_app_discover.erl
+++ b/src/rebar_app_discover.erl
@@ -1,3 +1,5 @@
+%%% @doc utility functions to do the basic discovery of apps
+%%% and layout for the project.
-module(rebar_app_discover).
-export([do/2,
@@ -11,6 +13,10 @@
-include("rebar.hrl").
-include_lib("providers/include/providers.hrl").
+%% @doc from the base directory, find all the applications
+%% at the top level and their dependencies based on the configuration
+%% and profile information.
+-spec do(rebar_state:t(), [file:filename()]) -> rebar_state:t().
do(State, LibDirs) ->
BaseDir = rebar_state:dir(State),
Dirs = [filename:join(BaseDir, LibDir) || LibDir <- LibDirs],
@@ -55,6 +61,10 @@ do(State, LibDirs) ->
end
end, State1, SortedApps).
+%% @doc checks whether there is an app at the top level (and returns its
+%% name) or the 'root' atom in case we're in an umbrella project.
+-spec define_root_app([rebar_app_info:t()], rebar_state:t()) ->
+ root | binary().
define_root_app(Apps, State) ->
RootDir = rebar_dir:root_dir(State),
case ec_lists:find(fun(X) ->
@@ -67,11 +77,17 @@ define_root_app(Apps, State) ->
root
end.
+%% @doc formatting errors from the module.
+-spec format_error(term()) -> iodata().
format_error({module_list, File}) ->
io_lib:format("Error reading module list from ~p~n", [File]);
format_error({missing_module, Module}) ->
io_lib:format("Module defined in app file missing: ~p~n", [Module]).
+%% @doc handles the merging and application of profiles and overrides
+%% for a given application, within its own context.
+-spec merge_deps(rebar_app_info:t(), rebar_state:t()) ->
+ {rebar_app_info:t(), rebar_state:t()}.
merge_deps(AppInfo, State) ->
%% These steps make sure that hooks and artifacts are run in the context of
%% the application they are defined at. If an umbrella structure is used and
@@ -97,6 +113,10 @@ merge_deps(AppInfo, State) ->
{AppInfo2, State2}.
+%% @doc Applies a given profile for an app, ensuring the deps
+%% match the context it will require.
+-spec handle_profile(atom(), binary(), rebar_app_info:t(), rebar_state:t()) ->
+ rebar_state:t().
handle_profile(Profile, Name, AppInfo, State) ->
TopParsedDeps = rebar_state:get(State, {parsed_deps, Profile}, {[], []}),
TopLevelProfileDeps = rebar_state:get(State, {deps, Profile}, []),
@@ -113,6 +133,12 @@ handle_profile(Profile, Name, AppInfo, State) ->
State2 = rebar_state:set(State1, {deps, Profile}, ProfileDeps2),
rebar_state:set(State2, {parsed_deps, Profile}, TopParsedDeps++ParsedDeps).
+%% @doc parses all the known dependencies for a given profile
+-spec parse_profile_deps(Profile, Name, Deps, Opts, rebar_state:t()) -> [rebar_app_info:t()] when
+ Profile :: atom(),
+ Name :: binary(),
+ Deps :: [term()], % TODO: refine types
+ Opts :: term(). % TODO: refine types
parse_profile_deps(Profile, Name, Deps, Opts, State) ->
DepsDir = rebar_prv_install_deps:profile_dep_dir(State, Profile),
Locks = rebar_state:get(State, {locks, Profile}, []),
@@ -123,14 +149,21 @@ parse_profile_deps(Profile, Name, Deps, Opts, State) ->
,Locks
,1).
+%% @doc Find the app-level config and return the state updated
+%% with the relevant app-level data.
+-spec project_app_config(rebar_app_info:t(), rebar_state:t()) ->
+ {Config, rebar_state:t()} when
+ Config :: [any()].
project_app_config(AppInfo, State) ->
C = rebar_config:consult(rebar_app_info:dir(AppInfo)),
Dir = rebar_app_info:dir(AppInfo),
Opts = maybe_reset_hooks(Dir, rebar_state:opts(State), State),
{C, rebar_state:opts(State, Opts)}.
-%% Here we check if the app is at the root of the project.
+%% @private Check if the app is at the root of the project.
%% If it is, then drop the hooks from the config so they aren't run twice
+-spec maybe_reset_hooks(file:filename(), Opts, rebar_state:t()) -> Opts when
+ Opts :: rebar_dict().
maybe_reset_hooks(Dir, Opts, State) ->
case ec_file:real_dir_path(rebar_dir:root_dir(State)) of
Dir ->
@@ -139,17 +172,22 @@ maybe_reset_hooks(Dir, Opts, State) ->
Opts
end.
+%% @doc make the hooks empty for a given set of options
+-spec reset_hooks(Opts) -> Opts when Opts :: rebar_dict().
reset_hooks(Opts) ->
lists:foldl(fun(Key, OptsAcc) ->
rebar_opts:set(OptsAcc, Key, [])
end, Opts, [post_hooks, pre_hooks, provider_hooks, artifacts]).
--spec all_app_dirs(list(file:name())) -> list(file:name()).
+%% @doc find the directories for all apps
+-spec all_app_dirs([file:name()]) -> [file:name()].
all_app_dirs(LibDirs) ->
lists:flatmap(fun(LibDir) ->
app_dirs(LibDir)
end, LibDirs).
+%% @doc find the directories based on the library directories
+-spec app_dirs([file:name()]) -> [file:name()].
app_dirs(LibDir) ->
Path1 = filename:join([LibDir,
"src",
@@ -168,32 +206,51 @@ app_dirs(LibDir) ->
[app_dir(File) || File <- Files] ++ Acc
end, [], [Path1, Path2, Path3])).
+%% @doc find all apps that haven't been built in a list of directories
+-spec find_unbuilt_apps([file:filename_all()]) -> [rebar_app_info:t()].
find_unbuilt_apps(LibDirs) ->
find_apps(LibDirs, invalid).
+%% @doc for each directory passed, find all apps that are valid.
+%% Returns all the related app info records.
-spec find_apps([file:filename_all()]) -> [rebar_app_info:t()].
find_apps(LibDirs) ->
find_apps(LibDirs, valid).
+%% @doc for each directory passed, find all apps according
+%% to the validity rule passed in. Returns all the related
+%% app info records.
-spec find_apps([file:filename_all()], valid | invalid | all) -> [rebar_app_info:t()].
find_apps(LibDirs, Validate) ->
rebar_utils:filtermap(fun(AppDir) ->
find_app(AppDir, Validate)
end, all_app_dirs(LibDirs)).
+%% @doc check that a given app in a directory is there, and whether it's
+%% valid or not based on the second argument. Returns the related
+%% app info record.
-spec find_app(file:filename_all(), valid | invalid | all) -> {true, rebar_app_info:t()} | false.
find_app(AppDir, Validate) ->
find_app(rebar_app_info:new(), AppDir, Validate).
+%% @doc check that a given app in a directory is there, and whether it's
+%% valid or not based on the second argument. Returns the related
+%% app info record.
+-spec find_app(rebar_app_info:t(), file:filename_all(), valid | invalid | all) ->
+ {true, rebar_app_info:t()} | false.
find_app(AppInfo, AppDir, Validate) ->
AppFile = filelib:wildcard(filename:join([AppDir, "ebin", "*.app"])),
AppSrcFile = filelib:wildcard(filename:join([AppDir, "src", "*.app.src"])),
AppSrcScriptFile = filelib:wildcard(filename:join([AppDir, "src", "*.app.src.script"])),
try_handle_app_file(AppInfo, AppFile, AppDir, AppSrcFile, AppSrcScriptFile, Validate).
+%% @doc find the directory that an appfile has
+-spec app_dir(file:filename()) -> file:filename().
app_dir(AppFile) ->
filename:join(rebar_utils:droplast(filename:split(filename:dirname(AppFile)))).
+%% @doc populates an app info record based on an app directory and its
+%% app file.
-spec create_app_info(rebar_app_info:t(), file:name(), file:name()) -> rebar_app_info:t().
create_app_info(AppInfo, AppDir, AppFile) ->
[{application, AppName, AppDetails}] = rebar_config:consult_app_file(AppFile),
@@ -215,8 +272,15 @@ create_app_info(AppInfo, AppDir, AppFile) ->
end,
rebar_app_info:dir(rebar_app_info:valid(AppInfo2, Valid), AppDir).
-%% Read in and parse the .app file if it is availabe. Do the same for
+%% @doc Read in and parse the .app file if it is availabe. Do the same for
%% the .app.src file if it exists.
+-spec try_handle_app_file(AppInfo, AppFile, AppDir, AppSrcFile, AppSrcScriptFile, valid | invalid | all) ->
+ {true, AppInfo} | false when
+ AppInfo :: rebar_app_info:t(),
+ AppFile :: file:filename(),
+ AppDir :: file:filename(),
+ AppSrcFile :: file:filename(),
+ AppSrcScriptFile :: file:filename().
try_handle_app_file(AppInfo, [], AppDir, [], AppSrcScriptFile, Validate) ->
try_handle_app_src_file(AppInfo, [], AppDir, AppSrcScriptFile, Validate);
try_handle_app_file(AppInfo, [], AppDir, AppSrcFile, _, Validate) ->
@@ -260,7 +324,14 @@ try_handle_app_file(AppInfo0, [File], AppDir, AppSrcFile, _, Validate) ->
try_handle_app_file(_AppInfo, Other, _AppDir, _AppSrcFile, _, _Validate) ->
throw({error, {multiple_app_files, Other}}).
-%% Read in the .app.src file if we aren't looking for a valid (already built) app
+%% @doc Read in the .app.src file if we aren't looking for a valid (already
+%% built) app.
+-spec try_handle_app_src_file(AppInfo, AppFile, AppDir, AppSrcFile, valid | invalid | all) ->
+ {true, AppInfo} | false when
+ AppInfo :: rebar_app_info:t(),
+ AppFile :: file:filename(),
+ AppDir :: file:filename(),
+ AppSrcFile :: file:filename().
try_handle_app_src_file(_AppInfo, _, _AppDir, [], _Validate) ->
false;
try_handle_app_src_file(_AppInfo, _, _AppDir, _AppSrcFile, valid) ->
@@ -277,9 +348,13 @@ try_handle_app_src_file(AppInfo, _, AppDir, [File], Validate) when Validate =:=
try_handle_app_src_file(_AppInfo, _, _AppDir, Other, _Validate) ->
throw({error, {multiple_app_files, Other}}).
+%% @doc checks whether the given app is not blacklisted in the config.
+-spec enable(rebar_state:t(), rebar_app_info:t()) -> boolean().
enable(State, AppInfo) ->
not lists:member(to_atom(rebar_app_info:name(AppInfo)),
rebar_state:get(State, excluded_apps, [])).
+%% @private convert a binary to an atom.
+-spec to_atom(binary()) -> atom().
to_atom(Bin) ->
list_to_atom(binary_to_list(Bin)).
diff --git a/src/rebar_app_info.erl b/src/rebar_app_info.erl
index 4f19d77..fdaadb8 100644
--- a/src/rebar_app_info.erl
+++ b/src/rebar_app_info.erl
@@ -103,11 +103,13 @@
new() ->
#app_info_t{}.
+%% @doc Build a new app info value with only the app name set.
-spec new(atom() | binary() | string()) ->
{ok, t()}.
new(AppName) ->
{ok, #app_info_t{name=ec_cnv:to_binary(AppName)}}.
+%% @doc Build a new app info value with only the name and version set.
-spec new(atom() | binary() | string(), binary() | string()) ->
{ok, t()}.
new(AppName, Vsn) ->
@@ -144,6 +146,9 @@ new(Parent, AppName, Vsn, Dir, Deps) ->
out_dir=ec_cnv:to_list(Dir),
deps=Deps}}.
+%% @doc update the opts based on the contents of a config
+%% file for the app
+-spec update_opts(t(), rebar_dict(), [any()]) -> t().
update_opts(AppInfo, Opts, Config) ->
LockDeps = case resource_type(AppInfo) of
pkg ->
@@ -163,6 +168,8 @@ update_opts(AppInfo, Opts, Config) ->
AppInfo#app_info_t{opts=NewOpts
,default=NewOpts}.
+%% @private extract the deps for an app in `Dir' based on its config file data
+-spec deps_from_config(file:filename(), [any()]) -> [{tuple(), any()}, ...].
deps_from_config(Dir, Config) ->
case rebar_config:consult_lock_file(filename:join(Dir, ?LOCK_FILE)) of
[] ->
@@ -184,30 +191,48 @@ discover(Dir) ->
not_found
end.
+%% @doc get the name of the app.
-spec name(t()) -> binary().
name(#app_info_t{name=Name}) ->
Name.
+%% @doc set the name of the app.
-spec name(t(), atom() | binary() | string()) -> t().
name(AppInfo=#app_info_t{}, AppName) ->
AppInfo#app_info_t{name=ec_cnv:to_binary(AppName)}.
+%% @doc get the dictionary of options for the app.
+-spec opts(t()) -> rebar_dict().
opts(#app_info_t{opts=Opts}) ->
Opts.
+%% @doc set the dictionary of options for the app.
+-spec opts(t(), rebar_dict()) -> t().
opts(AppInfo, Opts) ->
AppInfo#app_info_t{opts=Opts}.
+%% @doc get the dictionary of options under the default profile.
+%% Represents a root set prior to applying other profiles.
+-spec default(t()) -> rebar_dict().
default(#app_info_t{default=Default}) ->
Default.
+%% @doc set the dictionary of options under the default profile.
+%% Useful when re-applying profile.
+-spec default(t(), rebar_dict()) -> t().
default(AppInfo, Default) ->
AppInfo#app_info_t{default=Default}.
+%% @doc look up a value in the dictionary of options; fails if
+%% the key for it does not exist.
+-spec get(t(), term()) -> term().
get(AppInfo, Key) ->
{ok, Value} = dict:find(Key, AppInfo#app_info_t.opts),
Value.
+%% @doc look up a value in the dictionary of options; returns
+%% a `Default' value otherwise.
+-spec get(t(), term(), term()) -> term().
get(AppInfo, Key, Default) ->
case dict:find(Key, AppInfo#app_info_t.opts) of
{ok, Value} ->
@@ -216,10 +241,12 @@ get(AppInfo, Key, Default) ->
Default
end.
+%% @doc sets a given value in the dictionary of options for the app.
-spec set(t(), any(), any()) -> t().
set(AppInfo=#app_info_t{opts=Opts}, Key, Value) ->
AppInfo#app_info_t{opts = dict:store(Key, Value, Opts)}.
+%% @doc finds the .app.src file for an app, if any.
-spec app_file_src(t()) -> file:filename_all() | undefined.
app_file_src(#app_info_t{app_file_src=undefined, dir=Dir, name=Name}) ->
AppFileSrc = filename:join([ec_cnv:to_list(Dir), "src", ec_cnv:to_list(Name)++".app.src"]),
@@ -232,12 +259,15 @@ app_file_src(#app_info_t{app_file_src=undefined, dir=Dir, name=Name}) ->
app_file_src(#app_info_t{app_file_src=AppFileSrc}) ->
ec_cnv:to_list(AppFileSrc).
+%% @doc sets the .app.src file for an app. An app without such a file
+%% can explicitly be set with `undefined'.
-spec app_file_src(t(), file:filename_all() | undefined) -> t().
app_file_src(AppInfo=#app_info_t{}, undefined) ->
AppInfo#app_info_t{app_file_src=undefined};
app_file_src(AppInfo=#app_info_t{}, AppFileSrc) ->
AppInfo#app_info_t{app_file_src=ec_cnv:to_list(AppFileSrc)}.
+%% @doc finds the .app.src.script file for an app, if any.
-spec app_file_src_script(t()) -> file:filename_all() | undefined.
app_file_src_script(#app_info_t{app_file_src_script=undefined, dir=Dir, name=Name}) ->
AppFileSrcScript = filename:join([ec_cnv:to_list(Dir), "src", ec_cnv:to_list(Name)++".app.src.script"]),
@@ -250,12 +280,15 @@ app_file_src_script(#app_info_t{app_file_src_script=undefined, dir=Dir, name=Nam
app_file_src_script(#app_info_t{app_file_src_script=AppFileSrcScript}) ->
ec_cnv:to_list(AppFileSrcScript).
+%% @doc sets the .app.src.script file for an app. An app without such a file
+%% can explicitly be set with `undefined'.
-spec app_file_src_script(t(), file:filename_all()) -> t().
app_file_src_script(AppInfo=#app_info_t{}, undefined) ->
AppInfo#app_info_t{app_file_src_script=undefined};
app_file_src_script(AppInfo=#app_info_t{}, AppFileSrcScript) ->
AppInfo#app_info_t{app_file_src_script=ec_cnv:to_list(AppFileSrcScript)}.
+%% @doc finds the .app file for an app, if any.
-spec app_file(t()) -> file:filename_all() | undefined.
app_file(#app_info_t{app_file=undefined, out_dir=Dir, name=Name}) ->
AppFile = filename:join([ec_cnv:to_list(Dir), "ebin", ec_cnv:to_list(Name)++".app"]),
@@ -268,10 +301,13 @@ app_file(#app_info_t{app_file=undefined, out_dir=Dir, name=Name}) ->
app_file(#app_info_t{app_file=AppFile}) ->
AppFile.
+%% @doc sets the .app file for an app.
-spec app_file(t(), file:filename_all()) -> t().
app_file(AppInfo=#app_info_t{}, AppFile) ->
AppInfo#app_info_t{app_file=AppFile}.
+%% @doc returns the information stored in the app's app file,
+%% or if none, from the .app.src file.
-spec app_details(t()) -> list().
app_details(AppInfo=#app_info_t{app_details=[]}) ->
case app_file(AppInfo) of
@@ -290,59 +326,83 @@ app_details(AppInfo=#app_info_t{app_details=[]}) ->
app_details(#app_info_t{app_details=AppDetails}) ->
AppDetails.
+%% @doc stores the information that would be returned from the
+%% app file, when reading from `app_details/1'.
-spec app_details(t(), list()) -> t().
app_details(AppInfo=#app_info_t{}, AppDetails) ->
AppInfo#app_info_t{app_details=AppDetails}.
+%% @doc returns the app's parent in the dep tree.
+-spec parent(t()) -> root | binary().
parent(#app_info_t{parent=Parent}) ->
Parent.
+%% @doc sets the app's parent.
-spec parent(t(), binary() | root) -> t().
parent(AppInfo=#app_info_t{}, Parent) ->
AppInfo#app_info_t{parent=Parent}.
+%% @doc returns the original version of the app (unevaluated if
+%% asking for a semver)
-spec original_vsn(t()) -> string().
original_vsn(#app_info_t{original_vsn=Vsn}) ->
Vsn.
+%% @doc stores the original version of the app (unevaluated if
+%% asking for a semver)
-spec original_vsn(t(), string()) -> t().
original_vsn(AppInfo=#app_info_t{}, Vsn) ->
AppInfo#app_info_t{original_vsn=Vsn}.
+%% @doc returns the list of applications the app depends on.
-spec applications(t()) -> list().
applications(#app_info_t{applications=Applications}) ->
Applications.
+%% @doc sets the list of applications the app depends on.
+%% Should be obtained from the app file.
-spec applications(t(), list()) -> t().
applications(AppInfo=#app_info_t{}, Applications) ->
AppInfo#app_info_t{applications=Applications}.
+%% @doc returns the list of active profiles
-spec profiles(t()) -> list().
profiles(#app_info_t{profiles=Profiles}) ->
Profiles.
+%% @doc sets the list of active profiles
-spec profiles(t(), list()) -> t().
profiles(AppInfo=#app_info_t{}, Profiles) ->
AppInfo#app_info_t{profiles=Profiles}.
+%% @doc returns the list of dependencies
-spec deps(t()) -> list().
deps(#app_info_t{deps=Deps}) ->
Deps.
+%% @doc sets the list of dependencies.
-spec deps(t(), list()) -> t().
deps(AppInfo=#app_info_t{}, Deps) ->
AppInfo#app_info_t{deps=Deps}.
-dep_level(AppInfo=#app_info_t{}, Level) ->
- AppInfo#app_info_t{dep_level=Level}.
-
+%% @doc returns the level the app has in the lock files or in the
+%% dep tree.
+-spec dep_level(t()) -> non_neg_integer().
dep_level(#app_info_t{dep_level=Level}) ->
Level.
+%% @doc sets the level the app has in the lock files or in the
+%% dep tree.
+-spec dep_level(t(), non_neg_integer()) -> t().
+dep_level(AppInfo=#app_info_t{}, Level) ->
+ AppInfo#app_info_t{dep_level=Level}.
+
+%% @doc returns the directory that contains the app.
-spec dir(t()) -> file:name().
dir(#app_info_t{dir=Dir}) ->
Dir.
+%% @doc sets the directory that contains the app.
-spec dir(t(), file:name()) -> t().
dir(AppInfo=#app_info_t{out_dir=undefined}, Dir) ->
AppInfo#app_info_t{dir=ec_cnv:to_list(Dir),
@@ -350,54 +410,69 @@ dir(AppInfo=#app_info_t{out_dir=undefined}, Dir) ->
dir(AppInfo=#app_info_t{}, Dir) ->
AppInfo#app_info_t{dir=ec_cnv:to_list(Dir)}.
+%% @doc returns the directory where build artifacts for the app
+%% should go
-spec out_dir(t()) -> file:name().
out_dir(#app_info_t{out_dir=OutDir}) ->
OutDir.
+%% @doc sets the directory where build artifacts for the app
+%% should go
-spec out_dir(t(), file:name()) -> t().
out_dir(AppInfo=#app_info_t{}, OutDir) ->
AppInfo#app_info_t{out_dir=ec_cnv:to_list(OutDir)}.
+%% @doc gets the directory where ebin files for the app should go
-spec ebin_dir(t()) -> file:name().
ebin_dir(#app_info_t{out_dir=OutDir}) ->
ec_cnv:to_list(filename:join(OutDir, "ebin")).
+%% @doc gets the directory where private files for the app should go
-spec priv_dir(t()) -> file:name().
priv_dir(#app_info_t{out_dir=OutDir}) ->
ec_cnv:to_list(filename:join(OutDir, "priv")).
--spec resource_type(t(), pkg | src) -> t().
-resource_type(AppInfo=#app_info_t{}, Type) ->
- AppInfo#app_info_t{resource_type=Type}.
-
+%% @doc returns whether the app is source app or a package app.
-spec resource_type(t()) -> pkg | src.
resource_type(#app_info_t{resource_type=ResourceType}) ->
ResourceType.
--spec source(t(), string() | tuple() | checkout) -> t().
-source(AppInfo=#app_info_t{}, Source) ->
- AppInfo#app_info_t{source=Source}.
+%% @doc sets whether the app is source app or a package app.
+-spec resource_type(t(), pkg | src) -> t().
+resource_type(AppInfo=#app_info_t{}, Type) ->
+ AppInfo#app_info_t{resource_type=Type}.
+%% @doc finds the source specification for the app
-spec source(t()) -> string() | tuple().
source(#app_info_t{source=Source}) ->
Source.
--spec is_lock(t(), boolean()) -> t().
-is_lock(AppInfo=#app_info_t{}, IsLock) ->
- AppInfo#app_info_t{is_lock=IsLock}.
+%% @doc sets the source specification for the app
+-spec source(t(), string() | tuple() | checkout) -> t().
+source(AppInfo=#app_info_t{}, Source) ->
+ AppInfo#app_info_t{source=Source}.
+%% @doc returns the lock status for the app
-spec is_lock(t()) -> boolean().
is_lock(#app_info_t{is_lock=IsLock}) ->
IsLock.
--spec is_checkout(t(), boolean()) -> t().
-is_checkout(AppInfo=#app_info_t{}, IsCheckout) ->
- AppInfo#app_info_t{is_checkout=IsCheckout}.
+%% @doc sets the lock status for the app
+-spec is_lock(t(), boolean()) -> t().
+is_lock(AppInfo=#app_info_t{}, IsLock) ->
+ AppInfo#app_info_t{is_lock=IsLock}.
+%% @doc returns whether the app is a checkout app or not
-spec is_checkout(t()) -> boolean().
is_checkout(#app_info_t{is_checkout=IsCheckout}) ->
IsCheckout.
+%% @doc sets whether the app is a checkout app or not
+-spec is_checkout(t(), boolean()) -> t().
+is_checkout(AppInfo=#app_info_t{}, IsCheckout) ->
+ AppInfo#app_info_t{is_checkout=IsCheckout}.
+
+%% @doc returns whether the app is valid (built) or not
-spec valid(t()) -> boolean().
valid(AppInfo=#app_info_t{valid=undefined}) ->
case rebar_app_utils:validate_application_info(AppInfo) =:= true
@@ -410,14 +485,22 @@ valid(AppInfo=#app_info_t{valid=undefined}) ->
valid(#app_info_t{valid=Valid}) ->
Valid.
+%% @doc sets whether the app is valid (built) or not. If left unset,
+%% rebar3 will do the detection of the status itself.
-spec valid(t(), boolean()) -> t().
valid(AppInfo=#app_info_t{}, Valid) ->
AppInfo#app_info_t{valid=Valid}.
+%% @doc checks whether the app can be built with the current
+%% Erlang/OTP version. If the check fails, the function raises
+%% an exception and displays an error.
+-spec verify_otp_vsn(t()) -> ok | no_return().
verify_otp_vsn(AppInfo) ->
rebar_utils:check_min_otp_version(rebar_app_info:get(AppInfo, minimum_otp_vsn, undefined)),
rebar_utils:check_blacklisted_otp_versions(rebar_app_info:get(AppInfo, blacklisted_otp_vsns, [])).
+%% @doc checks whether all the build artifacts for an app to be considered
+%% valid are present.
-spec has_all_artifacts(#app_info_t{}) -> true | {false, file:filename()}.
has_all_artifacts(AppInfo) ->
Artifacts = rebar_app_info:get(AppInfo, artifacts, []),
@@ -427,6 +510,10 @@ has_all_artifacts(AppInfo) ->
,{out_dir, OutDir}],
all(OutDir, Context, Artifacts).
+%% @private checks that all files/artifacts in the directory are found.
+%% Template evaluation must happen and a bbmustache context needs to
+%% be provided.
+-spec all(file:filename(), term(), [string()]) -> true | {false, string()}.
all(_, _, []) ->
true;
all(Dir, Context, [File|Artifacts]) ->
@@ -441,15 +528,23 @@ all(Dir, Context, [File|Artifacts]) ->
%%%%%
+%% @doc given a set of override rules, modify the app info accordingly
+-spec apply_overrides(list(), t()) -> t().
apply_overrides(Overrides, AppInfo) ->
Name = binary_to_atom(rebar_app_info:name(AppInfo), utf8),
Opts = rebar_opts:apply_overrides(opts(AppInfo), Name, Overrides),
AppInfo#app_info_t{default=Opts, opts=Opts}.
+%% @doc adds a new profile with its own config to the app data
+-spec add_to_profile(t(), atom(), [{_,_}]) -> t().
add_to_profile(AppInfo, Profile, KVs) when is_atom(Profile), is_list(KVs) ->
Opts = rebar_opts:add_to_profile(opts(AppInfo), Profile, KVs),
AppInfo#app_info_t{opts=Opts}.
+%% @doc applies and merges the profile configuration in the specified order
+%% of profiles (or for a single profile) and returns an app info record
+%% with the resulting configuration
+-spec apply_profiles(t(), atom() | [atom(),...]) -> t().
apply_profiles(AppInfo, Profile) when not is_list(Profile) ->
apply_profiles(AppInfo, [Profile]);
apply_profiles(AppInfo, [default]) ->
@@ -481,9 +576,13 @@ apply_profiles(AppInfo=#app_info_t{default = Defaults, profiles=CurrentProfiles}
end, Defaults, AppliedProfiles),
AppInfo#app_info_t{profiles = AppliedProfiles, opts=NewOpts}.
+%% @private drops duplicated profile definitions
+-spec deduplicate(list()) -> list().
deduplicate(Profiles) ->
do_deduplicate(lists:reverse(Profiles), []).
+%% @private drops duplicated profile definitions
+-spec do_deduplicate(list(), list()) -> list().
do_deduplicate([], Acc) ->
Acc;
do_deduplicate([Head | Rest], Acc) ->
diff --git a/src/rebar_app_utils.erl b/src/rebar_app_utils.erl
index 847b0a5..7154999 100644
--- a/src/rebar_app_utils.erl
+++ b/src/rebar_app_utils.erl
@@ -44,10 +44,14 @@
%% Public API
%% ===================================================================
+%% @doc finds the proper app info record for a given app name in a list of
+%% such records.
-spec find(binary(), [rebar_app_info:t()]) -> {ok, rebar_app_info:t()} | error.
find(Name, Apps) ->
ec_lists:find(fun(App) -> rebar_app_info:name(App) =:= Name end, Apps).
+%% @doc finds the proper app info record for a given app name at a given version
+%% in a list of such records.
-spec find(binary(), binary(), [rebar_app_info:t()]) -> {ok, rebar_app_info:t()} | error.
find(Name, Vsn, Apps) ->
ec_lists:find(fun(App) ->
@@ -55,11 +59,18 @@ find(Name, Vsn, Apps) ->
andalso rebar_app_info:original_vsn(App) =:= Vsn
end, Apps).
+%% @doc checks if a given file is .app.src file
is_app_src(Filename) ->
%% If removing the extension .app.src yields a shorter name,
%% this is an .app.src file.
Filename =/= filename:rootname(Filename, ".app.src").
+%% @doc translates the name of the .app.src[.script] file to where
+%% its .app counterpart should be stored.
+-spec app_src_to_app(OutDir, SrcFilename) -> OutFilename when
+ OutDir :: file:filename(),
+ SrcFilename :: file:filename(),
+ OutFilename :: file:filename().
app_src_to_app(OutDir, Filename) ->
AppFile =
case lists:suffix(".app.src", Filename) of
@@ -72,10 +83,16 @@ app_src_to_app(OutDir, Filename) ->
filelib:ensure_dir(AppFile),
AppFile.
+%% @doc checks whether the .app file has all the required data to be valid,
+%% and cross-references it with compiled modules on disk
-spec validate_application_info(rebar_app_info:t()) -> boolean().
validate_application_info(AppInfo) ->
validate_application_info(AppInfo, rebar_app_info:app_details(AppInfo)).
+%% @doc checks whether the .app file has all the required data to be valid
+%% and cross-references it with compiled modules on disk.
+%% The app info is passed explicitly as a second argument.
+-spec validate_application_info(rebar_app_info:t(), list()) -> boolean().
validate_application_info(AppInfo, AppDetail) ->
EbinDir = rebar_app_info:ebin_dir(AppInfo),
case rebar_app_info:app_file(AppInfo) of
@@ -90,13 +107,37 @@ validate_application_info(AppInfo, AppDetail) ->
end
end.
--spec parse_deps(binary(), list(), rebar_state:t(), list(), integer()) -> [rebar_app_info:t()].
+%% @doc parses all dependencies from the root of the project
+-spec parse_deps(Dir, Deps, State, Locks, Level) -> [rebar_app_info:t()] when
+ Dir :: file:filename(),
+ Deps :: [tuple() | atom() | binary()], % TODO: meta to source() | lock()
+ State :: rebar_state:t(),
+ Locks :: [tuple()], % TODO: meta to [lock()]
+ Level :: non_neg_integer().
parse_deps(DepsDir, Deps, State, Locks, Level) ->
parse_deps(root, DepsDir, Deps, State, Locks, Level).
+%% @doc runs `parse_dep/6' for a set of dependencies.
+-spec parse_deps(Parent, Dir, Deps, State, Locks, Level) -> [rebar_app_info:t()] when
+ Parent :: root | binary(),
+ Dir :: file:filename(),
+ Deps :: [tuple() | atom() | binary()], % TODO: meta to source() | lock()
+ State :: rebar_state:t(),
+ Locks :: [tuple()], % TODO: meta to [lock()]
+ Level :: non_neg_integer().
parse_deps(Parent, DepsDir, Deps, State, Locks, Level) ->
[parse_dep(Dep, Parent, DepsDir, State, Locks, Level) || Dep <- Deps].
+%% @doc for a given dep, return its app info record. The function
+%% also has to choose whether to define the dep from its immediate spec
+%% (if it is a newer thing) or from the locks specified in the lockfile.
+-spec parse_dep(Dep, Parent, Dir, State, Locks, Level) -> rebar_app_info:t() when
+ Dep :: tuple() | atom() | binary(), % TODO: meta to source() | lock()
+ Parent :: root | binary(),
+ Dir :: file:filename(),
+ State :: rebar_state:t(),
+ Locks :: [tuple()], % TODO: meta to [lock()]
+ Level :: non_neg_integer().
parse_dep(Dep, Parent, DepsDir, State, Locks, Level) ->
Name = case Dep of
Dep when is_tuple(Dep) ->
@@ -117,6 +158,14 @@ parse_dep(Dep, Parent, DepsDir, State, Locks, Level) ->
end
end.
+%% @doc converts a dependency definition and a location for it on disk
+%% into an app info tuple representing it.
+-spec parse_dep(Parent, Dep, Dir, IsLock, State) -> rebar_app_info:t() when
+ Parent :: root | binary(),
+ Dep :: tuple() | atom() | binary(), % TODO: meta to source() | lock()
+ Dir :: file:filename(),
+ IsLock :: boolean(),
+ State :: rebar_state:t().
parse_dep(Parent, {Name, Vsn, {pkg, PkgName}}, DepsDir, IsLock, State) ->
{PkgName1, PkgVsn} = {ec_cnv:to_binary(PkgName), ec_cnv:to_binary(Vsn)},
dep_to_app(Parent, DepsDir, Name, PkgVsn, {pkg, PkgName1, PkgVsn, undefined}, IsLock, State);
@@ -152,6 +201,16 @@ parse_dep(Parent, {Name, Source, Level}, DepsDir, IsLock, State) when is_tuple(S
parse_dep(_, Dep, _, _, _) ->
throw(?PRV_ERROR({parse_dep, Dep})).
+%% @doc convert a dependency that has just been fetched into
+%% an app info record related to it
+-spec dep_to_app(Parent, Dir, Name, Vsn, Source, IsLock, State) -> rebar_app_info:t() when
+ Parent :: root | binary(),
+ Dir :: file:filename(),
+ Name :: binary(),
+ Vsn :: iodata() | undefined,
+ Source :: tuple(),
+ IsLock :: boolean(),
+ State :: rebar_state:t().
dep_to_app(Parent, DepsDir, Name, Vsn, Source, IsLock, State) ->
CheckoutsDir = ec_cnv:to_list(rebar_dir:checkouts_dir(State, Name)),
AppInfo = case rebar_app_info:discover(CheckoutsDir) of
@@ -166,7 +225,7 @@ dep_to_app(Parent, DepsDir, Name, Vsn, Source, IsLock, State) ->
not_found ->
rebar_app_info:new(Parent, Name, Vsn, Dir, [])
end,
- update_source(AppInfo0, Source, State)
+ update_source(AppInfo0, Source, State)
end,
C = rebar_config:consult(rebar_app_info:dir(AppInfo)),
AppInfo1 = rebar_app_info:update_opts(AppInfo, rebar_app_info:opts(AppInfo), C),
@@ -177,6 +236,11 @@ dep_to_app(Parent, DepsDir, Name, Vsn, Source, IsLock, State) ->
AppInfo5 = rebar_app_info:profiles(AppInfo4, [default]),
rebar_app_info:is_lock(AppInfo5, IsLock).
+%% @doc sets the source for a given dependency or app along with metadata
+%% around version if required.
+-spec update_source(rebar_app_info:t(), Source, rebar_state:t()) ->
+ rebar_app_info:t() when
+ Source :: tuple() | atom() | binary(). % TODO: meta to source()
update_source(AppInfo, {pkg, PkgName, PkgVsn, Hash}, State) ->
{PkgName1, PkgVsn1} = case PkgVsn of
undefined ->
@@ -203,6 +267,9 @@ update_source(AppInfo, {pkg, PkgName, PkgVsn, Hash}, State) ->
update_source(AppInfo, Source, _State) ->
rebar_app_info:source(AppInfo, Source).
+%% @doc grab the checksum for a given package
+-spec fetch_checksum(atom(), string(), iodata() | undefined, rebar_state:t()) ->
+ iodata() | no_return().
fetch_checksum(PkgName, PkgVsn, Hash, State) ->
try
rebar_packages:registry_checksum({pkg, PkgName, PkgVsn, Hash}, State)
@@ -213,6 +280,8 @@ fetch_checksum(PkgName, PkgVsn, Hash, State) ->
rebar_packages:registry_checksum({pkg, PkgName, PkgVsn, Hash}, State)
end.
+%% @doc convert a given exception's payload into an io description.
+-spec format_error(any()) -> iolist().
format_error({missing_package, Package}) ->
io_lib:format("Package not found in registry: ~s", [Package]);
format_error({parse_dep, Dep}) ->
@@ -224,6 +293,10 @@ format_error(Error) ->
%% Internal functions
%% ===================================================================
+%% @private find the correct version of a package based on the version
+%% and name passed in.
+-spec get_package(binary(), binary() | string(), rebar_state:t()) ->
+ term() | no_return().
get_package(Dep, Vsn, State) ->
case rebar_packages:find_highest_matching(Dep, Vsn, ?PACKAGE_TABLE, State) of
{ok, HighestDepVsn} ->
@@ -232,6 +305,8 @@ get_package(Dep, Vsn, State) ->
throw(?PRV_ERROR({missing_package, ec_cnv:to_binary(Dep)}))
end.
+%% @private checks that all the beam files have been properly
+%% created.
-spec has_all_beams(file:filename_all(), [module()]) ->
true | ?PRV_ERROR({missing_module, module()}).
has_all_beams(EbinDir, [Module | ModuleList]) ->
diff --git a/src/rebar_base_compiler.erl b/src/rebar_base_compiler.erl
index 9aa7419..dcb1975 100644
--- a/src/rebar_base_compiler.erl
+++ b/src/rebar_base_compiler.erl
@@ -36,21 +36,65 @@
format_error_source/2]).
-define(DEFAULT_COMPILER_SOURCE_FORMAT, relative).
+-type desc() :: term().
+-type loc() :: {line(), col()} | line().
+-type line() :: integer().
+-type col() :: integer().
+-type err_or_warn() :: {module(), desc()} | {loc(), module(), desc()}.
+
+-type compile_fn_ret() :: ok | {ok, [string()]} | skipped | term().
+-type compile_fn() :: fun((file:filename(), [{_,_}] | rebar_dict()) -> compile_fn_ret()).
+-type compile_fn3() :: fun((file:filename(), file:filename(), [{_,_}] | rebar_dict())
+ -> compile_fn_ret()).
+-type error_tuple() :: {error, [string()], [string()]}.
+-export_type([compile_fn/0, compile_fn_ret/0, error_tuple/0]).
%% ===================================================================
%% Public API
%% ===================================================================
+%% @doc Runs a compile job, applying `compile_fn()' to all files,
+%% starting with `First' files, and then `RestFiles'.
+-spec run(rebar_dict() | [{_,_}] , [First], [Next], compile_fn()) ->
+ compile_fn_ret() when
+ First :: file:filename(),
+ Next :: file:filename().
run(Config, FirstFiles, RestFiles, CompileFn) ->
%% Compile the first files in sequence
compile_each(FirstFiles++RestFiles, Config, CompileFn).
+%% @doc Runs a compile job, applying `compile_fn3()' to all files,
+%% starting with `First' files, and then the other content of `SourceDir'.
+%% Files looked for are those ending in `SourceExt'. Results of the
+%% compilation are put in `TargetDir' with the base file names
+%% postfixed with `SourceExt'.
+-spec run(rebar_dict() | [{_,_}] , [First], SourceDir, SourceExt,
+ TargetDir, TargetExt, compile_fn3()) -> compile_fn_ret() when
+ First :: file:filename(),
+ SourceDir :: file:filename(),
+ TargetDir :: file:filename(),
+ SourceExt :: string(),
+ TargetExt :: string().
run(Config, FirstFiles, SourceDir, SourceExt, TargetDir, TargetExt,
Compile3Fn) ->
run(Config, FirstFiles, SourceDir, SourceExt, TargetDir, TargetExt,
Compile3Fn, [check_last_mod]).
+%% @doc Runs a compile job, applying `compile_fn3()' to all files,
+%% starting with `First' files, and then the other content of `SourceDir'.
+%% Files looked for are those ending in `SourceExt'. Results of the
+%% compilation are put in `TargetDir' with the base file names
+%% postfixed with `SourceExt'.
+%% Additional compile options can be passed in the last argument as
+%% a proplist.
+-spec run(rebar_dict() | [{_,_}] , [First], SourceDir, SourceExt,
+ TargetDir, TargetExt, compile_fn3(), [term()]) -> compile_fn_ret() when
+ First :: file:filename(),
+ SourceDir :: file:filename(),
+ TargetDir :: file:filename(),
+ SourceExt :: string(),
+ TargetExt :: string().
run(Config, FirstFiles, SourceDir, SourceExt, TargetDir, TargetExt,
Compile3Fn, Opts) ->
%% Convert simple extension to proper regex
@@ -73,13 +117,26 @@ run(Config, FirstFiles, SourceDir, SourceExt, TargetDir, TargetExt,
simple_compile_wrapper(S, Target, Compile3Fn, C, CheckLastMod)
end).
+%% @doc Format good compiler results with warnings to work with
+%% module internals. Assumes that warnings are not treated as errors.
+-spec ok_tuple(file:filename(), [string()]) -> {ok, [string()]}.
ok_tuple(Source, Ws) ->
{ok, format_warnings(Source, Ws)}.
+%% @doc format error and warning strings for a given source file
+%% according to user preferences.
+-spec error_tuple(file:filename(), [Err], [Warn], rebar_dict() | [{_,_}]) ->
+ error_tuple() when
+ Err :: string(),
+ Warn :: string().
error_tuple(Source, Es, Ws, Opts) ->
{error, format_errors(Source, Es),
format_warnings(Source, Ws, Opts)}.
+%% @doc from a given path, and based on the user-provided options,
+%% format the file path according to the preferences.
+-spec format_error_source(file:filename(), rebar_dict() | [{_,_}]) ->
+ file:filename().
format_error_source(Path, Opts) ->
Type = case rebar_opts:get(Opts, compiler_source_format,
?DEFAULT_COMPILER_SOURCE_FORMAT) of
@@ -98,6 +155,8 @@ format_error_source(Path, Opts) ->
rebar_dir:make_relative_path(resolve_linked_source(Path), Cwd)
end.
+%% @private takes a filename and canonicalizes its path if it is a link.
+-spec resolve_linked_source(file:filename()) -> file:filename().
resolve_linked_source(Src) ->
{Dir, Base} = rebar_file_utils:split_dirname(Src),
filename:join(rebar_file_utils:resolve_link(Dir), Base).
@@ -106,6 +165,11 @@ resolve_linked_source(Src) ->
%% Internal functions
%% ===================================================================
+%% @private if a check for last modifications is required, do the verification
+%% and possibly skip the compile job.
+-spec simple_compile_wrapper(Source, Target, compile_fn3(), [{_,_}] | rebar_dict(), boolean()) -> compile_fn_ret() when
+ Source :: file:filename(),
+ Target :: file:filename().
simple_compile_wrapper(Source, Target, Compile3Fn, Config, false) ->
Compile3Fn(Source, Target, Config);
simple_compile_wrapper(Source, Target, Compile3Fn, Config, true) ->
@@ -116,18 +180,42 @@ simple_compile_wrapper(Source, Target, Compile3Fn, Config, true) ->
skipped
end.
+%% @private take a basic source set of file fragments and a target location,
+%% create a file path and name for a compile artifact.
+-spec target_file(SourceFile, SourceDir, SourceExt, TargetDir, TargetExt) -> File when
+ SourceFile :: file:filename(),
+ SourceDir :: file:filename(),
+ TargetDir :: file:filename(),
+ SourceExt :: string(),
+ TargetExt :: string(),
+ File :: file:filename().
target_file(SourceFile, SourceDir, SourceExt, TargetDir, TargetExt) ->
BaseFile = remove_common_path(SourceFile, SourceDir),
filename:join([TargetDir, filename:basename(BaseFile, SourceExt) ++ TargetExt]).
+%% @private removes the common prefix between two file paths.
+%% The remainder of the first file path passed will have its ending returned
+%% when either path starts diverging.
+-spec remove_common_path(file:filename(), file:filename()) -> file:filename().
remove_common_path(Fname, Path) ->
remove_common_path1(filename:split(Fname), filename:split(Path)).
+%% @private given two lists of file fragments, discard the identical
+%% prefixed sections, and return the final bit of the first operand
+%% as a filename.
+-spec remove_common_path1([string()], [string()]) -> file:filename().
remove_common_path1([Part | RestFilename], [Part | RestPath]) ->
remove_common_path1(RestFilename, RestPath);
remove_common_path1(FilenameParts, _) ->
filename:join(FilenameParts).
+%% @private runs the compile function `CompileFn' on every file
+%% passed internally, along with the related project configuration.
+%% If any errors are encountered, they're reported to stdout.
+-spec compile_each([file:filename()], Config, CompileFn) -> Ret | no_return() when
+ Config :: [{_,_}] | rebar_dict(),
+ CompileFn :: compile_fn(),
+ Ret :: compile_fn_ret().
compile_each([], _Config, _CompileFn) ->
ok;
compile_each([Source | Rest], Config, CompileFn) ->
@@ -148,12 +236,19 @@ compile_each([Source | Rest], Config, CompileFn) ->
end,
compile_each(Rest, Config, CompileFn).
+%% @private Formats and returns errors ready to be output.
+-spec format_errors(string(), [err_or_warn()]) -> [string()].
format_errors(Source, Errors) ->
format_errors(Source, "", Errors).
+%% @private Formats and returns warning strings ready to be output.
+-spec format_warnings(string(), [err_or_warn()]) -> [string()].
format_warnings(Source, Warnings) ->
format_warnings(Source, Warnings, []).
+%% @private Formats and returns warnings; chooses the distinct format they
+%% may have based on whether `warnings_as_errors' option is on.
+-spec format_warnings(string(), [err_or_warn()], rebar_dict() | [{_,_}]) -> [string()].
format_warnings(Source, Warnings, Opts) ->
%% `Opts' can be passed in both as a list or a dictionary depending
%% on whether the first call to rebar_erlc_compiler was done with
@@ -167,6 +262,11 @@ format_warnings(Source, Warnings, Opts) ->
end,
format_errors(Source, Prefix, Warnings).
+%% @private output compiler errors if they're judged to be reportable.
+-spec maybe_report(Reportable | term()) -> ok when
+ Reportable :: {{error, error_tuple()}, Source} | error_tuple() | ErrProps,
+ ErrProps :: [{error, string()} | Source, ...],
+ Source :: {source, string()}.
maybe_report({{error, {error, _Es, _Ws}=ErrorsAndWarnings}, {source, _}}) ->
maybe_report(ErrorsAndWarnings);
maybe_report([{error, E}, {source, S}]) ->
@@ -177,15 +277,23 @@ maybe_report({error, Es, Ws}) ->
maybe_report(_) ->
ok.
+%% @private Outputs a bunch of strings, including a newline
+-spec report([string()]) -> ok.
report(Messages) ->
lists:foreach(fun(Msg) -> io:format("~s~n", [Msg]) end, Messages).
+%% private format compiler errors into proper outputtable strings
+-spec format_errors(_, Extra, [err_or_warn()]) -> [string()] when
+ Extra :: string().
format_errors(_MainSource, Extra, Errors) ->
[begin
[format_error(Source, Extra, Desc) || Desc <- Descs]
end
|| {Source, Descs} <- Errors].
+%% @private format compiler errors into proper outputtable strings
+-spec format_error(file:filename(), Extra, err_or_warn()) -> string() when
+ Extra :: string().
format_error(Source, Extra, {{Line, Column}, Mod, Desc}) ->
ErrorDesc = Mod:format_error(Desc),
?FMT("~s:~w:~w: ~s~s~n", [Source, Line, Column, Extra, ErrorDesc]);
diff --git a/src/rebar_config.erl b/src/rebar_config.erl
index 5a35b87..97e27ab 100644
--- a/src/rebar_config.erl
+++ b/src/rebar_config.erl
@@ -46,17 +46,25 @@
%% Public API
%% ===================================================================
+%% @doc reads the default config file.
-spec consult() -> [any()].
consult() ->
consult_file(config_file()).
+%% @doc reads the default config file in a given directory.
-spec consult(file:name()) -> [any()].
consult(Dir) ->
consult_file(filename:join(Dir, config_file())).
+%% @doc reads a given app file, including the `.script' variations,
+%% if any can be found.
+-spec consult_app_file(file:filename()) -> [any()].
consult_app_file(File) ->
consult_file_(File).
+%% @doc reads the lock file for the project, and re-formats its
+%% content to match the internals for rebar3.
+-spec consult_lock_file(file:filename()) -> [any()]. % TODO: refine lock()
consult_lock_file(File) ->
Terms = consult_file_(File),
case Terms of
@@ -80,6 +88,11 @@ consult_lock_file(File) ->
read_attrs(Vsn, Locks, Attrs)
end.
+%% @private outputs a warning for a newer lockfile format than supported
+%% at most once.
+%% The warning can also be cancelled by configuring the `warn_config_vsn'
+%% OTP env variable.
+-spec warn_vsn_once() -> ok.
warn_vsn_once() ->
Warn = application:get_env(rebar, warn_config_vsn) =/= {ok, false},
application:set_env(rebar, warn_config_vsn, false),
@@ -93,6 +106,11 @@ warn_vsn_once() ->
end.
+%% @doc Converts the internal format for locks into the multi-version
+%% compatible one used within rebar3 lock files.
+%% @end
+%% TODO: refine type for lock()
+-spec write_lock_file(file:filename(), [any()]) -> ok | {error, term()}.
write_lock_file(LockFile, Locks) ->
{NewLocks, Attrs} = write_attrs(Locks),
%% Write locks in the beta format, at least until it's been long
@@ -107,27 +125,41 @@ write_lock_file(LockFile, Locks) ->
format_attrs(Attrs)]))
end.
-%% Attributes have a special formatting to ensure there's only one per
-%% line in terms of pkg_hash, so we disturb source diffing as little
-%% as possible.
+%% @private Because attributes for packages are fairly large, there is the need
+%% for a special formatting to ensure there's only one entry per lock file
+%% line and that diffs are generally stable.
+-spec format_attrs([term()]) -> iodata().
format_attrs([]) -> [];
format_attrs([{pkg_hash, Vals}|T]) ->
[io_lib:format("{pkg_hash,[~n",[]), format_hashes(Vals), "]}",
maybe_comma(T) | format_attrs(T)].
+%% @private format hashing in order to disturb source diffing as little
+%% as possible
+-spec format_hashes([term()]) -> iodata().
format_hashes([]) -> [];
format_hashes([{Pkg,Hash}|T]) ->
[" {", io_lib:format("~p",[Pkg]), ", ", io_lib:format("~p", [Hash]), "}",
maybe_comma(T) | format_hashes(T)].
+%% @private add a comma if we're not done with the full list of terms
+%% to convert.
+-spec maybe_comma([term()]) -> iodata().
maybe_comma([]) -> "";
maybe_comma([_|_]) -> io_lib:format(",~n", []).
+%% @private extract attributes from the lock file and integrate them
+%% into the full-blow internal lock format
+%% @end
+%% TODO: refine typings for lock()
+-spec read_attrs(_, [any()], [any()]) -> [any()].
read_attrs(_Vsn, Locks, Attrs) ->
%% Beta copy does not know how to expand attributes, but
%% is ready to support it.
expand_locks(Locks, extract_pkg_hashes(Attrs)).
+%% @private extract the package hashes from lockfile attributes, if any.
+-spec extract_pkg_hashes(list()) -> [binary()].
extract_pkg_hashes(Attrs) ->
Props = case Attrs of
[First|_] -> First;
@@ -135,6 +167,11 @@ extract_pkg_hashes(Attrs) ->
end,
proplists:get_value(pkg_hash, Props, []).
+%% @private extract attributes from the lock file and integrate them
+%% into the full-blow internal lock format
+%% @end
+%% TODO: refine typings for lock()
+-spec expand_locks(list(), list()) -> list().
expand_locks([], _Hashes) ->
[];
expand_locks([{Name, {pkg,PkgName,Vsn}, Lvl} | Locks], Hashes) ->
@@ -143,6 +180,9 @@ expand_locks([{Name, {pkg,PkgName,Vsn}, Lvl} | Locks], Hashes) ->
expand_locks([Lock|Locks], Hashes) ->
[Lock | expand_locks(Locks, Hashes)].
+%% @private split up extra attributes for locks out of the internal lock
+%% structure for backwards compatibility reasons
+-spec write_attrs(list()) -> {list(), list()}.
write_attrs(Locks) ->
%% No attribute known that needs to be taken out of the structure,
%% just return terms as is.
@@ -152,6 +192,9 @@ write_attrs(Locks) ->
_ -> {NewLocks, [{pkg_hash, lists:sort(Hashes)}]}
end.
+%% @private split up extra attributes for locks out of the internal lock
+%% structure for backwards compatibility reasons
+-spec split_locks(list(), list(), [{_,binary()}]) -> {list(), list()}.
split_locks([], Locks, Hashes) ->
{lists:reverse(Locks), Hashes};
split_locks([{Name, {pkg,PkgName,Vsn,undefined}, Lvl} | Locks], LAcc, HAcc) ->
@@ -161,11 +204,17 @@ split_locks([{Name, {pkg,PkgName,Vsn,Hash}, Lvl} | Locks], LAcc, HAcc) ->
split_locks([Lock|Locks], LAcc, HAcc) ->
split_locks(Locks, [Lock|LAcc], HAcc).
+%% @doc reads a given config file, including the `.script' variations,
+%% if any can be found, and asserts that the config format is in
+%% a key-value format.
+-spec consult_file(file:filename()) -> [{_,_}].
consult_file(File) ->
Terms = consult_file_(File),
true = verify_config_format(Terms),
Terms.
+%% @private reads a given file; if the file has a `.script'-postfixed
+%% counterpart, it is evaluated along with the original file.
-spec consult_file_(file:name()) -> [any()].
consult_file_(File) when is_binary(File) ->
consult_file_(binary_to_list(File));
@@ -185,6 +234,9 @@ consult_file_(File) ->
end
end.
+%% @private checks that a list is in a key-value format.
+%% Raises an exception in any other case.
+-spec verify_config_format([{_,_}]) -> true.
verify_config_format([]) ->
true;
verify_config_format([{_Key, _Value} | T]) ->
@@ -192,11 +244,14 @@ verify_config_format([{_Key, _Value} | T]) ->
verify_config_format([Term | _]) ->
throw(?PRV_ERROR({bad_config_format, Term})).
-%% no lockfile
+%% @doc takes an existing configuration and the content of a lockfile
+%% and merges the locks into the config.
+-spec merge_locks([{_,_}], list()) -> [{_,_}].
merge_locks(Config, []) ->
+%% no lockfile
Config;
-%% lockfile with entries
merge_locks(Config, Locks) ->
+ %% lockfile with entries
ConfigDeps = proplists:get_value(deps, Config, []),
%% We want the top level deps only from the lock file.
%% This ensures deterministic overrides for configs.
@@ -206,6 +261,8 @@ merge_locks(Config, Locks) ->
NewDeps = find_newly_added(ConfigDeps, Locks),
[{{locks, default}, Locks}, {{deps, default}, NewDeps++Deps} | Config].
+%% @doc convert a given exception's payload into an io description.
+-spec format_error(any()) -> iolist().
format_error({bad_config_format, Term}) ->
io_lib:format("Unable to parse config. Term is not in {Key, Value} format:~n~p", [Term]);
format_error({bad_dep_name, Dep}) ->
@@ -215,6 +272,8 @@ format_error({bad_dep_name, Dep}) ->
%% Internal functions
%% ===================================================================
+%% @private consults a consult file, then executes its related script file
+%% with the data returned from the consult.
-spec consult_and_eval(File::file:name_all(), Script::file:name_all()) ->
{ok, Terms::[term()]} |
{error, Reason::term()}.
@@ -234,18 +293,26 @@ consult_and_eval(File, Script) ->
Error
end.
+%% @private drops the .script extension from a filename.
+-spec remove_script_ext(file:filename()) -> file:filename().
remove_script_ext(F) ->
filename:rootname(F, ".script").
+%% @private sets up bindings for evaluations from a KV list.
+-spec bs([{_,_}]) -> erl_eval:binding_struct().
bs(Vars) ->
lists:foldl(fun({K,V}, Bs) ->
erl_eval:add_binding(K, V, Bs)
end, erl_eval:new_bindings(), Vars).
-%% Find deps that have been added to the config after the lock was created
+%% @private Find deps that have been added to the config after the lock was created
+-spec find_newly_added(list(), list()) -> list().
find_newly_added(ConfigDeps, LockedDeps) ->
[D || {true, D} <- [check_newly_added(Dep, LockedDeps) || Dep <- ConfigDeps]].
+%% @private checks if a given dependency is not within the lock file.
+%% TODO: refine types for dependencies
+-spec check_newly_added(term(), list()) -> false | {true, term()}.
check_newly_added({_, _}=Dep, LockedDeps) ->
check_newly_added_(Dep, LockedDeps);
check_newly_added({_, _, {pkg, _}}=Dep, LockedDeps) ->
@@ -255,6 +322,10 @@ check_newly_added({Name, _, Source}, LockedDeps) ->
check_newly_added(Dep, LockedDeps) ->
check_newly_added_(Dep, LockedDeps).
+%% @private checks if a given dependency is not within the lock file.
+%% TODO: refine types for dependencies
+%% @end
+-spec check_newly_added_(term(), list()) -> false | {true, term()}.
%% get [raw] deps out of the way
check_newly_added_({Name, Source, Opts}, LockedDeps) when is_tuple(Source),
is_list(Opts) ->
@@ -306,6 +377,9 @@ check_newly_added_(Dep, LockedDeps) when is_atom(Dep) ->
check_newly_added_(Dep, _) ->
throw(?PRV_ERROR({bad_dep_name, Dep})).
+%% @private returns the name/path of the default config file, or its
+%% override from the OS ENV var `REBAR_CONFIG'.
+-spec config_file() -> file:filename().
config_file() ->
case os:getenv("REBAR_CONFIG") of
false ->
diff --git a/src/rebar_core.erl b/src/rebar_core.erl
index da8c3e6..14c4906 100644
--- a/src/rebar_core.erl
+++ b/src/rebar_core.erl
@@ -24,6 +24,8 @@
%% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
%% THE SOFTWARE.
%% -------------------------------------------------------------------
+%% @doc Module providing core functionality about command dispatch, namespacing,
+%% and chaining for rebar3.
-module(rebar_core).
-export([init_command/2, process_namespace/2, process_command/2, do/2, format_error/1]).
@@ -31,6 +33,12 @@
-include("rebar.hrl").
-include_lib("providers/include/providers.hrl").
+%% @doc initial command set up; based on the first fragment of the
+%% command, dispatch to special environments. The keywords for
+%% `do' and `as' are implicitly reserved here, barring them from
+%% being used as other commands or namespaces.
+-spec init_command(rebar_state:t(), atom()) ->
+ {ok, rebar_state:t()} | {error, term()}.
init_command(State, do) ->
process_command(rebar_state:namespace(State, default), do);
init_command(State, as) ->
@@ -43,6 +51,14 @@ init_command(State, Command) ->
{error, Reason}
end.
+%% @doc parse the commands starting at the namespace level;
+%% a namespace is found if the first keyword to match is not
+%% belonging to an existing provider, and iff the keyword also
+%% matches a registered namespace.
+%% The command to run is returned last; for namespaces, some
+%% magic is done implicitly calling `do' as an indirect dispatcher.
+-spec process_namespace(rebar_state:t(), atom()) ->
+ {error, term()} | {ok, rebar_state:t(), atom()}.
process_namespace(_State, as) ->
{error, "Namespace 'as' is forbidden"};
process_namespace(State, Command) ->
@@ -61,7 +77,15 @@ process_namespace(State, Command) ->
{ok, rebar_state:namespace(State, default), Command}
end.
--spec process_command(rebar_state:t(), atom()) -> {ok, rebar_state:t()} | {error, string()} | {error, {module(), any()}}.
+%% @doc Dispatches a given command based on the current state.
+%% This requires mapping a command name to a specific provider.
+%% `as' and `do' are still treated as special providers here.
+%% Basic profile application may also be run.
+%%
+%% The function also takes care of expanding a provider to its
+%% dependencies in the proper order.
+-spec process_command(rebar_state:t(), atom()) ->
+ {ok, rebar_state:t()} | {error, string()} | {error, {module(), any()}}.
process_command(State, Command) ->
%% ? rebar_prv_install_deps:setup_env(State),
Providers = rebar_state:providers(State),
@@ -104,7 +128,11 @@ process_command(State, Command) ->
end
end.
--spec do([{atom(), atom()}], rebar_state:t()) -> {ok, rebar_state:t()} | {error, string()} | {error, {module(), any()}}.
+%% @doc execute the selected providers. If a chain of providers
+%% has been returned, run them one after the other, while piping
+%% the state from the first into the next one.
+-spec do([{atom(), atom()}], rebar_state:t()) ->
+ {ok, rebar_state:t()} | {error, string()} | {error, {module(), any()}}.
do([], State) ->
{ok, State};
do([ProviderName | Rest], State) ->
@@ -142,6 +170,8 @@ do([ProviderName | Rest], State) ->
{error, ProviderName}
end.
+%% @doc convert a given exception's payload into an io description.
+-spec format_error(any()) -> iolist().
format_error({bad_provider_namespace, {Namespace, Name}}) ->
io_lib:format("Undefined command ~s in namespace ~s", [Name, Namespace]);
format_error({bad_provider_namespace, Name}) ->
diff --git a/src/rebar_digraph.erl b/src/rebar_digraph.erl
index 363253a..a827735 100644
--- a/src/rebar_digraph.erl
+++ b/src/rebar_digraph.erl
@@ -1,3 +1,5 @@
+%%% @doc build a digraph of applications in order to figure out dependency
+%%% and compile order.
-module(rebar_digraph).
-export([compile_order/1
@@ -7,7 +9,9 @@
-include("rebar.hrl").
-%% Sort apps with topological sort to get proper build order
+%% @doc Sort apps with topological sort to get proper build order
+-spec compile_order([rebar_app_info:t()]) ->
+ {ok, [rebar_app_info:t()]} | {error, no_sort | {cycles, [[binary(),...]]}}.
compile_order(Apps) ->
Graph = digraph:new(),
lists:foreach(fun(App) ->
@@ -33,6 +37,11 @@ compile_order(Apps) ->
true = digraph:delete(Graph),
Order.
+%% @private Add a package and its dependencies to an existing digraph
+-spec add(digraph:graph(), {PkgName, [Dep]}) -> ok when
+ PkgName :: binary(),
+ Dep :: {Name, term()} | Name,
+ Name :: atom() | iodata().
add(Graph, {PkgName, Deps}) ->
case digraph:vertex(Graph, PkgName) of
false ->
@@ -57,6 +66,8 @@ add(Graph, {PkgName, Deps}) ->
digraph:add_edge(Graph, V, V3)
end, Deps).
+%% @doc based on a list of vertices and edges, build a digraph.
+-spec restore_graph({[digraph:vertex()], [digraph:edge()]}) -> digraph:graph().
restore_graph({Vs, Es}) ->
Graph = digraph:new(),
lists:foreach(fun({V, LastUpdated}) ->
@@ -67,6 +78,8 @@ restore_graph({Vs, Es}) ->
end, Es),
Graph.
+%% @doc convert a given exception's payload into an io description.
+-spec format_error(any()) -> iolist().
format_error(no_solution) ->
io_lib:format("No solution for packages found.", []).
@@ -74,22 +87,27 @@ format_error(no_solution) ->
%% Internal Functions
%%====================================================================
+%% @doc alias for `digraph_utils:subgraph/2'.
subgraph(Graph, Vertices) ->
digraph_utils:subgraph(Graph, Vertices).
+%% @private from a list of app names, fetch the proper app info records
+%% for them.
-spec names_to_apps([atom()], [rebar_app_info:t()]) -> [rebar_app_info:t()].
names_to_apps(Names, Apps) ->
[element(2, App) || App <- [find_app_by_name(Name, Apps) || Name <- Names], App =/= error].
+%% @private fetch the proper app info record for a given app name.
-spec find_app_by_name(atom(), [rebar_app_info:t()]) -> {ok, rebar_app_info:t()} | error.
find_app_by_name(Name, Apps) ->
ec_lists:find(fun(App) ->
rebar_app_info:name(App) =:= Name
end, Apps).
-%% The union of all entries in the applications list for an app and
+%% @private The union of all entries in the applications list for an app and
%% the deps listed in its rebar.config is all deps that may be needed
%% for building the app.
+-spec all_apps_deps(rebar_app_info:t()) -> [binary()].
all_apps_deps(App) ->
Applications = lists:usort([atom_to_binary(X, utf8) || X <- rebar_app_info:applications(App)]),
Deps = lists:usort(lists:map(fun({Name, _}) -> Name; (Name) -> Name end, rebar_app_info:deps(App))),
diff --git a/src/rebar_dir.erl b/src/rebar_dir.erl
index 79a1c7f..069d8fd 100644
--- a/src/rebar_dir.erl
+++ b/src/rebar_dir.erl
@@ -1,3 +1,4 @@
+%%% @doc utility functions for directory and path handling of all kind.
-module(rebar_dir).
-export([base_dir/1,
@@ -29,10 +30,14 @@
-include("rebar.hrl").
+%% @doc returns the directory root for build artifacts
+%% for the current profile, such as `_build/default/'.
-spec base_dir(rebar_state:t()) -> file:filename_all().
base_dir(State) ->
profile_dir(rebar_state:opts(State), rebar_state:current_profiles(State)).
+%% @doc returns the directory root for build artifacts for a given set
+%% of profiles.
-spec profile_dir(rebar_dict(), [atom()]) -> file:filename_all().
profile_dir(Opts, Profiles) ->
{BaseDir, ProfilesStrings} = case [ec_cnv:to_list(P) || P <- Profiles] of
@@ -46,25 +51,36 @@ profile_dir(Opts, Profiles) ->
ProfilesDir = string:join(ProfilesStrings, "+"),
filename:join(BaseDir, ProfilesDir).
+%% @doc returns the directory where dependencies should be placed
+%% given the current profile.
-spec deps_dir(rebar_state:t()) -> file:filename_all().
deps_dir(State) ->
filename:join(base_dir(State), rebar_state:get(State, deps_dir, ?DEFAULT_DEPS_DIR)).
+%% @doc returns the directory where a dependency should be placed
+%% given the current profile, based on its app name. Expects to be passed
+%% the result of `deps_dir/1' as a first argument.
-spec deps_dir(file:filename_all(), file:filename_all()) -> file:filename_all().
deps_dir(DepsDir, App) ->
filename:join(DepsDir, App).
+%% @doc returns the absolute path for the project root (by default,
+%% the current working directory for the currently running escript).
root_dir(State) ->
filename:absname(rebar_state:get(State, root_dir, ?DEFAULT_ROOT_DIR)).
+%% @doc returns the expected location of the `_checkouts' directory.
-spec checkouts_dir(rebar_state:t()) -> file:filename_all().
checkouts_dir(State) ->
filename:join(root_dir(State), rebar_state:get(State, checkouts_dir, ?DEFAULT_CHECKOUTS_DIR)).
+%% @doc returns the expected location of a given app in the checkouts
+%% directory for the project.
-spec checkouts_dir(rebar_state:t(), file:filename_all()) -> file:filename_all().
checkouts_dir(State, App) ->
filename:join(checkouts_dir(State), App).
+%% @doc Returns the directory where plugins are located.
-spec plugins_dir(rebar_state:t()) -> file:filename_all().
plugins_dir(State) ->
case lists:member(global, rebar_state:current_profiles(State)) of
@@ -74,33 +90,50 @@ plugins_dir(State) ->
filename:join(base_dir(State), rebar_state:get(State, plugins_dir, ?DEFAULT_PLUGINS_DIR))
end.
+%% @doc returns the list of relative path where the project applications can
+%% be located.
-spec lib_dirs(rebar_state:t()) -> file:filename_all().
lib_dirs(State) ->
rebar_state:get(State, project_app_dirs, ?DEFAULT_PROJECT_APP_DIRS).
+%% @doc returns the user's home directory.
+-spec home_dir() -> file:filename_all().
home_dir() ->
{ok, [[Home]]} = init:get_argument(home),
Home.
+%% @doc returns the directory where the global configuration files for rebar3
+%% may be stored.
+-spec global_config_dir(rebar_state:t()) -> file:filename_all().
global_config_dir(State) ->
Home = home_dir(),
rebar_state:get(State, global_rebar_dir, filename:join([Home, ".config", "rebar3"])).
+%% @doc returns the path of the global rebar.config file
+-spec global_config(rebar_state:t()) -> file:filename_all().
global_config(State) ->
filename:join(global_config_dir(State), "rebar.config").
+%% @doc returns the default path of the global rebar.config file
+-spec global_config() -> file:filename_all().
global_config() ->
Home = home_dir(),
filename:join([Home, ".config", "rebar3", "rebar.config"]).
+%% @doc returns the location for the global cache directory
-spec global_cache_dir(rebar_dict()) -> file:filename_all().
global_cache_dir(Opts) ->
Home = home_dir(),
rebar_opts:get(Opts, global_rebar_dir, filename:join([Home, ".cache", "rebar3"])).
+%% @doc appends the cache directory to the path passed to this function.
+-spec local_cache_dir(file:filename_all()) -> file:filename_all().
local_cache_dir(Dir) ->
filename:join(Dir, ".rebar3").
+%% @doc returns the current working directory, with some specific
+%% conversions and handling done to be cross-platform compatible.
+-spec get_cwd() -> file:filename_all().
get_cwd() ->
{ok, Dir} = file:get_cwd(),
%% On windows cwd may return capital letter for drive,
@@ -109,20 +142,33 @@ get_cwd() ->
%% cwd as soon as it possible.
filename:join([Dir]).
+%% @doc returns the file location for the global template
+%% configuration variables file.
+-spec template_globals(rebar_state:t()) -> file:filename_all().
template_globals(State) ->
filename:join([global_config_dir(State), "templates", "globals"]).
+%% @doc returns the location for the global template directory
+-spec template_dir(rebar_state:t()) -> file:filename_all().
template_dir(State) ->
filename:join([global_config_dir(State), "templates"]).
+%% @doc checks if the current working directory is the base directory
+%% for the project.
+-spec processing_base_dir(rebar_state:t()) -> boolean().
processing_base_dir(State) ->
Cwd = get_cwd(),
processing_base_dir(State, Cwd).
+%% @doc checks if the passed in directory is the base directory for
+%% the project.
+-spec processing_base_dir(rebar_state:t(), file:filename()) -> boolean().
processing_base_dir(State, Dir) ->
AbsDir = filename:absname(Dir),
AbsDir =:= rebar_state:get(State, base_dir).
+%% @doc make a path absolute
+-spec make_absolute_path(file:filename()) -> file:filename().
make_absolute_path(Path) ->
case filename:pathtype(Path) of
absolute ->
@@ -136,11 +182,16 @@ make_absolute_path(Path) ->
filename:join([Dir, Path])
end.
+%% @doc normalizing a path removes all of the `..' and the
+%% `.' segments it may contain.
+-spec make_normalized_path(file:filename()) -> file:filename().
make_normalized_path(Path) ->
AbsPath = make_absolute_path(Path),
Components = filename:split(AbsPath),
make_normalized_path(Components, []).
+%% @private drops path fragments for normalization
+-spec make_normalized_path([string()], [string()]) -> file:filename().
make_normalized_path([], NormalizedPath) ->
filename:join(lists:reverse(NormalizedPath));
make_normalized_path([H|T], NormalizedPath) ->
@@ -150,48 +201,67 @@ make_normalized_path([H|T], NormalizedPath) ->
_ -> make_normalized_path(T, [H|NormalizedPath])
end.
+%% @doc take a source and a target path, and relativize the target path
+%% onto the source.
+%%
+%% Example:
+%% ```
+%% 1> rebar_dir:make_relative_path("a/b/c/d/file", "a/b/file").
+%% "c/d/file"
+%% 2> rebar_dir:make_relative_path("a/b/file", "a/b/c/d/file").
+%% "../../file"
+%% '''
+-spec make_relative_path(file:filename(), file:filename()) -> file:filename().
make_relative_path(Source, Target) ->
AbsSource = make_normalized_path(Source),
AbsTarget = make_normalized_path(Target),
do_make_relative_path(filename:split(AbsSource), filename:split(AbsTarget)).
+%% @private based on fragments of paths, replace the number of common
+%% segments by `../' bits, and add the rest of the source alone after it
+-spec do_make_relative_path([string()], [string()]) -> file:filename().
do_make_relative_path([H|T1], [H|T2]) ->
do_make_relative_path(T1, T2);
do_make_relative_path(Source, Target) ->
Base = lists:duplicate(max(length(Target) - 1, 0), ".."),
filename:join(Base ++ Source).
-%%%-----------------------------------------------------------------
-%%% 'src_dirs' and 'extra_src_dirs' can be configured with options
+%%% @doc
+%%% `src_dirs' and `extra_src_dirs' can be configured with options
%%% like this:
-%%%
+%%% ```
%%% {src_dirs,[{"foo",[{recursive,false}]}]}
%%% {extra_src_dirs,[{"bar",[recursive]}]} (equivalent to {recursive,true})
-%%%
-%%% src_dirs/1,2 and extra_src_dirs/1,2 return only the list of
-%%% directories for the 'src_dirs' and 'extra_src_dirs' options
-%%% respectively, while src_dirs_opts/2 return the options list for
-%%% the given directory, no matter if it is configured as 'src_dirs' or
-%%% 'extra_src_dirs'.
-%%%
+%%% '''
+%%% `src_dirs/1,2' and `extra_src_dirs/1,2' return only the list of
+%%% directories for the `src_dirs' and `extra_src_dirs' options
+%%% respectively, while `src_dirs_opts/2' returns the options list for
+%%% the given directory, no matter if it is configured as `src_dirs' or
+%%% `extra_src_dirs'.
-spec src_dirs(rebar_dict()) -> list(file:filename_all()).
src_dirs(Opts) -> src_dirs(Opts, []).
+%% @doc same as `src_dirs/1', but allows to pass in a list of default options.
-spec src_dirs(rebar_dict(), list(file:filename_all())) -> list(file:filename_all()).
src_dirs(Opts, Default) ->
src_dirs(src_dirs, Opts, Default).
+%% @doc same as `src_dirs/1', but for the `extra_src_dirs' options
-spec extra_src_dirs(rebar_dict()) -> list(file:filename_all()).
extra_src_dirs(Opts) -> extra_src_dirs(Opts, []).
+%% @doc same as `src_dirs/2', but for the `extra_src_dirs' options
-spec extra_src_dirs(rebar_dict(), list(file:filename_all())) -> list(file:filename_all()).
extra_src_dirs(Opts, Default) ->
src_dirs(extra_src_dirs, Opts, Default).
+%% @private agnostic version of src_dirs and extra_src_dirs.
src_dirs(Type, Opts, Default) ->
lists:usort([case D0 of {D,_} -> D; _ -> D0 end ||
D0 <- raw_src_dirs(Type,Opts,Default)]).
+%% @private extracts the un-formatted src_dirs or extra_src_dirs
+%% options as configured.
raw_src_dirs(Type, Opts, Default) ->
ErlOpts = rebar_opts:erl_opts(Opts),
Vs = proplists:get_all_values(Type, ErlOpts),
@@ -200,19 +270,23 @@ raw_src_dirs(Type, Opts, Default) ->
Dirs -> Dirs
end.
+%% @doc returns all the source directories (`src_dirs' and
+%% `extra_src_dirs').
-spec all_src_dirs(rebar_dict()) -> list(file:filename_all()).
all_src_dirs(Opts) -> all_src_dirs(Opts, [], []).
+%% @doc returns all the source directories (`src_dirs' and
+%% `extra_src_dirs') while being able to configure defaults for both.
-spec all_src_dirs(rebar_dict(), list(file:filename_all()), list(file:filename_all())) ->
list(file:filename_all()).
all_src_dirs(Opts, SrcDefault, ExtraDefault) ->
lists:usort(src_dirs(Opts, SrcDefault) ++ extra_src_dirs(Opts, ExtraDefault)).
-%%%-----------------------------------------------------------------
+%%% @doc
%%% Return the list of options for the given src directory
%%% If the same option is given multiple times for a directory in the
-%%% config, the priority order is: first occurence of 'src_dirs'
-%%% followed by first occurence of 'extra_src_dirs'.
+%%% config, the priority order is: first occurence of `src_dirs'
+%%% followed by first occurence of `extra_src_dirs'.
-spec src_dir_opts(rebar_dict(), file:filename_all()) -> [{atom(),term()}].
src_dir_opts(Opts, Dir) ->
RawSrcDirs = raw_src_dirs(src_dirs, Opts, []),
@@ -221,7 +295,7 @@ src_dir_opts(Opts, Dir) ->
D==Dir],
lists:ukeysort(1,proplists:unfold(lists:append(AllOpts))).
-%%%-----------------------------------------------------------------
+%%% @doc
%%% Return the value of the 'recursive' option for the given directory.
%%% If not given, the value of 'recursive' in the 'erlc_compiler'
%%% options is used, and finally the default is 'true'.
@@ -234,16 +308,17 @@ recursive(Opts, Dir) ->
R = proplists:get_value(recursive, DirOpts, Default),
R.
-%% given a path if that path is an ancestor of an app dir return the path relative to that
-%% apps outdir. if the path is not an ancestor to any app dirs but is an ancestor of the
-%% project root return the path relative to the project base_dir. if it is not an ancestor
+%% @doc given a path if that path is an ancestor of an app dir, return the path relative to that
+%% apps outdir. If the path is not an ancestor to any app dirs but is an ancestor of the
+%% project root, return the path relative to the project base_dir. If it is not an ancestor
%% of either return it unmodified
-spec retarget_path(rebar_state:t(), string()) -> string().
-
retarget_path(State, Path) ->
ProjectApps = rebar_state:project_apps(State),
retarget_path(State, Path, ProjectApps).
+%% @private worker for retarget_path/2
+%% @end
%% not relative to any apps in project, check to see it's relative to
%% project root
retarget_path(State, Path, []) ->
diff --git a/src/rebar_dist_utils.erl b/src/rebar_dist_utils.erl
index f462826..93edf9d 100644
--- a/src/rebar_dist_utils.erl
+++ b/src/rebar_dist_utils.erl
@@ -7,6 +7,9 @@
%%%%%%%%%%%%%%%%%%
%%% PUBLIC API %%%
%%%%%%%%%%%%%%%%%%
+
+%% @doc allows to pick whether to use a short or long name, and
+%% starts the distributed mode for it.
-spec either(Name::atom(), SName::atom(), Opts::[{setcookie,term()}]) -> atom().
either(undefined, undefined, _) ->
'nonode@nohost';
@@ -19,13 +22,19 @@ either(undefined, SName, Opts) ->
either(_, _, _) ->
?ABORT("Cannot have both short and long node names defined", []).
+%% @doc starts a node with a short name.
+-spec short(SName::atom(), Opts::[{setcookie,term()}]) -> term().
short(Name, Opts) ->
start(Name, shortnames, Opts).
+%% @doc starts a node with a long name.
+-spec long(Name::atom(), Opts::[{setcookie,term()}]) -> term().
long(Name, Opts) ->
start(Name, longnames, Opts).
--spec find_options(rebar_state:state()) -> {Long, Short, Opts} when
+%% @doc utility function to extract all distribution options
+%% from a rebar3 state tuple.
+-spec find_options(rebar_state:t()) -> {Long, Short, Opts} when
Long :: atom(),
Short :: atom(),
Opts :: [{setcookie,term()}].
diff --git a/src/rebar_file_utils.erl b/src/rebar_file_utils.erl
index f2467c5..8645641 100644
--- a/src/rebar_file_utils.erl
+++ b/src/rebar_file_utils.erl
@@ -300,9 +300,8 @@ canonical_path([_|Acc], [".."|Rest]) -> canonical_path(Acc, Rest);
canonical_path([], [".."|Rest]) -> canonical_path([], Rest);
canonical_path(Acc, [Component|Rest]) -> canonical_path([Component|Acc], Rest).
-%% returns canonical target of path if path is a link, otherwise returns path
+%% @doc returns canonical target of path if path is a link, otherwise returns path
-spec resolve_link(string()) -> string().
-
resolve_link(Path) ->
case file:read_link(Path) of
{ok, Target} ->
@@ -310,9 +309,8 @@ resolve_link(Path) ->
{error, _} -> Path
end.
-%% splits a path into dirname and basename
+%% @doc splits a path into dirname and basename
-spec split_dirname(string()) -> {string(), string()}.
-
split_dirname(Path) ->
{filename:dirname(Path), filename:basename(Path)}.
diff --git a/src/rebar_pkg_resource.erl b/src/rebar_pkg_resource.erl
index 8e1713d..88419bd 100644
--- a/src/rebar_pkg_resource.erl
+++ b/src/rebar_pkg_resource.erl
@@ -137,6 +137,9 @@ etag(Path) ->
false
end.
+%% @doc returns the SSL options adequate for the project based on
+%% its configuration, including for validation of certs.
+-spec ssl_opts(string()) -> [term()].
ssl_opts(Url) ->
case get_ssl_config() of
ssl_verify_enabled ->
@@ -145,6 +148,9 @@ ssl_opts(Url) ->
[{verify, verify_none}]
end.
+%% @doc returns the SSL options adequate for the project based on
+%% its configuration, including for validation of certs.
+-spec ssl_opts(atom(), string()) -> [term()].
ssl_opts(ssl_verify_enabled, Url) ->
case check_ssl_version() of
true ->
diff --git a/src/rebar_prv_install_deps.erl b/src/rebar_prv_install_deps.erl
index 84a0563..c9fe0ad 100644
--- a/src/rebar_prv_install_deps.erl
+++ b/src/rebar_prv_install_deps.erl
@@ -101,6 +101,7 @@ do_(State) ->
{error, Reason}
end.
+%% @doc convert a given exception's payload into an io description.
-spec format_error(any()) -> iolist().
format_error({dep_app_not_found, AppDir, AppName}) ->
io_lib:format("Dependency failure: Application ~s not found at the top level of directory ~s", [AppName, AppDir]);
@@ -125,8 +126,14 @@ format_error({cycles, Cycles}) ->
format_error(Reason) ->
io_lib:format("~p", [Reason]).
-%% Allows other providers to install deps in a given profile
+%% @doc Allows other providers to install deps in a given profile
%% manually, outside of what is provided by rebar3's deps tuple.
+-spec handle_deps_as_profile(Profile, State, Deps, Upgrade) -> {Apps, State} when
+ Profile :: atom(),
+ State :: rebar_state:t(),
+ Deps :: [tuple() | atom() | binary()], % TODO: meta to source() | lock()
+ Upgrade :: boolean(),
+ Apps :: [rebar_app_info:t()].
handle_deps_as_profile(Profile, State, Deps, Upgrade) ->
Locks = [],
Level = 0,
diff --git a/src/rebar_utils.erl b/src/rebar_utils.erl
index a0a44d1..c357e94 100644
--- a/src/rebar_utils.erl
+++ b/src/rebar_utils.erl
@@ -97,6 +97,12 @@ sort_deps(Deps) ->
droplast(L) ->
lists:reverse(tl(lists:reverse(L))).
+%% @doc filtermap takes in a function that is either or both
+%% a predicate and a map, and returns the matching and valid elements.
+-spec filtermap(F, [In]) -> [Out] when
+ F :: fun((In) -> boolean() | {true, Out}),
+ In :: term(),
+ Out :: term().
filtermap(F, [Hd|Tail]) ->
case F(Hd) of
true ->
@@ -116,11 +122,16 @@ is_arch(ArchRegex) ->
false
end.
+%% @doc returns the sytem architecture, in strings like
+%% `"19.0.4-x86_64-unknown-linux-gnu-64"'.
+-spec get_arch() -> string().
get_arch() ->
Words = wordsize(),
otp_release() ++ "-"
++ erlang:system_info(system_architecture) ++ "-" ++ Words.
+%% @doc returns the size of a word on the system, as a string
+-spec wordsize() -> string().
wordsize() ->
try erlang:system_info({wordsize, external}) of
Val ->
@@ -504,11 +515,10 @@ patch_on_windows(Cmd, Env) ->
Cmd
end.
-%%
-%% Given env. variable FOO we want to expand all references to
-%% it in InStr. References can have two forms: $FOO and ${FOO}
-%% The end of form $FOO is delimited with whitespace or eol
-%%
+%% @doc Given env. variable `FOO' we want to expand all references to
+%% it in `InStr'. References can have two forms: `$FOO' and `${FOO}'
+%% The end of form `$FOO' is delimited with whitespace or EOL
+-spec expand_env_variable(string(), string(), term()) -> string().
expand_env_variable(InStr, VarName, RawVarValue) ->
case string:chr(InStr, $$) of
0 ->
@@ -750,6 +760,9 @@ remove_from_code_path(Paths) ->
code:del_path(Path)
end, Paths).
+%% @doc Revert to only having the beams necessary for running rebar3 and
+%% plugins in the path
+-spec cleanup_code_path([string()]) -> true | {error, term()}.
cleanup_code_path(OrigPath) ->
CurrentPath = code:get_path(),
AddedPaths = CurrentPath -- OrigPath,