[m-rev.] for review: Add Dockerfile to containerise mmc.

Sebastian Godelet sebastian.godelet at outlook.com
Fri Dec 28 03:26:26 AEDT 2018

For review by anone.

Add Dockerfile to containerise mmc.

Docker is a popular way to achieve cross-platform containerisation of applications.
Due to the rather lengthy compile time of the Mercury compiler itself, a way to package the compiler and all of its
dependencies is a desirable goal.

    Ignore README files, extras and everything from
    library/.gitignore and compiler/.gitignore, except for "configure".

    Dockerfile to create a containerised mmc, using a build script
    similar to INSTALL.git.

    Readme on how to use Docker with Mercury.

    Add link to README.Docker.

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 000000000..9f9294a95
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,112 @@
+# configure is not ignored, s.th. tarballs are supported
+# configure
+sicstus_compile sicstus_saved_state
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 000000000..8082ca410
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,84 @@
+# vim: ft=dockerfile tw=78 ts=4 sw=4 et
+# Supported Debian base images
+#   - stretch
+#   - jessie
+ARG MERCURY_DEV_PREFIX=/usr/local/mercury
+ARG MERCURY_DEV_TARGET=/var/tmp/mercury
+# first stage, base image
+RUN apt-get update && apt-get install -y \
+    apt-utils \
+    gcc \
+    libc-dev \
+    make \
+    pkg-config
+FROM base AS bootstrap
+ARG MERCURY_DL=http://dl.mercurylang.org/deb/
+# When using a source tarball, the source needs to be the top level directory,
+# e.g. `mercury-srcdist-rotd-2017-10-19'
+# inherited variables
+# install packaged compiler for bootstrapping
+# first install curl and lsb-realse so we can add the public key for downloading
+# Mercury packages.
+# Then add the remote repository and install all packages required for building
+# the Mercury compiler from source.
+RUN ( echo 'debconf debconf/frontend select Noninteractive' \
+        | debconf-set-selections ) && \
+    apt-get update && apt-get install -y \
+        bison \
+        flex \
+        $([ "$MERCURY_BOOTSTRAP" != "y" ] || \
+            echo autoconf automake curl gnupg2 lsb-release) && \
+    [ "${MERCURY_BOOTSTRAP}" != "y" ] || \
+        ( \
+            ( curl -fsSL https://paul.bone.id.au/paul.asc | apt-key add - ) && \
+            printf "%s $MERCURY_DL $(lsb_release -cs) main\n" "deb" "deb-src" \
+                > /etc/apt/sources.list.d/mercury.list && \
+            apt-get update && apt-get install -y \
+                mercury-rotd-recommended \
+        )
+# Checking for configure enables using
+#   - `docker build http://uri.to.bootstrapped.tar.gz',
+#   - `docker build https://github.com/:user:/mercury.git'
+#   - `docker build .'
+# Bootcheck fails currently: ( MAKE_DIR=`pwd`/scripts PATH=$PATH:`pwd`/scripts tools/bootcheck $MERCURY_DEV_PARALLEL ) \
+RUN ( \
+        ([ -f ./configure ] || ./prepare.sh) \
+        && ./configure \
+            --enable-libgrades=$MERCURY_DEV_LIBGRADES \
+            --with-default-grade=$MERCURY_DEFAULT_GRADE \
+            --prefix=$MERCURY_DEV_PREFIX \
+            --disable-symlinks \
+        && make PARALLEL=$MERCURY_DEV_PARALLEL install \
+        && rm -fR ${MERCURY_BOOTSTRAP_TARGET} \
+        && rm -fR $MERCURY_DEV_TARGET \
+    )
+FROM base AS compiler
diff --git a/README.Docker b/README.Docker
new file mode 100644
index 000000000..0635c32f4
--- /dev/null
+++ b/README.Docker
@@ -0,0 +1,69 @@
+This file documents using Mercury within a Docker container.
+Docker is a popular way to achieve cross-platform containerisation of applications.
+Due to the rather lengthy compile time of the Mercury compiler itself, a way to package the compiler and all of its
+dependencies is a desirable goal.
+Building Mercury
+The [Dockerfile](Dockerfile) is a [multi-staged](https://docs.docker.com/develop/develop-images/multistage-build/) Dockerfile.
+Currently there are three stages:
+  * base: Defines the basic image that all Mercury related containers should use.
+    Based on Debian (Apline Linux works as well but is not supported yet), it comes with gcc, make, pkg-config and libc headers.
+  * bootstrap: Installs the packaged ROTD compiler from the [download page](http://dl.mercurylang.org/deb/) and autotools.
+  * compiler: Uses the bootstrapped compiler to (auto-)configure Mercury and install it into a single-layered container.
+Used variables and arguments (for all stages):
+  - MERCURY_BOOTSTRAP: iff "y" then use a bootstrap mmc while building the compiler
+  - MERCURY_DEPEND_ARG: Currently defined as either jessie or stretch, to support building for different debian distributions.
+  - MERCURY_DL: Where to find the packaged ROTD compiler for Debian (see above).
+  - MERCURY_DEV_SOURCE: Source directory from where to obtain the compiler source code. Used to support building from tarballs (see below).
+  - MERCURY_DEV_TARGET: Temporary directory used as container working directory and for building the compiler.
+  - MERCURY_DEV_PREFIX: Default prefix to install Mercury to (```/usr/local/mercury```).
+  - MERUCRY_DEV_LIBGRADES and MERCURY_DEV_DEFAULT_GRADE: Grades to build, as defined by ```./configure --enable-libgrades```.
+    Default is asm_fast.gc.
+  - MERCURY_DEV_PARALLEL: Just as ```make PARALLEL=```, defaults to ```-j3```.
+Additionally building the ROTD tarball is supported via:
+docker build --build-arg MERCURY_BOOTSTRAP=n --build-arg MERCURY_DEV_SOURCE=mercury-srcdist-rotd-2018-12-24 http://dl.mercurylang.org/rotd/mercury-srcdist-rotd-2018-12-24.tar.gz
+Using containerised mmc on the host platform
+docker run --rm --mount type=bind,src="$(pwd)",dst=/var/tmp/mercury mercury-dev --linkage static -m hello
+The mount directive mounts the current working directory as a directory inside the container, where the containers default working directory is ```/var/tmp/mercury```, see MERCURY_DEV_TARGET.
+Another use case is to build entire libraries, such as [mercury-json](https://github.com/juliensf/mercury-json.git).
+For this the entry point has to be changed in case a Makefile or similar is used:
+git clone https://github.com/juliensf/mercury-json.git
+docker run --rm --mount type=bind,src="$(pwd)/mercury-json",dst=/var/tmp/mercury --entrypoint make mercury-dev:multi runtests
+Currently only static linkage is supported, as dynamic linkage searches the host for the Mercury runtime library, which might not be installed or not binary compatible.
+Similary, ```--use-grade-subdirs``` is not supported as it uses symbolic links that do not work properly on all platforms, but might work in a Linux only environment.
+Windows containers are not supported yet, but will be in the future. For this multi-arch files can be utilised.
+Note that using [Docker in comination with WSL](https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly) is tested and supported.
+Please follow all the instructions including changing the mount points from ```/mnt/c``` to ```/c``` only.
+Additionally only mounting shared volumes work, such as from the local user profile directory.
+As this is not yet established within the Mercury community, there are no best-pratices and conventions defined.
+It would be desirable to define a common location for installing libraries, a default set of grades available.
+Using Docker volumes to store both the runtime libraries and the extra/third party libraries would allow composition of complex build scripts.
+As an enhancement to the Mercury compiler special publish and pack targets could be designed that would allow isolated deployment and packaging of Mercury libraries and executables. This is already something [.NET Core](https://github.com/dotnet/core) supports via the [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-publish?tabs=netcore21).
diff --git a/README.md b/README.md
index 11465021e..0f7e17dc8 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@ Specific information is contained in individual README files:
   * Platforms
+      * [Docker](README.Docker)
       * [Linux](README.Linux)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20181227/da3b4996/attachment-0001.html>

More information about the reviews mailing list