Assignment Manifest

Each CS 240 assignment starts with an assignment manifest describing Due dates, the honor code Policy for collaboration and submissions, how to find starter Code, how to Submit your work, and a list of topics that are good Reference.

In this assignment, please ignore the Code and Submit lines above until directed explicitly. For this assignment, learning how to acquire starter code is part of the assignment itself. In future assignments, they serve as quick reminders of standard steps, with links to the full documentation.

(Orange boxes mark key information or warnings.)

Contents

Overview

The goal of this assignment is to help you:

  • Install and learn how to use course software tools and supporting infrastructure.
  • Become familiar with course logistics and policies.
  • Practice some concepts with bits.

Notes:

  • This is an individual assignment, meaning each student will submit their own work. Critically, each student should complete all of the tool and setup steps in their own account. We will rely on this going forward.
  • Since this is a practice assignment, you are encouraged to collaborate on ideas or troubleshooting with other students or work together side by (6 feet or a zoom away) side, even though you will each submit your own work.
  • Compared to the assignments that will follow, this one involves much more tool setup and tool learning, much less concept thinking, and many fewer points.
  • The tools will be new to most of you. It is absolutely expected that you may need some support in figuring them out. Please post questions or stop by drop-in hours if you get stuck. You are encouraged work with other students or come hang out in drop-in hours as you do these setup and tutorial steps.

Account and Tool Tasks

Please complete these tasks in order to setup your computer and CS account for access to CS 240 tools.

Request a CS account if you do not have one.

If you have not taken a Wellesley CS course before, please complete the relevant form to request a Wellesley CS account:

A friendly human must respond to your request, so please do this ASAP if it is needed.

Install VSCode on your computer and connect remotely to your CS account.

While lab meetings will use physical electronics hardware and specialized software that are not so easy to use remotely, many benefits of working directly in the lab on the CS Linux Machines for programming assignments are canceled out by the current public health situation. This term, we encourage you to work on programming assignments away from the lab using your own computer. However, you will still need to connect to the CS Linux machines to complete your work. Since CS 240 studies low-level details, you need to use the computing environment we have prepared to avoid trouble with incompatibilities between the different low-level details in different operating systems. (There are real differences that can cause obvious or subtle problems in CS 240 assignment work in a different environment.)

You will see the following reminder of this fact in assignments:

CS 240 code assignments require a CS 240 computing environment.

CS 240 code assignments are designed, tested, and graded in the CS 240 computing environment, since low-level system details matter in this course. We guarantee support (help with provided tools) and consistency (our grading and your testing use the same environment) only for work in a CS 240 computing environment.

This term we advise using VSCode with the Remote Development extension to connect to the CS Linux environment to complete your work. This means that you will run the VSCode application on your own computer, but it will connect to the CS Linux server to edit files and run commands in the CS 240 environment.

Follow the instructions to install and configure VSCode on your computer for remote access to the CS Linux environment.

If the recommended option is not working out for you, such as if you are not able to maintain a consistent network connection, there are other options for access to a CS 240 computing environment. (They require a little more setup or learning.) Please get in touch directly with your instructor if this is the case.

Configure your CS account to use CS 240 software tools.

These tasks will get you started using the command-line interface through a terminal.

Use VSCode with the Remote Development extension to open a terminal connected to the CS Linux server via SSH.

Using that terminal session, configure your CS account permanently1 to find CS 240 tools by running the command:

source /home/cs240/live/env/init/account.sh

This is a one-time setup step for your account.

Learn some terminal basics.

CS 240 requires (but does not assume you have) some basic terminal skills. This section gives a quick warm-up on the command line with the CS Linux machines.

(This part is adapted from past CS 240 lab activities by Jean Herbst.)

An operating system is the software which manages and controls all other applications and resources on a computer. The computers we use in CS 240 use the GNU/Linux operating system, which combines the Linux kernel (the operating system core) with the GNU operating system utilities.

For many CS 240 tasks, you will enter text commands directly at a prompt in a terminal window, rather than selecting options with a mouse through a graphical interface. A terminal is a session that can receive and send input and output for command-line programs. A shell is a program that is used for controlling and running programs interactively via a terminal. Sometimes the two terms are used interchangeably, though they are technically distinct.

Continue using the terminal you already have open in VSCode.

For each of the following steps, try the specified command and consider any questions listed. You do not need to submit answers to these questions anywhere..

Commands:

  1. pwd: Print the working directory (the directory you are currently where you are currently working). The shell always works in one directory at a time. Your command prompt may also show this information.

  2. ls: List the files and subdirectories in your working directory.
    • How do you know whether the items listed are files or subdirectories?

  3. ls -a: Are there any files which begin with a .?

  4. man ls: Check the manual for all the different options for using the ls command. Type SPACE to advance one page, q to exit.

  5. mkdir my-dir: Make a new directory called my-dir

  6. cd my-dir: Change your working directory to the new directory.

  7. echo yourname: Echo your name to the screen.

  8. echo yourname > test1.txt: Echo your name again, but this time redirect the echo into a new file named test1.txt.

  9. List the contents of the directory to see whether the new file was created or not. Then, use two different commands to display its contents to the screen (without an editor):

    • ls
    • less test1.txt (Page down with SPACE, exit with q.)
    • cat test1.txt
  10. Check out additional reference (ignore drop) (from CS 304) or other reference on the tools page as needed.

Learn Git basics for CS 240.

CS 240 uses the Git version control system to help manage assignment code. We do not assume you have used Git before. Even if you have used Git, there are some aspects of our workflow that will be new to you. (For those who have taken CS 251 with Ben recently, this is the same system you have used, but you will need to do the authentication step to set up for CS 240.)

Complete the Git for Code Assignments tutorial, starting at Concepts. Continue through First Steps and Solo Basics, then stop just before Team Basics.

Concept Tasks

Please complete the setup and practice items above before these tasks.

You will record answers to questions or exercises in this part as files in a new assignment repository called zero that you will use to submit the graded portions of the assignment. To get your starter code, run this command in your CS terminal: cs240 start zero --solo

Review Git for Code Assignments if needed while completing Git tasks for this repository.

Review course mechanics. (5 points)

The corner of each CS 240 page contains buttons that jump to:

  • the ▲ top of the page
  • the ☰ table of contents, if any
  • the ▼ bottom of the page

(Blue boxes mark optional asides.)

Read the Syllabus and other course info such as the course tools page, then answer the following questions. Write your answers in the file course.txt in your zero repository.

  1. What should you do if you can’t finish an assignment before the deadline?
  2. Is it ever acceptable to view another student’s code? If so, under what circumstances?
  3. Is it acceptable for two individuals to write a full code solution together on a whiteboard or shared document, then immediately type it up in their individual assignment submissions?
  4. When is it acceptable for one individual student to offer another individual student help understanding an error message?
  5. Give an example of when it is not acceptable to discuss high-level strategies for part of an assignment with another student.
  6. Why should you run CS 240 code on the CS Linux environment (remotely through VSCode/SSH from your computer or directly in the SCI L037 CS Systems Lab) instead of installing a C compiler and working with code directly on your own computer?
  7. What is one good next step if compiling or running your code raises an error you do not understand?

Make nothing from something. (5 points)

In this part, you will do some brief C programming with bitwise operators (introduced in prep for Tuesday, covered more in class on Tuesday) in the file zero.c. The goal is to write several functions that take any byte value as an argument, and, no matter what that byte value is, return the zero byte, 0x00. Of course this is trivial! Just return 0x00;!

To make the task a little more interesting, we prohibit you from using any operations except a small handful. As an example, the zero_minus function must use only the MINUS operator, -, and the parameter, x. (return and semicolon are also allowed and necessary.) No other C features are permitted, not even literal number values like 0 or 0x00.

Example

/**
 * EXAMPLE: zero_minus
 *
 * Goal: take an unknown byte value `x` and return the byte value 0x00
 * no matter what `x` is.
 *
 * The body of the function may use only `return`, `;`, `x`,
 * and the MINUS operator `-`.
 *
 * No other C features are allowed.
 */
byte zero_minus(byte x) {
  return x - x;
}

This function returns the zero byte (0x00) no matter what x it is given.

For simplicity, we use the type byte (instead of the actual more verbose C type unsigned char) to describe a 1-byte value in the range 0x00 to 0xff. Note: byte is not a standard C type name. Comments in zero.c explain its definition.

Task Specification

Your task is to replace the bodies of several more functions defined in the zero.c file that should behave just like zero_minus but with different restrictions:

  • zero_xor uses only bitwise XOR (^).
  • zero_and_not uses only bitwise AND (&) and bitwise NOT (~).
  • zero_or_not uses only bitwise OR (|) and bitwise NOT (~).
  • +Optional Challenge: zero_plus_not uses only integer addition (+) and bitwise NOT (~).

Any of these functions may use their parameter, x, as many times as needed, and as many parentheses as needed.

Hint: The simplest solutions are all quite short and easily fit on one line.

Compiling and Testing

The main function in the file zero_test.c tests the behavior of these zero-producing functions on all possible byte argument values. An incorrect return value from any function causes the program to print an error message.

To compile your puzzle solutions from zero.c with the test harness in zero_test.c and produce a testing executable, run the command make. This command uses compilation recipes in the Makefile to produce an executable called zero. If your code compiles successfully, the session will look like this:

$ make
gcc -std=c99 -O0 -g zero.c zero_test.c -o zero

If you have not changed zero.c sine the last time you compiled, you will see:

$ make
make: 'zero' is up to date.

Now that the executable zero has been compiled, we can run it with the command ./zero. Before you have made changes, expect to see:

$ ./zero 
Testing zero_minus... all tests passed!
Testing zero_xor... at least one test failed.
  zero_xor(0x01) returned 0x01
  [Skipping remaining tests for zero_xor]
Testing zero_and_not... at least one test failed.
  zero_and_not(0x01) returned 0x01
  [Skipping remaining tests for zero_and_not]
Testing zero_or_not... at least one test failed.
  zero_or_not(0x01) returned 0x01
  [Skipping remaining tests for zero_or_not]
Testing zero_plus_not... at least one test failed.
  zero_plus_not(0x01) returned 0x01
  [Skipping remaining tests for zero_plus_not]

The provided puzzle functions after zero_minus do not work; you need to change them so they do.

Every time you change zero.c and want to run the tests again, you must run make to (re-)compile the executable before running it. If you do not, you will be running an old executable that was compiled from an older version of your zero.c file. To help avoid forgetting to compile, you may wish to run the make test recipe, which compiles the executable if needed and runs it.

$ make test
gcc -std=c99 -O0 -g zero.c zero_test.c -o zero
./zero
Testing zero_minus... all tests passed!
Testing zero_xor... at least one test failed.
  zero_xor(0x01) returned 0x01
  [Skipping remaining tests for zero_xor]
Testing zero_and_not... at least one test failed.
  zero_and_not(0x01) returned 0x01
  [Skipping remaining tests for zero_and_not]
Testing zero_or_not... at least one test failed.
  zero_or_not(0x01) returned 0x01
  [Skipping remaining tests for zero_or_not]
Testing zero_plus_not... at least one test failed.
  zero_plus_not(0x01) returned 0x01
  [Skipping remaining tests for zero_plus_not]
make: *** [Makefile:43: test] Error 4

Submission

Submit: The course staff will collect your work directly from your hosted repository. To submit your work:

  1. Test your source code files one last time. Make sure that, at a minimum, submitted source code is free of syntax errors and any other static errors (such as static type errors or name/scope errors). In other words: the code does not need to complete the correct computation when invoked, but it must be a valid program. We will not grade files that do not pass this bar.

  2. Make sure you have committed your latest changes. (Replace FILES with the files you changed and MESSAGE with your commit message.)

    $ git add FILES
$ git commit -m "MESSAGE"

  3. Run the command cs240 sign to sign your work and respond to any assignment survey questions.

    $ cs240 sign

  4. Push your signature and your latest local commits to the hosted repository.

    $ git push

Confirm: All local changes have been submitted if the output of git status shows both:

  • Your branch is up to date with 'origin/master', meaning all local commits have been pushed
  • nothing to commit, meaning all local changes have been committed

Resubmit: If you realize you need to change something later, just repeat this process.

Grading

This assignment is graded out of a total of 10 possible points:

  • Account and Tool Tasks are ungraded
  • Concept Tasks:
    • Review course mechanics: 5 points
    • Make nothing from something: 5 points

  1. If you prefer to use the CS 240 tools only in the current shell session, then run the command source /home/cs240/live/env/init/session.sh instead; run this command in each shell session where you want to use the CS 240 tools. If you need to remove the permanent account configuration, edit ~/.bash_profile to remove the lines marked as related to CS 240. ↩