Lab 0: Orientation


Welcome to CS107e lab! Lab is one of the most beloved components of this course. Although we sadly can't share a physical space at this time, we aim to create a virtual lab experience brings us together to teach and learn from one another in the same great spirit of collaboration and community.

Goals

During this lab you will:

  • Start getting to know one another
  • Confirm working install of developer tools
  • Set up assignments repo
  • Practice with the command line and key tools such as your text editor
  • Review binary and hexadecimal number representations

How does lab work?

When you arrive at lab, say hello and introduce yourself to your labmates. Together you will tackle the exercises below. Everyone is encouraged to collaborate with other labmates to share insights and offer each other useful tips. You pair up and use private messages to exchange notes, or just talk to one another. The instructors and TAs will circulate to offer advice and answers so as to keep everyone progressing smoothly.

Lab is a time to experiment and explore. After we introduce topics in readings/lectures, you'll do guided exercises in lab to further your understanding of the material, get hand-on practice with the tools in a supported environment, and ready yourself to succeed at this week's assignment.

Bare metal programming requires precision. A trivial typo or slight misunderstanding can stop your progress cold. Working with the support of your classmates and staff can make the difference between quickly resolving that sticking point versus hours of frustration wrestling on your own in the dark.

Each lab has a set of check-in questions that we want you to answer as you go. Touch base with the staff on your answers to confirm your understanding and resolve any confusion. The check-in questions are intentionally simple and your responses are not graded; we use them as a gauge of how you're doing with the material so that we know better how to help guide you.

To get the most out of lab, don't set your goal at merely finishing the absolute minimum required in the shortest possible time. If you already have a good handle on the material, use the lab period to dive into further nooks and crannies or help out those peers who could benefit from your experience. You should also get to know the staff. They are masters of the craft, and you will learn a lot by talking to them and asking them questions. Any topic is fair game.

The combination of hands-on experimentation, give and take with your peers, and the expert guidance of our staff is what makes lab time truly special. Your sincere participation can really accelerate your learning!

Prelab preparation

To prepare, please do the following before coming to lab:

  1. Follow the instructions in installation guide to set up your environment.
  2. Review our guide to the Unix command line.

Lab exercises

When you start lab, pull up the check-in questions in your browser so you can refer to them as you go.

1. Confirm install

Use the Final check steps at the end of the installation guide to confirm that the needed tools are installed and your environment is correctly configured. If you hit any snags, bring those issues to lab and we can help you resolve.

2. Inventory your kit

You should have received your CS107e kit. Unpack and identify each part and compare to the kit inventory to ensure your kit is complete. Let us know without delay if any shortage so we can get you the missing supplies.

3. Set up your local assignments repository

Our course repositories will be hosted on GitHub. You will download assignment starter files from GitHub and upload your completed work to GitHub for grading. Each student will be given a private assignments repository inside our CS107e GitHub organization. The repository that resides on GitHub is your remote assignments repo. It will be connected to the local assignments repo on your computer where you will work on the assignments. Set up the local assignments rep by following the steps below. Be sure to ask for help if you run into any snags.

  • Step 1: Accept GitHub invitations

    You should have received two email invitations from GitHub: an invitation for read-only access to the starter code repo https://github.com/cs107e/assignments-mirror.git and another invitation for read-write access to your private assignments repo. Once you receive and accept both invitations, you're ready to proceed.

  • Step 2: Create SSH key and add to GitHub account

    In order to interact with GitHub from the command line, you'll need set up an SSH key on your GitHub account. An SSH key is a way to authenticate that you are who you say you are. To create an SSH key, enter the following command in your shell:

    $ ssh-keygen -t rsa -b 4096 -C "<your_email>"
    

    After you press enter, you'll be prompted to choose an alternate name for your key. Skip this by pressing enter again. Next, you'll be prompted to enter a passphrase for a key. If you want no passphrase, press enter. Otherwise, enter your passphrase. If you choose to add a passphrase, you must enter that passphrase each time you push to or pull from GitHub .

    Confirm the key has been created by looking for the key files in your .ssh directory:

    $ ls ~/.ssh/
    

    You should see two files: id_rsa and id_rsa.pub. SSH uses public-key cryptography, which requires a private key and a public key. id_rsa is your private key and should never be shared. id_rsa.pub is your public key and can (and should) be shared.

    Now add your new SSH key to your GitHub account by following these instructions.

  • Step 3: Clone assignments repo

    Note: In this step and the steps to follow, where you see [YOUR-GITHUB-USERNAME], replace with your actual GitHub username.

    After accepting the GitHub invitation and setting up your SSH key, you can now clone your assignments repo. In your browser, visit the page https://github.com/cs107e/[YOUR-GITHUB-USERNAME]-assignments to see the contents of your remote repo. It should have only a single file: README.md, which lists the name of your repo and nothing more. Upon confirming this, switch to the terminal and execute the following commands to clone the repo, which creates a local copy on your machine of the remote repo on GitHub. We recommend that you store your local repo in the parent directory cs107e_home that you made during the install process.

      $ cd ~/cs107e_home
      $ git clone git@github.com:cs107e/[YOUR-GITHUB-USERNAME]-assignments.git assignments
    

    Confirm that the local clone repo matches the remote repo by cd'ing and and examining its contents.

      $ cd assignments
      $ ls 
      $ cat README.md
    
  • Step 4: Create dev branch

    The master branch in your assignments repo is write-protected which means that you will not be able to directly modify the master branch on GitHub. Instead, you'll create a separate dev branch where you will do your work. To create this branch, change to your assignments repo and execute the following commands:

      $ cd ~/cs107e_home/assignments
      $ git branch
      $ git checkout -b dev
      $ git branch
    

    When you run the first git branch command, notice how there is only a single branch listed: master and there is an asterisk next to master, which means that it is the currently checked out branch. When you run the second git branch command, you should have two branches–master and dev–and the asterisk marking the currently checked out branch is now next to dev.

  • Step 5: Get starter files

    Next, you must configure your local assignments repo to have an additional remote connection to the starter code repo so that it can also synchronize with that repo. Execute the following commands to add a remote for starter-code

      $ git remote -v
      $ git remote add starter-code git@github.com:cs107e/assignments-mirror.git
      $ git remote -v
    

    After running the first git remote -v command, you should have only a single remote: origin. origin is a shorthand way of referring to your remote repo on GitHub. The git remote add command adds a second remote. This second remote is starter-code, which is a shorthand way of referring to the starter code repo on GitHub. The second git remote -v should show you both remotes: origin and starter-code and the URLs that they represent.

    To get the starter files, verify that you're on the dev branch and execute the following commands:

      $ git pull --allow-unrelated-histories starter-code assign0-starter 
      $ ls
    

    The git pull command will open up vim and display the message "Merge branch 'assign0-starter' of github.com:cs107e/assignments-mirror into dev". Confirm this merge by typing :x, which will save and exit vim. The ls command should show the addition of a second file–notes.txt–that was pulled down from the starter code repo when you executed the git pull.

  • Step 6: Create remote branch

    A few steps earlier, you created a dev branch in your repo. Unfortunately, this branch is only local. That is, it doesn't exist in your remote repo on GitHub yet. Let's fix this now. First confirm that you're on the dev branch. Then, run the following command:

      $ git push --set-upstream origin dev
    

    This command creates the dev branch on the origin remote (your GitHub repo) and connects this remote dev to your local dev.

    If you return to your GitHub repo in your browser, you should now find a dev branch in the branches dropdown menu.

Review our course guide on git for an introduction to git and links to further readings.

4. Website scavenger hunt

Our course website is where you'll find lecture slides, lab writeups, and assignment specifications, along with a trove of additional resources such as our course guides and curated set of readings, resources, and demos. We encourage you to explore a bit and become acquainted with what's available and how it's organized. The Search tab is handy way to find matching content across all pages on the site.

As you explore, see if you find answers to such questions as:

  • Oh no! I lost my copy of the pinout diagram for the Raspberry Pi A+. Where can I find a new copy of the one CS107E uses? (p.s… Is there an interactive version available as well?)
  • Where can I find the recommended readings to review before a lecture?
  • I have never used the gdb debugger before. Where do I start and where can I learn more?
  • I'm so sick of unplugging and replugging in my USB-serial adapter. Is there another solution? (For bonus points, find a link to a soldering tutorial!)
  • What is the course policy on late work?
  • Breadboards make no sense to me. How do I know which holes are connected?
  • Pat demo'ed this cool ARM simulator in lecture. How can I play with that myself?
  • I'm working really hard to write tests, but I just don't feel like I'm covering my bases. What am I doing wrong? Is there advice on software testing more broadly?
  • My partner and I are struggling to come up with project ideas. Are there examples of what other groups have done in the past?

If you're confused about a topic or want to learn more, check the website first and see if there's any information there. However, if you're confused, still curious, or can't find the information you need, that's why we're here! You should always feel comfortable coming to us with any questions you have, as well as suggestions on how we can improve the quality of the resources available to you.

5. Command line practice

Over the course of CS107E, you'll get comfortable navigating the command line. To start, read through and follow all the steps in our Unix Command Line Guide.

While that guide covers the basics, here's a couple more tricks to speed up your workflow. Practice using these—you'll be amazed at how much they boost your productivity!

  • Typing a long path of a file or directory? Use ✨tab-complete✨! When you press [tab], UNIX will automatically fill in your partially typed command. Try navigating to new directories in your file system and see what you can get to successfully tab-complete.
  • To replay a previous command, use your arrow keys (↑ and ↓) to move through the commands in your history. Type history and see everything you've done in this session.
  • Used a long command a while ago, but don't want to type it all out again? Search through your history with ctrl+r!
  • Want to go back to your home directory? Instead of typing cd ~, save a couple keystrokes with just cd.
  • To move to the beginning of the line, type ctrl+a. To get to the end, type ctrl+e. (p.s… these are the same in Emacs, which you'll learn about in a bit!)
  • To redirect the output of a command into a file (for example, if you wrote tests with a lot of output, which you want to be able to read through at your leisure), use the > symbol like this:
    $ command_with_long_output > new_file.txt
    
  • Want to look at the contents of a file without opening it in a text editor? Use cat, short for concatenate, like this:
    $ cat file_I_want_to_look.at
    
  • Use man to access the manual page for a command, including sample usage and list of option flags. For example, read man cp and find out what the -r option does. A handy website tool is http://explainshell.com which can be used to break down and explain a command and its options. Enter cp -r there to see an explanation.

Over time, you might learn about other helpful commands, like grep, diff, and echo. Curious about how to use these, or any other commands you've seen used? Get more information from the man page, explainshell, a google search, or other reference document. Make a point to learn a new command each day when you sit down to work and you'll soon be well on your way to becoming a command line ninja! 🔥

6. Editors

When you've taken CS classes in the past (like 106A/B/X), you've likely relied on IDEs (integrated development environments) like PyCharm, Qt, or Eclipse. While those are great for some tasks, we're going to rely on a new set of tools for this class: text editors. Have you ever opened a file in Notepad or TextEdit? The editors we'll be using, like Emacs and Vim, aren't too different at a basic level, except that they're built specifically for programming and can be configured to do all kinds of fancy things (although you don't need to worry about that for now).

XKCD Text Editors

Every programmer has their own (usually strongly held) opinion about which editor they prefer to use. Common choices are Emacs, Vim, Sublime, Nano, and VSCode. While these editors can often feel overwhelming at first—especially command line editors, like Emacs and Vim—you will be so grateful for the time you invest in learning them well during this class.

No matter which editor you decide to make your home base, we think it's a worthwhile investment for everyone to learn enough Emacs and Vim that you could open a file, make an edit, and save & close the file without any trouble (this skill will serve you well in the future, like if you have to quickly edit code on systems you've just ssh'ed into).

To start with, practice opening a new file named emacs_is_better.txt in the directory ~/ with emacs:

$ emacs ~/emacs_is_better.txt

If that worked, type away! Once you're ready to save your document and exit Emacs, type:

ctrl+x ctrl+s
ctrl+x ctrl+c

Now that you've tried Emacs, let's get a taste of Vim. To open a new file in ~/ named vim_is_better.txt, type:

$ vim ~/vim_is_better.txt

To edit in vim, there's actually another step. We need to switch out of command mode into insert mode. Type i and you should be able to start writing away! Once you feel ready to quit, type ESC (the escape character) and you'll be back into command mode. From there, to save and quit, type:

:wq

As long as you are able to open, edit, and exit in Emacs and Vim, you could attack any command line and start writing code (albeit, not very efficiently).

At this point, you might be wondering—why are programmers obsessed with these tools? There are a million tools that can edit text far more intuitively, from Google Docs to iMessage to a text box in MS Paint—and while that's all true, the benefit of these text editors is 1) agility & speed and 2) configurability.

Why are these tools so much faster? For one, they can be launched directly from the command line, as we'll see below. Once you get comfortable programming in an editor, you should be able to do everything you need with your keyboard, and never touch your mouse. While it might not seem like a big deal, flipping back and forth between the command line and your code quickly will speed up your workflow a lot.

How are these tools configurable? Well, once you've spent some time working with your editor, you might decide that you want to permanently add line numbers. Or rainbow indent markers. Or have "lambda" always be replaced with λ. Or have your editor always show you an XKCD upon startup. Once you feel comfortable with Emacs or Vim, you can look into editing their .config files (or, you can feel free to ask the TAs if they're willing to share their personal configs!).

We don't care which text editor you choose for this class, but right now, learn how to do the following things in that text editor without touching your mouse. Our command line guide has links to common Emacs and Vim commands, but you can also find all this information online. Practice the following:

  • Move your cursor to the end of the line. Now move it to the start of the line. Practice moving back and forth.
  • Move your cursor one line down. Move it one line up. Go up and down and up down.
  • Scroll the screen down. Now scroll it back up. Repeat. Practice makes perfect!
  • If you can't see line numbers on the side of your screen, learn how to display them. We promise you'll thank us later when there's a bug in line 173.
  • Delete an entire line of text all at once.
  • Now undo that! Hint: if you're working through the command line, you'll likely regret typing ctrl+z like you're used to, which sends a SIGSTP to the process—a little sneak peek of CS110!
  • Search through your code. This one can take some practice, because many text editors have different kinds of searches. Find one that works for you.
  • Learn how to copy, cut, and paste code around your document, and then practice doing that over and over.

Now that you've learned how to do these, spend the next week practicing the commands! Your goal is to build up muscle memory around these commands—so even though it'll be annoying for the first week to keep looking up how to do this or that, we promise that with practice it'll become easier and easier, until you can't even remember a time when you needed to leave your keyboard while writing code💪.

7. Binary numbers

Now that you know where the guides are located, find the binary guide. Practice your binary/hex conversions by writing down answers to the questions in the guide. Then, follow the link at the bottom of the guide to get some more practice courtesy of CS107.

Check in with TA

Each pair of students should periodically touch base with the TA as you answer the check-in questions. The TA will verify your understanding and can help with any unresolved issues.

Remember that the goal of the lab is not to answer exactly and only these questions – it's to work through the material. The questions are an opportunity to self-test your understanding and confirm with us.

It's okay if you don't completely finish all of the exercises during lab; your sincere participation for the full lab period is sufficient for credit. However, if you don't finish, we highly encourage you to work those parts to solidify your knowledge of this material before moving on.