anvl_locate ¶This module provides a generic mechanism for resolving external dependencies. It doesn’t do anything on its own, but acts as a broker between dependency resolver plugins (such as Git, Builtin ANVL Plugin) and dependency consumers.
Consumer of the external dependency supplies the following parameters:
Kind, a type of a dependency that needs resolution.
Kinds serve as "namespaces" for dependencies,
for example,
they allow to distinguish dependencies for different languages used within the project.
Dependency, a term identifying the dependency.
SubDirFun, a function that can identify a sub-dependency by inspecting contents of a directory.
For each kind anvl_locate maintains a search path,
that is a list of directories.
Dependency resolution works as following:
SubDirFun is executed for each entry of the existing search path.
If it returns a match (a subdirectory),
then this subdirectory becomes the result of resolution,
which gets cached for the future using ANVL’s standard memoization mechanism.
Non-matches are cached as well.
anvl_locate passes dependency kind and ID to the plugins.
The plugins can inspect project config or any other source,
download the dependency into some local directory,
and add it to the search path.
Note: finding of a compatible set of the dependency versions,
(i.e. solving a system of inequations foo_ver >= 1 && foo_ver < 3, ...)
is not a responsibility of this module.
This step is delegated to other plugins.
-type locate_hook() :: fun((kind(),
dependency()) -> locate_hook_ret()).
-type locate_hook_ret() :: {_Changed :: boolean(),
[{anvl_project:t(),
_Prio :: integer(),
file:filename()}]}.
-type subdirectory_fun() :: fun((kind(), dependency(),
file:filename()) -> {value, file:filename()} |
false).
Not exported
A function that tries to locate a dependency in a local directory.
-type kind() :: atom().
Different path IDs allow to discriminate between types of dependencies.
-type dependency() :: term().
External dependency that has to be resolved.
-spec get_path(kind() | '_') -> [{anvl_project:t(),
file:filename()}].
Get local search path for the given dependency type or '_' (wildcard).
-spec get_lock(anvl_plugin:t(), kind(),
_Package) -> binary().
Get cached value of lock for a dependency.
-spec resolve_lock(anvl_plugin:t(), fun(() -> Hash),
anvl_project:t(), kind(), Package) -> {Changed,
Hash} when Package ::
atom() |
binary() |
string(),
Changed ::
boolean(),
Hash ::
binary().
A helper function that plugins can use to implement dependency locking.
If plugin uses this function, it must implement the following callback:
resolve_version(Package, Tag) -> binary()
-spec add_path(kind(), integer(), anvl_project:t(),
file:filename()) -> ok.
Add a local directory to the search path.
Entries with higher Prio are searched first.
-spec add_hook(locate_hook(), integer()) -> ok.
Add function Fun as a dependency discovery hook.
When multiple hooks are capable of resolving the dependency, hooks with higher Priority are chosen.
-spec add_hook(locate_hook()) -> ok.
Equivalent to add_hook(Fun, 0).
-spec location(kind(), dependency()) -> #{dir :=
file:filename(),
project := anvl_project:t()}.
Return location of a resolved dependency.
project field of the return map is set to
a path entry where the dir is located if the path entry is an ANVL project
or to parent project that declared the dependency otherwise.
-spec located(kind(), subdirectory_fun(),
dependency()) -> anvl_condition:t().
Condition: external dependency Dep has been located.