summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/rebar_app_discover.erl6
-rw-r--r--src/rebar_config.erl6
-rw-r--r--src/rebar_digraph.erl22
-rw-r--r--src/rebar_dir.erl91
-rw-r--r--src/rebar_dist_utils.erl9
5 files changed, 109 insertions, 25 deletions
diff --git a/src/rebar_app_discover.erl b/src/rebar_app_discover.erl
index acefdb4..fd55960 100644
--- a/src/rebar_app_discover.erl
+++ b/src/rebar_app_discover.erl
@@ -13,7 +13,9 @@
-include("rebar.hrl").
-include_lib("providers/include/providers.hrl").
-%% @doc from the base directory,
+%% @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),
@@ -158,7 +160,7 @@ project_app_config(AppInfo, State) ->
Opts = maybe_reset_hooks(Dir, rebar_state:opts(State), State),
{C, rebar_state:opts(State, Opts)}.
-%% @doc 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().
diff --git a/src/rebar_config.erl b/src/rebar_config.erl
index 84f40d4..97e27ab 100644
--- a/src/rebar_config.erl
+++ b/src/rebar_config.erl
@@ -125,9 +125,9 @@ write_lock_file(LockFile, Locks) ->
format_attrs(Attrs)]))
end.
-%% @private 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]) ->
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 32cb264..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,9 +142,14 @@ 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"]).
@@ -129,6 +167,8 @@ 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 ->
@@ -142,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) ->
@@ -181,37 +226,42 @@ 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),
@@ -220,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, []),
@@ -241,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'.
@@ -254,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 03f4392..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,12 +22,18 @@ 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).
+%% @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(),