The purpose of this assignment is to help you learn the basics of the Linux operating system with the Bash shell and the Git version control system. The assignment will also give you an opportunity to explore to develop your preferred computing environment and workflow. Finally, the submitted survey "artifact" from this assignment will inform the course's instructors about your background relevant to the COS 217 course, thereby helping the course staff to (1) confirm that your background is appropriate, and (2) advise you throughout the course.
Make sure you study the course Policies web page before doing this assignment or any of the COS 217 assignments.
Your first task is to configure your computing environment. Once you have done so, the next two tasks can be completed in either order (or even interspersed with each other).
The second task is to start from the code provided in a COS 217 GitHub repository, produce your own new repository with the same contents, and then use the code from your new repository to take the COS 217 survey. Along the way in the second task, you will have to decide on your development workflow for this course.
The third task is to hone your skills in the Bash command line interface and use your new or renewed skills to complete an exercise that uses the Bash shell. Once you have completed all three tasks, you will fill in the appropriate responses in your readme file.
You will submit your survey answers and readme to the COS 217 submission system on armlab and also store them into your cloud repository.
Some portions of this assignment must be completed on the armlab cluster, but others may be completed in any (suitable) environment of your choosing.
Create a proper COS 217 computing environment on our armlab cluster by completing steps 2 through 7 in the A Minimal COS 217 Computing Environment document from the first precept.
Create a proper setup to use Git and GitHub by completing the Setup Steps 1 through 3 from the Git and GitHub Primer document from the first precept. You will need to configure Git on armlab. If you will be developing in an IDE on your own machine, you will also need to configure Git on your own machine and potentially within your IDE.
Note: you should complete this by attentively and assiduously following the precise instructions in Setup Step 5 from the Git and GitHub Primer document from the first precept.
Make and populate a repository for your work in this assignment. It
should initially have the contents from our provided COS 217
assignment repository for this assignment
(https://github.com/COS217/Survey
). The files in our
repository include a file that describes the repository's contents
(README.md
) and a C sourcecode file
(conductsurvey.c
), neither of which needs to be
edited. The files also include a readme text file for the assignment
(readme
), which you will fill out and submit in Steps 3.3
and 3.4
Once you have your own repository for this assignment, get one or more working copies of it: one on armlab (where you will build, test, and ultimately submit your code) and one on each machine where you will be editing your code locally (e.g., your laptop). If you will be developing directly on armlab, you only need one working copy.
For this assignment, you are not required to edit any code, but we encourage you to follow the procedure as though you were, anyway, as part of your acclimation to the computing environment.
Determine a reasonable mechanism by which you can stage files onto armlab's file system for building, testing, debugging, and submitting. Here is a non-exhaustive list of options:
The easiest way to get files to armlab is to do your development on armlab in the first place! There's no better way to become proficient in the Linux environment than by doing all your work in that environment, rather than just popping in to run a couple commands only when necessary. One common sticking point for students is the code editing interface. The precept handouts provide tutorials for using our standard configuration of emacs, but if you're curious to try this workflow out, the course staff would be happy to provide tips, tricks, and hacks for customizing emacs to include some of the conveniences of modern IDEs.
Our strongly recommended workflow uses Git as your transfer mechanism between your preferred development environment and armlab, as diagramed in the Git and the Cloud schematic from the first precept. In this setup, you do your development on your own machine in an editor or IDE with which you're comfortable and can tune for C as needed (examples include VSCode, Sublime, CLion, Kate, CodeLite). When you're ready to build, test, debug, or submit your program, you commit the changes in your working copy and push to the GitHub cloud repo. Then you pull the changes down from the cloud into the working copy you have on armlab.
(Many editors and IDEs have builtin or plugin functionality to support committing and pushing to your repo directly — you can find tutorials for customizing and tuning your editor/IDE setup online or get pointers from Intro Lab TAs and other Princeton programmers about their niftiest setup details!)
Another command-line focused workflow uses scp
,
the secure copy command. This is a venerable and still useful
command — in fact, the course staff uses it for their own
staging of course materials to the website and to armlab — but
at this point we believe that there are better options for COS 217
students. Because armlab requires 2-factor authentication, this
workflow has some subtle configurations to avoid having to accept a
Duo challenge for every single file movement. (It is possible,
though, and we'd be happy to provide details.) Another downside of
this approach is that it relies on copying files around manually,
which is prone to overwriting files accidentally. And if a user has
chosen this file transfer workflow instead of the more streamlined
one above that uses Git for file staging, we have our suspicion that
they might not be using Git for actual version control either. That
would make them doubly succeptible to such accidents. Another manual
copying approach (with the same potential risks) uses the Secure
File Transfer Protocol (SFTP) instead of secure copy.
There are windowed clients available for either of
scp
or SFTP (e.g., FileZilla) but we actively recommend
against this approach and cannot offer technical
support for getting it working. Although initially the GUI may feel
more comfortable than an entirely command-line-based approach,
FileZilla and friends' clunkiness persists long after students would
have already become adept in the alternative approaches. Further, it
is difficult or even impossible to automate standalone GUI-based
approaches, and they do not cleanly integrate into your editor or
IDE.
There are many variants and combinations of these workflows that
are viable. We suggest that you take some time to experiment. (It's
good practice using the Linux environment anyway!) Give several
editing environments and staging workflows a fair shake, and then make
a decision that you think you can stick with for the remainder of the
course. The easiest way to try this out iteratively is by making
successive edits to your readme
file, editing comments in
the C source code, and adding/removing the survey results or other
text files.
Once you have adopted a reasonable method to transfer files onto
armlab for building, testing, debugging, and/or submitting, it is time
to do that for the Survey program's source code, which consists of a
single file: conductsurvey.c
.
If your choice is to develop on armlab, this step is already complete by virtue of Step 2.2!
If your choice is to do all file copying through Git, your only new work is to clone a new working copy of your repo onto armlab.
If your choice is one of the "manually moving files around" options, then complete the appropriate actions for that workflow.
Theconductsurvey.c
file contains a program written in the C programming language. We encourage you to read the program, but you are not responsible for understanding it at this point. (It uses some advanced features of C that we'll cover later in the semester.)
In an armlab shell that has been moved (with the cd
command) to the directory containing conductsurvey.c
,
issue the command:
gcc217 conductsurvey.c -o conductsurvey
to use the conductsurvey.c
file (which contains source
code) to build the conductsurvey
file (which contains
executable code). We will discuss the meaning behind this command in
detail during the first two weeks of class.
Once your current working directory on armlab contains the resulting
conductsurvey
executable, issue the command:
./conductsurvey
to run the conductsurvey
program and thus take the
survey. Read the instructions carefully and answer all questions.
After you've answered all questions, the conductsurvey
program will finish and the Bash shell prompt again will be
active. The result will be a file named survey
in your
working directory.
Make sure that you took the survey properly. To do that, issue this command:
ls
to display the names of all files in your working directory. One of
those files should be named survey
. Then issue this
command:
cat survey
to examine the contents of the survey
file. The file
should contain your survey responses.
To practice using Git, next make sure the results of the survey are saved back into your remote repository along with the code that administered the survey.
If developing on armlab, assuming that you followed Steps
2.4 and 2.5 exactly, your survey
file will already be
in place within your working copy of the repository. All you will
have to do is complete the first three Git commands below from the
working copy of your repository.
If using the recommended Git workflow, assuming that you
followed Steps 2.4 and 2.5 exactly, your survey
file
will already be in place within your working copy of the
repository. All you will have to do is complete the first three
Git commands below from the working copy of your repository on
armlab, and the last Git command below from the working copy of
your repository on your development environment.
If using scp
or SFTP, you will repeat the file
copy, except in the opposite direction (copying from armlab to
your development environment), and then complete the first three
Git commands below from your working copy of the
repository.
Once the survey
file is copied to the right location
to be saved into the repository, the following 4 commands will
accomplish that. (This is a variant of Use Case 1: Adding Files from
the Git and GitHub Primer document from the first
precept.)
git add survey
git commit -m "adding the results of the COS 217 survey"
(or a similar message)git push origin main
git pull
From the directory on armlab in which you took the survey, issue a
submit
command to submit the results of the survey. More
specifically, issue this command:
submit 0 survey
to submit the survey results (survey
) as part of
Assignment 0. This copies that file into the submission
directory that instructors maintain for you on armlab for each
assignment. The submit
command can take multiple files as
arguments to copy to your submission directory, e.g., submit
X file1 file2
, where X is
the assignment number.
You can resubmit a file as many times as you would like. For
example, if you submit a file named survey
to your
Assignment 0 submission directory and then later submit another file
named survey
to your Assignment 0 submission directory,
then the new version of survey
simply overwrites the old
version of survey
in your Assignment 0 submission
directory, updating the submission time to the time of the most recent
submission. The most recently submitted version is the only one that
instructors will grade.
When you submit a file, the submit
command will also
print a summary of your submitted files. The summary lists, for each file:
its size (in bytes), the timestamp at which it was submitted, its
filename, and its MD5
checksum. You can also get this summary by issuing the
submit
command with only the assignment number (i.e.,
with no file arguments).
You can verify that you have submitted the file you intended by comparing the intended file's checksum with the checksum reported by
submit
. If the MD5 checksums do not match, then the files do not match. (If the checksums do match, it is overwhelmingly likely that the files match.)For example, on armlab you can use the command
md5sum filename
, and on a Mac you can usemd5 filename
. Many editors also have a checksum core feature or plugin.WARNING: Given this easy check that the files submitted are the ones you have intended, you should assume that laments to the course staff asking to resubmit a corrected version of a file are unlikely to be persuasive.
As an alternative, instead of issuing a submit X
file1 file2
command, you can issue a
submitandbackup X file1 file2
command to submit those two files for Assignment X. The
submitandbackup
does the same copy that
submit
does to your submission directory, but it also
creates a directory subordinate to your home directory whose name is
of the form
BACKUP_X_date_time
, and
creates a backup copy of the specified file(s) in that directory. If
you consistently issue submitandbackup
commands, then
you'll have a record of which files you submitted, when you submitted
those files, and the contents of those files. (This is in
addition to the version control that you maintain with Git.)
You can issue unsubmit
commands to delete specified
files from your submission directory. For example the command
unsubmit 0 survey
deletes the survey
file
(which, presumably, you submitted previously) from your Assignment 0
submission directory. The unsubmit
program does not
affect files in your working directory.
There are innumerable tutorials on the web for becoming a more fluid and comfortable user of the Bash shell's command line interface. Some reasonable examples include: COS 217's video walkthrough from a previous semester: (part 1) and (part 2); Software Carpentry; many interesting selections from O'Reilly's bash Cookbook (available with Princeton login); and the BashGuide. Longer reference texts include Learning the bash Shell (available with Princeton login).
In this step, we strongly suggest that you take a tour through one or several Bash how-tos, primers, tutorials, etc. to (re-)familiarize yourself with working on the command line and perhaps try to demystify commands that you have previously been given to copy verbatim without having to understand what they do. You don't have to be an expert in Bash to succeed in this course, but we don't want Bash facility to be an impediment to your success either.
Create 286 text files that each contain one lower-case letter
(a
through z
) followed by a newline
character. When these files are globbed in
the default order on armlab, the contents should be 11 copies of the
alphabet, one letter per line. For example, assuming that you've named
each of your text files with the suffix .txt
, then
cat *.txt
should print a
on the first line,
b
on the second line, ..., z
on the
twenty-sixth line, a
on the twenty-seventh line, and so
on.
Clearly you should not do this by hand! You should use your Bash knowledge based on the tools you've learned about in your Step 3.1 investigations, likely combined with a fair bit of trial-and-error and iterative improvements. You may consider using command pipelines, brace expansion, loops, or other Bash features to automate this file creation process.
Hints: Consider iterating over two separate variables: the letter to be written and the count of how many times you've put this letter into a file. Consider how you can name your files with these two variables to get them to glob in the required order.
If you have done this correctly, then the output from the cat
*.txt
command shown above should have the MD5sum
455bb2644b20e887ac06a7471d5257ff
.
For each assignment, you will complete a readme
file. It provides a space for feedback to help make the assignment
better and help your preceptor know what you might be struggling
with. It is also the place to cite your sources and affirm the "This
paper represents my own work in accordance with University
regulations." statement required by the University. Finally, the
readme
is also the place where you will answer the
technical questions posed by most assignments.
Fill out the identification, feedback, and acknowledgement portions in your working copy of your repository, then complete the assignment-specific question.
For this assignment, you will supply the command(s) you used to
generate the files in Step 3.2 and provide evidence of your successful
completion of this task by listing the checksum from the combined
output of your netid and the files from Step 3.2. The command to
generate this checksum would be (again, assuming that your files are
named with .txt
suffixes and that your files are the only
files named in this way in the directory):
(echo `whoami`; cat *.txt) | md5sum
Copy this checksum directly into the readme on the line designated "MD5:", for example:
MD5:0d926f2666767454f1e4a0c293b0f8f1
Issue a
submit
command to submit your completed readme file:
submit 0 readme
Confirm that both your survey results and your readme have been submitted correctly.
We encourage you to experiment with your editors/IDEs, your corresponding workflow for getting your code onto armlab for testing and debugging (and submitting!), and practice with how to do common tasks in the Bash shell. A small bit of exploratory play now will set you up to be comfortable and competent with a solution that works for you for the rest of the seemster. Choosing not to do so will only continue to waste your own time over the coming days and weeks with general unfamiliarity and resulting inefficiencies.
You likely want to make a copy of the sourcecode (with, e.g.,cp conductsurvey.c experiment.c
) to do your exploration and experimentation so that you don't change the behavior of the actual program.
Your Assignment 0 submission is worth very little towards your
final grade (1%, whereas each of the other 6 assignments contributes
9%, for a total of 55% of your final grade coming from
assignments). However, your Assignment 0 submission is
required. The submit
command will not
accept your submissions for subsequent assignments until you complete
Assignment 0. Our rationale is that Assignment 0 ensures you have
configured your environment(s) and learned the workflow(s) for
completing subsequent assignments.
Your grade on Assignment 0 will be all-or-nothing based on having submitted the two required files on-time with the appropriate content in each of them.
This assignment was written by Christopher Moretti, expanded from prior versions by Iasonas Petras and Robert M. Dondero, Jr.