« Back to the main CS 300 website
Lab 0: Getting Set Up (Docker & Git)
Due Tuesday, January 30th, at 8:00 PM EST
Introduction
Welcome to your first lab! The main focus will be to get you set up with the tools we’ll be using throughout CS 300, and give you an intuitive understanding of each tool.
The main tools we’ll be using are Docker, a convenient way to manage virtual environments as “containers”, and Git, the most prominent version control software.
Tool |
Use |
Docker |
Software environment virtualization |
Git |
Version control software |
GitHub |
Online code storage and version control |
- You’ll be able to develop locally. With virtualization, we can specify a standard development environment on any machine, so your code will work no matter where it’s run. (You won’t need to log into the CIT department machines to write, test, or hand in your code. However, you can use the department machines if you want; read on.)
- Version control is awesome. All changes to your code are tracked and can be reverted, making testing and debugging significantly more bearable. Your changes are also semi-automatically merged with other people’s, making collaboration easy. CS 300 has no partner assignments, but version control will be useful for other courses that do.
- It’s how it’s done in the industry. Most companies use some form of version-control in order to better manage projects and collaboration, and use machine virtualization and containers for easier deployment and testing.
What if I don’t have my own computer?
- For students who don’t have access to their own laptop, the Brown IT Service provides loaner laptops for free.
- Please contact us if you have any issues working on your own computer or cannot obtain a computer.
- Our development environment (the “course container”) and assignments work on the department machines, so you can always use machines in CIT to do your work if necessary. ee this section for some special instructions to follow as you read the rest of this guide.
Note: If you run into issues with your Docker at any point during the course, please reference the under the Resources tab on the course website.
Development Environment Setup
Your computer is probably running Mac OS X, Windows, or Linux! These different operating systems all come with different libraries and preinstalled software. A Virtual Machine (VM) can establish the same software environment for everyone.
Software inside a VM believes it is running on a physical computer, even though it is running within an OS within another computer. Achieving this level of virtualization has costs (in terms of computation and energy), including the cost of emulating the underlying hardware.
In this class, we will use a container, a technology that emulates an OS without the full overhead of a VM. The container runs a Linux-based operating system, Ubuntu. Our grading server also runs a Linux-based OS (Debian), so if your code works in the container, it will work on the grading server.
(Optional reading) Virtual machines vs. containers?
We will talk about this in the OS section of the course. But if you’re curious, here is a more detailed walk-through of the differences between a Virtual Machine and a container.
Docker
Docker is one of the most popular container solutions and widely used in industry. In CS 300, we use Docker because it lets you run a course container on Windows, macOS, or Linux.
Task: Download and install Docker.
You may download Docker here. On Linux machines, follow the instructions here.
After downloading Docker, follow Docker’s instructions to install it on your OS. Accept if Docker asks for privileged access.
On Windows or macOS, open the Docker Desktop application after it has been installed. You may see a message similar to “Docker Desktop is Starting…”. Once this message goes away, your Docker has started successfully!
Verify Docker is installed by executing the following command in a terminal:
$ docker --version
A Docker version number should be printed.
After installing Docker, a Docker process (the Docker daemon) will run in the background. Run the following command to verify:
$ docker info
This should print some information about your Docker installation.
If you see the following error:
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
it means Docker hasn’t started running yet. On Windows or macOS, ensure your Docker Desktop is running. On Linux, try the command sudo systemctl docker restart
in a terminal.
If you’re running into other problems while setting up Docker, check out our Docker debugging guide here!
Windows-based computers only
To run the following steps in this lab, you will need to set up Windows Subsystem for Linux (WSL). WSL should already be enabled after you install Docker, but you may still need to install a Linux distribution. This will run in an actual Linux VM, and you will run your Docker container within that VM (turtles all the way down for you!).
- Verify that Hyper-V/Virtual Machine Platform is enabled
- Hyper-V/Virtual Machine Platform are Windows’s hardware virtualization products, which may be required to build containers, use WSL, and install Docker. To verify that these are enabled, go to Settings > Apps > Optional Features > More Windows Features, and verify that the boxes for “Hyper-V” and “Virtual Machine Platform” are checked. (If they are not present, do not worry about them). From here, follow the system prompts. Proceed to step 2.
- Do I have a Linux distribution (Linux distro) installed?
- Run
wsl -l -v
in the Command Prompt or Powershell. If there is only “Docker Desktop” and “Docker Desktop Data”, you do not have a Linux distribution installed. Proceed to step 3.
- Otherwise, you have a Linux distro installed. Proceed to step 4.
- Install a Linux Distribution.
- Run
wsl --set-default-version 2
to ensure Ubuntu will be installed under WSL 2.
- Install “Ubuntu 20.04” from Microsoft Store. (link here)
- Click “Open” after Ubuntu is downloaded. A terminal will open and guide you through the installation process.
- Ensure your Linux Distribution runs on WSL 2.
- From the output of
wsl -l -v
, find out if your Linux distro is using WSL 1 or WSL 2. If it’s WSL1:
- Run
wsl --set-version <distro name> 2
to update your distro to use WSL 2.
- Set your default Linux distro
- Run
wsl --setdefault <distro-name>
to configure your default Linux distro. <distro-name>
should be “Ubuntu-20.04” if you installed using step 2.
Enter wsl
in your Command Prompt or Powershell, and you’ll enter into your WSL! For the rest of the lab, run commands within your WSL Linux environment, unless otherwise specified.
You will also need to connect Docker with WSL. To do so, open your Docker Desktop’s settings (on its top right corner), click “Resources”, “WSL integration”, then enable integration with your Linux distro. Then, click “Apply and Restart”.
Set up CS 300 Docker Environment
In Docker, an environment is defined as a Docker image. An image specifies the operating system environment that a container provides. An image can also contain additional software dependencies and configurations.
Next, you will download the the course’s setup code and create the CS 300 Docker image!
macOS only: install Apple development tools
If you’re running on macOS, you will need to install a set of Apple-recommended command-line tools via the following command:
xcode-select --install
This ensures that your computer has installed git
, a program we’ll use below. Alternatively, you may also download and install git
directly, following instructions here.
Task: Do the following to set up your development environment.
- Enter the directory on your computer where you want to do your coursework. For Windows users, choosing somewhere in the C drive will make the following steps easier.
Then, enter the following command to download our development environment to the new subdirectory YOUR_DIRECTORY
. Choose your own name (e.g., cs300
) instead of our placeholder YOUR_DIRECTORY
.
To do so, replace YOUR_DIRECTORY
in the git command below with whatever you choose:
$ git clone https://github.com/csci0300/cs300-s24-devenv.git YOUR_DIRECTORY
This command clones a GitHub repository onto your computer; we will explain the details of Git and cloning later in this lab.
-
Run cd YOUR_DIRECTORY
to enter the directory you have just created (e.g., cd cs300
if you called your directory cs300
).
-
Inside this folder, do the following:
$ ./cs300-run-docker setup
./cs300-run-docker setup
downloads your Docker image, which may take a while. (It’s normal for this script to run for up to 15 minutes.)
You can ignore messages about logging into your Docker account or scanning for vulnerabilities.
Why are there two Dockerfiles?
You may notice that there are two Dockerfiles in the docker
folder: Dockerfile
and Dockerfile.arm64
. Why are there two Dockerfiles, when CS 300 only uses one container?
Machines run on different architectures, and we will explore that in our course during the semester. Computers that use an Intel chip runs on Intel’s x86 architecture. Recent Macs released by Apple begin to use Apple silicon, which run on the ARM architecture.
Different architectures use different sets of CPU instructions. Therefore, programs running on different architectures need to be compiled differently.
Some CS 300 projects are designed to run on the x86 architecture. When running these projects on a different architecture (e.g., on an Apple M1 machine), they must be cross-compiled to use x86 instructions.
For students running on ARM machines, our scripts use Dockerfile.arm64
, which installs additional packages to compile x86 binaries on an ARM machine. Other students, running on chips that use the x86 architecture, use Dockerfile
.
Entering the container
Once you created your Docker image, you will want to create a container running this image.
⚠️ Renaming or moving the development environment ⚠️
If you can, please avoid renaming or moving the folder containing your CS 300 development environment after this step. Doing so will require you to create a new course container because Docker stores some path names in its internal data, and renaming the folder breaks those paths.
Task: and explore it by running a few commands. Then, exit the container by exit
, or Ctrl-D.
Windows users: use the Windows-specific instructions below instead.
Make sure you’re inside directory YOUR_DIRECTORY
(e.g., cs300
) when running the command below.
$ ./cs300-run-docker
cs300-user@9899143429a2:~$
cs300-user@9899143429a2:~$ uname
Linux
cs300-user@9899143429a2:~$ echo "Hello world!"
Hello world!
cs300-user@9899143429a2:~$ ls -lah
total 24K
drwxr-xr-x 6 cs300-user cs300-user 192 Jan 25 22:23 .
drwxr-xr-x 1 root root 4.0K Jan 25 22:25 ..
-rw-r--r-- 1 cs300-user cs300-user 132 Jan 25 22:23 .bash_profile
-rw-r--r-- 1 cs300-user cs300-user 4.0K Jan 25 22:23 .bashrc
-rw-r--r-- 1 cs300-user cs300-user 25 Jan 25 22:23 .gdbinit
-rw-r--r-- 1 cs300-user cs300-user 813 Jan 25 22:23 .profile
cs300-user@9899143429a2:~$ exit
Don’t worry if the number after cs300-user
is different. This is an identifier that uniquely identifies this container.
You may run any Linux commands inside this container. To exit, enter exit
or use Ctrl-D.
Instructions for Windows only
If you see errors along the lines of bash: '\r': command not found
or bash: /home/cs300-user/.bash_profile: line 5: syntax error: unexpected end of file
when you enter the container, you need to convert your files’ line endings (characters that delineate the end of a line) from Windows to UNIX (Linux) format.
To do so, do the following:
- Enter into WSL. You may do so by opening Ubuntu in the start menu or through the
wsl
command.
- Use
cd
to navigate to the folder where you just cloned the setup repository. If you cloned your setup repository to your C: drive, use cd /mnt/c
to enter the C: drive from your WSL.
- Run
sudo apt-get update
, then install dos2unix
with sudo apt-get -y install dos2unix
.
- Run
dos2unix ./cs300-run-docker
(you should only need to run this once).
- Next, run
./cs300-run-docker
.
- If you see the next line begins with
cs300-user@@9899143429a2:~$ ...
, you’re inside the container, hopefully without errors!
Shared Folders
“If my Docker container is a separate (virtual) computer than my laptop, how will I move files between the two?”, you may ask. Great question! You’ll move files between the two in any of the ways you can move files between any two computers! (Bear with us!)
To get files to and from department machines, you may have used things like scp
, sftp
, and Cyberduck, which allow you to copy files over the network. These work, but are inconvenient if you’re constantly moving them back and forth. (Git would technically also fall under this category, even though it’s fancier, as you’ll find out shortly.)
If you’re lucky, you may have been exposed to FUSE and sshfs
, which allow you to mount a filesystem over the network. This allows your computer to navigate the remote files as if they were stored locally, which means any changes you make are happening on both ends automatically.
Inside of the container, your home directory (/home/cs300-user
, or ~
) is actually a mount of the home
directory inside your development environment directory (i.e., YOUR_DIRECTORY
from earlier, such as cs300
). Any changes you make in one will be visible in the other.
Important extra setting for macOS users: change filesystem sync configuration
Many students have reported issues with syncing files in their mounted home directory issues on MacOS. This might be caused by gRPC FUSE, the default file system sharing implementation of Docker.
VirtioFS
Task: Outside of the container, go into your [YOUR_DIRECTORY]/home
folder, and create a file and a folder. Then, go into your container, delete that file, and add a file to the folder. This is so you get a feel for what is going on, since you’ll be using this on a regular basis!
Help
Outside of the container, in your [YOUR_DIRECTORY]/home
folder:
$ touch cool_file
$ mkdir awesome_folder
$ cd ..
$ ./cs300-run-docker
Inside the container:
cs300-user@9899143429a2:~$ ls
awesome_folder cool_file
cs300-user@9899143429a2:~$ rm cool_file
cs300-user@9899143429a2:~$ cd awesome_folder
cs300-user@9899143429a2:~$ touch even_cooler_file
cs300-user@9899143429a2:~$ exit
Back outside the container:
$ cd home
$ ls
awesome_folder
$ cd awesome_folder
$ ls
even_cooler_file
If you move or rename your development environment folder…
Your Docker container will still try to mount to the original path, even after you rename, remove, or move the folder YOUR_DIRECTORY
.
After moving your development environment folder, you’ll need to delete the old container and start a new container. You can do so with:
./cs300-run-docker --clean
You should be able to enter a container, and see all of your work now!
Text Editors and IDEs
What development environment or editor to use is a question that divides people and has led to countless hours being wasted on heated discussion, offline and online for decades. Some people prefer very simple editors that run in their terminal, while others prefer graphical integrated development environments (IDEs). For CS 300, we don’t really care what you use – if it works for you, great!
To make your life easier, however, you probably want to use an editor with syntax highlighting for C and C++, the main programming languages we’ll use in CS 300.
You can edit your source code inside the course container, or on your normal operating system. Recall that the home directory inside the container is a mount of your local cs300/home
directory (or whatever you named it). This means that you can install any editor or IDE of your choice on your local machine, edit your files and work on your assignments locally, and all of your changes will be reflected in your container! You can then compile, build, and run your assignments inside your container. This is the power of mounting !
There are plenty of great choices for text editors. If you’re not sure which one to install, we recommend VS Code. It has very nice integration with our Docker container, and it’s nicely customizable with extensions.
How to link VS Code with the course Dev Environment
- Download and Install VS Code on your computer (not the course container) normally.
- Navigate to the extensions tab by clicking this icon on the left side of the screen:
- Search for and install the “Docker” and “Dev Containers” VS Code extensions via the extensions tab. Also install “WSL” if you are on Windows.
- Make sure your course container is running (either by connecting to it, or checking the docker desktop app).
- Click the green button in the bottom left of VS Code, then click “Attatch to running container” and select your CS300 course container:
- You can now open any folder you want to edit, and can get a terminal from your course container by clicking View > Terminal.
How to configure VS Code with C/C++
You can install the C/C++ extension for helpful features like code completion, syntax highlighting, markings of warnings, etc.
You might see the following error message:
cpptools client: couldn't create connection to server
To fix this, from the home directory of your container, run the following command:
cd cs300-user/.vscode-server && sudo chmod -R 755 extensions
Simple editors:
vim
is a classic, highly configurable editor that comes with many Linux distributions. It’s a multi-mode editor, meaning that you have to switch between modes (e.g., input, select, edit). It runs in the terminal, all functions are controlled by keystrokes and internal commands, and vim can be customized with plugins.
- Sublime Text is a modern, lightweight, cross-platform editor highly customizable via plugins and with a strong fulltext search.
IDEs:
- (Recommended) VS Code is a free IDE built by Microsoft, and has support for all major languages (including C and C++). It also comes with built-in Git integration. Runs on macOS, Linux, and Windows, as well as connection options to the class VM.
- CLion is a cross-platform IDE built by JetBrains specifically for C and C++ development. It helps you with code navigation, generation, and refactoring. Students qualify for free licenses. Runs on macOS, Linux, and Windows.
- Note that CLion is sometimes finicky to set up and configure however.
- XCode is Apple’s official free IDE for Mac and iOS app development, and supports C and C++ (in addition to various other languages). Runs on macOS.
Installing programs on Linux (in your course container)
Our containers come with a few programs pre-installed, but what if we want more? With a text-based interface like the command line, it’s quite difficult to navigate the web and find a suitable download link. Instead, we use a program called a package manager which can automatically download, install, and update programs. We’ll be using a manager called apt
. apt
can install many things, including tools to build (or compile), and debug your code. Our containers already come with these tools for your convenience.
To get practice using apt
, we’re going to install some fun (and useless) command line programs, but apt
is generally the way to go for installing almost anything on your course container.
Task: Install fortune
and cowsay
.
Within your container, use apt
to install:
fortune
- A program which outputs a random fortune when used.
cowsay
- A program that generates ascii-art of a cow saying text.
You will need to use sudo
, which runs commands with elevated privileges.
First, do:
$ sudo apt update
This builds an up-to-date index of packages available to download.
Then, for each package, do:
$ sudo apt install <PACKAGE>
Help
$ sudo apt install fortune
$ sudo apt install cowsay
If you’re having trouble…
If you cannot run fortune
or cowsay
after installing them, you may need to tell the terminal where to find these programs by adding their location to the “PATH”. You can do this by running the following command:
$ export PATH=$PATH:/usr/games
Now, try it out! you can type fortune
into your terminal to see a prediction for your semester, and can use cowsay by typing cowsay "<some string>"
.
cs300-user:~$ fortune
You will gain money by an illegal action.
cs300-user:~$ cowsay "What a strange fortune... At least I get some money!"
______________________________________
/ What a strange fortune... At least I \
\ get some money! /
--------------------------------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
Of course, apt
can also be used to install more serious programs, like vim
or emacs
.
Extra (optional) fun
fortune
generates text, and cowsay
can display text in a fun way. Is there any way to combine the two? Yes!
You’ll learn about how this works under the hood later, but data can be moved from one process to another using something called a pipe. By putting the |
pipe character between two commands, the output of the first will become the input of the second.
Try it out by running:
cs300-user:~$ fortune | cowsay
Custom packages and ./cs300-run-docker --clean
Running ./cs300-run-docker --clean
will remove any custom packages that you have installed. This is because --clean
removes any existing cs300 containers on your system.
Fortunately, you should be able to re-install your packages with apt
using your new-found package installation skills!
If you have custom configurations for your packages, (e.g., a .vimrc
file for vim
), the configurations are persisted even if you have used --clean
. This is because user-specific configurations are stored in ~
(or its sub-directories), which are just a mount of your [YOUR_DIRECTORY]/home
directory on your machine.
Git
Git is an awesome version control tool for your code. In essence, it allows you to continuously save your project as a sequence of small changes instead of one final thing. Some of the cool things this grants you are:
- Reverting changes in case your code breaks.
- Merging changes with partners, even if you’re working on the same file.
- Having multiple branches, to test out implementations without ruining your code.
- Retrieving stencil code and handing in solutions, like you’ll be doing throughout the semester!
Learning Git
There are a ton of resources out there to learn about Git, so we won’t try to recreate them. Instead, we’ll link you to a few tutorials, and encourage you to find more on your own!
Git inside and outside the course container
You can either run Git commands outside your course container, or inside the course container. In the guide to follow we generally assume the latter, but the former is preferable if you have already set up Git on your computer—it’s a matter of preference.
Before you start running Git commands, you’ll need to configure your name and email in Git.
Task: Set your name and email in Git. The examples
cs300-user@9899143429a2:~$ git config --global user.name "Jennifer Stevenson"
cs300-user@9899143429a2:~$ git config --global user.email "jennifer_stevenson@brown.edu"
If you are not already signed up to GitHub with your brown.edu
email address, add it to your profile so that GitHub knows to correctly attribute commits to your username.
Optional: you can cache your GitHub credentials to avoid entering them in each time.
cs300-user@9899143429a2:~$ git config --global credential.helper store
Now, take a look at some beginning Git tutorials.
Authenticating with GitHub
Now that you understand the basics of how Git works, you will need to authenticate Git on your container (or local machine) with GitHub so that you can push to and pull from your GitHub repos. To do this, we suggest using SSH, a popular protocol for passwordless authentication.
Task: Set up SSH authentication with GitHub. This form of authentication is more secure and, once configured, simpler to use than personal access tokens, which you may have used in prior classes. (If you want to continue using a personal access token, though, that is fine too.)
See the dropdowns below for detailed instructions if you’re unsure about how to do this.
Help: Where do I run these commands?
We suggest running these within your course container, so that you can run git push
and git pull
from within your container (which is where you’ll be doing all your work for this course.) As a reminder, you are in your course container if your terminal has a prompt that looks like this:
cs300-user@522562e7c6cc:~$
However, if you wish, you can also perform this SSH authentication setup in a normal terminal in MacOS or Linux, or in WSL on Windows. If you opt for this option, you will need to run git push
and git pull
from outside your container in the [YOUR_DIRECTORY]/home
directory instead.
Help: Detailed steps for SSH keypair authentication
1. First, generate a keypair to be used for authentication with GitHub using the following command:
cs300-user@9899143429a2:~$ ssh-keygen -t ed25519
It will then ask where you want to save the key files. Simply press Enter
to save it to the default location (home/cs300-user/.ssh/id_ed25519
).
Then, it will ask you for a passphrase. If you wish, enter a passphrase you will remember to secure your private key file. (You will have to type this password each time you git push
.) A passphrase is not strictly required; if you don’t specify one (just press enter), you won’t be prompted when interacting with Github.
To check that the key was successfully generated, run:
cs300-user@9899143429a2:~$ ls ~/.ssh
If you see an output like id_ed25519 id_ed25519.pub
, then you have successfully generated a keypair.
Extra steps for Windows only
Due to details with how your [YOUR_DIRECTORY]/home
folder is mounted in your container on Windows, extra steps are necesary for your SSH keypair to be usable within your container. (These steps are only necessary if you are a) on Windows and b) setting up GitHub authentication within your container.)
You need to apply the fix in this StackOverflow post. To perform this fix, run the following command in WSL (not in your course container).
$ echo -e "\n[automount]\noptions = \"metadata\"\n" | sudo tee -a /etc/wsl.conf
You will be prompted for a password. This is your WSL Ubuntu password, which you set when you installed Ubuntu in WSL.
After running this command, check that it worked by running the following:
$ sudo cat /etc/wsl.conf
If you see an output that ends with the following, then the fix worked.
[automount]
options = "metadata"
Once you have applied this fix, restart your computer. Then enter your container (not WSL) and run the following command:
cs300-user@9899143429a2:~$ chmod 600 ~/.ssh/id_ed25519
Then ensure this worked by running the following command:
cs300-user@9899143429a2:~$ ls -la ~/.ssh/id_ed25519
If the first characters of the output are -rw-------
, then you’re good to go. If they are -rwxrwxrwx
or something else, then the fix didn’t work. (In this case, please make an EdStem post.)
After you have done this, continue with the steps below.
2. Next, upload the public key file that you generated to GitHub.
First, you need to copy the public key to your clipboard. To do this, first print out the contents of your public key file:
cs300-user@9899143429a2:~$ cat ~/.ssh/id_ed25519.pub
You should see an output something like this:
ssh-ed25519 [random characters] cs300-user@522562e7c6cc
Select this entire line in your terminal and copy it. (To copy selected text from the terminal, use Ctrl+Shift+C
on Windows or Linux, or Cmd+C
on MacOS).
Then, you need to paste this public key into GitHub. To do this, open a browser and navigate to your GitHub account settings. Find the section of settings titled SSH and GPG keys. Then click New SSH key.
Put whatever you’d like for Title, leave Key type as Authentication Key, and for Key, paste in the line you copied from the terminal a moment ago. Then press Add SSH key to add the key.
3. Test the GitHub connection.
Before you move on, you should ensure this process worked. To test your connection with GitHub, run the following command (you may have to enter your key passphrase):
cs300-user@9899143429a2:~$ ssh -T git@github.com
If you see an output like this, simply type yes
:
The authenticity of host 'github.com (140.82.112.4)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])?
If you see an output like this, you’re good to go:
Hi [username]! You've successfully authenticated, but GitHub does not provide shell access.
GitHub Classroom Setup
We use GitHub Classroom to distribute the assignments throughout the semester. You will be working with two repositories: one for projects, and one for labs. Each will contain a directory for each project or lab.
Task: Accept the GitHub Classroom assignment for projects and labs, then clone each repo into your container.
Projects: Set up CS300 Projects 2024
Labs: Set up CS300 Labs 2024
Help
We recommend doing the steps below within your course container (especially if you followed our GitHub authentication tutorial above in your container), but you can do the following steps outside your container, but within the home
directory in your CS 300 development environment as well.
$ ./cs300-run-docker
cs300-user@9899143429a2:~$
- Inside or outside the container, clone each repo. Do this by going to the GitHub Repo link created by classrooms, and clicking Clone or download. Then go to the SSH tab and copy the URL in the box, and use it to clone like so:
$ git clone git@github.com:csci0300/cs300-s24-projects-YOURUSERNAME.git
$ git clone git@github.com:csci0300/cs300-s24-labs-YOURUSERNAME.git
… where YOURUSERNAME
is your GitHub username. The above commands assume that you have registered an SSH public key with GitHub; if you haven’t, we recommend following the steps above regarding authenticating with GitHub.
Once you cloned the repository, you should see the snake
in the cloned projects repo, and the lab0
directory in the cloned labs repo. These are the only assignments we’ve released so far; you will add others later.
Exercise
At this point, you have your version control set up. Let’s do a quick exercise to practice your newfound Git skills. The results of this part of the lab are what you hand in at the end.
Inside the lab0
ee a file hello_world.c
. This is a Hello World program, and is the one you’ll make changes to. To run the program you need to compile it first (we will cover compilation in detail in a later lab). For now, just use the following commands:
$ gcc hello_world.c -o hello_world
$ ./hello_world
Note: Make sure you do everything inside of your container.
Task:
- Modify the program so it prints the following tounge twister:
Oh, Shelley? She sells seashells by the shilling. Silly, selling Shelley.
- Then, commit and push your changes.
Help
Committing and pushing:
$ git add hello_world.c
$ git commit -m "Added tounge twister."
$ git push
You have now committed your changes to Git and they are stored in the version history (git log
should show your new commit!). You’ve also pushed the new commit to GitHub’s servers. Next, you’ll set up the grading server and hand in this lab.
Handin Instructions
Head over to the grading server. If you were registered for CS 300 on the first day of classes, you should have received credentials by email.
If you only recently registered or you’re shopping the course but haven’t registered, you won’t have an account yet. In that case, please complete this form and wait until you receive your credentials. We will create accounts based on the form entries at 8pm every day.
Step 1: Log into the grading server with the password you received. Once you’re logged in, enter your GitHub username (at the top).
Step 2: Add the repository URL under the “Labs” category. Click “Labs” to initiate a fetch of your repository from GitHub.
Note: If your GitHub account is not linked to your Brown email address, the grading server will give you a command to run to verify your repository.
Step 3: You should see your commit listed on the Labs page, as shown above. You’ll also see a button labeled “Lab 0 checkoff”. Click this button to have your lab submission checked off and graded.
You should see a screen similar to this one, with a grade of 2 points for Lab 0:
Step 4: Use your anonymous ID located at the top right corner of the grading server to fill out this quick Diversity Survey.
- Each question within the form is optional, and we will never tie this information back to your actual identity.
- We will only use this form to assess how diverse our student body is, and to check and correct for any bias in grading.
- We will delete your responses at the end of CS 300.
Step 5: If you have not already signed up for section, go do so now! Here’s how it works:
- Identify section times that you can make from our section schedule.
- Enroll in one of the sections (C01-C10) for CSCI 0300 (even if you are taking CSCI 1310, the master’s-level course, or if you are in the remote section).
Some more general information on sections:
- Sections will take place every week. They aim to give you an opportunity to interact with the course content, other students, and TAs in a smaller, more personalized setting.
- Sections will consist of approximately 25 students and are led by either two TAs or one of the instructors. Students and their instructor will have the same section throughout the semester.
- Sections will take place during section weeks (see the course calendar) and run from Thursday to Wednesday.
- There will be eight sections throughout the semester and your attendance at section is mandatory. Section instructors will take attendance during section.
Filling out both the diversity survey and registering for section is required and your grade for Lab 0 and Lab 1 will depend on whether you filled this out (even if you passed the checkoff on the grading server!).
Finally, an opportunity to help future CS 300 students…
This year, we are offering the optional opportunity for a few students to participate in a CS 300 beta program, where we will test new technologies for future iterations of the course before rolling them out to all students.
As part of the beta program this year, you will submit your assignments to two grading servers: the normal grading server, and a “beta” grading server that runs new tech (specifically, it uses Docker containers on the grading server). We will use your experience and feedback to improve the next generation grading server.
Note that:
- Joining the beta program makes most sense if you’re excited about systems and infrastructure and want to altruistically help future generations of CS 300 students have a better experience; there is no gain for you beyond satisfaction, and you will spend some more time on assignment
- ing on interest, not all interested students may be able to join the beta program.
- All of your actual handins and grading will happen via the normal grading server.
- The beta grading server may go down without warning.
- The course staff will not offer any support for using the beta grading server.
If you’d like to take part in the CS 300 beta program, please submit this form.
Congratulations, you’ve completed Lab 0 and are set up for CS 300!
Appendix
This section contains extra instructions for special cases when setting up the development environment. You can ignore it unless you’ve specifically been referred to this section.
Using department machines
If you are interested in using the container environment on department systems, you will need to follow a slightly different set up process to configure your development environment. On department systems, our container environment uses a different tool instead of Docker called Podman, which is better designed for systems with many users, like on department systems. Most of the time, you won’t need to worry about this, but you’ll need to follow a slightly different procedure to set up your environment now.
Please read the following instructions and keep them in mind as you do the rest of the lab 0 setup:
- Before setting up Docker, visit this page and follow the instructions in the “Opt-In” section or instructions on how to enable support on your account. Then, you should be able to log into a department system and follow the instructions in this guide.
- In the section “Set up CS300 Docker Environment”, please run the following command instead of
./cs300-run-docker setup
:
$ ./cs300-run-docker build-image
This command compiles a special container image designed to run on department machines, which may take 15-20 minutes. After it completes, you can proceed with the rest of the setup.
- In general, you may notice that
./cs300-run-docker
may take 1-2 minutes each time you run it–this is expected, as department systems need to do extra work when you run this command
« Back to the main CS 300 website
Lab 0: Getting Set Up (Docker & Git)
Due Tuesday, January 30th, at 8:00 PM EST
Introduction
Welcome to your first lab! The main focus will be to get you set up with the tools we’ll be using throughout CS 300, and give you an intuitive understanding of each tool.
The main tools we’ll be using are Docker, a convenient way to manage virtual environments as “containers”, and Git, the most prominent version control software.
Why are we using these tools?
What if I don’t have my own computer?
Note: If you run into issues with your Docker at any point during the course, please reference the Docker Debugging Guide under the Resources tab on the course website.
Development Environment Setup
Your computer is probably running Mac OS X, Windows, or Linux! These different operating systems all come with different libraries and preinstalled software. A Virtual Machine (VM) can establish the same software environment for everyone.
Software inside a VM believes it is running on a physical computer, even though it is running within an OS within another computer. Achieving this level of virtualization has costs (in terms of computation and energy), including the cost of emulating the underlying hardware.
In this class, we will use a container, a technology that emulates an OS without the full overhead of a VM. The container runs a Linux-based operating system, Ubuntu. Our grading server also runs a Linux-based OS (Debian), so if your code works in the container, it will work on the grading server.
(Optional reading) Virtual machines vs. containers?
We will talk about this in the OS section of the course. But if you’re curious, here is a more detailed walk-through of the differences between a Virtual Machine and a container.
Docker
Docker is one of the most popular container solutions and widely used in industry. In CS 300, we use Docker because it lets you run a course container on Windows, macOS, or Linux.
Task: Download and install Docker.
You may download Docker here. On Linux machines, follow the instructions here.
After downloading Docker, follow Docker’s instructions to install it on your OS. Accept if Docker asks for privileged access.
On Windows or macOS, open the Docker Desktop application after it has been installed. You may see a message similar to “Docker Desktop is Starting…”. Once this message goes away, your Docker has started successfully!
Verify Docker is installed by executing the following command in a terminal:
$ docker --version
A Docker version number should be printed.
After installing Docker, a Docker process (the Docker daemon) will run in the background. Run the following command to verify:
$ docker info
This should print some information about your Docker installation.
If you see the following error:
it means Docker hasn’t started running yet. On Windows or macOS, ensure your Docker Desktop is running. On Linux, try the command
sudo systemctl docker restart
in a terminal.If you’re running into other problems while setting up Docker, check out our Docker debugging guide here!
Windows-based computers only
To run the following steps in this lab, you will need to set up Windows Subsystem for Linux (WSL). WSL should already be enabled after you install Docker, but you may still need to install a Linux distribution. This will run in an actual Linux VM, and you will run your Docker container within that VM (turtles all the way down for you!).
wsl -l -v
in the Command Prompt or Powershell. If there is only “Docker Desktop” and “Docker Desktop Data”, you do not have a Linux distribution installed. Proceed to step 3.wsl --set-default-version 2
to ensure Ubuntu will be installed under WSL 2.wsl -l -v
, find out if your Linux distro is using WSL 1 or WSL 2. If it’s WSL1:wsl --set-version <distro name> 2
to update your distro to use WSL 2.wsl --setdefault <distro-name>
to configure your default Linux distro.<distro-name>
should be “Ubuntu-20.04” if you installed using step 2.Enter
wsl
in your Command Prompt or Powershell, and you’ll enter into your WSL! For the rest of the lab, run commands within your WSL Linux environment, unless otherwise specified.You will also need to connect Docker with WSL. To do so, open your Docker Desktop’s settings (on its top right corner), click “Resources”, “WSL integration”, then enable integration with your Linux distro. Then, click “Apply and Restart”.
Set up CS 300 Docker Environment
In Docker, an environment is defined as a Docker image. An image specifies the operating system environment that a container provides. An image can also contain additional software dependencies and configurations.
Next, you will download the the course’s setup code and create the CS 300 Docker image!
macOS only: install Apple development tools
If you’re running on macOS, you will need to install a set of Apple-recommended command-line tools via the following command:
xcode-select --install
This ensures that your computer has installed
git
, a program we’ll use below. Alternatively, you may also download and installgit
directly, following instructions here.Task: Do the following to set up your development environment.
Then, enter the following command to download our development environment to the new subdirectory
YOUR_DIRECTORY
. Choose your own name (e.g.,cs300
) instead of our placeholderYOUR_DIRECTORY
. To do so, replaceYOUR_DIRECTORY
in the git command below with whatever you choose:$ git clone https://github.com/csci0300/cs300-s24-devenv.git YOUR_DIRECTORY
This command clones a GitHub repository onto your computer; we will explain the details of Git and cloning later in this lab.
Run
cd YOUR_DIRECTORY
to enter the directory you have just created (e.g.,cd cs300
if you called your directorycs300
).Inside this folder, do the following:
$ ./cs300-run-docker setup
./cs300-run-docker setup
downloads your Docker image, which may take a while. (It’s normal for this script to run for up to 15 minutes.)You can ignore messages about logging into your Docker account or scanning for vulnerabilities.
Why are there two Dockerfiles?
You may notice that there are two Dockerfiles in the
docker
folder:Dockerfile
andDockerfile.arm64
. Why are there two Dockerfiles, when CS 300 only uses one container?Machines run on different architectures, and we will explore that in our course during the semester. Computers that use an Intel chip runs on Intel’s x86 architecture. Recent Macs released by Apple begin to use Apple silicon, which run on the ARM architecture.
Different architectures use different sets of CPU instructions. Therefore, programs running on different architectures need to be compiled differently.
Some CS 300 projects are designed to run on the x86 architecture. When running these projects on a different architecture (e.g., on an Apple M1 machine), they must be cross-compiled to use x86 instructions.
For students running on ARM machines, our scripts use
Dockerfile.arm64
, which installs additional packages to compile x86 binaries on an ARM machine. Other students, running on chips that use the x86 architecture, useDockerfile
.Entering the container
Once you created your Docker image, you will want to create a container running this image.
⚠️ Renaming or moving the development environment ⚠️
If you can, please avoid renaming or moving the folder containing your CS 300 development environment after this step. Doing so will require you to create a new course container because Docker stores some path names in its internal data, and renaming the folder breaks those paths.
Task: Enter your container and explore it by running a few commands. Then, exit the container by
exit
, or Ctrl-D.Windows users: use the Windows-specific instructions below instead.
Make sure you’re inside directory
YOUR_DIRECTORY
(e.g.,cs300
) when running the command below.$ ./cs300-run-docker # enters your Docker container cs300-user@9899143429a2:~$ # you're inside the container! cs300-user@9899143429a2:~$ uname Linux cs300-user@9899143429a2:~$ echo "Hello world!" Hello world! cs300-user@9899143429a2:~$ ls -lah total 24K drwxr-xr-x 6 cs300-user cs300-user 192 Jan 25 22:23 . drwxr-xr-x 1 root root 4.0K Jan 25 22:25 .. -rw-r--r-- 1 cs300-user cs300-user 132 Jan 25 22:23 .bash_profile -rw-r--r-- 1 cs300-user cs300-user 4.0K Jan 25 22:23 .bashrc -rw-r--r-- 1 cs300-user cs300-user 25 Jan 25 22:23 .gdbinit -rw-r--r-- 1 cs300-user cs300-user 813 Jan 25 22:23 .profile cs300-user@9899143429a2:~$ exit # or Ctrl-D
Don’t worry if the number after
cs300-user
is different. This is an identifier that uniquely identifies this container.You may run any Linux commands inside this container. To exit, enter
exit
or use Ctrl-D.Instructions for Windows only
If you see errors along the lines of
bash: '\r': command not found
orbash: /home/cs300-user/.bash_profile: line 5: syntax error: unexpected end of file
when you enter the container, you need to convert your files’ line endings (characters that delineate the end of a line) from Windows to UNIX (Linux) format.To do so, do the following:
wsl
command.cd
to navigate to the folder where you just cloned the setup repository. If you cloned your setup repository to your C: drive, usecd /mnt/c
to enter the C: drive from your WSL.sudo apt-get update
, then installdos2unix
withsudo apt-get -y install dos2unix
.dos2unix ./cs300-run-docker
(you should only need to run this once)../cs300-run-docker
.cs300-user@@9899143429a2:~$ ...
, you’re inside the container, hopefully without errors!Shared Folders
“If my Docker container is a separate (virtual) computer than my laptop, how will I move files between the two?”, you may ask. Great question! You’ll move files between the two in any of the ways you can move files between any two computers! (Bear with us!)
To get files to and from department machines, you may have used things like
scp
,sftp
, and Cyberduck, which allow you to copy files over the network. These work, but are inconvenient if you’re constantly moving them back and forth. (Git would technically also fall under this category, even though it’s fancier, as you’ll find out shortly.)If you’re lucky, you may have been exposed to FUSE and
sshfs
, which allow you to mount a filesystem over the network. This allows your computer to navigate the remote files as if they were stored locally, which means any changes you make are happening on both ends automatically.Inside of the container, your home directory (
/home/cs300-user
, or~
) is actually a mount of thehome
directory inside your development environment directory (i.e.,YOUR_DIRECTORY
from earlier, such ascs300
). Any changes you make in one will be visible in the other.Important extra setting for macOS users: change filesystem sync configuration
Many students have reported issues with syncing files in their mounted home directory issues on MacOS. This might be caused by gRPC FUSE, the default file system sharing implementation of Docker.
To resolve this, go into your Docker settings and make sure that the sync method is set to
VirtioFS
. Look here for detailed instructions on how to do this.Task: Outside of the container, go into your
[YOUR_DIRECTORY]/home
folder, and create a file and a folder. Then, go into your container, delete that file, and add a file to the folder. This is so you get a feel for what is going on, since you’ll be using this on a regular basis!Help
Outside of the container, in your
[YOUR_DIRECTORY]/home
folder:$ touch cool_file $ mkdir awesome_folder $ cd .. $ ./cs300-run-docker
Inside the container:
cs300-user@9899143429a2:~$ ls # print the file and dir we just created awesome_folder cool_file
cs300-user@9899143429a2:~$ rm cool_file cs300-user@9899143429a2:~$ cd awesome_folder cs300-user@9899143429a2:~$ touch even_cooler_file cs300-user@9899143429a2:~$ exit # or just CTRL-D
Back outside the container:
$ cd home # this enters the mounted directory $ ls # should just show awesome_folder awesome_folder $ cd awesome_folder $ ls # should show even_cooler_file even_cooler_file
If you move or rename your development environment folder…
Your Docker container will still try to mount to the original path, even after you rename, remove, or move the folder
YOUR_DIRECTORY
.After moving your development environment folder, you’ll need to delete the old container and start a new container. You can do so with:
You should be able to enter a container, and see all of your work now!
Text Editors and IDEs
What development environment or editor to use is a question that divides people and has led to countless hours being wasted on heated discussion, offline and online for decades. Some people prefer very simple editors that run in their terminal, while others prefer graphical integrated development environments (IDEs). For CS 300, we don’t really care what you use – if it works for you, great!
To make your life easier, however, you probably want to use an editor with syntax highlighting for C and C++, the main programming languages we’ll use in CS 300.
You can edit your source code inside the course container, or on your normal operating system. Recall that the home directory inside the container is a mount of your local
cs300/home
directory (or whatever you named it). This means that you can install any editor or IDE of your choice on your local machine, edit your files and work on your assignments locally, and all of your changes will be reflected in your container! You can then compile, build, and run your assignments inside your container. This is the power of mounting !There are plenty of great choices for text editors. If you’re not sure which one to install, we recommend VS Code. It has very nice integration with our Docker container, and it’s nicely customizable with extensions.
How to link VS Code with the course Dev Environment
How to configure VS Code with C/C++
You can install the C/C++ extension for helpful features like code completion, syntax highlighting, markings of warnings, etc.
You might see the following error message:
To fix this, from the home directory of your container, run the following command:
Simple editors:
vim
is a classic, highly configurable editor that comes with many Linux distributions. It’s a multi-mode editor, meaning that you have to switch between modes (e.g., input, select, edit). It runs in the terminal, all functions are controlled by keystrokes and internal commands, and vim can be customized with plugins.IDEs:
Installing programs on Linux (in your course container)
Our containers come with a few programs pre-installed, but what if we want more? With a text-based interface like the command line, it’s quite difficult to navigate the web and find a suitable download link. Instead, we use a program called a package manager which can automatically download, install, and update programs. We’ll be using a manager called
apt
.apt
can install many things, including tools to build (or compile), and debug your code. Our containers already come with these tools for your convenience.To get practice using
apt
, we’re going to install some fun (and useless) command line programs, butapt
is generally the way to go for installing almost anything on your course container.Task: Install
fortune
andcowsay
.Within your container, use
apt
to install:fortune
- A program which outputs a random fortune when used.cowsay
- A program that generates ascii-art of a cow saying text.You will need to use
sudo
, which runs commands with elevated privileges.First, do:
$ sudo apt update
This builds an up-to-date index of packages available to download.
Then, for each package, do:
$ sudo apt install <PACKAGE>
Help
$ sudo apt install fortune $ sudo apt install cowsay
If you’re having trouble…
If you cannot run
fortune
orcowsay
after installing them, you may need to tell the terminal where to find these programs by adding their location to the “PATH”. You can do this by running the following command:$ export PATH=$PATH:/usr/games
Now, try it out! you can type
fortune
into your terminal to see a prediction for your semester, and can use cowsay by typingcowsay "<some string>"
.Of course,
apt
can also be used to install more serious programs, likevim
oremacs
.Extra (optional) fun
fortune
generates text, andcowsay
can display text in a fun way. Is there any way to combine the two? Yes! You’ll learn about how this works under the hood later, but data can be moved from one process to another using something called a pipe. By putting the|
pipe character between two commands, the output of the first will become the input of the second.Try it out by running:
Custom packages and
./cs300-run-docker --clean
Running
./cs300-run-docker --clean
will remove any custom packages that you have installed. This is because--clean
removes any existing cs300 containers on your system.Fortunately, you should be able to re-install your packages with
apt
using your new-found package installation skills!If you have custom configurations for your packages, (e.g., a
.vimrc
file forvim
), the configurations are persisted even if you have used--clean
. This is because user-specific configurations are stored in~
(or its sub-directories), which are just a mount of your[YOUR_DIRECTORY]/home
directory on your machine.Git
Git is an awesome version control tool for your code. In essence, it allows you to continuously save your project as a sequence of small changes instead of one final thing. Some of the cool things this grants you are:
Learning Git
There are a ton of resources out there to learn about Git, so we won’t try to recreate them. Instead, we’ll link you to a few tutorials, and encourage you to find more on your own!
Git inside and outside the course container
You can either run Git commands outside your course container, or inside the course container. In the guide to follow we generally assume the latter, but the former is preferable if you have already set up Git on your computer—it’s a matter of preference.
Before you start running Git commands, you’ll need to configure your name and email in Git.
Task: Set your name and email in Git. The examples below assume that you’re doing it inside the container, but you can also do this on your computer if you prefer to use Git outside the container.
cs300-user@9899143429a2:~$ git config --global user.name "Jennifer Stevenson" cs300-user@9899143429a2:~$ git config --global user.email "jennifer_stevenson@brown.edu"
If you are not already signed up to GitHub with your
brown.edu
email address, add it to your profile so that GitHub knows to correctly attribute commits to your username.Optional: you can cache your GitHub credentials to avoid entering them in each time.
cs300-user@9899143429a2:~$ git config --global credential.helper store
Now, take a look at some beginning Git tutorials.
Task:
Read the Harvard CS 61 Intro to Git.
More Resources
Feel free to check out other resources to learn more!
Git – The Simple Guide – quick and dirty guide Git Handbook – in-depth introduction
Now that you understand the basics of how Git works, you will need to authenticate Git on your container (or local machine) with GitHub so that you can push to and pull from your GitHub repos. To do this, we suggest using SSH, a popular protocol for passwordless authentication.
Task: Set up SSH authentication with GitHub. This form of authentication is more secure and, once configured, simpler to use than personal access tokens, which you may have used in prior classes. (If you want to continue using a personal access token, though, that is fine too.)
See the dropdowns below for detailed instructions if you’re unsure about how to do this.
Help: Where do I run these commands?
We suggest running these within your course container, so that you can run
git push
andgit pull
from within your container (which is where you’ll be doing all your work for this course.) As a reminder, you are in your course container if your terminal has a prompt that looks like this:However, if you wish, you can also perform this SSH authentication setup in a normal terminal in MacOS or Linux, or in WSL on Windows. If you opt for this option, you will need to run
git push
andgit pull
from outside your container in the[YOUR_DIRECTORY]/home
directory instead.Help: Detailed steps for SSH keypair authentication
1. First, generate a keypair to be used for authentication with GitHub using the following command:
It will then ask where you want to save the key files. Simply press
Enter
to save it to the default location (home/cs300-user/.ssh/id_ed25519
).Then, it will ask you for a passphrase. If you wish, enter a passphrase you will remember to secure your private key file. (You will have to type this password each time you
git push
.) A passphrase is not strictly required; if you don’t specify one (just press enter), you won’t be prompted when interacting with Github.To check that the key was successfully generated, run:
If you see an output like
id_ed25519 id_ed25519.pub
, then you have successfully generated a keypair.Extra steps for Windows only
Due to details with how your
[YOUR_DIRECTORY]/home
folder is mounted in your container on Windows, extra steps are necesary for your SSH keypair to be usable within your container. (These steps are only necessary if you are a) on Windows and b) setting up GitHub authentication within your container.)You need to apply the fix in this StackOverflow post. To perform this fix, run the following command in WSL (not in your course container).
$ echo -e "\n[automount]\noptions = \"metadata\"\n" | sudo tee -a /etc/wsl.conf
You will be prompted for a password. This is your WSL Ubuntu password, which you set when you installed Ubuntu in WSL.
After running this command, check that it worked by running the following:
$ sudo cat /etc/wsl.conf
If you see an output that ends with the following, then the fix worked.
Once you have applied this fix, restart your computer. Then enter your container (not WSL) and run the following command:
cs300-user@9899143429a2:~$ chmod 600 ~/.ssh/id_ed25519
Then ensure this worked by running the following command:
cs300-user@9899143429a2:~$ ls -la ~/.ssh/id_ed25519
If the first characters of the output are
-rw-------
, then you’re good to go. If they are-rwxrwxrwx
or something else, then the fix didn’t work. (In this case, please make an EdStem post.)After you have done this, continue with the steps below.
2. Next, upload the public key file that you generated to GitHub.
First, you need to copy the public key to your clipboard. To do this, first print out the contents of your public key file:
cs300-user@9899143429a2:~$ cat ~/.ssh/id_ed25519.pub
You should see an output something like this:
Select this entire line in your terminal and copy it. (To copy selected text from the terminal, use
Ctrl+Shift+C
on Windows or Linux, orCmd+C
on MacOS).Then, you need to paste this public key into GitHub. To do this, open a browser and navigate to your GitHub account settings. Find the section of settings titled SSH and GPG keys. Then click New SSH key.
Put whatever you’d like for Title, leave Key type as Authentication Key, and for Key, paste in the line you copied from the terminal a moment ago. Then press Add SSH key to add the key.
3. Test the GitHub connection.
Before you move on, you should ensure this process worked. To test your connection with GitHub, run the following command (you may have to enter your key passphrase):
If you see an output like this, simply type
yes
:If you see an output like this, you’re good to go:
GitHub Classroom Setup
We use GitHub Classroom to distribute the assignments throughout the semester. You will be working with two repositories: one for projects, and one for labs. Each will contain a directory for each project or lab.
Task: Accept the GitHub Classroom assignment for projects and labs, then clone each repo into your container.
Projects: Set up CS300 Projects 2024
Labs: Set up CS300 Labs 2024
Help
We recommend doing the steps below within your course container (especially if you followed our GitHub authentication tutorial above in your container), but you can do the following steps outside your container, but within the
home
directory in your CS 300 development environment as well.$ ./cs300-run-docker cs300-user@9899143429a2:~$ # inside the container!
$ git clone git@github.com:csci0300/cs300-s24-projects-YOURUSERNAME.git $ git clone git@github.com:csci0300/cs300-s24-labs-YOURUSERNAME.git
… where
YOURUSERNAME
is your GitHub username. The above commands assume that you have registered an SSH public key with GitHub; if you haven’t, we recommend following the steps above regarding authenticating with GitHub.Once you cloned the repository, you should see the
snake
in the cloned projects repo, and thelab0
directory in the cloned labs repo. These are the only assignments we’ve released so far; you will add others later.Exercise
At this point, you have your version control set up. Let’s do a quick exercise to practice your newfound Git skills. The results of this part of the lab are what you hand in at the end.
Inside the
lab0
directory in your cloned labs repo, you should see a filehello_world.c
. This is a Hello World program, and is the one you’ll make changes to. To run the program you need to compile it first (we will cover compilation in detail in a later lab). For now, just use the following commands:$ gcc hello_world.c -o hello_world # to compile it $ ./hello_world # to run it
Note: Make sure you do everything inside of your container.
Task:
Help
Committing and pushing:
$ git add hello_world.c $ git commit -m "Added tounge twister." $ git push
You have now committed your changes to Git and they are stored in the version history (
git log
should show your new commit!). You’ve also pushed the new commit to GitHub’s servers. Next, you’ll set up the grading server and hand in this lab.Handin Instructions
Head over to the grading server. If you were registered for CS 300 on the first day of classes, you should have received credentials by email.
If you only recently registered or you’re shopping the course but haven’t registered, you won’t have an account yet. In that case, please complete this form and wait until you receive your credentials. We will create accounts based on the form entries at 8pm every day.
Step 1: Log into the grading server with the password you received. Once you’re logged in, enter your GitHub username (at the top).
Step 2: Add the repository URL under the “Labs” category. Click “Labs” to initiate a fetch of your repository from GitHub.
Note: If your GitHub account is not linked to your Brown email address, the grading server will give you a command to run to verify your repository.
Step 3: You should see your commit listed on the Labs page, as shown above. You’ll also see a button labeled “Lab 0 checkoff”. Click this button to have your lab submission checked off and graded.
You should see a screen similar to this one, with a grade of 2 points for Lab 0:
Step 4: Use your anonymous ID located at the top right corner of the grading server to fill out this quick Diversity Survey.
Step 5: If you have not already signed up for section, go do so now! Here’s how it works:
Some more general information on sections:
Filling out both the diversity survey and registering for section is required and your grade for Lab 0 and Lab 1 will depend on whether you filled this out (even if you passed the checkoff on the grading server!).
Finally, an opportunity to help future CS 300 students…
This year, we are offering the optional opportunity for a few students to participate in a CS 300 beta program, where we will test new technologies for future iterations of the course before rolling them out to all students.
As part of the beta program this year, you will submit your assignments to two grading servers: the normal grading server, and a “beta” grading server that runs new tech (specifically, it uses Docker containers on the grading server). We will use your experience and feedback to improve the next generation grading server.
Note that:
If you’d like to take part in the CS 300 beta program, please submit this form.
Congratulations, you’ve completed Lab 0 and are set up for CS 300!
Appendix
This section contains extra instructions for special cases when setting up the development environment. You can ignore it unless you’ve specifically been referred to this section.
Using department machines
If you are interested in using the container environment on department systems, you will need to follow a slightly different set up process to configure your development environment. On department systems, our container environment uses a different tool instead of Docker called Podman, which is better designed for systems with many users, like on department systems. Most of the time, you won’t need to worry about this, but you’ll need to follow a slightly different procedure to set up your environment now.
Please read the following instructions and keep them in mind as you do the rest of the lab 0 setup:
./cs300-run-docker setup
:This command compiles a special container image designed to run on department machines, which may take 15-20 minutes. After it completes, you can proceed with the rest of the setup.
./cs300-run-docker
may take 1-2 minutes each time you run it–this is expected, as department systems need to do extra work when you run this command