Prerequisites

To set up the development environment, you need to install the following tools.

• Vagrant: a tool for managing and configuring Virtual Machines. 
• VirtualBox: free virtual machine software that we use for developing our firmware code.
• VirtualBox Extension Pack: it's located at the same download page as virtual box.
• Git: make sure to go on Github and create an account.

Installation

The idea is that Vagrant uses VirtualBox to provision a virtual machine for our pre-configured image, box. This virtual machine contains a fully integrated development environment, including everything you'll need to develop software for our team. Now open up a Git Bash window (on Windows) or a terminal window (on Mac), and run the following commands:

First, clone the repo:

# Clone the repo
git clone https://github.com/uw-midsun/box.git && cd box

Then, you will have to download our vagrant box:

# Download and load the vagrant box
vagrant up && vagrant reload

# Access the box
vagrant ssh

Be sure you have the prerequisites installed! Each link should bring you directly to the proper download page.

Congratulations! If you're now at a prompt that says something along the lines of vagrant@midsunbox, you're in our development environment.

We expose a shared folder between your host operating system and the virtual environment, located at box/shared to allow you to use your favorite text editor from your host operating system.

# You should still be ssh'd into the box
# Check with whoami - it should say "vagrant"
whoami
# Access the shared folder - found at box/shared
cd ~/shared
# Clone the firmware repo
git clone https://github.com/uw-midsun/firmware.git && cd firmware
# Try to build the firmware
make build_all

While we're at it, let's configure some settings:

# Configure git
git config --global user.name "Your Name"
git config --global user.email youremail@example.com

git config --global push.default simple
git config --global core.autocrlf input

# Only works for git >= 2.9
git config core.hooksPath hooks
# If git < 2.9 (All boxes before the 18.04 release)
rm -rf .git/hooks && ln -s ~/shared/firmware/hooks .git/hooks

Please use the email that's associated with your GitHub account.

Usage

# Bring up the virtual machine
# This step is only necessary after a reboot
vagrant up
# Access the box
vagrant ssh
# Move to the firmware folder
cd shared/firmware
# See https://github.com/uw-midsun/firmware#usage for some common commands
make [cmd] ...

You're done! From now on, we'll assume you're using our development environment.

Now at this point you are ready to move onto the Firmware Tutorial!

FAQ

Q: I've cloned the firmware repo and I'm in the directory, but I can't build it.

A: Are you sure you've actually entered Vagrant's virtual machine? Running whoami should print vagrant if you're in our development environment. Remember that all Vagrant just provisions a virtual machine, and you still need to ssh into it to actually access it! Treat it like another computer on the network.

Q: How do I use vagrant? When do I use it?

A: Since vagrant is actually just a virtual machine (in this case, running Ubuntu), it's no different than sshing into a Linux computer on the network. vagrant up just launches the VM and vagrant ssh just connects you to it. Whenever you're developing firmware, you should be sshed into the vagrant box.

Q: What is make? Is it related to vagrant?

A: Make is actually a standard GNU tool for designing build systems! It parses our Makefile so it knows what to do when you run commands such as make build_all or make lint. Vagrant just allows us to provide a pre-configured virtual machine with all the dependencies our build system needs, Make included.