|
| 1 | +<!DOCTYPE html> |
| 2 | +<html lang="en"> |
| 3 | +<head> |
| 4 | + <meta charset="UTF-8"> |
| 5 | + <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 6 | + <title>PANET: Photon and Neutron Experimental Techniques</title> |
| 7 | + <link rel="stylesheet" href="css/custom.css"> |
| 8 | + <link rel="icon" href="../logo/favicon.svg" type="image/svg"> |
| 9 | +</head> |
| 10 | +<body> |
| 11 | + <!-- Fixed Header --> |
| 12 | + <header id="fixed-header"> |
| 13 | + <div class="header-content"> |
| 14 | + <img id="panet_logo" alt="PaNET Logo" src="../logo/panet_logo.png" alt="PANET Logo" class="logo"> |
| 15 | + <h1 class="main-title">PANET: Photon and Neutron Experimental Techniques</h1> |
| 16 | + </div> |
| 17 | + </header> |
| 18 | + |
| 19 | + <div id="wrapper"> |
| 20 | + <div id="content"> |
| 21 | + <!-- Navigation will be visible initially, hidden when content is shown --> |
| 22 | + <nav id="navigation"> |
| 23 | + <h1>Documentation</h1> |
| 24 | + <ul class="nav-list"> |
| 25 | + <li><a href="index.html" class="nav-link" data-section="scope">Scope of PaNET</a></li> |
| 26 | + <li><a href="https://expands-eu.github.io/ExPaNDS-experimental-techniques-ontology/index-en.html" class="nav-link" data-section="scope">Browse PaNET</a></li> |
| 27 | + <li><a href="workflow.html" class="nav-link" data-section="git-workflow">Git Workflow</a></li> |
| 28 | + <li><a href="std_op_proc.html" class="nav-link" data-section="procedures">PaNET Standard Operating Procedures</a></li> |
| 29 | + <li><a href="build.html" class="nav-link-selected" data-section="environment">Build the Environment</a></li> |
| 30 | + <li><a href="release.html" class="nav-link" data-section="release">Make a Release</a></li> |
| 31 | + <!-- CHANGE> Removed PEPICO section from navigation --> |
| 32 | + </ul> |
| 33 | + </nav> |
| 34 | + |
| 35 | + <!-- Added scope sidebar that's visible by default alongside navigation --> |
| 36 | + <aside id="scope-sidebar"> |
| 37 | + <h1>PaNET build environment</h1> |
| 38 | + <div> |
| 39 | + <p>This repo contains tools for working with the Photon and Neutron Experimental Techniques (PaNET) <a href="https://github.com/ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology">github repository</a>. In particular when building the ontology file <code>PaNET.owl</code> from the various the input files.</p> |
| 40 | + |
| 41 | + <p>There are two main parts:</p> |
| 42 | + <ol> |
| 43 | + <li>A script, <code>build-panet</code>, that builds the PaNET. To work, it requires that various software packages are installed.</li> |
| 44 | + <li>A 'Dockerfile' script that describes how to build a container image that contains the <code>build-panet</code> script and the software packages it needs.</li> |
| 45 | + </ol> |
| 46 | + |
| 47 | + <h2>Using the script directly</h2> |
| 48 | + <p>The script 'build-panet' uses:</p> |
| 49 | + <ul class="md-itemization"> |
| 50 | + <li>the OBO Robot tool to build the PaNET ontology. Currently, this must be (precisely) v1.8.1: newer versions currently do not work. Note that robot requires that Java is installed.</li> |
| 51 | + <li>the <code>git</code> command. This is used to deduce a version number for the ontology. It is possible to avoid a dependency on git by specifying the version explicitly; however, this is not recommended.</li> |
| 52 | + </ul> |
| 53 | + |
| 54 | + <p>The script takes an optional argument: the path of a comma-separated values (csv) input file. The script will create a corresponding OWL file (in RDF/XML) in the same directory. The steps involved are:</p> |
| 55 | + <ol> |
| 56 | + <li>Generate an initial set of definitions from the CSV file.</li> |
| 57 | + <li>Run a reasoner to deduce more information about terms.</li> |
| 58 | + <li>Merge some (fairly constant) information about the ontology itself from the 'PaNET_metadata.ttl' file. This is located in the same directory as the CSV file.</li> |
| 59 | + </ol> |
| 60 | + |
| 61 | + <p>If no argument is given then the path <code>source/PaNET.csv</code> is used. This allows the script to be run from the base directory of the PaNET git repository.</p> |
| 62 | + |
| 63 | + <h2>Container image</h2> |
| 64 | + <p>A container image allows you to build the PaNET ontology without installing any dependencies. You only need the ability to run run a container. This may also be useful when automating, as CI/CD frameworks often support containers.</p> |
| 65 | + |
| 66 | + <p>In order to use the containerised PaNET-build script you must first get the container image onto you computer. There are two main ways of doing this: downloading it and building it yourself. These different approaches are described in the next two sections. If you are not sure, follow the instructions for downloading the image.</p> |
| 67 | + |
| 68 | + <p>Once you have the container image, you can use it to build the PaNET ontology. This is also described below.</p> |
| 69 | + |
| 70 | + <h3>Downloading the container image</h3> |
| 71 | + <p>A pre-build container image is available from this git repo's <a href="https://gitlab.desy.de/paul.millar/panet-build/container_registry">container registry</a>.</p> |
| 72 | + |
| 73 | + <p>Container images have the label <code>panet-build</code>, with the latest version being <code>panet-build:latest</code>. Therefore, the full reference for the latest container version is <code>gitlab.desy.de:5555/paul.millar/panet-build:latest</code>.</p> |
| 74 | + |
| 75 | + <p>Here is an example command showing how to download the latest image with docker:</p> |
| 76 | + <div class="md-tab-content"> |
| 77 | +docker pull gitlab.desy.de:5555/paul.millar/panet-build:latest |
| 78 | + </div> |
| 79 | + |
| 80 | + <p>Here is the equivalent command when using podman:</p> |
| 81 | + <div class="md-tab-content"> |
| 82 | +podman pull gitlab.desy.de:5555/paul.millar/panet-build:latest |
| 83 | + </div> |
| 84 | + |
| 85 | + <h3>Building the container image</h3> |
| 86 | + <p>This step is not necessary if you simply want to build the PaNET ontology. Rather, this information is useful if you wish to enhance the build process in a way that requires additional tools.</p> |
| 87 | + |
| 88 | + <p>This git repo contains the <code>Dockerfile</code> file that contains instructions for building the container image.</p> |
| 89 | + |
| 90 | + <p>The image may be built using a standard procedure. The following instructions show how to build the image and tag it <code>panet-build:latest</code> if the repo is the current directory.</p> |
| 91 | + |
| 92 | + <p>Here is the command for docker:</p> |
| 93 | + <div class="md-tab-content"> |
| 94 | +docker build . -t panet-build |
| 95 | + </div> |
| 96 | + |
| 97 | + <p>and for podman:</p> |
| 98 | + <div class="md-tab-content"> |
| 99 | +podman build . -t panet-build |
| 100 | + </div> |
| 101 | + |
| 102 | + <h3>Using the container image</h3> |
| 103 | + <p>By default, the container image expects the PaNET git repository to be available as the <code>/work</code> directory within the container image. Typically, this is achieved by "mounting" the PaNET git repository directory (on the host computer) at this location.</p> |
| 104 | + |
| 105 | + <p>This may be done by explicitly specifying the git location.</p> |
| 106 | + |
| 107 | + <p>A typical command with docker is:</p> |
| 108 | + <div class="md-tab-content"> |
| 109 | +docker run -v ~/git/PaNET/:/work --rm -it panet-build |
| 110 | + </div> |
| 111 | + |
| 112 | + <p>... or with podman:</p> |
| 113 | + <div class="md-tab-content"> |
| 114 | +podman run -v ~/git/PaNET/:/work --rm -it panet-build |
| 115 | + </div> |
| 116 | + |
| 117 | + <p>Often, the current directory is the PaNET git repository's base directory. In this case, then a somewhat simplified version of the command may be used.</p> |
| 118 | + |
| 119 | + <p>Here is a complete example, showing how to check out PaNET and use docker to build the ontology:</p> |
| 120 | + <div class="md-tab-content"> |
| 121 | +cd ~/git |
| 122 | +git clone https://github.com/ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology PaNET |
| 123 | +cd PaNET |
| 124 | +docker run -v $PWD/:/work --rm -it panet-build |
| 125 | + </div> |
| 126 | + |
| 127 | + <p>Here is the same example but using podman instead:</p> |
| 128 | + <div class="md-tab-content"> |
| 129 | +cd ~/git |
| 130 | +git clone https://github.com/ExPaNDS-eu/ExPaNDS-experimental-techniques-ontology PaNET |
| 131 | +cd PaNET |
| 132 | +podman run -v $PWD/:/work --rm -it panet-build |
| 133 | + </div> |
| 134 | + |
| 135 | + <p>The container accepts argument and passes these to the script. Therefore, it is possible to specify a target CSV file, similar to running the script directly. Note that the build process assumes that the ontology metadata is available as the file <code>PaNET_metadata.ttl</code> in the same directory as the source CSV file.</p> |
| 136 | + |
| 137 | + <p>Specifying an alternative source file may be useful, under some specific circumstances. However, the reader is encouraged to edit the <code>PaNET.csv</code> file directly and to use <code>git</code> to manage those changes.</p> |
| 138 | + </div> |
| 139 | + </aside> |
| 140 | + </div> |
| 141 | + </div> |
| 142 | +</body> |
| 143 | +</html> |
0 commit comments