Quick Installation Guide

This is an overview of the process necessary to install Vrui on a fresh Linux system, particularly aimed at novice users, and using Ubuntu Linux or one of its derivatives such as Linux Mint as example distribution (under the assumption that novice users would try Ubuntu first). Notes about differences to other Linux distributions, using Fedora Linux as a running example (since that's what I'm using myself), are interspersed where necessary.

Depending on the speed of your network connection (determining how long it takes to download Vrui and its required packages) and the speed of your computer, this entire process should only take a few minutes.

Prerequisites

A "virgin" Linux installation is missing several components that are required to build Vrui, and even more components that are optional, but create a more complete Vrui experience. The most basic requirement to build Vrui from source is having a development system, consisting at least of g++, the GNU C++ compiler, make, expr, sed and find. These tools should really be part of every Linux system, but more and more of them get dropped from newer distributions. If typing any of the preceding commands into a terminal results in a "command not found" error, run the following commands from a terminal (in the rest of this document, a dollar sign ($) indicates commands that you type into the terminal, as opposed to things the terminal prints out, and <...> indicates a placeholder that you will have to replace with concrete values, such as the version number of the particular Vrui package you downloaded):

$ sudo apt-get update
$ sudo apt-get install build-essential

The equivalent command on Fedora Linux is:

$ sudo dnf install gcc-c++

Enter additional information, such as your password, when prompted by the terminal.

Afterwards, install the following required packages from a terminal:

$ sudo apt-get install zlib1g-dev mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev

The equivalent command on Fedora Linux is:

$ sudo dnf install zlib-devel mesa-libGL-devel mesa-libGLU-devel

Mesa is a free implementation of the OpenGL 3D graphics library, but it does not offer very high performance on Nvidia or ATI/AMD graphics cards. For that purpose, you need to install the vendor-supplied OpenGL drivers, either from the repositories of your Linux distribution, or directly from the vendor. That part is beyond the scope of this guide; search the support forums of your Linux distribution for detailed guides.

Optional Libraries

For a complete Vrui experience, install the following additional libraries from a terminal:

$ sudo apt-get install libudev-dev libdbus-1-dev libusb-1.0-0-dev libpng-dev libjpeg-dev
$ sudo apt-get install libtiff-dev libasound-dev libv4l-dev libdc1394-22-dev
$ sudo apt-get install libspeex-dev libogg-dev libtheora-dev libbluetooth-dev
$ sudo apt-get install libfreetype6-dev libXi-dev libXrandr-dev libopenal-dev

The equivalent commands on Fedora Linux are:

$ sudo dnf install libudev-devel dbus-devel libusb1-devel libpng-devel libjpeg-devel
$ sudo dnf install libtiff-devel alsa-lib-devel libv4l-devel libdc1394-devel
$ sudo dnf install speex-devel libogg-devel libtheora-devel bluez-libs-devel
$ sudo dnf install freetype-devel libXi-devel libXrandr-devel openal-soft-devel

These libraries add the ability to, in order, enumerate hardware devices, talk to desktop services, talk to USB devices such as Microsoft Kinect cameras, load and save images in a variety of formats, record and play back stereo sound, capture video from webcams or high-end Firewire cameras, send compressed audio or video over the Internet, connect to Bluetooth devices such as Nintendo Wii or Playstation Move controllers, render beautiful 3D text, receive input from multitouch screens, enumerate connected displays, and create spatial 3D sound effects.

Downloading and Unpacking Vrui

Vrui is distributed as tarballs, i.e., as compressed file archives not unlike zip files. These tarballs can be downloaded directly from the Download page. An easy way to unpack them is to use the graphical archive manager. When clicking on any of the tarball links, a window should pop up asking what to do with the selected tarball. Check the "Open with" button, leave the default "Archive Manager" application, and press OK. This will download the tarball, and then show its contents. There should only be a single folder in the tarball, named after the Vrui version and release, e.g., "Vrui-4.6-005". Select that folder, and click the "Extract" button. This will open a file selection dialog, pointed to your home directory. Click on the "Create Folder" button, and enter the new folder's name as "src". This will open the new folder, and show an empty list of files. Then ensure that the "Selected Files" and "Re-create folders" buttons are checked, and press Extract. This will unpack the sources, and show a completion dialog. Simply press Quit.

That said, there is an even easier way to download and unpack Vrui, if you're not afraid of the command line. Open a terminal, and enter the following commands:

$ cd ~
$ mkdir src
$ cd src
$ wget http://www.idav.ucdavis.edu/~okreylos/ResDev/Vrui/Vrui-<release>-<build>.tar.gz
$ tar xfz Vrui-<release>-<build>.tar.gz

where you replace Vrui-<release>-<build>.tar.gz with the version you want to download, e.g., Vrui-4.6-005.tar.gz.

Pro tip: You can download and unpack a tarball all at once, without even storing the tarball on your hard drive. Replace the last two lines (wget and tar) with the following, exactly as shown here:

$ wget -O - http://www.idav.ucdavis.edu/~okreylos/ResDev/Vrui/Vrui-<release>-<build>.tar.gz | tar xfz -

The "-O -" option tells wget to stream the downloaded file to a so-called "pipe" instead of writing it to disk. The pipe symbol "|" tells the shell to pipe the downloaded file to the tar command, and the "xfz -" option tells tar to read the packed file from a pipe instead of from disk. Neat.

Building and Installing Vrui

After the sources have been unpacked, open a new terminal window and enter the following commands:

$ cd ~/src
$ ls
Vrui-<release>-<build>
$ cd Vrui-<release>-<build>

Replace Vrui-<release>-<build> with the actual name of the Vrui base directory as printed by ls, e.g., Vrui-4.6-005.

Then build Vrui by running

$ make

in the already-open terminal window. This will take a few minutes, depending on the speed of your computer. The build system will display its progress in the terminal; if everything worked well, the last line will say "Creating pkg-config meta data file..."

To install Vrui inside the /usr/local directory hierarchy, run

$ sudo make install

in the same terminal window as before. This will ask for your password (you need to have administrative rights), and then create several new directories inside /usr/local, and install inside it all files required to build and run Vrui applications. To check the installation, run

$ ls -1 /usr/local/bin
AlignPoints
AlignTrackingMarkers
DeviceTest
EyeCalibrator
FindHMD
MeasureEnvironment
OculusCalibrator
OnVive.sh
PrintInputDeviceDataFile
RoomSetup
RunViveTracker.sh
SampleTrackerField
ScreenCalibrator
TrackingTest
VRDeviceDaemon
XBackground

If you do not want to install Vrui in a system location such as /usr/local, you can install it inside your home directory. After downloading and extracting the tarball, and moving into Vrui's source directory, run

$ make INSTALLDIR=$HOME/Vrui
$ make INSTALLDIR=$HOME/Vrui install

This will create a new directory Vrui directly inside your home directory, containing the entire Vrui installation. To uninstall cleanly, simply remove that entire directory and everything inside it.

Updating device permissions

Vrui can talk to a lot of non-standard devices such as head-mounted displays, motion controllers, joysticks, gamepads, ... By default, for security reasons, non-standard devices can only be accessed by the system administrator. For the specific devices known to Vrui, there is no risk in granting access to the user currently logged in to the console. To change the default behavior, Vrui can install so-called "device rule files" in a system location, typically /etc/udev/rules.d. To install the rules necessary to talk to VR devices, run

$ sudo make installudevrules

from inside Vrui's source directory.

Building and Running Vrui Example Applications

Vrui contains several simple example applications, meant as a quick getting-started guide for Vrui developers, but also useful to test whether a new Vrui installation works properly. To build these examples, run

$ cd ExamplePrograms
$ make

in the same terminal window as before. This will be a relatively quick process, and create several executable programs in a new "bin" directory inside the "ExamplePrograms" directory. To start the least boring one, run

$ ./bin/ShowEarthModel

in the same terminal window. If Vrui was built successfully, this will open a window, and show a spinning globe on a black background. Press the left mouse button to rotate the globe, the "z" key to move the globe inside the window, roll the scroll wheel to zoom in or out, or press the right mouse button to open the program's main menu. When you're done, select "Vrui System" -> "Quit Program" from the main menu, or simply close the window.

Congratulations, Vrui is now installed and working!