Skip to content
Haskell to JavaScript compiler, based on GHC
Haskell JavaScript C Gnuplot Shell C++ Other
Branch: ghc-8.6
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
cbits add CRT_noglob.c required for ghcjs-pkg on windows Oct 20, 2013
ghc @ fd6cbea bump ghc submodule Jun 15, 2019
lib Fix references to Maybe constructors in rts.h Sep 6, 2019
src-bin support cabal-install >= 2.5 with ghcjs-boot May 6, 2019
.gitignore re-add accidentally overwritten recent changes from the 8.0 branch, m… Jan 10, 2018
Dockerfile run ghcjs-boot in the correct directory May 6, 2018
HACKING.markdown update travis and some docs Jul 23, 2014
LICENSE improve boot Jun 24, 2014
cabal.project fix stack build and add documentation/script for cabal new-build Jan 14, 2018
ghcjs.cabal bump some version bounds and switch to newer stack lts Aug 26, 2019
sources.txt Travis support Nov 11, 2012
stack.yaml bump some version bounds and switch to newer stack lts Aug 26, 2019



GHCJS is a Haskell to JavaScript compiler that uses the GHC API.

Quick Start - Developing GHCJS

Starting with GHC version 8.2, GHCJS depends on a customized ghc library, installed under the name ghc-api-ghcjs

getting and preparing the source tree

$ git clone --branch ghc-8.6
$ cd ghcjs
$ git submodule update --init --recursive
$ ./utils/

The ./utils/ script requires Bash version 4.0 or greater. If you are building on macOS, you will need the gnu version of tar. You can install this with brew install gnu-tar, which makes it accessible at gtar. The ./utils/ will automatically pick up on this.

building the compiler

GHCJS depends on a few "local" packages in the source tree. You can use cabal-install and stack to set up a build environment that contains these packages.

Cabal new-build
$ cabal new-configure
$ cabal new-build

Since cabal new-build does not install executables or wrapper scripts, we need to make them accessible by hand. You can do this by creating symlinks to the /utils/ script.

For example if the .bin directory is in your PATH:

$ cd .bin
$ ln -s ../utils/ ghcjs
$ ln -s ../utils/ ghcjs-pkg
$ ln -s ../utils/ haddock-ghcjs
$ ln -s ../utils/ hsc2hs-ghcjs
$ ln -s ../utils/ ghcjs-boot
Cabal sandbox

if you want to build with a Cabal sandbox, use the script to add the local packages.

$ ./utils/
$ cabal install

or you can use stack:

$ stack build

Booting GHCJS

The ghcjs-boot program builds the "boot" libraries, like ghc-prim, base and template-haskell with GHCJS. After booting, GHCJS can compile regular Haskell programs and packages.

$ ghcjs-boot

when invoked without arguments, ghcjs-boot will build the libraries from boot.tar (unless the current directory contains a boot.yaml file), installed in GHCJS' data directory (boot.tar is generated by the script and included in a source distribution).

Optionally you can point ghcjs-boot to a different location, like another boot.tar archive:

$ ghcjs-boot -s location/of/boot.tar

or a directory (must contain a boot.yaml file):

$ ghcjs-boot -s ./lib/boot

GHCJS executables and library paths

The GHCJS binaries like ghcjs and ghcjs-pkg are private executables and installed in the libexec directory. The Setup.hs script installs wrapper scripts in the bin directory to pass the library path to the binary.

Note: reinstalling GHCJS (cabal install) does not cause existing wrapper scripts to be overwritten. Remove the wrapper scripts first if you want a fresh copy.


.cabal-sandbox/bin/ghcjs might contain the following:

exec "$executablename" -B"$topdir" ${1+"$@"}

To change the library installation location (topdir), modify the scripts prior to running ghcjs-boot.

on Windows, an options file is used instead of a wrapper script

Generating a source distribution

if you work on boot packages that need some for an upstream library, make sure to update the patches in /lib/patches first

$ ./utils/

then regenerate the packages and the /data/boot.tar archive

$ ./utils/

and the source distribution archive

$ cabal sdist
You can’t perform that action at this time.