ODK Runner

This is a proof-of-concept for a binary “runner” tool for the Ontology Development Kit. That is, a program that could replace the run.sh and run.bat scripts used to invoke the ODK.

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.

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...]

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.