CSCI 221 Fall 2020

LAB 01: logistics

Attempt before the 9/9 lecture

In this lab we will practice the steps involved in writing and running C code, and then submitting that work. We’ll be working in a Unix-like environment, typing a variety of Unix commands, to get this work done. For those of you on campus, we’ll spend a brief moment logging into a Linux machine to try some commands there. Then, for the rest of the lab, you can either use that machine or the environment you’ve set up on your own computer.

In order to complete this lab from off campus, your machine must be set up according to this installation guide.

You will be submitting work through your GitHub account. This lab shows you how to use Git, at least enough to do the work in this class. Using Git all semester, you will clone programming assignments, edit the code, and then commit and push those edits to a Git account repository, one for each assignment.

The lab is in four parts. In Part 0, if on campus, you’ll learn to remotely log in to a “dumpling” Linux machine and navigate its system using Unix commands. In Part 1, optionally you’ll try the same on your own machine. In Part 2, you’ll use one of those two machines to test out your Git account, create your first Git code “repository.” In Part 3, you’ll learn how to clone some starting C code that we’ve provided, change it, and submit the changes.

To participate in this lab, you should already have a GitHub account and shared its username with us. Your machine also needs some command-line tools (Terminal on Macs; e.g. Powershell or GitBash on Windows) or else a secure-shell client (available as the command ssh in most command-line tools; also Putty on Windows).

In all the work below, you’ll need to use your Reed Unix user name and your GitHub account name. The former is made up of the same letters that form the start of your Reed email; mine is jimfix@reed.edu and so my user name is jimfix. The latter is the name you made up when you created your GitHub account. Everywhere below in the typed examples, we’ll use rgluthy to represent a Reed user name, and Gluthy to represent the GitHub name.

Part 0: work on a dumpling

Note: this part can only be completed by students that are on campus. Those of you that are off-campus can watch what I do live.

The first thing you’ll want to do is bring up the command-line console on your machine.

In your future as a computer programmer or researcher, you will likely be given access to a remote server or a cloud system, one that can only be accessed over a network login (e.g. a research machine at a university, a build system within a tech firm, an AWS or Azure cloud instance). Knowing how to remotely log in and being comfortable navigating that system will be critical for that. It’s also common to create virtual machines as part of a software or research project to execute software or a software system in a “sandboxed” environment, possibly to emulate the activity of a networked collection of computers. In all these scenarios, the use of Unix tools is typically necessary.

SSH to a dumpling
Let’s do just that: log in to a Linux computer on campus. Within the command line tool, type the following command:

ssh rgluthy@gyoza.reed.edu

This command runs the “secure shell” tool. It allows you to open up a Unix shell console, securely, on the computer you chose (it uses cryptographic information exchange protocols to protect the information you type, information sent from your computer to it). That computer will challenge you to prove that you are you by asking for your password. Once you’ve entered that password, you’ll see a few other system messages (possibly one asking whether you really want to do this; you do want to, so answer “yes”) and then you’ll be put into that remote system, and it will await your commands.

Make a folder
The system you are on has given you your own filesystem “home” where you can store and work on files and folders there. That filesystem happens to be a *networked filesystem", so it turns out that home is shared with and accessible from several machines (it’s using a system called AFS). If you are curious about that, type the following as your first command there:

pwd

This prints the working folder (in old Unix terminology, a “directory”) within the command console. It will be the full path of your file home, the series of nested folders where your files live on the system. When in Unix, the commands that you type take effect (typically) within the working folder—the folder that you are currently working within.

If you then type

ls

this will list the contents of the home folder. You’ll likely see some folders here, though this depends on how Reed set up your account. The command ls -l is also useful. It lists the contents with more (i.e. longer) information. I often use ls -ltr which lists things in the same way, but ordered by time of the last change to an item, “in reverse” from oldest to youngest.

Let’s modify the file system to create a folder for doing your course work here. We’ll create that folder and then change which folder we’re working within. Type the command

mkdir CS2

to create a folder named CS2 within your home. Go ahead and type ls or ls -ltr to see that the folder has actually been created.

The Unix command for changing the console to work in a different folder is cd. Type cd then a SPACE and then the full path name of your CS2 work folder.

cd CS2

and then type pwd again and you will see that you’ve moved into the folder that you just created earlier. Here, too, you can create subfolders, create code source files, and so forth.

If you get an error anywhere above, talk to one of us and we can help you determine the correct command. It could be that you are mistyping, or maybe you put spaces in the folder name to make the Unix command tricky. In any case we can help you get it right.

Anyway, congratulations, you are changing a networked filesystem by remote access to a machine that you do not own! We’ll continue to do this for the remainder of the lab work.

FYI: logging out
You have the option of continuing to work here for Parts 2 and 3 of today’s lab. If, however, you decided you wanted to log out and leave, you can enter the command

exit

and this will take you off that remote system. When you are ready to begin working again, just run the ssh command again, go into the system, and you will see the same folders and files that were there when you exited.

Part 1: work on your own machine

Now, optionally, let’s do the same work on your own computer. Exit out of gyoza by typing the command

exit

and this will drop you out of that remote login, and put you back to the state of working within your own machine, and within its own filesystem. Type in a similar set of commands that you typed on gyoza, each of these below

pwd
cd
pwd
mkdir CS2
cd CS2

That second command cd makes sure that you move to work within your unix user’s home folder. The cd command, when given no argument, puts you there.

If you were able to complete Part 0 and also to complete the Part 1 commands just above, then you have a choice: you can continue to work on your machine, or you can log back on to gyoza. Either is fine for today.

Part 2: try the git tools

Okay, now let’s practice editing files and working with Git’s tools.

Configure git on this remote system
Make sure you are sitting in your account’s home folder, working within the subfolder CS2 (either on your machine or gyoza). Enter these three commands:

git config --global user.username "Gluthy"
git config --global user.name "Rory Gluthy"
git config --global user.email "rgluthy@reed.edu"

but using your actual info, not Rory’s. This should set up Git on this machine, tying your dumpling account to your GitHub account.

Now, on your actual machine (not on gyoza) bring up the GitHub site on your browser and login to it with your GitHub username. (Again, let’s assume that it’s Gluthy throughout the instructions here and below.)

On GitHub, create a repository. If you have just logged into GitHub, you should see a left column with the heading Repositories along with a small green button labelled New. You should then see a screen labelled Create a new repository. Here’s that green button

and here’s that creation screen

Enter the repository name lb01-p2 and a short description like “my first repo”. Also check the box for “Initialize this repository with a README.” Hit Create the repository and Viola! you should see this:

You’ve just created a project folder named lb01-p2 under your GitHub account (a GitHub repository). It contains only a single file named README.md, just created, and with the text displayed at the bottom of the screen. Well done.

Clone the repository onto the dumpling Now we are going to essentially download that new repository folder so that you can edit and add to it on the dumpling, rather than through the web. We do that using the Unix command git, typing it into the dumpling console. Enter the command

git clone THE_URL_FOR_CLONING_THE_LB01-P2_REPO

to do that, but first we need to find out the right thing to put in place of the UPPERCASE_TEXT_JUST_ABOVE. In your browser, click on the big green button on the upper right labeled “Code” You should see a web URL, like so

You’ll want to use the text in the rectangle for the git clone command. So you should enter your equivalent of

git clone https://github.com/Gluthy/lb01-p2.git

using your GitHub username instead of Gluthy. The git command might now ask you for your Git username, and it will certainly then ask you to type your Git password. Once you’ve entered these, you should see some messages like

Cloning into 'lb01-p2'...
Username for 'https://github.com': Gluthy
Password for 'https://Gluthy@github.com': 
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.

Success! Now if you enter ls you should see a folder named lb01-p2. If you enter

cd lb01-p2
ls

you should see a file named README.md. If you enter the command

cat README.md

you’ll see its text contents were properly downloaded.

Change the repository’s content
Let’s now make some changes to our repository. We’ll do this using a Unix command-line text editor called nano. We’ll do two things

1. Edit the README.md file.
2. Create a second text file.

Let’s do Step 1. Enter the command

nano README.md

This will start the nano editor. This is a terminal-based editor and so, rather than bringing up a separate editing window on your computer (like Microsoft Windows might), it instead brings up the editor within the small confines of the console. You should see something like this

At the top is a line indicating that you are in the nano editor, at the bottom is a command key reference, and then most of the middle lines are the actual contents of that text file. Move the cursor around, say, to the last line and just start typing words into the last line of the file. Type whatever you like. When you are done, you can “Write Out” those changes to the file with by holding the control key on the keyboard and then hitting the letter O. In other words, type control-o. This will prompt for the name of the file, but you can just hit return and it will save the changes to the same-named file. Having done that, type control-x to exit nano.

Enter

cat README.md

and you should see that the file’s contents have changed.

Now on to Step 2. Enter the command

nano second.txt

and that will create a new empty text file named second.txt within the editor. Again, feel free to start typing whatever you like. Write out the file with control-o and then exit with control-x. Enter

ls
cat second.txt

and you’ll see the new file and then see its contents.

Stage these changes for a repo update
Next thing we’ll do is work towards submitting these changes to your GitHub account’s notion of the repository. Here, you’ve just made a few changes to your local repository, which was initially just a clone of the remote repository that you created on the GitHub site. Our goal is to push those changes up to (the original master version of) the remote repository.

Before doing that, we need to stage all our updates, registering which files with changes are part of the staged update. You can get a full sense of what’s changed in this local area with the command

git status

It’ll be useful to enter this command with each of our steps below, just to see how locally Git is tracking what we are asking it to do with our changes. Enter the commands

git add README.md
git status
git add second.txt
git status

The two git add commands set the stage for our major update. Let’s now commit their contents to the staged update with the command

git commit -m "updated version with our first changes"

With this command, we’ve officially, within the Git tools, made a full update, a series of related changes to the contents, of our dumpling’s version of the repository.

Push those changes
What’s really just happened is that you’ve just completed your work with Part 2 of this lab and you are satisfied with them. So you now actually want to submit that work. Will do that by updating the GitHub version of the repository. This is called the “remote repository” because it is not the one “local” to the dumpling. We will update it on GitHub so that it reflects the same staged set of changes that we just committed to the local version. This is called a push to the remote repository.

Before doing so, first just check the GitHub page in the browser and notice that it still contains the original stuff.

Enter the command

git push origin master

Sparks will fly, you’ll have to type your GitHub password again, you’ll see some console output, there will be a slight pause as the machine connects to the GitHb web site, and then the push will be done!

Go back to the website and you should see that the remote repository on GitHub changes with your updates.

Congrats.

Part 3: completing a GitClassroom assignment

I’ve constructed a repository named lb01-p3 that contains some C code that we’ll take a look at. That repository lives in the ReedCS2-S20 Git “organization” I’ve created for this course. In this last part, we’re going to use the Git Classroom mechanisms for creating a homework assignment repository for you, one that turns out to be a copy of the initial lb01-p3 repository that I’ve built. Once you’ve gotten that copy through GitClassroom and have it on GitHub, we’ll then essentially repeat the steps of Part 2 so that you can clone, modify, add/commit, and then push your work on the assignment.

There will be two additional steps:
1. You will create and work within a branch of that repository.
2. You will issue a pull request to us, asking us to review the changes in your branch.
These go hand-in-hand: when an individual is a contributor to a software project, they work on branched versions of the master version of that project’s source code. And, once they’ve made useful changes and tested them, they alert the other project members, requesting that their changes get incorporated into the master branch. We’ll instead, use this process to give you feedback.

Getting the assignment repository
I’ve used GitClassroom to devise a special web link that you can load in your browser. This will take you to a page where you can “accept the Lab 1 Part 3” classroom assignment. Below is the link

https://classroom.github.com/a/zo8-d_1q

Click on this, or cut and paste the URL into your browser, and follow the instructions on that loaded page to “Accept the assignment.” Along the way, GitClassroom will ask you to identify yourself within my “GitClassroom roster.”

The roster is just a list of everyone’s Reed usernames and should include yours. Scroll through that list and find your Reed username, and clicking that will link your GitHub account to the classroom list.

Finally, and as a result, you will now have a repository that you can clone and update. It should be sitting at a URL like

https://github.com/ReedCS2-F20/lb01-p3-rgluthy

Note that, even though it is your repository, it lives within the ReedCS2-F20 classroom.

Let’s clone this repository. You’ll want to back out of the Part 2 folder. Within the dumpling, enter the commands

cd ..
pwd
ls

The last two can help you verify that you are now in your dumpling user’s CS2 folder, not in the local folder for Part 2. If you get lost here, you could instead try

cd ~
cd CS2

Once ypu are in CS2 enter the correct clone command, something like

git clone https://github.com/ReedCS2-F20/lb01-p3-rgluthy.git

This will download a folder named lb01-p3-rgluthy. Go into it with

cd lb01-p3-rgluthy

If you ls the contents of this folder, you’ll see it contains a README file, and then four C programs.

Lastly, you want to set up a new branch for you to work. You do that with the command

git checkout -b work

Here, in this command, work can be anything other than master. That is, you can actually make several branches. We’d like you to make a branch name that isn’t confusing to us, and so that we’ll know which one you are submitting once everything is done. Choose a name like this one, or this one maybe with a version number as part of it (like work-v3), so that it’s clear to us which is your final completed work.

Editing, compiling, and running
In lab, we will examine these four programs carefully. Your assignment, laid out in the README.md file, is to modify these and submit them as your work for today. I thought here I should lay out the commands you’ll need to enter to work with C programs.

Here’s again the command for editing a file, say hello.cc:

nano hello.cc

Here’s the command for compiling that C code, to create an executable named hello:

g++ -o hello hello.cc

And here’s the command you enter for running that new executable:

./hello

And that’s pretty much it!

Submitting your completed work
Once you’ve completed, say, the first three exercises. You’ll want to mimic what we did in Part 2. You’ll eventually want to use the commands

git add hello.cc
git add countDown.cc
git add cToF.cc
git commit -m "completed the lab exercises"

just like you did for Part 2. And then finally you’ll want to push the changes up to GitHub, and specifically for the branch you created (up above with git checkout). Type the command

git push origin work

and you will have then submitted your completed assignment for this lab.

A Final Note

We’ve covered a lot of ground here, but with little explanation, I hope you are okay with that, as performing all these actions, and seeing the results, was probably helpful in learning what these steps are about. Nonetheless, you should definitely feel free to ask us questions about any of these steps.

My plan tomorrow is to show you these steps again, though instead to demonstrate how you should hand in your work for Homework 01.