diff --git a/README-datalab.txt b/README-datalab.txt deleted file mode 100644 index e137b39..0000000 --- a/README-datalab.txt +++ /dev/null @@ -1,202 +0,0 @@ -##################################################################### -# 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. -