Assignment 0: Introductory Survey

Purpose

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.

Rules

Make sure you study the course Policies web page before doing this assignment or any of the COS 217 assignments.

The Task

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.

Procedure

Some portions of this assignment must be completed on the armlab cluster, but others may be completed in any (suitable) environment of your choosing.

Step 1: Create a Proper armlab Computing Environment

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.

Step 2: Create a Proper GitHub Setup

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.

Step 3: Mirror/Import the COS 217 Survey Repository and Clone Your New Repository

Get a working copy of your own version of the COS 217 assignment repository for this assignment by completing the Setup Step 5 from the Git and GitHub Primer document from the first precept. The COS 217 assignment repository for this assignment is the one used in that document's example: https://github.com/COS217/Survey

Step 4: Test Options for Staging Files to armlab

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. 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, Atom, Sublime, CLion, 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 LabTAs 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 workflow instead of the more streamlined Git one above, we have our suspicion that they might not be doing much version control with Git 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 do not recommend this approach. 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. Thus, we do strongly encourage everyone to at least try the first two options above before defaulting to this choice.

Step 5: Stage the Survey Program Source Code to armlab

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 scp, SFTP, or other "manually moving files around" options, then complete the appropriate actions for that workflow.

The conductsurvey.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.)

Step 6: Build the Survey Program

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 week of classes.

Step 7: Run the Survey Program

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.

Step 8: Examine the Survey Results

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.

Step 9: Save the Survey Results into Your Repository

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.

1. git add survey
2. git commit -m "adding the results of the COS 217 survey" (or a similar message)
3. git push origin main
4. (for the Git solution only, update the working copy on the development environment to get the update from the cloud that was pushed from the working copy on armlab)
   git pull

Step 10: Submit the Survey Results

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 file survey for Assignment 0.

The instructors maintain for you one submission directory for each assignment. The submit X file1 file2 ... command on armlab copies the specified file(s) to your Assignment X submission directory. For example, the submit 0 survey command copies your survey file from your working directory to your Assignment 0 submission directory.

Instead of issuing a submit X file1 file2 ... command, you can issue a submitandbackup X file1 file2 ... command. The submitandbackup X file1 file2 ... command first copies the specified file(s) to your Assignment X submission directory, just as the submit X file1 file2 ... command does. Then it 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 resubmit a file. 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.

You can issue submit commands with no file arguments to review what files you have submitted for an assignment. For example, the command submit 0 will print a list of the files that have been submitted for Assignment 0.

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.

Grading

We will not grade your Assignment 0 submission. However, your Assignment 0 submission is required. We 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.