aboutsummaryrefslogtreecommitdiff
path: root/docs/embedding_luarocks_in_an_application.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/embedding_luarocks_in_an_application.md36
1 files changed, 36 insertions, 0 deletions
diff --git a/docs/embedding_luarocks_in_an_application.md b/docs/embedding_luarocks_in_an_application.md
new file mode 100644
index 00000000..008be1d4
--- /dev/null
+++ b/docs/embedding_luarocks_in_an_application.md
@@ -0,0 +1,36 @@
1# Embedding LuaRocks in an application
2
3You can use LuaRocks bundled inside your application, for example, to install
4application-specific extension modules. Packaging those extensions or plugins
5as rocks reduces maintenance overhead and allows the user to perform updates.
6
7In this scenario, it is not desirable to have the application-specific
8LuaRocks and any other copy of LuaRocks installed by the user (or other
9applications!) to interfere with each other. For this reason, the `configure`
10script allows hardcoding the location of a configuration file. For example,
11the compilation process of a package bundling LuaRocks could do something like
12this:
13
14```bash
15export PREFIX=$HOME/my-app/
16./configure --prefix=$PREFIX --sysconfdir=$PREFIX/luarocks --force-config
17```
18
19The copy of LuaRocks installed in `$HOME/my-app/` will ignore customization
20schemes such as the `$LUAROCKS_CONFIG` environment variable and will only use
21`$HOME/my-app/luarocks/config-5.x.lua`.
22
23An interesting option in those cases is for the application to provide in its
24configuration file an URL for their own rocks repository, so they can have
25control over updates to be performed. Continuing the previous example, the
26config-5.x.lua file could contain something like this:
27
28```lua
29 rocks_servers = {
30 "http://www.example.com/my-app-plugins/rocks/"
31 }
32```
33
34This way the bundled copy of LuaRocks will download rocks from your app's
35plugins and not the https://luarocks.org server (note that the user would
36still be able to override it explicitly using the `--server` flag).