1. Installation

There are two main ways to install the Futhark compiler: using a precompiled tarball or compiling from source. Both methods are discussed below. If you are using Linux, see Installing Futhark on Linux. If you are using Windows, make sure to read Setting up Futhark on Windows. If you are using macOS, read Using OpenCL or CUDA.

Futhark is also available via Nix. If you are using Nix, simply install the futhark derivation from Nixpkgs.

1.1. Dependencies

The Linux binaries we distribute are statically linked and should not require any special libraries installed system-wide.

When building from source on Linux and macOS, you will need to have the gmp and tinfo libraries installed. These are pretty common, so you may already have them. On Debian-like systems (e.g. Ubuntu), use:

sudo apt install libtinfo-dev libgmp-dev

If you install Futhark via a package manager (e.g. Homebrew, Nix, or AUR), you shouldn’t need to worry about any of this.

Actually running the output of the Futhark compiler may require additional dependencies, for example an OpenCL library and GPU driver. See the documentation for the respective compiler backends.

1.2. Compiling from source

The recommended way to compile Futhark is with the Haskell Tool Stack, which handles dependencies and compilation of the Futhark compiler. You will therefore need to install the stack tool. Fortunately, the stack developers provide ample documentation about installing Stack on a multitude of operating systems. If you’re lucky, it may even be in your local package repository.

You can either retrieve a source release tarball or perform a checkout of our Git repository:

$ git clone https://github.com/diku-dk/futhark.git

This will create a directory futhark, which you must enter:

$ cd futhark

To get all the prerequisites for building the Futhark compiler (including, if necessary, the appropriate version of the Haskell compiler), run:

$ stack setup

Note that this will not install anything system-wide and will have no effect outside the Futhark build directory. Now you can run the following command to build the Futhark compiler, including all dependencies:

$ stack build

The Futhark compiler and its tools will now be built. This step typically requires at least 8GiB of memory. You may be able to build it on a smaller machine by adding the --fast option, although the resulting Futhark compiler binary will run slower.

After building, you can copy the binaries to your $HOME/.local/bin directory by running:

$ stack install

Note that this does not install the Futhark manual pages.

1.2.1. Compiling with cabal

You can also compile Futhark with cabal. If so, you must install an appropriate version of GHC (usually the newest) and cabal yourself, for example through your favourite package manager. On Linux, you can always use ghcup. Then clone the repository as listed above and run:

$ cabal update
$ cabal build

To install the Futhark binaries to a specific location, for example $HOME/.local/bin, run:

$ cabal install --install-method=copy  --overwrite-policy=always --installdir=$HOME/.local/bin/

1.3. Installing from a precompiled snapshot

Tarballs of binary releases can be found online, but are available only for very few platforms (as of this writing, only GNU/Linux on x86_64). See the enclosed README.md for installation instructions.

Furthermore, every day a program automatically clones the Git repository, builds the compiler, and packages a simple tarball containing the resulting binaries, built manpages, and a simple Makefile for installing. The implication is that these tarballs are not vetted in any way, nor more stable than Git HEAD at any particular moment in time. They are provided for users who wish to use the most recent code, but are unable to compile Futhark themselves.

We build such binary snapshots for the following operating systems:

Linux (x86_64)
futhark-nightly-linux-x86_64.tar.xz
Windows (x86_64)

futhark-nightly-windows-x86_64.zip

You will still likely need to make a C compiler (such as GCC) available on your own.

1.4. Installing Futhark on Linux

  • Linuxbrew is a distribution-agnostic package manager that contains a formula for Futhark. If Linuxbrew is installed (which does not require root access), installation is as easy as:

    $ brew install futhark
    

    Note that as of this writing, Linuxbrew is hampered by limited compute resources for building packages, so the Futhark version may be a bit behind.

  • Arch Linux users can use a futhark-nightly package or a regular futhark package.

  • NixOS users can install the futhark derivation.

Otherwise (or if the version in the package system is too old), your best bet is to install from source or use a tarball, as described above.

1.4.1. Using OpenCL or CUDA

If you wish to use futhark opencl or futhark cuda, you must have the OpenCL or CUDA libraries installed, respectively. Consult your favourite search engine for instructions on how to do this on your distribution. It is usually not terribly difficult if you already have working GPU drivers.

For OpenCL, note that there is a distinction between the general OpenCL host library (OpenCL.so) that Futhark links against, and the Installable Client Driver (ICD) that OpenCL uses to actually talk to the hardware. You will need both. Working display drivers for the GPU does not imply that an ICD has been installed - they are usually in a separate package. Consult your favourite search engine for details.

1.5. Installing Futhark on macOS

Futhark is available on Homebrew, and the latest release can be installed via:

$ brew install futhark

Or you can install the unreleased development version with:

$ brew install --HEAD futhark

This has to compile from source, so it takes a little while (20-30 minutes is common).

macOS ships with one OpenCL platform and various devices. One of these devices is always the CPU, which is not fully functional, and is never picked by Futhark by default. You can still select it manually with the usual mechanisms (see Executable Options), but it is unlikely to be able to run most Futhark programs. Depending on the system, there may also be one or more GPU devices, and Futhark will simply pick the first one as always. On multi-GPU MacBooks, this is is the low-power integrated GPU. It should work just fine, but you might have better performance if you use the dedicated GPU instead. On a Mac with an AMD GPU, this is done by passing -dAMD to the generated Futhark executable.

1.6. Setting up Futhark on Windows

The Futhark compiler itself is easily installed on Windows via stack (see above). If you are using the default Windows console, you may need to run chcp 65001 to make Unicode characters show up correctly.

It takes a little more work to make the OpenCL and PyOpenCL backends functional. This guide was last updated on the 5th of May 2016, and is for computers using 64-bit Windows along with CUDA 7.5 and Python 2.7 (Anaconda preferred).

Also Git for Windows is required for its Linux command line tools. If you have not marked the option to add them to path, there are instructions below how to do so. The GUI alternative to git, GitHub Desktop is optional and does not come with the required tools.

1.6.1. Setting up Futhark and OpenCL

  1. Clone the Futhark repository to your hard drive.

  2. Install Stack using the 64-bit installer. Compile the Futhark compiler as described in Installation.

  3. For editing environment variables it is strongly recommended that you install the Rapid Environment Editor

  4. For a Futhark compatible C/C++ compiler, that you will also need to install pyOpenCL later, install MingWpy. Do this using the pip install -i https://pypi.anaconda.org/carlkl/simple mingwpy command.

  5. Assuming you have the latest Anaconda distribution as your primary one, it will get installed to a place such as C:\Users\UserName\Anaconda2\share\mingwpy. The pip installation will not add its bin or include directories to path.

    To do so, open the Rapid Environment Editor and add C:\Users\UserName\Anaconda2\share\mingwpy\bin to the system-wide PATH variable.

    If you have other MingW or GCC distributions, make sure MingWpy takes priority by moving its entry above the other distributions. You can also change which Python distribution is the default one using the same trick should you need so.

    If have done so correctly, typing where gcc in the command prompt should list the aforementioned MingWpy installation at the top or show only it.

    To finish the installation, add the C:\Users\UserName\Anaconda2\share\mingwpy\include to the CPATH environment variable (note: not PATH). Create the variable if necessary.

  6. The header files and the .dll for OpenCL that comes with the CUDA 7.5 distribution also need to be installed into MingWpy. Go to C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v7.5\include and copy the CL directory into the MingWpy include directory.

    Next, go to C:\Program Files\NVIDIA Corporation\OpenCL and copy the OpenCL64.dll file into the MingWpy lib directory (it is next to include).

    The CUDA distribution also comes with the static OpenCL.lib, but trying to use that one instead of the OpenCL64.dll will cause programs compiled with futhark opencl to crash, so ignore it completely.

Now you should be able to compile with futhark opencl and run Futhark programs on the GPU.

Congratulations!

1.6.2. Setting up PyOpenCL

The following instructions are for how to setup the futhark-pyopencl backend.

First install Mako using pip install mako.

Also install PyPNG using pip install pypng (not stricly necessary, but some examples make use of it).

  1. Clone the PyOpenCL repository to your hard drive. Do this instead of downloading the zip, as the zip will not contain some of the other repositories it links to and you will end up with missing header files.

  2. If you have ignored the instructions and gotten Python 3.x instead 2.7, you will have to do some extra work.

    Edit .\pyopencl\compyte\ndarray\gen_elemwise.py and .\pyopencl\compyte\ndarray\test_gpu_ndarray.py and convert most Python 2.x style print statements to Python 3 syntax. Basically wrap print arguments in brackets “(..)” and ignore any lines containing StringIO >> operator.

    Otherwise just go to the next point.

  3. Go into the repo directory and from the command line execute python configure.py.

    Edit siteconf.py to following:

    CL_TRACE = false
    CL_ENABLE_GL = false
    CL_INC_DIR = ['c:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v7.5\\include']
    CL_LIB_DIR = ['C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v7.5\\lib\\x64']
    CL_LIBNAME = ['OpenCL']
    CXXFLAGS = ['-std=c++0x']
    LDFLAGS = []
    

    Run the following commands:

    > python setup.py build_ext --compiler=mingw32
    > python setup.py install
    

If everything went in order, pyOpenCL should be installed on your machine now.

  1. Lastly, Pygame needs to be installed. Again, not stricly necessary, but some examples make use of it. To do so on Windows, download pygame-1.9.2a0-cp27-none-win_amd64.whl from here. cp27 means Python 2.7 and win_amd64 means 64-bit Windows.

    Go to the directory you have downloaded the file and execute pip install pygame-1.9.2a0-cp27-none-win_amd64.whl from the command line.

Now you should be able to run the Game of Life example.

  1. To run the makefiles, first setup make by going to the bin directory of MingWpy and making a copy of mingw32-make.exe. Then simply rename mingw32-make Copy.exe or similar to make.exe. Now you will be able to run the makefiles.

    Also, if you have not selected to add the optional Linux command line tools to PATH during the Git for Windows installation, add the C:\Program Files\Git\usr\bin directory to PATH manually now.

  2. This guide has been written off memory, so if you are having difficulties - ask on the issues page. There might be errors in it.