The ILLIXR application is kick-started through a tool called Runner
The Runner tool is responsible for
preparing the environment,
downloading required assets/code,
compiling each plugin,
launching the ILLIXR application.
Runner is necessary for our project since ILLIXR manages plugins and data that span
many locations and launch configurations.
A configuration (defined via a YAML file in
ILLIXR/configs/) specifies parameters
and plugins required to launch ILLIXR for a specific design/evaluation scenario.
Compilation and Usage
To run ILLIXR (from the root directory of the project) using
native launch configuration,
To drop into
command: gdb -q --args $cmd in the
action block of
configs/native.yaml, and use the same command.
To run ILLIXR with Monado,
The OpenXR application to run is defined in the
(a YAML object).
As introduced in the introduction to the ILLIXR build process, a Configuration
(or config) describes the key information needed to launch an ILLIXR application.
This section provides a detailed breakdown of the structure of a configuration file.
ILLIXR/configs/native.yaml for the
native action will be used as
the running example.
The first block in the config file contains a list of
plugin_group is a list of plugins.
plugin_groups: - plugin_group: - path: plugin1/ - path: plugin2/ - path: plugin3/ - path: plugin4/
This defines a list of plugins by their location,
Allowed paths will be described below.
plugin_groups get flattened and those plugins are initialized in order at runtime.
Several of the default plugins are order-sensitive.
The next block in the config defines the offline IMU data, camera data, and ground-truth data.
data: subpath: mav0 relative_to: archive_path: download_url: 'http://robotics.ethz.ch/~asl-datasets/ijrr_euroc_mav_dataset/vicon_room1/V1_02_medium/V1_02_medium.zip'
Next, we define the location of OBJ files for
Then, we define the Action to be taken for the configuration. Each action has a name, and can contain a number of member fields beyond this.
action: name: native command: gdb -q --args $cmd
native action supports an optional
In that argument
$cmd is replaced with the separated command-line arguments to run ILLIXR,
$quoted_cmd is replaced with a single string comprising all command-line arguments.
command argument also supports
$env_cmd, which interpret command-line argument
assignments in the form of
VARNAME=VALUE as environment variable mappings.
See the configuration glossary entry for more details about supported actions.
Finally, we support two compilation profiles:
opt, which compiles with
-O3 and disables debug prints and assertions,
dbg, which compiles with debug flags and enables debug prints and assertions.
!include other configuration files via pyyaml-include.
Consider separating the site-specific configuration options into its own file.
A path refers to a location of a resource. There are 5 ways of specifying a path:
Simple path: Either absolute or relative path in the native filesystem.
Git repo: A git repository.
- git_repo: https://github.com/user/repo.git version: master # branch name, SHA-256, or tag
Download URL: A resource downloaded from the internet.
- download_url: https://example.com/file.txt
Zip archive: A path that points within the contents of a zip archive. Note that
archive_pathis itself a path (recursive).
- archive_path: path/to/archive.zip - archive_path: download_url: https://example.com/file.zip
Complex path: A hard-coded path relative to another path (recursive). This is useful to specify a subdirectory of a git repository or zip archive.
- subpath: path/within/git_repo relative_to: git_repo: ... version: ...
Previously, we would have to specify which plugins to build and which to run separately, violating DRY principle.
Previously, configuration had to be hard-coded into the component source code, or passed as parsed/unparsed as strings in env-vars on a per-component basis. This gives us a consistent way to deal with all configurations.
Currently, plugins are specified by a path to the directory containing their source code and build system.
Each plugin should not have to know or care how the others are compiled. In the future, they may even be distributed separately, just as SOs. Therefore, each plugin needs its own build system.
Despite this per-plugin flexibility, building the 'default' set of ILLIXR plugins should be extremely easy.
It should be easy to build in parallel.
Always rebuild every time, so the binary is always "fresh." This is a great convenience when experimenting. However, this implies that rebuilding must be fast when not much has changed.
Make is the de facto standard for building C/C++ programs. GNU Make, and the makefile language begets no shortage of problems [1,2,3,4,5], but we choose Make for its tradeoff of between simplicity and functionality. What it lacks in functionality (compared to CMake, Ninja, scons, Bazel, Meson) it makes up for in simplicity. It's still the build system in which it is the easiest to invoke arbitrary commands in shell and the easiest to have a
common.mkincluded in each plugin. This decision to use Make should be revisited, when this project outgrows its ability, but for now, Make remains, in our judgement, the best tool for the job.