Skip to content

Commit

Permalink
deploy: 6f28b82
Browse files Browse the repository at this point in the history
  • Loading branch information
@lucapegolotti
lucapegolotti committed Oct 23, 2023
0 parents commit b86503d
Show file tree
Hide file tree
Showing 49 changed files with 6,375 additions and 0 deletions.
Empty file added .nojekyll
Empty file.
Binary file added bc_s.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added bdwn.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added closed.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
178 changes: 178 additions & 0 deletions containers.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>svExternals: Containers</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">svExternals
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Containers </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#autotoc_md0">How to use the Docker containers to build the external libraries</a><ul><li class="level2"><a href="#autotoc_md1">Tips on using containers</a><ul><li class="level3"><a href="#autotoc_md2">Docker images vs Docker containers</a></li>
<li class="level3"><a href="#autotoc_md3">Useful commands (to be run on the host)</a></li>
<li class="level3"><a href="#autotoc_md4">Creating an image out of a container and pushing to DockerHub</a></li>
</ul>
</li>
<li class="level2"><a href="#autotoc_md5">Use containers to run GitHub actions</a></li>
</ul>
</li>
<li class="level1"><a href="#autotoc_md6">Create new Docker images to build SimVascular externals</a><ul><li class="level2"><a href="#autotoc_md7">Notes on building Ubuntu images</a></li>
<li class="level2"><a href="#autotoc_md8">Notes on building MacOS images</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>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:</p><ol type="1">
<li>Ubuntu 20</li>
<li>Ubuntu 22</li>
<li>MacOS 12 (Monterey)</li>
<li>MacOS 13 (Ventura)</li>
</ol>
<h1><a class="anchor" id="autotoc_md0"></a>
How to use the Docker containers to build the external libraries</h1>
<ol type="1">
<li><em><b>Download the Docker client</b></em>: The Docker client can be simply downloaded from the <a href="https://www.docker.com/get-started/">official Docker website</a>.</li>
<li><em><b>Pull the image corresponding to the desired operating system</b></em>: The list of available images can be found on <a href="https://hub.docker.com/u/simvascular">DockerHub</a>. 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: ```console docker pull simvascular/ubuntu20:svexternals docker run -it &ndash;platform linux/amd64 simvascular/ubuntu20:svexternals ``<code> 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</code>&ndash;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.</li>
<li><p class="startli"><em><b>Clone the svExternals repository and run the scripts</b></em>: within a terminal in the container, run the following steps: ```console git clone <a href="https://github.com/SimVascular/svExternals.git">https://github.com/SimVascular/svExternals.git</a> cd svExternals bash build_all.sh ``` These sequence of commands will build and create install files for all the required externals.</p>
<p class="startli"><em><b>Note</b></em>: 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.</p>
</li>
</ol>
<h2><a class="anchor" id="autotoc_md1"></a>
Tips on using containers</h2>
<h3><a class="anchor" id="autotoc_md2"></a>
Docker images vs Docker containers</h3>
<p>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. </p>
<h3><a class="anchor" id="autotoc_md3"></a>
Useful commands (to be run on the host)</h3>
<ol type="1">
<li>The command <code>docker images</code> allows easily listing all the available images on a particular system.</li>
<li>When a container is created and running on a system, it is listed when launching <code>docker ps</code>. Note that, after exiting the container (for example, by typing <code>exit</code> within an Ubuntu terminal running in headless state, or closing the GUI of a MacOS docker container), the container is no longer visible using <code>docker ps</code>. It can instead be found using <code>docker ps -a</code>.</li>
<li>To attach a new terminal to a running container, one can use <code>docker exec -it {container.id} /bin/bash</code>, where <code>{container.id}</code> can be found by running <code>docker ps</code>.</li>
<li>In order to restart a closed container, one can use <code>docker start -ai {container.id}</code> </li>
</ol>
<h3><a class="anchor" id="autotoc_md4"></a>
Creating an image out of a container and pushing to DockerHub</h3>
<p>Containers can be used to create Docker images. To do so, run </p><div class="fragment"><div class="line">docker commit {container.id} {dockerhub.username}/&quot;tag&quot;</div>
</div><!-- fragment --><p> where <code>{container.id}</code> can be found by running <code>docker ps -a</code>, <code>{dockerhub.username}</code> should match the DockerHub account where the image will be pushed, and <code>tag</code> is a descriptor of the image. For SimVascular developers, this command could look something like this: </p><div class="fragment"><div class="line">docker commit {container.id} simvascular/ubuntu22:svexternals</div>
</div><!-- fragment --><p> Once the image is created, it can be pushed to DockerHub by running </p><div class="fragment"><div class="line">docker push {dockerhub.username}/&quot;tag&quot;</div>
</div><!-- fragment --><p><em><b>Note</b></em>: To be able to push with a particular DockerHub account credentials, the user first needs to login by typing <code>docker login</code>. </p>
<h2><a class="anchor" id="autotoc_md5"></a>
Use containers to run GitHub actions</h2>
<p>Our Docker image are configured to use GitHub actions. Each image contains a folder named <code>actions-runner</code> in the home directory. Running the <code>run.sh</code> 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 <a href="https://github.com/SimVascular/svExternals/tree/main/.github/workflows">here</a>. 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 <a href="https://docs.github.com/en/actions/using-workflows">here</a>.</p>
<h1><a class="anchor" id="autotoc_md6"></a>
Create new Docker images to build SimVascular externals</h1>
<p>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</p>
<h2><a class="anchor" id="autotoc_md7"></a>
Notes on building Ubuntu images</h2>
<p>Ubuntu images can be pulled from <a href="https://hub.docker.com/_/ubuntu">here</a> by running, for example </p><div class="fragment"><div class="line">docker pull ubuntu:20.04</div>
</div><!-- fragment --><p> Here are notes on (hopefully) installing everything needed to build the SimVascular externals:</p><ol type="1">
<li>Update package manager: <code>sudo apt-get update</code></li>
<li>Install development tools and common utilities:</li>
</ol>
<div class="fragment"><div class="line">sudo apt-get install -y gcc make automake git gperf bison flex \</div>
<div class="line">byacc nodejs rsync file build-essential llvm libpcre3 \</div>
<div class="line">libpcre3-dev automake python-dev-is-python3</div>
</div><!-- fragment --><ol type="1">
<li>Install X and graphics-related packages:</li>
</ol>
<div class="fragment"><div class="line">sudo apt-get install -y libfontconfig1-dev libfreetype6-dev \</div>
<div class="line">libx11-dev libx11-xcb-dev libxext-dev libxfixes-dev libxi-dev \</div>
<div class="line">libxrender-dev libxt-dev libgl1-mesa-dev libglu1-mesa-dev \</div>
<div class="line">libxcomposite-dev libxcursor-dev libxtst-dev libxkbcommon-dev \</div>
<div class="line">libxkbcommon-x11-dev libxcb1-dev libxcb-glx0-dev libxcb-keysyms1-dev \</div>
<div class="line">libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev libxcb-sync0-dev \</div>
<div class="line">libxcb-xfixes0-dev libxcb-shape0-dev libxcb-randr0-dev \</div>
<div class="line">libxcb-render-util0-dev libxcb-xinerama0-dev libxcb-xkb-dev \</div>
<div class="line">libxcb-util0-dev libdrm-dev libxdamage-dev libxrandr-dev</div>
</div><!-- fragment --><ol type="1">
<li>Other development libraries: <div class="fragment"><div class="line">sudo apt-get install -y libtiff4-dev libatspi2.0-dev \</div>
<div class="line">libdbus-1-dev libnss3-dev libssl-dev</div>
</div><!-- fragment --></li>
<li>For Qt WebEngine Python2 is required: <div class="fragment"><div class="line">sudo apt-get install -y python2</div>
<div class="line">sudo ln -s /bin/python2.7 /usr/bin/python</div>
</div><!-- fragment --></li>
</ol>
<h2><a class="anchor" id="autotoc_md8"></a>
Notes on building MacOS images</h2>
<p>MacOS Docker images are available <a href="https://hub.docker.com/r/sickcodes/docker-osx">here</a>. 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 <a href="https://github.com/sickcodes/Docker-OSX/discussions/199#discussioncomment-510813">this link</a> and <a href="https://christitus.com/docker-macos/">this link</a>. Once this is done, the SimVascular external libraries could be installed by following these directions:</p><ol type="1">
<li><a href="https://webkit.org/build-tools/">Install developer tools and Xcode</a>. Note: in order to compile the current version of Qt (5.15), Xcode 13 is or an earlier version is required. Starting from Ventura, Xcode 13 is technically not supported anymore, but, once downloaded, it can still be selected as default by using <code>xcode-select</code>. In particular, one needs to manually move Xcode to the <code>Applications</code> folder, and then run <code>sudo xcode-select -s /Applications/Xcode.app/Contents/Developer</code>.</li>
<li><a href="https://brew.sh">Install brew</a></li>
<li>Using brew, install <code>wget</code>, <code>git</code>, <code>automake</code>, <code>pcre</code>, <code>docbook-xsl</code>, <code>nodejs</code>, <code>rsync</code>, <code>openmp</code>.</li>
<li>Following <a href="https://stackoverflow.com/questions/19242275/re-error-illegal-byte-sequence-on-mac-os-x/19770395#19770395">this link</a>, add <div class="fragment"><div class="line">export LC_CTYPE=C </div>
<div class="line">export LANG=C</div>
</div><!-- fragment --> to avoid issues using <code>sed</code> in <code>build_python.sh</code></li>
<li>Compilation of Qt on MacOS must be on 1 core <a href="https://doc.qt.io/qt-5/macos-building.html">because of a race condition</a></li>
</ol>
<p>Additional steps may be required to build SimVascular in the container:</p><ol type="1">
<li>the compiler could complain that some system libraries (like <code>wchar.h</code>) cannot be found. In this case, one needs to create a symlink like <div class="fragment"><div class="line">sudo ln -s /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/* /usr/local/include/</div>
</div><!-- fragment --></li>
<li>Install <code>gcc</code> using brew.</li>
</ol>
<p>Good luck! </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
79 changes: 79 additions & 0 deletions dir_45ceaae7855647d8e15cc2abf65b95d9.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>svExternals: doc/pages Directory Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">svExternals
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="dir_e68e8157741866f444e17edd764ebbae.html">doc</a></li><li class="navelem"><a class="el" href="dir_45ceaae7855647d8e15cc2abf65b95d9.html">pages</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">pages Directory Reference</div> </div>
</div><!--header-->
<div class="contents">
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
Loading

0 comments on commit b86503d

Please sign in to comment.