{"id":40620255,"url":"https://github.com/incatools/odkrunner","last_synced_at":"2026-02-27T05:04:42.883Z","repository":{"id":220168963,"uuid":"750573981","full_name":"INCATools/odkrunner","owner":"INCATools","description":"A binary runner for the Ontology Development Kit","archived":false,"fork":false,"pushed_at":"2026-01-02T21:52:15.000Z","size":280,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-21T16:56:58.464Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/INCATools.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-30T22:29:21.000Z","updated_at":"2026-01-02T21:52:16.000Z","dependencies_parsed_at":"2024-06-25T22:57:38.864Z","dependency_job_id":"e0ec495e-717e-4861-99df-3be33f51daa0","html_url":"https://github.com/INCATools/odkrunner","commit_stats":null,"previous_names":["gouttegd/odkrunner","incatools/odkrunner"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/INCATools/odkrunner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/INCATools%2Fodkrunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/INCATools%2Fodkrunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/INCATools%2Fodkrunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/INCATools%2Fodkrunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/INCATools","download_url":"https://codeload.github.com/INCATools/odkrunner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/INCATools%2Fodkrunner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29885801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-21T06:50:23.416Z","updated_at":"2026-02-27T05:04:42.878Z","avatar_url":"https://github.com/INCATools.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"ODK Runner\n==========\n\nThis is a binary “runner” for the [Ontology Development\nKit](https://github.com/INCATools/ontology-development-kit) (ODK). That\nis, a program that can be used to invoke ODK workflows.\n\nThe runner is intended to become the recommended way of invoking ODK\nworkflows, superseding the `run.sh` and `run.bat` scripts that are\ninstalled within every ODK-managed repository.\n\nRationale for a binary runner\n-----------------------------\n* We need a single runner that works across all the platforms supported\n  by the ODK (GNU/Linux, macOS, Windows), instead of having a shell\n  script (`run.sh`) for GNU/Linux and macOS, and a batch script\n  (`run.bat`) for Windows. Having different runners for different\n  platforms makes it likely that they are not equivalent (this is\n  exactly the case currently: the batch script is way behind its shell\n  counterpart).\n* We need a runner that can be executed “out of the box” on the user’s\n  system, without requiring the installation of a runtime. This excludes\n  almost all scripting languages (certainly all the scripting languages\n  that I know of).\n\nSince the runner is a binary program, we need to provide different\nversions for each system, but at least those versions are compiled from\nthe same source code, so there is still only one runner to maintain even\nif there are three different binaries to provide.\n\nInstallation (pre-compiled binaries)\n------------------------------------\n(For an installation from source, see the ”Building” section below.)\n\nFrom the page of the [last\nrelease](https://github.com/INCATools/odkrunner/releases/latest),\ndownload the appropriate binary for your system:\n\n* `odkrun-linux` for GNU/Linux (x86_64);\n* `odkrun-macos` for macOS (x86_64 and arm64);\n* `odkrun.exe` for Windows (x86_64).\n\nFor the GNU/Linux and macOS versions, rename the downloaded binary to\n`odkrun`.\n\nPlace the binary in a directory that is listed in your system’s `PATH`\nvariable. Check that you can call `odkrun --version` in a terminal and\nget the program’s version message.\n\nInstallation only needs to be done once on any machine, regardless of\nhow many repositories are being managed by the ODK on that machine.\n\nTo upgrade to a newer version, simply download the binary for the newer\nversion as above and overwrite the old binary with it.\n\nUsage\n-----\nSimply run `odkrun` followed by any command you want to execute within a\nODK container. For example, assuming you are in the `src/ontology`\ndirectory of a ODK-managed repository and you want to refresh the\nimports of your ontology:\n\n```sh\n$ odkrun make refresh-imports\n```\n\nThe runner aims to offer (at least) the same features as the `run.sh`\nscript generated by the ODK, but more easily controllable using command\nline options rather than environment variables.\n\nFor example, to run the above command using the _ODKLite_ image rather\nthan the default _ODKFull_, with the `run.sh` script you would need to\ndo:\n\n```sh\n$ ODK_IMAGE=odklite sh run.sh make refresh-imports\n```\n\nwhereas with `odkrun`, you simply need to use the `-l` option:\n\n```sh\n$ odkrun -l make refresh-imports\n```\n\nSee the output of `odkrun --help` for a list of possible options.\n\nThe runner supports the shell-based configuration file used by the\nODK-generated `run.sh` wrapper script. If the current working directory\ncontains a file named `run.sh.conf`, the runner will attempt to parse\nthat file and use the options it may contain.\n\n### Seeding\n\nThe runner can also replace the `seed-via-docker.sh` script to\ninitialise a new ODK-managed repository:\n\n```sh\n$ odkrun seed -C my-config.yaml [other seeding options...]\n```\n\nODK backends\n------------\nOne benefit of the ODK Runner is to provide an abstraction layer between\nthe user and several “backends” that can provide the set of tools needed\nby the ODK workflows.\n\nCurrently, three different backends are supported: Docker images,\nSingularity images, and “native” environments.\n\n### Docker and Singularity\n\nDocker images are the primary backend, and the most well supported.\nThat’s what the ODK Runner will use by default. The exact image used may\nbe specified using the `--image` (`-i`) and `--tag` (`-t`) option; the\ndefault is `obolibrary/odkfull:latest`.\n\nSingularity images are in fact the same Docker images, but used through\nthe [Singularity container\nplatform](https://docs.sylabs.io/guides/latest/user-guide/#), rather\nthan Docker. Use the `--singularity` (`-s`) option to select this\nbackend. The image to use may be selected using the same `-i` and `-t`\noptions as for Docker.\n\n### Native backend\n\nNative environments are currently only supported on GNU/Linux and macOS\n– and they are unlikely to ever be supported on Windows. Briefly, a\nnative environment is in fact a plain directory (under\n`$XDG_DATA_HOME/ontology-development-kit/images` on GNU/Linux, or\n`$HOME/.local/share/ontology-development-kit/images` on macOS; that\ndirectory is hereafter called the _images directory_) that is expected\nto contain all the tools needed by ODK workflows (unless they are\nalready available on the system’s `PATH`), as well as all the\nnon-executable resources.\n\nUse the `--native` (`-n`) option to select the native backend. The value\nof the `--image` option is then interpreted as the name of a directory\nwithin the images directory. The `--tag` option is ignored with this\nbackend.\n\nThe ODK Runner can generate a shell script that can be used to\nautomatically set up a native environment. For example, the following\ncommand:\n\n```sh\n$ odkrun --image myenv setup-script \u003e setup.sh\n```\n\nwill create a script to setup a native environment in\n`$XDG_DATA_HOME/ontology-development-kit/images/myenv`.\n\nOnce the script has been executed, the newly created environment can be\ninvoked with:\n\n```sh\n$ odkrun --image myenv --native \u003cCOMMAND...\u003e\n```\n\n\nBuilding\n--------\n\n### Building for GNU/Linux\n\nGNU/Linux is the platform the runner is developed on, and building under\nand for that platform should be straightforward:\n\n```sh\n$ ./configure\n$ make\n```\n\nThe resulting `odkrun` binary can then be placed somewhere in the `PATH`\nand called directly. If you have administrative rights, you can directly\ninstall it in `/usr/local/bin` with:\n\n```sh\n# make install\n```\n\nThe `configure` accepts the usual Autotools options to change the\ninstallation directory as needed.\n\nIf building from a repository checkout rather than from a release\ntarball, you will need to generate the build system first. Make sure you\nhave the Autotools installed and run:\n\n```sh\n$ autoreconf -i\n```\n\nThen run the `configure` script as above.\n\n### Building for macOS\n\nUnder macOS, the procedure should be the same as under GNU/Linux. Make\nsure you have the _XCode Command Line Tools_ installed and run:\n\n```sh\n$ ./configure\n$ make\n```\n\nthen place the resulting `odkrun` binary somewhere in your `PATH`.\n\nBeware that by default, the compiler seems to generate binaries that can\nonly run on a version of macOS at least as high as the version on which\nthe compiler is currently running (e.g., a binary generated on macOS\n13.0 will not run on any macOS \u003c 13.0). Use the `--with-min-osx-version`\noption at configure time to change that:\n\n```sh\n$ ./configure --with-min-osx-version=11.0\n```\n\nBuilding for macOS under GNU/Linux has been tested to work with the\n[OSXCross](https://github.com/tpoechtrager/osxcross) cross-compiling\nenvironment. With OSXCross installed and its binaries in the `PATH`, the\nODK Runner may be built with:\n\n```sh\n$ ./configure --host=x86_64-apple-darwin21.4 CC=o64-clang\n$ make\n```\n\nAdjust the host tripled depending in the version of the macOS SDK you\nhave installed with OSXCross. Here, _darwin21.4_ is for the 12.3 SDK.\n\n### Building for Windows\n\nBuilding for Windows has only been tested under GNU/Linux using the\n[MinGW64](https://www.mingw-w64.org/) toolchain. With that toolchain\ninstalled and its binaries in the `PATH`, build the runner with:\n\n```sh\n$ ./configure --host=x86_64-w64-mingw32\n$ make\n```\n\nand place the resulting `odkrun.exe` binary somewhere in your `PATH`.\n\nCopying\n-------\nThe ODK Runner is free software, published under a 3-clause BSD license\nsimilar to the one used by the ODK itself. See the [COPYING](COPYING)\nfile.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincatools%2Fodkrunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fincatools%2Fodkrunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fincatools%2Fodkrunner/lists"}