This tutorial will show you how to compile Torque 3D inside an Ubuntu virtual machine using Vagrant. You'll be able to use the resulting binaries on other Ubuntu computers to play T3D games.

What is Vagrant?

Vagrant is a command-line application that helps you manage virtual machines. It allows you to write script files that describe a virtual machine, and then execute those scripts to create it. This means the process of deciding which base image to use and which application to install is automated, and stored in configuration files that are easy to edit and version control.

Before you get started, download and install VirtualBox and Vagrant. You may also find why Vagrant? an interesting read.

Terminology

A VM or virtual machine emulates another computer in software inside your actual computer. Virtual machines let Windows users run Linux and vice versa without having to dual-boot or have two computers.

The host OS is the 'real' computer which the virtual machine runs inside, and the guest is the OS that runs inside the virtual machine. For example, if I have a Windows computer and install a virtual machine which runs Ubuntu, I say that Windows is my host OS, and Ubuntu is the guest OS.

Provisioning is the act of installing software and libraries into the guest OS inside a VM. Usually you only call it 'provisioning' if it's an automated process, as it is with Vagrant; otherwise it's just installing stuff.

SSH stands for secure shell. It's a method of logging into a remote system via the text console, and is a common method of accessing servers and VMs. This tutorial will use SSH access so we don't have to deal with installing a GUI on the VM.

Setup

Windows host

If you're a Windows developer, you may want to use a virtual machine to compile the engine and distribute binaries to your Linux users, or simply to test your changes for cross-platform compatibility. You might also use a virtual machine to build a dedicated server, if your game requires that.

Once you have installed Vagrant and VirtualBox, start a terminal by opening the Start menu, typing cmd and pressing Enter. (Note! If you have any symlinks in your T3D directory, you'll need to open the console with administrator permissions by right-clicking the cmd entry and selecting the appropriate option.) Now change directory to this folder, wherever you have installed Torque. For example:

cd "C:\Torque3D\Tools\Vagrant\Ubuntu 14"

Now you're ready to boot up your virtual machine!

vagrant up

Vagrant will import the base virtual image, and start installing software. This will take some time - let it run until you get back to a command prompt. Once that happens, all that remains is to type

vagrant ssh

This starts an SSH session, which gets you into a command prompt inside the VM itself.

Linux host

Linux users, even though they could compile the engine in Linux natively, choose to use virtual machines to isolate their build environment. This means not needing to install libraries and software on their host OS, and it also means that if the virtual machine becomes a mess of conflicting libraries, it's easy to wipe it out and start again.

Hey! Listen! If you have a 32-bit host OS (how can you tell? Have a read), and you intend to run the guest-compiled binary in your host, you'll need to edit Vagrantfile before continuing. Find the line containing ubuntu/trusty64 and change it to ubuntu/trusty32.

And it's time to boot-

cd ~/Torque3D/Tools/Vagrant
vagrant up && vagrant ssh

Building Torque

Now that you've SSHed into your virtual machine, you can start a new project and compile the engine! Using the Vagrant config provided in Tools/Vagrant/Ubuntu 14/Vagrantfile, the Torque 3D folder is mounted in the virtual machine in the /torque folder. So,

cd /torque

Now you're ready to follow the instructions in the Linux compiling tutorial to generate your projects and compile them. Note that during compiling you may see messages like warning: Clock skew detected. This is a consequence of using a VM, and is usually harmless.

Once the compile completes, if you're on an Ubuntu host with a compatible version to the VM, you should be able to run the binary! Find the project directory on your host OS, and run game/LinuxTest.