pyrox.dev
1# Lua {#lua}
2
3## Using Lua {#lua-userguide}
4
5### Overview of Lua {#lua-overview}
6
7Several versions of the Lua interpreter are available: luajit, lua 5.1, 5.2, 5.3.
8The attribute `lua` refers to the default interpreter, it is also possible to refer to specific versions, e.g. `lua5_2` refers to Lua 5.2.
9
10Lua libraries are in separate sets, with one set per interpreter version.
11
12The interpreters have several common attributes. One of these attributes is
13`pkgs`, which is a package set of Lua libraries for this specific
14interpreter. E.g., the `busted` package corresponding to the default interpreter
15is `lua.pkgs.busted`, and the lua 5.2 version is `lua5_2.pkgs.busted`.
16The main package set contains aliases to these package sets, e.g.
17`luaPackages` refers to `lua5_1.pkgs` and `lua52Packages` to
18`lua5_2.pkgs`.
19
20Note that nixpkgs patches the non-luajit interpreters to avoid referring to
21`/usr` and have `;;` (a [placeholder](https://www.lua.org/manual/5.1/manual.html#pdf-package.path) replaced with the default LUA_PATH) work correctly.
22
23### Installing Lua and packages {#installing-lua-and-packages}
24
25#### Lua environment defined in separate `.nix` file {#lua-environment-defined-in-separate-.nix-file}
26
27Create a file, e.g. `build.nix`, with the following expression
28
29```nix
30with import <nixpkgs> {};
31
32lua5_2.withPackages (ps: with ps; [ busted luafilesystem ])
33```
34
35and install it in your profile with
36
37```shell
38nix-env -if build.nix
39```
40Now you can use the Lua interpreter, as well as the extra packages (`busted`,
41`luafilesystem`) that you added to the environment.
42
43#### Lua environment defined in `~/.config/nixpkgs/config.nix` {#lua-environment-defined-in-.confignixpkgsconfig.nix}
44
45If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.
46using `config.nix`,
47
48```nix
49{ # ...
50
51 packageOverrides = pkgs: with pkgs; {
52 myLuaEnv = lua5_2.withPackages (ps: with ps; [ busted luafilesystem ]);
53 };
54}
55```
56
57and install it in your profile with
58
59```shell
60nix-env -iA nixpkgs.myLuaEnv
61```
62The environment is installed by referring to the attribute, and considering
63the `nixpkgs` channel was used.
64
65#### Lua environment defined in `/etc/nixos/configuration.nix` {#lua-environment-defined-in-etcnixosconfiguration.nix}
66
67For the sake of completeness, here's another example how to install the environment system-wide.
68
69```nix
70{ # ...
71
72 environment.systemPackages = with pkgs; [
73 (lua.withPackages(ps: with ps; [ busted luafilesystem ]))
74 ];
75}
76```
77
78### How to override a Lua package using overlays? {#how-to-override-a-lua-package-using-overlays}
79
80Use the following overlay template:
81
82```nix
83final: prev:
84{
85
86 lua = prev.lua.override {
87 packageOverrides = luaself: luaprev: {
88
89 luarocks-nix = luaprev.luarocks-nix.overrideAttrs(oa: {
90 pname = "luarocks-nix";
91 src = /home/my_luarocks/repository;
92 });
93 };
94 };
95
96 luaPackages = lua.pkgs;
97}
98```
99
100### Temporary Lua environment with `nix-shell` {#temporary-lua-environment-with-nix-shell}
101
102
103There are two methods for loading a shell with Lua packages. The first and recommended method
104is to create an environment with `lua.buildEnv` or `lua.withPackages` and load that. E.g.
105
106```sh
107$ nix-shell -p 'lua.withPackages(ps: with ps; [ busted luafilesystem ])'
108```
109
110opens a shell from which you can launch the interpreter
111
112```sh
113[nix-shell:~] lua
114```
115
116The other method, which is not recommended, does not create an environment and requires you to list the packages directly,
117
118```sh
119$ nix-shell -p lua.pkgs.busted lua.pkgs.luafilesystem
120```
121Again, it is possible to launch the interpreter from the shell.
122The Lua interpreter has the attribute `pkgs` which contains all Lua libraries for that specific interpreter.
123
124
125## Developing with lua {#lua-developing}
126
127Now that you know how to get a working Lua environment with Nix, it is time
128to go forward and start actually developing with Lua. There are two ways to
129package lua software, either it is on luarocks and most of it can be taken care
130of by the luarocks2nix converter or the packaging has to be done manually.
131Let's present the luarocks way first and the manual one in a second time.
132
133### Packaging a library on luarocks {#packaging-a-library-on-luarocks}
134
135[Luarocks.org](https://luarocks.org/) is the main repository of lua packages.
136The site proposes two types of packages, the `rockspec` and the `src.rock`
137(equivalent of a [rockspec](https://github.com/luarocks/luarocks/wiki/Rockspec-format) but with the source).
138
139Luarocks-based packages are generated in [pkgs/development/lua-modules/generated-packages.nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/lua-modules/generated-packages.nix) from
140the whitelist maintainers/scripts/luarocks-packages.csv and updated by running
141the package `luarocks-packages-updater`:
142
143```sh
144
145nix-shell -p luarocks-packages-updater --run luarocks-packages-updater
146```
147
148[luarocks2nix](https://github.com/nix-community/luarocks) is a tool capable of generating nix derivations from both rockspec and src.rock (and favors the src.rock).
149The automation only goes so far though and some packages need to be customized.
150These customizations go in [pkgs/development/lua-modules/overrides.nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/lua-modules/overrides.nix).
151For instance if the rockspec defines `external_dependencies`, these need to be manually added to the overrides.nix.
152
153You can try converting luarocks packages to nix packages with the command `nix-shell -p luarocks-nix` and then `luarocks nix PKG_NAME`.
154
155#### Packaging a library manually {#packaging-a-library-manually}
156
157You can develop your package as you usually would, just don't forget to wrap it
158within a `toLuaModule` call, for instance
159
160```nix
161{
162 mynewlib = toLuaModule ( stdenv.mkDerivation { /* ... */ });
163}
164```
165
166There is also the `buildLuaPackage` function that can be used when lua modules
167are not packaged for luarocks. You can see a few examples at `pkgs/top-level/lua-packages.nix`.
168
169## Lua Reference {#lua-reference}
170
171### Lua interpreters {#lua-interpreters}
172
173Versions 5.1, 5.2, 5.3 and 5.4 of the lua interpreter are available as
174respectively `lua5_1`, `lua5_2`, `lua5_3` and `lua5_4`. Luajit is available too.
175The Nix expressions for the interpreters can be found in `pkgs/development/interpreters/lua-5`.
176
177#### Attributes on lua interpreters packages {#attributes-on-lua-interpreters-packages}
178
179Each interpreter has the following attributes:
180
181- `interpreter`. Alias for `${pkgs.lua}/bin/lua`.
182- `buildEnv`. Function to build lua interpreter environments with extra packages bundled together. See section *lua.buildEnv function* for usage and documentation.
183- `withPackages`. Simpler interface to `buildEnv`.
184- `pkgs`. Set of Lua packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.
185
186#### `buildLuarocksPackage` function {#buildluarockspackage-function}
187
188The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-luarocks-package.nix`
189The following is an example:
190```nix
191{
192 luaposix = buildLuarocksPackage {
193 pname = "luaposix";
194 version = "34.0.4-1";
195
196 src = fetchurl {
197 url = "https://raw.githubusercontent.com/rocks-moonscript-org/moonrocks-mirror/master/luaposix-34.0.4-1.src.rock";
198 hash = "sha256-4mLJG8n4m6y4Fqd0meUDfsOb9RHSR0qa/KD5KCwrNXs=";
199 };
200 disabled = (luaOlder "5.1") || (luaAtLeast "5.4");
201 propagatedBuildInputs = [ bit32 lua std_normalize ];
202
203 meta = {
204 homepage = "https://github.com/luaposix/luaposix/";
205 description = "Lua bindings for POSIX";
206 maintainers = with lib.maintainers; [ vyp lblasc ];
207 license.fullName = "MIT/X11";
208 };
209 };
210}
211```
212
213The `buildLuarocksPackage` delegates most tasks to luarocks:
214
215* it adds `luarocks` as an unpacker for `src.rock` files (zip files really).
216* `configurePhase` writes a temporary luarocks configuration file which location
217is exported via the environment variable `LUAROCKS_CONFIG`.
218* the `buildPhase` does nothing.
219* `installPhase` calls `luarocks make --deps-mode=none --tree $out` to build and
220install the package
221* In the `postFixup` phase, the `wrapLuaPrograms` bash function is called to
222 wrap all programs in the `$out/bin/*` directory to include `$PATH`
223 environment variable and add dependent libraries to script's `LUA_PATH` and
224 `LUA_CPATH`.
225
226It accepts as arguments:
227
228* 'luarocksConfig': a nix value that directly maps to the luarocks config used during
229 the installation
230
231By default `meta.platforms` is set to the same value as the interpreter unless overridden otherwise.
232
233#### `buildLuaApplication` function {#buildluaapplication-function}
234
235The `buildLuaApplication` function is practically the same as `buildLuaPackage`.
236The difference is that `buildLuaPackage` by default prefixes the names of the packages with the version of the interpreter.
237Because with an application we're not interested in multiple version the prefix is dropped.
238
239#### lua.withPackages function {#lua.withpackages-function}
240
241The `lua.withPackages` takes a function as an argument that is passed the set of lua packages and returns the list of packages to be included in the environment.
242Using the `withPackages` function, the previous example for the luafilesystem environment can be written like this:
243
244```nix
245lua.withPackages (ps: [ps.luafilesystem])
246```
247
248`withPackages` passes the correct package set for the specific interpreter version as an argument to the function. In the above example, `ps` equals `luaPackages`.
249But you can also easily switch to using `lua5_1`:
250
251```nix
252lua5_1.withPackages (ps: [ps.lua])
253```
254
255Now, `ps` is set to `lua5_1.pkgs`, matching the version of the interpreter.
256
257### Lua Contributing guidelines {#lua-contributing}
258
259Following rules should be respected:
260
261* Commit names of Lua libraries should reflect that they are Lua libraries, so write for example `luaPackages.luafilesystem: 1.11 -> 1.12`.