asterius/docs/building.md

# Building guide

`asterius` is tested on Linux x64. Windows/macOS x64 may also work.

A pre-built Docker image is provided for your convenience.

## Using a pre-built Docker image

We build and test Docker images on CircleCI. They are pushed to `terrorjack/asterius`, the tags are git revisions. `terrorjack/asterius:latest` correspond to latest revision on `master`.

Put input program in a directory (e.g. `~/mirror`), then map the directory to a Docker volume:

```
terrorjack@ubuntu:~$ docker run -it -v ~/mirror:/mirror terrorjack/asterius
root@76bcb511663d:~# cd /mirror
root@76bcb511663d:/mirror# ahc-link --help
...
```

## Building custom `ghc`

`asterius` requires a forked `ghc` which can be found [here](https://github.com/TerrorJack/ghc/tree/asterius). We are looking forward to building `asterius` with vanilla `ghc-head` in the long run, but at the moment, we use our own `ghc` fork so it's easy to test radical changes on `ghc` itself.

The building guide of `ghc` can be found [here](https://ghc.haskell.org/trac/ghc/wiki/Building).

On Linux/macOS, a prebuilt `ghc` tarball is provided. It's already included in [`stack.yaml`](https://github.com/tweag/asterius/blob/master/stack.yaml). Note that the Windows bindist does not provide prof libs/haddock (due to AppVeyor build time restriction).

## Extra dependencies

Besides the custom `ghc`, these dependencies are also required:

- `cmake`/`make`/`g++`: For building in-tree [`binaryen`](https://github.com/WebAssembly/binaryen)
- `autoconf`: For booting `ghc-prim`/`base`
- `nodejs`: For running tests. Ensure the latest version is used, since we rely on some recent V8 experimental features (e.g. BigInt support)
- `stack`: Someday `cabal` may also work, no specific obstacles anyway.

## Building `asterius`

`stack build asterius`. That's it. Set `MAKEFLAGS=-j8` to pass flags to `make` for parallel building of `binaryen`.

After the dust settles, run `stack exec ahc-boot` to perform booting. Set the `ASTERIUS_DEBUG` environment variable to make `ahc-boot` print IRs to text files which are useful when debugging compiled code of standard libraries. Be aware that this flag slows down the booting process significantly!
Improve JSFFI & docs (+18 squashed commit) Squashed commit: [1ea1365] Improve documentation & re-add docs builder on circleci [cba4e06] Disable parallel building of binaryen to solve OOM on circleci [aad1174] Add Int/Word support for JSFFI; use unified JS_VAL variant for non-reference types [6dacf15] no message [d396479] no message [9e03ab4] no message [2ab2d53] no message [3dc2431] no message [50e4565] no message [76b3749] no message [6b885af] no message [14515a2] no message [522fd3d] no message [fcc48b3] Update to ghc-8.7.20180712 [701ab03] Implement jsffi wrapper functions; add Char support, add js_putchar example to jsffi test suite [ebd1a85] no message [b1da7e7] no message [844c831] no message 2018-07-12 12:43:27 +03:00			`# Building guide`

bytestring support & numerous bugfixes and impovements 2018-11-07 19:04:50 +03:00			`asterius` is tested on Linux x64. Windows/macOS x64 may also work.

			`A pre-built Docker image is provided for your convenience.`
Port readme & roadmap to docs pages 2018-04-05 10:25:24 +03:00
Improve JSFFI & docs (+18 squashed commit) Squashed commit: [1ea1365] Improve documentation & re-add docs builder on circleci [cba4e06] Disable parallel building of binaryen to solve OOM on circleci [aad1174] Add Int/Word support for JSFFI; use unified JS_VAL variant for non-reference types [6dacf15] no message [d396479] no message [9e03ab4] no message [2ab2d53] no message [3dc2431] no message [50e4565] no message [76b3749] no message [6b885af] no message [14515a2] no message [522fd3d] no message [fcc48b3] Update to ghc-8.7.20180712 [701ab03] Implement jsffi wrapper functions; add Char support, add js_putchar example to jsffi test suite [ebd1a85] no message [b1da7e7] no message [844c831] no message 2018-07-12 12:43:27 +03:00			`## Using a pre-built Docker image`

			We build and test Docker images on CircleCI. They are pushed to `terrorjack/asterius`, the tags are git revisions. `terrorjack/asterius:latest` correspond to latest revision on `master`.

			Put input program in a directory (e.g. `~/mirror`), then map the directory to a Docker volume:

			```
			`terrorjack@ubuntu:~$ docker run -it -v ~/mirror:/mirror terrorjack/asterius`
			`root@76bcb511663d:~# cd /mirror`
			`root@76bcb511663d:/mirror# ahc-link --help`
			`...`
			```

Port readme & roadmap to docs pages 2018-04-05 10:25:24 +03:00			## Building custom `ghc`

Add docs on ahc-link and links to blog posts; a ton of other housekeeping (+5 squashed commit) Squashed commit: [a1e989b] Keep CallImport variant in asterius ir to make the linker's life easier [cd38489] Update binaryen to 41ebb1b, remove CallImport variants [7e44c86] no message [2c0f2da] Fix breakage of jsffi stub c file compilation [2c7f914] Get rid of the GHCUnexported hack 2018-09-20 16:46:26 +03:00			`asterius` requires a forked `ghc` which can be found [here](https://github.com/TerrorJack/ghc/tree/asterius). We are looking forward to building `asterius` with vanilla `ghc-head` in the long run, but at the moment, we use our own `ghc` fork so it's easy to test radical changes on `ghc` itself.
Port readme & roadmap to docs pages 2018-04-05 10:25:24 +03:00
Fix binaryen marshalling for BinaryenSetFunctionTable (+2 squashed commit) Squashed commit: [6d4708d] no message [565c21b] no message 2018-09-02 03:37:44 +03:00			The building guide of `ghc` can be found [here](https://ghc.haskell.org/trac/ghc/wiki/Building).
Port readme & roadmap to docs pages 2018-04-05 10:25:24 +03:00
bytestring support & numerous bugfixes and impovements 2018-11-07 19:04:50 +03:00			On Linux/macOS, a prebuilt `ghc` tarball is provided. It's already included in [`stack.yaml`](https://github.com/tweag/asterius/blob/master/stack.yaml). Note that the Windows bindist does not provide prof libs/haddock (due to AppVeyor build time restriction).
Port readme & roadmap to docs pages 2018-04-05 10:25:24 +03:00
			`## Extra dependencies`

			Besides the custom `ghc`, these dependencies are also required:

Add docs on ahc-link and links to blog posts; a ton of other housekeeping (+5 squashed commit) Squashed commit: [a1e989b] Keep CallImport variant in asterius ir to make the linker's life easier [cd38489] Update binaryen to 41ebb1b, remove CallImport variants [7e44c86] no message [2c0f2da] Fix breakage of jsffi stub c file compilation [2c7f914] Get rid of the GHCUnexported hack 2018-09-20 16:46:26 +03:00			- `cmake`/`make`/`g++`: For building in-tree [`binaryen`](https://github.com/WebAssembly/binaryen)
			- `autoconf`: For booting `ghc-prim`/`base`
			- `nodejs`: For running tests. Ensure the latest version is used, since we rely on some recent V8 experimental features (e.g. BigInt support)
			- `stack`: Someday `cabal` may also work, no specific obstacles anyway.
Port readme & roadmap to docs pages 2018-04-05 10:25:24 +03:00
			## Building `asterius`

Implement & document the remote monad EDSL to write wasm in Haskell (+3 squashed commit) Squashed commit: [6504e82] Implement remote monad style EDSL for WebAssembly & use it to refactor most of builtin functions [82c7048] Field test [d958724] Start work on a shallow EDSL for hand-written WebAssembly code in Haskell 2018-07-29 03:46:00 +03:00			`stack build asterius`. That's it. Set `MAKEFLAGS=-j8` to pass flags to `make` for parallel building of `binaryen`.
Port readme & roadmap to docs pages 2018-04-05 10:25:24 +03:00
Add docs on ahc-link and links to blog posts; a ton of other housekeeping (+5 squashed commit) Squashed commit: [a1e989b] Keep CallImport variant in asterius ir to make the linker's life easier [cd38489] Update binaryen to 41ebb1b, remove CallImport variants [7e44c86] no message [2c0f2da] Fix breakage of jsffi stub c file compilation [2c7f914] Get rid of the GHCUnexported hack 2018-09-20 16:46:26 +03:00			After the dust settles, run `stack exec ahc-boot` to perform booting. Set the `ASTERIUS_DEBUG` environment variable to make `ahc-boot` print IRs to text files which are useful when debugging compiled code of standard libraries. Be aware that this flag slows down the booting process significantly!