# Lua {#lua}

## Using Lua {#lua-userguide}

### Overview of Lua {#lua-overview}

Several versions of the Lua interpreter are available: luajit, lua 5.1, 5.2, 5.3.
The 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.

Lua libraries are in separate sets, with one set per interpreter version.

The interpreters have several common attributes. One of these attributes is
`pkgs`, which is a package set of Lua libraries for this specific
interpreter. E.g., the `busted` package corresponding to the default interpreter
is `lua.pkgs.busted`, and the lua 5.2 version is `lua5_2.pkgs.busted`.
The main package set contains aliases to these package sets, e.g.
`luaPackages` refers to `lua5_1.pkgs` and `lua52Packages` to
`lua5_2.pkgs`.

Note that nixpkgs patches the non-luajit interpreters to avoid referring to
`/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.

### Installing Lua and packages {#installing-lua-and-packages}

#### Lua environment defined in separate `.nix` file {#lua-environment-defined-in-separate-.nix-file}

Create a file, e.g. `build.nix`, with the following expression

```nix
with import <nixpkgs> { };

lua5_2.withPackages (
  ps: with ps; [
    busted
    luafilesystem
  ]
)
```

and install it in your profile with

```shell
nix-env -if build.nix
```
Now you can use the Lua interpreter, as well as the extra packages (`busted`,
`luafilesystem`) that you added to the environment.

#### Lua environment defined in `~/.config/nixpkgs/config.nix` {#lua-environment-defined-in-.confignixpkgsconfig.nix}

If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.
using `config.nix`,

```nix
{
  # ...

  packageOverrides =
    pkgs: with pkgs; {
      myLuaEnv = lua5_2.withPackages (
        ps: with ps; [
          busted
          luafilesystem
        ]
      );
    };
}
```

and install it in your profile with

```shell
nix-env -iA nixpkgs.myLuaEnv
```
The environment is installed by referring to the attribute, and considering
the `nixpkgs` channel was used.

#### Lua environment defined in `/etc/nixos/configuration.nix` {#lua-environment-defined-in-etcnixosconfiguration.nix}

For the sake of completeness, here's another example how to install the environment system-wide.

```nix
{
  # ...

  environment.systemPackages = with pkgs; [
    (lua.withPackages (
      ps: with ps; [
        busted
        luafilesystem
      ]
    ))
  ];
}
```

### How to override a Lua package using overlays? {#how-to-override-a-lua-package-using-overlays}

Use the following overlay template:

```nix
final: prev: {

  lua = prev.lua.override {
    packageOverrides = luaself: luaprev: {

      luarocks-nix = luaprev.luarocks-nix.overrideAttrs (oa: {
        pname = "luarocks-nix";
        src = /home/my_luarocks/repository;
      });
    };
  };

  luaPackages = lua.pkgs;
}
```

### 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