|
svExternals
|
The external libraries needed to build SimVascular rely on a large number of additional external packages. To facilitate reusability and making the maintaing process more straightforward, we developed some Docker containers based on different operating systems that are equipped with all the required dependencies. The containers that are currently available are based on the following operating systems:
Download the Docker client: The Docker client can be simply downloaded from the official Docker website.
Pull the image corresponding to the desired operating system: The list of available images can be found on DockerHub. The following steps show how to pull and run the Docker image for Ubuntu 20, but images for other operating systems can be downloaded in a similar way:
When dealing with Ubuntu images, this will open a terminal within the container. MacOS images, instead, will open a complete GUI running MacOS. In this case, the username and password are "ghrunner". Note that, on MacOS hosts running Apple Silicon, the --platform option enables the emulation of AMD64 instructions on Apple's proprietary chips. To get optimal performance on Apple Silicon, it is recommended to activate emulation using Rosetta 2 in the Docker client settings.
Clone the svExternals repository and run the scripts: within a terminal in the container, run the following steps:
These sequence of commands will build and create install files for all the required externals.
Note: our Docker images are configured to be used as GitHub runners. More information can be found in the "Use containers to run GitHub actions" section of this document.
Docker images are blueprints to create Docker containers. DockerHub is a service that allows users to host Docker images. By pulling a Docker image following step 2 in "How to use the Docker containers to build the external libraries", we can create new containers following the blueprint of the image.
docker images allows easily listing all the available images on a particular system.docker ps. Note that, after exiting the container (for example, by typing exit within an Ubuntu terminal running in headless state, or closing the GUI of a MacOS docker container), the container is no longer visible using docker ps. It can instead be found using docker ps -a.docker exec -it {container.id} /bin/bash, where {container.id} can be found by running docker ps.docker start -ai {container.id} Containers can be used to create Docker images. To do so, run
where {container.id} can be found by running docker ps -a, {dockerhub.username} should match the DockerHub account where the image will be pushed, and tag is a descriptor of the image. For SimVascular developers, this command could look something like this:
Once the image is created, it can be pushed to DockerHub by running
Note: To be able to push with a particular DockerHub account credentials, the user first needs to login by typing docker login.
Our Docker image are configured to use GitHub actions. Each image contains a folder named actions-runner in the home directory. Running the run.sh script within that directory makes the container listen to triggers from GitHub runners to launch the build of individual external libraries. The workflows for different operating system are implemented here. These workflows can be initiated directly from GitHub, or scheduled to be run at a certain time every day/week/month. Note that, if no container is listening to jobs coming from GitHub, the actions will fail. More information can be found here.
Creating new Docker images able to build the SimVascular external libraries can be a challenging process. Below are some sparse notes helpful to build Ubuntu and MacOS images. Hopefully, this could be used to create new Windows images in the future
Ubuntu images can be pulled from here by running, for example
Here are notes on (hopefully) installing everything needed to build the SimVascular externals:
sudo apt-get updateMacOS Docker images are available here. Compared to Linux, creating MacOS Docker containers our of these images is more involved, as they include a GUI and they requires installing the operating system from scratch. Moreover, it is recommended that the container be optimized for memory and efficiency by following this link and this link. Once this is done, the SimVascular external libraries could be installed by following these directions:
xcode-select. In particular, one needs to manually move Xcode to the Applications folder, and then run sudo xcode-select -s /Applications/Xcode.app/Contents/Developer.wget, git, cmake, automake, pcre, docbook-xsl, nodejs, rsync, openmp.bashrc.sh to avoid issues when using sed in build_python.shAdditional steps may be required to build SimVascular in the container:
wchar.h) cannot be found. In this case, one needs to create a symlink like gcc using brew.Good luck!
1.9.1