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. |
check_external_deps (rockspec, mode) | Set up path-related variables for external dependencies. |
compare_versions (a, b) | Utility function to compare version numbers given as strings. |
fulfill_dependencies (rockspec) | Check dependencies of a rock and attempt to install any missing ones. |
match_constraints (version, constraints) | Check if a version satisfies a set of constraints. |
match_dep (dep, blacklist) | Attempt to match a dependency to an installed rock. |
match_deps (rockspec, blacklist) | Attempt to match dependencies of a rockspec to installed rocks. |
parse_constraint (input) | Consumes a constraint from a string, converting it to table format. |
parse_constraints (input) | Convert a list of constraints from string to table format. |
parse_dep (dep) | Convert a dependency from string to table format. |
parse_version (vstring) | Parse a version string, converting to table format. |
partial_match (version, requested) | A more lenient check for equivalence between versions. |
scan_deps (results, missing, manifest, name, version) | Recursively scan dependencies, to build a transitive closure of all dependent packages. |
show_dep (dep, internal) | Convert a dependency in table format to a string. |
show_version (v, internal) | Convert a version table to a string. |
values_set (tbl) | Return a set of values of a table. |
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.
Return value:
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.
Return value:
boolean: true if v1 is considered lower than v2. - 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.
Return value:
boolean or (nil, string): True if no errors occurred, or nil and an error message if any test failed. - compare_versions (a, b)
-
Utility function to compare version numbers given as strings.
Parameters
- a: string: one version.
- b: string: another version.
Return value:
boolean: True if a > b. - 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.
Return value:
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. - match_constraints (version, constraints)
-
Check if a version satisfies a set of constraints.
Parameters
- version: table: A version in table format
- constraints: table: An array of constraints in table format.
Return value:
boolean: True if version satisfies all constraints, false otherwise. - match_dep (dep, blacklist)
-
Attempt to match a dependency to an installed rock.
Parameters
- dep: table: A dependency parsed in table format.
- blacklist: table: Versions that can't be accepted. Table where keys are program versions and values are 'true'.
Return value:
table or nil: A table containing fields 'name' and 'version' representing an installed rock which matches the given dependency, or nil if it could not be matched. - 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'.
Return value:
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. - parse_constraint (input)
-
Consumes a constraint from a string, converting it to table format. For example, a string ">= 1.0, > 2.0" is converted to a table in the format {op = ">=", version={1,0}} and the rest, "> 2.0", is returned back to the caller.
Parameters
- input: string: A list of constraints in string format.
Return value:
(table, string) or nil: A table representing the same constraints and the string with the unused input, or nil if the input string is invalid. - 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.
Return value:
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.
Return value:
table or nil: A table representing the same dependency relation, or nil if the input string is invalid. - 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.
Return value:
table or nil: A version table or nil if the input string contains invalid characters. - partial_match (version, requested)
-
A more lenient check for equivalence between versions. This returns true if the requested components of a version match and ignore the ones that were not given. For example, when requesting "2", then "2", "2.1", "2.3.5-9"... all match. When requesting "2.1", then "2.1", "2.1.3" match, but "2.2" doesn't.
Parameters
- version: string or table: Version to be tested; may be in string format or already parsed into a table.
- requested: string or table: Version requested; may be in string format or already parsed into a table.
Return value:
boolean: True if the tested version matches the requested version, false otherwise. - scan_deps (results, missing, manifest, name, version)
-
Recursively scan dependencies, to build a transitive closure of all dependent packages.
Parameters
- results: table: The results table being built.
- missing:
- manifest:
- name: string: Package name.
- version: string: Package version.
Return value:
(table, table): The results and a table of missing dependencies. - show_dep (dep, internal)
-
Convert a dependency in table format to a string.
Parameters
- dep: table: The dependency in table format
- internal: boolean or nil: Whether to display versions in their internal representation format or how they were specified.
Return value:
string: The dependency information pretty-printed as a string. - show_version (v, internal)
-
Convert a version table to a string.
Parameters
- v: table: The version table
- internal: boolean or nil: Whether to display versions in their internal representation format or how they were specified.
Return value:
string: The dependency information pretty-printed as a string. - values_set (tbl)
-
Return a set of values of a table.
Parameters
- tbl: table: The input table.
Return value:
table: The array of keys.