To use GHCJS with stack, place a GHCJS version in the compiler field of stack.yaml. After this, some stack commands should work with GHCJS. In particular:
-
stack setupwill install GHCJS from source and boot it, which takes a long time. -
stack buildwill 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, whereEXECUTABLEis the name of your executable).
You can also build existing stack projects which target GHC, and instead build
them with GHCJS. For example: stack build --compiler ghcjs-0.2.0.9006020_ghc-7.10.3
There are advanced options for stack setup: --ghcjs-boot-options (one word at a time) and --[no-]ghcjs-boot-clean
which will pass your settings down to the ghcjs-boot. You will need to know exactly what you are doing with them.
Sidenote: If you receive a message like
The program 'ghcjs' version >=0.1 is required but the version of .../ghcjs could not be determined.,
then you may need to install a different version of node. See
issue #1496.
Please see the ghcjs-stack-dist repository for lts-8 and lts-9 configurations and refer to the README for common issues.
Support for > lts-9 snapshots (GHC 8.2 and above) is currently work in progress.
These versions of GHCJS were created by Marcin Tolysz, and were particularly crafted to include package versions which match those expected by particular stackage snapshots.
For ghcjs based on ghc-7.10.3 one could try:
resolver: lts-6.30
compiler: ghcjs-0.2.0.9006030_ghc-7.10.3
compiler-check: match-exact
setup-info:
ghcjs:
source:
ghcjs-0.2.0.9006030_ghc-7.10.3:
url: http://ghcjs.tolysz.org/lts-6.30-9006030.tar.gz
sha1: 2371e2ffe9e8781808b7a04313e6a0065b64ee51Or for the latest one based on ghc-8.0.1 (with more features):
resolver: lts-7.19
compiler: ghcjs-0.2.1.9007019_ghc-8.0.1
compiler-check: match-exact
setup-info:
ghcjs:
source:
ghcjs-0.2.1.9007019_ghc-8.0.1:
url: http://ghcjs.tolysz.org/ghc-8.0-2017-02-05-lts-7.19-9007019.tar.gz
sha1: d2cfc25f9cda32a25a87d9af68891b2186ee52f9The latter can be generated via: https://github.com/tolysz/prepare-ghcjs
the former is a bit more manual. Those bundles are only tested against the latest node-7.4.0.
In order to correctly boot and use ghcjs, one might need to install alex happy hscolour hsc2hs with the normal ghc.
Older resolvers:
If you do not use the same resolver, say, an older LTS snapshot, you will get some warnings like this:
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
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
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
...
These warnings can usually be safely ignored, but they do indicate a divergence between your snapshot's packages, and those that are being used to compile your project. You will normally get these warnings when using a GHCJS tarball that has not been packaged with a particular snapshot in mind.
If you want to build some older GHCJS packages, you may need to use the "old base" GHCJS. To do this, use the following compiler info:
compiler: ghcjs-0.1.0.20150924_ghc-7.10.2
compiler-check: match-exactIn order to use a GHCJS installed on your PATH, just add the following to your stack.yaml:
compiler: ghcjs-0.2.0_ghc-7.10.2(Or, ghcjs-0.1.0_ghc-7.10.2 if you are working with an older version)
This is particularly useful when you have built GHCJS from source.
For projects with both a server and client, the recommended project
organization is to put one or both of your stack.yaml files in
sub-directories. This way, you can use the current working directory to
specify whether you're working on the client or server. This will also allow
more straightforward editor tooling, once projects like ghc-mod and
haskell-ide-engine support GHCJS.
For example, here's what a script for building both client and server looks like:
#!/bin/bash
# Build the client
stack build --stack-yaml=client/stack.yaml
# Copy over the javascript
rm -f server/static/all.js
cp $(stack path --stack-yaml=client/stack.yaml --local-install-root)/bin/client.jsexe/all.js server/static/all.js
# Build the server
stack build --stack-yaml=server/stack.yamlYou can also put both the yaml files in the same directory, and have e.g.
ghcjs-stack.yaml, but this won't work well with editor integrations.
If you don't want to use a snapshot, instead place the ghcjs version in the resolver field of your stack.yaml. This is also necessary when using stack < 0.1.8.
If stack setup command fails to successfully complete with message: commitBuffer: invalid argument (invalid character), it means you have a locale problem.
This problem is not exclusive to GHCJS, and might happen also during other builds. A workaround is to set Language for non-Unicode programs to English (US).
For details see stack issue #1448.