aboutsummaryrefslogtreecommitdiff
path: root/docs/dependencies.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/dependencies.md')
-rw-r--r--docs/dependencies.md91
1 files changed, 91 insertions, 0 deletions
diff --git a/docs/dependencies.md b/docs/dependencies.md
new file mode 100644
index 00000000..eab287aa
--- /dev/null
+++ b/docs/dependencies.md
@@ -0,0 +1,91 @@
1# Dependencies
2
3LuaRocks handles dependencies on Lua modules — rocks can specify other rocks
4it depends on, and attempts to fulfill those dependencies at install time. A
5rock will only be installed if all its dependencies can be fulfilled.
6
7LuaRocks also supports verification of dependencies on external libraries. A
8rock can specify an external package it depends on (for example, a C library),
9and give to LuaRocks hints on how to detect if it is present, typically as C
10header or library filenames. LuaRocks then looks for these files in a
11pre-configured search path and, if found, assumes the dependency is fulfilled.
12If not found, an error message is reported and the user can then install the
13missing external dependency (using the tools provided by their operating
14system) or inform LuaRocks of the location of the external dependency in case
15it was installed and LuaRocks failed to find it.
16
17Dependencies of a rock are specified in its [rockspec](rockspec_format.md)
18file. See the complete specification of the dependency syntax in the [Rockspec
19format](rockspec_format.md) page and examples in rockspec files of the [public
20rocks server](http://luarocks.org/).
21
22# Dependency modes
23
24Since 2.0.12, the LuaRocks command-line tool supports different "dependency
25modes". These are useful to specify how it should behave on the presence of
26multiple rocks trees specified in the [config file](config_file_format.md):
27
28* `one`
29* `all`
30* `order`
31* `none`
32
33This can be set through the configuration file, using the string variable
34deps_mode (example: `deps_mode="order"`) or through the command-line, using the
35`--deps-mode` flag (example: `--deps-mode=order`).
36
37## one
38
39This is the default behavior. LuaRocks only takes **one** rocks tree into
40account when checking dependencies. For example, if you have two rocks trees
41configured (`rocks_trees={home.."/.luarocks", "/usr"}`) and you try to install
42a rock in `$HOME/.luarocks`, it will check that all required dependencies are
43installed _in that tree_. If the dependency rock is already installed under
44`/usr`, it will ignore that copy.
45
46This is a cautious behavior because it ensures that a rock and all its
47dependencies are installed under the same tree. So, if another user modifies
48the other tree, there's no risk that the rock installed in your home tree
49might stop working.
50
51## all
52
53LuaRocks scans **all** configured rocks trees to search for dependencies. If
54the required rock for a dependency is available in _any_ tree, it will
55consider that dependency fulfilled, and will not install that again.
56
57However, note for example that if you install a rock in /usr and its
58dependency was installed in your $HOME tree, the installed rock will work for
59your user account (which has access to the /usr tree and your home tree), but
60will probably not work for other users, if they don't have a compatible
61dependency installed in their own home trees.
62
63## order
64
65LuaRocks uses the **order** of the list of rocks trees to determine if a rocks
66tree should be used as a valid provider of dependencies or not. LuaRocks will
67only use rocks from either the tree it is installing to, or trees that appear
68**below** the rock that's in use in the rocks_trees array. So, if your
69rocks_trees array looks like `{home.."/.luarocks", "/usr/local", "/usr"}`,
70installing a rock under your $HOME directory will accept dependencies from any
71of the three trees. Installing into `/usr/local` will use dependencies from `/usr`
72but not from the `$HOME` directory. Installing into `/usr` will use rocks from
73that tree only.
74
75So, by carefully ordering your array of rocks trees in the configuration file,
76you can use the same configuration file for both your administrator account
77and your regular user account.
78
79Note, however, that like in the "all" mode, an administrator can break a rock
80you installed in your home account by removing a dependency rock from the
81global tree.
82
83## none
84
85LuaRocks does not use any tree, or install any dependencies. This means, of
86course, that installed rocks may be installed with missing dependencies and
87may simply not work. This mode is not recommended for general use, but it is
88useful in some specific scenarios (incorrect dependencies, batch
89recompilation, etc.)
90
91This is equivalent to the old `--nodeps` option.