From b4526aa9622d34f40b281dae5c25f649d5ea614c Mon Sep 17 00:00:00 2001 From: Yura Lazarev Date: Sun, 14 Jun 2026 19:34:36 +0200 Subject: [PATCH] docs: rework README for the PureScript Lua set, add a package nav table Replace the inherited generic package-sets README with one describing this set: the pslua backend, the upstream-ps // upstream-lua override, spago usage, and links to CONTRIBUTING.md and the ADRs. Add a navigation table of the Lua fork packages and their repo URLs. Docs only. --- README.md | 93 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 55 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 2a1b4de4..95e15ca4 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,62 @@ -# 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/Unisay/purescript-lua), the +PureScript-to-Lua compiler backend. It starts from the standard PureScript +package set and overrides the core libraries with 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) +The set is defined in [`src/packages.dhall`](src/packages.dhall) as +`upstream-ps // upstream-lua`. The right operand wins, so the Lua forks override +their JavaScript-targeting upstreams while every other package comes straight +from the PureScript set. -## 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. +Point the `upstream` import in your `packages.dhall` at a released set: -If you use a package manager based on package sets, that means that to install a package: - -1. The package must be in the package set -2. The package's dependencies and transitive dependencies must also be in the package set - -## 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"] -} +```dhall +let upstream = + https://github.com/Unisay/purescript-lua-package-sets/releases/download/psc-0.15.15-20260614-4/packages.dhall ``` -[spago]: https://github.com/purescript/spago +Releases are tagged `psc-0.15.15-[-N]`, and +[`latest-compatible-sets.json`](latest-compatible-sets.json) records the most +recent one. Move between versions with `spago upgrade-set --tag `. + +## Packages + +The Lua forks in this set. Each keeps its upstream PureScript API and ships a Lua +FFI in place of the JavaScript one. + +| Package | Repository | +|---|---| +| arrays | https://github.com/Unisay/purescript-lua-arrays | +| assert | https://github.com/Unisay/purescript-lua-assert | +| console | https://github.com/Unisay/purescript-lua-console | +| control | https://github.com/Unisay/purescript-lua-control | +| effect | https://github.com/Unisay/purescript-lua-effect | +| enums | https://github.com/Unisay/purescript-lua-enums | +| exceptions | https://github.com/Unisay/purescript-lua-exceptions | +| foldable-traversable | https://github.com/Unisay/purescript-lua-foldable-traversable | +| functions | https://github.com/Unisay/purescript-lua-functions | +| integers | https://github.com/Unisay/purescript-lua-integers | +| lazy | https://github.com/Unisay/purescript-lua-lazy | +| ngx | https://github.com/Unisay/purescript-lua-ngx | +| numbers | https://github.com/Unisay/purescript-lua-numbers | +| partial | https://github.com/Unisay/purescript-lua-partial | +| prelude | https://github.com/Unisay/purescript-lua-prelude | +| refs | https://github.com/Unisay/purescript-lua-refs | +| safe-coerce | https://github.com/Unisay/purescript-lua-safe-coerce | +| strings | https://github.com/Unisay/purescript-lua-strings | +| unfoldable | https://github.com/Unisay/purescript-lua-unfoldable | +| unsafe-coerce | https://github.com/Unisay/purescript-lua-unsafe-coerce | + +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/).