git.iko.soy/rowtype-yoga/purescm
on release/v1.1.0 help sign in
rowtype-yoga/purescm/README.md
79 lines 2.8 kB history raw
1# purescm - Chez Scheme backend for PureScript
3## Installation
5```
6npm i --global purescm@next
7```
9## Usage
11The best way to use `purescm` is to use the [spago](https://github.com/purescript/spago) integration for alternative PureScript backends. In `spago.yaml` use the `backend` config like so:
13```
14workspace:
15 backend:
16 cmd: purescm
17 args:
18 - "build"
19```
21Then to compile your `purescm` project you can run:
23```
24spago build
25```
27This will produce output under `output/`. You can run the compiled program with:
29```
30purescm run
31```
33### Bundling
35Scheme files can be precompiled to a single Chez program:
37```
38purescm bundle-app
39```
41which generates a single file `output/main` which can be run with `scheme` or `petite`:
43```
44scheme --program output/main
45```
47## Vendored Dependencies
49In order to represent `Array` and record types in `purescm`, the backend has a runtime dependency on implementations of SRFI 214 (Flexvectors) and SRFI 125 (Intermediate hash tables). This is due in part to how [vectors](https://cisco.github.io/ChezScheme/csug9.5/objects.html#./objects:h5) are more like "arrays" than "array lists" and [hashtables](https://cisco.github.io/ChezScheme/csug9.5/objects.html#./objects:h12)' canonical accessor, `hashtable-ref`, takes a `default` value rather than raising an exception.
51We vendor [chez-srfi](https://github.com/arcfide/chez-srfi) using the following steps:
531. Clone `chez-srfi` at the project root.
552. Navigate to `chez-srfi` and run `./install.chezscheme.sps ../vendor`. This should produce an `srfi` folder inside of `vendor`.
573. Copy the desired SRFIs from `vendor/srfi` into `vendor/purs/runtime/srfi`. Make sure to also copy the SRFIs and other scheme files (e.g. the ones in the `private` folder) that they depend on. The [library-requirements](https://cisco.github.io/ChezScheme/csug9.5/libraries.html#./libraries:h7) function can aid in this process.
594. Modify the copied scheme files such that the library names align with the folder structure. [`sd`](https://github.com/chmln/sd) makes this easy!
60```sh
61sd "\(srfi " "(purs runtime srfi " vendor/purs/**/*.sls
62```
645. To verify, simply invoke the Scheme REPL:
65```scheme
66$ scheme --libdirs ./vendor:
67Chez Scheme Version 9.5.8
68Copyright 1984-2022 Cisco Systems, Inc.
70> (import (purs runtime srfi :125))
72```
74## Snapshots
76To run snapshots, run `npm run test`.
77To overwrite old snapshots with the latest output, run `npm run test -- -a "--accept"`.
78To add a new snapshot, create a file called `Snapshot.X.purs` where `X` indicates what is being tested.
79If a snapshot needs a dependency, install it by running `spago -x test-snapshots/spago.dhall install <packages...>`. The snapshots have their own `spago.dhall` file so as not to pollute the `purescm` binary with unneeded dependencies.