ODK Runner

This is a binary “runner” for the 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, 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:

$ 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:

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

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

$ 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:

$ 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, 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:

$ 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:

$ odkrun --image myenv --native <COMMAND...>

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:

$ ./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:

# 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:

$ 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:

$ ./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:

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

Building for macOS under GNU/Linux has been tested to work with the OSXCross cross-compiling environment. With OSXCross installed and its binaries in the PATH, the ODK Runner may be built with:

$ ./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 toolchain. With that toolchain installed and its binaries in the PATH, build the runner with:

$ ./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 file.