Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/incatools/odkrunner

A binary runner for the Ontology Development Kit
https://github.com/incatools/odkrunner

Last synced: 4 months ago
JSON representation

A binary runner for the Ontology Development Kit

Awesome Lists containing this project

README 

          
ODK Runner

==========



This is a binary “runner” for the [Ontology Development

Kit](https://github.com/INCATools/ontology-development-kit) (ODK). That

is, a program that can be used to invoke ODK workflows.



The runner is intended to become the recommended way of invoking ODK

workflows, superseding the `run.sh` and `run.bat` scripts that are

installed within every ODK-managed repository.



Rationale for a binary runner

-----------------------------

* We need a single runner that works across all the platforms supported

  by the ODK (GNU/Linux, macOS, Windows), instead of having a shell

  script (`run.sh`) for GNU/Linux and macOS, and a batch script

  (`run.bat`) for Windows. Having different runners for different

  platforms makes it likely that they are not equivalent (this is

  exactly the case currently: the batch script is way behind its shell

  counterpart).

* We need a runner that can be executed “out of the box” on the user’s

  system, without requiring the installation of a runtime. This excludes

  almost all scripting languages (certainly all the scripting languages

  that I know of).



Since the runner is a binary program, we need to provide different

versions for each system, but at least those versions are compiled from

the same source code, so there is still only one runner to maintain even

if there are three different binaries to provide.



Installation (pre-compiled binaries)

------------------------------------

(For an installation from source, see the ”Building” section below.)



From the page of the [last

release](https://github.com/INCATools/odkrunner/releases/latest),

download the appropriate binary for your system:



* `odkrun-linux` for GNU/Linux (x86_64);

* `odkrun-macos` for macOS (x86_64 and arm64);

* `odkrun.exe` for Windows (x86_64).



For the GNU/Linux and macOS versions, rename the downloaded binary to

`odkrun`.



Place the binary in a directory that is listed in your system’s `PATH`

variable. Check that you can call `odkrun --version` in a terminal and

get the program’s version message.



Installation only needs to be done once on any machine, regardless of

how many repositories are being managed by the ODK on that machine.



To upgrade to a newer version, simply download the binary for the newer

version as above and overwrite the old binary with it.



Usage

-----

Simply run `odkrun` followed by any command you want to execute within a

ODK container. For example, assuming you are in the `src/ontology`

directory of a ODK-managed repository and you want to refresh the

imports of your ontology:



```sh

$ odkrun make refresh-imports

```



The runner aims to offer (at least) the same features as the `run.sh`

script generated by the ODK, but more easily controllable using command

line options rather than environment variables.



For example, to run the above command using the _ODKLite_ image rather

than the default _ODKFull_, with the `run.sh` script you would need to

do:



```sh

$ ODK_IMAGE=odklite sh run.sh make refresh-imports

```



whereas with `odkrun`, you simply need to use the `-l` option:



```sh

$ odkrun -l make refresh-imports

```



See the output of `odkrun --help` for a list of possible options.



The runner supports the shell-based configuration file used by the

ODK-generated `run.sh` wrapper script. If the current working directory

contains a file named `run.sh.conf`, the runner will attempt to parse

that file and use the options it may contain.



### Seeding



The runner can also replace the `seed-via-docker.sh` script to

initialise a new ODK-managed repository:



```sh

$ odkrun seed -C my-config.yaml [other seeding options...]

```



ODK backends

------------

One benefit of the ODK Runner is to provide an abstraction layer between

the user and several “backends” that can provide the set of tools needed

by the ODK workflows.



Currently, three different backends are supported: Docker images,

Singularity images, and “native” environments.



### Docker and Singularity



Docker images are the primary backend, and the most well supported.

That’s what the ODK Runner will use by default. The exact image used may

be specified using the `--image` (`-i`) and `--tag` (`-t`) option; the

default is `obolibrary/odkfull:latest`.



Singularity images are in fact the same Docker images, but used through

the [Singularity container

platform](https://docs.sylabs.io/guides/latest/user-guide/#), rather

than Docker. Use the `--singularity` (`-s`) option to select this

backend. The image to use may be selected using the same `-i` and `-t`

options as for Docker.



### Native backend



Native environments are currently only supported on GNU/Linux and macOS

– and they are unlikely to ever be supported on Windows. Briefly, a

native environment is in fact a plain directory (under

`$XDG_DATA_HOME/ontology-development-kit/images` on GNU/Linux, or

`$HOME/.local/share/ontology-development-kit/images` on macOS; that

directory is hereafter called the _images directory_) that is expected

to contain all the tools needed by ODK workflows (unless they are

already available on the system’s `PATH`), as well as all the

non-executable resources.



Use the `--native` (`-n`) option to select the native backend. The value

of the `--image` option is then interpreted as the name of a directory

within the images directory. The `--tag` option is ignored with this

backend.



The ODK Runner can generate a shell script that can be used to

automatically set up a native environment. For example, the following

command:



```sh

$ odkrun --image myenv setup-script > setup.sh

```



will create a script to setup a native environment in

`$XDG_DATA_HOME/ontology-development-kit/images/myenv`.



Once the script has been executed, the newly created environment can be

invoked with:



```sh

$ odkrun --image myenv --native 

```



Building

--------



### Building for GNU/Linux



GNU/Linux is the platform the runner is developed on, and building under

and for that platform should be straightforward:



```sh

$ ./configure

$ make

```



The resulting `odkrun` binary can then be placed somewhere in the `PATH`

and called directly. If you have administrative rights, you can directly

install it in `/usr/local/bin` with:



```sh

# make install

```



The `configure` accepts the usual Autotools options to change the

installation directory as needed.



If building from a repository checkout rather than from a release

tarball, you will need to generate the build system first. Make sure you

have the Autotools installed and run:



```sh

$ autoreconf -i

```



Then run the `configure` script as above.



### Building for macOS



Under macOS, the procedure should be the same as under GNU/Linux. Make

sure you have the _XCode Command Line Tools_ installed and run:



```sh

$ ./configure

$ make

```



then place the resulting `odkrun` binary somewhere in your `PATH`.



Beware that by default, the compiler seems to generate binaries that can

only run on a version of macOS at least as high as the version on which

the compiler is currently running (e.g., a binary generated on macOS

13.0 will not run on any macOS < 13.0). Use the `--with-min-osx-version`

option at configure time to change that:



```sh

$ ./configure --with-min-osx-version=11.0

```



Building for macOS under GNU/Linux has been tested to work with the

[OSXCross](https://github.com/tpoechtrager/osxcross) cross-compiling

environment. With OSXCross installed and its binaries in the `PATH`, the

ODK Runner may be built with:



```sh

$ ./configure --host=x86_64-apple-darwin21.4 CC=o64-clang

$ make

```



Adjust the host tripled depending in the version of the macOS SDK you

have installed with OSXCross. Here, _darwin21.4_ is for the 12.3 SDK.



### Building for Windows



Building for Windows has only been tested under GNU/Linux using the

[MinGW64](https://www.mingw-w64.org/) toolchain. With that toolchain

installed and its binaries in the `PATH`, build the runner with:



```sh

$ ./configure --host=x86_64-w64-mingw32

$ make

```



and place the resulting `odkrun.exe` binary somewhere in your `PATH`.



Copying

-------

The ODK Runner is free software, published under a 3-clause BSD license

similar to the one used by the ODK itself. See the [COPYING](COPYING)

file.