Skip to content

Commit 2825b48

Browse files
mgsloanmgsloan
committed
Trim and clarify ghcjs.md
1 parent 6da953b commit 2825b48

1 file changed

Lines changed: 23 additions & 33 deletions

File tree

‎doc/ghcjs.md‎

Lines changed: 23 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
# GHCJS
22

3-
To use GHCJS with stack `>= 0.1.8`, place a GHCJS version in the [`compiler`](yaml_configuration.md#compiler) field of `stack.yaml`. After this, all stack commands should work with GHCJS, except for `ide`. In particular:
3+
To use GHCJS with stack, place a GHCJS version in the [`compiler`](yaml_configuration.md#compiler) field of `stack.yaml`. After this, all stack commands should work with GHCJS! In particular:
44

55
* `stack setup` will install GHCJS from source and boot it, which takes a long time.
6+
67
* `stack build` will compile your code to JavaScript. In particular, the generated code for an executable ends up in `$(stack path --local-install-root)/bin/EXECUTABLE.jsexe/all.js` (bash syntax, where `EXECUTABLE` is the name of your executable).
78

8-
You can also build existing stack projects which target GHC, and instead build them with GHCJS. For example: `stack build --compiler ghcjs-0.1.0.20150924_ghc-7.10.2`
9+
You can also build existing stack projects which target GHC, and instead build
10+
them with GHCJS. For example: `stack build --compiler ghcjs-0.2.0.9006020_ghc-7.10.3`
911

1012
Sidenote: If you receive a message like `The program 'ghcjs' version >=0.1 is
1113
required but the version of .../ghcjs could not be determined.`, then you may
@@ -14,11 +16,12 @@ need to install a different version of `node`. See
1416

1517
## Example Configurations
1618

17-
### Stack based repacks
19+
### Recent versions of GHCJS, repacked for stack
1820

19-
Upstream `ghcjs` bundles have some specific version of packages, and each version of stack resolver can potentially have a different version of those packages. We might ignore those differences and it usually works, but it might as well break if the package has some different semantics or we install the same package with 2 resolvers.
20-
One way of remedying this situation is to repack the bundle to use packages at versions from the resolver. This will allow using multiple resolvers for different projects without a clash.
21-
Using other ways of installing `ghcjs` might require purging `~/.ghcjs` or even `~/.stack` each time we use a different resolver.
21+
These versions of GHCJS were created by
22+
[Marcin Tolysz](https://github.com/tolysz), and were particularly crafted to
23+
include package versions which match those expected by particular stackage
24+
snapshots.
2225

2326
For `ghcjs` based on `ghc-7.10.3` one could try:
2427
```yaml
@@ -38,7 +41,7 @@ Or for the latest one based on `ghc-8.0.1` (with more features):
3841
```yaml
3942
resolver: lts-7.2
4043
compiler: ghcjs-0.2.1.9007002_ghc-8.0.1
41-
compiler-check: match-exact
44+
compiler-check: match-exact
4245
4346
setup-info:
4447
ghcjs:
@@ -58,38 +61,25 @@ Older resolvers:
5861
| lts-6.19 | http://ghcjs.tolysz.org/lts-6.19-9006019.tar.gz | ef4264d5a93b269ee4ec8f9d5139da030331d65a |
5962
| lts-6.18 | http://ghcjs.tolysz.org/lts-6.18-9006018.tar.gz | 3e9f345116c851349a5a551ffd94f7e0b74bfabb |
6063

64+
If you do not use the same resolver, say, an older LTS snapshot, you will get
65+
some warnings like this:
6166

62-
### GHCJS `master` (a.k.a. improved base)
63-
64-
To use the master branch, a.k.a improved base, add the following to your `stack.yaml`:
65-
66-
GHCJS compiled with GHC 7.10.3 LTS-5.12 (stack.yaml upgraded from stock GHCJS)
67-
```yaml
68-
compiler: ghcjs-0.2.0.20160414_ghc-7.10.3
69-
compiler-check: match-exact
70-
setup-info:
71-
ghcjs:
72-
source:
73-
ghcjs-0.2.0.20160414_ghc-7.10.3:
74-
url: https://s3.amazonaws.com/ghcjs/ghcjs-0.2.0.20160414_ghc-7.10.3.tar.gz
75-
sha1: 6d6f307503be9e94e0c96ef1308c7cf224d06be3
7667
```
77-
78-
GHCJS compiled with GHC 7.10.2 LTS-3.6 (stack.yaml that comes with GHCJS)
79-
```yaml
80-
compiler: ghcjs-0.2.0.20160414_ghc-7.10.2
81-
compiler-check: match-exact
82-
setup-info:
83-
ghcjs:
84-
source:
85-
ghcjs-0.2.0.20160414_ghc-7.10.2:
86-
url: https://s3.amazonaws.com/ghcjs/ghcjs-0.2.0.20160414_ghc-7.10.2.tar.gz
87-
sha1: f0a7243e781e27ebfe601eebaf5c57422007c142
68+
Ignoring that the GHCJS boot package "aeson" has a different version, 0.9.0.1, than the resolver's wanted version, 0.8.0.2
69+
Ignoring that the GHCJS boot package "attoparsec" has a different version, 0.13.0.1, than the resolver's wanted version, 0.12.1.6
70+
Ignoring that the GHCJS boot package "scientific" has a different version, 0.3.3.8, than the resolver's wanted version, 0.3.4.2
71+
...
8872
```
8973

74+
These warnings can usually be safely ignored, but they do indicate a divergence
75+
between your snapshot's packages, and those that are being used to compile your
76+
project. You will normally get these warnings when using a GHCJS tarball that
77+
has not been packaged with a particular snapshot in mind.
78+
9079
### GHCJS (old base)
9180

92-
You can use this resolver for GHCJS (old base) in your `stack.yaml`:
81+
If you want to build some older GHCJS packages, you may need to use the "old
82+
base" GHCJS. To do this, use the following compiler info:
9383

9484
```yaml
9585
compiler: ghcjs-0.1.0.20150924_ghc-7.10.2

0 commit comments

Comments
 (0)