Quick Installation Guide

This is an overview of the process necessary to install Vrui-2.x on a fresh Linux system, particularly aimed at novice users, and using Ubuntu Linux 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 some very slim installs omit them (Fedora Linux has these tools installed by default). 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

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 commands on Fedora Linux are:

$ su

to temporarily become the administrator user (enter the root password when prompted), followed by:

$ yum 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 libusb-1.0-0-dev libpng12-dev libjpeg62-dev libtiff4-dev libasound2-dev
$ sudo apt-get install libdc1394-22-dev libspeex-dev libogg-dev libtheora-dev libbluetooth-dev libopenal-dev

The equivalent commands on Fedora Linux are, again as administrator:

$ yum install libusb1-devel libpng-devel libjpeg-devel libtiff-devel alsa-lib-devel libv4l-devel
$ yum install libdc1394-devel speex-devel libogg-devel libtheora-devel bluez-libs-devel openal-soft-devel

These libraries add the ability to, in order, 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 controllers, 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. The easiest 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-2.6-001". 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. Simply open a terminal, and enter the following commands:

$ cd ~
$ mkdir src
$ cd src
$ wget http://idav.ucdavis.edu/~okreylos/ResDev/Vrui/Vrui-Current.tar.gz
$ tar xfz Vrui-Current.tar.gz

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-2.6-001.

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 in your home directory, simply run

$ make install

in the same terminal window as before. This will create a new directory "Vrui-<release>" (e.g., "Vrui-2.6") in your home directory, and install inside it all files required to build and run Vrui applications. To check the installation, run

$ ls -1 ~/Vrui-<release>/bin
AlignTrackingMarkers
DeviceTest
MeasureEnvironment
PrintInputDeviceDataFile
ScreenCalibrator
VRDeviceDaemon
XBackground

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.