-
Notifications
You must be signed in to change notification settings - Fork 186
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
GHC 8.2 support comes with a few other changes: - the separate shims and ghcjs-boot repositories have been folded into the main repository - GHCJS builds against a number of customized upstream packages (with different names)
- Loading branch information
Showing
229 changed files
with
45,688 additions
and
11,444 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| [submodule "ghc"] | ||
| path = ghc | ||
| url = https://github.com/ghcjs/ghc.git |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,160 +1,106 @@ | ||
| Quick Start | ||
| =========== | ||
|
|
||
| Get GHC 7.10.2 ([MinGHC](https://www.haskell.org/downloads/windows) 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](http://www-cs-students.stanford.edu/~tjw/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 | ||
| Introduction | ||
| ============ | ||
|
|
||
| GHCJS can be installed with GHC 7.10.2 or later. | ||
|
|
||
| ### Requirements | ||
|
|
||
| - GHC 7.10.2 or higher | ||
| - Cabal 2.0.0.2 and cabal-install 2.0.0.0 or higher | ||
| - alex and happy | ||
| - [node.js](http://nodejs.org) 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](https://github.com/ghcjs/ghcjs/wiki/Preparing-the-Windows-build-environment) 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 | ||
| GHCJS is a Haskell to JavaScript compiler that uses the GHC API. | ||
|
|
||
| #### Build the libraries | ||
| Quick Start - Developing GHCJS | ||
| ============================== | ||
|
|
||
| Use `ghcjs-boot` to build the base libraries for `GHCJS`: | ||
| Starting with GHC version 8.2, GHCJS depends on a customized `ghc` library, | ||
| installed under the name `ghc-api-ghcjs` | ||
|
|
||
| if you used the Git repository to install: | ||
| $ ghcjs-boot --dev | ||
| #### getting and preparing the source tree | ||
|
|
||
| if you are doing a development build from a different branch than `master`, you need to tell `ghcjs-boot` to use the correct branch of the `ghcjs-boot` and `shims` repositories: | ||
| $ ghcjs-boot --dev --ghcjs-boot-dev-branch somebranch --shims-dev-branch | ||
| ``` | ||
| $ git clone https://github.com/ghcjs/ghcjs.git | ||
| $ cd ghcjs | ||
| $ git submodule update --init | ||
| $ ./utils/boot | ||
| if you are installing from hackage, the ghcjs source distribution package already includes the correct libraries. run: | ||
| $ ghcjs-boot | ||
| if you want to build with a Cabal sandbox, use the `makeSandbox.sh` script | ||
| to add the local packages. | ||
| Some distros install node.js as `nodejs` instead of `node`. Add `--with-node nodejs` to the `ghcjs-boot` command in that case. | ||
| ``` | ||
| $ ./utils/makeSandbox.sh | ||
| $ cabal install | ||
| ``` | ||
| Usage | ||
| ===== | ||
| or you can use stack: | ||
| `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](http://nodejs.org/) and [SpiderMonkey jsshell](http://download.cdn.mozilla.net/pub/firefox/nightly/latest-mozilla-central/). | ||
| for example: | ||
| ``` | ||
| $ stack build | ||
| ``` | ||
| $ ghcjs -o helloWorld helloWorld.hs | ||
| $ node helloWorld.jsexe/all.js | ||
| Hello world! | ||
| #### Booting GHCJS | ||
| ### Stack support | ||
| 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. | ||
| [stack](https://github.com/commercialhaskell/stack) supports setting up the | ||
| GHCJS compiler and building your code. See stack's | ||
| [ghcjs documentation](https://docs.haskellstack.org/en/stable/ghcjs/) for | ||
| information on how to do this. | ||
| ``` | ||
| $ ghcjs-boot | ||
| ``` | ||
| ### Cabal support | ||
| 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 `makePackages.sh` script and included in a source distribution). | ||
| Use `cabal install --ghcjs packageName` to install a package | ||
| Optionally you can point `ghcjs-boot` to a different location, like another | ||
| `boot.tar` archive: | ||
| 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. | ||
| ``` | ||
| $ ghcjs-boot -s location/of/boot.tar | ||
| ``` | ||
| ### Sandboxes | ||
| or a directory (must contain a `boot.yaml` file): | ||
| You can use Cabal sandboxes with GHCJS, create a new sandbox with: | ||
| ``` | ||
| $ ghcjs-boot -s ./lib/boot | ||
| ``` | ||
| $ cabal sandbox init | ||
| ### GHCJS executables and library paths | ||
| Then you can just configure with `--ghcjs` to build with GHCJS inside the sandbox: | ||
| 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. | ||
| $ cabal install --ghcjs | ||
| 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. | ||
| If you also want to set GHCJS as the default compiler in the sandbox, run: | ||
| Example: | ||
| $ cabal sandbox init | ||
| $ echo "compiler: ghcjs" >> cabal.config | ||
| `.cabal-sandbox/bin/ghcjs` might contain the following: | ||
| 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. | ||
| ``` | ||
| #!/bin/sh | ||
| topdir="/home/luite/.ghcjs/x86_64-linux-8.2.0.1-8.2.2/ghcjs" | ||
| executablename="/home/luite/haskell/ghcjs-8.2/ghcjs/.cabal-sandbox/libexec/x86_64-linux-ghc-8.2.2/ghcjs-8.2.0.1/ghcjs" | ||
| exec "$executablename" -B"$topdir" ${1+"$@"} | ||
| ``` | ||
| ### Package databases | ||
| To change the library installation location (`topdir`), modify the scripts | ||
| prior to running `ghcjs-boot`. | ||
| Use `ghcjs-pkg` to manipulate the GHCJS package database | ||
| on Windows, an `options` file is used instead of a wrapper script | ||
| The package database and runtime files from the [shims](https://github.com/ghcjs/shims.git) 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. | ||
| #### Generating a source distribution | ||
| See [GHCJS introduction](http://weblog.luite.com/wordpress/?p=14) for more examples. | ||
| if you work on boot packages that need some for an upstream library, | ||
| make sure to update the patches in `/lib/patches` first | ||
| Hacking GHCJS | ||
| ============= | ||
| ``` | ||
| $ ./utils/updatePatches.sh | ||
| ``` | ||
| 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](HACKING.markdown) document | ||
| to get started. The [wiki](https://github.com/ghcjs/ghcjs/wiki) may also contain useful information. | ||
| then regenerate the packages and the `/data/boot.tar` archive | ||
| JSC and webkit | ||
| ============== | ||
| ``` | ||
| $ ./utils/makePackages.sh | ||
| ``` | ||
| 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](https://patch-tag.com/r/hamish/webkit) - Bindings for WebKitGTK+ that provide a low level DOM interface. | ||
| * [webkit-javascriptcore](https://github.com/gtk2hs/webkit-javascriptcore) - Low level bindings for JavaScriptCore | ||
| * [jsc](https://github.com/ghcjs/jsaddle) - Higher level interface for JavaScriptCore | ||
| and the source distribution archive | ||
| 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](https://github.com/ghcjs/ghcjs-examples/) | ||
| ``` | ||
| $ cabal sdist | ||
| ``` |
Oops, something went wrong.