Skip to content

docs: rework README for the PureScript Lua set, add package nav table #2

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

Closed
Unisay wants to merge 1 commit into from
Closed

docs: rework README for the PureScript Lua set, add package nav table #2

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
93 changes: 55 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +9 to +12

## 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 <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-<YYYYMMDD>[-N]`, and
[`latest-compatible-sets.json`](latest-compatible-sets.json) records the most
recent one. Move between versions with `spago upgrade-set --tag <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 |
Comment on lines +49 to +52
| 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.
Comment on lines +55 to +56

## 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/).