Versions Compared

Version Old Version 35 New Version Current
Changes made by

ShiCheng Lu

Adel Chinoy

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note
titleM1 Mac Users

If you have an M1 Apple silicon-based Mac, please ignore this page and follow the specific environment setup steps at Environment Setup For M1 Based Macs.

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: checkout the ubuntu-20.04 branch for the new box 

Code Block
# Clone the repo
git clone https://github.com/uw-midsun/box.git && cd box
# checkout the ubuntu-20.04 branch for the new version of the box
git checkout ubuntu-20.04


Then, you will have to download our vagrant box:

...

Code Block
languagebash
# 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 (if you are on Apple Silicon, ignore this) 
scons


Info

Note: Using passwords to authenticate Git operations with Github.com will soon be deprecated as shown here: Token Authentication RequiredYou will need to setup an ssh key to access github with your account. 

If you have already performed git clone with https, you will need to can alternatively set up a token to be able to push any changes to our repo and you will need to enter this token in replacement of your password each time you push.

AlternativelyIf you are setting up fresh, you can set up need to use an ssh key to link it with your account so you don't have to re-enter you username and token each time you want to push. To learn how to add an ssh key you can run run the following commands in this tutorial within your VM: Add an SSH Keyvagrant. Then, make sure to link it to your Github account.

Code Block
languagebash
# 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


Also, if you have already performed git clone with https, you will need to can switch to ssh by performing the command below. If you don't, you will constantly be prompted for your user/token still even if you've already added your ssh key and linked it to your Github account.

Code Block
languagebash
# 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):

Code Block
languagebash
# 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

...

Code Block
languagetext
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

...

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

Usage

Code Block
languagebash
# 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.

...