Vagrant

We recommend using Vagrant to run a small virtualized Linux machine inside your computer. This is especially important when solving the assignments for Module 2 and 3. The benefits are that you can develop your assignments in a Unix environment and that the tools and programming languages that are used in the course are pre-installed in our Vagrant setup.

Installing Vagrant

Download and install VirtualBox Links to an external site..
Download and install Vagrant Links to an external site..
Open a terminal window and navigate to your course repository, i.e. to the folder "id2202-username".
Copy one of the four Vagrant files from the folder "template-projects" to the root of your repo, as shown in the commands below (the name of the file needs to be "Vagrantfile"). If you are programming in OCaml, you can use a small Vagrant file (with the string "OCaml" in the file name). Otherwise, you need to use a large Vagrantfile (without "OCaml" in the name), that installs all of the languages supported in the course.
Windows users (OCaml):
```
$ copy template-projects/Vagrantfile-OCaml.win Vagrantfile
```
Non-Windows users (OCaml):
```
$ cp template-projects/Vagrantfile-OCaml Vagrantfile
```
Windows users (all languages):
```
$ copy template-projects/Vagrantfile.win Vagrantfile
```
Non-Windows users (all languages):
```
$ cp template-projects/Vagrantfile Vagrantfile
```
Run the command:
```
$ vagrant up
```
It might take a long time (~20 minutes) to finish as it needs to download and install a lot of packages, but you only have to do this once unless you edit your Vagrant file.

Note: if you have not yet got access to the repos, you can download the vagrant files here: [vagrant-file-for-windows-ocaml Download vagrant-file-for-windows-ocaml], [vagrant-file-for-mac-or-linux-ocaml Download vagrant-file-for-mac-or-linux-ocaml], [vagrant-file-for-windows Download vagrant-file-for-windows], and [vagrant-file-for-mac-or-linux Download vagrant-file-for-mac-or-linux]

Installing Vagrant (mac m1/m2)

Since this processor uses an ARM architecture and we are compiling to x86 we need to set-up vagrant so that it is able to emulate an x86_64 environment. We do this by using qemu Links to an external site. as a vagrant provider instead of virtualbox. However, since this emulation is done solely in software, this provider is a fair bit slower than virtualbox. This is typically not a problem when you are developing and testing your compiler, but doing vagrant up the first time will take longer. We therefore provide Vagrantfiles for this setup with fewer dependencies, where you can instead add additional dependencies as needed.

The setup procedure is as follows:

Install homebrew Links to an external site.. We will use it to install the rest of the stuff.
Install qemu with
```
brew install qemu
```
Install Vagrant Links to an external site..
Install the qemu vagrant provider Links to an external site. with
```
vagrant plugin install vagrant-qemu
```
Open a terminal window and navigate to your course repository, i.e. to the folder "id2202-username".
Copy the vagrant file with the qemu suffix for your language of choice to your repository root. E.g. cp template-project/Vagrantfile-OCaml.qemu Vagrantfile (or download it from one of the links below and rename it accordingly if it is not present in template-project).
Run the command
```
vagrant up --provider qemu 
```
This will take some time so find something else to do in the meantime. On our mac mini 2020 model, it took ~1.5h to run this command for the OCaml environment and ~20min for the Haskell environment the first time. If you want to, you can tweak the line
```
qe.smp = "cpus=4,sockets=1,cores=4,threads=1" 
```
in the Vagrantfile to leverage more cores to speed things up.
When the command in 7 has finished you can follow the instructions for using Vagrant. To sync your files from the host machine to the guest machine you need to use vagrant rsync and/or vagrant rsync-auto as described in the FAQ below.

Qemu-specific vagrantfiles: Vagrantfile-OCaml.qemu Download Vagrantfile-OCaml.qemu, Vagrantfile-Haskell.qemu Download Vagrantfile-Haskell.qemu, Vagrantfile-Rust.qemu Download Vagrantfile-Rust.qemu, Vagrantfile-C++.qemu Download Vagrantfile-C++.qemu, and Vagrantfile-Java.qemu Download Vagrantfile-Java.qemu.

Using Vagrant

Open a terminal window and navigate to your course repository, i.e. to the folder "id2202-username".
Run the command:
```
$ vagrant ssh
```
You should now be inside the Vagrant virtual machine.

Your repository is located in the folder "/vagrant"

$ cd /vagrant

$ ls
README.md  Vagrantfile  exercises  solutions  template-projectss

To compile e.g. the "Hello World" project for Ocaml, do:
```
$ cd template-projects/ocaml && make
```
To exit from your virtual machine, either do "Ctrl-D" or enter:
```
$ exit
```

Other useful commands

You can find more commands in the Vagrant documentation Links to an external site.. In particular, you might want to look up:

vagrant suspend
vagrant halt
vagrant resume
vagrant destroy

FAQ

As a Windows user, when I do "vagrant up", I get the error: "There was an error when attempting to rsync a synced folder.", what should I do?

In most cases, this error arises when there are files with symlinks in your repo. The error message will show which file(s) cause the error. In most cases, you can just delete these files and the error goes away when you rerun "vagrant up".

Files are not synced between my machine and the vagrant environment.

You can address this problem when you have a running vagrant session (i.e. you did vagrant up) as follows:

Go to the folder where your Vagrantfile file is located in a new terminal.
Run the command: vagrant rsync-auto. This command will watch the current directory and sync files between your windows machine and the vagrant session. Be advised, there might some delay when syncing.
Alternatively, you can force a sync manually by running the command vagrant rsync.

You find more details here: https://developer.hashicorp.com/vagrant/docs/cli/rsync-auto Links to an external site. and here: https://developer.hashicorp.com/vagrant/docs/cli/rsync Links to an external site.

As a Windows user, vagrant up results in an error similar to:

There was an error while executing `VBoxManage`, a CLI used by Vagrant for controlling VirtualBox. The command and stderr is shown below.

Command: ["startvm", "0a967fd3-201d-4023-9dda-a1d0495750c0", "--type", "headless"]

Stderr: VBoxManage.exe: error: The virtual machine 'ansible-node' has terminated unexpectedly during startup with exit code -1073741819 (0xc0000005) VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component MachineWrap, interface IMachine

This seems to be an open bug https://github.com/hashicorp/vagrant/issues/12484 Links to an external site. related to virtualbox not being able to run in headless mode. A possible work around is to:

Run vagrant destroy to kill any running vagrant sessions.
Edit the Vargrantfile, and inside config.vm.provider "virtualbox" do |v| ... end add a line v.gui = true before end
Try vargrant up again.

Vagrant fails to initialize its home directory

Vagrant does not appear to handle paths containing non-ASCII characters properly, which most commonly happens when you have a non-English username in windows (see: https://github.com/hashicorp/vagrant/issues/2113 Links to an external site.). The fix is to create a new directory somewhere you have write permissions such that the path contains only ASCII characters, then setting the VAGRANT_HOME environment variable:

setx VAGRANT_HOME "X:/path/to/new/directory/using/forward/slashes"

Issues related to WSL2

There seems to be problems with vagrant on windows machines with WSL2 enabled and Hyper-V. A possible fix is to disable Hyper-V Links to an external site. and to reboot.