Haskell to JavaScript compiler
GHCJS is a Haskell to JavaScript compiler that uses the GHC API.
GHCJS supports many modern Haskell features, including:
- All type system extensions supported by GHC
- Lightweight preemptive threading with blackholes, MVar, STM, asynchronous exceptions
- Weak references, CAF deallocation, StableName, StablePtr
- Unboxed arrays, emulated pointers
- Integer support through JSBN, 32 and 64 bit signed and unsigned arithmetic (
Word64
,Int32
etc.) - Cost-centres, stack traces
- Cabal support, GHCJS has its own package database
And some JavaScript-specific features:
- new JavaScriptFFI extension, with convenient import pattens, asynchronous FFI and a JSRef FFI type,
- synchronous and asynchronous threads.
Installation
First install GHC 7.8.2 or later and check with ghc --version
that it's the
compiler in your PATH
. Next, make sure that you have all the prerequisites for your platform.
Platform-specific requirements
Linux / OS X
- a recent version of
alex
andhappy
need to be in yourPATH
git
,make
,cpp
,autoreconf
,patch
need to be in yourPATH
- one of the dependencies is the
terminfo
Haskell package, which requireslibtinfo
. On Debian/Ubuntu this is provided by thelibtinfo-dev
package.
Windows
- virus scanners often interfere with configure scripts (permission denied errors),
disable on-access scanning before running
ghcjs-boot
. - no extra programs need to be installed,
ghcjs-boot
will download an archive (around 100MB) with the required programs.
Installation steps
If you use GHC 7.8, you need to update your Cabal
to version 1.22 to be able to use
GHCJS. GHC 7.10 already includes a compatible Cabal
version.
Note that you need a compatible Cabal
library in your GHC package database, just upgrading
the cabal-install
program is not enough. ghcjs-boot
will complain if it finds an incompatible
version.
Make sure that you're now running the updated cabal-install
, GHCJS
support must be listed under the
compiler flags:
$ cabal install --help
...
build files (default dist)
-g --ghc compile with GHC
--ghcjs compile with GHCJS
--nhc98 compile with NHC
...
Next, install ghcjs
and its ghcjs-prim
dependency:
$ git clone https://github.com/ghcjs/ghcjs-prim.git
$ git clone https://github.com/ghcjs/ghcjs.git
$ cabal install ./ghcjs ./ghcjs-prim
If cabal install ./ghcjs ./ghcjs-prim
fails because cabal cannot resolve dependencies, try adding --reorder-goals --max-backjumps=-1
. Sometimes the transformers
package causes problems, since GHC ships with an older version. Try --constraint=transformers==0.3.0.0
(or the version that came with your GHC) if the problem looks related to this package.
Build the base libraries for GHCJS
:
if you used the Git repository to install:
$ ghcjs-boot --dev
if you are using a package from hackage that includes the libraries:
$ ghcjs-boot
Some distros install node.js as nodejs
instead of node
. Add --with-node nodejs
to the ghcjs-boot
command in that case.
Usage
ghcjs
can be invoked with the same command line arguments as ghc
. The generated programs can be run directly from
the shell with Node.js and SpiderMonkey jsshell.
for example:
$ ghcjs -o helloWorld helloWorld.hs
$ node helloWorld.jsexe/all.js
Hello world!
Cabal support
Use cabal install --ghcjs packageName
to install a package
Most packages from hackage should work out of the box. The main exception is packages with foreign (non-Haskell) dependencies. For these packages a JavaScript implementation of the dependencies must be provided. If a package you want to use does not work, please create a ticket.
Sandboxes
You can use Cabal sandboxes with GHCJS, create a new sandbox with:
$ cabal sandbox init
Then you can just configure with --ghcjs
to build with GHCJS inside the sandbox:
$ cabal install --ghcjs
If you also want to set GHCJS as the default compiler in the sandbox, run:
$ cabal sandbox init
$ echo "compiler: ghcjs" >> cabal.config
Setting the default compiler to ghcjs
makes cabal sandbox exec
and cabal sandbox hc-pkg
use
GHCJS-specific settings. These commands do not know about the configure flags, so setting the default
compiler is the only way to make them use the correct settings for GHCJS.
Package databases
Use ghcjs-pkg
to manipulate the GHCJS package database
The package database and runtime files from the shims repository are kept in the
GHCJS application data directory, typically ~/.ghcjs/
. Remove this directory to reset your GHCJS installation, you
will need to run ghcjs-boot --init
again.
See GHCJS introduction for more examples.
Hacking GHCJS
If you want to hack on GHCJS, please join our friendly community on IRC at #ghcjs
on freenode (You're also
welcome if you only use the compiler or just want to chat about it!). Read the HACKING.markdown document
to get started. The wiki may also contain useful information.
JSC and webkit
Applications that use the following libraries should compile with GHCJS and run in a modern web browser and interface with DOM and JavaScript in the browser.
- webkit - Bindings for WebKitGTK+ that provide a low level DOM interface.
- webkit-javascriptcore - Low level bindings for JavaScriptCore
- jsc - Higher level interface for JavaScriptCore
You can use these libraries without GHCJS to build a native version of your application (it will use WebKitGTK+ to run without a browser). If you want to find out more about making GHCJS compatible Haskell applications check out the GHCJS Examples