IHaskell

You can now try IHaskell directly in your browser at CoCalc or mybinder.org.

Alternatively, watch a talk and demo showing off IHaskell features.

IHaskell is a kernel for the Jupyter project, which allows you to use Haskell inside Jupyter frontends (including the console and notebook). It currently supports GHC 8, 8.2, 8.4, and 8.6. For GHC 7.10 support please use the GHC7 tag.

For a tour of some IHaskell features, check out the demo Notebook. More example notebooks are available on the wiki. The wiki also has more extensive documentation of IHaskell features.

Interactive In-Browser Notebook

Installation

Linux

Some prerequisites; adapt to your distribution.

sudo apt-get install -y python3-pip git libtinfo-dev libzmq3-dev libcairo2-dev libpango1.0-dev libmagic-dev libblas-dev liblapack-dev

Install stack, clone this repository, install Python requirements, install ihaskell, and install the Jupyter kernelspec with ihaskell.

These instructions assume you don't already have Stack or a Jupyter installation, please skip the relevant steps if this is not the case.

curl -sSL https://get.haskellstack.org/ | sh
git clone https://github.com/gibiansky/IHaskell
cd IHaskell
pip3 install -r requirements.txt
# stack install gtk2hs-buildtools # Disabled for now because gtk2hs-buildtools doesn't work with lts-13 yet
stack install --fast
ihaskell install --stack

If you want to use jupyterlab, you need to install the jupyterlab ihaskell extension to get syntax highlighting with:

jupyter labextension install jupyterlab-ihaskell

Run Jupyter.

stack exec jupyter -- notebook

Mac

You need to have Homebrew installed. If you do not have it yet run /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" in your terminal.

You also need the Xcode command line tools. You can install them by running xcode-select --install in the terminal and following the prompts.

These instructions assume you don't already have Stack or a Jupyter installation, please skip the relevant steps if this is not the case.

brew install python3 zeromq libmagic cairo pkg-config haskell-stack pango
git clone https://github.com/gibiansky/IHaskell
cd IHaskell
pip3 install -r requirements.txt
# stack install gtk2hs-buildtools # Disabled for now because gtk2hs-buildtools doesn't work with lts-13 yet
stack install --fast
ihaskell install --stack

If you have Homebrew installed to a custom location, you'd need to specify --extra-include-dirs ${HOMEBREW_PREFIX}/include --extra-lib-dir ${HOMEBREW_PREFIX}/lib to the stack command.

Run Jupyter.

stack exec jupyter -- notebook

Tested on macOS Sierra (10.12.6)

Windows

IHaskell does not support Windows, however it can be used on Windows 10 via Windows Subsystem for Linux (WSL). If WSL is not installed, follow the Installation Guide for Windows 10. The following assumes that Ubuntu is picked as the Linux distribution.

In the Ubuntu app, follow the steps above for Linux.

Jupyter Notebook is now ready to use. In the Ubuntu app, launch a Notebook Server, without opening the notebook in a browser:

jupyter notebook --no-browser

Returning to Windows 10, open a browser and copy and paste the URL output in the step above (the token will differ).

Or copy and paste one of these URLs:
     http://localhost:8888/?token=9ca8a725ddb1fdded176d9e0e675ba557ebb5fbef6c65fdf

Tested on Windows 10 (build 18362.175) with Ubuntu 18.04 on WSL

Alternatively, install Virtualbox, install Ubuntu or another Linux distribution, and proceed with the install instructions.

Docker

To quickly run a Jupyter notebook with the IHaskell kernel, try the Dockerfile in the top directory.

docker build -t ihaskell:latest .
docker run --rm -it -p8888:8888 ihaskell:latest

Or use the continously updated Docker image on Docker Hub.

docker run --rm -p 8888:8888 gibiansky/ihaskell

In order to mount your own local files into the Docker container use following command:

docker run --rm -p 8888:8888 -v "$PWD":/home/jovyan/work gibiansky/ihaskell

Be aware that the directory you're mounting must contain a stack.yaml file. A simple version would be:

resolver: lts-14.27
packages: []

It's recommended to use the same LTS version as the iHaskell image is using itself (as can be seen in its stack.yaml). This guarantees that stack doesn't have to first perform a lengthy installation of GHC before running your notebook.

Stack and Docker

IHaskell, being a Jupyter kernel, has a tall pile of compile-time and run-time dependencies provided by, traditionally, apt, pip, and npm. To develop IHaskell, we want to be able to isolate and control all of the dependencies. We can use Stack's Docker integration to install all of those runtime dependencies into an isolated environment.

The system library dependencies installed with apt will be isolated in the ihaskell-dev Docker image.
Dependencies installed by pip and npm will be isolated in the IHaskell/.stack-work subdirectory.
All Stack build products and installed binaries will be isolated in the IHaskell/.stack-work subdirectory.

The following stack --docker commands require a Docker image named ihaskell-dev, so build that image from the docker/Dockerfile with this command:

docker build -t ihaskell-dev docker

Install the ghc version specified by the Stack resolver.

stack --docker setup

Install Jupyter and all of its requirements.

stack --docker exec pip3 -- install jupyter

Build IHaskell and all of its packages.

stack --docker install

Direct IHaskell to register itself as a Jupyter kernel.

stack --docker exec ihaskell -- install --stack

Optionally, install JupyterLab and the IHaskell JupyterLab extension for syntax highlighting. See the ihaskell_labextension/README.md.

stack --docker exec pip3 -- install jupyterlab
stack --docker exec bash -- -c 'cd ihaskell_labextension;npm install;npm run build;jupyter labextension link .'

Run the Jupyter notebook, with security disabled for testing, listening on all interfaces.

stack --docker exec jupyter -- notebook --NotebookApp.token='' --no-browser --LabApp.ip=0.0.0.0 notebooks

Run JupyterLab (if you installed it), with security disabled for testing, listening on all interfaces.

stack --docker exec jupyter -- lab --NotebookApp.token='' --no-browser --LabApp.ip=0.0.0.0 notebooks

Everything in Stackage can be installed by stack --docker install.

To install a local package, add it to the stack.yaml file (See: "Where are my packages?" below). Install the package with stack, then restart jupyter.

# after adding details about mypackage to stack.yaml
stack --docker install mypackage

To cleanly delete the entire Stack Docker development environment:

docker image rm ihaskell-dev
stack clean --full

Nix

If you have the nix package manager installed, you can create an IHaskell notebook environment with one command. For example:

$ nix-build -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-20.03.tar.gz release.nix --argstr compiler ghc865 --arg packages "haskellPackages: [ haskellPackages.lens ]"
<result path>
$ <result path>/bin/ihaskell-notebook

It might take a while the first time, but subsequent builds will be much faster. You can use the https://ihaskell.cachix.org cache for prebuilt artifacts.

The IHaskell display modules are not loaded by default and have to be specified as additional packages:

$ nix-build -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-20.03.tar.gz release.nix --argstr compiler ghc865 --arg packages "haskellPackages: [ haskellPackages.ihaskell-blaze haskellPackages.ihaskell-charts ]"

For more examples of using IHaskell with Nix, see https://github.com/vaibhavsagar/notebooks.

Troubleshooting

Where are my packages? (IHaskell + Stack)

Stack manages separate environments for every package. By default your notebooks will only have access to a few packages that happen to be required for ihaskell. To make packages available add them to the stack.yaml in the ihaskell directory and run stack solver && stack install.

Packages should be added to the packages: section and can take the following form (reproduced here from the stack documentation). If you've already installed a package by stack install you can simply list its name even if it's local.

- package-name
- location: .
- location: dir1/dir2
- location: https://example.com/foo/bar/baz-0.0.2.tar.gz
- location: http://github.com/yesodweb/wai/archive/2f8a8e1b771829f4a8a77c0111352ce45a14c30f.zip
- location:
    git: git@github.com:commercialhaskell/stack.git
    commit: 6a86ee32e5b869a877151f74064572225e1a0398
- location:
    hg: https://example.com/hg/repo
    commit: da39a3ee5e6b4b0d3255bfef95601890afd80709

The kernel keeps dying (IHaskell + Stack)

The default instructions globally install IHaskell with support for only one version of GHC. If you've e.g. installed an lts-10 IHaskell and are using it with an lts-9 project the mismatch between GHC 8.2 and GHC 8.0 will cause this error. Stack also has the notion of a 'global project' located at ~/.stack/global-project/ and the stack.yaml for that project should be on the same LTS as the version of IHaskell installed to avoid this issue.

openFile: does not exist (Stack + Docker)

If you try to run a notebook with stack --docker and see an IHaskell kernel error that looks like this:

ihaskell: /opt/ghc/8.6.5/lib/ghc-8.6.5/settings: openFile: does not exist

Then delete your ~/.stack directory and start over.

bendo/IHaskell