Skip to content

Getting Started

ILLIXR is configured and built via CMake. The CMake system checks for required dependencies, builds each requested plugin, builds the main ILLIXR binary, and (optionally) installs these components.

ILLIXR currently builds on Linux and Windows systems, and has been tested on the following configurations:

  • Ubuntu
    • 22.04
    • 24.04
  • Fedora1
    • 38+
  • Windows2
    • 11
  • Android

Other versions of these operating systems may work, but will likely require some manual installation of dependencies. For other Linux distributions (e.g. RHEL) it will require significant manual installation of dependencies as many are not available in the distribution repos. The instructions below are a generalized version.

Building ILLIXR

Clone the repository

git clone https://github.com/ILLIXR/ILLIXR --single-branch
This will clone only the default branch, if you want all branches then remove the --single-branch flag.

Install dependencies

There are two levels of dependencies in ILLIXR: those that are required for any type of build, and those that are required only for specific plugins.

Select your operating system and version

ILLIXR may compile with other versions of the above operating systems, but some of the necessary prerequisite packages are not supplied by the OS repos and will need to be compiled by hand. You should be able to use the package and cmake commands for other versions of the same OS (other than the missing packages) to compile ILLIXR. RHEL is not supported at this time as many of the prerequisite packages are not natively available. You will also need to have a C++ compiler installed as well as a generator (make, ninja, etc.) and CMake 3.24 or newer (installation is OS dependent). We recommend the clang compiler, as some plugin dependencies require it to build.

Currently the Windows build has been tested using Microsoft Visual Studio. Most of the dependencies will automatically install using vcpkg, but there are a few you will need to manually install beforehand:

You will need to change one of the settings in Visual Studio, otherwise the CMake generation will fail. Under Tools, open the Options item. Then select CMake in the left hand panel. There should be an option titled 'CMake configuration file', select 'Never use CMake Presets'.

It is also possible to use CLion as the IDE, but it needs to be configured to use vcpkg and still requires the installation of Visual Studio.

To build ILLIXR for Android platforms you will need a recent version of Android Studio. ILLIXR is known to build for the Quest 3 headset with:

  • Android NDK, version 27.2.12479018
  • Android SDK, version 13.0 (API 33)

Other combinations may work as well, depending on your Android device. The Eigen libraries (v 3.4.1) will need to be available on the host Linux of Windows system.

For Android we provide some of the dependencies as precompiled libraries for the 4 most common architectures. To download them run the following:

cd your repo location
git submodule init
git submodule update
cd android_libraries/third_party

Then run prepare.sh or prepare.bat (Linux and Windows host OS)

This imports the android_libraries submodule and expands its contents.

Pick the ILLIXR plugins you want to use

Include virtualization support:
See ILLIXR Under Virtualization for details.

Use the following to install the dependencies for the selected plugins:



























The following plugins are available for Android:


    

    For the Android platform any plugins being used have to be manually selected in a few files.
    

      

    • CMakeLists.txt: Near line 186, for any plugin you wish to use set the corresponding USE_ variable to ON. This
  ensures they will be configured and built.
      • 

    • src/CMakeLists.txt: In the target_link_libraries(native-activity call comment/uncomment the plugin list to
  match what you selected above. This ensures that all libraries are properly linked, this is an Android specific
  requirement.
      • 

    • src/main.cpp: Change the contents of const std::vector<std::string> plugins to reflect your choice above. Since
  Android programs cannot be run with command line arguments, this code replaces the command line capabilities of
  Linux and Windows.
      • 

    

    

    

    


    

    Build command
    

    Some ILLIXR plugins rely on code that falls under the GNU General Public License (GPL) v3.0
or GNU Lesser General Public License (LGPL) v2.1. If you do not wish to build
these codes you can select to exclude them below (or add -DNO_GPL=ON or -DNO_LGPL=ON to your cmake command line, NO_LGPL=ON implies
the same for NO_GPL).
    

    No GPL code
    
No LGPL code
    

    If you are using a Conda environment to build, be sure to add your Conda prefix path to your CMake arguments.
    

    

    

    

    -DCMAKE_PREFIX_PATH=$CONDA_PREFIX

    

    

    

    -DCMAKE_PREFIX_PATH=%CONDA_PREFIX%

    

    

    

    


    

    

    

    

    Use the following to build and install ILLIXR. You can specify the install location by giving the path to CMAKE_INSTALL_PREFIX.
If you want the default install path then do not add the option to the command line.
    

    

    Warning
    

    If your install prefix requires sudo privileges then you will need to run both the build and install under sudo (this is due to the way cmake builds and installs some of the pre-packaged dependencies during the build phase).
    

    

    
    
    
    

    

    Common CMake command line arguments (always prepend with a -D):
    

      

    • CMAKE_INSTALL_PREFIX
   The root path to install the libraries and binary to. This defaults to /usr/local.
      • 

    • CMAKE_BUILD_TYPE
   The build type to do: Debug, Release, RelWithDebInfo
      • 

    • YAML_FILE
   The profile file of plugins to build and install. The default is None, meaning plugins should be specified individually on the command line.
      • 

    • USE_<PLUGIN_NAME>=ON
   Build the specifically named plugin (e.g -DUSE_TIMEWARP_VK=ON to build the timewarp_vk plugin). Any number of plugins can be specified on the command line in this fashion.
      • 

    • BUILD_DOCS
   Set to ON to enable building the documentation.
      • 

    

    

    

    To configure and build in Visual Studio, you will need to edit some configuration files:open the CMakeSettings.json file, or create one if it does not exist. Double clicking the file from the Solution Explorer will open it in an input mode, rather then a raw file. You will want to make sure the following entries are set:
    

      

    • CMakePresets.json: edit the CMAKE_TOOLCHAIN_FILE entry to point to your vcpkg toolchain file, you may have to look around for it (e.g. D:/Program Files/Microsoft Visual Studio/2022/Community/VC/vcpkg/scripts/buildsystems/vcpkg.cmake)
      • 

    • CMakeSettings.json:
        

      • If you are using the offload_rendering_server plugin, edit the CMake command arguments entry, changing the -DVIDEO_CODEC_SDK_PATH argument to point to your NVIDIA video codec SDK installation.
        • 

      • If you want to use a profile file of plugins to specify the plugins to build, specify -DYAML_FILE=<profile file> (e.g., -DYAML_FILE=profiles/native_timewarp_vk.yaml)
        • 

      • If you want to specify the individual plugins to build add a flag for each one (e.g -DUSE_TIMEWARP_VK=ON to build the timewarp_vk plugin). Any number of plugins can be specified on the command line in this fashion.
        • 

      

      • 

    • launch/*.bat: These scripts are used to specify environment variables when launching ILLIXR. They can be used when launching from within Visual Studio by selecting the appropriate configuration from the drop down menu. They can also be used from the command line to launch ILLIXR.
        

      • Edit the ILLIXR_INSTALL line to point to your ILLIXR install directory.
        • 

      • Edit the ILLIXR_BUILD line to point to your ILLIXR source tree. Prepend your path to the existing /out/build (e.g., ILLIXR_BUILD=D:/ILLIXR/out/build/x64-Debug).
        • 

      

      • 

    

    

    Note
    

    The first time you configure the project (or open it in Visual Studio) it will take a long time to compile and install the dependency libraries, likely this will take several hours. Subsequent configurations will be quick, unless a new dependency needs to be installed.
    

    

    

    

    To configure and build for Android, run Gradle in Android Studio and build within the IDE. Since you cannot use
command line-based environment variables when running on Android, all environment variables have to be hard coded.
All variables are set in main.cpp and are compiled in.
    

    

    

    

    

    Documentation Prerequisites
    

    Building the documentation requires Doxygen and mkdocs(>= v1.5) to be installed, both of which are typically available from OS packages. Additionally, we utilize the material, mkdocs-material-extensions, mkdocs-get-deps, mkdocs-include-markdown-plugin, PyMdown, Pygments, mkdoxy, and mkdocs-glightbox python packages, which can be installed via pip using docs/requirements.txt.
    

    

    An alternate to specifying the plugins as command line arguments is to create a YAML file which specifies the
plugins to build. Using -DYAML_FILE=<FILE_NAME> as the command line argument specifying the YAML file to use.
    

    

    You may need to specify the full path to the YAML_FILE
    

    See profile for the format.
    

    

    The current list of plugins is:
    

    

    

    

      

      

      

        

        

        

          

          

          

          

          The CMake process will also create a YAML file call illixr.yaml which can be used as input to the binary on
Linux and Windows.
          

          Running ILLIXR
          

          

          Note
          

          ILLIXR no longer provides a data set that is automatically downloaded and installed. You can download EuRoC data sets to use from here.
          

          

          Android
          

          To run on an Android device, it must have permissions to allow USB connections. These are usually part of the debugging
tools and will require you to enable debugging. How this is done can vary by device. Once you have the permissions set,
connect the device to your computer while Android Studio is running. You may see a pop-up asking for permissions to
allow the UDB connection or USB debugging, allow this permission. You should now see your device listed in both the pulldown menu
at the top of Android Studio and in the Device Manager tab. If not, please see the Android Studio documentation and trouble shooting
pages. You can now use the Run or Debug items under the Run menu to run ILLIXR on the device. This will install the
APK and allow
          

          Linux and Windows
          

          To run the ILLIXR binary just call main.<>.exe with any of the following command line arguments. (the <> indicate
an infix specifying the build type, for Debug use dbg, for Release use opt, for RelWithDebInfo use optdbg)
          

            

          • -p,--plugins=<>, comma separated list of plugins to use (case sensitive, all lowercase, no spaces)
            • 

          • -y,--yaml=<>, the profile file to use which specifies some or all of the above arguments (e.g. the generated illixr.yaml)
            • 

          • --<ANY ENVIRONMENT VARIABLE NAME>, you can specify any variable the ILLIXR uses on the command line. Common ones are:
            • 

          • --duration=<>, the duration to run for in seconds (default is 60)
            • 

          • --data=<>, the data file to use
            • 

          • --demo_data=<>, the demo data to use
            • 

          • --enable_offload
            • 

          • --enable_alignment
            • 

          • --enable_verbose_errors, give more information about errors
            • 

          • --enable_pre_sleep, force ILLIXR to sleep for the given number of seconds before starting the plugins (this is useful for attaching a debugger)
            • 

          

          Regarding parameters for the binary, the following priority will be used:
1. If the parameter is specified on the command line, it will have the highest priority
2. If the parameter has a value in the yaml file, this value will only be used if it is not specified on the command line (second priority)
3. If the parameter has a value as an environment variable, this value will only be used if it is not specified on the command line nor yaml file
          

          Please refer to the display backend for instructions on setting display-related environment variables.
          

          For specific usage instructions, refer to the README files of the respective plugins.
          

          Profile file format
          

          An example of a YAML profile file is

          plugins: pose_lookup,timewarp_vk,vkdemo,native_renderer
build_type: Debug
install_prefix: /home/user/illixr
env_vars:
  ILLIXR_RUN_DURATION: 5
  DATA: data/mav0
  DEMO_DATA: demo_data
  ENABLE_OFFLOAD: false
  ENABLE_ALIGNMENT: false
  ENABLE_VERBOSE_ERRORS: false
  ENABLE_PRE_SLEEP: false

          

          Where the entries are defined as (* indicates required field):
          

            

          • 

            plugins *
: Comma separated list of plugins (case-sensitive) to build or load at runtime.
            

            • 

          • 

            build_type
: The type of build to perform (Debug, Release, or RelWithDebInfo). Ignored at run time.
            

            • 

          • 

            install_prefix
: The root path to where the compiled libraries and binaries should be installed. (e.g. specifying /home/user will install libraries in /home/user/lib and binaries in /home/user/bin).
            

            

            Note
            

            The prefix is also used for installing any packages that were downloaded and build from external repositories (e.g. DBoW2, GTSAM, etc). At runtime this path is added to LD_LIBRARY_PATH to aid in finding the plugin libraries.
            

            

            • 

          • 

            env_vars
: environment variables to use, any environment variable ILLIXR uses can be set here and will be valid during program execution.
            

            • 

          

          In general, you should not edit a profile file directly. The exception to this is when you are testing things on your own machine. Profile files are generated automatically from the master profiles/plugins.yaml during the cmake configuration stage. This is done so that any changes to a profile or the addition or removal of a plugin can be managed from a single file. The build system will generate an illixr.yaml file which contains entries from the command line and any input profile file and can be freely edited (it is generated every time cmake is called).
          

          Environment Variables
          

          Since you cannot use command line-based environment variables when running on Android, all environment variables have to be hard coded.
 All variables are set in main.cpp and are compiled in.
          

          ILLIXR and several of its dependencies use environment variables to steer processing and define quasi-constant values. Traditionally, one would use std::getenv and std::setenv to get and set these items. However, in ILLIXR the switchboard acts as an interface to these functions with get_env (returns std::string), get_env_bool (returns bool), get_env_char (returns char*), and set_env. Using the switchboard interfaces allows for environment variables to be set from the command line and/or yaml file. It is strongly encouraged to the switchboard interface wherever possible. Any items given on the command line which do not match expected command line arguments are considered to be environment variables. For example:
          

          main.dbg.exe --yaml=my.yaml --DATA_SOURCE=/home/my/data --PROCESS_DATA

          

          This will set env environment variables DATA_SOURCE to /home/my/data and PROCESS_DATA to True. For yaml files, any items not in the expected set will be considered to be environment variables. For example:
          

          plugins: fauxpose,timewarp_vk,vkdemo,debugview,audio_pipeline
enable_offload: false
env_vars:
  DATA_SOURCE: /home/my/data
  PROCESS_DATA: true

          

          Here, the keywords plugins and enable_offload are ignored, as they are expected options. The DATA_SOURCE and PROCESS_DATA entries will cause environment variables to be set to the respective values.
          

          

          Note
          

          The names and values of the environment variables are case-sensitive.
          

          

          

          Note
          

          The get_env_bool considers any of 'y', 'yes', 'true', 'on' (case-insensitive), and "1" to be true.
          

          

          Common Environment Variables
          

            

          • 

            illixr_run_duration
: The duration to run ILLIXR for in seconds.
            

            • 

          • 

            demo_data
: The path to the demonstration data to use at runtime (ignored by build steps)
            

            • 

          • 

            enable_offload
: ? Default is false
            

            • 

          • 

            enable_alignment
: ? Default is false
            

            • 

          • 

            enable_verbose_errors
: Controls the verbosity of error messages. Default is false
            

            • 

          • 

            enable_pre_sleep
: Force ILLIXR to sleep for the given number of seconds before starting the plugins (this is useful for attaching a debugger), Default is 0, indicating no sleeping.
            

            • 

          

          Each plugin can define environment variables to use. See the documentation of each plugin for details.
          

          ILLIXR Graphics Backends
          

          ILLIXR currently supports both OpenGL and Vulkan backends (indicated as gl and vk in the config suffixes). Since some plugins should behave differently (and compile differently) based on what backend is being used, it's important to run make clean if you want to try swapping between the two backends.
          

          

          Warning
          

          The use of the OpenGL back end is in the process of being deprecated. Thus gl based plugins are not guaranteed to work in every instance.
          

          

          Rationale
          

            

          • The current system can use profile files to control everything from the build to running ILLIXR, in keeping with the DRY principle.
   However, for maximum flexibility control can also be done at the command line level as well.
            • 

          

          Philosophy
          

            

          • 

            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.
            

            • 

          • 

            Re-running make (and optionally cmake first) will only rebuild those parts of the code with have changed.
            

            • 

          

          Next Steps
          

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

            

          • 

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

            • 

          • 

            ILLIXR/include/illixr/:
    A directory holding resources and utilities available globally to all plugins.
    This directory contains the interfaces for Switchboard and Phonebook.
            

            • 

          • 

            ILLIXR/plugins/<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 CMake system will detect and rebuild the respective binary
the next time it runs.
If you want to add your own plugin, see Writing Your Plugin.
          



          

          

            

          1. 

            Primary development is aimed at Ubuntu systems, full support for Fedora may require extra work on the users part. ↩
            

            2. 

          2. 

            At the current time only a subset of plugins are available for Windows. More will be added in the future. ↩
            

            3.