Skip to content

Getting Started

These instructions have been tested with Ubuntu 18.04 and 20.04.

ILLIXR Runtime without Monado

  1. Clone the repository:

    git clone --recursive --branch v2-latest https://github.com/ILLIXR/ILLIXR

    Note for ILLIXR versions older than v2.2.0:

    Update the submodules. Submodules are git repositories inside a git repository that need to be pulled down separately:

    git submodule update --init --recursive

  2. Install dependencies:

    ./install_deps.sh [--jobs <integer>]

    This script installs some Ubuntu/Debian packages and builds several dependencies from source. Without any arguments, the script will print the help message, and proceed using default values. To change the number of threads/tasks to use for building, specify using the --jobs argument. Other available options can be inspected using the --help flag.

  3. Inspect configs/native.yaml.

    The schema definition is in runner/config_schema.yaml. For more details on the runner and the config files, see Building ILLIXR.

  4. Build and run ILLIXR without Monado:

    ./runner.sh configs/native.yaml

    If you are running ILLIXR without a graphical environment, try ILLIXR headlessly using Xvfb:

    ./runner.sh configs/headless.yaml

  5. To clean up after building, run:

    ./runner.sh configs/clean.yaml

    Or simply:

    ./clean.sh

ILLIXR Runtime with Monado

ILLIXR leverages Monado, an open-source implementation of OpenXR, to support a wide range of OpenXR client applications. Because of a low-level driver issue, Monado only supports Ubuntu 18.04+.

  1. Compile and run:

    ./runner.sh configs/monado.yaml

ILLIXR under Virtualization

ILLIXR can be run inside a QEMU-KVM image. Check out the instructions here.

Next Steps

Try browsing the source for the runtime and provided plugins. The source code is divided into components in the following directories:

  • ILLIXR/runtime/: A directory holding the implementation for loading and interfacing plugins. This directory contains Spindle.

  • ILLIXR/common/: A directory holding resources and utilities available globally to all plugins. Most plugins symlink this directory into theirs. This directory contains the interfaces for Switchboard and Phonebook.

  • ILLIXR/<plugin_dir>/: A unique directory for each plugin. Most of the core XR functionality is implemented via plugins. See Default Components for more details.

If you edit any of the source files, the runner will detect and rebuild the respective binary the next time it runs. If you want to add your own plugin, see Writing Your Plugin.

Otherwise, proceed to the next section, Building ILLIXR.