GHC whole program compiler project

The project consists of GHC-WPC and the corresponding External STG IR and tooling.

GHC-WPC is an extended GHC that exports the STG IR (.o_stgbin) for the compiled modules and linker metadata (.ghc_stgapp) at application link time.

This repo uses GHC-WPC via stack, so no worries, stack will download it and do the setup automatically, but only on x64 Debian9, Ubuntu 16.04-17.10. If you use macOS or Windows you have to compile GHC-WPC manually. See the developer instructions below.
However external-stg package compiles with vanilla GHC also.

Readings

External STG tools (Ext-STG)

gen-exe main compiler driver, it produces executable from .ghc_stgapp files.
gen-obj compiles STG IR files .o_stgbin to object code .o. (gen-exe calls it)
ext-stg CLI tool for external STG IR, it can pretty print .o_stgbin files.

Sample applications for GHC-WPC

There is a set of prepared applications in the ghc-wpc-sample-programs repository that you can compile easily to try out GHC-WPC. No special preparation needed if you use x64 Debian9, Ubuntu 16.04-17.10. It's only the regular stack based workflow.

Usage (user)

DOES NOT WORK AT THE MOMENT, NEW BINARY RELEASE OF GHC-WPC IS NEEDED

try the GHC-WPC developer usage way

The user of External STG is the one who does not alter the Ext-STG IR, instead just uses it via the external-stg package. I.e. external-stg-compiler is such an example.

Important: GHC-WPC has precompiled x64 Debian9, Ubuntu 16.04-17.10 binary release, so the install is straigtforward thanks to stack.

Clone this repository.

git clone git@github.com:grin-compiler/ghc-whole-program-compiler-project.git

Install the external stg tooling with the following commands:
```
(cd mod-pak ; stack install)
stack --stack-root `pwd`/.stack-root install
```
NOTE: the stack root is set to the local folder to prevent spamming the global stack sandbox.
Use gen-exe and ext-stg from terminal. (it should be in PATH due to the stack install)

Why?

to make it easy to develop new backends for GHC without extending Cabal with new targets
to facilitate compiler/PL research that needs real world programs to analyse
to allow whole program analysis (new insights might be adopted to incremental compilers)
to escape from GHC codebase to the mainstream Haskell UX/DX that allows to use any library
to allow program observation with arbitrary precision
to make it easy to focus on the compiler backend development without hacking GHC
to allow other compilers to target GHC/STG and the feature rich RTS

Usage (GHC-WPC developer)

If you change the External STG IR, then GHC-WPC must be recompiled. If you just would like to use Ext-STG IR in you project then please follow the (user) usage instructions.

Install (exact version):
- GHC 8.8.3
- happy 1.19.12
- alex 3.2.5

Clone this repository.

git clone --recursive git@github.com:grin-compiler/ghc-whole-program-compiler-project.git

Compile GHC-WPC in ./ghc-wpc folder with Hadrian (see ghc.dev for details). e.g.
```
./boot
./configure
hadrian/build-stack -j
```
Set the path to the local GHC-WPC build in the corresponding part of ./stack.yaml.
Install the external stg tooling with the following commands:
```
(cd mod-pak ; stack install)
stack --stack-root `pwd`/.stack-root install
```
NOTE: the stack root is set to the local folder to prevent spamming the global stack sandbox.
Use gen-exe and ext-stg from terminal. (it should be in PATH due to the stack install)

TODO

Ext-STG IR

export IdInfo

dmjio / ghc-whole-program-compiler-project