diff options
Diffstat (limited to 'doc/languages-frameworks/lua.section.md')
| -rw-r--r-- | doc/languages-frameworks/lua.section.md | 69 |
1 files changed, 36 insertions, 33 deletions
diff --git a/doc/languages-frameworks/lua.section.md b/doc/languages-frameworks/lua.section.md index a0e9917b8ec..ea893ce3a4a 100644 --- a/doc/languages-frameworks/lua.section.md +++ b/doc/languages-frameworks/lua.section.md @@ -1,14 +1,8 @@ ---- -title: Lua -author: Matthieu Coudron -date: 2019-02-05 ---- +# User’s Guide to Lua Infrastructure {#users-guide-to-lua-infrastructure} -# User's Guide to Lua Infrastructure +## Using Lua {#using-lua} -## Using Lua - -### Overview of Lua +### Overview of Lua {#overview-of-lua} 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. @@ -23,27 +17,31 @@ The main package set contains aliases to these package sets, e.g. `luaPackages` refers to `lua5_1.pkgs` and `lua52Packages` to `lua5_2.pkgs`. -### Installing Lua and packages +### Installing Lua and packages {#installing-lua-and-packages} -#### Lua environment defined in separate `.nix` file +#### 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 `~/.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 { # ... @@ -52,14 +50,16 @@ using `config.nix`, }; } ``` + and install it in your profile with + ```shell nix-env -iA nixpkgs.myLuaEnv ``` -The environment is is installed by referring to the attribute, and considering +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 `/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. @@ -72,7 +72,7 @@ For the sake of completeness, here's another example how to install the environm } ``` -### How to override a Lua package using overlays? +### How to override a Lua package using overlays? {#how-to-override-a-lua-package-using-overlays} Use the following overlay template: @@ -93,18 +93,22 @@ final: prev: } ``` -### Temporary Lua environment with `nix-shell` +### 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 @@ -114,7 +118,7 @@ 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 +## Developing with Lua {#developing-with-lua} 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 @@ -122,7 +126,7 @@ 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 {#packaging-a-library-on-luarocks} [Luarocks.org](www.luarocks.org) is the main repository of lua packages. The site proposes two types of packages, the rockspec and the src.rock @@ -135,16 +139,17 @@ the whitelist maintainers/scripts/luarocks-packages.csv and updated by running m [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`. -For instance if the rockspec defines `external_dependencies`, these need to be manually added in in its rockspec file then it won't work. +For instance if the rockspec defines `external_dependencies`, these need to be manually added in its rockspec file then it won't work. You can try converting luarocks packages to nix packages with the command `nix-shell -p luarocks-nix` and then `luarocks nix PKG_NAME`. Nix rely on luarocks to install lua packages, basically it runs: `luarocks make --deps-mode=none --tree $out` -#### Packaging a library manually +#### 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 { ... }); ``` @@ -152,16 +157,15 @@ 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-reference} -### Lua interpreters +### Lua interpreters {#lua-interpreters} Versions 5.1, 5.2 and 5.3 of the lua interpreter are available as respectively `lua5_1`, `lua5_2` and `lua5_3`. 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 {#attributes-on-lua-interpreters-packages} Each interpreter has the following attributes: @@ -170,8 +174,7 @@ Each interpreter has the following attributes: - `withPackages`. Simpler interface to `buildEnv`. - `pkgs`. Set of Lua packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`. - -#### `buildLuarocksPackage` function +#### `buildLuarocksPackage` function {#buildluarockspackage-function} The `buildLuarocksPackage` function is implemented in `pkgs/development/interpreters/lua-5/build-lua-package.nix` The following is an example: @@ -187,7 +190,7 @@ luaposix = buildLuarocksPackage { disabled = (luaOlder "5.1") || (luaAtLeast "5.4"); propagatedBuildInputs = [ bit32 lua std_normalize ]; - meta = with stdenv.lib; { + meta = with lib; { homepage = "https://github.com/luaposix/luaposix/"; description = "Lua bindings for POSIX"; maintainers = with maintainers; [ vyp lblasc ]; @@ -211,16 +214,17 @@ install the package By default `meta.platforms` is set to the same value as the interpreter unless overridden otherwise. -#### `buildLuaApplication` function +#### `buildLuaApplication` function {#buildluaapplication-function} The `buildLuaApplication` function is practically the same as `buildLuaPackage`. The difference is that `buildLuaPackage` by default prefixes the names of the packages with the version of the interpreter. Because with an application we're not interested in multiple version the prefix is dropped. -#### lua.withPackages function +#### lua.withPackages function {#lua.withpackages-function} The `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. Using the `withPackages` function, the previous example for the luafilesystem environment can be written like this: + ```nix with import <nixpkgs> {}; @@ -229,6 +233,7 @@ lua.withPackages (ps: [ps.luafilesystem]) `withPackages` passes the correct package set for the specific interpreter version as an argument to the function. In the above example, `ps` equals `luaPackages`. But you can also easily switch to using `lua5_2`: + ```nix with import <nixpkgs> {}; @@ -237,16 +242,14 @@ lua5_2.withPackages (ps: [ps.lua]) Now, `ps` is set to `lua52Packages`, matching the version of the interpreter. - -### Possible Todos +### Possible Todos {#possible-todos} * export/use version specific variables such as `LUA_PATH_5_2`/`LUAROCKS_CONFIG_5_2` * let luarocks check for dependencies via exporting the different rocktrees in temporary config -### Lua Contributing guidelines +### Lua Contributing guidelines {#lua-contributing-guidelines} Following rules should be respected: * Make sure libraries build for all Lua interpreters. * Commit names of Lua libraries should reflect that they are Lua libraries, so write for example `luaPackages.luafilesystem: 1.11 -> 1.12`. - |