CSE-376 (Spring 2009) Homework Assignment #4 (Class Project) (Handout #8, version 1) Due Sunday, 5/10/2009, 11:59pm (This assignment is worth 15% of your grade.) *** PURPOSE: To port a C/Unix package to several different Unix systems, using various GNU Autotools. Note the deadline is hard. No extensions can be given because your work must be graded and class grades must be given in time for people to graduate. So start early so you don't all hit the same machines at once. You are responsible for reading the class mailing list. I will be posting additional information, answers to questions, and various clarifications as you begin asking me questions. *** TASK: Use GNU Autoconf, Automake, and Libtool to port the SKEY package to the following ten systems (first 10 out of 14): No. Host Name Running Operating System === ============================= ==================================== 1 a-centos5.fsl.cs.sunysb.edu CentOS Linux 5 (x86_64) 2 a-solaris8.fsl.cs.sunysb.edu Sun Solaris 8 (SPARC Ultra-5) 3 a-freebsd6.fsl.cs.sunysb.edu FreeBSD 6.0 (i386) 4 a-centos44.fsl.cs.sunysb.edu CentOS Linux 4.4 (ia64) 5 a-irix.fsl.cs.sunysb.edu SGI IRIX 6.5 (MIPS 64-bit) 6 a-hpux11.fsl.cs.sunysb.edu HP-UX 11.20 (ia64) 7 a-osx.fsl.cs.sunysb.edu Apple MacOS-X 8.11.0 (PPC) 8 a-debian30.fsl.cs.sunysb.edu Debian Linux 3.0 (i386) 9 a-suse93.fsl.cs.sunysb.edu SuSE Linux 9.3 (i386) 10 a-netbsd20.fsl.cs.sunysb.edu NetBSD 2.0.2 (i386) -- 11 a-openbsd37.fsl.cs.sunysb.edu OpenBSD 3.7 (i386) 12 a-solaris10s.fsl.cs.sunysb.edu Sun Solaris 10 (SPARCv9) 13 a-solaris9.fsl.cs.sunysb.edu Sun Solaris 9 (SPARC) 14 a-rh9.fsl.cs.sunysb.edu Red Hat Linux 9 (i386) These systems are organized in a relatively straightforward order, such that each system adds a small wrinkle to your porting effort. You should begin on a-centos5, because it isn't a VM and will be more efficient to work on. After you get your code working on the first machine, it should be relatively simple to get other Linux systems working, because it is just a different version. FreeBSD, Solaris, IRIX, and HP-UX are then all very different compared to the Linux hosts, so you will need to test for specific APIs. If you do your porting job right, then you will find that after getting the first 4-5 systems working, the rest of them will work with minimal changes. This shows the decreasing incremental effort needed to port a package to the N-th systems after porting to N-1 systems. In general, use the top machine designated "primary" for running Autoconf and Automake to produce your configure scripts and such. I've installed the latest versions of autoconf/automake/libtool on it. Do not try to run autoconf/automake on the other machines because it may have older versions of those tools or not have them at all. Then, you can use any of the other machines to actually run ./configure and "make". Work first on machines that run faster, and leave slower machines to last. You can use a vanilla skey tarball, or use the sources you already worked on before in hw3. Your code should compile cleanly: if you're using gcc, ensure that it builds cleanly with gcc -Wall -Werror. You are to produce a new package named "skey-2.0." (After all this work, surely this package deserves a new major release number. :-) You should write a configure.in template and as many Makefile.am templates as needed. You may have to provide other input files to autoconf/automake/libtool. Use as many autoconf/automake/libtool features as needed to make the package more versatile and flexible. The more useful features you use, the better your grade will be (and you can mention it in the README). But, do not include feature tests that are obviously not needed for this assignment (e.g., "is this a DOS system?") Organize your sources nicely. Create subdirectories such as lib, tools, man, misc, etc. as you see fit; then move your sources there as needed. The more organized your sources are, the better your grade will be. (Do not confuse a directory "lib" that's part of your source tree, with the directory INSTALLDIR/lib that is the directory where a built library is installed.) Your generated configure script should support building in the same source directory or in a "shadow" directory (such as a per-OS directory). Your generated Makefile should support targets like: all, clean, install, dist (to make a tarball distribution), check (to run tests), etc. For "make install" make sure you install all libraries, binaries, man pages, and headers. Also install any other files you think are needed, and justify it in the README. Note where things should be installed (e.g., "bin" vs. "sbin" etc.) For "make check", you should design a simple regression suite of tests that runs "skey" on various inputs and outputs, and determines if the output matches what's expected. The regression suite should check that the programs you build report proper results when given input, and report errors when given bad input (say, wrong options, in which case the binary exits with a non-zero status code). This is how regression suites work in general. (So don't forget to fix the bug that makes skey produce different output on some systems.) Use libtool to ensure that you can build and install either static and shared libraries with the configure script. Hint: get things working with autoconf/automake first, then move on to including libtool features. Hint2: make sure you install the shared libraries because a dynamically linked binary will need them before it can execute. Use the ChangeLog at the top level directory (skey-2.0/ChangeLog) to record the actions you've made. You can add a change log entry if you're using Emacs as follows. Put the cursor anywhere in a C source/header file, or any other file, and type (in Emacs) "CONTROL-x 4 a": this will open a new ChangeLog entry so you can record each and every change you've made to any file. Using ChangeLog files is good programing practice to ensure that you (the developer) have recorded what changes you've made, for others to see. Add a file named "NEWS" at the top level directory, where you briefly list major new features added to this release. This is another useful convention. Add a README file at the top level directory, listing what you've done for this project. This file is an IMPORTANT part of your project grade. So remember to provide enough details there. You have to change the skey package's sources to add several new features (this is the same as you had to do in hw3): -v flag to print version of package (for example "skey version 2.0") -h to print usage (with all new options) -e to echo back the passphrase being entered (otherwise don't echo back) -d to print debugging/tracing output -l ARG: Set the logging device to ARG # Remember to update the man pages (in NROFF format) to mention the new command-line switches. To help you use these Autotools, you can inspect the am-utils package which I and others have been maintaining for several years, here: This is the same software that is described in the "overhauling" paper here: http://www.fsl.cs.sunysb.edu/project-am-utils.html#papers (You may find reading that paper useful.) You can see what typically goes into various files, when, how, etc. Feel free to borrow ideas and scripts from the am-utils package, but be sure to acknowledge what you borrow or based your work on (else it's plagiarism). For example, the "bootstrap" and "buildall" scripts may be very useful to you, with some small modifications. *** TESTING: To test your package, run "make dist" first on one of the primary machines. If successful, it will create a tarball in the build directory named something like "skey-2.0.tar.gz". Copy that file to your home directory, with a command like $ cp skey-2.0.tar.gz ~ You can try it out by simply unpacking that tarball in a new temp directory and seeing if it configures and builds as you expect. For example, if building on a-solaris8: $ cd ~/tmp $ tar xzvf ~/skey-2.0.tar.gz $ mkdir B.solaris8 $ cd B.solaris8 $ ../skey-2.0/configure --prefix=$HOME/skey-2.0/solaris8 --enable-debug $ make all $ make check $ make install $ ~/skey-2.0/solaris8/skey *** SUBMISSION All of your work files should be located in ~/cse376/USER/hw4/. You can copy the files from HW3 and start working on those, but be sure to work in a new, separate directory (hw4/). Your CVS-based submission should include all the files needed to rebuild the package, but NO files that can be regenerated by running "./configure && make". Be sure to follow the testing procedure above and include: - a README file describing what you've done, where, new files you've added, how to use them, and any special/clever things you've done that we should take notice. - all of the existing skey files, possibly modified as you see fit. - any new files you've had to add: scripts, templates, text files, etc. (See the class Web page for CVS submission guidelines.) *** EXTRA CREDIT (OPTIONAL FOR UNDERGRADUATE STUDENTS) [8 pts] Get the code running on the last 4 systems listed above (2 points per machine) [4 pts] Adapt the buildall and config.guess.long scripts from the am-utils package for use here, esp. the use of automatically generated build directories that include not just the OS name, but the system name (i.e., rh9, suse93, centos5, etc.) Good luck.