The purpose of this assignment is to help you learn the basics of the Git version control system, Linux operating system and the Bash shell. The assignment will also give you an opportunity to explore your preferred computing environment and workflow. Finally, the submitted "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 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. Finally, submit your answers to the COS 217 submission system on armlab and also store them into your 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-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-3 from the Git and GitHub Primer document from the first precept.
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 two files in our
repository are a file that describes the repository's contents
(README.md) and a C sourcecode file
(conductsurvey.c).
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 (see Step 11 below).
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
Git one above, 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)
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's clunkiness persists long after students would have
already become adept in the alternative approaches. Further, it is
difficult or even impossible to automate FileZilla, nor can it be
integrated into your editor or IDE.
There are many variants and combinations of these workflows that are viable. We suggest that you to take some time to experiment (it's good practice using the Linux environment anyway!), give at least 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.
Once you have chosen a reasonable method to transfer files onto armlab for building, testing, 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 3!
If your choice is to do all file copying through Git, your only new work is to clone a 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.cfile 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 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.
In an armlab shell that has been moved to the directory containing 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 repository along with the code that administered the survey.
If developing on armlab, assuming that you followed Step 6 and
Step 7 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 Step 6 and Step 7 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 Step 5, 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.
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 surveygit commit -m "adding the results of the COS 217 survey" (or a similar message)git push origin maingit pullFrom 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 file survey for Assignment 0.
The instructors maintain for you one submission directory for each assignment. Thesubmit X file1 file2 ...command on armlab copies the specified file(s) to your Assignment X submission directory. For example, thesubmit 0 surveycommand copies yoursurveyfile from your working directory to your Assignment 0 submission directory.
Instead of issuing asubmit X file1 file2 ...command, you can issue asubmitandbackup X file1 file2 ...command. Thesubmitandbackup X file1 file2 ...command first copies the specified file(s) to your Assignment X submission directory, just as thesubmit X file1 file2 ...command does. Then it creates a directory subordinate to your home directory whose name is of the formBACKUP_X_date_time, and creates a backup copy of the specified file(s) in that directory. If you consistently issuesubmitandbackupcommands, 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 resubmit a file. For example, if you submit a file namedsurveyto your Assignment 0 submission directory and then later submit another file namedsurveyto your Assignment 0 submission directory, then the new version ofsurveysimply overwrites the old version ofsurveyin your Assignment 0 submission directory.
You can issuesubmitcommands with no file arguments to review what files you have submitted for an assignment. For example, the commandsubmit 0will print a list of the files that have been submitted for Assignment 0.
You can issueunsubmitcommands to delete specified files from your submission directory. For example the commandunsubmit 0 surveydeletes thesurveyfile (which, presumably, you submitted previously) from your Assignment 0 submission directory. Theunsubmitprogram does not affect files in your working directory.
We encourage you to experiment with your editors/IDEs and workflow for getting your code onto armlab for testing and debugging (and submitting!). 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.
You likely want to make a copy of the sourcecode (with, e.g.,cp conductsurvey.c experiment.c) to do your exploration and experimentation, that you don't change the behavior of the actual program.
We will not grade your Assignment 0 submission. 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.
This assignment was written by Iasonas Petras with contributions by Robert M. Dondero, Jr. and Christopher Moretti.