diff --git a/README-datalab.txt b/README-datalab.txt new file mode 100644 index 0000000..e137b39 --- /dev/null +++ b/README-datalab.txt @@ -0,0 +1,202 @@ +##################################################################### +# 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. + diff --git a/datalab-handout.tar b/datalab-handout.tar new file mode 100644 index 0000000..b639e53 Binary files /dev/null and b/datalab-handout.tar differ diff --git a/datalab-release.html b/datalab-release.html new file mode 100644 index 0000000..0e9e9ab --- /dev/null +++ b/datalab-release.html @@ -0,0 +1,171 @@ + +
+
+
+12/16/2019+
11/1/2018+
10/24/2018+
10/23/2018+
5/4/2016+
2/17/2016+
9/16/2014+
9/2/2014+
1/30/2014+
9/19/2012+
4/26/2012+
8/22/2011+
5/31/2011+
1/2/2011+This is a major update of the Data Lab: +
8/29/2003+
1/27/2003+
9/26/2002+
6/3/2002+
|