The magic

To get a docker container I took the file Dockerfile and built an image called "myampersand", using the following command:

It took 45 minutes to build, but I got an image called myampersand in the docker repository on my laptop.

To see it work, I executed the newly created image on a little file in my working directory, hello.adl from the command line with the following command:

The same command in the Windows command line is:

Do you want to reproduce this?

The Ampersand repository contains a file, , that contains a recipe for building an Ampersand compiler and put it in your Ampersand repository. You need the following ingredients to run it:

1. A machine to run docker, for building your docker image with. I ran it on my MacBook.

2. Docker, which you need .

3. Docker needs least 5G of memory to build Ampersand, which is more than the standard 2G. I used to increase Docker's memory on my Macbook.

To run it, I cloned the Ampersand repository, into ~/Ampersand/, and built the image with:

It runs on my Mac for over half an hour, so some patience is required. If you don't have that patience, consider using the image from docker hub. It was built for your convenience.

The resulting docker image sits in the docker repository on you laptop (placed there when docker was installed).

So which steps does Docker take?

If you want a slightly different image (for reasons of your own), you may want to repeat this process yourself. For that purpose, let us walk through the different steps described in Dockerfile.

Let us discuss the steps one-by-one. (Please check the , just in case it is inconsistent with this documentation.) All of these steps happen automatically, as they are in the docker file.

The first statement states that the compiler is built on a well-defined Haskell image.

This building stage is called buildstage because we want to use a to obtain a small Ampersand image without excess-software.

We decide to work in the build-container from a working directory called /Ampersand.

Normally we want to generate Ampersand from the source code on GitHub. For this purpose we clone the Ampersand-repository into the (working directory in the) build environment.

In this case I wanted to build from a specific feature, so I checked it out.

Now everything is in place to compile Ampersand. Running stack install results in a full-fledged Ampersand compiler in /root/.local/bin. Mind you, this takes a while...

If we were to stop here, we get an image larger than 4GB. We can do better than that by starting over with a clean machine. So we introduce a second FROM-line in the Dockerfile which starts with a clean slate. We use an empty ubuntu machine (form some reason yet unknown, the smaller alpine image doesn't work)

Now we must copy the ampersand executable to /bin, from where we can run it as though it were a normal ubuntu-command. It is the only software we will copy into this image. (Haskell and the intermediate files are all absent). This results in an image that is slightly over 220MB.

When compiling, we will work in a directory called scripts. When using this container, we will volume-map this directory to the actual working directory that contains the ampersand-files we want to compile.

The program to be called when running the container is of course ampersand (residing in /bin/). If called without arguments it will use --verbose.

We followed docker's instruction for automated builds, to automate the workflow from committing to the Ampersand repository on Github to the corresponding docker image on Docker hub.

Manual builds

If you must do things on your own, you might want to reproduce parts of the builds.

The Dockerfile for the Ampersand compiler resides in the root of the Ampersand repository. So from the command line, if you are at the root of the Ampersand repository, you can call docker build . to create the image. See for more details.

The package.yaml file for the Ampersand compiler resides in the root of the Ampersand repository. So from the command line, if you are at the root of the Ampersand repository, you can call stack install to create the image. See for more details.

Requirement

The proper use of Docker ensures that your application will run on any location on the internet. Yet, when testing your application on your laptop, you may discover that your laptop is not configured as a domain on the internet. To run any Ampersand application locally without changes, your laptop must behave like an ordinary top-level domain: localhost. Your computer must believe that localhost is like com, or edu

The Ampersand compiler is a Haskell program built with stack. Stack is a build tool for Haskell projects such as Ampersand. We have automated the building process (using stack) for the following purposes:

1. to prevent mistakes such as dependency conflicts inside and between Haskell packages, for an uninterrupted compilation process (robust building);

2. to generate ampersand compilers for different platforms (platform independence);

3. to provide a reproducible and reliable build process to developers with diverse development tools, operating systems, and working environments (uniform building);

4. to allow for generating images for docker containers (containerization);

5. to accellerate the build process to increase the release frequency of Ampersand.

Installation

comes as part of , so there is no need to install Haskell separately.

The are pretty clear for the various platforms. Make sure you read the part about the STACK_ROOT environment variable.

To compile Ampersand you need a file , which sits in the Ampersand repository. Fetch it and put it in you working directory. From the command-line, call command stack install and after a while (go get coffee!) your ampersand compiler exists! NB: If you want to build Rieks' preprocessor as well, the magic spell is stack install --flag ampersand:buildAll