CSCI 104
Next incomplete Task completion: 0%

Getting Started

Before you start out on your 104 journey you’re going to have to complete a couple of setup steps. Make sure you read each section carefully; if you don’t, you may find yourself unable to submit assignments.

Register with Github

If you have not created a Github account yet, follow the instructions in this section. If you already have a Github account and you wish to use it for this course, you can skip to the next section.

We will be using git extensively this semester in labs and in programming assignments. Github is a development ecosystem based around git. In CSCI 104, we will be using Github to host our git repositories and we will take advantage of other GitHub features such as Actions and wiki.

We start by visiting Github’s signup page. You are free to choose your username; it does not necessarily need to match your USC username. Likewise, you are welcome to any email, just remember which email you use as you will need it later. You will be sent an email to verify your email address. Do that before proceeding.

If in doubt, use a GitHub account with your @usc.edu e-mail address.

Install Git

You can skip this section if you have git installed or are using the VM, which has git installed.

In order to actually install the git command line tools, go to the git website and follow the instructions for your operating system.

If you’re installing on MacOS, installing the Homebrew package manager should also get you there: brew.sh

Special Notes for Windows

If you are using Windows, we recommend installing git bash, which will be provided as an option in the installer. Git bash is a separate shell that provides access to git as well as other command line utilities. If you have more experience with git or other command line tools, installing git and the other unix commands directly to your CMD is a pretty convenient option.

Virtual Machine

We have two options for running the compiler tools that we will use for grading. While you are welcome to use any editor/IDE to develop your homework code, you must compile and run your code (and any of our tests) in a Linux virtual environment using a Linux VM, Docker, or some similar solution of your creation.

We offer two solutions: a traditional VM and Docker. We recommend Docker, as it avoids emulating an entire desktop by giving you easy and low-latency command-line access to all the tools you need. Plus, you can use your own local editor to develop and write code.

Docker

Follow the directions in this Github repository.

If you want more information on how Docker works and how to use it, you can read the additional guide.

VM

Alternatively, you can download and install the Course VM, the instructions for which are available in the wiki. This provides a full-featured virtual OS with graphical interface, etc. It is larger, stores your files on a separate “virtual disk” that is not directly accessible from your computer’s host OS, and can sometimes get corrupted, so please push your work to Github often.

Configuring an SSH Key

One of the main features of using a distributed version control system such as git is having a complete backup of your code and its history. Git uses the Secure Shell protocol (SSH) when contacting remote servers. To facilitate this communication, you need to generate a pair of encryption keys: one public and the other private. In this step, we will generate the set of keys required to use SSH. This will be done manually through the command line.

Important: where you run the following instructions will depend on whether you’re using Docker or the VM. If you are using Docker, you must open a terminal on your normal operating system. This is because Docker reboots itself from a pre-canned image everytime, which would erase all git configurations you had. If you’re on Windows, installing Git should either give you Git Bash or access to unix commands in CMD. If you are using the VM, you have to open Terminal inside the virtual desktop. Going forward, whichever applies to you will be the terminal we refer to when we ask you to open or write commands in a terminal.

Note: you will be copying and pasting several commands in this lab. If you are using the VM, you can use ctrl + shift + c to copy from Terminal and ctrl + shift + v to paste into Terminal. You can also right-click in Terminal and choose Copy/Paste. If you’re using Docker, copy and paste should work how it normally does on your operating system.

Use the following command to generate an SSH key, replacing ttrojan@usc.edu with the email associated with your Github account:

ssh-keygen -t rsa -b 2048 -C "ttrojan@usc.edu"

When prompted for a location to save the key, use whatever the default is. The path may look slightly different than the one below, but that’s fine.

Generating public/private rsa key pair.
Enter file in which to save the key (/home/csci104/.ssh/id_rsa):

After that, you will be prompted for a passphrase to secure your private key. We recommend you do NOT generate a passphrase (because you’ll have to enter it each time you upload your code to Github) and simply hit Enter when prompted for a passphrase. If you do decide to enter a passphrase, please note that your password will not show up in terminal as you type it. When you are done typing your password (don’t enter anything if you do not wish to set a passphrase), press enter. You will be prompted to verify your passphrase. Re-enter your passphrase (or nothing if you did not set one) and press enter.

Upon success, you should receive confirmation that your key was generated. It will most likely look something like this:

Your identification has been saved in /home/csci104/.ssh/id_rsa.
Your public key has been saved in /home/csci104/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:vC+4OG2u1PIeE0OKX9jiFFHuLnkYCBSsvIW8ybD873H ttrojan@usc.edu
The key's randomart image is:
+---[RSA 2048]----+
|   ++o.          |
|    S+.o *.*     |
|   +.X. o        |
|    0. o +       |
|   ..o  E .      |
|  .=S. . + .0    |
| .*=* ...        |
|.+.=o*. ..  *o*  |
| .++*oo. ..      |
+----[SHA256]-----+

Git Configuration

The next step is to configure your git profile in your development environment. This is important because your profile information is used to annotate your contributions to a repository/project. It may not seem like a big deal when you are the only one committing to a repository. However, it’s a good habit to build since in a group setting, this information will help track what changes you made and how much you’ve contributed.

You only need to do this configuration once for any machine or virtual machine you want to develop on. We’ll be setting the following fields:

To get started, have a terminal open.

Personal Information

Please use your actual first and last name when configuring your git user.name. For your email, you should use the email address you’ve associated with your Github account. Configure your information as follows, replacing the example name and email with your own:

git config --global user.name "Tommy Trojan"
git config --global user.email "ttrojan@usc.edu"

Git CLI

By default, git does not color its output. Pretty printing git messages makes it easy read the output and take proper actions. You can enable colors for interactive use with:

git config --global color.ui auto

Git Editor

When committing code in git, the system requires a commit message. If a message is not provided via the shell, git will launch the operating system’s default text editor prompting you for a message. You can customize this action by setting what command you want to invoke to open a text editor, for example:

Choose one of them (nano is likely the easiest) and run the following command:

git config --global core.editor "nano"

Default branch name

Recently GitHub has changed to main as the default branch. We need our local git command to respect that:

git config --global init.defaultBranch main

Miscellaneous Settings

Operating systems implement new lines differently. Here you will configure git to automatically normalize the line feed to properly match the platform:

git config --global core.autocrlf input

Since Git 2.0, Git has updated its default push settings. To avoid getting a warning when you push (we will explain what push means soon), apply the following setting:

git config --global push.default simple

You can double check your settings using the following command:

git config --list

Github Profile

You need to update your profile to include your name and SSH public key. There are also some optional settings you can change such as your profile picture and email notifications.

In your profile settings:

In your SSH key settings:

In your notification settings, apply the following settings:

Homework grade reports are released through GitHub, and using the above settings will ensure that you receive email notifications when your grade report is available.