Scripts for building G+Smo Docker images

License	MPL 2.0
OS support	Linux, Windows, macOS
Docker pulls
Repository	mmoelle1/gismo
Status	completed
Developer	Matthias Möller
Maintainer	M.Moller@tudelft.nl
Last checked	21-01-2022

Table of content

1. Building Docker images
2. Prebuilt Docker images
3. Using Docker images

The run_build_docker.sh script provides an easy mechanism to create customized Docker images. We assume that you have installed Docker as described at Docker.com and can execute it with your user privileges. To build a customized Docker image run

./run_build_docker.sh os-compiler-cxx-buildtype[-cpu][-coeff_type][-index_type][-option0][-option1][...][:arch][/branch]

Disclaimer: Not all optional features are supported on all architectures and/or OS versions. Please report errors to the maintainer.

Disclaimer: Not all G+Smo extensions are supported on all architectures and/or OS versions. Please report errors to the maintainer. Private repositories are not accessible without a password.

The following Docker images are built automatically for commits to the G+Smo stable branch. Unspecified options are set to their default values:

• ubuntu20.04-gcc11-cxx11-release (GCC 11.x, C++11, Release mode with OpenMP)
• ubuntu20.04-clang11-cxx11-release (Clang 11.x, C++11, Release mode with OpenMP)

  The directory structure of the G+Smo library is as follows:

• $HOME/gismo: G+Smo main directory
• $HOME/gismo/build/bin: pre-compiled executables of example and tutorial applications
• $HOME/gismo/examples: source code of example and tutorial applications
• $HOME/gismo/filedata: parameterisations and other configuration files
• $HOME/gismo/src: source code of the G+Smo library

For a full description of the source code directory structure see the G+Smo Wiki.

To install Docker for your platform (Windows, macOS, Linux, cloud platforms, etc.) follow the instructions at docker.com.

Once you have Docker installed, you can run one of the above images by executing the following command:

docker run --rm -ti mmoelle1/gismo:ubuntu20.04-gcc11-cxx11-release

  You will be logged in under username gismo with standard password gismo. The --rm flag to the docker run command ensures that the container is removed upon termination. The directory $HOME/gismo/build/bin is added to the PATH variable so that example and tutorial applications can be run directly, e.g.:

docker run --rm -ti mmoelle1/gismo:ubuntu20.04-gcc11-cxx11-release geometry_example

  If you want to access data that is stored in a directory on your host computer from within your Docker container you need to mount (-v) the directory on your host computer when starting the Docker container. Assume that you want to make your current working directory on your host computer ($(pwd)) accessible under /home/gismo/shared in the docker container you need start the docker image as follows:

docker run --rm -ti -v $(pwd):/home/gismo/shared mmoelle1/gismo:ubuntu20.04-gcc11-cxx11-release

  It is also possible to mount a directory on your host computer to a directory of the Docker container and make it the working (-w) so that files generated inside the Docker container are accessible on your host computer:

docker run --rm -ti -w/home/gismo/shared -v $(pwd):/home/gismo/shared mmoelle1/gismo:ubuntu20.04-gcc11-cxx11-release

  A good starting point for learning the G+Smo library is to walk through the example and tutorial applications.

Open the file hooks/build and add a code block of the form

# gsKLShell extension
shopt -s extglob;
case "$IMAGE_NAME" in
    ?(*\-)noklshell?(\-*))
        if [[ ${GISMO_OPTIONAL} =~ "gsKLShell" ]]; then
            GISMO_OPTIONAL="${GISMO_OPTIONAL//gsKLShell/}"
        fi
        ;;
    ?(*\-)klshell?(\-*))
        if [[ ${GISMO_OPTIONAL} ]]; then
            GISMO_OPTIONAL="${GISMO_OPTIONAL};gsKLShell"
        else
            GISMO_OPTIONAL="gsKLShell"
        fi
        ;;
esac
shopt -u extglob;

That's it for most extensions.

If your extension requires certain options to be set make sure you add the above code snippet before the handling of these options, e.g., the gsTrilinos extension requires GISMO_WITH_MPI=ON and is therefore handled before.

# gsTrilinos extension (must be before checking for MPI support)
shopt -s extglob;
case "$IMAGE_NAME" in
    ?(*\-)notrilinos?(\-*))
        if [[ ${GISMO_OPTIONAL} =~ "gsTrilinos" ]]; then
            GISMO_OPTIONAL="${GISMO_OPTIONAL//gsTrilinos/}"
        fi
        ;;
    ?(*\-)trilinos?(\-*))
        if [[ ${GISMO_OPTIONAL} ]]; then
            GISMO_OPTIONAL="${GISMO_OPTIONAL};gsTrilinos"
        else
            GISMO_OPTIONAL="gsTrilinos"
        fi
        GISMO_WITH_MPI=ON
        ;;
esac
shopt -u extglob;

[...]

# MPI support
shopt -s extglob;
case "$IMAGE_NAME" in
    ?(*\-)nompi?(\-*))
        GISMO_WITH_MPI=OFF
        ;;
    ?(*\-)mpi?(\-*))
        GISMO_WITH_MPI=ON
        ;;
    *)
        if [ -z "$GISMO_WITH_MPI" ]; then
            GISMO_WITH_MPI=OFF
        fi
        ;;
esac
shopt -u extglob;

If your extension requires additional software packages (e.g., a Fortran compiler or additional libraries and header files) to be installed in the Docker image open the file ubuntu20.04/Dockerfile and add a code block of the form

# Install prerequisites for gsOpenCascade extension
RUN if [ ${GISMO_OPTIONAL} =~ "gsOpenCascade" ] ; then \
    apt-get update -q && \
    apt-get install --no-install-recommends -yq \
        libgl-dev \
        libxi-dev \
        libxmu-dev \
        mesa-common-dev \
        tk-dev && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*; \
    fi

Repeat the above step for all Dockerfiles.

Disclaimer: Different OSes might have different naming conventions for libraries and/or header files and even use different commands for installing software packages. Consult your OS documentation for further details.

The first step in adding a G+Smo option is similar to adding a G+Smo extension (see above). Open the file hooks/build and add a code block of the form

# MPI support
shopt -s extglob;
case "$IMAGE_NAME" in
    ?(*\-)nompi?(\-*))
        GISMO_WITH_MPI=OFF
        ;;
    ?(*\-)mpi?(\-*))
        GISMO_WITH_MPI=ON
        ;;
    *)
        if [ -z "$GISMO_WITH_MPI" ]; then
            GISMO_WITH_MPI=OFF
        fi
        ;;
esac
shopt -u extglob;

Next, open the file ubuntu20.04/Dockerfile and add a code block of the form

# GISMO_WITH_MPI          : {ON,OFF}
ARG GISMO_WITH_MPI=OFF

Additionally, add this flag to the cmake command at the bottom of the file

# Configure and build G+Smo library
RUN cd gismo    && \
    mkdir build && \
    cd build    && \
    CC=$CC \
    CXX=$CXX \
    FC=$FC \
    cmake .. \
        [...]
        -DGISMO_WITH_MPI=$GISMO_WITH_MPI \
        [...]
    make

Repeat the above step for all Dockerfiles.

Adding a new Docker image 'newimage' (replace with the desired name) requires some more work.

First, open the file run_build_docker.sh and add a code block of the form

?(*:)?(*\-)newimage?(\-*))
        (DOCKER_REPO="mmoelle1/gismo"
         DOCKERFILE="${BASE_DIR}/newimage/Dockerfile"
         source ${BASE_DIR}/newimage/hooks/build)
        ;;

Next, create the directory newimage and create a Dockerfile. We suggest to copy an existing Dockerfile, e.g., from ubuntu20.04 and update it to your needs.

Next, create a new directory newimage/hooks and create a link named build to the file hooks/build.

Finally, create a file _compiler_settings in the directory newimage/hooks with the following content (adapted to your needs):

#!/bin/bash
# hooks/_compiler_settings

# Compiler setting
shopt -s extglob;
case "$IMAGE_NAME" in

    # Clang
    
    ?(*\-)clang6.0?(\-*))
        CC=clang-6.0
        CXX=clang++-6.0
        ;;

    [...]

    # GCC

    ?(*\-)gcc7?(\-*))
        CC=gcc-7
        CXX=g++-7
        FC=gfortran-7
        ;;
    
    [...]
                      
    *)
        echo "[***] Unsupported compiler"
        exit 1
        ;;
esac
shopt -u extglob;

echo "[---] CC:                     ${CC}"
echo "[---] CXX:                    ${CXX}"
echo "[---] FC:                     ${FC}"

In summary, you should have created the following directory structure and files

newimage
|
+-- Dockerfile
|
+-- hooks
    |
    +-- _compiler_settings
    |
    +-- build -> ../../hooks/build