Skip to content

Commit dce5fd4

Browse files
mrcjkbmrcjkb
committed
lux announcement
1 parent 7b50a92 commit dce5fd4

File tree

1 file changed

+138
-0
lines changed

1 file changed

+138
-0
lines changed

‎posts/2025-04-07-lux-announcement.markdown

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: Announcing Lux - a luxurious package manager for Lua
3+
tags: lua, luarocks, neovim, nix
4+
class: container
5+
---
6+
7+
![](https://github.com/nvim-neorocks/lux/raw/master/lux-logo.svg){ width=300px }
8+
9+
It's time Lua got the ecosystem it deserves!
10+
11+
For a bit over a year, we have been cooking up [Lux](https://github.com/nvim-neorocks/lux),
12+
a new package manager for creating, maintaining and publishing Lua code.
13+
It does this through a simple and intuitive CLI inspired by other
14+
well-known package managers like [`cargo`](https://doc.rust-lang.org/cargo/).
15+
16+
Today, we feel the project has hit a state of "very usable for everyday tasks"[^1].
17+
18+
[^1]: We still have things to flesh out, like MSVC support, error messages and edge cases,
19+
but all those fixes are planned for the 1.0 release.
20+
21+
22+
## Features
23+
24+
- Fully portable between systems.
25+
- Parallel builds and installs. 🚀
26+
- Handles the installation of Lua headers[^2] for you.
27+
Forget about users complaining they have the wrong Lua headers installed on their system.
28+
All you need to do is specify compatible lua versions.
29+
- A fully embeddable `lux-lib` crate, which can even be built to expose a Lua API.
30+
- Has an actual notion of a "project", with a simple governing `lux.toml` file.
31+
- Uses the `lux.toml` to auto-generate rockspecs.
32+
Say goodbye to managing 10 different rockspec files in your repository. 🎉
33+
- Powerful lockfile support.
34+
- Fully reproducible builds and developer environments.
35+
- Source + rockspec hashes that can be used to make Lux easy to integrate with [Nix](https://nixos.org/).
36+
- Integrated code formatting (`lx fmt`) and linting (`lx check`)
37+
powered by [`stylua`](https://github.com/JohnnyMorganz/StyLua)
38+
and [`luacheck`](https://github.com/mpeterv/luacheck).
39+
- Native support for running tests with [`busted`](https://lunarmodules.github.io/busted/).
40+
- Including the ability to use Neovim as a Lua interpreter.
41+
- Sets up a pure environment.
42+
- Compatible with the luarocks ecosystem.
43+
- In case you have a complex rockspec that you don't want to rewrite to TOML,
44+
lux allows you to create an `extra.rockspec` file, so everything just works.
45+
- Need to install a package that uses a custom luarocks build backend?
46+
Lux can install luarocks and shell out to it for the build step,
47+
while managing dependencies natively.
48+
49+
[^2]: Lua 5.1, 5.2, 5.3. 5.4 and luajit.
50+
51+
52+
## Motivation
53+
54+
### Lua
55+
56+
While extensive, Luarocks carries with it around 20 years of baggage,
57+
which makes it difficult to make suitable for modern Lua development, while
58+
retaining backward compatibility.
59+
60+
With Lux, we're pushing for a fresh start:
61+
62+
- **A notion of a project:**
63+
- With TOML as the main manifest format, you can easily add, remove, pin
64+
and update dependencies using the CLI.
65+
- If you're in a project directory (with a `lux.toml`), commands like `build`
66+
will build your project, and install it into a project-local tree.
67+
- Building will produce a lockfile of your project's dependencies,
68+
allowing you to reproduce your exact dependencies on any compatible system.
69+
- **Enforced SemVer:**
70+
Luarocks allows for arbitrary versions after the patch version.
71+
For example, `1.0.1.0.0.0.2` is considered valid by Luarocks, but it has no
72+
useful meaning.
73+
Lux will parse this too, but will treat everything after the patch
74+
version as a prerelease version.
75+
We made this decision because we want to encourage package maintainers
76+
to stick to [SemVer](https://semver.org/) for their releases.
77+
- **Parallel builds:**
78+
Inspired by the Nix store, Lux hashes[^3] install directories to prevent
79+
package conflicts and enable highly parallel builds without risking file system corruption.
80+
81+
[^3]: See [our guide](https://nvim-neorocks.github.io/explanations/lux-package-conflicts)
82+
for details.
83+
84+
### Neovim
85+
86+
Thanks to our Neovim plugin manager, [`rocks.nvim`](https://github.com/nvim-neorocks/rocks.nvim),
87+
and the later addition of Luarocks support to [`lazy.nvim`](https://github.com/folke/lazy.nvim),
88+
Luarocks has been steadily gaining popularity in the Neovim space as a way of distributing
89+
plugins.
90+
But it's been heavily held back by not being fully portable and by being unpredictable
91+
from system to system.
92+
Because Luarocks is written in Lua, installing a large number of packages
93+
and synchronising plugins with `rocks.nvim` has been painfully slow.
94+
95+
With Lux, we hope that plugins will start treating themselves as Lua projects.
96+
Using Lux is non-destructive and doesn't interfere with the current way of
97+
distributing Neovim plugins (which is via git).
98+
99+
In fact, Lux has a `--nvim` flag, which tells it to install packages into a tree
100+
structure that is compatible with Neovim's [`:h packages`](https://neovim.io/doc/user/repeat.html#packages).
101+
102+
### Nix
103+
104+
If a Neovim plugin exists as a Luarocks package, [`nixpkgs`](https://github.com/NixOS/nixpkgs)
105+
will use it as the source of truth.
106+
This is mainly because with a proper package manager, the responsibility of declaring dependencies
107+
is the responsibility of the package author.
108+
However, Luarocks has very basic lockfile support, which does not include source hashes.
109+
While Luarocks (as does Lux) supports conflicting dependencies
110+
via its [`luarocks.loader`](https://luarocks.org/modules/hisham/luarocks-loader),
111+
nixpkgs cannot reasonably add multiple versions of the same dependency to its package set.
112+
Lux's [`lux.lock`](https://github.com/nvim-neorocks/lux/blob/5d2bee87a99afb6e532421d381d1b4986b855d56/lux-lib/resources/test/sample-project-lockfile-missing-deps/lux.lock),
113+
stores source and rockspec hashes of each dependency.
114+
If the source URL is a git repository, lux will store a [NAR hash](https://nix.dev/manual/nix/2.26/store/file-system-object/content-address#serial-nix-archive).
115+
This means the a `lux.lock` can be used to create a [`fixed-output derivation`](https://bmcgee.ie/posts/2023/02/nix-what-are-fixed-output-derivations-and-why-use-them/)
116+
with all dependencies, just as you can do with a `Cargo.lock`.
117+
118+
119+
## Next steps
120+
121+
Right now, our priorities are set on squashing bugs and improving error messages.
122+
Soon, we'll be rewriting `rocks.nvim` to use Lux instead of Luarocks under the hood.
123+
This should let rocks.nvim catch up with other plugin managers in terms of speed
124+
and make it endlessly more stable than before.
125+
If the rewrite is successful, then that spells great news for the Neovim ecosystem
126+
going forward, as it means that Lux can be embedded in other places too
127+
(e.g. lazy.nvim, which has had troubles with luarocks in the past)!
128+
129+
130+
## Documentation
131+
132+
If you'd like to jump on the Lux train early, head over to [our documentation website](https://nvim-neorocks.github.io/tutorial/getting-started).
133+
A tutorial as well as guides can be found on there.
134+
135+
If you have any questions or issues, feel free to reach out in [the GitHub discussions](https://github.com/nvim-neorocks/lux/discussions)
136+
or [our issue tracker](https://github.com/nvim-neorocks/lux/issues). Cheers! :)
137+
138+
The Lux Team

0 commit comments

Comments
 (0)