Module luarocks.deps
Dependency handling functions.
Dependencies are represented in LuaRocks through strings with a package name followed by a comma-separated list of constraints. Each constraint consists of an operator and a version number. In this string format, version numbers are represented as naturally as possible, like they are used by upstream projects (e.g. "2.0beta3"). Internally, LuaRocks converts them to a purely numeric representation, allowing comparison following some "common sense" heuristics. The precise specification of the comparison criteria is the source code of this module, but the test/test_deps.lua file included with LuaRocks provides some insights on what these criteria are.
Functions
| __eq (v1, v2) | Equality comparison for versions. |
| __lt (v1, v2) | Size comparison for versions. |
| parse_version (vstring) | Parse a version string, converting to table format. |
| compare_versions (a, b) | Utility function to compare version numbers given as strings. |
| parse_constraints (input) | Convert a list of constraints from string to table format. |
| parse_dep (dep) | Convert a dependency from string to table format. |
| show_version (v, internal) | Convert a version table to a string. |
| show_dep (dep, internal) | Convert a dependency in table format to a string. |
| match_constraints (version, constraints) | Check if a version satisfies a set of constraints. |
| match_deps (rockspec, blacklist) | Attempt to match dependencies of a rockspec to installed rocks. |
| fulfill_dependencies (rockspec) | Check dependencies of a rock and attempt to install any missing ones. |
| check_external_deps (rockspec, mode) | Set up path-related variables for external dependencies. |
| scan_deps (results, name, version, missing, manifest) | Recursively scan dependencies, to build a transitive closure of all dependent packages. |
Functions
- __eq (v1, v2)
-
Equality comparison for versions.
All version numbers must be equal.
If both versions have revision numbers, they must be equal;
otherwise the revision number is ignored.
Parameters:
v1: table: version table to compare.v2: table: version table to compare.
Returns:
-
boolean: true if they are considered equivalent.
- __lt (v1, v2)
-
Size comparison for versions.
All version numbers are compared.
If both versions have revision numbers, they are compared;
otherwise the revision number is ignored.
Parameters:
v1: table: version table to compare.v2: table: version table to compare.
Returns:
-
boolean: true if v1 is considered lower than v2.
- parse_version (vstring)
-
Parse a version string, converting to table format.
A version table contains all components of the version string
converted to numeric format, stored in the array part of the table.
If the version contains a revision, it is stored numerically
in the 'revision' field. The original string representation of
the string is preserved in the 'string' field.
Returned version tables use a metatable
allowing later comparison through relational operators.
Parameters:
vstring: string: A version number in string format.
Returns:
-
table or nil: A version table or nil
if the input string contains invalid characters.
- compare_versions (a, b)
-
Utility function to compare version numbers given as strings.
Parameters:
a: string: one version.b: string: another version.
Returns:
-
boolean: True if a > b.
- parse_constraints (input)
-
Convert a list of constraints from string to table format.
For example, a string ">= 1.0, < 2.0" is converted to a table in the format
{{op = ">=", version={1,0}}, {op = "<", version={2,0}}}.
Version tables use a metatable allowing later comparison through
relational operators.
Parameters:
input: string: A list of constraints in string format.
Returns:
-
table or nil: A table representing the same constraints,
or nil if the input string is invalid.
- parse_dep (dep)
-
Convert a dependency from string to table format.
For example, a string "foo >= 1.0, < 2.0"
is converted to a table in the format
{name = "foo", constraints = {{op = ">=", version={1,0}},
{op = "<", version={2,0}}}}. Version tables use a metatable
allowing later comparison through relational operators.
Parameters:
dep: string: A dependency in string format as entered in rockspec files.
Returns:
-
table or nil: A table representing the same dependency relation,
or nil if the input string is invalid.
- show_version (v, internal)
-
Convert a version table to a string.
Parameters:
v: table: The version tableinternal: boolean or nil: Whether to display versions in their internal representation format or how they were specified.
Returns:
-
string: The dependency information pretty-printed as a string.
- show_dep (dep, internal)
-
Convert a dependency in table format to a string.
Parameters:
dep: table: The dependency in table formatinternal: boolean or nil: Whether to display versions in their internal representation format or how they were specified.
Returns:
-
string: The dependency information pretty-printed as a string.
- match_constraints (version, constraints)
-
Check if a version satisfies a set of constraints.
Parameters:
version: table: A version in table formatconstraints: table: An array of constraints in table format.
Returns:
-
boolean: True if version satisfies all constraints,
false otherwise.
- match_deps (rockspec, blacklist)
-
Attempt to match dependencies of a rockspec to installed rocks.
Parameters:
rockspec: table: The rockspec loaded as a table.blacklist: table or nil: Program versions to not use as valid matches. Table where keys are program names and values are tables where keys are program versions and values are 'true'.
Returns:
-
table, table: A table where keys are dependencies parsed
in table format and values are tables containing fields 'name' and
version' representing matches, and a table of missing dependencies
parsed as tables.
- fulfill_dependencies (rockspec)
-
Check dependencies of a rock and attempt to install any missing ones.
Packages are installed using the LuaRocks "install" command.
Aborts the program if a dependency could not be fulfilled.
Parameters:
rockspec: table: A rockspec in table format.
Returns:
-
boolean or (nil, string, [string]): True if no errors occurred, or
nil and an error message if any test failed, followed by an optional
error code.
- check_external_deps (rockspec, mode)
-
Set up path-related variables for external dependencies.
For each key in the external_dependencies table in the
rockspec file, four variables are created:
_DIR, _BINDIR, _INCDIR and _LIBDIR. These are not overwritten if already set (e.g. by the LuaRocks config file or through the command-line). Values in the external_dependencies table are tables that may contain a "header" or a "library" field, with filenames to be tested for existence. Parameters:
rockspec: table: The rockspec table.mode: string: if "build" is given, checks all files; if "install" is given, do not scan for headers.
Returns:
-
boolean or (nil, string): True if no errors occurred, or
nil and an error message if any test failed.
- scan_deps (results, name, version, missing, manifest)
-
Recursively scan dependencies, to build a transitive closure of all
dependent packages.
Parameters:
results: table: The results table being built.name: string: Package name.version: string: Package version.missing:manifest:
Returns:
-
(table, table): The results and a table of missing dependencies.