diff --git a/README.md b/README.md index 2a1b4de4..59079b71 100644 --- a/README.md +++ b/README.md @@ -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 `. - -## 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-[-N]`; +[`latest-compatible-sets.json`](latest-compatible-sets.json) records the most +recent one, and `spago upgrade-set --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.