Skip to content

docs: rework README for the Lua package set #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Unisay merged 1 commit into from
Jun 14, 2026
Merged

docs: rework README for the Lua package set #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 67 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,76 @@
# Package Sets
# PureScript Lua Package Set

A curated list of [PureScript Lua](https://github.com/Unisay/purescript-lua) packages for the `spago` package manager.
The package set for [pslua](https://github.com/purescript-lua/purescript-lua),
the PureScript-to-Lua compiler backend. It collects the core PureScript
libraries as Lua forks: each fork keeps the upstream PureScript sources and
replaces the JavaScript FFI with Lua that runs on Lua 5.1.

- [What is a package-set?](#what-is-a-package-set)
- [Add your package](#adding-your-package)
- [How do I use package-sets with `spago`?](#how-do-i-use-package-sets-with-spago)
[`src/packages.dhall`](src/packages.dhall) holds only these Lua forks. It is the
*overrides* half of a set, not a whole set: the release workflow copies it
verbatim into each `psc-*` release asset. To build a project you merge it with
the standard PureScript set and let the Lua forks win over their
JavaScript-targeting upstreams.

## What is a package set?
## Using the set with spago

A package set is a collection of packages in which there is only one version for each package, and the entire collection of packages compiles successfully together. A package set ensures you can always install a package from the set without introducing a conflict in your dependencies.
In your project's `packages.dhall`, import both the upstream PureScript set and a
released Lua set, then merge them so the Lua forks override the upstreams:

If you use a package manager based on package sets, that means that to install a package:
```dhall
let upstream-ps =
https://github.com/purescript/package-sets/releases/download/psc-0.15.15-20240309/packages.dhall

1. The package must be in the package set
2. The package's dependencies and transitive dependencies must also be in the package set
let upstream-lua =
https://github.com/purescript-lua/purescript-lua-package-sets/releases/download/psc-0.15.15-20260614-4/packages.dhall

## Adding your package

This repository aims to be a good collection of packages you can depend on.

If you would like to add your new package to the package sets, please make a PR.

## How do I use `package-sets` with `spago`?

[`spago`][spago] is a package manager and build tool for PureScript which uses Dhall package sets. This makes them easy to extend and override.

With `spago` the package-set address is specified in the `upstream` variable of your local `packages.dhall`, which will usually import a remote `packages.dhall`, e.g. the one from this repo. You can change the package-set version you are using by running `spago upgrade-set`, or if you want to point to a particular version, `spago upgrade-set --tag <tag>`.

## How do I use `package-sets` with psc-package?

[`psc-package`][psc-package] is a package manager for PureScript that works essentially by running a bunch of git commands. It is not maintained by the PureScript core team and we recommend using Spago instead.

With `psc-package` the package-set address is set in the `source` field of a `psc-package.json` file, which should list the URL of a repository with a `packages.json` file in the root (such as this one). Your configuration should look something like this:

```json
{
"name": "project-name",
"set": "set-name",
"source": "https://github.com/purescript/package-sets.git",
"depends": ["aff", "console", "prelude"]
}
in upstream-ps // upstream-lua
```

[spago]: https://github.com/purescript/spago
The right operand wins, so every package that has a Lua fork comes from this set
and everything else comes straight from the PureScript set. Pointing `upstream`
at the Lua release on its own would give you only the forks, which is why the
merge is required.

Lua releases are tagged `psc-0.15.15-<YYYYMMDD>[-N]`;
[`latest-compatible-sets.json`](latest-compatible-sets.json) records the most
recent one, and `spago upgrade-set --tag <tag>` moves between them.

## Packages

The Lua forks in this set. Each keeps its upstream PureScript API and ships a Lua
FFI in place of the JavaScript one. The package name is the Dhall key in
`src/packages.dhall` — note that the OpenResty bindings are keyed `lua-ngx`.

| Package | Repository | Version |
|---|---|---|
| arrays | https://github.com/purescript-lua/purescript-lua-arrays | v7.3.0 |
| assert | https://github.com/purescript-lua/purescript-lua-assert | v6.1.1 |
| console | https://github.com/purescript-lua/purescript-lua-console | v6.1.0 |
| control | https://github.com/purescript-lua/purescript-lua-control | v6.0.1 |
| effect | https://github.com/purescript-lua/purescript-lua-effect | v4.1.2 |
| enums | https://github.com/purescript-lua/purescript-lua-enums | v6.1.0 |
| exceptions | https://github.com/purescript-lua/purescript-lua-exceptions | v6.1.0 |
| foldable-traversable | https://github.com/purescript-lua/purescript-lua-foldable-traversable | v6.1.1 |
| functions | https://github.com/purescript-lua/purescript-lua-functions | v6.1.0 |
| integers | https://github.com/purescript-lua/purescript-lua-integers | v6.1.1 |
| lazy | https://github.com/purescript-lua/purescript-lua-lazy | v7.0.0 |
| lua-ngx | https://github.com/purescript-lua/purescript-lua-ngx | v0.2.0 |
| numbers | https://github.com/purescript-lua/purescript-lua-numbers | v9.1.1 |
| partial | https://github.com/purescript-lua/purescript-lua-partial | v4.1.0 |
| prelude | https://github.com/purescript-lua/purescript-lua-prelude | v7.2.2 |
| refs | https://github.com/purescript-lua/purescript-lua-refs | v6.1.0 |
| safe-coerce | https://github.com/purescript-lua/purescript-lua-safe-coerce | v2.0.0 |
| st | https://github.com/purescript-lua/purescript-lua-st | v6.3.0 |
| strings | https://github.com/purescript-lua/purescript-lua-strings | v6.2.0 |
| unfoldable | https://github.com/purescript-lua/purescript-lua-unfoldable | v6.1.0 |
| unsafe-coerce | https://github.com/purescript-lua/purescript-lua-unsafe-coerce | v6.1.0 |

Every other package in the set is an unmodified PureScript package that needs no
Lua-specific FFI.

## Maintaining a fork

[`CONTRIBUTING.md`](CONTRIBUTING.md) is the practical canon: the toolchain, the
Lua 5.1 and FFI rules, CI, and the release process. The reasoning behind each
rule is recorded as an ADR under [`docs/adr/`](docs/adr/). Read the ADRs before a
decision that affects the whole set, and add one after making such a decision.