### Temporary Lua environment with `nix-shell` {#temporary-lua-environment-with-nix-shell}


There are two methods for loading a shell with Lua packages. The first and recommended method
is to create an environment with `lua.buildEnv` or `lua.withPackages` and load that. E.g.

```sh
$ nix-shell -p 'lua.withPackages(ps: with ps; [ busted luafilesystem ])'
```

opens a shell from which you can launch the interpreter

```sh
[nix-shell:~] lua
```

The other method, which is not recommended, does not create an environment and requires you to list the packages directly,

```sh
$ nix-shell -p lua.pkgs.busted lua.pkgs.luafilesystem
```
Again, it is possible to launch the interpreter from the shell.
The Lua interpreter has the attribute `pkgs` which contains all Lua libraries for that specific interpreter.


## Developing with lua {#lua-developing}

Now that you know how to get a working Lua environment with Nix, it is time
to go forward and start actually developing with Lua. There are two ways to
package lua software, either it is on luarocks and most of it can be taken care
of by the luarocks2nix converter or the packaging has to be done manually.
Let's present the luarocks way first and the manual one in a second time.

### Packaging a library on luarocks {#packaging-a-library-on-luarocks}

[Luarocks.org](https://luarocks.org/) is the main repository of lua packages.
The site proposes two types of packages, the `rockspec` and the `src.rock`
(equivalent of a [rockspec](https://github.com/luarocks/luarocks/wiki/Rockspec-format) but with the source).

Luarocks-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
the whitelist maintainers/scripts/luarocks-packages.csv and updated by running
the package `luarocks-packages-updater`:

```sh

nix-shell -p luarocks-packages-updater --run luarocks-packages-updater
```

[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).
The automation only goes so far though and some packages need to be customized.
These customizations go in [pkgs/development/lua-modules/overrides.nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/lua-modules/overrides.nix).
For instance if the rockspec defines `external_dependencies`, these need to be manually added to the overrides.nix.

You can try converting luarocks packages to nix packages with the command `nix-shell -p luarocks-nix` and then `luarocks nix PKG_NAME`.

#### Packaging a library manually {#packaging-a-library-manually}

You can develop your package as you usually would, just don't forget to wrap it
within a `toLuaModule` call, for instance

```nix
{
  mynewlib = toLuaModule (
    stdenv.mkDerivation {
      # ...
    }
  );
}
```

There is also the `buildLuaPackage` function that can be used when lua modules
are not packaged for luarocks. You can see a few examples at `pkgs/top-level/lua-packages.nix`.

## Lua Reference {#lua-reference}

### Lua interpreters {#lua-interpreters}

Versions 5.1, 5.2, 5.3 and 5.4 of the lua interpreter are available as
respectively `lua5_1`, `lua5_2`, `lua5_3` and `lua5_4`. Luajit is available too.
The Nix expressions for the interpreters can be found in `pkgs/development/interpreters/lua-5`.

#### Attributes on lua interpreters packages {#attributes-on-lua-interpreters-packages}

Each interpreter has the following attributes:

- `interpreter`. Alias for `${pkgs.lua}/bin/lua`.