AllStuRead/README-datalab.txt

#####################################################################
# CS:APP Data Lab
# Directions to Instructors
#
# May 31, 2011: Now includes the "Beat the Prof" contest
#
# Copyright (c) 2002-2018, R. Bryant and D. O'Hallaron
######################################################################

This directory contains the files that you will need to run the CS:APP
Data Lab, which helps develops the student's understanding of bit
representations, two's complement arithmetic, and IEEE floating point.

For fun, we've also provided a new user-level HTTP-based "Beat the
Prof" contest that replaces the old email-based version. The new
contest is completely self-contained and does not require root
password.  The only requirement is that you have a user account on a
Linux machine with an IP address.

System requirements: Uses bison and flex to build dlc.

************
1. Overview
************

In this lab, students work on a C file, called bits.c, that consists
of a series of programming "puzzles".  Each puzzle is an empty
function body that must be completed so that it implements a specified
mathematical function, such as "absolute value". Students must solve
the non-floating point puzzles using only straight-line C code and a
restricted set of C arithmetic and logical operators. For the
floating-point puzzles they can use conditionals and arbitrary
operators.

Students use the following three tools to check their work.
Instructors use the same tools to assign grades.

1. dlc: A "data lab compiler" that checks each function in bits.c for
compliance with the coding guidelines, checking that the students use
less than the maximum number of operators, that they use only
straight-line code, and that they use only legal operators. The
sources and a Linux binary are included with the lab.

2. btest: A test harness that checks the functions in bits.c for
correctness. This tool has been significantly improved, now checking
wide swaths around the edge cases for integers and floating point
representations such as 0, Tmin, denorm-norm boundary, and inf.

3. driver.pl: A autograding driver program that uses dlc and btest to
check each test function in bits.c for correctness and adherence to
the coding guidelines

The default version of the lab consists of 15 puzzles, in
./src/selections.c, chosen from a set of 73 standard puzzles defined
in the directory ./src/puzzles/. You can customize the lab from term
to term by choosing a different set of puzzles from the standard set
of puzzles.

You can also define new puzzles of your own and add them to the
standard set. See ./src/README for instructions on how to add new
puzzles to the standard set.

NOTE: If you define new puzzles, please send them to me (Dave
O'Hallaron, droh@cs.cmu.edu) so that I can add them to the standard
set of puzzles in the data lab distribution.

********
2. Files
********

All CS:APP labs have the same simple top-level directory structure:

Makefile	   Builds the entire lab.
README		   This file.
src/		   Contains all source files for the lab.
datalab-handout/   Handout directory that goes to the students. Generated
		   by the Makefile from files in ./src. Never modify anything
		   in this directory. 
grade/		   Autograding scripts that instructors can use to 
		   grade student handins.
writeup/	   Sample Latex lab writeup.
contest/           Everything needed for the optional "Beat the Prof" contest.

********************
3. Building the Lab
*******************

Step 0. If you decide to run the "Beat the Prof" contest (section 5),
then edit the ./contest/Contest.pm file so that the driver knows where
to send the results. See ./contest/README for the simple
instructions. If you decide *not* to offer the contest, then do
nothing in this step.

Step 1. Select the puzzles you want to include by editing the file
./src/selections.c.

The default ./src/selections.c comes from a previous instance of the
Data Lab at CMU.  The file ./src/selections-all.c contains the
complete list of puzzles to choose from.

Step 2. Modify the Latex lab writeup in ./writeup/datalab.tex to 
tailor it for your course. 

Step 3. Type the following in the current directory:
     unix> make clean
     unix> make 

The Makefile generates the btest source files, builds the dlc binary
(if necessary), formats the lab writeup, and then copies btest, the
dlc binary, and the driver to the handout directory.  After that, it
builds a tarfile of the handout directory (in ./datalab-handout.tar)
that you can then hand out to students.

Note on Binary Portability: dlc is distributed in the datalab-handout
directory as a binary. Linux binaries are not always portable across
distributions due to different versions of dynamic libraries. You'll
need to be careful to compile dlc on a machine that is compatible with
those that the students will be using.

Note: Running "make" also automatically generates the solutions to the
puzzles, which you can find in ./src/bits.c and ./src/bits.c-solution.


******************
4. Grading the Lab
******************

There is a handy autograder script that automatically grades your
students' handins.  See ./grade/README for instructions.

**************************
5. "Beat the Prof" Contest
**************************

For fun, we've included an optional "Beat the Prof" contest, where
students compete against themselves and the instructor. The goal is to
solve each Data Lab puzzle using the fewest number of
operators. Students who match or beat the instructor's operator count
for each puzzle are winners. See ./contest/README for the simple
instructions on how to set up the contest.

NOTE: The contest is completely optional. Whether you decide to
offer it or not has no affect on how you build and distribute the lab.

NOTE: If you do decide to offer the contest, then you should configure
the contest *before* you build the lab, so that the driver knows the
server and port to send the contest results of each student (using the
constants defined in the ./src/Driverhdrs.pm file, which is
autogenerated from the ./contest/Contest.pm config file).

If you decide to offer the contest *after* you've built and handed out
the lab to the students, you're still OK:

1) Configure the contest as described in contest/Makefile

2) Rebuild the lab in the usual way:
   linux> cd datalab
   linux> make

3) Distribute the new ./src/Driverhdrs.pm file to the students.


***************************
6. Experimental BDD checker
***************************

For fun, we have included an experimental correctness checker based on
binary decision diagrams (BDDs) (R. E. Bryant, IEEE Transactions on
Computers, August, 1986) that uses the CUDD BDD package from the
University of Colorado. The BDD checker does an exhaustive test of the
test functions in bits.c, formally verifying the correctness of each
test function against a reference solution for *ALL* possible input
values. For functions that differ from the reference solution, the BDD
checker produces a counterexample in the form of a set of function
arguments that cause the test solution to differ from the reference
solution.

The sources are included in ./src/bddcheck. To compile:

  unix> cd src/bddcheck
  unix> make clean
  unix> make

To use BDDs to check ./src/bits.c for correctness:

  unix> cd src
  unix> ./bddcheck/check.pl     # with error messages and counterexamples
  unix> ./bddcheck/check.pl -g  # compact tabular output with no error messages

Note that check.pl must be run from the parent directory of ./bddcheck.

We've been using this BDD checker instead of btest at CMU for several
years and the code appears to be stable. The main weakness is in the
Perl code that extracts the functions from bits.c. It usually works,
but some things -- such as calls to other functions, or functions that
don't end with a single brace -- confuse it. So we're reluctant to
make it the default checker for the distributed CS:APP labs. However,
if you have any questions about the correctness of a particular
solution, then this is the authoritative way to decide.

Please send any comments about the BDD checker to randy.bryant@cs.cmu.edu.