Development Environment Setup

This is a tutorial to set up your development environment for MRover. Only Ubuntu 18.04 systems are officially supported. It is recommended that you use the team's Vagrant box for development, as this is the easiest to set up and run. If you choose not to use Vagrant, you can use the provided Ansible playbooks to configure an Ubuntu 18.04-based system for development, either on a Virtual Machine or your own computer.

Table of Contents

1. Setting up the Vagrant box
   1.1. Install VirtualBox
   1.2. Install Vagrant
   1.3. Install Git
   1.4. Fork Repository
   1.5. Clone Repository
   1.6. Create Virtual Machine
   1.7. Close Virtual Machine
2. Configuring an Ubuntu 18.04-based System
   2.1. Install Ansible
   2.2. Run the Ansible Playbook

1. Setting up the Vagrant box

Vagrant is a tool that makes building and maintaining virtual software development environments easy. Using the Vagrantfile in the workspace root directory, it creates an easy-to-use virtual machine with the configurations required to develop software for MRover.

A virtual machine is simply a program that emulates an entirely independent computer running on the host computer. This provides an easy way to build, run, and test rover software on a machine that does not natively support Ubuntu. The following guide will help you set up your computer to run our Vagrant box and begin developing on your own computer.

1.1. Install VirtualBox

VirtualBox is a tool for hosting virtual machines.

• Download VirtualBox
  • Windows
  • Mac
• Install with default settings

1.2. Install Vagrant

• Download Vagrant
  • Windows
  • Mac
• Install with default settings
• Restart computer

1.3. Install Git

Git is a version control program that you will use to develop software for MRover.

• Download Git
  • Windows
  • Mac
• Install with mostly default options
  • Note: For line ending conversions, choose "Checkout as-is, commit Unix-style line endings". This is important! Windows, Mac, and Unix use different ASCII characters to indicate a line ending. By selecting this option, when you develop on your own machine and add it to version control with git, the line endings will be converted to Unix-style line endings. If you do not do this, you will have problems when you try to use MRover's build system on Linux.

1.4. Fork Repository

When contributing software, changes should not be added to the master branch until they have been tested and reviewed by a member of leadership. However, you'll still want to track your changes on a remote branch so they are not just stored locally. To keep the main mrover-workspace repository organized, members are encouraged to create and develop changes on a fork. A fork is like a copy of a repository owned by your GitHub account. When you clone the forked repository, it is referred to by git as origin. You can create branches, make commits, and do whatever you want to the origin remote without affecting the original repository (called upstream by git). Once your changes are have been finished and tested, they can be added to upstream via a pull request. (If you aren't familiar with git and none of that made sense to you, don't worry! Check out the Contribution Workflow page).

• If you haven't done so, create a GitHub account
• Go to https://github.com/umrover/mrover-workspace
• Click the button that says "Fork" in the upper right
• Select your GitHub username

You now have your own fork of mrover-workspace.

1.5. Clone Repository

Now that you've created a fork of mrover-workspace, you'll need to create a local copy where you can make changes and develop software. From Git Bash (Windows) or Terminal (Mac), run

$ git clone https://github.com/<username>/mrover-workspace.git

replacing <username> with your GitHub username. This will create a directory called mrover-workspace containing the contents of the repository.

Alternatively, you can configure an SSH Key for your account and clone your fork with ssh.

1.6. Create Virtual Machine

Now, the virtual machine must be booted for the first time and provisioned, which means an Ansible playbook will be run to configure the environment with the appropriate dependencies.

• Enter the workspace directory:

$ cd mrover-workspace

• Boot the virtual machine. This will take awhile the first time as the virtual machine needs to be provisioned:

$ vagrant up

• ssh into the virtual machine. This will open a terminal inside the virtual machine running Ubuntu 18.04.

$ vagrant ssh

The contents of the mrover-workspace directory are automatically transferred to the virtual machine via rsync. This means that, while you are conceptually on a different computer after running vagrant ssh, the changes made on your local machine will be present on the virtual machine. This allows you to edit and develop code on your local machine in a text editor of your choice, rather than messing around with a command line editor like vim in the virtual machine. Changes made locally can then be built/executed/tested in the virtual machine.

1.7. Close Virtual Machine

To exit the virtual machine, run

$ logout

When you finish your working session, shut down the virtual machine:

$ vagrant halt

This will stop the virtual machine from running in the background on your computer and consuming resources when you are not using it.

2. Configuring an Ubuntu 18.04-based System

If you don't want to use the Vagrant box, you can configure an Ubuntu 18.04-based system using the Ansible configurations provided in the repository. Ansible is an IT automation tool that makes configuring a system with the required dependencies, services, and network configurations easy.

This guide will help you to configure your own Ubuntu 18.04-based system. This could either be a virtual machine hosted by VirtualBox, or a personal computer with an Ubuntu install. If you want to set up a virtual machine or dual-boot your machine, there are plenty of resources available online.

This guide assumes you have already

• Created a fork
• Cloned the repository

2.1. Install Ansible

Install Ansible from the terminal with the apt package manager:

$ sudo apt-add-repository ppa:ansible/ansible  # add the ansible repository to apt
$ sudo apt-get update                          # download additional packages
$ sudo apt-get upgrade -y                      # upgrade currently installed packages
$ sudo apt-get install ansible -y              # install ansible

2.2. Run the Ansible Playbook

To configure the required dependencies to develop, build and run MRover software, the devbox.yml playbook is provided. To run it, enter the ansible subdirectory of mrover-workspace and run the playbook like so:

$ cd ansible
$ ansible-playbook -K -i "localhost," -c local devbox.yml

This will take awhile as apt installs all the required packages. Once the playbook finishes successfully, your machine is ready to develop.