hamishmack/ghcjs repository overview

⁠Quick Start

Get GHC 7.10.2 (MinGHC⁠ on Windows) and make sure that happy is installed. On linux you may need to install a package like libtinfo-dev to make the Haskell terminfo package work.

Now run the following to install the current snapshot of the master branch:

$ cabal install http://ghcjs.luite.com/master.tar.gz
$ ghcjs-boot

⁠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 patterns, asynchronous FFI and a JSVal FFI type,
• synchronous and asynchronous threads.

⁠Installation

GHCJS can be installed with GHC 7.10.2 or later.

⁠Requirements

• GHC 7.10.2 or higher
• Cabal 1.22.4 and cabal-install 1.22.3 or higher
• alex and happy
• node.js⁠ 0.10.28 or higher. GHCJS uses node.js for its build system and for running Template Haskell.

⁠Platform-specific preparation

⁠Linux / OS X

• A recent version of alex and happy need to be in your PATH
• git, make, cpp, autoreconf need to be in your PATH
• One of the dependencies is the terminfo Haskell package, which requires libtinfo. On Debian/Ubuntu this is provided by the libtinfo-dev package.

⁠Windows

• You need a shell that's capable of running autotools scripts (with git, make, cpp, autoreconf installed). See the GHCJS Wiki⁠ or the INSTALL.windows file for instructions for setting up MSYS2 for this.
• A recent version of alex and happy need to be in your PATH
• Virus scanners often interfere with configure scripts (permission denied errors), disable on-access scanning before running ghcjs-boot.

⁠Installation steps

⁠Install GHCJS (for compiler development)

Get ghcjs from Github and install it:

$ git clone https://github.com/ghcjs/ghcjs.git
$ cabal install ./ghcjs

⁠Build the Base Libraries

When installing from hackage, as shown above in the quickstart, the built base libraries are included in the source distribution package.

$ ghcjs-boot

Alternately, if you used the ghcjs⁠ repository to install.

• On the master branch.

$ git branch
* master
$ ghcjs-boot --dev

• On another branch, such as ghc-8.0, supply the branch names for repositories ghcjs-boot⁠ and shims⁠.

$ git branch
* ghc-8.0
$ ghcjs-boot --dev --ghcjs-boot-dev-branch ghc-8.0 --shims-dev-branch ghc-8.0

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!

⁠Stack support

stack⁠ supports setting up the GHCJS compiler and building your code. See stack's ghcjs documentation⁠ for information on how to do this.

⁠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.

⁠Differences from GHC

• Foreign Function Interface (FFI)⁠
• Marshalling between Haskell and Javascript⁠

⁠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⁠