Prerequisites

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

• Vagrant: a tool for managing and configuring Virtual Machines. Download the latest distro of Vagrant here
• VirtualBox: Download the latest version of Virtualbox VirtualBox 7.0. You need both the main application and the "Oracle VM VirtualBox Extension Pack", available here. Check that the versions are the same 😉
• 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

...

# 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_xivfwxv.git && cd firmware_xivfwxv
# Try to build the firmware
make build_all (if you are on Apple Silicon, ignore this) 
scons

# Create an ssh key
ssh-keygen -t ed25519 -C "your_email@example.com"
# Press enter to save at default location, and enter again to use no passphrase

# Add your ssh key to the ssh agent
eval "$(ssh-agent -s)"

# Add all keys to the ssh agent
ssh-add

# Make sure you are in the git repo
cd firmware_xivfwxv

# Switch from https to ssh
git remote set-url origin git@github.com:uw-midsun/firmware_xivfwxv.git

While we're at it, let's configure some settings (while still in our vagrant box):

# 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_xiv/hooks .git/hooks

# Make sure that pylint is up to date so that the hooks don't fail, and install autopep8 for Python formatting
pip3 install pylint autopep8

# Make sure virtualenv is installed so Python dependencies get properly installed
sudo pip3 install virtualenv

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

YOU ARE FINISHED HERE

Update existing box

Only worry about this if you had the old box previously

to update existing boxes to ubuntu-20.04, navigate to your box folder

get the new box from the ubuntu-20.04 branch

git fetch && git checkout ubuntu-20.04

you might also need to destroy the old box

vagrant halt
vagrant destroy
vagrant up

after you ssh into the new box, you should see this message

Welcome to Ubuntu 20.04.3 LTS

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

 * Super-optimized for small spaces - read how we shrank the memory
   footprint of MicroK8s to make it the smallest full K8s around.

   https://ubuntu.com/blog/microk8s-memory-optimisation

if your message lists a ubuntu version other than 20.04, I don't know what happened, message ShiCheng on slack and we'll figure it out.

After updating the box, you may need to reconfigure your git configurations, follow the steps above.

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_xivfwxv folder
cd shared/firmware_xivfwxv
# See https://github.com/uw-midsun/firmware_xivfwxv #usage for some common commands
make [cmd] ...

# To exit the virtual machine press CTRL + D
# Stop the virtual machine
vagrant halt

...

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: Don't worry, you don't have to use vim unless you really want to! Since we use a shared folder, both the box and your computer can access its contents. As long as you keep your code in there like in the instructions, you're able to access that folder from your computer and use whatever text editor / code editor / IDE you want.

Q: I upgraded to Big Sur after installing, and it doesn't work! Does this not work for Big Sur? (Likely applies to future MacOS updates, Big Sur is currently the latest as of writing this)

A: It works for Big Sur! Upgrading operating systems for Mac doesn't seem to transfer the permissions for VirtualBox properly, so you may need to re-install VirtualBox in order to gain the prompt to come up in System Preferences > Security & Privacy. Once installed, you will need to click "Allow" to give Oracle Virtual Box the proper permissions. Note: to uninstall VirtualBox and Vagrant, just download the latest version (see the links at the top of the page), and it should come with an uninstall tool.