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 (Linux, Intel Mac, and Windows)

  1. Download and install VirtualBox Links to an external site..
  2. Download and install Vagrant Links to an external site..
  3. Navigate to your course repository, i.e., to the folder "id2203-username".

Setting up Vagrant (Linux and Intel Mac)

  1. Save one of the following Vagrant files to the root of your repository:
    1. Vagrantfile-Scala.unix Download Vagrantfile-Scala.unix includes support for Scala.
    2. Vagrantfile-OCaml.unix Download Vagrantfile-OCaml.unix includes support for OCaml.
    3. Vagrantfile.unix Download Vagrantfile.unix includes all supported languages (takes longer to install).
  2. Rename the file to "Vagrantfile", e.g., mv Vagrantfile.unix Vagrantfile.
  3. In your repository root, run the command vagrant up.
  4. Wait, 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.

Setting up Vagrant (Windows)

  1. Save one of the following Vagrant files to the root of your repository:
    1. Vagrantfile-Scala.win Download Vagrantfile-Scala.win includes support for Scala.
    2. Vagrantfile-OCaml.win Download Vagrantfile-OCaml.win includes support for OCaml.
    3. Vagrantfile.win Download Vagrantfile.win includes all supported languages (takes longer to install). Caveat: It is currently not possible to build the Haskell template project inside the shared folder "/vagrant". You can build it in your home folder (~) inside the Vagrant environment. However, this means that you manually have to move your source files from "/vagrant" to this location before building if you edit them on your host system.
  2. Rename the file to "Vagrantfile", e.g., mv Vagrantfile.win Vagrantfile.
  3. Open the VirtualBox gui and keep it open while you work with Vagrant.
  4. In your repository root, run the command vagrant up.
  5. Vagrant will synchronize your repository folder on the host with the Vagrant guest environment using SMB. It will therefore during the setup:
    1. Ask you to provide your Windows username and password.
    2. Prompt you to allow Vagrant access-rights to setup the shared folder.
  6. Wait, 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.

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 installation procedure is as follows:

  1. Install homebrew Links to an external site., we will use it install the rest of the stuff.
  2. Install qemu with brew install qemu.
  3. Download and install Vagrant Links to an external site..
  4. Install the qemu vagrant provider Links to an external site. with vagrant plugin install vagrant-qemu.
  5. Navigate to your course repository, i.e., to the folder "id2203-username".

Setting up Vagrant (Mac M1/M2)

  1. Save one of the following Vagrant files to the root of your repository:
    1. Vagrantfile-Scala.qemu Download Vagrantfile-Scala.qemu includes support for Scala.
    2. Vagrantfile-OCaml.qemu Download Vagrantfile-OCaml.qemu includes support for OCaml.
    3. Vagrantfile-Haskell.qemu Download Vagrantfile-Haskell.qemu includes support for Haskell.
    4. Vagrantfile-Rust.qemu Download Vagrantfile-Rust.qemu includes support for Rust.
    5. Vagrantfile-C++.qemu Download Vagrantfile-C++.qemu includes support for C/C++.
    6. Vagrantfile-Java.qemu Download Vagrantfile-Java.qemu includes support for Java.
  2. Rename the file to "Vagrantfile", e.g., mv Vagrantfile-Scala.qemu Vagrantfile.
  3. In your repository root, run the command vagrant up --provider qemu.
  4. Wait, It might take a long time (~1 hour) 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. 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.

Using Vagrant

  1. Open a terminal window and navigate to your course repository, i.e. to the folder "id2202-username".
  2. If you are on windows, open the VirtualBox gui and keep it open.
  3. Run the command: vagrant ssh. You should now be inside the Vagrant virtual machine.
  4. Your repository is located in the folder "/vagrant": cd /vagrant. Listing the files with ls should output something like: README.md Vagrantfile exercises solutions template-projects.
  5. Your repository root on your host machine and the folder "/vagrant" are kept in sync with the following caveats:
    1. You might have to, in another terminal, run vagrant rsync in the project root to synchronize the files.
    2. For the qemu Vagrant setup it will only synchronize from host to guest. I.e., changes to files in the "/vagrant" directory will not show in your "id2202-username" directory on your host system.
    3. You can continuously synchronize files with the command vagrant rsync-auto.
  6. To compile e.g. the "Hello World" project for Ocaml, do: cd template-project/ocaml && make.
  7. 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:

  1. Go to the folder where your Vagrantfile file is located in a new terminal.
  2. 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.
  3. 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:

  1. Run vagrant destroy to kill any running vagrant sessions.
  2. Edit the Vargrantfile,  and inside config.vm.provider "virtualbox" do |v| ... end add a line v.gui = true before end
  3. 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.