Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Compatibility layer


The compatibility layer of the EESSI project uses Gentoo Prefix to provide a known base on top of the host. This is the foundation we use to build our software stack on. An alternative would be the NixOS.

Installation and Configuration


The bootstrap process will need a clean environment with C and C++ compilers (the system version of gcc and g++ will do) as well as the make command. It also is very sensitive to the environment, so setup a user with unset CFFLAGS, CFLAGS, LDFLAGS, PKG_CONFIG_PATH and the always harmful LD_LIBRARY_PATH variables.

EESSI provides a Docker container for this, which can be run via Singularity.

Bootstrapping Gentoo Prefix

Gentoo Prefix provides a bootstrap script to build the prefix, see Gentoo Prefix Bootstrap. We forked this version and made some modifications. See issue #8 for more details.

You can run our version of the bootstrap script (see inside the Singularity container by executing:

singularity run docker://

If you want to run your own version of the bootstrap script, use:

singularity exec docker:// ./

Our version of the script allows you to pick a custom snapshot for the Portage tree. This can be done by setting CUSTOM_SNAPSHOT_URL to a URL that points to a directory, and setting CUSTOM_SNAPSHOT_URL to the name of a snapshot file (must be a bzip2 archive). For instance:

env CUSTOM_SNAPSHOT_URL="" CUSTOM_SNAPSHOT_VERSION="20201209" singularity run docker://

If you want to limit the supported/installed Python version(s), you can set the environment variable PYTHON_TARGETS before starting the bootstrap script. By only including a Python 3 version, you can prevent Python 2 from being installed, e.g.:

env PYTHON_TARGETS="python3_8" CUSTOM_SNAPSHOT_URL="" CUSTOM_SNAPSHOT_VERSION="20201126" singularity run docker://

After starting the bootstrap have a long coffee...

Once the bootstrap is completed, run the script to replace some paths with symlinks into the host OS:


In order to generate the right locales for your installation, see this item of the Gentoo Prefix FAQ.

Adding the EESSI overlay and packages

Additional packages are added in the EESSI overlay, which is based on ComputeCanada. You can add them manually or in an automated way by using Ansible, being Ansible the preferred way. Below you can find the two options explained.

Ansible playbook (Option 1)

The installation of the EESSI-specific parts can be automatically executed by running the Ansible playbook install.yml inside the folder ansible/playbooks. This playbook will install the EESSI Gentoo overlay and a set of packages, including Lmod and archspec. See the README in the ansible/playbooks folder for more details.

Manually (Option 2)

First, set EPREFIX to the path containing your Gentoo Prefix installation, and start the prefix:

export EPREFIX=/path/to/your/prefix

Ensure that the configuration directory for repositories exists:

mkdir -p ${EPREFIX}/etc/portage/repos.conf

If you used ${PYTHON_TARGETS} during the bootstrap, be sure to set it to the same value now, e.g.:

export PYTHON_TARGETS="python3_7"

Next, configure and sync the overlay:

emerge eselect-repository
eselect repository add eessi git
emerge --sync eessi

After synchronizing the overlay, add the EESSI package set(s) that you would like to install, e.g. for set 2020.08:

mkdir ${EPREFIX}/etc/portage/sets/
ln -s  ${EPREFIX}/var/db/repos/eessi/etc/portage/sets/2020.08 ${EPREFIX}/etc/portage/sets/

Finally, install the package set(s) defined at ${EPREFIX}/etc/portage/sets/, e.g.:

emerge @2020.08

Updating the Prefix


Updating packages can be as easy as

emerge --sync

If you run into problems, usually a newer ebuild is not suited to build in a prefix environment. Try to mask latest versions:

Create a mask file if not existing and mask newer versions from thin provisioning tools greater or equal to 0.7.6:

echo ">=sys-block/thin-provisioning-tools-0.7.6" >> ${EPREFIX}/etc/portage/package.mask


Updating Portage requires the kernel source which corresponds to your running kernel on the host. Emerge will detect it in /usr/src/linux.

Check your running kernel version with:

cat /proc/version
Linux version 4.20.0-1.el7.elrepo.x86_64 (mockbuild@Build64R7) 

On a Centos 7 host kernel sources are installed in /usr/src/kernels. Link /usr/src/linux to the appropiate kernel source after installation. Example for an elrepo kernel:

rpm -ivh kernel-ml-devel-4.20.0-1.el7.elrepo.x86_64.rpm
cd /usr/src ; ln -s kernels/4.20.0-1.el7.elrepo.x86_64 linux

When ready update Portage from the Prefix environment:

emerge --oneshot sys-apps/portage


The software in this repository is distributed under the terms of the GNU General Public License v2.0.

See LICENSE for more information.

SPDX-License-Identifier: GPL-2.0-only


Compatibility layer of the EESSI project







No releases published