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