aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHisham Muhammad <hisham@gobolinux.org>2025-01-05 21:40:39 -0300
committerHisham Muhammad <hisham@gobolinux.org>2025-02-21 11:22:43 -0300
commit7e86fa86b4d08fd6118d6eab46d92b29ffea791e (patch)
tree10fdd12beed4b0eca408533ad11d1f52d7d62e10
parent1ada2ea4bbd94ac0c58e3e2cc918194140090a75 (diff)
downloadluarocks-7e86fa86b4d08fd6118d6eab46d92b29ffea791e.tar.gz
luarocks-7e86fa86b4d08fd6118d6eab46d92b29ffea791e.tar.bz2
luarocks-7e86fa86b4d08fd6118d6eab46d92b29ffea791e.zip
docs: import Wiki docs into the main repo
-rw-r--r--docs/browse_rocks.md13
-rw-r--r--docs/config_file_format.md226
-rw-r--r--docs/creating_a_makefile_that_plays_nice_with_luarocks.md189
-rw-r--r--docs/creating_a_rock.md438
-rw-r--r--docs/creating_luarocks_with_gnu_autotools.md67
-rw-r--r--docs/credits.md24
-rw-r--r--docs/dependencies.md91
-rw-r--r--docs/download.md39
-rw-r--r--docs/embedding_luarocks_in_an_application.md36
-rw-r--r--docs/file_formats.md23
-rw-r--r--docs/file_locations.md110
-rw-r--r--docs/hosting_binary_rocks.md41
-rw-r--r--docs/index.md80
-rw-r--r--docs/installation_instructions_for_macos.md39
-rw-r--r--docs/installation_instructions_for_unix.md140
-rw-r--r--docs/installation_instructions_for_windows.md159
-rw-r--r--docs/integrating_distro_modules_with_luarocks.md190
-rw-r--r--docs/license.md5
-rw-r--r--docs/luarocks.md102
-rw-r--r--docs/luarocks_admin.md19
-rw-r--r--docs/luarocks_admin_add.md53
-rw-r--r--docs/luarocks_admin_help.md17
-rw-r--r--docs/luarocks_admin_make_manifest.md72
-rw-r--r--docs/luarocks_admin_refresh_cache.md47
-rw-r--r--docs/luarocks_admin_remove.md47
-rw-r--r--docs/luarocks_build.md22
-rw-r--r--docs/luarocks_config.md60
-rw-r--r--docs/luarocks_doc.md21
-rw-r--r--docs/luarocks_download.md19
-rw-r--r--docs/luarocks_help.md17
-rw-r--r--docs/luarocks_install.md37
-rw-r--r--docs/luarocks_lint.md15
-rw-r--r--docs/luarocks_list.md27
-rw-r--r--docs/luarocks_make.md27
-rw-r--r--docs/luarocks_new_version.md37
-rw-r--r--docs/luarocks_pack.md31
-rw-r--r--docs/luarocks_path.md32
-rw-r--r--docs/luarocks_purge.md22
-rw-r--r--docs/luarocks_remove.md22
-rw-r--r--docs/luarocks_search.md29
-rw-r--r--docs/luarocks_show.md25
-rw-r--r--docs/luarocks_test.md104
-rw-r--r--docs/luarocks_through_a_proxy.md36
-rw-r--r--docs/luarocks_unpack.md61
-rw-r--r--docs/luarocks_upload.md26
-rw-r--r--docs/luarocks_write_rockspec.md75
-rw-r--r--docs/manifest_file_format.md41
-rw-r--r--docs/more_resources.md32
-rw-r--r--docs/namespaces.md71
-rw-r--r--docs/paths_and_external_dependencies.md43
-rw-r--r--docs/pinning_versions_with_a_lock_file.md52
-rw-r--r--docs/platform_agnostic_external_dependencies.md93
-rw-r--r--docs/platform_overrides.md20
-rw-r--r--docs/recommended_practices_for_makefiles.md176
-rw-r--r--docs/release_history.md597
-rw-r--r--docs/rock_file_format.md51
-rw-r--r--docs/rock_manifest_file_format.md19
-rw-r--r--docs/rocks_repositories.md54
-rw-r--r--docs/rockspec_format.md164
-rw-r--r--docs/tools/docs.tl74
-rw-r--r--docs/tools/lfs.d.tl82
-rw-r--r--docs/types_of_rocks.md32
-rw-r--r--docs/using_luarocks.md198
-rw-r--r--docs/welcome.md17
64 files changed, 4828 insertions, 0 deletions
diff --git a/docs/browse_rocks.md b/docs/browse_rocks.md
new file mode 100644
index 00000000..80be38d8
--- /dev/null
+++ b/docs/browse_rocks.md
@@ -0,0 +1,13 @@
1# Browse rocks
2
3To browse rocks, simply go to:
4
5* [http://luarocks.org](http://luarocks.org)
6
7You can also use the [luarocks search](luarocks_search.md) command in the [luarocks](luarocks.md) command-line tool.
8
9We also have the following mirrors:
10
11* [https://github.com/rocks-moonscript-org/moonrocks-mirror/](https://github.com/rocks-moonscript-org/moonrocks-mirror/)
12* [loadk.com/luarocks](https://loadk.com/luarocks)
13
diff --git a/docs/config_file_format.md b/docs/config_file_format.md
new file mode 100644
index 00000000..3cbe5deb
--- /dev/null
+++ b/docs/config_file_format.md
@@ -0,0 +1,226 @@
1# Config file format
2
3The LuaRocks configuration file is a Lua file containing assignments. Default
4values are assumed for variables that are not assigned explicitly.
5
6The location of the configuration file can be configured through flags during
7installation. If no `--force-config` or `/FORCECONFIG` flags were used on
8installation, the `LUAROCKS_CONFIG` environment variable can be used as well
9(or for a particular Lua version, `LUAROCKS_CONFIG_5_2`, similar to the
10`LUA_PATH_5_2` feature introduced in Lua 5.2).
11
12The default value is platform-dependent; exact paths depend on flags given
13during installation, but on Unix systems it would be something like
14`/etc/luarocks/config.lua` or `/etc/luarocks/config-5.1.lua` for older
15versions of lua; on Windows systems, `c:\luarocks\config.lua`.
16
17Specifically on Unix systems, the following directories are searched (in this
18order) for a user config file:
19
20* `$XDG_CONFIG_HOME/luarocks/`.
21* `$HOME/.config/luarocks/`.
22* `$HOME/.luarocks/`.
23
24# Locations
25
26* `rocks_trees` (array of strings or tables) - The path to the local rocks
27 trees, where rocks are installed. When installing rocks, LuaRocks tries to
28 pick a location to store the rock starting from the bottom of the list; when
29 loading rocks in runtime, LuaRocks scans from the top of the list. This way,
30 if one has the local dir first and the system-wide dir last (this is what
31 the default installation does, for instance), rocks installed by the user
32 take precedence over rocks installed system-wide, and rocks installed by the
33 admin user go to the system-wide dir while user installations go to their
34 home directory. An entry in this table can be:
35 * a string, denoting the prefix of a tree. For example: `home.."/.luarocks"`
36 * a table, where deployment subdirectories of a tree can be further
37 customized. The 'root' field is mandatory; 'bin_dir', 'lib_dir' and
38 'lua_dir' are optional. Example: `{ root = home.."/local", bin_dir =
39 home.."/local/arch/bin", lib_dir = home.."/local/arch/lib/lua/5.1",
40 lua_dir = home.."/local/share/lua/5.1" }`
41
42* `rocks_servers` (array of strings) - Remote URLs or local pathnames of rocks
43 servers: directories containing .rock or .rockspec files, and a "manifest"
44 file, generated by the luarocks-admin make_manifest command. Default is {
45 "http://luarocks.org/repositories/rocks" }.
46
47* `external_deps_dirs` (array of strings) - Where to look for external
48 dependencies, when a prefix is not set for a specific dependency in the
49 _variables_ table (see below) or through the command-line. Default is {
50 "/usr/local", "/usr" } on Unix; { "c:\\external" } on Windows.
51
52* `external_deps_subdirs` (table with string keys and string values) -
53 Subdirectories to be used in conjunction with external_deps_dirs. Specifies
54 where to look for specific types external dependencies. This can be
55 overriden, for example, on Linux distributions which feature multiarch
56 libraries and libraries are no longer in the "lib" subdir. Default is { bin
57 = "bin", lib = "lib", include = "include" }.
58
59* `runtime_external_deps_subdirs` (table with string keys and string values) -
60 Same as the above, to be used with _luarocks install_.
61
62* `lib_modules_path` (string) - The path where modules with native C
63 extensions will be installed. If you are using a x86_64 *nix OS, you will
64 probably need this line in `config.lua`:
65 `lib_modules_path="/lib64/lua/"..lua_version`. See [issue
66 416](https://github.com/keplerproject/luarocks/issues/416).
67
68# File upload
69
70* `upload_server` (string) - An FTP URL for a rock server (optionally
71 including username and password), or an alias specified in the
72 upload_servers table. Example:
73 `"ftp://_user_:_password_@ftp.luarocks.org/repositories/rocks"`
74
75* `upload_user` (string) - Default login name rock servers.
76
77* `upload_password` (string) - Default password rock servers.
78
79* `upload_servers` (table with string keys and table values) - A list of
80 aliases for URLs, to be used for accessing repositories through various
81 protocols. Each entry has a string alias as a key and a table as a value.
82 This table value contains protocol names as keys and pathnames as values.
83 Protocols "http", "ftp" and "sftp" are supported. Example: `{ rocks = { http
84 = "www.example.com/rocks", sftp = "example.com/var/rocks" } }`
85
86# Platform-specific settings
87
88* `lua_extension` (string) - Filename extension of Lua files (without the
89 dot/separator). Default is "lua".
90
91* `lib_extension` (string) - Filename extension of dynamic library files
92 (without the dot/separator). Default is "so" on Unix; "dll" on Windows.
93
94* `arch` (string) - A two-part string identifying operating system and
95 hardware architecture, for filtering binary rocks. This value is
96 autodetected by LuaRocks. Example values are "macosx-powerpc" and
97 "win32-x86".
98
99* `platforms` (array of string) - A list of string identifiers indicating
100 which platform constraints can be satisfied by the running system. This is
101 used for filtering commands on the LuaRocks build rules. This allows a more
102 general platform definition such as "unix" when the same build commands are
103 valid for all Unix variants, instead of enumerating all known valid arch
104 entries, and at the same time using a more specific definition such as
105 "macosx" when a platform-specific flag is used. This value is automatically
106 filled according to the value of _arch_.
107
108* `external_deps_patterns` (table) - Name patterns to be used when matching
109 dependencies in a [portable
110 way](platform_agnostic_external_dependencies.md).
111
112* `runtime_external_deps_patterns` (table) - Name patterns to be used by
113 _luarocks install_ when matching dependencies in a [portable
114 way](platform_agnostic_external_dependencies.md).
115
116* `link_lua_explicitly` (boolean) - Link the Lua library to the built modules
117 when using the builtin mode (this is set to true for Cygwin).
118
119# Variables
120
121* `variables` (table) - A table containing string-to-string key-value pairs
122 containing variables to be substituted by build rules in rockspecs. LuaRocks
123 provides a general facility for build back-ends in which they can substitute
124 the entries of this table in strings containing references written
125 $(LIKE_THIS). Some standard variables are expected by the included
126 back-ends. For example, the "make" back-end expects the LIBFLAG to contain
127 the flag to be passed to the C compiler to instruct it to build a shared
128 library. So, in Linux systems, `variables["LIBFLAG"] = "-shared"`.
129
130After reading the user entries, LuaRocks dynamically adds entries to this
131table that refer to the rock being compiled, to make values available to the
132build back-end. These are:
133
134* `PREFIX` - The installation prefix of the rock (absolute path inside the
135 rocks tree). Example: `"/home/hisham/.luarocks/5.1/foo/1.0-1/"`
136
137 * `LUADIR` - Directory for storing Lua modules written in Lua (absolute path
138 inside the rock entry of the rocks tree). Example:
139 `"/home/hisham/.luarocks/5.1/foo/1.0-1/lua/"`
140
141 * `LIBDIR` - Directory for storing Lua modules written in C (absolute path
142 inside the rock entry of the rocks tree). Example:
143 `"/home/hisham/.luarocks/5.1/foo/1.0-1/lib/"`
144
145 * `BINDIR` - Directory for storing command-line scripts (absolute path
146 inside the rock entry of the rocks tree). Example:
147 `"/home/hisham/.luarocks/5.1/foo/1.0-1/bin/"`
148
149 * `CONFDIR` - Directory for storing configuration files for a module
150 (absolute path inside the rock entry of the rocks tree). Example:
151 `"/home/hisham/.luarocks/5.1/foo/1.0-1/conf/"`
152
153Such entries should not be added by the user in the configuration file, as
154they are dynamically constructed for each different rock. If you need to
155customize the various locations where files are deployed in a tree, use the
156table syntax for `rocks_trees` entries (see above).
157
158<font color="green">(since 2.0.5)</font> You can also override external
159commands called by LuaRocks by using entries in the _variables_ table, in case
160you need to customize the way they are called. Note that by installing
161appropriate Lua modules, most of these external command invocations can be
162avoided. Currently recognized entries in the _variables_ table are:
163
164* `MAKE` for build.type="make";
165
166* `CC, LD` (and `RC` on Windows) for build.type="builtin";
167
168* `CVS, GIT, SSCM, SVN` for their respective download protocols;
169
170* `RSYNC, SCP` for luarocks-admin operations;
171
172* `WGET` or `CURL` when LuaSocket is not installed;
173
174* `PWD, MKDIR, RMDIR, CP, LS, RM, FIND, TEST, CHMOD, STAT` when LuaFileSystem
175 is not installed;
176
177* `ZIP` when Lua-Zlib is not installed;
178
179* `UNZIP` when LuaZip is not installed;
180
181* `GUNZIP, BUNZIP2, TAR` on Unix or `SEVENZ` on Windows for source extraction
182 during "luarocks build";
183
184* `MD5SUM, OPENSSL` or `MD5` according to the operating system, when the Lua
185 md5 module is not installed.
186
187# External input
188
189As the config file itself is a Lua code file, there is some possibility to
190execute Lua code. Because it is run in a sandbox this is very limited, but
191might still be useful.
192
193What LuaRocks makes available:
194
195* parameters/values: several values are made available to the config file
196 (pre-loaded in the sandbox) and include things like processor and OS
197 platform, rocks trees which are in use, etc. (see `dump_env()` below)
198
199* function: `os_getenv(varname)`; this is the regular Lua function
200 `os.getenv()` and allows one to fetch environment variable values from the
201 OS.
202
203* function: `dump_env()`; this will dump a list of all variables provided by
204 LuaRocks as a debug aid.
205
206To test this, add a line `dump_env()` to your config file and execute
207`luarocks` on the commandline to see the results.
208
209# Other
210
211* `cmake_generator` (string) - If specified it overrides the default cmake
212 generator. Currently only Makefile-based generators are supported.
213
214* `wrap_bin_scripts` (boolean) - The default value is true: scripts installed
215 at bin/ are launched by a wrapper script that sets path environment
216 variables to ensure Lua modules are found. If set to false, scripts
217 installed at bin/ are copied directly, and no wrappers are generated.
218
219* `use_extensions` (boolean) - If specified, rockspec format verison 1.1 is
220 enabled, adding the deploy.wrap_bin_scripts option to the rockspec format,
221 which acts like the wrap_bin_scripts option above, in a rock by rock basis.
222
223* `local_by_default` (boolean) - If `true`, the tree in the user's home
224 directory is used as if the command line option `--local` had been given
225
226
diff --git a/docs/creating_a_makefile_that_plays_nice_with_luarocks.md b/docs/creating_a_makefile_that_plays_nice_with_luarocks.md
new file mode 100644
index 00000000..d6d43a6b
--- /dev/null
+++ b/docs/creating_a_makefile_that_plays_nice_with_luarocks.md
@@ -0,0 +1,189 @@
1# Creating a Makefile that plays nice with LuaRocks
2
3The page about [Recommended practices for
4Makefiles](recommended_practices_for_makefiles.md) mentions what you should do
5in order to create a Makefile that LuaRocks can work with. What it does not do
6is to explain how to interact between your rockspec and the Makefile so that
7your rock will install in a way such that LuaRocks knows everything it needs
8to know to handle everything after the installation (like, for example,
9removal).
10
11LuaRocks creates a few very important variables for you, that you can pass to
12your Makefile. They come in 2 varieties, one set for building the module and
13another set for installing it. The variables are:
14
15For building:
16
17* `CFLAGS` - flags for the C compiler
18* `LIBFLAG` - the flags needed for the linker to create shared libraries
19* `LUA_LIBDIR` - where to find the lua libraries
20* `LUA_BINDIR` - where to find the lua binary
21* `LUA_INCDIR` - where to find the lua headers
22* `LUALIB` - the name of the lua library. This is not available nor needed on all platforms.
23* `LUA` - the name of the lua interpreter
24
25For installing:
26
27* `PREFIX` - basic installation prefix for the module
28* `BINDIR` - where to put user callable programs or scripts
29* `LIBDIR` - where to put the shared libraries
30* `LUADIR` - where to put the lua files
31* `CONFDIR` - where to put your modules configuration
32
33Most of these variables point immediately where you'd expect them to, but
34`BINDIR`, `LIBDIR` and `LUADIR` are special. These point to a location where
35you need to put the files in order for LuaRocks to move them to their final
36destination. If you install your stuff here, then LuaRocks will know what
37files your module installed and can later remove them.
38
39These variables are not readily available in the Makefile, you need to tell
40LuaRocks to pass them to make. A simple rockspec that will do this looks
41like this:
42
43```
44package = "lrtest"
45version = "1.0-1"
46source = {
47 url = "http://..."
48}
49build = {
50 type = "make",
51 build_variables = {
52 CFLAGS="$(CFLAGS)",
53 LIBFLAG="$(LIBFLAG)",
54 LUA_LIBDIR="$(LUA_LIBDIR)",
55 LUA_BINDIR="$(LUA_BINDIR)",
56 LUA_INCDIR="$(LUA_INCDIR)",
57 LUA="$(LUA)",
58 },
59 install_variables = {
60 INST_PREFIX="$(PREFIX)",
61 INST_BINDIR="$(BINDIR)",
62 INST_LIBDIR="$(LIBDIR)",
63 INST_LUADIR="$(LUADIR)",
64 INST_CONFDIR="$(CONFDIR)",
65 },
66}
67```
68
69The corresponding Makefile looks like this:
70
71```
72all:
73 @echo --- build
74 @echo CFLAGS: $(CFLAGS)
75 @echo LIBFLAG: $(LIBFLAG)
76 @echo LUA_LIBDIR: $(LUA_LIBDIR)
77 @echo LUA_BINDIR: $(LUA_BINDIR)
78 @echo LUA_INCDIR: $(LUA_INCDIR)
79 @echo LUA: $(LUA)
80
81install:
82 @echo --- install
83 @echo INST_PREFIX: $(INST_PREFIX)
84 @echo INST_BINDIR: $(INST_BINDIR)
85 @echo INST_LIBDIR: $(INST_LIBDIR)
86 @echo INST_LUADIR: $(INST_LUADIR)
87@echo INST_CONFDIR: $(INST_CONFDIR)
88```
89
90Now, if you call `luarocks make`, the output will look something
91like this:
92
93```
94-- build
95CFLAGS: -O2 -fPIC
96LIBFLAG: -shared
97LUA_LIBDIR: /usr/local/lib
98LUA_BINDIR: /usr/local/bin
99LUA_INCDIR: /usr/local/include
100
101-- install
102INST_PREFIX: /usr/local/lib/luarocks/rocks/lrtest/1.0-1
103INST_BINDIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/bin
104INST_LIBDIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/lib
105INST_LUADIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/lua
106INST_CONFDIR: /usr/local/lib/luarocks/rocks/lrtest/1.0-1/conf
107```
108
109You will notice that the aforementioned special variables do not point to
110the location you'd expect them to. LuaRocks will move files you put there
111to their final destination for you, and in the process keep track of what
112was installed.
113
114The `CONFDIR` and `PREFIX` variables point to locations
115where you can store configuration or other data for your module. Your code
116must be made aware of these paths in order to use them. If you use the
117`copy_directories` entry in the build section of your rockspec,
118then what is mentioned there is copied to $(PREFIX) (i.e. a directory doc
119will be available unter $(PREFIX)/doc). If you copy directories in your
120`install` Makefile rule, you should do the same.
121
122Now, if your Makefile is meant to be used standalone as well, which it
123probably is, you would also want to define these variables inside of your
124Makefile, but in such a way that it will not hinder LuaRocks. Luckily
125variables passed on the command line to make override those defined in
126the Makefile.
127
128With this, a Makefile that is usable both from LuaRocks and standalone
129might look like this:
130
131```
132CFLAGS = -fPIC -O2
133LIBFLAG = -shared
134LUA_LIBDIR = /usr/local/lib/lua/5.2
135LUA_BINDIR = /usr/local/bin
136LUA_INCDIR = /usr/local/include
137LUA = lua
138
139INST_PREFIX = /usr/local
140INST_BINDIR = $(INST_PREFIX)/bin
141INST_LIBDIR = $(INST_PREFIX)/lib/lua/5.2
142INST_LUADIR = $(INST_PREFIX)/share/lua/5.2
143INST_CONFDIR = $(INST_PREFIX)/etc
144
145all:
146 @echo --- build
147 @echo CFLAGS: $(CFLAGS)
148 @echo LIBFLAG: $(LIBFLAG)
149 @echo LUA_LIBDIR: $(LUA_LIBDIR)
150 @echo LUA_BINDIR: $(LUA_BINDIR)
151 @echo LUA_INCDIR: $(LUA_INCDIR)
152
153install:
154 @echo --- install
155 @echo INST_PREFIX: $(INST_PREFIX)
156 @echo INST_BINDIR: $(INST_BINDIR)
157 @echo INST_LIBDIR: $(INST_LIBDIR)
158 @echo INST_LUADIR: $(INST_LUADIR)
159 @echo INST_CONFDIR: $(INST_CONFDIR)
160```
161
162You probably don't just want to echo stuff, so here's how to use the variables
163when actually building or installing something:
164
165```
166...
167
168all: lrtest.so
169
170lrtest.so: lrtest.o
171 $(CC) $(LIBFLAG) -o $@ -L$(LUA_LIBDIR) $<
172
173lrtest.o: lrtest.c
174 $(CC) -c $(CFLAGS) -I$(LUA_INCDIR) $< -o $@
175
176install: lrtest.so lrtest.lua
177 cp lrtest.so $(INST_LIBDIR)
178 cp lrtest.lua $(INST_LUADIR)
179```
180
181There is of course a lot more to a proper Makefile and rockspec, this is only
182to show how to take advantage of LuaRocks' builtin helpers for this sort of
183thing. Also, keep in mind that for additional external dependencies, more
184variables are created by LuaRocks, which have to be passed to the Makefile in
185the same way. Check the other documentation, especially [Rockspec
186format](rockspec_format.md) and [Recommended practices for
187Makefiles](recommended_practices_for_makefiles.md), for details.
188
189
diff --git a/docs/creating_a_rock.md b/docs/creating_a_rock.md
new file mode 100644
index 00000000..e93505ac
--- /dev/null
+++ b/docs/creating_a_rock.md
@@ -0,0 +1,438 @@
1# Creating a rock
2
3So, you wrote a Lua package (containing one or more modules) and want to make
4it available to users through LuaRocks. The process consists essentially of
5the following steps:
6
7* Writing a rockspec file
8* Publishing your code online
9* Submitting a rockspec for inclusion in the rocks server
10
11## Writing a rockspec
12
13A rockspec file is the metadata file for your package, containing all the
14information LuaRocks needs in order to fetch, build and install your package.
15The [Rockspec format](rockspec_format.md) supports various kinds of build
16systems, but in this tutorial we'll use LuaRocks' own built-in build system --
17that's why we're listing "Writing a rockspec" as the first step. We'll use the
18rockspec in place of a Makefile.
19
20A rockspec is actually a Lua file, but it is loaded in an empty environment,
21so there are no Lua functions available. A skeleton for a basic rockspec looks
22can be written by hand or generated using [luarocks write_rockspec](luarocks_write_rockspec.md).
23It may look like this:
24
25```lua
26package = "LuaFruits"
27version = "1.0-1"
28source = {
29 url = "..." -- We don't have one yet
30}
31description = {
32 summary = "An example for the LuaRocks tutorial.",
33 detailed = [[
34 This is an example for the LuaRocks tutorial.
35 Here we would put a detailed, typically
36 paragraph-long description.
37 ]],
38 homepage = "http://...", -- We don't have one yet
39 license = "MIT/X11" -- or whatever you like
40}
41dependencies = {
42 "lua >= 5.1, < 5.4"
43 -- If you depend on other rocks, add them here
44}
45build = {
46 -- We'll start here.
47}
48```
49
50This should be saved in a file called luafruits-1.0-1.rockspec. The name must
51contain lowercase versions of the "package" and "version" fields, or else
52LuaRocks will complain.
53
54There is some missing stuff in our rockspec which we will fill later, such as
55the source.url and description.homepage fields. We'll add those when we upload
56our sources whatever server you choose to.
57
58Right now our focus will be on the "build" section.
59
60### Building a module
61
62LuaRocks supports a number of "build types": "make" for using Makefiles,
63"cmake" for using CMake, etc. In this tutorial, however, we'll use its
64built-in build system, called the "builtin" type.
65
66```lua
67build = {
68 type = "builtin"
69 -- Now we need to tell it what to build.
70}
71```
72
73In the "builtin" type, we add a subtable called "modules", in which keys are
74module names in Lua notation, and values indicate how to build them. This
75example shows the various possibilities supported:
76
77```lua
78build = {
79 type = "builtin",
80 modules = {
81 -- A simple module written in Lua
82 apricot = "src/apricot.lua",
83
84 -- Note the required Lua syntax when listing submodules as keys
85 ["apricot.seeds"]("apricot.seeds") = "src/apricot/seeds.lua",
86
87 -- A simple module written in C
88 banana = "src/banana.c",
89
90 -- C modules can span multiple files.
91 cherry = {"src/cherry.c", "src/cherry_pie.c"},
92
93 -- C modules also support an extended syntax, supporting
94 -- cross-platform specifications of C defines, libraries and
95 -- paths for external dependencies.
96 date = {
97 sources = {"src/date.c", "src/cali_date.c", "src/arab_date.c"},
98 defines = {"MAX_DATES_PER_MEAL=50"},
99 libraries = {"date"},
100 incdirs = {"$(LIBDATE_INCDIR)"},
101 libdirs = {"$(LIBDATE_LIBDIR)"}
102 }
103 }
104}
105```
106
107Since modules written in Lua do not need to be compiled, LuaRocks only needs
108to know where they are in your source directory tree in order to copy them to
109the proper place on installation (see the "apricot" and "apricot.seeds" in the
110above example).
111
112Similarly, for C code with no dependencies on external libraries, it suffices
113to say where the sources are and LuaRocks will invoke the appropriate compiler
114and linker for the platform. You can use a simple string value for single-file
115modules, such as the "banana" example above or an array value for multiple
116source files (as in the "cherry" example).
117
118To make writing rocks for projects with a common directory layout even easier,
119the "builtin" build type recursively copies all files and directories it finds
120in a folder called "./lua" (if it exists) to the same place as other Lua
121files. It's almost as if an entry had been added to `modules` for every file
122in `lua`, except that the files will only be copied - files ending in ".c"
123won't be compiled.
124
125#### Depending on other rocks
126
127You can specify that your code depends on other rocks, so you can use modules
128from other rocks in your code and have them be automatically downloaded and
129installed when a user installs your rock.
130
131Suppose we need the modules from the "luaknife" rock, in order to cut our
132fruits. But we need version later than 2.3 of luaknife, because we're using
133functions that were introduced in that version. We'll add that to our
134dependencies table:
135
136```lua
137dependencies = {
138 "lua >= 5.1, < 5.4",
139 "luaknife >= 2.3"
140}
141```
142
143Note that the dependency on Lua itself is also given in that table, and that
144it uses two constraints on its version at once: `>= 5.1` and `< 5.4`. When
145several constraints are used like this, they all have to be satisfied.
146Therefore, `lua >= 5.1, < 5.4` means that our rock supports Lua `5.1`, `5.2`,
147and `5.3`, but not yet-to-be-released `5.4`. There are a few other operators
148for specifying version constraints, see
149[Rockspec format](rockspec_format.md#dependency-information).
150
151#### C modules linking to external libraries
152
153*If your code does not use third-party libraries, you may skip this subsection.*
154
155For building C code that links to C libraries, you can use the long syntax
156given in the "date" example above, in which sources are listed in the
157"sources" subtable. You need to specify the libraries to be linked in the
158"libraries" subtable. The library name is specified in a platform-independent
159way: in the above example, `libraries={"date"}` will result in `-ldate` for
160GCC on Unix and `DATE.LIB` for MSVC on Windows. (Note that if this is not
161appropriate, the rockspec format allows [per-platform
162overrides](platform_overrides.md).) If you need to link code that uses
163libraries, you need to tell LuaRocks where to find them. You do this by adding
164a new section to the rockspec:
165
166```lua
167external_dependencies = {
168 LIBDATE = {
169 header = "libdate.h"
170 }
171}
172```
173
174Adding the "external_dependencies" table will make LuaRocks search for the
175external dependencies in its lookup path (on Unix the defaults are
176`/usr/local` and `/usr`; on Windows, which doesn't have a standard for
177development trees, you'll probably have to specify it yourself through the
178[Config file format](config_file_format.md) or the [luarocks](luarocks.md) when
179invoking "luarocks"). We give a hint to LuaRocks, the `libdate.h` header, so
180it can test whether the development package is really there (on many Linux
181distros, one needs to install "-dev" packages in order to have all headers and
182libraries needed for compilation available, so header files are a good hint).
183In this case, for example, it would look for `/usr/local/include/libdate.h`
184and `/usr/include/libdate.h` on Unix. If you (or your users) have LibDate
185installed elsewhere, it's always possible to tell LuaRocks so through the
186command-line, passing for example `LIBDATE_DIR=/opt/libdate` as an argument.
187
188When LuaRocks succeeds finding an external dependency, it creates special
189variables for it which can be used in incdirs and libdirs fields. The example
190above shows two such variables, `LIBDATE_INCDIR` and `LIBDATE_LIBDIR` being
191use. It's important to always pass those variables: if LibDate happened to be
192in the system lookup path of your compiler, compilation would succeed without
193those variables, but they would fail in a user's system where they are
194somewhere else, such as in the `LIBDATE_DIR=/opt/libdate` example given
195earlier.
196
197### Using LuaRocks as a build system
198
199Now that your build section is written, you can use LuaRocks as a build system
200and have it compile and install your code as a rock. Just type:
201
202```
203luarocks make
204```
205
206and it will do its thing. Like "make", it will look for the appropriate rules
207file (in our case, the rockspec) in the current directory and then will
208proceed to build and install the package in your rocks tree, assuming the
209sources are in the current directory as well.
210
211### Including documentation and other files
212
213In the build section you can include arbitrary files through the
214"copy_directories" table. In this table you can list directories in your rock
215that will be copied to the target rocktree during installation.
216
217```lua
218 copy_directories = { "doc", "test" }
219```
220
221A special case for these is the "doc" directory for locally installed
222documentation. Documentation installed this way will be available on the
223target system through
224
225```
226luarocks doc ROCKNAME
227```
228
229## Publishing your code online
230
231Now, to complete the rockspec for public consumption we need to fill the
232sources.url field. For that, we need the code to be available online. We have
233two approaches for that: if you have your source code in an online repository
234such as [GitHub](GitHub)(https://github.com), you may use that directly.
235Alternatively, you can publish a tarball with the sources on the web.
236
237### Method 1: using a repository such as Github
238
239Make sure your release is tagged in your repository. Failing to use a tag will
240make LuaRocks point at your latest development code, making it a "moving
241target". LuaRocks users should be directed to a specific version of your code.
242(If you want to make a rockspec pointing at your repository's HEAD, use "scm"
243as the version number of your rockspec -- this will identify it as a rockspec
244for the "unstable" version.)
245
246In the `source.url` field, enter the URL for your repository using your SCM tool
247as the protocol. For git repositories, you don't need use the .git extension.
248Then, use the `source.tag` entry to specify your tag. For example, this is how
249our source section would look like if we hosted LuaFruits on Github:
250
251```lua
252source = {
253 url = "git://github.com/me/luafruits",
254 tag = "v1.0",
255}
256```
257
258To tag a release in Git, use the "git tag" command, and remember to pass the
259"--tags" flag to "git push":
260
261```
262git tag v1.0
263git push --tags
264```
265
266Or use GitHub's "Releases" interface.
267
268LuaRocks also supports other source control management systems, such as CVS
269(cvs://), Subversion (svn://) and Mercurial (hg://).
270
271Don't worry about deployment complications when using this method. When you
272submit a rock for inclusion in the LuaRocks repository, a .src.rock file is
273generated which contains a copy of the source code, so LuaRocks users won't
274need to have Git or any other such tool installed to use your rock.
275
276### Method 2: publishing a tarball
277
278When using a zip or tarball, by default LuaRocks expects it to contain a
279top-level directory with your code. This directory should be named the same as
280the tarball itself (but without the .zip or .tar.gz extension) and its
281recommended that this name be the lowercase name of the package with its
282version number (but without the LuaRocks revision number). If your code is
283located in a different directory, please see [Rockspec
284format](rockspec_format.md) for instructions. In our example, we should make a
285tarball with the following contents:
286
287```
288luafruits-1.0/
289luafruits-1.0/src/apricot.lua
290luafruits-1.0/src/apricot/seeds.lua
291luafruits-1.0/src/banana.c
292luafruits-1.0/src/cherry.c
293luafruits-1.0/src/cherry_pie.c
294luafruits-1.0/src/date.c
295luafruits-1.0/src/cali_date.c
296luafruits-1.0/src/arab_date.c
297```
298
299Note that the rockspec itself doesn't need to be stored in the tarball
300(actually, storing the final rockspec inside the package is a chicken-egg
301problem because rockspecs can contain the source.md5 field with a checksum of
302the tarball).
303
304It's important to note that LuaRocks does not enforce the internal structure.
305Our example only has a src/ subdirectory because the build rules listed above
306used it (we could have done without it if we wanted to). The tarball could
307contain other files as well, such as licenses and documentation. The only
308convention used here is the top level directory name, and if desired this can
309be overridden in the rockspec using the sources.dir field. So, now we pack our
310code. On Unix, for example, that would be:
311
312```
313tar czvpf luafruits-1.0.tar.gz luafruits-1.0/
314```
315
316And now we're ready to publish the tarball online. You can upload it to any
317public web server; if you need hosting space, you can use the Pages feature
318from [GitHub](GitHub)(https://github.com). Your source section would then look
319something like this:
320
321```lua
322source = {
323 url = "http://me.github.com/luafruits/luafruits-1.0.tar.gz"
324}
325```
326
327## The completed rockspec
328
329We're ready to complete our rockspec. By now it will look like this:
330
331```lua
332package = "LuaFruits"
333version = "1.0-1"
334source = {
335 url = "git://github.com/me/luafruits",
336 tag = "v1.0",
337}
338description = {
339 summary = "An example for the LuaRocks tutorial.",
340 detailed = [[
341 This is an example for the LuaRocks tutorial.
342 Here we would put a detailed, typically
343 paragraph-long description.
344 ]],
345 homepage = "http://me.github.com/luafruits",
346 license = "MIT/X11"
347}
348dependencies = {
349 "lua >= 5.1, < 5.4",
350 "luaknife >= 2.3"
351}
352external_dependencies = {
353 LIBDATE = {
354 header = "libdate.h"
355 }
356}
357build = {
358 type = "builtin",
359 modules = {
360 apricot = "src/apricot.lua",
361 ["apricot.seeds"]("apricot.seeds") = "src/apricot/seeds.lua",
362 banana = "src/banana.c",
363 cherry = {"src/cherry.c", "src/cherry_pie.c"},
364 date = {
365 sources = {"src/date.c", "src/cali_date.c", "src/arab_date.c"},
366 defines = {"MAX_DATES_PER_MEAL=50"}
367 libraries = {"date"},
368 incdirs = {"$(LIBDATE_INCDIR)"},
369 libdirs = {"$(LIBDATE_LIBDIR)"}
370 }
371 },
372 copy_directories = { "doc", "test" }
373}
374```
375
376## Submitting a rockspec for inclusion in the rocks server
377
378### Web upload
379
380This is the simplest step: just create an account at
381https://luarocks.org/register and upload your rockspec. It will automatically
382be included in the public LuaRocks repository once the mirror propagates the
383change. Users of LuaRocks >= 2.2 will be able to download your package
384immediately. We will usually publish both the .rockspec file and the
385appropriate .rock file in the server.
386
387### Pack command
388
389You can also create .rock files yourself. If you run the [luarocks
390pack](luarocks_pack.md) command on your rockspec, like this:
391
392```
393luarocks pack luafruits-1.0-1.rockspec
394```
395
396you will get a file called luafruits-1.0-1.src.rock, which contains the
397rockspec itself and your sources. Since it contains the source code, users
398won't need to use Git or whatever tool specified in source.url to fetch the
399code; it's all in the rock.
400
401If you have the rock installed in your local tree, you can also pack the
402binaries you just built:
403
404```
405luarocks pack luafruits
406```
407
408(The version is optional, latest is assumed.) This will create a file with a
409name such as luafruits-1.0-1.linux-x86.rock.
410
411### Upload command
412
413When you've verified that creating the rock works, you can upload it to the
414LuaRocks server with the [luarocks upload](luarocks_upload.md) command:
415
416```
417luarocks upload luafruits-1.0-1.rockspec --api-key=<your API key>
418```
419
420You can get an API from the [settings page of your account on the LuaRocks web
421site](https://luarocks.org/settings/api-keys).
422
423## Conclusion
424
425And we're done -- by writing a simple rules file which simply describes which
426sources compose the project and which libraries they use, we actually achieved
427a lot behind the scenes: LuaRocks takes care of using the right compiler for
428your platform (GCC? MSVC?), passing the right flags (-fpic? -shared? -bundle
429-undefined dynamic_lookup?) and checking external dependencies (/usr/lib?
430/usr/local/lib? Is it really there?). Getting all these little portability
431details right is not always easy to do on hand-written Makefiles, so that's
432why we recommend using LuaRocks's own build system whenever possible. There
433are many other features of LuaRocks we haven't covered in this tutorial
434(per-platform overrides, support for command-line scripts, etc.), but this
435should get you started.
436
437
438
diff --git a/docs/creating_luarocks_with_gnu_autotools.md b/docs/creating_luarocks_with_gnu_autotools.md
new file mode 100644
index 00000000..3e684691
--- /dev/null
+++ b/docs/creating_luarocks_with_gnu_autotools.md
@@ -0,0 +1,67 @@
1# Creating LuaRocks with GNU autotools
2
3Note that LuaRocks requires packages to be relocatable, and GNU autotools by
4default builds non-relocatable packages. For many programs it's not necessary
5to do anything particular to make them relocatable; applications which need to
6find resources at run-time may be problematic. See GNU Smalltalk for one
7approach (look at the RELOCATABILITY section in its configure.ac).
8[Zee](http://github.com/rrthomas/zee) uses another approach, of patching in
9paths for in-place running of the program during development, and relying on
10Lua search paths at run-time, purely to find Lua modules. Search for
11'in_place_lua_path'.
12
13Use a rockspec template like the following, and call it $PACKAGE.rockspec.in:
14
15```
16package="@PACKAGE@"
17 version="@VERSION@-1"
18 source = {
19 url = "https://github.com/downloads/<USER>/@PACKAGE@/@PACKAGE@-@VERSION@.tar.gz",
20 md5 = "@MD5@",
21 dir = "@PACKAGE@-@VERSION@"
22 }
23 description = {
24 summary = "<Short summary>",
25 detailed = [[
26 <Detailed information.>
27 ]],
28 homepage = "http://github.com/<USER>/@PACKAGE@/",
29 license = "<LICENSE>"
30 }
31 dependencies = {
32 "lua >= 5.1"
33 }
34 build = {
35 type = "command",
36 build_command = "LUA=$(LUA) CPPFLAGS=-I$(LUA_INCDIR) ./configure --prefix=$(PREFIX) --libdir=$(LIBDIR) --datadir=$(LUADIR) && make clean && make",
37 install_command = "make install"
38 }
39```
40
41Add "$PACKAGE.rockspec.in" to AC_CONFIG_FILES in your configure.ac:
42
43Add or amend the following rules in your Makefile.am:
44
45```
46ROCKSPEC = $(PACKAGE)-$(VERSION)-1.rockspec
47```
48
49```
50$(ROCKSPEC): $(PACKAGE).rockspec dist
51 sed -e 's/@MD5@/'`$(MD5SUM) $(distdir).tar.gz | \
52 cut -d " " -f 1`'/g' < $(PACKAGE).rockspec > $@
53```
54
55```
56EXTRA_DIST = $(PACKAGE).rockspec.in
57```
58
59```
60DISTCLEANFILES = $(PACKAGE).rockspec
61```
62
63You can use [woger](http://github.com/rrthomas/woger/) to automate your
64releases, uploading rockspecs to luarocks.org and announcements to the Lua
65mailing list. The details are evolving, so see woger itself for details, and a
66frequently-updated project such as
67[luaposix](http://github.com/luaposix/luaposix/) for example Makefile.am code.
diff --git a/docs/credits.md b/docs/credits.md
new file mode 100644
index 00000000..e5d6232c
--- /dev/null
+++ b/docs/credits.md
@@ -0,0 +1,24 @@
1# Credits
2
3# Institutional Sponsors
4
5While developed by an open source community, LuaRocks has been supported in
6various forms by a number of organizations over the years and we thank every
7one of them:
8
9* [CNPq](http://www.cnpq.br)
10* [Fábrica Digital](http://www.fabricadigital.com.br/)
11* [FINEP](http://www.finep.gov.br/)
12* [IMPA](http://www.impa.br/)
13* [LabLua](http://www.lua.inf.puc-rio.br/)
14* [itch.io](http://itch.io/)
15* [Kong](http://getkong.org/)
16
17# Developers
18
19LuaRocks is a collective project, a product of [many
20hands](https://github.com/luarocks/luarocks/graphs/contributors). The
21implementation is led by [Hisham Muhammad](http://hisham.hm), but see the [Git
22history](https://github.com/luarocks/luarocks/commits/master) for
23detailed credits.
24
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.
diff --git a/docs/download.md b/docs/download.md
new file mode 100644
index 00000000..fd8c6655
--- /dev/null
+++ b/docs/download.md
@@ -0,0 +1,39 @@
1# Download
2
3# Downloading
4
5Latest release: **LuaRocks 3.11.1** - '31/May/2024'
6
7* [Tarball for Unix](https://luarocks.org/releases/luarocks-3.11.1.tar.gz)
8* [Windows all-in-one executable (32-bit)](https://luarocks.org/releases/luarocks-3.11.1-windows-32.zip)
9* [Windows all-in-one executable (64-bit)](https://luarocks.org/releases/luarocks-3.11.1-windows-64.zip)
10* [other files](https://luarocks.github.io/luarocks/releases)
11
12For release notes and older versions, see the [release history](release_history.md).
13
14# Installing
15
16* [Installation instructions for Unix](installation_instructions_for_unix.md) (Linux, BSDs, etc.)
17* [Installation instructions for macOS](installation_instructions_for_macos.md)
18* [Installation instructions for Windows](installation_instructions_for_windows.md)
19
20LuaRocks is a pure Lua application with no library dependencies. Its current
21release depends on some helper tools, but you shouldn't worry about them, as
22they are shipped by default on most Unix systems. For Windows, the all-in-one
23package already includes them and a binary of Lua, as a convenience.
24
25Once LuaRocks is installed, make sure to read the
26[Documentation](index.md) for more information!
27
28# The bleeding edge
29
30Development is done using Git. To get the latest development sources, run:
31
32```
33git clone git://github.com/luarocks/luarocks.git
34```
35
36There is also a web interface available at:
37
38* [http://github.com/luarocks/luarocks](http://github.com/luarocks/luarocks)
39
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).
diff --git a/docs/file_formats.md b/docs/file_formats.md
new file mode 100644
index 00000000..9030cd26
--- /dev/null
+++ b/docs/file_formats.md
@@ -0,0 +1,23 @@
1# File formats
2
3These pages are the reference specification for file formats used by LuaRocks.
4All files are actual Lua files, but they are loaded in a restricted
5environment in which the standard Lua libraries are not available.
6
7* [Rockspec format](rockspec_format.md) - Rockspecs are the files which
8 contain rules explaining how rocks are built and installed as well as their
9 dependencies and other metadata.
10
11* [Config file format](config_file_format.md) - The specification of the
12 LuaRocks configuration file format, as it takes shape.
13
14* [Manifest file format](manifest_file_format.md) - The index file that
15 describes a LuaRocks [repository](rocks_repositories.md), used by both rocks
16 servers and rocks trees.
17
18* [Rock file format](rock_file_format.md) - Reference to the .rock file
19 format: the installable packages produced from
20 [rockspecs](rockspec_format.md).
21
22
23
diff --git a/docs/file_locations.md b/docs/file_locations.md
new file mode 100644
index 00000000..d8e1c684
--- /dev/null
+++ b/docs/file_locations.md
@@ -0,0 +1,110 @@
1# File locations
2
3This is a summary of all file paths related to LuaRocks, including the files
4that compose LuaRocks (its scripts and modules), files installed by LuaRocks
5(Lua modules and scripts), and files required by LuaRocks (programs, libraries
6and headers).
7
8For each path, the default value is also listed.
9
10Whenever "5.x" is used, it refers to the Lua version you configured during
11installation.
12
13# Path to LuaRocks
14
15* LuaRocks command-line scripts. These are the main LuaRocks commands
16 (`luarocks`, `luarocks-admin`); it should be in your system PATH.
17
18 * Unix default: /usr/local/bin
19
20* LuaRocks modules. These are Lua modules (`luarocks.fs`, etc.) used by
21 LuaRocks. The LuaRocks command-line tools are configured during installation
22 to be able to find those files.
23
24 * Unix default: /usr/local/share/lua/5.x/
25
26# Path to Lua binaries and associated data
27
28* Lua interpreter. Where to find the Lua interpreter to execute scripts and
29 LuaRocks itself.
30
31 * Unix default: /usr/local/bin/lua
32
33* Lua libraries. The directory containing the Lua virtual machine as a shared
34 library. On some platforms, Lua modules written in C (also called "C
35 modules") should link against this library
36
37 * Unix default: /usr/local/lib
38
39* Lua header files (lua.h, etc.). They are required when compiling C modules.
40
41 * Unix default: /usr/local/include
42
43On Unix, those locations vary according to your OS variant or distribution. If
44you're using a Linux distribution, for example, you may have installed Lua
45using your package manager and paths use /usr/ rather than /usr/local/, and
46the `lua` binary may be called `lua-5.x`.
47
48For Windows users, having libraries and headers around may be uncommon, as
49Windows tends to have binary distributions. LuaRocks can provide binary rocks,
50but rocks in the standard repository are often available only as source code
51and need to be compiled during the installation process.
52
53# Paths to rocks trees
54
55LuaRocks by default is configured to use two rocks trees:
56
57* System-wide [rock tree](rocks_repositories.md) (used by default)
58 * Unix default: /usr/local/
59* Per-user [rock tree](rocks_repositories.md) (may be selected by the user with the --local flag).
60 * Unix default: $HOME/.luarocks/
61
62In order to use the modules installed in the rock trees, the [deployment
63directories](rocks_repositories.md) should be in the `LUA_PATH` and
64`LUA_CPATH` environment variables.
65
66On Unix, performing a vanilla installation of Lua from lua.org and a vanilla
67installation of LuaRocks will install both under /usr/local, meaning that the
68environment variables for the system-wide rock tree are correct by default.
69
70The command `[luarocks path](luarocks_path.md)` outputs the correct environment
71variables set for a rock tree.
72
73# Path where command-line scripts are installed
74
75Rocks may also deploy command-line scripts. This location is relative to the
76rock tree where they are installed:
77
78* System-wide [rock tree](rocks_repositories.md) (used by default)
79
80 * Unix default: /usr/local/bin/
81
82* Per-user [rock tree](rocks_repositories.md) (may be selected by the user
83 with the --local flag).
84
85 * Unix default: $HOME/.luarocks/bin/
86
87To be able to call those scripts from the shell, the location where they are
88installed need to be in your environment path.
89
90On Unix, /usr/local/bin is usually in the $PATH by default, but
91$HOME/.luarocks/bin is not.
92
93The command `[luarocks path](luarocks_path.md) --bin` outputs the correct PATH
94environment variables set for a rock tree.
95
96# Compiler
97
98For compiling modules written in C, you need a compiler toolchain installed.
99
100For many platforms this is a non-issue: Linux distribution often include
101`gcc` (the default installation of Ubuntu, notably, ships without build
102tools by default: run `sudo apt-get install build-essential`).
103
104On Windows, where binary distribution is the standard, this might be an
105additional requirement. Because more rocks are available as source code than
106as binary rocks, it is probably best to have a C compiler available. LuaRocks
107supports MinGW and the Microsoft Visual Studio toolchains. The compiler should
108be in the system path, or explicitly configured in the LuaRocks config files.
109
110
diff --git a/docs/hosting_binary_rocks.md b/docs/hosting_binary_rocks.md
new file mode 100644
index 00000000..1df055ab
--- /dev/null
+++ b/docs/hosting_binary_rocks.md
@@ -0,0 +1,41 @@
1# Hosting binary rocks
2
3At the moment, LuaRocks.org hosts only rockspecs and src.rock files, and not
4binary rocks. But you can host your own repository of binary rocks at any
5static HTTP server (for example, Github Pages).
6
7Suppose you want to host a binary rock for a rock of yours named `my_rock`:
8
9Step 1: build your rocks with `luarocks build my_rock`. This will compile your
10rocks locally in your system. After a successful build, you should see them
11installed with `luarocks list`.
12
13Step 2: create binary rocks from using `luarocks pack my_rock`. This will
14create a binary rock file, named after your operating system and processor,
15for example, `my_rock-1.0-1-macosx-x86_64.rock`. Note that this binary is
16dependent on library versions of your own machine. This is more of an issue in
17some operating systems than others (Linux binaries are very picky with library
18dependencies, so it's helpful to build binaries on older distros for greater
19compatibility.)
20
21Step 2.5: if your rock has dependencies, repeat step 2 for them as well.
22
23Step 3: create a new directory `my_dir`, copy your rock binary into it (and
24possibly your rockspec and src.rock as well, for a nice one-stop-shop of your
25rock) and run `luarocks-admin make-manifest my_dir`. This will create files
26named `manifest-*` in it, which turn this directory into a working LuaRocks
27server. You can even use it locally: `luarocks install --server=my_dir
28my_rock` should work!
29
30Step 4: upload the contents of `my_dir`, manifest files and rocks, into a HTTP
31server and use its URL as the argument of `--server`. For example, if you
32uploaded it into `http://example.com/binary-rock/manifest-5.3` and
33`http://example.com/binary-rock/my-rock-1.0-1-macosx-x86_64.rock`, then using
34`luarocks install --server=http://example.com/binary-rock my_rock` should
35fetch the manifest, read it, find the rock name, download it and install it.
36
37Note that in a repo that contains both binary and source rocks, running
38`luarocks install http://example.com/binary-rock my_rock` will download and
39install the binary rock, and `luarocks build http://example.com/binary-rock
40my_rock` will download, compile and install the source rock.
41
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..584414ab
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,80 @@
1# Index
2
3* [Welcome](welcome.md)
4
5* Installing LuaRocks
6 * [Download](download.md)
7 * [Installation instructions for Unix](installation_instructions_for_unix.md)
8 * [Installation instructions for macOS](installation_instructions_for_macos.md)
9 * [Installation instructions for Windows](installation_instructions_for_windows.md)
10
11* Using LuaRocks
12 * [Using LuaRocks](using_luarocks.md)
13 * [Types of rocks](types_of_rocks.md)
14 * [Rocks repositories](rocks_repositories.md)
15 * [Browse rocks](browse_rocks.md)
16 * [Dependencies](dependencies.md)
17 * [Paths and external dependencies](paths_and_external_dependencies.md)
18 * [Namespaces](namespaces.md)
19 * [Pinning versions with a lock file](pinning_versions_with_a_lock_file.md)
20 * [Community support and more resources](more_resources.md)
21
22* Creating rocks
23 * [Creating a rock](creating_a_rock.md)
24 * [Platform overrides](platform_overrides.md)
25 * [Platform-agnostic external dependencies](platform_agnostic_external_dependencies.md)
26 * [Recommended practices for Makefiles](recommended_practices_for_makefiles.md)
27 * [Creating a Makefile that plays nice with LuaRocks](creating_a_makefile_that_plays_nice_with_luarocks.md)
28 * [Creating LuaRocks with GNU autotools](creating_luarocks_with_gnu_autotools.md)
29
30* Advanced topics
31 * [LuaRocks through a proxy](luarocks_through_a_proxy.md)
32 * [Embedding LuaRocks in an application](embedding_luarocks_in_an_application.md)
33 * [Integrating distro modules with LuaRocks](integrating_distro_modules_with_luarocks.md)
34 * [Hosting binary rocks](hosting_binary_rocks.md)
35
36* Reference
37 * [File formats](file_formats.md)
38 * [Config file format](config_file_format.md)
39 * [Rock file format](rock_file_format.md)
40 * [Rockspec format](rockspec_format.md)
41 * [Rock manifest file format](rock_manifest_file_format.md)
42 * [Manifest file format](manifest_file_format.md)
43
44 * [File locations](file_locations.md)
45
46 * Command-line interface
47 * [luarocks](luarocks.md)
48 * [luarocks build](luarocks_build.md)
49 * [luarocks config](luarocks_config.md)
50 * [luarocks doc](luarocks_doc.md)
51 * [luarocks download](luarocks_download.md)
52 * [luarocks help](luarocks_help.md)
53 * [luarocks install](luarocks_install.md)
54 * [luarocks lint](luarocks_lint.md)
55 * [luarocks list](luarocks_list.md)
56 * [luarocks make](luarocks_make.md)
57 * [luarocks new_version](luarocks_new_version.md)
58 * [luarocks pack](luarocks_pack.md)
59 * [luarocks path](luarocks_path.md)
60 * [luarocks purge](luarocks_purge.md)
61 * [luarocks remove](luarocks_remove.md)
62 * [luarocks search](luarocks_search.md)
63 * [luarocks show](luarocks_show.md)
64 * [luarocks test](luarocks_test.md)
65 * [luarocks unpack](luarocks_unpack.md)
66 * [luarocks upload](luarocks_upload.md)
67 * [luarocks write_rockspec](luarocks_write_rockspec.md)
68
69 * [luarocks-admin](luarocks_admin.md)
70 * [luarocks-admin add](luarocks_admin_add.md)
71 * [luarocks-admin help](luarocks_admin_help.md)
72 * [luarocks-admin make manifest](luarocks_admin_make_manifest.md)
73 * [luarocks-admin refresh cache](luarocks_admin_refresh_cache.md)
74 * [luarocks-admin remove](luarocks_admin_remove.md)
75
76 * [Release history](release_history.md)
77
78* [Credits](credits.md)
79* [License](license.md)
80* [Index](index.md)
diff --git a/docs/installation_instructions_for_macos.md b/docs/installation_instructions_for_macos.md
new file mode 100644
index 00000000..216e042d
--- /dev/null
+++ b/docs/installation_instructions_for_macos.md
@@ -0,0 +1,39 @@
1# Installation instructions for macOS
2
3LuaRocks is a command-line tool. You can install LuaRocks using one of the
4third-party package managers available for macOS (formerly known as "Mac OS X"
5or "OS X"), or you may install it manually, in the Unix way.
6
7# Option 1: using Homebrew
8
9One option is to use [Homebrew](https://brew.sh). If you don't have it
10installed, follow its installation instructions.
11
12If you already have it installed, make sure it is up to date so you pick the
13most recent version of LuaRocks:
14
15```
16brew update
17```
18
19and then install LuaRocks:
20
21```
22 brew install luarocks
23```
24
25# Option 2: installing it manually
26
27If you do not wish to use a package management tool to install LuaRocks, you
28can install it on macOS as you would do in any other Unix system, assuming you
29have the Mac Developer Tools installed. Download the Unix tarball and then
30follow the [installation instructions for
31Unix](installation_instructions_for_unix.md) to install it to /usr/local.
32
33# Next steps
34
35Once LuaRocks is installed, learn more about [using
36LuaRocks](using_luarocks.md).
37
38
39
diff --git a/docs/installation_instructions_for_unix.md b/docs/installation_instructions_for_unix.md
new file mode 100644
index 00000000..79afc64e
--- /dev/null
+++ b/docs/installation_instructions_for_unix.md
@@ -0,0 +1,140 @@
1# Installation instructions for Unix
2
3First of all, get the [latest ".tar.gz" package
4here](http://luarocks.github.io/luarocks/releases).
5
6The LuaRocks build system for Unix is based on a simple "configure" script and
7a Makefile. The "configure" script offers some flags that are useful for
8different models of use of LuaRocks. Run `./configure --help` for details.
9
10## Quick start
11
12To get a default installation of Lua and LuaRocks under `/usr/local`:
13
14First, ensure that you have development tools installed on your system,
15otherwise run the command below to install them.
16
17For Ubuntu/Debian systems, this should do it:
18
19```
20-$ sudo apt install build-essential libreadline-dev unzip
21```
22
23For Yum-based distributions, try this:
24
25```
26-$ sudo yum install libtermcap-devel ncurses-devel libevent-devel readline-devel
27```
28
29Then, to build and install Lua, either install it using your package
30manager of choice, or run the following commands to download the
31package tarball, extract, build and install it. (Replace 5.3.5 with the
32latest Lua version.)
33
34```
35-$ curl -R -O http://www.lua.org/ftp/lua-5.3.5.tar.gz
36-$ tar -zxf lua-5.3.5.tar.gz
37-$ cd lua-5.3.5
38-$ make linux test
39-$ sudo make install
40```
41
42Once Lua and its dependencies are installed, it is time to install LuaRocks:
43
44* Download and unpack [latest ".tar.gz" file](http://luarocks.github.io/luarocks/releases).
45
46* Run `./configure --with-lua-include=/usr/local/include`. (This will attempt
47 to detect your installation of Lua. If you get any error messages, see the
48 section [Customizing your settings](#customizing-your-settings), below.)
49
50* Run `make`.
51
52* As superuser, run `make install`.
53
54Installation should be done! Run `luarocks` with no arguments to
55see a summary of your settings.
56
57This should be sufficient. For more information and installation options, read on.
58
59## The default settings
60
61The default settings are suitable for installing LuaRocks globally in your
62system while allowing both system-wide and per-user sets of rocks. User
63accounts will be able to install their own rocks in their $HOME directory, and
64the superuser can install rocks that will be available for everyone.
65
66By default LuaRocks will install itself in `/usr/local`, like Lua, and will
67use `/usr/local/etc/luarocks/config.lua` as a default path for the
68configuration file. The default system-wide rocks trees is configured as
69`/usr/local/lib/luarocks`, and per-user rocks install at
70`$HOME/.luarocks/rocks/`. Command-line scripts provided by rocks will be
71installed in `/usr/local/lib/luarocks/bin/` or `$HOME/.luarocks/bin/`,
72respectively. The user may then add these directories to their `$PATH`
73variable.
74
75## Customizing your settings
76
77All paths described above can be overridden with flags in the `configure`
78script, or entries in the configuration file. These are the supported flags,
79as presented by the `--help` option:
80
81```
82Installation directories:
83 --prefix=PREFIX Directory where LuaRocks should be installed,
84 Default is '/usr/local'
85
86By default, `make install' will install all the files in `/usr/local',
87`/usr/local/lib' etc. You can specify an installation prefix other than
88`/usr/local/' using `--prefix', for instance `--prefix=$HOME'.
89
90For better control, use the options below.
91
92Fine tuning of the installation directories:
93 --sysconfdir=SYSCONFDIR Directory for single-machine config.
94 Default is PREFIX/etc
95
96Where to install files provided by rocks:
97 --rocks-tree=DIR Root of the local tree of installed rocks.
98 To make files installed in this location
99 accessible to Lua and your $PATH, see
100 "luarocks path --help" after installation.
101 Avoid using paths controlled by your
102 system's package manager, such as /usr.
103 - Default is PREFIX
104
105Where is your Lua interpreter:
106 --lua-version=VERSION Use specific Lua version: 5.1, 5.2, 5.3, or 5.4
107 - Default is auto-detected.
108 --with-lua-bin=LUA_BINDIR Location of your Lua binar(y/ies).
109 - Default is the directory of the
110 auto-detected Lua interpreter,
111 (or DIR/bin if --with-lua is used)
112 --with-lua=LUA_DIR Use Lua from given directory. Default is LUA_BINDIR/..
113 --with-lua-include=DIR Lua's includes dir. Default is LUA_DIR/include
114 --with-lua-lib=DIR Lua's libraries dir. Default is LUA_DIR/lib
115 --with-lua-interpreter=NAME Lua interpreter name.
116 - Default is to auto-detected
117
118For specialized uses of LuaRocks:
119 --force-config Force using a single config location.
120 Do not honor the $LUAROCKS_CONFIG_5_x
121 or $LUAROCKS_CONFIG environment
122 variable or the user's local config.
123 Useful to avoid conflicts when LuaRocks
124 is embedded within an application.
125 --disable-incdir-check If you do not wish to use "luarocks build",
126 (e.g. when only deploying binary packages)
127 you do not need lua.h installed. This flag
128 skips the check for lua.h in "configure".
129
130```
131
132After installation, a default config file called config.lua will be installed
133at the directory defined by `--sysconfdir`. For further configuration of
134LuaRocks paths, see the [Config file format](config_file_format.md).
135
136## Next steps
137
138Once LuaRocks is installed, learn more about [using LuaRocks](using_luarocks.md).
139
140
diff --git a/docs/installation_instructions_for_windows.md b/docs/installation_instructions_for_windows.md
new file mode 100644
index 00000000..b8c18c9d
--- /dev/null
+++ b/docs/installation_instructions_for_windows.md
@@ -0,0 +1,159 @@
1# Installation instructions for Windows
2
3There are two packages for Windows:
4
5* if you already have a Lua installation, the <b>single binary</b> package
6 which you can use: get the [latest windows-32.zip file
7 here](http://luarocks.github.io/luarocks/releases), unpack it and you'll
8 have a <tt>luarocks.exe</tt> ready to use. Make sure the executable is
9 available from your executable PATH so you can run <tt>luarocks</tt> from
10 the command line the same way you run <tt>lua</tt>.
11
12* we also provide an all-in-one package which includes Lua 5.1 and LuaRocks in
13 source format; get the [latest win32.zip file
14 here](http://luarocks.github.io/luarocks/releases). The instructions below
15 are about this package.
16
17This page refers to the second method. The all-in-one package includes
18everything you need to launch LuaRocks, including helper binaries and a
19Lua interpreter. (You can use your own Lua interpreter if you already have
20one installed, see below.)
21
22<b>Important:</b> To compile many Lua packages, you will also need a C compiler.
23The installer batch file included in the all-in-one package attempts to detect
24if you have Microsoft Visual Studio or [Mingw](https://mingw.org) (Minimalistic GNU for Windows, which includes GCC).
25
26The installer script, <tt>INSTALL.BAT</tt>, provides a number of options for
27customizing your installation. Run <tt>INSTALL /?</tt> for details.
28
29Run `INSTALL.BAT` it from a Command Prompt window. If you will be using it
30with Microsoft Visual Studio, it is recommended to use LuaRocks with the
31Visual Studio Command Prompt, where all environment variables for using the
32MSVC compiler, `cl`, are set.
33
34* If you using <a href="https://www.cygwin.com/">Cygwin</a> then go through [installation instructions for Unix](installation_instructions_for_unix.md).
35
36# The default settings
37
38The default settings are suitable for installing LuaRocks globally
39in your system while allowing both system-wide and per-user sets of rocks.
40Non-priviledged accounts will be able to install their own rocks in their
41%APPDATA% directory, and administrator accounts can install rocks that
42will be available for everyone.
43
44# Making a system-wide repository
45
46All paths described above can be overridden with flags in the INSTALL.BAT script,
47or entries in the configuration file.
48
49{|
50| /P _dir_ || Where to install. Default is %PROGRAMFILES%\LuaRocks\_version_. Because LuaRocks contains 32bit executables, this will be in the c:\program files (x86)\ path on 64bit systems.
51|}
52
53Configuring the destinations:
54
55{| cellpadding=5px
56| /TREE _dir_ || Root of the local tree of installed rocks. Default is %PROGRAMFILES%\LuaRocks\systree. On 64bit systems this default depends on the Lua interpreter used. A 64bit interpreter will have the c:\program files\ path, where a 32bit interpreter on a 64bit system will follow the c:\program files (x86)\ path.
57|-------------------------------------------------------------------------
58| /SCRIPTS _dir_ || Where to install commandline scripts installed by rocks. Default is {TREE}/bin.
59|-------------------------------------------------------------------------
60| /CONFIG _dir_ || Location where the config file should be installed. Default is to follow /P option
61|-------------------------------------------------------------------------
62| /SELFCONTAINED || Creates a self contained installation in a single directory given by /P. Sets the /TREE and /CONFIG options to the same location as /P. And does not load registry info with option /NOREG. The only option NOT self contained is the user rock tree, so don't use that if you create a self contained installation.
63|}
64
65Configuring the Lua interpreter:
66
67{| cellpadding=5px
68| /LV _version_ || Lua version to use; either 5.1, 5.2 or 5.3. Default is auto-detected.
69|-------------------------------------------------------------------------
70| /LUA _dir_ || Location where Lua is installed - e.g. c:\lua\5.1\. If not provided, the installer will search the system path and some default locations for a valid Lua installation. This is the base directory, the installer will look for subdirectories bin, lib, include. Alternatively these can be specified explicitly using the /INC, /LIB, and /BIN options.
71|-------------------------------------------------------------------------
72| /INC _dir_ || Location of Lua includes - e.g. c:\lua\5.1\include. If provided overrides sub directory found using /LUA.
73|-------------------------------------------------------------------------
74| /LIB _dir_ || Location of Lua libraries (.dll/.lib) - e.g. c:\lua\5.1\lib. If provided overrides sub directory found using /LUA.
75|-------------------------------------------------------------------------
76| /BIN _dir_ || Location of Lua executables - e.g. c:\lua\5.1\bin. If provided overrides sub directory found using /LUA.
77|-------------------------------------------------------------------------
78| /L || Install LuaRocks' own copy of Lua even if detected, this will always be a 5.1 installation. (/LUA, /INC, /LIB, /BIN cannot be used with /L)
79within an application.
80|}
81
82Compiler configuration:
83
84{| cellpadding=5px
85| /MW || Use mingw as build system instead of MSVC.
86|}
87
88Other options:
89
90{| cellpadding=5px
91| /FORCECONFIG || Use a single config location. Do not use the LUAROCKS_CONFIG variable or the user's home directory. Useful to avoid conflicts when LuaRocks is embedded
92|-------------------------------------------------------------------------
93| /F || Force. Remove installation directory if it already exists.
94|-------------------------------------------------------------------------
95| /NOREG || Do not load registry info to register '.rockspec' extension with LuaRocks commands (right-click).
96|-------------------------------------------------------------------------
97| /NOADMIN || The installer requires admin priviledges. If not available it will elevate a new process. Use this switch to prevent elevation, but make sure the destination paths are all accessible for the current user.
98|-------------------------------------------------------------------------
99| /Q || Do not prompt for confirmation of settings
100|}
101
102After installation, a default config file called config.lua will be installed at the directory defined by /CONFIG. For further configuration of LuaRocks paths, see the [Config file format](config_file_format.md). For more information on the structure of rocks trees see [rocks repositories](rocks_repositories.md).
103
104# Making a self-contained installation
105
106Another option is to install LuaRocks in a self-contained manner. This
107is an interesting alternative when shipping an application which uses
108third-party modules. Bundling them as rocks reduces maintenance overhead
109and allows the user to perform updates.
110
111In this scenario, it is not desired to have the user's (or the system's)
112configuration affect the self-contained LuaRocks install, in case the
113user or the system also have different LuaRocks installations. For this
114reason, the INSTALL.BAT script allows to hardcode the location of a
115configuration file. For example, the compilation process of a package
116bundling LuaRocks could do something like this:
117
118```
119SET PREFIX=C:\mypackage
120 INSTALL /P %PREFIX% /CONFIG %PREFIX%\luarocks
121```
122
123The copy of LuaRocks installed in C:\mypackage will ignore
124customization schemes such as the %LUAROCKS_CONFIG% environment variable
125and will only use C:\mypackage\luarocks\config.lua.
126
127An interesting option in those cases is for the application to provide
128in its configuration file an URL for their own rocks repository, so they
129can have control over updates to be performed. Continuing the previous
130example, luarocks\config.lua could contain something like this:
131
132```
133repositories = {
134 "http://www.example.com/rocks/"
135 }
136```
137
138# Picking the Lua interpreter
139
140LuaRocks can use its own Lua interpreter provided by the Lua for WIndows project,
141and will do so by default if it fails to find your Lua installation
142automatically. If you want to use your own interpreter, which is not on the system path,
143you can pass its path using the /LUA variable (or /BIN, /LIB and /INC explicitly, if
144you have a custom directory structure).
145
146When looking for an interpreter, it will also try to figure out the name of
147the Lua binary (lua.exe, lua5.1.exe). This is set in the `lua_interpreter`
148variable in the configuration file. If you want to use an alternative name to the
149interpreter, you can set that variable in your configuration file directly.
150
151An important element is the runtime libraries used by the interpreter, as LuaRocks must
152compile additional rocks installed with the same runtime as the interpreter. To do this
153LuaRocks will analyse the executable found.
154
155# Next steps
156
157Once LuaRocks is installed, learn more about [using LuaRocks](using_luarocks.md).
158
159
diff --git a/docs/integrating_distro_modules_with_luarocks.md b/docs/integrating_distro_modules_with_luarocks.md
new file mode 100644
index 00000000..fb073500
--- /dev/null
+++ b/docs/integrating_distro_modules_with_luarocks.md
@@ -0,0 +1,190 @@
1# Integrating distro modules with LuaRocks
2
3This is documentation on strategies to integrate OS-installed modules (e.g.
4packages such as `luafilesystem` and `lpeg` provided by Linux distros) with
5existing versions of LuaRocks.
6
7This page will list two approaches: the minimal one, and a more complete one
8that extends the first one.
9
10## Assumptions
11
12* The examples below use Lua 5.3 — just change "5.3" to "5.1" or "5.2" and the
13 same applies.
14* Distro-installed modules live at standard Lua locations under `/usr`, such
15 as `/usr/lib/lua/5.3/lfs.so`
16
17## The bare minimum approach
18
19This is the _minimum_ that should be added to distro module packages so that
20they visible as dependencies by LuaRocks:
21
22### The main manifest file
23
24For LuaRocks to be able to find any OS-installed modules, there needs to be an
25index file called `manifest` at `/usr/lib/luarocks/rocks-5.3/`.
26
27This file should be generated running:
28
29```
30luarocks-admin make-manifest --local-tree --tree=/usr
31```
32
33This should be run as a post-install action after installing any module via
34the distro. This file is the LuaRocks "index" and should be kept up-to-date or
35else LuaRocks doesn't know about the installed modules.
36
37### Rock metadata necessary to build the main manifest
38
39For the above command to work, there has to be a directory tree for each rock
40and version, containing, at the bare minimum, a `rock_manifest` file. The
41structure looks like this:
42
43`/usr/lib/luarocks/rocks-$LUA_VERSION/$ROCK_NAME/$ROCK_VERSION-$ROCK_REVISION/`
44
45* $LUA_VERSION with with a dot: "5.3"
46
47* $ROCK_NAME should match the name used in the luarocks.org repository — in other words, `luafilesystem` has to be called `luafilesystem`, not `lfs`. LuaRocks checks dependencies by rock name, not by individual module name.
48
49* $ROCK_VERSION usually matches upstream, so that's not an issue.
50
51* $ROCK_REVISION can always be 0 for our purposes here.
52
53Examples:
54
55* /usr/lib/luarocks/rocks-5.3/lpeg/1.0.0-0/
56* /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/
57* /usr/lib/luarocks/rocks-5.3/lua-cjson/2.1.0-0/
58
59### The rock_manifest file
60
61Inside the version directory for a rock there must be a `rock_manifest` file.
62The minimal contents of `rock_manifest` to make `luarocks-admin` not fail is
63simply:
64
65```lua
66rock_manifest = {}
67```
68
69This means that in the above examples, we'd have several identical one-liner files:
70
71* /usr/lib/luarocks/rocks-5.3/lpeg/1.0.0-0/rock_manifest
72* /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/rock_manifest
73* /usr/lib/luarocks/rocks-5.3/lua-cjson/2.1.0-0/rock_manifest
74
75### Necessary LuaRocks configuration
76
77With those empty manifests, the post-install operation mentioned above works
78and a later `luarocks install` will the existence of the "rocks" in /usr,
79given the following configuration in `/etc/luarocks/config-5.3.lua`:
80
81```
82rocks_trees = {
83 { name = "user", root = home.."/.luarocks" },
84 { name = "distro-modules", root = "/usr" },
85 { name = "system", root = "/usr/local" },
86}
87deps_mode = "all"
88```
89
90It's important that the "system" tree is the last entry: it is the one used
91for system-wide installation of rocks using LuaRocks (when `sudo luarocks` is
92used). The "distro-modules" tree should never be used directly by the user.
93
94For more info on the deps_mode flag, see the [Dependency
95modes](dependencies.md#dependency-modes) documentation.
96
97### Caveats
98
99*Error messages*: Running with such bare minimum setup will resolve
100dependencies, but running the post-install operation above will output error
101messages when running, such as...
102
103```
104Tree inconsistency detected: luafilesystem 1.6.0-0 has no rockspec. Could not load rockspec file /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/luafilesystem-1.6.0-0.rockspec (/usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/luafilesystem-1.6.0-0.rockspec: No such file or directory)"
105```
106
107...for each entry under `/usr/lib/luarocks/rocks-5.3` (for our purposes, these
108can be simply ignored and silenced away with `&> /dev/null`).
109
110*Failed commands*: this minimal tree will work for solving dependencies, but
111not for much else. In particular, `luarocks list --tree=/usr` will work, but
112`luarocks show lpeg --tree=/user` will not, complaining that it can't find a
113rockspec.
114
115## A more complete approach
116
117A more complete approach to make commands such as `luarocks show` to work
118would entail two steps: adding proper contents to `rock_manifest` and
119including a rockspec file for each module.
120
121### A complete rock_manifest
122
123A workable version of `rock_manifest` with contents would look like this:
124
125```
126rock_manifest = {
127 lib = {
128 ["lpeg.so"] = "136a74c6e472c36a65449184e1820a31"
129 },
130 ["lpeg-1.0.0-0.rockspec"] = "4933a611af43404761002ee139c393e8",
131 lua = {
132 ["re.lua"] = "5f09bb0129b09b6a8e8c1db1b206b1ca"
133 }
134}
135```
136
137The entries under `lib` are the files installed by the package at `/usr/lib/5.3`.
138The entries under `lua` are the files installed by the package at `/usr/share/5.3`.
139The rockspec key is the rockspec file to be stored alongside the `rock_manifest` file.
140The values to these entries are MD5 sums to the files in question.
141
142### Including a rockspec file
143
144For `luarocks show` to display metadata properly, a rockspec file must exist.
145It should be named according to the pattern
146`$ROCK_NAME-$ROCK_VERSION-$ROCK_REVISION.rockspec` (in all lowercase).
147Continuing the examples above:
148
149* /usr/lib/luarocks/rocks-5.3/lpeg/1.0.0-0/lpeg-1.0.0-0.rockspec
150* /usr/lib/luarocks/rocks-5.3/luafilesystem/1.6.0-0/luafilesystem-1.6.0-0.rockspec
151* /usr/lib/luarocks/rocks-5.3/lua-cjson/2.1.0-0/lua-cjson-2.1.0-0.rockspec
152
153For simplicity, I would recommend just copying over the appropriate rockspec
154file from [luarocks.org](http://luarocks.org) and bundling them in the package
155metadata. For completeness, this is how the one for LPeg 1.0 looks like:
156
157```
158package = "LPeg"
159version = "1.0.0-1"
160source = {
161 url = "http://www.inf.puc-rio.br/~roberto/lpeg/lpeg-1.0.0.tar.gz",
162 md5 = "0aec64ccd13996202ad0c099e2877ece",
163}
164description = {
165 summary = "Parsing Expression Grammars For Lua",
166 detailed = [[
167 LPeg is a new pattern-matching library for Lua, based on Parsing
168 Expression Grammars (PEGs). The nice thing about PEGs is that it
169 has a formal basis (instead of being an ad-hoc set of features),
170 allows an efficient and simple implementation, and does most things
171 we expect from a pattern-matching library (and more, as we can
172 define entire grammars).
173 ]],
174 homepage = "http://www.inf.puc-rio.br/~roberto/lpeg.html",
175 maintainer = "Gary V. Vaughan <gary@vaughan.pe>",
176 license = "MIT/X11"
177}
178dependencies = {
179 "lua >= 5.1"
180}
181build = {
182 type = "builtin",
183 modules = {
184 lpeg = {
185 "lpcap.c", "lpcode.c", "lpprint.c", "lptree.c", "lpvm.c"
186 },
187 re = "re.lua"
188 }
189}
190```
diff --git a/docs/license.md b/docs/license.md
new file mode 100644
index 00000000..7ff07be0
--- /dev/null
+++ b/docs/license.md
@@ -0,0 +1,5 @@
1# License
2
3LuaRocks uses the MIT license. See the file
4[COPYING](https://github.com/luarocks/luarocks/blob/master/COPYING) at the
5root of the repository for the license text.
diff --git a/docs/luarocks.md b/docs/luarocks.md
new file mode 100644
index 00000000..91bb6731
--- /dev/null
+++ b/docs/luarocks.md
@@ -0,0 +1,102 @@
1# luarocks
2
3**luarocks** is the command-line interface for LuaRocks, the Lua package manager.
4
5# Usage
6
7```
8luarocks [--server=<server> | --only-server=<server>] [--tree=<tree>] [--only-sources=<url>] [--deps-mode=<mode>] [<VAR>=<VALUE>]... <command> [<argument>]
9```
10
11Variables from the "variables" table of the [configuration file](config_file_format.md) can be overriden with VAR=VALUE assignments.
12
13{|
14| --server=_server_ || Fetch rocks/rockspecs from this server (takes priority over config file)
15|-
16| --only-server=_server_ || Fetch rocks/rockspecs from this server only (overrides any entries in the config file)
17|-
18| --only-sources=_url_ || Restrict downloads of sources to URLs starting with the given URL. For example, --only-sources=http://luarocks.org will allow LuaRocks to download sources only if the URL given in the rockspec starts with http://luarocks.org .
19|-
20| --tree=_tree_ || Which tree to operate on.
21|-
22| --local || Use the tree in the user's home directory. To enable it, see `[luarocks path](luarocks_path.md)`
23|-
24| --deps-mode=_mode_ || Select dependencies mode:
25
26How to handle the list of rocks servers given in the rocks_servers array in the [config file](config_file_format.md).
27
28* **one** - Consider only the tree at the top of the list (possibly, the one given by the --tree flag, overriding all entries from rocks_trees), ignore all others
29* **all** - Consider all trees: if a dependency is installed in any tree of the rocks_trees list, we have a positive match.
30* **order** - Consider only trees starting from the "current" one in the order, where the "current" is either:
31 * the one at the bottom of the rocks_trees list,
32 * or one explicitly given with --tree
33 * or the "home" tree if --local was given or local_by_default=true is configured (usually at the top of the list)
34|-
35| --verbose || Display verbose output of commands executed.
36|-
37| --timeout || Timeout on network operations, in seconds. 0 means no timeout (wait forever). Default is 30.
38|}
39
40# Supported commands
41
42{|
43| [build](luarocks_build.md) || Build/compile and install a rock.
44|-
45| [doc](luarocks_doc.md) || Shows documentation for an installed rock.
46|-
47| [download](luarocks_download.md)|| Download a specific rock or rockspec file from a rocks server.
48|-
49| [help](luarocks_help.md) || Help on commands.
50|-
51| [install](luarocks_install.md) || Install a rock.
52|-
53| [lint](luarocks_lint.md) || Check syntax of a rockspec.
54|-
55| [list](luarocks_list.md) || Lists currently installed rocks.
56|-
57| [config](luarocks_config.md) || Query and set the LuaRocks configuration.
58|-
59| [make](luarocks_make.md) || Compile package in current directory using a rockspec and install it.
60|-
61| [new_version](luarocks_new_version.md) || Auto-write a rockspec for a new version of a rock.
62|-
63| [pack](luarocks_pack.md) || Create a rock, packing sources or binaries.
64|-
65| [path](luarocks_path.md) || Return the currently configured package path.
66|-
67| [purge](luarocks_purge.md) || Remove all installed rocks from a tree.
68|-
69| [remove](luarocks_remove.md) || Uninstall a rock.
70|-
71| [search](luarocks_search.md) || Query the LuaRocks repositories.
72|-
73| [test](luarocks_test.md) || Run the test suite in the current directory.
74|-
75| [show](luarocks_show.md) || Shows information about an installed rock.
76|-
77| [unpack](luarocks_unpack.md) || Unpack the contents of a rock.
78|-
79| [upload](luarocks_upload.md) || Upload a rockspec to the public rocks repository.
80|-
81| [write_rockspec](luarocks_write_rockspec.md) || Write a template for a rockspec file.
82|}
83
84# Overview of the difference between "make", "build", "install" and "pack"
85
86{|
87| luarocks install modulename || downloads a binary .rock file and installs it to the local tree (falls back to "luarocks build modulename" behavior if a binary rock is not found)
88|-
89| luarocks build modulename || downloads a .src.rock or a rockspec and builds+installs it to the local tree.
90|-
91| luarocks build modulename-1.0-1.linux-x86.rock || extracts the rockspec from the rock and builds it as if the rockspec was passed in the command-line (i.e., redownloading sources and recompiling C modules if any).
92|-
93| luarocks build modulename-1.0-1.rockspec || builds+installs the rock using the given rockspec downloading the sources
94|-
95| luarocks make modulename-1.0-1.rockspec || builds+installs the rock using the rockspec using the contents of your current directory (kind of like the way make uses a Makefile) instead of downloading sources
96|-
97| luarocks pack modulename || grabs the rock from your local tree and packs it into a binary .rock file
98|-
99| luarocks pack modulename-1.0-1.rockspec || downloads the sources from the url and packs it into a .src.rock file
100|}
101
102
diff --git a/docs/luarocks_admin.md b/docs/luarocks_admin.md
new file mode 100644
index 00000000..ca673e76
--- /dev/null
+++ b/docs/luarocks_admin.md
@@ -0,0 +1,19 @@
1# luarocks-admin
2
3**luarocks-admin** is the repository management tool for LuaRocks, the Lua package manager.
4
5# Usage
6
7```
8luarocks-admin <command> [<arguments>]...
9```
10
11# Supported commands
12
13* [help](luarocks_admin_help.md) - Help on commands.
14* [make-manifest](luarocks_admin_make_manifest.md) - Compile a manifest file for a repository.
15* [add](luarocks_admin_add.md) - Add a rock or rockspec to a rocks server.
16* [remove](luarocks_admin_remove.md) - Remove a rock or rockspec from a rocks server.
17* [refresh-cache](luarocks_admin_refresh_cache.md) - Refresh local cache of a remote rocks server.
18
19
diff --git a/docs/luarocks_admin_add.md b/docs/luarocks_admin_add.md
new file mode 100644
index 00000000..6e15b429
--- /dev/null
+++ b/docs/luarocks_admin_add.md
@@ -0,0 +1,53 @@
1# luarocks-admin add
2
3Add a rock or rockspec to a rocks server.
4
5## Usage
6
7`luarocks-admin add [--server=<server>] [--no-refresh] [--index] {<rockspec>|<rock>}...`
8
9Arguments may be local rockspecs or rock files. The flag `--server` indicates
10which server to use. If not given, the default server set in the
11`upload_server` variable from the [configuration file](config_file_format.md)
12is used instead. You need to either explicitly pass a full URL to `--server`
13or configure an upload server in your configuration file prior to using the
14`add` command.
15
16Flags:
17
18* `--no-refresh` - The local cache should not be refreshed prior to generation of the updated manifest.
19* `--index` - Produce an `index.html` file for the manifest. This flag is automatically set if an `index.html` file already exists.
20
21## Examples
22
23### Basic example
24
25Add a rockspec to your default configured upload server:
26
27```
28luarocks-admin add lpeg-0.9-1.rockspec
29```
30
31### Handling multiple repositories
32
33Assuming your `~/.luarocks/config.lua` file looks like this:
34
35```lua
36upload_server = "main"
37upload_servers = {
38 main = {
39 http = "www.example.com/repos/main",
40 sftp = "myuser@example.com/var/www/repos/main"
41 },
42 dev = {
43 http = "www.example.com/repos/devel-rocks",
44 sftp = "myuser@example.com/var/www/repos/devel-rocks"
45 },
46}
47```
48
49you can specify which repository to use with the `--server` flag:
50
51```
52luarocks-admin add --server=dev my_rock-scm-1.rockspec
53```
diff --git a/docs/luarocks_admin_help.md b/docs/luarocks_admin_help.md
new file mode 100644
index 00000000..92232b87
--- /dev/null
+++ b/docs/luarocks_admin_help.md
@@ -0,0 +1,17 @@
1# luarocks-admin help
2
3Help on commands.
4
5## Usage
6
7`luarocks-admin help [<command>]`
8
9`<command>` is the command to show help for. If no argument is given, a list
10of supported commands, with summaries, is shown.
11
12## Example
13
14```
15luarocks-admin help make-manifest
16```
17
diff --git a/docs/luarocks_admin_make_manifest.md b/docs/luarocks_admin_make_manifest.md
new file mode 100644
index 00000000..03f7785c
--- /dev/null
+++ b/docs/luarocks_admin_make_manifest.md
@@ -0,0 +1,72 @@
1# luarocks-admin make manifest
2
3Compile a manifest file for a repository.
4
5## Usage
6
7`luarocks-admin make-manifest [--local-tree] [<repository>]`
8
9`<repository>`, if given, is a local repository pathname. If no argument is
10given, rebuilds the manifest for the local repository of installed packages.
11
12This command is used to update the [manifest file](manifest_file_format.md) in
13a directory containing rocks. By publishing a directory in a web server
14containing rocks and a manifest file, one creates a remote repository -
15LuaRocks clients can then configure their [configuration files](config_file_format.md) to search this repository.
16
17If `--local-tree` is passed, versioned versions of the manifest file are not
18created. Use this when rebuilding the manifest of a local rocks tree.
19
20## Example
21
22Suppose you wrote a rockspec for your module called "LuaSomething" and you
23want to publish a LuaRocks repository in your site. (Normally, you don't need
24to do this, just upload your rockspec to the public rocks repository, so that
25LuaRocks users can access your module without further configuration. But let's
26proceed with the example.) Your module, LuaSomething, is now installed in your
27local repository: you can find it at `~/.luarocks/rocks/luasomething/1.0-1/`.
28To prepare a public repository, let's first pack your new rock:
29
30```
31luarocks pack luasomething
32```
33
34If LuaSomething is a pure-Lua module, this will generate
35`luasomething-1.0-1.all.rock` - this is a portable rock. If it contains C
36code, it generated a non-portable rock, such as
37`luasomething-1.0-1.linux-x86.rock` (in the Linux case specifically, it's
38probably not a good idea to publish binary rocks as they most likely won't be
39portable across Linux distributions). As an alternative, run [luarocks
40pack](luarocks_pack.md) on the rockspec, to create a source rock:
41
42```
43luarocks pack ~/.luarocks/rocks/luasomething/1.0-1/luasomething-1.0-1.rockspec
44```
45
46This will create `luasomething-1.0-1.src.rock`.
47
48Now, create a directory that we'll use to create your public repository, and copy the files you want to publish.
49
50```
51mkdir ~/myrocksrepo
52cp luasomething-1.0-1.src.rock ~/myrocksrepo
53cp ~/.luarocks/rocks/luasomething/1.0-1/luasomething-1.0-1.rockspec ~/myrocksrepo
54```
55
56Perhaps you may have also a Windows build of your rock, packed with [luarocks
57pack](luarocks_pack.md) on a Windows machine:
58
59```
60cp luasomething-1.0-1.win32-x86.rock ~/myrocksrepo
61```
62
63Now create a manifest file for this directory:
64
65```
66luarocks-admin make-manifest ~/myrocksrepo
67```
68
69And we're done: you can now just copy these files and the generated manifest
70to a public directory in a web server and your users will be able to use your
71rock by adding the URL you published the files at to their "repositories"
72array in their LuaRocks configuration file.
diff --git a/docs/luarocks_admin_refresh_cache.md b/docs/luarocks_admin_refresh_cache.md
new file mode 100644
index 00000000..e41293c0
--- /dev/null
+++ b/docs/luarocks_admin_refresh_cache.md
@@ -0,0 +1,47 @@
1# luarocks-admin refresh cache
2
3Refresh local cache of a remote rocks server.
4
5## Usage
6
7`luarocks-admin refresh-cache [--from=<server>]`
8
9The flag `--from` indicates which server to use. If not given, the default
10server set in the `upload_server` variable from the [configuration
11files](config_file_format.md) is used instead. You need to either explicitly
12pass a full URL to `--from` or configure an upload server in your
13configuration file prior to using the `refresh-cache` command.
14
15## Examples
16
17### Basic example
18
19Refresh the cache of your main upload server:
20
21```
22luarocks-admin refresh-cache
23```
24
25### Handling multiple repositories
26
27Assuming your `~/.luarocks/config.lua` file looks like this:
28
29```lua
30upload_server = "main"
31upload_servers = {
32 main = {
33 http = "www.example.com/repos/main",
34 sftp = "myuser@example.com/var/www/repos/main"
35 },
36 dev = {
37 http = "www.example.com/repos/devel-rocks",
38 sftp = "myuser@example.com/var/www/repos/devel-rocks"
39 },
40}
41```
42
43you can specify which cache to refresh with the `--from` flag:
44
45```
46luarocks-admin refresh-cache --from=dev
47```
diff --git a/docs/luarocks_admin_remove.md b/docs/luarocks_admin_remove.md
new file mode 100644
index 00000000..7a861a23
--- /dev/null
+++ b/docs/luarocks_admin_remove.md
@@ -0,0 +1,47 @@
1# luarocks-admin remove
2
3Remove a rock or rockspec from a rocks server.
4
5## Usage
6
7`luarocks-admin remove [--server=<server>] [--no-refresh] {<rockspec>|<rock>}...`
8
9Arguments are local files, which may be rockspecs or rocks.
10
11The flag `--server` indicates which server to use. If not given, the default server set in the `upload_server` variable from the [configuration files](config_file_format.md) is used instead.
12
13The flag `--no-refresh` indicates the local cache should not be refreshed prior to generation of the updated manifest.
14
15You need to have [rsync](https://rsync.samba.org/) installed in order to use this command.
16
17## Examples
18
19### Basic example
20
21Remove a rockspec from your default configured upload server:
22
23```
24luarocks-admin remove lpeg-0.9-1.rockspec
25```
26
27### Handling multiple repositories
28
29Assuming your `~/.luarocks/config.lua` file looks like this:
30
31```lua
32upload_server = "main"
33upload_servers = {
34 main = {
35 rsync = "www.example.com/repos/main",
36 },
37 dev = {
38 rsync = "www.example.com/repos/devel-rocks",
39 },
40}
41```
42
43you can specify which repository to use with the `--server` flag:
44
45```
46luarocks-admin remove --server=dev my_rock-scm-1.rockspec
47```
diff --git a/docs/luarocks_build.md b/docs/luarocks_build.md
new file mode 100644
index 00000000..75b7898d
--- /dev/null
+++ b/docs/luarocks_build.md
@@ -0,0 +1,22 @@
1# luarocks build
2
3Build/compile and install a rock.
4
5## Usage
6
7`luarocks build [--pack-binary-rock] {<rockspec> | <rock> | <name> [<version>]}`
8
9Builds and installs a rock, compiling its C parts if any. Argument may be a
10rockspec file, a source rock file or the name of a rock to be fetched from a
11repository, in which case a version may be passed as well. In case of more
12than one rock matching the request, the `build` command favors source rocks.
13
14If `--pack-binary-rock` is passed, the rock is not installed; instead, a
15`.rock` file with the contents of compilation is produced in the current
16directory.
17
18## Example
19
20```
21luarocks build luasocket
22```
diff --git a/docs/luarocks_config.md b/docs/luarocks_config.md
new file mode 100644
index 00000000..54553399
--- /dev/null
+++ b/docs/luarocks_config.md
@@ -0,0 +1,60 @@
1# luarocks config
2
3Query information about the LuaRocks configuration.
4
5# Usage
6
7```
8luarocks config (<key> | <key> <value> --scope=<scope> | <key> --unset --scope=<scope> | )
9```
10
11When given a configuration key, it prints the value of that key
12according to the currently active configuration (taking into account
13all config files and any command-line flags passed)
14
15Examples:
16
17* `luarocks config lua_interpreter`
18* `luarocks config variables.LUA_INCDIR`
19* `luarocks config lua_version`
20
21When given a configuration key and a value,
22it overwrites the config file (see the --scope option below to determine which)
23and replaces the value of the given key with the given value.
24
25* `lua_dir` is a special key as it checks for a valid Lua installation
26 (equivalent to --lua-dir) and sets several keys at once.
27* `lua_version` is a special key as it changes the default Lua version
28 used by LuaRocks commands (equivalent to passing --lua-version).
29
30Examples:
31
32* `luarocks config variables.OPENSSL_DIR /usr/local/openssl`
33* `luarocks config lua_dir /usr/local`
34* `luarocks config lua_version 5.3`
35
36When given a configuration key and --unset,
37it overwrites the config file (see the --scope option below to determine which)
38and deletes that key from the file.
39
40Example: `luarocks config variables.OPENSSL_DIR --unset`
41
42When given no arguments, it prints the entire currently active
43configuration, resulting from reading the config files from
44all scopes.
45
46Example: `luarocks config`
47
48## Options
49
50```
51--scope=<scope> The scope indicates which config file should be rewritten.
52 Accepted values are "system", "user" or "project".
53 * Using a wrapper created with `luarocks init`,
54 the default is "project".
55 * Using --local (or when `local_by_default` is `true`),
56 the default is "user".
57 * Otherwise, the default is "system".
58
59--json Output as JSON
60```
diff --git a/docs/luarocks_doc.md b/docs/luarocks_doc.md
new file mode 100644
index 00000000..d39e708b
--- /dev/null
+++ b/docs/luarocks_doc.md
@@ -0,0 +1,21 @@
1# luarocks doc
2
3Show documentation for an installed rock.
4
5## Usage
6
7`luarocks doc [--home] [--list] <name> [<version>]`
8
9Attempts to open documentation for an installed rock using a number
10of heuristics.
11
12If `--home` is passed, opens the home page of the project.
13
14If `--list` is passed, documentation files bundled with the rock
15are listed but not opened.
16
17## Example
18
19```
20luarocks doc luasocket
21```
diff --git a/docs/luarocks_download.md b/docs/luarocks_download.md
new file mode 100644
index 00000000..1a3597ab
--- /dev/null
+++ b/docs/luarocks_download.md
@@ -0,0 +1,19 @@
1# luarocks download
2
3Download a specific rock or rockspec file from a rocks server.
4
5## Usage
6
7`luarocks download [--all] [--arch=<arch> | --source | --rockspec] [<name> [<version>]]`
8
9If `--all` is passed, all matching files are downloaded, and `<name>` argument
10becomes optional. `--arch`, `--source` and `--rockspec` options select file
11type.
12
13## Example
14
15Download rockspec for the latest version of a rock:
16
17```
18luarocks download --rockspec lpeg
19```
diff --git a/docs/luarocks_help.md b/docs/luarocks_help.md
new file mode 100644
index 00000000..3a39f7fe
--- /dev/null
+++ b/docs/luarocks_help.md
@@ -0,0 +1,17 @@
1# luarocks help
2
3Help on commands.
4
5## Usage
6
7`luarocks help [<command>]`
8
9`<command>` is the command to show help for. If no argument is given, a list
10of supported commands, with summaries, is shown.
11
12## Example
13
14```
15luarocks help remove
16```
17
diff --git a/docs/luarocks_install.md b/docs/luarocks_install.md
new file mode 100644
index 00000000..f3eddbd6
--- /dev/null
+++ b/docs/luarocks_install.md
@@ -0,0 +1,37 @@
1# luarocks install
2
3Install a rock.
4
5## Usage
6
7`luarocks install [--keep] [--only-deps] {<rock> | <name> [<version>]}`
8
9Argument may be the name of a rock to be fetched from a server, with optional
10version, or the direct URL or filename of a rockspec. In case of more than one
11rock matching the request, the `install` command favors binary rocks.
12
13Unless `--keep` is passed, other versions of the rock are removed after
14installing the new one.
15
16If `--only-deps` is passed, the rock itself is not installed, but its
17dependencies are.
18
19## Examples
20
21Installing a rock:
22
23```
24luarocks install luasocket
25```
26
27Installing a specific version of a rock:
28
29```
30luarocks install luasocket 3.0rc1
31```
32
33Installing a rock ignoring its dependencies:
34
35```
36luarocks install busted --deps-mode=none
37```
diff --git a/docs/luarocks_lint.md b/docs/luarocks_lint.md
new file mode 100644
index 00000000..f2d0f411
--- /dev/null
+++ b/docs/luarocks_lint.md
@@ -0,0 +1,15 @@
1# luarocks lint
2
3Check syntax of a rockspec.
4
5## Usage
6
7`luarocks lint <rockspec>`
8
9Checks syntax and format of a local rockspec.
10
11## Example
12
13```
14luarocks lint my-rock-0.1.0-1.rockspec
15```
diff --git a/docs/luarocks_list.md b/docs/luarocks_list.md
new file mode 100644
index 00000000..b9627d5f
--- /dev/null
+++ b/docs/luarocks_list.md
@@ -0,0 +1,27 @@
1# luarocks list
2
3Lists currently installed rocks.
4
5## Usage
6
7`luarocks list [--outdated] [--porcelain] [<query>] [<version>]`
8
9`<query>` is a substring of a rock name to filter by. When no arguments are
10supplied, a list of all rocks you have installed is returned.
11
12If `--outdated` is passed, only rocks for which there is a higher version
13available in the rocks server are listed.
14
15If `--porcelain` is passed, machine-friendly output is produced.
16
17The `list` command queries the local repository (the rocks you have
18installed). To query remote repositories (the rocks available for download at
19the LuaRocks server), use [luarocks search](luarocks_search.md).
20
21## Example
22
23List all installed rocks:
24
25```
26luarocks list
27```
diff --git a/docs/luarocks_make.md b/docs/luarocks_make.md
new file mode 100644
index 00000000..88629334
--- /dev/null
+++ b/docs/luarocks_make.md
@@ -0,0 +1,27 @@
1# luarocks make
2
3Compile package in current directory using a rockspec.
4
5## Usage
6
7`luarocks make [--pack-binary-rock] [<rockspec>]`
8
9Builds sources in the current directory, but unlike [luarocks
10build](luarocks_build.md), it does not fetch sources, etc., assuming
11everything is available in the current directory. After the build is complete,
12it also installs the rock.
13
14If no argument is given, it looks for a rockspec in the current directory and
15in `./rockspec` and `./rockspecs` subdirectories. Of all the rockspecs the one
16with the highest version is used. If rockspecs for more than one rock are
17found, you must specify which one to use through the command-line.
18
19If `--pack-binary-rock` is passed, the rock is not installed; instead, a
20`.rock` file with the contents of compilation is produced in the current
21directory.
22
23## Example
24
25```
26luarocks make
27```
diff --git a/docs/luarocks_new_version.md b/docs/luarocks_new_version.md
new file mode 100644
index 00000000..087a9235
--- /dev/null
+++ b/docs/luarocks_new_version.md
@@ -0,0 +1,37 @@
1# luarocks new_version
2
3Auto-write a rockspec for a new version of a rock.
4
5## Usage
6
7`luarocks new_version [--tag=<tag>] [<package>|<rockspec>] [<new_version>] [<new_url>]`
8
9Creates a rockspec for a new version of a rock based on data from an existing
10rockspec.
11
12If a package name is given, it downloads the latest rockspec from the public
13rocks server. If a rockspec URL or path is given, it uses it instead. If no
14argument is given, it looks for a rockspec same way the [luarocks
15make](luarocks_make.md) command does.
16
17New version of the rockspec can be specified by passing it as the second
18argument or by using `--tag` option: the tag will be used as version, with
19leading "v" removed.
20
21New URL (value of `source.url` rockspec field) can be passed as the third
22argument. If it's not passed explicitly it will be inferred from the old URL
23by replacing occurrences of the old version in it with the new one. If new tag
24(value of `source.tag`) is not set explicitly using `--tag`, it is updated in
25the same way.
26
27## Example
28
29Creating a rockspec for version `0.2.0` from an scm rockspec in current
30directory, with new tag `v0.2.0`:
31
32```
33luarocks new_version --tag=v0.2.0
34```
35
36This creates a rockspec called `my-rock-0.2.0-1.rockspec` in current directory.
37
diff --git a/docs/luarocks_pack.md b/docs/luarocks_pack.md
new file mode 100644
index 00000000..7721ba34
--- /dev/null
+++ b/docs/luarocks_pack.md
@@ -0,0 +1,31 @@
1# luarocks pack
2
3Create a rock, packing sources or binaries.
4
5## Usage
6
7`luarocks pack {<rockspec> | <name> [<version>]}`
8
9Argument may be a rockspec file, for creating a source rock, or the name of an
10installed package, for creating a binary rock. In the latter case, the package
11version may be given as a second argument.
12
13## Examples
14
15```
16luarocks pack luafilesystem 1.4.0
17```
18
19Assuming you have LuaFileSystem 1.4.0 installed in your local tree, this
20creates in the current directory a file called
21`luafilesystem-1.4.0-1.linux-x86.rock` (filename will of course vary according
22to the platform), using the binary that is already installed.
23
24```
25luarocks pack copas-1.1.1-1.rockspec
26```
27
28Assuming you have `copas-1.1.1-1.rockspec` in the current directory, this
29creates (also in the current directory) a file called
30`copas-1.1.1-1.src.rock`, fetching sources as specified in the rockspec.
31
diff --git a/docs/luarocks_path.md b/docs/luarocks_path.md
new file mode 100644
index 00000000..05f36fe0
--- /dev/null
+++ b/docs/luarocks_path.md
@@ -0,0 +1,32 @@
1# luarocks path
2
3Return the currently configured package path.
4
5## Usage
6
7`luarocks path [--append] [--bin] [--lr-path | --lr-cpath | --lr-bin]`
8
9Prints package paths for this installation of Luarocks formatted as a shell
10script. The script prepends these values to default system ones
11(`package.path` and `package.cpath`) and updates `$LUA_PATH` and `$LUA_CPATH`
12environment variables. On Unix systems, you may run:
13
14```
15eval $(luarocks path)
16```
17
18If `--append` is passed, LuaRocks paths are appended to system values instead
19of being prepended.
20
21If `--bin` is passed it also prints path to the directories where
22command-line scripts provided by rocks are located, prepending it to
23`$PATH` (or appending if `--append` is used).
24
25`--lr-path`, `--lr-cpath`, and `--lr-bin` flags print just corresponding
26paths, without systems values and not formatted as a shell script.
27
28## Example
29
30```
31luarocks path
32```
diff --git a/docs/luarocks_purge.md b/docs/luarocks_purge.md
new file mode 100644
index 00000000..7fda2565
--- /dev/null
+++ b/docs/luarocks_purge.md
@@ -0,0 +1,22 @@
1# luarocks purge
2
3Remove all installed rocks from a tree.
4
5## Usage
6
7`luarocks purge --tree=<tree> [--old-versions]`
8
9Removes all installed rocks from a given tree. The tree must be provided
10explicitly using `--tree`.
11
12If `--old-versions` is passed, the highest version
13of each rock is kept.
14
15## Example
16
17Deleting all rocks from local tree:
18
19```
20luarocks purge --tree=~/.luarocks
21```
22
diff --git a/docs/luarocks_remove.md b/docs/luarocks_remove.md
new file mode 100644
index 00000000..0a74a2d9
--- /dev/null
+++ b/docs/luarocks_remove.md
@@ -0,0 +1,22 @@
1# luarocks remove
2
3Uninstall a rock.
4
5## Usage
6
7`luarocks remove [--force|--force-fast] <name> [<version>]`
8
9`<name>` is the name of a rock to be uninstalled. If a `<version>` is not
10given, try to remove all versions at once. Will only perform the removal if it
11does not break dependencies.
12
13To override this check and force the removal, use `--force`.
14
15To perform a forced removal without looking for broken dependencies,
16use `--force-fast`.
17
18## Example
19
20```
21luarocks remove --force luafilesystem 1.3.0
22```
diff --git a/docs/luarocks_search.md b/docs/luarocks_search.md
new file mode 100644
index 00000000..70cea427
--- /dev/null
+++ b/docs/luarocks_search.md
@@ -0,0 +1,29 @@
1# luarocks search
2
3Query the LuaRocks servers.
4
5## Usage
6
7`luarocks search [--porcelain] [--source] [--binary] { <query> [<version>] | --all }`
8
9Lists files available on LuaRocks servers. `<query>` is a substring of a rock
10name to filter by. The search can be narrowed further narrowed down using a
11version. To list files for all rocks pass `--all`.
12
13If `--porcelain` is passed, machine-friendly output is produced.
14
15If `--source` is passed, only rockspecs and source rocks are shown.
16
17If `--binary` is passed, only binary and pure-Lua rocks are shown.
18
19Rocks not supporting version of Lua used by LuaRocks are not listed.
20
21The `luarocks search` command queries remote repositories.
22To query your local repository (the rocks you have installed), use [luarocks list](luarocks_list.md).
23
24## Example
25
26```
27luarocks search socket
28```
29
diff --git a/docs/luarocks_show.md b/docs/luarocks_show.md
new file mode 100644
index 00000000..353935c5
--- /dev/null
+++ b/docs/luarocks_show.md
@@ -0,0 +1,25 @@
1# luarocks show
2
3Shows information about an installed rock.
4
5## Usage
6
7`luarocks show <name> [<version>]`
8
9`<name>` is an installed package name.
10Without any flags, show all module information.
11With these flags, return only the desired information:
12
13* `--home` - home page of project
14* `--modules` - all modules provided by this package as used by `require()`
15* `--deps` - packages this package depends on, including indirect dependencies
16* `--rockspec` - the full path of the rockspec file
17* `--mversion` - the package version
18* `--rock-tree` - local tree where rock is installed
19* `--rock-dir` - data directory of the installed rock
20
21## Example
22
23```
24luarocks show luasocket
25```
diff --git a/docs/luarocks_test.md b/docs/luarocks_test.md
new file mode 100644
index 00000000..035d316e
--- /dev/null
+++ b/docs/luarocks_test.md
@@ -0,0 +1,104 @@
1# luarocks test
2
3Run the test suite for the Lua project in the current directory.
4
5## Usage
6
7`luarocks test [-h] [--test-type <type>] [<rockspec>] [<args>] ...`
8
9If the first argument is a rockspec, it will use it to determine the
10parameters for running tests; otherwise, it will attempt to detect the
11rockspec.
12
13Any additional arguments are forwarded to the test suite. To make sure that
14test suite flags are not interpreted as LuaRocks flags, use `--` to separate
15LuaRocks arguments from test suite arguments.
16
17### Arguments
18
19* `rockspec` - Project rockspec.
20* `args` - Test suite arguments.
21
22### Options
23
24* `--test-type <type>` - Specify the test suite type manually if it was not
25 specified in the rockspec and it could not be auto-detected.
26
27## Test types
28
29There are two test types that ship by default with LuaRocks: `busted` and
30`command`. They can be specified explicitly in a rockspec in the `test.type`
31field. Custom test types can be loaded using the `test_dependencies` field; a
32dependency can declare a new test type by adding a module in the
33`luarocks.test.*` namespace; it can then be used as a test type in the
34rockspec.
35
36### `busted` test type
37
38You can enable the `busted` test type adding a top-level `test` table in a
39rockspec and setting its `type` to `busted`. The `busted` type can be
40auto-detected if the project's source contains a configuration file called
41`.busted`, so if a project has that file `luarocks test` can be used to launch
42Busted even if it doesn't have a `test` section in the rockspec.
43
44Here's an example of a `busted` test section, also using the `flags` option to
45pass extra flags to Busted, and using per-platform overrides.
46
47```
48test = {
49 type = "busted",
50 platforms = {
51 windows = {
52 flags = { "--exclude-tags=ssh,git,unix" }
53 },
54 unix = {
55 flags = { "--exclude-tags=ssh,git" }
56 }
57 }
58}
59```
60
61### `command` test type
62
63You can enable the `command` test type adding a top-level `test` table in a
64rockspec and setting its `type` to `command`. The `command` type can be
65auto-detected if the project's source contains a file called `test.lua` at the
66root of the source tree, so if a project has that file `luarocks test` can be
67used to run it using the default Lua interpreter even if it doesn't have a
68`test` section in the rockspec.
69
70The `test` block for a `command` test type can take either a `script`
71argument, which is a Lua script to be launched using the configured Lua
72interpreter, or a `command` argument, which is a command to be launched
73directly on a shell. Both can take additional arguments via the `flags` array
74entry.
75
76Here is an example using a script:
77
78```
79test = {
80 type = "command",
81 script = "tests/test_all.lua",
82}
83```
84
85And here is an example using a command:
86
87```
88test = {
89 type = "command",
90 command = "make test",
91}
92```
93
94## Invocation example
95
96In the following example, assume a project uses Busted as its test tool. The
97current directory contains the source code of a Lua project with a rockspec in
98its root, this will run Busted, pass any additional arguments specified in the
99`test.flags` field of the rockspec, plus the `--exclude-tags=ssh` argument
100given explicitly via the command-line:
101
102```
103luarocks test -- --exclude-tags=ssh
104```
diff --git a/docs/luarocks_through_a_proxy.md b/docs/luarocks_through_a_proxy.md
new file mode 100644
index 00000000..589142fc
--- /dev/null
+++ b/docs/luarocks_through_a_proxy.md
@@ -0,0 +1,36 @@
1# LuaRocks through a proxy
2
3LuaRocks performs network access through either helper applications (typically
4`curl` on macOS, or `wget` on other platforms), or using built-in modules
5LuaSocket and LuaSec. All of them use the same method to configure proxies:
6the `http_proxy`, `https_proxy` and `ftp_proxy` environment variables.
7
8## Environment variable example
9
10On Unix systems, you can set the `http_proxy` environment variable like
11this:
12
13 export http_proxy=http://server:1234
14
15On Windows systems, the command syntax is:
16
17 set http_proxy=http://server:1234
18
19## Git
20
21If you are behind a firewall that blocks the `git://` protocol, you may
22configure your Git to use HTTPS instead. The solution is to tell Git to always
23use HTTPS instead of `git://` by running the following command:
24
25 git config --global url."https://".insteadOf git://
26
27This adds the following to your `~/.gitconfig`:
28
29 [url "https://"]
30 insteadOf = git://
31
32## External references
33
34* [curl manpage](http://www.hmug.org/man/1/curl.php)
35* ["How to use wget through proxy"](http://blog.taragana.com/index.php/archive/how-to-use-wget-through-proxy/)
36* ["Tell git to use https instead of git protocol"](http://jgoodall.me/posts/2013/05/29/git-use-https)
diff --git a/docs/luarocks_unpack.md b/docs/luarocks_unpack.md
new file mode 100644
index 00000000..4fa8754a
--- /dev/null
+++ b/docs/luarocks_unpack.md
@@ -0,0 +1,61 @@
1# luarocks unpack
2
3Unpack the contents of a rock.
4
5## Usage
6
7`luarocks unpack [--force] {<rock> | <rockspec> | <name> [<version>]}`
8
9Unpacks the contents of a rock in a newly created directory under the current
10directory. Argument may be a rock file, a rockspec file, or the name of a
11rock/rockspec in a remote repository.
12
13If `--force` is passed, files are unpacked even if the output directory
14already exists.
15
16When a rock is given, LuaRocks creates a directory and extracts the contents
17of a rock inside it. If it is a `.src.rock` file, it also extracts the
18sources, and copies the rock's rockspec to the root of the sources directory,
19so that you can run [luarocks make](luarocks_make.md).
20
21When a rockspec is given, LuaRocks creates a directory and then fetches and
22extracts the sources for the module inside it. It also copies the rockspec to
23the root of the sources directory.
24
25When a binary rock is given, it just extracts the contents of the rock in the
26created directory for further inspection. To fetch the sources, you can run
27`luarocks unpack` again on the rockspec file that will be extracted from the
28binary rock.
29
30When a name (and optionally a version) is given, LuaRocks tries to download a
31source rock or a rockspec from remote repositories, and then proceeds as if
32the obtained file was provided locally.
33
34## Examples
35
36```
37luarocks unpack luafilesystem 1.4.0
38```
39
40This fetches `luafilesystem-1.4.0-1.src.rock` from the remote repository and
41creates in the current directory a directory called `luafilesystem-1.4.0-1`
42with the contents of the rock, including the LuaFileSystem sources unpacked.
43You will then be able to go into the
44`luafilesystem-1.4.0-1/luafilesystem-1.4.0` directory and run [luarocks
45make](luarocks_make.md).
46
47```
48luarocks unpack copas-1.1.1-1.rockspec
49```
50
51Assuming you have `copas-1.1.1-1.rockspec` in the current directory, this
52creates in the current directory a directory called `copas-1.1.1-1` with the
53rockspec and the Copas sources unpacked. You will then be able to go into the
54`copas-1.1.1-1/copas-1.1.1` directory and run [luarocks
55make](luarocks_make.md).
56
57While the extracted directory names may look repetitive, note that the first
58directory is a directory in a LuaRocks "name-version-revision" format, and the
59second directory is the directory contained inside the sources archives, which
60may be in any format, and in some cases may not even exist.
61
diff --git a/docs/luarocks_upload.md b/docs/luarocks_upload.md
new file mode 100644
index 00000000..167ec803
--- /dev/null
+++ b/docs/luarocks_upload.md
@@ -0,0 +1,26 @@
1# luarocks upload
2
3Upload a rockspec to the public rocks repository.
4
5## Usage
6
7`luarocks upload [--skip-pack] [--api-key=<key>] [--force] <rockspec>`
8
9Packs a source rock file (`.src.rock`) using a rockspec and uploads it
10and the rockspec to the public rocks repository.
11
12To access the server, an API key is required. It is passed using `--api-key`
13option and can be issued at the [LuaRocks site](https://luarocks.org/) on
14the "Setting" page after logging in.
15
16If `--skip-pack` is passed, the source rock is not packed and only the rockspec
17is uploaded.
18
19If `--force` is passed, existing files will be overwritten if the same version
20of the package already exists.
21
22## Example
23
24```
25luarocks upload my-rock-0.1.0-1.rockspec --api-key=<REDACTED>
26```
diff --git a/docs/luarocks_write_rockspec.md b/docs/luarocks_write_rockspec.md
new file mode 100644
index 00000000..59b3fbe0
--- /dev/null
+++ b/docs/luarocks_write_rockspec.md
@@ -0,0 +1,75 @@
1# luarocks write_rockspec
2
3Write a template for a rockspec file.
4
5## Usage
6
7`[--output=<file>] [...] [<name>] [<version>] [<url>|<path>]`
8
9This commands creates an initial version of a rockspec for a rock
10based on name, version, and location of its sources. The resulting
11rockspec is just a template: several fields, such as `dependencies`,
12have to be filled by hand.
13
14If only two arguments are given, the first one is considered the name and the
15second one is the location.
16If only one argument is given, it must be the location.
17If no arguments are given, current directory is used as location.
18LuaRocks will attempt to infer name and version if not given,
19using "scm" as default version.
20
21If location is a local directory and a Git or Mercurial repository,
22source URL will be inferred from it.
23
24Resulting rockspec is created in current directory, with file name
25based on rock name and version. Output location can be changed using `--output` option.
26
27Several fields of the rockspec can be set explicitly:
28
29* `--license=<license>` sets license name, such as `MIT/X11` (by default inferred
30 from `COPYING`, `LICENSE`, or `MIT-LICENSE.txt` files, if they exist).
31* `--summary=<text>` sets short description (by default inferred from
32 `README.md` or `README` files, if they exist).
33* `--detailed=<text>` sets detailed description (by default inferred
34 from `README.md` or `README` files, if they exist).
35* `--homepage` sets project home page URL (by default may be inferred from source URL).
36* `--lua-version=<versions>` sets supported Lua versions. `<versions>` must be one of
37 "5.1", "5.2", "5.3", "5.1,5.2", "5.2,5.3", or "5.1,5.2,5.3".
38* `--rockspec-format=<version>` sets rockspec format version.
39* `--tag=<tag>` sets tag to use. Will attempt to extract version number from it.
40* `--lib=<lib>[,<lib>]` sets libraries that C files need to link with, filling [external_dependencies](rockspec_format.md#dependency-information) table. The argument should be a comma delimited list of names.
41
42LuaRocks will attempt to fill `build` table of the rockspec using
43[builtin build back-end](rockspec_format.md#builtin), listing files from `src`
44and `lua` directories in project sources.
45
46## Example
47
48Creating an scm rockspec for a project hosted in a Git repository:
49
50```
51mkdir my-rock
52cd my-rock
53git init .
54git remote add origin https://github.com/my-username/my-rock
55luarocks write-rockspec
56```
57
58This creates `my-rock-scm-1.rockspec` file:
59
60```lua
61package = "my-rock"
62version = "scm-1"
63source = {
64 url = "git+https://github.com/my-username/my-rock"
65}
66description = {
67 homepage = "https://github.com/my-username/my-rock",
68 license = "*** please specify a license ***"
69}
70dependencies = {}
71build = {
72 type = "builtin",
73 modules = {}
74}
75```
diff --git a/docs/manifest_file_format.md b/docs/manifest_file_format.md
new file mode 100644
index 00000000..2fe57dee
--- /dev/null
+++ b/docs/manifest_file_format.md
@@ -0,0 +1,41 @@
1# Manifest file format
2
3A manifest file describes files contained in a rocks tree or server. Each
4rocks tree or server has a `manifest` file in its root. Rocks servers may also
5have versioned manifests (e.g. `manifest-5.1` for Lua 5.1) and compressed
6manifests (e.g. `manifest-5.1.zip`). These must match the contents of the
7uncompressed manifest.
8
9Like a rockspec, a manifest file contains a Lua program setting several
10globals. Three of them are mandatory:
11
12* `repository`: a table where each key is a package name and its value is a table describing versions of the package
13 hosted on a server or installed in a rocks tree.
14 * `repository[package_name]`: a table where each key is a package version (including revision, e.g. `1.0.0-1`)
15 and its value provides information for that version.
16 * `repository[package_name][package_version]`: a list of tables containing several fields:
17 * `arch`: architecture of the rock as a string. Always set to `installed` in rock tree manifests.
18 * `modules` (only for rock tree manifests): a table mapping module names to paths under installation
19 directory for Lua or C modules.
20 * `commands` (only for rock tree manifests): a table mapping script names to paths under installation
21 directory for binaries.
22 * `dependencies` (only for rock tree manifests): a table mapping names of packages the rock depends on
23 (perhaps indirectly) to versions of installed packages satisfying the dependency.
24* `modules`: empty table in rock server manifests (may change in future releases). In rock tree manifests
25 it's a table mapping module names to lists of packages and versions providing that module. Each value in the
26 list is a string in `module/version` format (e.g. `foo/1.0.0-1`).
27* `commands`: empty table in rock server manifests (may change in future releases). In rock tree manifests
28 it's a table mapping script names to lists of packages and versions providing that script, using same
29 format as `modules` table.
30* `dependencies` (only for rock tree manifests): a table containing precomputed dependency information
31 to be used by `luarocks.loader`. Each key is a package name.
32 * `dependencies[package_name]`: A table where each key is a version (with revision) and its value describes
33 dependencies of that version of the package.
34 * `dependencies[package_name][package_version]`: An array of direct dependencies represented as tables
35 with the following fields:
36 * `name`: name of the rock that is depended on.
37 * `constraints`: an array of parsed version constraints. Each constraint is represented as
38 a table with fields:
39 * `op`: an operator as a string (e.g. `>=`).
40 * `version`: version to the right of the operator as an array of parts, e.g. `{1, 0, 0}` for `1.0.0`.
41 It also contains version as a string in `string` field and may contain revision in `revision` field.
diff --git a/docs/more_resources.md b/docs/more_resources.md
new file mode 100644
index 00000000..587ebb67
--- /dev/null
+++ b/docs/more_resources.md
@@ -0,0 +1,32 @@
1# Community support and more resources
2
3On LuaRocks:
4
5* [Matrix chat-room](https://app.gitter.im/#/room/#luarocks_luarocks:gitter.im)
6 - for all things LuaRocks!
7* [luarocks GitHub issues](https://github.com/luarocks/luarocks/issues) - for
8 reporting bugs in the CLI tool
9* [luarocks-site GitHub issues](https://github.com/luarocks/luarocks/issues) -
10 for reporting bugs related to the [luarocks.org](https://luarocks.org)
11 website itself
12
13On Lua:
14
15* [Lua mailing list](http://www.lua.org/lua-l.html) - for questions about the Lua language itself or specific Lua modules (most module authors hang out there!)
16* [Lua documentation](http://www.lua.org/docs.html) - documentation on the Lua language, including the reference manual
17* [Lua Forum](https://luaforum.com) - a beginner friendly Lua community
18
19On LuaJIT:
20
21* [LuaJIT mailing list](http://luajit.org/list.html) - for LuaJIT-specific discussion
22
23## Presentations on LuaRocks
24
25Some past presentations discussing LuaRocks:
26
27* [LuaRocks: fostering an ecosystem for Lua modules](http://hisham.hm/talks#fosdem2015), presented by Hisham Muhammad at FOSDEM 2015, Brussels, Belgium
28* [What's new in LuaRocks](http://hisham.hm/talks#luawshop14), presented by Hisham Muhammad at the Lua Workshop 2014, Moscow, Russia
29* [LuaRocks - past, present and future](http://hisham.hm/talks#luawshop13), presented by Hisham Muhammad at the Lua Workshop 2013, Toulouse, France
30* [LuaRocks 2.0](http://hisham.hm/talks#luawshop09), presented by Hisham Muhammad at the Lua Workshop 2009, Rio de Janeiro, Brazil
31* [LuaRocks: o sistema de pacotes de extensão para a linguagem Lua](http://hisham.hm/talks#fisl9), presented by Hisham Muhammad at FISL 9.0 - IX International Forum on Free Software, Porto Alegre, Brazil
32
diff --git a/docs/namespaces.md b/docs/namespaces.md
new file mode 100644
index 00000000..f00c692a
--- /dev/null
+++ b/docs/namespaces.md
@@ -0,0 +1,71 @@
1# Namespaces
2
3The LuaRocks.org repository allows for each user to published their own
4collection of rocks. Since LuaRocks 3, this concept of per-user rocks has been
5integrated into the tool, in the form of **namespaces**.
6
7What you can do with namespaces:
8
9* Install packages using a namespace:
10 * `luarocks install my_user/my_rock`
11* Depend on a specific namespaced version of a rock in your rockspec:
12 * `dependencies = { "my_user/my_rock > 2.0" }`
13
14## Background
15
16LuaRocks has always supported multiple repositories, which can be set in the
17[config file](config_file_format.md) with the `rocks_servers` entry. A
18repository is an address (a local directory or a remote URL) where LuaRocks
19can find a `manifest-5.x` file and .rock and .rockspec files. We also call
20such repository a "manifest", for short.
21
22The [LuaRocks.org](LuaRocks.org)(LuaRocks.org)(https://luarocks.org) website
23features a root manifest at `https://luarocks.org` as well as per-user
24manifests at `https://luarocks.org/manifests/<your-user-name>`. Entries in the
25root manifest are operated in a first-come first-served manner, but even if
26someone else has already taken a rock name, you can upload your own version of
27it to your user manifest. You can refer to a per-user manifest the same way as
28any other rocks server, adding to your configuration or using it with the
29`--server` flag. This means that you were always able to install your own
30version of a rock using a command such as `luarocks install <my-rock>
31--server=https://luarocks.org/manifests/<your-user-name>`. However, you could
32not specifically depend on it from another rockspec, and once installed, the
33information that this rock came from a specific manifest was lost. With
34namespaces, now you can!
35
36## Using namespaces
37
38All `luarocks` commands that accept a rock name as command line argument can
39now take a namespaced variant:
40
41```
42luarocks install my_user/my_rock
43```
44
45LuaRocks will take your `rocks_trees` configuration and search for namespaced
46manifests on each entry: for example, given the default server
47`https://luarocks.org` it will look in
48`https://luarocks.org/manifests/my_user`.
49
50When installing, LuaRocks will internally store the information that this copy
51of `my_rock` came from the `my_user` namespace, so it will be able to use that
52information when another rockspec specifically asks for `my_user/my_rock` in
53its dependencies. (The namespace information is stored in a separate
54`rock_namespace` metadata file, at
55`lib/luarocks/rocks-5.x/my_rock/1.0-1/rock_namespace`, relative to your local
56rocks tree.)
57
58## Compatibility between non-namespaced and namespaced rocks
59
60A namespaced package can stand for a non-namespaced one. If you have
61`my_user/my_rock 1.0` installed and a rock depends on `my_rock 1.0`, the
62installed rock will satisfy the dependency.
63
64The opposite is not true: if you have `my_rock 1.0` installed but that did not
65come from a `my_user` namespace, it will not satisfy a dependency for
66`my_user/my_rock`.
67
68## Current limitations
69
70You cannot have two rocks with the same name and version but different
71namespaces installed at the same time in the same local rocks tree.
diff --git a/docs/paths_and_external_dependencies.md b/docs/paths_and_external_dependencies.md
new file mode 100644
index 00000000..c7a59408
--- /dev/null
+++ b/docs/paths_and_external_dependencies.md
@@ -0,0 +1,43 @@
1# Paths and external dependencies
2
3Many Lua rocks are bindings to C libraries: for example,
4[luaossl](https://luarocks.org/modules/daurnimator/luaossl) is a binding
5library to the [OpenSSL](https://openssl.org) library. This means that, in our
6example, luaossl _depends on_ OpenSSL. But since this is not a regular
7rock-to-rock dependency (if it were, LuaRocks could solve this by itself), we
8call this an **external dependency**.
9
10When building a rock with external dependencies, LuaRocks needs to make sure
11the necessary C libraries and headers are installed, and know where those C
12libraries are.
13
14## Specifying external dependencies in your rockspecs
15
16When writing a rock with external dependencies, one needs to be careful to
17avoid the "works on my machine" situation: when you write code that hardcodes
18the location of external dependencies as they are in your system, but then
19fails to build in other people's systems.
20
21The way to avoid this problem is to avoid any hardcoded paths. Instead, the
22`build` section of a [rockspec](rockspec_format.md) should make use of path
23variables. If not using the `builtin` build type, paths set by the module's
24own build system must not be relied on and explicit paths should be passed to
25it by the rockspec instead.
26
27Paths where LuaRocks should install files into are defined as the `PREFIX`,
28`LUADIR`, `LIBDIR` and `BINDIR` variables. (See the [Config file
29format](config_file_format.md) page for details.)
30
31Paths for external dependencies (such as C libraries used in the compilation
32of modules) are generated from the `external_dependencies` section of the
33rockspec (see the [Rockspec format](rockspec_format.md) page for details.) Lua
34itself is considered a special external dependency.
35
36These path variables are set in the global `variables` table defined in the
37[config file](config_file_format.md). Their values are populated automatically
38by LuaRocks, but can be overriden by the user (either by setting them directly
39in the config file, or by passing them through the "luarocks" command line).
40
41The `variables` table always contains entries for `LUA_BINDIR`, `LUA_INCDIR`
42and `LUA_LIBDIR`. Like the other external dependency variables, these can be
43overriden in the LuaRocks config file or in the command line. \ No newline at end of file
diff --git a/docs/pinning_versions_with_a_lock_file.md b/docs/pinning_versions_with_a_lock_file.md
new file mode 100644
index 00000000..19ccb3ae
--- /dev/null
+++ b/docs/pinning_versions_with_a_lock_file.md
@@ -0,0 +1,52 @@
1# Pinning versions with a lock file
2
3Pinning dependency versions is a way to get more predictable builds. As
4explained in [this
5page](https://before-you-ship.18f.gov/infrastructure/pinning-dependencies/):
6
7> The practice of “pinning dependencies” refers to making explicit the
8versions of software your application depends on (defining the dependencies of
9new software libraries is outside the scope of this document). Dependency
10pinning takes different forms in different frameworks, but the high-level idea
11is to “freeze” dependencies so that deployments are repeatable. Without this,
12we run the risk of executing different software whenever servers are restaged,
13a new team-member joins the project, or between development and production
14environments.
15
16## Pinning dependencies in LuaRocks
17
18To pin dependencies in LuaRocks, you build a package as usual, using `luarocks
19build` or `luarocks make`, and add the `--pin` option. This will build the
20package and its dependencies, and will also create a `luarocks.lock` file in
21the current directory. This is a text file containing the names and versions
22of all dependencies (and its dependencies, recursively) that were installed,
23with the exact versions used when building.
24
25## Using pinned dependencies in LuaRocks
26
27When building a package with `luarocks build`, `luarocks make` (or via
28`luarocks install` if there is not prebuilt binary package), *without* using
29`--pin`, if the current directory contains a `luarocks.lock` file, it is used
30as the authoritative source for exact version of all dependencies, both
31immediate and recursively loaded dependencies. For each dependency that is
32recursively scanned, LuaRocks will attempt to use the version in the
33`luarocks.lock` file, ignoring the version constraints in the rockspec.
34
35When building a package using a lock file, `luarocks.lock` is copied to the
36package's metadata directory (e.g.
37`/usr/local/luarocks/rocks/5.3/name/version/luarocks.lock`) — if you later
38pack it as a binary rock with `luarocks pack`, the lock file will be packaged
39inside the rock, and will be used when that binary rock is installed with
40`luarocks install`.
41
42## Updating pinned dependencies
43
44Building a package again with the `--pin` flag ignores any existing
45`luarocks.lock` file and recreates this file, by scanning dependency based on
46the dependency constraints specified in the rockspec.
47
48It is also possible to edit the `luarocks.lock` by hand, of course, but there
49are no checks: if the versions you set for the various dependencies are not
50compatible with each other, LuaRocks won't be able to do anything about it and
51will blindly follow what is set on the `luarocks.lock` file.
52
diff --git a/docs/platform_agnostic_external_dependencies.md b/docs/platform_agnostic_external_dependencies.md
new file mode 100644
index 00000000..97f983fa
--- /dev/null
+++ b/docs/platform_agnostic_external_dependencies.md
@@ -0,0 +1,93 @@
1# Platform-agnostic external dependencies
2
3Since 0.6, LuaRocks supports specifying files for external dependency search
4in a platform-agnostic way. When filenames given in the
5`external_dependencies` section of a [rockspec](rockspec_format.md) don't
6have any dot (".") characters, their contents are substituted according to the
7patterns given in the `external_deps_patterns` table of the [configuration
8file](config_file_format.md).
9
10These patterns will typically not be used in the configuration file, as
11LuaRocks provides sensible defaults. The default patterns defined on Unix are:
12
13```
14bin = {"?"}
15lib = {"lib?.a", "lib?.so"}
16include = {"?.h"}
17```
18
19On Windows the defaults are:
20
21```
22bin = {"?.exe", "?.bat"}
23lib = {"?.lib", "?.dll"}
24include = {"?.h"}
25```
26
27For example, a [rockspec](rockspec_format.md) can define an external
28dependency like this:
29
30```
31external_dependencies = {
32 FOO = {
33 library = "foo"
34 }
35 }
36```
37
38and this will result in searches for libfoo.a or libfoo.so on Unix systems,
39and foo.lib or foo.dll on Windows. For entries that have more than one
40pattern, such as lib, only one entry needs to be satisfied.
41
42In other words, the value "foo" you see in the
43external_dependencies.FOO.library entry is the same value you would use when
44linking the library, for example -lfoo. In addition, once you added FOO in the
45external_dependencies, this means you can pass entries such as FOO_DIR and
46FOO_LIBDIR to the `luarocks` command-line tool, in case you have these
47libraries in non-standard locations. For example, if the user installed the
48library in a custom location in their own home directory, it would still be
49usable, like this:
50
51```
52luarocks install my_rockspec_using_foo-1.0-1.rockspec FOO_LIBDIR=/home/joeuser/foo/lib
53```
54
55When performing external dependency checks during installation (as opposed to
56build) of rocks, static libraries and headers are not searched. The
57`runtime_external_deps_patterns` table is used instead.
58
59Since 3.4.0, the variable DEPS_DIR which doesn't depend on the name FOO, could
60also used, like this:
61
62```
63luarocks install my_rockspec_using_foo-1.0-1.rockspec DEPS_DIR=/home/joeuser/foo/lib
64```
65
66# When filenames don't match
67
68If the pattern system is not enough to hide platform differences, you can
69always resort to [per-platform overrides](platform_overrides.md). For example:
70
71```
72external_dependencies = {
73 FOO = {
74 library = "foo"
75 }
76 platforms = {
77 win32 = {
78 FOO = {
79 library = "winfoo32.dll"
80 }
81 }
82 }
83}
84```
85
86# Statically linked libraries and dependencies
87
88If your rock links a library statically, avoid adding a library search in its
89[rockspec](rockspec_format.md)'s `external_dependencies` table. Search for a
90header instead, so that the external dependency search does not fail when
91users install a binary rock and they don't have the library installed
92separately.
93
diff --git a/docs/platform_overrides.md b/docs/platform_overrides.md
new file mode 100644
index 00000000..ddda180f
--- /dev/null
+++ b/docs/platform_overrides.md
@@ -0,0 +1,20 @@
1# Platform overrides
2
3To specify platform-specific information in rockspecs, one should use the
4`platforms` field of top-level tables.
5
6In top-level tables, a field `platforms` is treated specially. If present,
7it may contain a table containing sub-tables representing different platforms.
8For example, `build.platforms.unix`, if present, as the name implies, would
9be a table containing specifics for building on Unix systems.
10
11The contents of platform tables override the contents of the top-level table
12where `platforms` is located. For example, in a Linux system, an entry
13`build.platforms.linux.foo` will override `build.foo`. Tables are
14scanned deeply, so if `build.foo` is a table, the contents of
15`build.platforms.linux.foo` will add to or replace the contents of
16`build.foo`, instead of just replacing the entire table. Therefore, you
17don't need to rewrite the entire `build` section in a platform table, only
18the fields should change.
19
20
diff --git a/docs/recommended_practices_for_makefiles.md b/docs/recommended_practices_for_makefiles.md
new file mode 100644
index 00000000..1391ec3b
--- /dev/null
+++ b/docs/recommended_practices_for_makefiles.md
@@ -0,0 +1,176 @@
1# Recommended practices for Makefiles
2
3When authoring a Lua module, especially those containing C code, developers
4are always faced with some build and deployment issues: where to find
5libraries, where to install modules, which flags to pass when building, and so
6on. Looking at the existing modules available in the web, it is clear to see
7that there are no _de facto_ standards in Makefiles for Lua modules, and that
8many of them are incomplete copies of one another, and many of them share the
9same deficiencies. Here is a list of some of those issues we found during the
10development of LuaRocks, and how to avoid them. Following the recommendations
11below will improve the portability of your Makefiles and make things easier
12for writing rocks, other packagers such as Linux distributions, and your
13users.
14
15# Do not ask users to edit files "by hand"
16
17Asking users to hand-edit things is error-prone. Even though systems like
18LuaRocks support applying patches -- which is the automated equivalent of
19hand-tweaking files -- this adds maintenance burden, as patches have to be
20updated on each release if any change happens in the file. Always use
21variables, so that they can be overridden by automated processes. Hand-tweaks
22in the code can be avoided by propagating C defines from Makefiles as well.
23
24Don't:
25```
26// Edit this to suit your installation
27const char* bla_dir = "/usr/local/share/bla";
28```
29
30Do:
31
32```
33BLA_DIR=/usr/local/share/bla
34# ...
35bla.o:
36 $(CC) -c bla.c -DBLA_DIR=\"$(BLA_DIR)\"
37```
38
39## Do not hardcode any paths
40
41This is a corollary to the above recommendation, really. Whenever you are
42passing any paths, don't write them directly in Makefile rules. Always factor
43them out into variables.
44
45# Provide a nice "install" rule
46
47A large number of Makefiles for Lua modules ship without an "install" rule,
48probably due to the long-standing lack of standard install locations for
49modules that plagued the Lua world in the past. Nowadays, however, the
50convention of using .../lib/lua/5.1/ for C modules and .../share/lua/5.1/ for
51Lua modules (relative to the prefix where Lua is installed) is well
52established, and there is no reason not to use it. To make things even easier
53for your users, you can also factor out the common Lua prefix. /usr/local is a
54good default, since it is also the default for the vanilla Lua tarball.
55
56Don't:
57
58```
59# no make install rule!
60```
61
62Do:
63
64```
65LUA_DIR=/usr/local
66LUA_LIBDIR=$(LUA_DIR)/lib/lua/5.1
67LUA_SHAREDIR=$(LUA_DIR)/share/lua/5.1
68
69# ...
70
71install:
72 mkdir -p $(LUA_LIBDIR)/bla
73 cp bla/core.so $(LUA_LIBDIR)/bla
74 mkdir -p $(LUA_SHAREDIR)/bla
75 cp bla.lua $(LUA_SHAREDIR)
76 cp bla/extras.lua $(LUA_SHAREDIR)/bla
77```
78
79Some packagers recommend prepending an empty `$(DESTDIR)` variable to all target
80paths in your install rule, but that's not strictly necessary if your paths
81are all set into variables, which can be redefined for the "make install" run,
82like in the example above.
83
84# Do not assume libraries are in the system path
85
86If your program uses LibPNG, adding "-lpng" to your Makefile is not enough.
87Your users may have the LibPNG library somewhere else, so let them specify the
88locations of both the libraries and headers. The default values you pick are
89not really important, as long as they're overridable by the user, but
90/usr/local is always a good choice on Unix systems as this is the first
91typical "non-system path" that users may want to use.
92
93Of course, use one library per value; don't assume all third-party libraries
94can be found in the same place.
95
96Don't:
97
98```
99gcc -o bla bla.c -lpng
100```
101
102Do:
103
104```
105LIBPNG_DIR=/usr/local
106LIBPNG_INCDIR=$(LIBPNG_DIR)/include
107LIBPNG_LIBDIR=$(LIBPNG_DIR)/lib
108
109# ...
110 $(CC) -o bla bla.c -lpng -L$(LIBPNG_LIBDIR) -I$(LIBPNG_INCDIR)
111```
112
113# Avoid compiler assumptions
114
115Even if your code only compiles in GCC and is Unix-only, there are still build portability issues to look out for. The main ones are:
116
117* **Not all GCCs link libraries with the same flags** - for instance, linking
118 shared libraries is done with "-shared" on Linux and "-bundle -undefined
119 dynamic_lookup -all_load" on Mac OSX. Factoring the flags in a variable is
120 a nice gesture for users of other operating systems. (LuaRocks can take
121 care of the detection part and set the flag appropriately, but packages of
122 other systems will benefit as well.)
123
124* **The compiler is not always called "gcc"** - this one is for the people in
125 the embedded world; in their toolchains, their cross-compilers often have
126 names like "arm-nofpu-gcc". $(CC) is a standard variable in make. Just use
127 that instead of "gcc" and you're good to go.
128
129Don't:
130
131```
132bla.so:
133 gcc -o bla.so -shared bla.o
134```
135
136Do:
137
138```
139LIBFLAG=-shared
140# ...
141bla.so:
142 $(CC) -o bla.so $(LIBFLAG) bla.o
143```
144
145# Do not "overload" variables
146
147As mentioned in the topic about third-party libraries above, don't reuse variables just because two conceptually different locations happen to point to the same place. For example, do not assume that the directory you're using to _find_ libraries and the directory you're _installing_ libraries to is the same. That little economy will only cause confusion and trouble to your users.
148
149Don't:
150
151```
152LIBDIR=/usr/local/lib
153INCDIR=/usr/local/include
154# ...
155bla.so:
156 $(CC) $(LIBFLAG) -o bla.so -lpng -L$(LIBDIR) -I$(INCDIR)
157install:
158 mkdir -p $(LIBDIR)
159 cp bla.so $(LIBDIR)/lua/5.1
160```
161
162Do:
163
164```
165LIBPNG_DIR=/usr/local
166LIBPNG_LIBDIR=$(LIBPNG_DIR)/lib
167LIBPNG_INCDIR=$(LIBPNG_DIR)/include
168LUA_DIR=/usr/local
169LUA_LIBDIR=$(LUA_DIR)/lib/lua/5.1
170# ...
171bla.so:
172 $(CC) $(LIBFLAG) -o bla.so -lpng -L$(LIBPNG_LIBDIR) -I$(LIBPNG_INCDIR)
173install:
174 mkdir -p $(LUA_LIBDIR)
175 cp bla.so $(LUA_LIBDIR)
176```
diff --git a/docs/release_history.md b/docs/release_history.md
new file mode 100644
index 00000000..4759fe17
--- /dev/null
+++ b/docs/release_history.md
@@ -0,0 +1,597 @@
1# Release history
2
3**Version 3.11.1** - 31/May/2024 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.11.1.tar.gz) -
4[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.11.1-windows-32.zip) -
5[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.11.1-windows-64.zip) -
6[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.11.1-linux-x86_64.zip) -
7[other files](http://luarocks.github.io/luarocks/releases)
8
9**Version 3.11.0** - 13/Mar/2024 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.11.0.tar.gz) -
10[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.11.0-windows-32.zip) -
11[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.11.0-windows-64.zip) -
12[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.11.0-linux-x86_64.zip) -
13[other files](http://luarocks.github.io/luarocks/releases)
14
15**Version 3.10.0** - 27/Feb/2024 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.10.0.tar.gz) -
16[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.10.0-windows-32.zip) -
17[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.10.0-windows-64.zip) -
18[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.10.0-linux-x86_64.zip) -
19[other files](http://luarocks.github.io/luarocks/releases)
20
21**Version 3.9.2** - 08/Dec/2022 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.9.2.tar.gz) -
22[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.9.2-windows-32.zip) -
23[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.9.2-windows-64.zip) -
24[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.9.2-linux-x86_64.zip) -
25[other files](http://luarocks.github.io/luarocks/releases)
26
27**Version 3.9.1** - 01/Jul/2022 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.9.1.tar.gz) -
28[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.9.1-windows-32.zip) -
29[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.9.1-windows-64.zip) -
30[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.9.1-linux-x86_64.zip) -
31[other files](http://luarocks.github.io/luarocks/releases)
32
33**Version 3.9.0** - 17/Apr/2022 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.9.0.tar.gz) -
34[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.9.0-windows-32.zip) -
35[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.9.0-windows-64.zip) -
36[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.9.0-linux-x86_64.zip) -
37[other files](http://luarocks.github.io/luarocks/releases)
38
39* `builtin` build mode now always respects CC, CFLAGS and LDFLAGS
40* Check that lua.h version matches the desired Lua version
41* Check that the version of the Lua C library matches the desired Lua version
42* Fixed deployment of non-wrapped binaries
43* Fixed crash when `--lua-version` option is malformed
44* Fixed help message for `--pin` option
45* Unix: use native methods and don't always rely on $USER to determine user
46* Windows: use native CLI tooling more
47* macOS: support .tbd extension when checking for libraries
48* macOS: add XCode SDK path to search paths
49* macOS: add best-effort heuristic for library search using Homebrew paths
50* macOS: avoid quoting issues with LIBFLAG
51* macOS: deployment target is now 11.0 on macOS 11+
52* added DragonFly BSD support
53* LuaRocks test suite now runs on Lua 5.4 and LuaJIT
54* Internal dependencies of standalone LuaRocks executable were bumped
55
56**Version 3.8.0** - 08/Nov/2021 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.8.0.tar.gz) -
57[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.8.0-windows-32.zip) -
58[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.8.0-windows-64.zip) -
59[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.8.0-linux-x86_64.zip) -
60[other files](http://luarocks.github.io/luarocks/releases)
61
62**Version 3.7.0** - 13/Apr/2021 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.7.0.tar.gz) -
63[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.7.0-windows-32.zip) -
64[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.7.0-windows-64.zip) -
65[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.7.0-linux-x86_64.zip) -
66[other files](http://luarocks.github.io/luarocks/releases)
67
68**Version 3.6.0** - 30/Mar/2021 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.6.0.tar.gz) -
69[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.6.0-windows-32.zip) -
70[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.6.0-windows-64.zip) -
71[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.6.0-linux-x86_64.zip) -
72[other files](http://luarocks.github.io/luarocks/releases)
73
74**Version 3.5.0** - 10/Dec/2020 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.5.0.tar.gz) -
75[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.5.0-windows-32.zip) -
76[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.5.0-windows-64.zip) -
77[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.5.0-linux-x86_64.zip) -
78[other files](http://luarocks.github.io/luarocks/releases)
79
80**Version 3.4.0** - 25/Sep/2020 - [Source tarball for Unix](http://luarocks.org/releases/luarocks-3.4.0.tar.gz) -
81[Windows binary (32-bit)](http://luarocks.org/releases/luarocks-3.4.0-windows-32.zip) -
82[Windows binary (64-bit)](http://luarocks.org/releases/luarocks-3.4.0-windows-64.zip) -
83[Linux binary (x86_64)](http://luarocks.org/releases/luarocks-3.4.0-linux-x86_64.zip) -
84[other files](http://luarocks.github.io/luarocks/releases)
85
86* `luarocks make` now supports `--only-deps`
87* `luarocks make` new flag: `--no-install`, which only performs the compilation step
88* `--deps-only` is now an alias for `--only-deps` (useful in case you always kept getting it wrong, like me!)
89* `luarocks build` and `luarocks make` now support using `--pin` and `--only-deps` at the same time, to produce a lock file of dependencies in use without installing the main package.
90* `luarocks show` can now accept a substring of the rock's name, like `list`.
91* `luarocks config`: when running without system-wide permissions, try storing the config locally by default. Also, if setting both lua_dir and --lua-version explicitly, auto-switch the default Lua version.
92* `luarocks` with no arguments now prints more info about the location of the Lua interpreter which is being used
93* `luarocks new_version` now keeps the old URL if the MD5 doesn't change.
94* `DEPS_DIR` is now accepted as a generic variable for dependency directories (e.g. `luarocks install foo DEPS_DIR=/usr/local`)
95* Handle quoting of arguments at the application level, for improved Windows support
96* All-in-one binary bundles `dkjson`, so it runs `luarocks upload` without requiring any additional dependencies.
97* Tweaks for Terra compatibility
98* win32: generate proper temp filename
99* No longer assume that Lua 5.3 is built with compat libraries and bundles `bit32`
100* `luarocks show`: do not crash when rockspec description is empty
101* When detecting the location of `lua.h`, check that its version matches the version of Lua being used
102* Fail gracefully when a third-party tool (wget, etc.) is missing
103* Fix logic for disabling mirrors that return network errors
104* Fix detection of Lua path based on arg variable
105* Fix regression on dependency matching of luarocks.loader
106
107**Version 3.3.1** - 07/Feb/2020 - [All Unix](http://luarocks.org/releases/luarocks-3.3.1.tar.gz) -
108[Windows all-in-one executable (32-bit)](http://luarocks.org/releases/luarocks-3.3.1-windows-32.zip) -
109[Windows all-in-one executable (64-bit)](http://luarocks.org/releases/luarocks-3.3.1-windows-64.zip) -
110[other files](http://luarocks.github.io/luarocks/releases)
111
112* Fix downgrades of rocks containing directories: stop it from creating spurious 0-byte files where directories have been
113* Fix error message when attempting to copy a file that is missing
114* Detect OpenBSD-specific dependency paths
115
116**Version 3.3.0** - 28/Jan/2020 - [All Unix](http://luarocks.org/releases/luarocks-3.3.0.tar.gz) -
117[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.3.0-windows-32.zip) -
118[other files](http://luarocks.github.io/luarocks/releases)
119
120**Version 3.2.1** - 05/Sep/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.2.1.tar.gz) -
121[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.2.1-windows-32.zip) -
122[other files](http://luarocks.github.io/luarocks/releases)
123
124**Version 3.2.0** - 28/Aug/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.2.0.tar.gz) -
125[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.2.0-windows-32.zip) - [other files](https://luarocks.github.io/luarocks/releases)
126
127* Bugfix: luarocks path does not change the order of pre-existing path items when prepending or appending to path variables
128* Bugfix: fix directory detection on the Mac
129* When building with --force-config, LuaRocks now never uses the "project" directory, but only the forced configuration
130* Lua libdir is now only checked for commands/platforms that really need to link Lua explicitly
131* LuaJIT is now detected dynamically
132* RaptorJIT is now detected as a LuaJIT variant
133* Improvements in Lua autodetection at runtime
134* luarocks new_version: new option --dir
135* luarocks which: report modules found via package.path and package.cpath as well
136* install.bat: Improved detection for Visual Studio 2017 and higher
137* Bundled LuaSec in all-in-one binary bumped to version 0.8.1
138
139**Version 3.1.3** - 06/Jun/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.3.tar.gz) -
140[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.3-windows-32.zip)
141
142**Version 3.1.2** - 07/May/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.2.tar.gz) -
143[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.2-windows-32.zip)
144
145**Version 3.1.1** - 06/May/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.1.tar.gz) -
146[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.1-windows-32.zip)
147
148**Version 3.1.0** - 30/Apr/2019 - [All Unix](http://luarocks.org/releases/luarocks-3.1.0.tar.gz) -
149[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.1.0-windows-32.zip)
150
151* config: add git-like modes for setting and inspecting configuration
152* make: run rockspec patches on first `luarocks make` run and use a lockfile to avoid double patching
153* persist selected Lua version when setting `luarocks config lua_version 5.x`
154* new flag --global for overriding local_by_default = true
155* do not complain if home cache cannot be created (use temp dir instead)
156* caching improvements for increased performance
157* project-based workflow: if ./.luarocks/config-5.x.lua exists, assume Lua 5.x
158* install, pack, build, make: new flags --sign and --verify (using GPG)
159* install: new flag --no-doc
160* Improve Lua paths auto-detection
161* Various bugfixes
162
163**Version 3.0.4** - 30/Oct/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.4.tar.gz) -
164[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.4-windows-32.zip)
165
166* Fork-free platform detection at startup
167* Improved detection of the default rockspec in commands such as `luarocks test`
168* Various minor bugfixes
169
170**Version 3.0.3** - 15/Sep/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.3.tar.gz) -
171[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.3-windows-32.zip)
172
173* Minor bugfixes
174
175**Version 3.0.2** - 07/Sep/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.2.tar.gz) -
176[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.2-windows-32.zip)
177
178* Improvements in luarocks init, new --reset flag
179* write_rockspec: --lua-version renamed to --lua-versions
180* Improved behavior in module autodetection
181* Bugfixes in luarocks show
182* Fix upgrade/downgrade when a single rock has clashing module filenames
183* Fix for autodetected external dependencies with non-alphabetic characters
184
185**Version 3.0.1** - 14/Aug/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.1.tar.gz) -
186[Windows all-in-one executable](http://luarocks.org/releases/luarocks-3.0.1-windows-32.zip)
187
188* Numerous bugfixes
189* Store Lua location in config file, so that a user can run `luarocks init --lua-dir=/my/lua/location` and have that location remain active for that project
190* Various improvements to the Unix makefile, including $(DESTDIR) support and an uninstall rule
191* Autodetect FreeBSD-style include paths (/usr/include/lua5x/)
192
193**Version 3.0.0** - 25/Jul/2018 - [All Unix](http://luarocks.org/releases/luarocks-3.0.0.tar.gz) -
194[Windows batch installer](http://luarocks.org/releases/luarocks-3.0.0-win32.zip)
195
196* New rockspec format
197* New commands, including `luarocks init` for per-project workflows
198* New flags, including `--lua-dir` and `--lua-version` for using multiple Lua installs with a single LuaRocks
199* New build system, gearing towards a new distribution model
200* General improvements, including namespaces
201* User-visible changes, including some breaking changes
202* Internal changes
203
204**Version 2.4.4** - 12/Mar/2018 - [All Unix](http://luarocks.org/releases/luarocks-2.4.4.tar.gz) -
205[Windows](http://luarocks.org/releases/luarocks-2.4.4-win32.zip)
206
207* Do not halt a package deletion process when a file from the package is missing
208* Updated bundled binaries in Windows package: Lua 5.1.5, Wget 1.19.4, 7zip 18.01
209* Updated Windows installer to better handle gcc toolchains
210* Fix detection of directories on Windows
211* Fixes .def generation on Windows
212
213**Version 2.4.3** - 12/Sep/2017 - [All Unix](http://luarocks.org/releases/luarocks-2.4.3.tar.gz) -
214[Windows](http://luarocks.org/releases/luarocks-2.4.3-win32.zip)
215
216* Fixed display of pathnames in `luarocks show`
217* Improved check for write permissions when installing
218* Plus assorted bugfixes and improvements
219
220**Version 2.4.2** - 30/Nov/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.4.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.4.2-win32.zip)
221
222* Fixed conflict resolution on deploy/delete
223* Improved dependency check messages
224* Performance improvements when removing packages
225* Support user-defined `platforms` array in config file
226* Improvements in Lua interpreter version detection in Unix configure script
227* Relaxed Lua version detection to improve support for alternative implementations (e.g. Ravi)
228* Plus assorted bugfixes and improvements
229
230**Version 2.4.1** - 06/Oct/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.4.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.4.1-win32.zip)
231
232* Avoid coroutine use in luarocks.loader
233* Fix upgrade issues for very old versions
234
235**Version 2.4.0** - 08/Sep/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.4.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.4.0-win32.zip)
236
237* New test suite based on Busted; runs on Linux, OSX and Windows
238* git+ssh:// fetch protocol
239* Improved behavior preserving permissions
240* Improved listing of dependencies on installation
241* Improved behavior of argument handling in `pack`
242* MSYS and Haiku platform detection
243* Feature-based detection of internal bit32 and utf8 modules
244* Internal reorganization of luarocks.fs code
245* `remove` option --force=fast renamed to --force-fast
246* Plus assorted bugfixes and cleanups
247
248**Version 2.3.0** - 09/Jan/2016 - [All Unix](http://luarocks.org/releases/luarocks-2.3.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.3.0-win32.zip)
249
250* Windows: major redesign of the install tree structure
251* Windows: Auto setup of MSVC environments
252* Improve error messages when tools are not installed
253* CMake: generate 64-bit builds when appropriate
254* Improve check of location of config files
255* MacOSX: set MACOSX_DEPLOYMENT_TARGET using env
256* Remove --extensions flag; use rockspec_format instead
257* New `luarocks config` command to query configuration
258* Improved UI for messages when external deps are missing
259* Unix: Robustness improvement in configure script
260* Plus tweaks and bugfixes. See the changelog for details.
261
262**Version 2.2.2** - 24/Apr/2015 - [All Unix](http://luarocks.org/releases/luarocks-2.2.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.2.2-win32.zip)
263
264* `luarocks build --only-deps` and `luarocks install --only-deps` for installing dependencies only
265* Mercurial support
266* Improved command-line argument parser, now validates arguments (it previously ignored unrecognized arguments) and accepts both `--flag=option` and `--flag option` in flags that take arguments.
267* For consistency with `luarocks show`, `luarocks doc --homepage` is now `luarocks doc --home`
268* Improvements to CMake build backend
269* Improved Makefiles for handling simultaneous bootstrapped installations
270* Various bugfixes
271
272**Version 2.2.1** - 17/Mar/2015 - [All Unix](http://luarocks.org/releases/luarocks-2.2.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.2.1-win32.zip)
273
274* Improved compatibility with Lua 5.3
275* `luarocks list --outdated` for listing modules with available upgrades
276* Assorted bugfixes
277
278**Version 2.2.0** - 15/Aug/2014 - [All Unix](http://luarocks.org/releases/luarocks-2.2.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.2.0-win32.zip)
279
280* MoonRocks is the new default repository: http://rocks.moonscript.org - Rocks don't need to be sent to the LuaRocks mailing list anymore, you can upload them directly at the website or using...
281* ...`luarocks upload` command for uploading rocks to MoonRocks via the command-line
282* Preliminary support for Lua 5.3
283* No longer uses the module() function, for Lua 5.2 installations built without Lua 5.1 compatibility
284* --branch flag for `luarocks build` and `luarocks make`
285* various improvements in `luarocks doc` command
286* "git+http" transport for source.url
287
288**Version 2.1.2** - 10/Jan/2014 - [All Unix](http://luarocks.org/releases/luarocks-2.1.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.1.2-win32.zip)
289
290* major improvements in the Windows install.bat script. Now installs by default on standard Windows locations, while the old self-contained all-under-one-dir installation is still supported through an option flag. The documentation at luarocks.org didn't catch up with it yet, so please refer to "install /?" for instructions.
291* a new command, "luarocks doc <module>" that tries to find any installed documentation. Due to the lack of documentation standards for Lua, this uses a few heuristics. Feedback on the feature is appreciated.
292* a rocks_provided configuration entry in which you can preload dependencies that are already fulfulled in your system; a few defaults are included (bit32 is auto-provided in Lua 5.2; luabitop is auto-provided in LuaJIT)
293* generated script wrappers are now more robust
294* Graceful handling of permission errors on Windows
295* Minor performance improvements
296* Support for "named trees", so you can label your rocks trees and use flags such as --tree=system or --tree=user instead of the full path
297* "luarocks" with no arguments presents more useful diagnostics
298* Improved Lua detection in Unix installer
299* plus assorted bugfixes
300
301**Version 2.1.1** - 29/Oct/2013 - [All Unix](http://luarocks.org/releases/luarocks-2.1.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.1.1-win32.zip)
302
303* Remote manifests are now compressed and locally cached, making commands faster
304* New command "write_rockspec" which generates rockspec file templates
305* detection of multiarch directories on Linux
306* environment and performance improvements on Windows
307* New --force=fast option for 'luarocks remove'
308* New --local-tree flag for 'luarocks-admin make-manifest'
309* Improved error checking
310* plus assorted bugfixes
311
312**Version 2.1.0** - 09/Aug/2013 - [All Unix](http://luarocks.org/releases/luarocks-2.1.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.1.0-win32.zip)
313
314* accesses manifest-{5.1,5.2} in remote servers to provide properly filtered results for Lua 5.1 or 5.2
315* Remove old versions when installing a new one and old versions are no longer needed to honor dependencies.
316* 'make bootstrap' is now an advertised option for installing LuaRocks itself as a rock on Unix systems
317* 'luarocks purge --old-versions' for cleaning up a local tree
318* --keep flag to produce the old behavior of keeping old versions around (can be made permanent setting keep_old_versions=true in the config file)
319* security config options 'accepted_build_types' and 'hooks_enabled'
320* 'lua_version' is now available as a global for your config.lua
321* new flags --lr-path, --lr-cpath, --lr-bin for 'luarocks path' for use in scripts
322* friendlier error messages
323* plus bugfixes
324
325**Version 2.0.13** - 16/Apr/2013 - [All Unix](http://luarocks.org/releases/luarocks-2.0.13.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.13-win32.zip)
326
327* Support for Lua 5.2 is no longer marked as experimental
328* Support for installing two instances of LuaRocks, for Lua 5.1 and 5.2, in parallel
329* Improvements for the 'builtin' build mode on Windows
330* rclauncher on Windows does not rely on a precompiled object anymore
331* Improvements for the Windows installer, including optional registry entries for context-menu operations
332* Improvements in 'luarocks new_version` command for autogenerating updated rockspecs
333* 'luarocks remove' command accepts rock and rockspec filenames
334
335**Version 2.0.12** - 05/Nov/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.12.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.12-win32.zip)
336
337* "Dependencies mode" selection to configure how to work with multiple local trees
338* New command "purge" that erases a local tree
339* --porcelain flag for "list" and "search"
340* More consistent user-agent reporting
341* Code cleanups, removal of dead code
342* Fixes regressions on Mac and Windows
343
344**Version 2.0.11** - 21/Sep/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.11.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.11-win32.zip)
345
346* Work around LuaSocket crash when given proxy URLs without the scheme part
347* Save manifest file in a single fs operation to make it more atomic
348* Fix tree loading order on luarocks.loader with multiple trees
349* Fix detection of write permissions
350* Improve dependency detection using configurable patterns, now a file like "libfoo.so.1" satisfies "libfoo.so"
351* --bin flag for "luarocks path" command, exports $PATH
352* Support for mirrors in the rocks_servers list, default list of mirrors included
353* Avoid using Lua modules internally on Windows, to avoid file system locking
354* Add NetBSD support
355* Rename luarocks.rep to luarocks.repos
356* Fail gracefully on the absence of cmake, on cmake build mode
357* New command "lint", to check the syntax of a rockspec
358* Fix builtin build mode on Mac OSX < 10.5
359* Improve configure tests for Debian-based platforms
360
361**Version 2.0.10** - 12/Jul/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.10.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.10-win32.zip)
362
363* Fix fetching Git tags/branches
364* Fix strictness issue with parameter of io.open
365* Builtin mode sets rpath when compiling on Unix
366* Use full path in $(LUA) when configured with --with-lua
367* Cleanup of .svn dir in svn-based rocks
368* Improvement for 'make bootstrap'
369
370**Version 2.0.9** - 31/May/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.9.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.9-win32.zip)
371
372* Experimental support for Lua 5.2 (auto-detection and explicit --lua-version flag in configure)
373* Solaris support and BSD fixes
374* --nodeps flag for forced installation without dependencies
375* "new_version" command to streamline writing of updated rockspecs
376* Improved handling of LUAROCKS_SYSCONFIG variable
377* Clickable URLs in descriptions in rocks repo index.html
378* Nicer-looking persisted tables
379* Assorted bugfixes
380
381**Version 2.0.8** - 29/Feb/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.8.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.8-win32.zip)
382
383* Fix in CMake build backend
384* Fix handling error condition of --pack-binary-rock
385* Fixes for Windows .bat installer
386* Improved arch detection when packing binary rocks
387* Workaround LuaPosix 5.1.15 problem with chmod()
388* Proper error messages when config files are invalid
389* Avoid checking permissions when it's not necessary
390* Fix behavior of 'builtin' rocks which install init.lua scripts
391* git+file:// pseudoprotocol for local Git repos
392* New binaries from GnuWin32 shipped in Win32 zip
393* Nicer-looking help
394
395**Version 2.0.7.1** - 10/Jan/2012 - [All Unix](http://luarocks.org/releases/luarocks-2.0.7.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.7.1-win32.zip)
396
397* Fix installation of files in build operation
398* Deprecate --to and --from, use --server and --tree instead
399* Improved documentation, thanks to LDoc
400
401**Version 2.0.7** - 10/Dec/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.7.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.7-win32.zip)
402
403* Quieter git checkout
404* --only-sources flag to restrict download of sources from a single domain
405* Copy entries to bin/ with proper permissions
406* Fix --pack-binary-rock and add support for it in "luarocks make" as well
407* Isolate references to "5.1" to luarocks.cfg module
408* More logical names for flags: --tree, --server
409* Improved documentation
410
411**Version 2.0.6** - 04/Oct/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.6.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.6-win32.zip)
412
413* Fixes for rockspecs missing 'description' or the contents of 'source.url'
414* Escape fixes for LuaJIT/Metalua
415* Support for building a rock without installing it
416* Site-local configuration is now at luarocks.site_config
417* Support for Mercurial
418* Flag for experimental extensions
419* Plus assorted bugfixes
420
421**Version 2.0.5** - 17/Aug/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.5.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.5-win32.zip)
422
423* External commands are overridable through variables or config.lua
424* No longer uses print() - output goes to stdout, errors to stderr
425* Handle redirects between http (LuaSocket) and https (LuaSec)
426* Avoid relying on the $PWD variable
427* Code cleanups
428
429**Version 2.0.4.1** - 17/Jan/2011 - [All Unix](http://luarocks.org/releases/luarocks-2.0.4.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.4.1-win32.zip)
430
431* Minor bugfix release
432
433**Version 2.0.4** - 23/Dec/2010 - [All Unix](http://luarocks.org/releases/luarocks-2.0.4.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.4-win32.zip)
434
435* Command "remove" for luarocks-admin
436* Check for write permissions in repository and suggest --local
437* Remove .git from source tree when downloading from Git
438* Display of external dependencies in index.html
439* OpenBSD support
440* More thorough search for external libraries
441* Normalize paths to fix behavior when LFS is used under Windows
442* Add HTTPS support using LuaSec when using LuaSocket, for consistency
443* Better propagation of error messages
444* Stable sort of persisted files such as manifests
445* Plus assorted bugfixes
446
447**Version 2.0.3** - 14/Sep/2010 - [All Unix](http://luarocks.org/releases/luarocks-2.0.3.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.3-win32.zip)
448
449* Check for permissions and warn user instead of just installing in local tree
450* --local flag for operations on the local tree
451* -fPIC is always set in CFLAGS exported to makefiles
452* respect permissions when copying files in Unix systems
453* display license after build/installation
454* svn:// protocol for scm rockspecs
455* "luarocks list" and "luarocks search" are now case-insensitive
456* "luarocks-admin add" supports adding multiple files at once
457* "luarocks-admin add" supports rsync for download and upload and scp for upload
458* new command: "luarocks show" displays information about an installed rock
459* new command: "luarocks path" to make it easy to export Lua env variables
460* plus assorted bugfixes
461
462**Version 2.0.2** - 01/Apr/2010 - [All Unix](http://luarocks.org/releases/luarocks-2.0.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.2-win32.zip)
463
464* use LuaSocket if available for downloading files
465* use LuaZip if available for unzipping files
466* MinGW support in builtin build backend
467* updated installation files for Windows, including a LuaForWindows-compatible package
468
469**Version 2.0.1** - 27/Oct/2009 - [All Unix](http://luarocks.org/releases/luarocks-2.0.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0.1-win32.zip)
470
471* luarocks.cfg is no longer edited during installation; a separate site-local luarocks.config module is created.
472* robustness fixes and improvements for luarocks.add
473* cleanup of configure options and references to the old LuaForge URLs
474* install LuaRocks as a rock
475* plus assorted bugfixes
476
477**Version 2.0** - 17/Oct/2009 - [All Unix](http://luarocks.org/releases/luarocks-2.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-2.0-win32.zip)
478
479* module files are now deployed to standard Lua-style paths
480* new package loader module luarocks.loader, superseding the require()-override module luarocks.require
481* new abstraction system for file system operations: the OS-specific back-ends for luarocks.fs were split between native-Lua and tool-based implementations
482* new format for local manifest
483* new command for luarocks: "download", to fetch .rock and .rockspec files
484* new commands for luarocks-admin: "add", to upload rocks to a repository, and "refresh_cache", to refresh the cache used by the "add" command
485* plus a number of cleanups and bugfixes
486
487**Version 1.0.1** - 13/Mar/2009 - [All Unix](http://luarocks.org/releases/luarocks-1.0.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-1.0.1-win32.zip)
488
489* Improve portability in usage of Unix tools
490* Allow use of local rocks servers in the --from flag
491* Improve detection of external libraries on Mac OSX
492* Fix build of the 'builtin' backend under Windows
493* Support for the 'md5' binary as a MD5 checker
494
495**Version 1.0** - 01/Sep/2008 - [All Unix](http://luarocks.org/releases/luarocks-1.0.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-1.0-win32.zip)
496
497* Add support for post-install hooks
498* Path helper scripts for binaries on Windows systems.
499* Git support, contributed by Thomas Harning.
500* Improve shell compatibility for different Unix systems.
501* Add the @ operator for no-upgrade dependencies.
502* Add check for rockspec version format.
503* Generate index.html when building a manifest for a repository.
504* Plus assorted bugfixes.
505
506**Version 0.6** - 30/Jun/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.6.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.6-win32.zip)
507
508* Check external deps on binary installs. Allow rockspecs to specify supported platforms. Support platform-agnostic specification of external deps files. Allow overriding external deps subdirs.
509* Structured build systems in subdirectories.
510* Smarter check to decide if a rock is pure Lua or not, also checking bin/
511* Restructuring of fs code.
512* Modularized fetch code to support multiple SCMs.
513* Added specific support for 'doc' directory in rockspecs. Auto-install files in 'lua' in builtin builds.
514* Support for Surround SCM, contributed by Ignacio Burgueño.
515* "module" build type renamed to "builtin"; "cvs_tag" and "cvs_module" renamed to "tag" and "module". Old names still supported for compatibility for now, to be cleaned up by 1.0.
516* Plus many bugfixes.
517
518**Version 0.5.2** - 13/May/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.5.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.5.2-win32.zip)
519
520* Fixes problems with removal of read-only files on Windows
521* Fixes issues with external libraries on the 'module' build type on Windows
522* Fixes the --only-from flag
523* Renames the luarocks.config module to luarocks.cfg avoiding conflict's with the user configuration file config.lua
524
525**Version 0.5.1** - 25/Apr/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.5.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.5.1-win32.zip)
526
527* Added function get_rock_from_module in luarocks.require, allowing apps to inspect which rock they're getting modules from.
528* Added variables LUA, LIB_EXTENSION and OBJ_EXTENSION, now available for rockspec authors.
529* Assorted bugfixes, especially for the Windows package.
530* Build system improvements: add DESTDIR variable to makefile to make things easier for distros packaging LuaRocks.
531
532**Version 0.5** - 03/Apr/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.5.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.5-win32.zip)
533
534* New flags in the ./configure on Unix (see configure --help) and install.bat on Windows (see install.bat /?)
535* Support for multiple local repositories. By extension, LuaRocks features more intuitive configuration defaults (it installs rocks to $PREFIX/lib/luarocks if you have the permission, and to $HOME/.luarocks if you don't).
536* Flags --from=_server_, --only-from=_server_ and --to=_tree_, to allow specifying exactly where to get rocks from and where to install them to.
537* The manifest file now stores dependency info -- luarocks.require no longer scans rockspec files.
538* 'unpack' command allows unpacking binary and pure-Lua rocks, for inspecting.
539* Plus assorted bugfixes.
540
541**Version 0.4.3** - 03/Mar/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.3.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4.3-win32.zip)
542
543* The MD5 check feature added in 0.4.2 can now use openssl instead of md5sum (making LuaRocks friendlier to OSX).
544* Added a license file in the tarball (making LuaRocks friendlier to Debian).
545* Plus assorted bugfixes.
546
547**Version 0.4.2** - 09/Feb/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4.2-win32.zip)
548
549* Support .lua files directly in the URL field.
550* Perform check of MD5 checksum in sources.
551* Accept plain strings in all fields of the source table of the "module" build type.
552* Bugfixes.
553
554**Version 0.4.1** - 25/Jan/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4.1-win32.zip)
555
556* New configure/install.bat flags for setting scripts dir and local repository dir.
557* "unpack" command now supports rockspec files as well.
558* Complete code documentation.
559* Many assorted bugfixes.
560
561**Version 0.4** - 18/Jan/2008 - [All Unix](http://luarocks.org/releases/luarocks-0.4.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.4-win32.zip)
562
563* Adds the "unpack" command for debugging rocks (.src.rock only at this point).
564* Support curl as an alternative downloader for OSX, removing the dependency on wget.
565* Support for installing non-Lua entries in bin/ dirs.
566* Support for specifying libdirs, incdirs, libraries and defines in "module"-type builds.
567* x86_64 support, by Brian Hetro.
568* FreeBSD support, by Matthew M. Burke.
569* Performance improvements.
570* Many assorted bugfixes.
571
572**Version 0.3.2** - 21/Dec/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.3.2.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.3.2-win32.zip)
573
574* Support for patching and inclusion of extra files (such as Makefiles) through a rockspec.
575* Support "platforms" overrides table for dependencies, external dependencies and source URLs.
576* Many assorted bugfixes.
577
578**Version 0.3.1** - 18/Dec/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.3.1.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.3.1-win32.zip)
579
580* Improved search: results now feature separate lists for source and binary rocks.
581* Windows support for the "module" build type (using Visual Studio).
582* Many assorted bugfixes.
583
584**Version 0.3** - 04/Dec/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.3.tar.gz) - [Windows](http://luarocks.org/releases/luarocks-0.3-win32.zip)
585
586* Includes Windows package.
587* Adds the "module" build type.
588* Performance improvements.
589
590**Version 0.2** - 23/Oct/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.2.tar.gz)
591
592* Bugfixes and improvements to build infrastructure.
593* Adds the LuaRocks "remove" command.
594
595**Version 0.1** - 09/Aug/2007 - [All Unix](http://luarocks.org/releases/luarocks-0.1.tar.gz)
596
597* Initial release.
diff --git a/docs/rock_file_format.md b/docs/rock_file_format.md
new file mode 100644
index 00000000..10748bde
--- /dev/null
+++ b/docs/rock_file_format.md
@@ -0,0 +1,51 @@
1# Rock file format
2
3This page describes the .rock file format used by LuaRocks.
4
5Note that there are different [types of rocks](types_of_rocks.md).
6
7## Filenames
8
9* .rock and .rockspec filenames must be all-lowercase
10* Rock names must follow the format "$NAME-$VERSION-$REVISION.$PLATFORM.rock", where:
11
12 * $NAME is an arbitrary name (matchable via `"[a-z0-9_-]+"`)
13 * $VERSION is a version number parseable by LuaRocks (e.g. "1.0", "2.1beta1", "scm" for git-HEAD/svn-master rockspecs)
14 * $REVISION is the rockspec revision number, a positive integer
15 * $PLATFORM must follow the format "$OS-$ARCH", where:
16
17 * $OS is an operating system identifier known by LuaRocks
18 * $ARCH is a hardware architecture identifier known by LuaRocks
19
20## Source rocks
21
22A source rock must contain at its root the rockspec file. For a rock called `myrock-1.0-1.src.rock` it would be called:
23
24* `myrock-1.0-1.rockspec` - the [rockspec file](Rockspec format) in the archive root
25
26Additionally, it must contain the sources:
27
28* If the `source.url` field is specified using a file download protocol-type URL (`http://`, `https://`, `file://` and so on) pointing to the source archive (or source file in case of a single-file rock), the rock should contain the product of downloading this URL.
29 * For example, a source rock may contain two files: `myrock-1.0-1.rockspec` and `myrock-1.0.tar.gz`
30* If the `source.url` field is specified using a Source Control Manager (SCM) protocol-type URL (`git://`, `hg://`, `svn://` and so on), the rock should contain the corresponding checked-out sources. The SCM metadata (e.g. the `.git` directory) does not need to be present. (Note: This is not specific to "scm" rocks that point to in-development repositories; a stable-version rockspec may use a SCM-based URL and an SCM tag with `source.tag` in the rockspec to point to a release version).
31 * For example, a source rock may contain at the root the rockspec `myrock-1.0-1.rockspec` and a directory `myrock` that would be the result of `git clone https://github.com/example/myrock`
32
33## Binary rocks
34
35A binary rock must contain at its root two files. For a rock called `myrock-1.0-1.linux-x86.rock` they would be called:
36
37* `myrock-1.0-1.rockspec` - the [rockspec file](Rockspec-format) in the archive root
38* `rock_manifest` - a [rock manifest file](Rock-manifest-file-format)
39
40These standard directories are handled specially:
41
42* `lib/` - a directory containing binary modules (the contents of this directory are files that go into `$PREFIX/lib/lua/5.x/` in a vanilla Lua installation on Unix). The directory structure inside this directory is replicated when installing.
43* `lua/` - a directory containing Lua modules (the contents of this directory are files that go into `$PREFIX/share/lua/5.x/` in a vanilla Lua installation on Unix). The directory structure inside this directory is replicated when installing.
44* `bin/` - a directory containing executable Lua scripts (the contents of this directory are files that go into `$PREFIX/bin/` in a vanilla Lua installation on Unix)
45* `doc/` or `docs/` - documentation files - if present, their contents are listed when running `luarocks doc`. The directory structure inside this directory is replicated when installing.
46
47Any additional directories in the .rock file are copied verbatim (including subdirectories) to `$ROCK_TREE/lib/luarocks/rocks-5.x/myrock/1.0-1/` (common directories are `tests`, `samples`, `examples`, etc.
48
49### Pure-Lua rocks
50
51Pure-Lua rocks are identical to binary rocks, except that they don't have a `lib/` directory containing binary modules. When a rock contains only `lua/` files and no `lib/` files, it automatically gains the `.all.rock` file extension. If the rock is platform-specific, the packager may rename the file to the proper platform, or specify the list of supported platforms in the `supported_platforms` table of the rockspec.
diff --git a/docs/rock_manifest_file_format.md b/docs/rock_manifest_file_format.md
new file mode 100644
index 00000000..e7838d11
--- /dev/null
+++ b/docs/rock_manifest_file_format.md
@@ -0,0 +1,19 @@
1# Rock manifest file format
2
3The `rock_manifest` file lists the files contained in a binary rock, with the
4MD5 checksum for each file.
5
6It is a Lua file containing a single global variable definition, that defines
7the variable **rock_manifest**, assigning to it a _table of file checksums_ of
8the [archive file's root directory](Rock file format) (except for the
9`rock_manifest` file itself).
10
11A table of file checksums is defined as a table describing a directory, where
12for each entry in the directory, there is a string key with its filename (only
13the basename).
14
15If the filename is a non-directory, the value of its key is a string with the
16MD5 checksum of the file.
17
18If the filename is a directory, the value of its key is itself a table of file
19checksums of that directory.
diff --git a/docs/rocks_repositories.md b/docs/rocks_repositories.md
new file mode 100644
index 00000000..6e0f38cb
--- /dev/null
+++ b/docs/rocks_repositories.md
@@ -0,0 +1,54 @@
1# Rocks repositories
2
3For normal use, rocks repositories are manipulated by the `luarocks`
4command-line tool. LuaRocks fetches rocks from one kind of repository -- rocks
5servers -- and installs them into another kind of repository -- rocks trees.
6
7Generally speaking, a rocks repository is a directory containing rocks and/or
8rockspecs, and a manifest file which catalogs the rocks contained therein.
9Rocks servers may contain [packed rocks](types_of_rocks.md) and rockspecs, and
10may be located in remote (HTTP or FTP) URLs or paths in the local filesystem.
11Rocks trees can contain only [unpacked](types_of_rocks.md) (installed) rocks,
12and are always local.
13
14LuaRocks can be configured to use multiple rocks trees and multiple rocks
15servers. See the [Config file format](config_file_format.md) for details and
16the reference for the [luarocks](luarocks.md) command-line tool for details.
17
18Publishing a repository as a rocks server consists of making a directory
19containing rocks and a manifest file available online. A manifest file can be
20created using the make-manifest command of the `luarocks-admin` command-line
21tool, included in LuaRocks. For the rocks tree, the manifest file is updated
22automatically by LuaRocks.
23
24# Rocktree structure
25
26A rocks tree has this (default) layout;
27
28```
29{base} (base rocks tree directory)
30 ├── bin (deployment of command line scripts)
31 ├── lib
32 │ ├── luarocks
33 │ │ └── rocks (contains manifest and sub-dirs with rocks)
34 │ │
35 │ └── lua
36 │ └── 5.1 (deployment of binary modules)
37
38 └── share
39 └── lua
40 └── 5.1 (deployment of Lua modules)
41```
42
43Whenever LuaRocks installs a rock it will install them (the executable parts)
44in the deployment directories. These directories should be included in your
45system path, `LUA_PATH`, and `LUA_CPATH` to be able to
46`require` the modules from your own scripts or use the command line
47scripts from a prompt. Other included elements (see `copy_directories`
48in rockspec), including the manifest and rockspecs, will be stored in the
49`base/lib/luarocks/rocks`.
50
51When multiple versions of the same rock are being installed, the older ones in
52the deployment directories will be renamed to a name including the version.
53The `luarocks.loader` module will be able to load the proper version of
54the modules despite the changed names.
diff --git a/docs/rockspec_format.md b/docs/rockspec_format.md
new file mode 100644
index 00000000..d74daa9e
--- /dev/null
+++ b/docs/rockspec_format.md
@@ -0,0 +1,164 @@
1# Rockspec format
2
3For number fields, strings are accepted and converted using tonumber().
4
5## Package metadata
6
7* **rockspec_format** (string) - the file format version. Example: "1.0"
8* **package** (string, mandatory field) - the name of the package. Example: "LuaSocket"
9* **version** (string, mandatory field) - the version of the package, plus a suffix indicating the revision of the rockspec. Example: "2.0.1-1"
10* **description** (table)
11 * **description.summary** (string) - A one-line description of the package. Example: "Network support for the Lua language"
12 * **description.detailed** (string) - A longer description of the package. Example: "LuaSocket is a Lua extension library that is composed by two parts: a C core that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for functionality commonly needed by applications that deal with the Internet."
13 * **description.license** (string) - The license used by the package. A short name, such as "MIT" and "GPL-2" is preferred. Software using the same license as Lua 5.x should use "MIT".
14 * **description.homepage** (string) - An URL for the project. This is not the URL for the tarball, but the address of a website. Example: "http://github.com/keplerproject/rings"
15 * **description.issues_url** (string) (since 3.0) - An URL for the project's issue tracker. Example: "http://github.com/keplerproject/rings/issues"
16 * **description.maintainer** (string) - Contact information for the _rockspec_ maintainer (which may or may not be the package maintainer -- contact for the package maintainer can usually be obtained through the address in the homepage field). Example: "John Doe &lt;john@doe.gov&gt;"
17 * **description.labels** (array of strings) (since 3.0) - A list of short strings that specify labels for categorization of this rock. See the list of labels at [http://luarocks.org] for inspiration. Example: { "crypto", "network", "tls", "https" }
18
19## Dependency information
20
21Dependencies 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 the luarocks.deps module, but the test/test_deps.lua file included with LuaRocks provides some insights on what these criteria are.
22
23* **supported_platforms** (array of strings) - If this array is not present, the rock is assumed to be portable to any platform. If present, this should contain strings containing LuaRocks platform identifiers, optionally preceded by a "!" to indicate a negative match. If only negative entries are listed, the rock is assumed to be portable to any platform except those listed. If any positive entry exists, then at least one entry must match positively to the currently running platform. Currently supported LuaRocks platform identifiers are: "unix", "windows", "win32", "cygwin", "macosx", "linux", "freebsd". Platforms may have more than one valid identifier; e.g. Linux defines both "unix" and "linux". Note that, as of 0.6, Cygwin under Windows defines {"unix", "cygwin"} but *not* "windows".
24* **dependencies** (array of strings) - Each string represents a package this rock depends on, containing a package name followed by a comma-separated list of constraints. Example: `{"lfs >= 1.0, &lt; 2.0"}`. Accepted operators are the relational operators of Lua: `==` `~=` `<` `>` `<=` `>=` , as well as a special operator, `~>`, inspired by the "pessimistic operator" of RubyGems (`"~> 2"` means `">= 2, < 3"`; `"~> 2.4"` means `">= 2.4, < 2.5"`). The absence of an operator means an implicit `==` (i.e., `"lfs 1.0"` is the same as `"lfs == 1.0"`). "lua" is an special dependency name; it matches not a rock, but the version of Lua in use. Supports [per-platform overrides](platform-overrides).
25* **build_dependencies** (array of strings) (since 3.0) - Dependencies that apply at build-time only, but not when installing binary (`.<platform>.rock`) or pure-Lua (`.all.rock`) rocks. Each string represents a package this rock depends on at build time, containing a package name followed by a comma-separated list of constraints. The syntax in the same as the `dependencies` field. Supports [per-platform overrides](platform-overrides).
26* **external_dependencies** (table) - For each key in the external_dependencies table in the rockspec file, four variables available to the build rules are created: <i>key</i>_DIR, <i>key</i>_BINDIR, <i>key</i>_INCDIR and <i>key</i>_LIBDIR. These are not overwritten if already set (e.g. by the LuaRocks config file or through the command-line). The base prefix for these can be given explicitly setting <i>key</i>_DIR in the config file or through the command-line, or implicitly, defaulting to the value of default_external_deps_dir, set in the config file. Values in the external_dependencies table are tables that may contain a "header" or a "library" field, with filenames to be tested for existence. Example: `{ EXPAT = { header = "expat.h" } }` -- on Unix, this will check that EXPAT_DIR/include/expat.h exists and will create variables accordingly. You can also use platform overrides or specify files of external dependencies in a [platform-agnostic manner](platform-agnostic-external-dependencies). Supports [per-platform overrides](platform-overrides).
27* **test_dependencies** (array of strings) (since 3.0) - Dependencies that apply at test-time only, that is, only needed when running `luarocks test`. Each string represents a package this rock depends on at test time, containing a package name followed by a comma-separated list of constraints. The syntax in the same as the `dependencies` field. Supports [per-platform overrides](platform-overrides).
28
29## Build rules
30
31* **source** (table, mandatory field) - Contains information on how to fetch sources to build this rock. Supports [per-platform overrides](platform-overrides).
32 * **source.url** (string, mandatory field) - the URL of the package source archive. Examples: "http://github.com/downloads/keplerproject/wsapi/wsapi-1.3.4.tar.gz", "git://github.com/keplerproject/wsapi.git". Note that this field is ignored when running [luarocks make](luarocks_make.md), which uses the sources from your current directory instead. Different protocols are supported:
33 * `cvs://` - for the CVS source control manager
34 * `file://` - for URLs in the local filesystem (note that for Unix paths, the root slash is the third slash, resulting in paths like `"file:///full/path/filename"`
35 * `ftp://` - for FTP URLs
36 * `git://` - for the Git source control manager
37 * `git+file://` - for the Git source control manager when using repositories that need file:// URLs
38 * `git+http://` - for the Git source control manager when using repositories that need http:// URLs
39 * `git+https://` - for the Git source control manager when using repositories that need https:// URLs
40 * `git+ssh://` - for the Git source control manager when using repositories that need SSH login, such as `git@example.com/myrepo`
41 * `hg://` - for the Mercurial source control manager
42 * `hg+http://` - for the Mercurial source control manager using repositories that need http:// URLs
43 * `hg+https://` - for the Mercurial source control manager using repositories that need https:// URLs
44 * `hg+ssh://` - for the Mercurial source control manager using repositories that need SSH login
45 * `http://` - for HTTP URLs
46 * `https://` - for HTTPS URLs
47 * `hg://` - for the Mercurial source control manager
48 * `sscm://` - for the SurroundSCM source control manager
49 * `svn://` - for the Subversion source control manager
50 * **source.md5** (string) - the MD5 sum for the source archive. Example: "9ca22fd9f9413b54802d3d40b38c4e5c"
51 * **source.file** (string) - the filename of the source archive. Can be omitted if it can be inferred from the `source.url` field. Example: "luasocket-2.0.1.tar.gz"
52 * **source.dir** (string) - the name of the directory created when the source archive is unpacked. Can be omitted if it can be inferred from the `source.file` field. Example: "luasocket-2.0.1"
53 * **source.tag** (string) - for SCM-based URL protocols such as "cvs://" and "git://", this field can be used to specify a tag for checking out sources. Example: "HEAD" (For compatibility reasons, `source.cvs_tag` is also accepted.)
54 * **source.branch** (string) - for SCM-based URL protocols such as "git://", this field can be used to specify a branch for checking out sources. Example: "v1.0"
55 * **source.module** (string) - for SCM-based URL protocols such as "cvs://" and "git://", this field can be used to specify the module to be checked out. Can be omitted if it is the same as the basename of the `source.url` field. Example: "cgilua" (For compatibility reasons, `source.cvs_module` is also accepted.)
56* **build** (table) - Contains all information pertaining _how_ to build a rock. Supports [per-platform overrides](platform-overrides).
57 * **build.type** (string) - The LuaRocks build back-end to use. Example: "make"
58 * **build.install** (table) - For packages which don't provide means to install modules and expect the user to copy the .lua or library files by hand to the proper locations. This table contains categories of files. Each category is itself a table, where the array part is a list of filenames to be copied. For module directories only, in the hash part, other keys are identifiers in Lua module format, to indicate which subdirectory the file should be copied to. For example, `build.install.lua = {["foo.bar"] = "src/bar.lua"}` will copy src/bar.lua to the foo directory under the rock's Lua files directory. The available categories are:
59 * **build.install.lua** (table) - Lua modules written in Lua.
60 * **build.install.lib** (table) - Dynamic libraries implemented compiled Lua modules.
61 * **build.install.conf** (table) - Configuration files.
62 * **build.install.bin** (table) - Lua command-line scripts.
63 * **build.copy_directories** (array of strings) (since 1.0) - A list of directories in the source directory to be copied to the rock installation prefix as-is. Useful for installing documentation and other files such as samples and tests. Default is {"doc"} for documentation to be locally installed in the rocktree.
64 * :warning: **Warning:** - do not use the following directory names: "lua", "lib", "rock_manifest" or the name of your rockspec; those names are used by the .rock format internally, and attempting to copy directories with those names using the build.copy_directories directive will cause a clash.
65 * **build.patches** (table) - A rockspec can embed patches in unified diff ("diff -u") format, which are applied prior to building the modules. Each entry in this table should contain a descriptive file name for the patch a the key, and the text of the patch as the value (typically, as a long string). The patch is applied from within the source.dir directory, and file names ignore the first directory level (in other word, patches are applied with the equivalent of "patch -p 1"). Keep in mind that the actual text of the patch cannot be indented. Example:
66```
67patches = {
68 ["lua51-support.diff"] = [[
69--- old/mymodule.c....
70]]
71}
72```
73
74### Build back-ends
75
76Build back-ends indicate how to build a package.
77Fields of the `build` table other than `build.type`, `build.platforms` and `build.install` are specific to the given type.
78
79#### builtin
80
81This is a mode for packages distributing pure Lua or simple C modules. All pathnames used are relative to `source.dir`. The goal is to allow module authors to specify compilation of their C code in a clean, simple and portable way.
82
83* **build.modules** (array) - An array in which keys are module names in the format normally used by the require() function, and values may be:
84 * strings - pathnames of Lua files or C sources, for modules based on a single source file.
85 * array of strings - pathnames of C sources of a simple module written in C composed of multiple files.
86 * table - a table containing one or more fields:
87 * **build.sources** (array of strings) - the only mandatory field, pathnames of C sources.
88 * **build.libraries** (array of strings) - external libraries to be linked.
89 * **build.defines** (array of strings) - a list of C defines. eg. { "FOO=bar", "USE_BLA" }
90 * **build.incdirs** (array of strings) - directories to be added to the compiler's headers lookup directory list.
91 * **build.libdirs** (array of strings) - directories to be added to the linker's library lookup directory list.
92
93#### make
94
95Indicates the package uses a Makefile.
96
97 * **build.makefile** (string) - Makefile to be used. Default is "Makefile" on Unix variants and "Makefile.win" under Win32.
98 * **build.build_target** (string) - Default is "".
99 * **build.build_pass** (boolean) - Whether to perform a make pass on the target indicated by `build.build_target`. Default is true (i.e., to run make).
100 * **build.install_target** (string) - Default is "install".
101 * **build.install_pass** (boolean) - Whether to perform a make pass on the target indicated by `build.build_target`. Default is true (i.e., to run make).
102 * **build.build_variables** (table) - Assignments to be passed to make during the build pass. Default is {}.
103 * **build.install_variables** (table) - Assignments to be passed to make during the install pass. Default is {}.
104 * **build.variables** (table) - Assignments to be passed to make on both passes. Default is {}.
105
106Variables expected by this back-end to be provided by the configuration file are:
107
108 * **CC** - Command to call the C compiler.
109 * **CFLAGS** - Flags to be passed to the C compiler. May be empty.
110 * **LIBFLAG** - Flag to be passed to the C compiler to instruct it to build a shared library.
111
112These are usually detected by the default configuration, but can be overridden
113by the [configuration file](config-file-format). See also the "Variables"
114section of the [Config file format](config_file_format.md) specification for
115other path variables that are defined automatically, and the documentation on
116the `external_dependencies` entry above for variables that are automatically
117generated based on paths of external dependencies.
118
119#### cmake
120
121Indicates the package uses CMake for building.
122
123* **build.cmake** (string) - If given, its contents are used as the CMakeLists.txt file. If not given, it is assumed that the package provides a CMakeLists.txt file.
124* **build.variables** (table) - Additional variables to be passed to CMake. Equals to calling CMake with attributes: `cmake -Dkey1=value1 -Dkey2=value2 ...`
125
126Additionally you can specify these environment variables when calling LuaRocks:
127
128 * **CMAKE_MODULE_PATH** - Tells CMake where to search for additional modules.
129 * **CMAKE_INCLUDE_PATH** - Path to desired include directory.
130 * **CMAKE_LIBRARY_PATH** - Path to libraries.
131
132#### command
133
134A simple backend called "command" is also provided, in which build commands are typed in directly in the rockspec file.
135
136* **build.build_command** (string) - Command to run to build the package.
137* **build.install_command** (string) - Command to run to install the package.
138
139#### none
140
141A null build back-end. Indicates that there is no build to perform.
142
143## Test rules
144
145* **test** (table) - Contains all information pertaining how to test a rock. Supports [per-platform overrides](platform-overrides).
146
147### Test back-ends
148
149Test back-ends indicate how to test a package.
150Fields of the `test` table other than `test.type` and `test.platforms` are specific to the given type.
151
152#### busted
153
154If `test.type` is not specified, this type is auto-detected if `.busted` is present in the root of the source tree.
155
156* **test.flags** (array of string) - Additional CLI flags to pass to Busted when running.
157
158#### command
159
160If `test.type` is not specified, this type is auto-detected if a file called `test.lua` is present in the root of the source tree.
161
162* **test.script** (string) - Filename of a Lua script to run as a test. Only one of `script` or `command` should be passed.
163* **test.command** (string) - Filename of a shell command to run as a test. Only one of `script` or `command` should be passed.
164* **test.flags** (array of string) - Additional CLI flags to pass to either the script or command when running.
diff --git a/docs/tools/docs.tl b/docs/tools/docs.tl
new file mode 100644
index 00000000..502de3c4
--- /dev/null
+++ b/docs/tools/docs.tl
@@ -0,0 +1,74 @@
1local lfs = require("lfs")
2
3local args = {...}
4
5if not args[1] then
6 print("missing argument: <dirname>")
7 os.exit(1)
8end
9
10local dirname = args[1]
11
12local function path(filename: string): string
13 return dirname .. "/" .. filename
14end
15
16local function process_md(filename: string)
17 local data = assert(io.open(path(filename))):read("*a")
18 local missing = {}
19 for link in data:gmatch("%]%(([^)]*%.md)[^)]*%)") do
20 if not lfs.attributes(path(link)) then
21 table.insert(missing, { at = filename, link = link })
22 end
23 end
24
25 if #missing == 0 then
26 return
27 end
28
29 print("Broken links:")
30
31 for _, link in ipairs(missing) do
32 print("* At " .. link.at .. " : " .. link.link)
33 end
34
35 os.exit(1)
36end
37
38local function check_index(filename: string, all_pages: {string: boolean})
39 local data = assert(io.open(path(filename))):read("*a")
40 for link in data:gmatch("%]%(([^)]*%.md)[^)]*%)") do
41 all_pages[link] = nil
42 end
43
44 if not next(all_pages) then
45 return
46 end
47
48 local missing = {}
49 for k, _ in pairs(all_pages) do
50 table.insert(missing, k)
51 end
52 table.sort(missing)
53
54 print("Pages not referenced in index:")
55
56 for _, page in ipairs(missing) do
57 print("* " .. page)
58 end
59
60 os.exit(1)
61end
62
63local all_pages = {}
64for f in lfs.dir(args[1]) do
65 if f:match("%.md$") then
66 process_md(f)
67 all_pages[f] = true
68 end
69end
70
71check_index("index.md", all_pages)
72
73print("All ok!")
74
diff --git a/docs/tools/lfs.d.tl b/docs/tools/lfs.d.tl
new file mode 100644
index 00000000..12535ca4
--- /dev/null
+++ b/docs/tools/lfs.d.tl
@@ -0,0 +1,82 @@
1local record lfs
2
3 enum FileMode
4 "file"
5 "directory"
6 "link"
7 "socket"
8 "named pipe"
9 "char device"
10 "block device"
11 "other"
12 end
13
14 record Attributes
15 dev: number
16 ino: number
17 mode: FileMode
18 nlink: number
19 uid: number
20 gid: number
21 rdev: number
22 access: number
23 modification: number
24 change: number
25 size: number
26 permissions: string
27 blocks: number
28 blksize: number
29 end
30
31 enum OpenFileMode
32 "binary"
33 "text"
34 end
35
36 enum LockMode
37 "r"
38 "w"
39 end
40
41 record Lock
42 free: function()
43 end
44
45 dir: function(string): function(): string
46
47 chdir: function(string): boolean, string
48
49 lock_dir: function(string, number): Lock, string
50
51 -- returns number on success, really!? this should be fixed in the lfs library
52 link: function(string, string, boolean): number, string
53
54 mkdir: function(string): boolean, string
55
56 rmdir: function(string): boolean, string
57
58 setmode: function(string, OpenFileMode): boolean, string
59
60 currentdir: function(): string
61
62 attributes: function(string): Attributes
63 attributes: function(string, string): string
64 attributes: function(string, string): number
65 attributes: function(string, string): FileMode
66 attributes: function(string, Attributes): Attributes
67
68 symlinkattributes: function(string): Attributes
69 symlinkattributes: function(string, string): string
70 symlinkattributes: function(string, string): number
71 symlinkattributes: function(string, string): FileMode
72 symlinkattributes: function(string, Attributes): Attributes
73
74 touch: function(string, number, number): boolean, string
75
76 -- TODO: FILE needs to be renamed to io.FILE in tl itself
77 lock: function(FILE, LockMode, number, number): boolean, string
78 unlock: function(FILE, number, number): boolean, string
79
80end
81
82return lfs
diff --git a/docs/types_of_rocks.md b/docs/types_of_rocks.md
new file mode 100644
index 00000000..7e69253d
--- /dev/null
+++ b/docs/types_of_rocks.md
@@ -0,0 +1,32 @@
1# Types of rocks
2
3A **rock** is a bundle containing a specification file (called a "rockspec")
4and files providing Lua modules.
5
6A **[rockspec](rockspec_format.md)** is a Lua file containing a series of
7assignments to variables that provide various information about the rock, such
8as description metadata, dependency relations and build rules. Rocks are
9created from rockspecs.
10
11When packed, a rock is an archive file in ZIP format, with the .rock filename
12extension. When installed, a rock is unpacked into a directory in the local
13rocks repository.
14
15There are several types of rocks, and when packed they are identified by their
16filename extensions. These are:
17
18* Source rocks (`.src.rock`): these contain the rockspec and the source code
19 for the Lua modules provided by the rock. When installing a source rock, the
20 source code needs to be compiled.
21
22* Binary rocks (`_.system-arch_.rock`: `.linux-x86.rock,
23 .macosx-powerpc.rock`): these contain the rockspec and modules in compiled
24 form. Modules written in Lua may be in source .lua format, but modules
25 compiled as C dynamic libraries are compiled to their platform-specific
26 format.
27
28* Pure-Lua rocks (`.all.rock`): these contain the rockspec and the Lua modules
29 they provide in .lua format. These rocks are directly installable without a
30 compilation stage and are platform-independent.
31
32
diff --git a/docs/using_luarocks.md b/docs/using_luarocks.md
new file mode 100644
index 00000000..c65ef432
--- /dev/null
+++ b/docs/using_luarocks.md
@@ -0,0 +1,198 @@
1# Using LuaRocks
2
3So, you have followed the installation instructions (either on
4[Unix](installation_instructions_for_unix.md) or
5[Windows](installation_instructions_for_windows.md)) and now you have LuaRocks
6installed on your machine. Now you probably want to install some rocks
7(packages containing Lua modules) and use them in your Lua code.
8
9For LuaRocks to function properly, we have a quick checklist to go through
10first:
11
12# Command-line tools (and the system path)
13
14LuaRocks installs some command-line tools which are your interface for
15managing your rocks: [luarocks](luarocks.md) and
16[luarocks-admin](luarocks_admin.md). Make sure the directory where they are
17located is in your PATH -- the exact location depends on the flags you gave
18when installing LuaRocks.
19
20Run [luarocks](luarocks.md) to see the available commands:
21
22```
23luarocks
24```
25
26You can get help on any command by using the [luarocks help](luarocks_help.md) command:
27
28```
29luarocks help install
30```
31
32Installing packages is done by typing commands such as:
33
34```
35luarocks install dkjson
36```
37
38# Rocks trees and the Lua libraries path
39
40When you install rocks using the `luarocks install`, you get new modules
41available for loading via `require()` from Lua. For example, after we install
42the dkjson rock, type `luarocks show dkjson` to show the module installed by
43the rock:
44
45```
46luarocks show dkjson
47```
48
49This should output something like this:
50
51```
52dkjson 2.5-2 - David Kolf's JSON module for Lua
53
54dkjson is a module for encoding and decoding JSON data. It supports UTF-8.
55
56JSON (JavaScript Object Notation) is a format for serializing data based on the
57syntax for JavaScript data structures.
58
59dkjson is written in Lua without any dependencies, but when LPeg is available
60dkjson uses it to speed up decoding.
61
62License: MIT/X11
63Homepage: http://dkolf.de/src/dkjson-lua.fsl/
64Installed in: /usr/local
65
66Modules:
67 dkjson (/usr/local/share/lua/5.3/dkjson.lua)
68```
69
70It presents a short description of the rock, its license, and the list of
71modules it provides (in this case, only one, `dkjson`). Note that "Installed
72in:" shows the directory tree where the rock was installed. This is the "rocks
73tree" in use.
74
75Most LuaRocks installations will feature two rocks trees:
76
77* "system" [rock tree](rocks_repositories.md) (used by default)
78* "user" [rock tree](rocks_repositories.md)
79
80To be able to use the module, we need to make sure that Lua can find that
81dkjson.lua file when we run `require("dkjson")`. You can check your Lua paths
82from the Lua environment, using
83
84```
85print(package.path)
86print(package.cpath)
87```
88
89These variables can be pre-configured from outside Lua, using the LUA_PATH and
90LUA_CPATH environment variables.
91
92If you installed both Lua and LuaRocks in their default directories
93(/usr/local on Linux and Mac OSX), then the "system" tree is /usr/local and it
94will work by default. However, the "user" tree (for installing rocks without
95admin privileges) is not detected by Lua by default. For that we'll need to
96configure these environment variables.
97
98LuaRocks offers a semi-automated way to do this. If you type the following
99command:
100
101```
102luarocks path --bin
103```
104
105...it will print commands suitable for your platform for setting up your
106environment. On typical Unix terminal environments, you can type this:
107
108```
109eval "$(luarocks path --bin)"
110```
111
112and it apply the changes, temporarily, to your shell. To have these variables
113set permanently, you have to configure the environment variables to your shell
114configuration (for example, by adding the above line to your `.bashrc` file if
115your shell is Bash).
116
117# Multiple versions using the LuaRocks package loader
118
119If you want to make use of LuaRocks' support for multiple installed versions
120of modules, you need to load a custom package loader: luarocks.loader.
121
122You should be able to launch the Lua interpreter with the LuaRocks-enabled
123loader by typing:
124
125```
126lua -lluarocks.loader
127```
128
129Alternatively, you can load the LuaRocks module loader from Lua by issuing
130this command:
131
132```
133require "luarocks.loader"
134```
135
136If your system is correctly set up so that this command runs with no errors,
137subsequent calls to `require()` are LuaRocks-aware and the exact version of
138each module will be determined based on the dependency tree of previously
139loaded modules.
140
141# Scripts installed by rocks (and the scripts path)
142
143Besides modules, rocks can also install command-line scripts. The default
144location of this directory (unless you configured your local repository
145differently) is /usr/local/bin for system-wide installs and ~/.luarocks/bin
146for per-user installs on Unix and %APPDATA%/luarocks/bin on Windows -- make
147sure it is in your PATH as well.
148
149If you use the `--bin` argument in `luarocks path`, it will also print the
150appropriate PATH configuration:
151
152```
153luarocks path --bin
154```
155
156# Using in Unix systems with sudo
157
158When you use LuaRocks to install a package while you aren't root, the package
159will get installed in $HOME/.luarocks/ instead of the system-wide (by default,
160/usr/local/) and become only available for you. Moreover Lua doesn't know with
161its default setup that packages can be available in the current user's home.
162If you want to install a package available for all users, you should run it as
163superuser, typically using sudo.
164
165For example:
166
167```
168sudo luarocks install stdlib
169```
170
171After that, some files may not have correct permissions. For example, if
172/usr/local/share/lua/5.1/base.lua is only readable by root user, you should at
173least set them to readable for all users (chmod a+r or chmod 644).
174
175For example:
176
177```
178cd /usr/local/share/lua/5.1
179 sudo chmod a+r *
180```
181
182# Using a C compiler
183
184Because rocks are generally available in the repository as [source
185rocks](types_of_rocks.md) rather than binary rocks, it is best to have a C
186compiler available.
187
188On Windows, MinGW and Microsoft compilers are supported. The compiler should
189be in the system path, or explicitly configured in the LuaRocks config files.
190On Windows systems, one way of getting the compiler in the system path is to
191open the appropriate command prompt as configured by your compiler package
192(for example, the MSVC Command Prompt for Visual Studio).
193
194Note that for compiling binary rocks that have dependencies on other
195libraries, LuaRocks needs to be able to find [external
196dependencies](paths_and_external_dependencies.md).
197
198
diff --git a/docs/welcome.md b/docs/welcome.md
new file mode 100644
index 00000000..300f740e
--- /dev/null
+++ b/docs/welcome.md
@@ -0,0 +1,17 @@
1<p align="center"><img src="http://luarocks.github.io/luarocks/luarocks.png" width="500px"/></p>
2
3This is **LuaRocks**, the package manager for the Lua programming language.
4
5LuaRocks allows you to install Lua modules as self-contained packages called
6**[rocks](types_of_rocks.md)**. LuaRocks supports both local and remote
7repositories, and multiple local rocks trees.
8
9LuaRocks is free software and uses the same [license](license.md) as Lua.
10
11## Quick start
12
13* [Download](download.md)
14* [Using LuaRocks](using_luarocks.md)
15* [Creating a rock](creating_a_rock.md)
16
17For more information, check the full [documentation index](index.md).