Skip to main content

Setup

For this course we'll be using Development Containers (shortened to devcontainers). A devcontainer is a self contained collection of all the software required to run and develop software. All devcontainers use Linux, so no matter what operating system you're using (Windows, macOS, or Linux) you'll be running the same version of Linux as the rest of the class with everything you need.

You'll also be using Git for version control. If you're new to using Git, the free online Git Book is an excellent resource. Chapter 3 is especially useful, since a lot of students are uncomfortable with branching.

We'll be using GitHub to host your code. Please create an account if you haven't already. You can get a free Pro account through GitHub Education. We'll create and give you access to your repository to use for the course. Please make sure you login to CompEng.gg and connect your GitHub account.

You should be using a password manager to follow good security practices. The recommended password manager is 1Password. It is a paid option with nice features such as SSH integration. Luckily as University of Toronto students, you can get a free subscription here. We won't cover it in this setup, but it's a good idea to use it.

Software​

We'll need a minimal set of software for a development environment. Please select the tab corresponding to your operating system for instructions specific for you.

You'll need download and install the following on your machine for development:

You’ll need to have Docker desktop running in the background when working on the labs.

SSH​

We're going to generate SSH keys for you. This is a secure way to connect to servers, and for servers to verify that the key belongs to you. An SSH key has two parts, a private key and a public key. Only you should have access to the private key, it's used to encrypt your data. Never share your private key. You can give out your public key, it's used to identify you (we're going to register it on GitHub).

Launch Git Bash by pressing the Windows key and typing "Git Bash", then pressing enter. This is your terminal.

Older guides may as you to generate an RSA key, but current best practices suggest upgrading to Ed25519 (this is the cryptography). Generate your new key by typing the following command in your terminal and pressing enter:

ssh-keygen -t ed25519

You can follow these steps:

  1. Press enter to save your private key to the default location.
  2. Enter a passphrase. Enter a good passphrase and remember it. This should be unique, and not shared with any other of your passwords. It's important to set this because even if you accidentally share your private key (which you should NEVER do), someone else would still need your passphrase to use it and pretend to be you. If you'd like to ignore this warning, you can make it blank (as someone who has done this, trust me, you'll regret it).
  3. Enter the same passphrase again to make sure you typed it correctly.

That's it! You should get a message that your key was successfully created. There's going to be two files generated: id_ed25519, and id_ed25519.pub. id_ed25519 contains your private key, you should NEVER share this and be very careful if you try to move it. This key is your secure identity, you should be able to use this to access multiple systems if you keep it safe. id_ed25519.pub contains your public key, and we'll use this.

Type the following command and press enter:

cat ~/.ssh/id_ed25519.pub

Copy the result of this command, this is your public key. You'll need it to access your code for the course.

Before moving on, please setup an SSH agent so you don't have to type a passphrase everytime. You'll need it even if you don't have a passphrase for a smooth experience. Follow the guide provided by GitHub:

Windows Instructions

GitHub​

Now you'll have to add your SSH key to GitHub. Make sure you're logged in, we'll be adding our public key so we can access the code for the course.

  1. Click your profile photo in the top right.

  2. Click on "Settings".

  3. Look for "Access" in the sidebar and click "SSH and GPG keys".

  4. Click the green "New SSH key" near the top right.

  5. Type whatever you want to name this key, something like your email is fine.

  6. Paste your public key into the "Key" field.

  7. Click "Add SSH key".

Git​

Now that you're authorized to use GitHub, you can use Git to clone your repository to your computer. We're going to continue using the same terminal we used in the previous sections. If you haven't used Git before, it not only stores your source code. Git stores the entire history of changes you make to your code, so as long as you make checkpoints (through committing and pushing), you can always go back to any previous version of your code.

If you haven't heard the terms committing and pushing before, please read the Git Book (especially chapter 2). In short, a "commit" creates a checkpoint of all your source files on your computer (you can do this without internet). A "push" makes sure your repository with all your checkpoints is the same as the one on a server (you need internet to do this, and to ensure all your changes are on GitHub). This ensures there's a backup of your work, and lets us see your code. You should push early and often.

For the following commands replace <UTORID> with your UTorID, not your username on GitHub. As a reminder, it should be 8 characters long. Type the following commands, pressing enter after each line:

note

Before proceeding, you have you accept the GitHub invite to the organization and to your repository! Your organization invite should be here. The URL for your repository invite should be https://github.com/compeng-gg/2024-fall-ece344-<UTORID>/invitations.

cd ~
git clone git@github.com:compeng-gg/2024-fall-ece344-<UTORID> ece344
cd ece344
git remote add upstream git@github.com:compeng-gg/2024-fall-ece344-student
note

It's normal to see Are you sure you want to continue connecting (yes/no/[fingerprint])? the first time you connect to GitHub. This is to verify you're connecting to the correct server. Type yes and press enter to continue.

Note: you can replace cd ~ by going to whatever directory you'd like to create your ece344 directory in.

Now, we'll setup our Git options. Type the following commands in the terminal:

git config user.name "Your Full Name"
git config user.email your@email.com

Replace "Your Full Name" and your@email.com with your student information (your email should end with something similar to @mail.utoronto.ca). Next, we'll do some more Git settings, type the following commands:

git config init.defaultBranch main
git config pull.rebase false
git config alias.lol "log --pretty=oneline --abbrev-commit --graph --decorate"

You can also run the commands again, replacing the git config before the commands with git config --global to apply them globally to every Git repository as well. However, you should still run the plain git config (without --global) so you don't run into strange issues. You may want to use your personal email with git config --global user.email.

VSCode​

Open VSCode and select "Open Folder...". Navigate to ece344 and hit “Select”. It’s very important to open the ece344 directory in VSCode, any other directory. After this you should see the provided code.

Next, we're going to install the extension that let's us use containers. Go to Settings → Extensions, and download Dev Containers extension. After installing click the green button in the bottom left and click "Reopen in Container". The first time you do this, it will take a bit to setup (you should only have to do this once). Once in the devcontainer, it’s recommended to install the clangd extension.

Troubleshooting​

Public key denied when pushing​

If you haven't set up ssh-agent then you can only push and pull outside of VSCode (so either using Git Bash, or your machine's terminal).

Windows​

If you get an error saying virtualization not enabled then follow the instructions here.