readme(cook) readme(cook) NAME cook - a file construction tool DESCRIPTION Put simply, the cook program is yet another make-oid. The cook program is a tool for constructing files, and maintaining referential integrity between files. It is given a set of files to create, and recipes of how to create and maintain them. In any non-trivial program there will be prerequisites to performing the actions necessary to creating any file, such as include files. The cook program provides a mechanism to define these. When a program is being developed or maintained, the programmer will typically change one file of several which comprise the program. The cook program examines the last- modified times of the files to see when the prerequisites of a file have changed, implying that the file needs to be recreated as it is logically out of date. The cook program also provides a facility for implicit recipes, allowing users to specify how to form a file with a given suffix from a file with a different suffix. For example, to create filename.o from filename.c NEW IN THIS RELEASE A number of features have been added to cook with this release. A few of them are detailed here: * There are new ``f77'' and ``g77'' cookbooks, to allow Fortran sources, in addition to C sources. * There is a new [options] function, which expands to the current settings of the command line options. This is useful for recursive cook directory structures. See the Reference Manual for more information. * There is a new ``recursive'' cookbook, to assist in constructing recursive cook structures. * The find_libs program now understands about shared libraries. * A bug which made the builtin [glob] function far to generous has been corrected. * A bug which caused some expression evaluation errors to be ignored has been corrected. * The ``set update'' flag has been re-named the ``set time-adjust'' flag, to more closely describe what it does. The old name will continue to work indefinitely. 1 readme(cook) readme(cook) * There is a new ``set time-adjust-back'' flag, which sets recipe target times to be exactly one (1) second younger than the youngest ingredient. This is usually an adjustment into the recent past. The following changes were made in the previous release: * The fingerprint code has been improved to work better with the search_list functionality. * The diagnostics have been improved when cook ``don't know how''. A list of attempted ingredients is included in the error message. * There is a new mkdir recipe flag. This creates recipe target directories before the recipe body is run. See the Reference Manual for more information. * There is a new unlink recipe flag. This unlinks recipe targets before the recipe body is run. See the Reference Manual for more information. * There is a new recurse recipe flag. This overrides the infinite loop recipe heuristic, allowing recipes to recuse upon themselves if one of their ingredients matches one of their targets. See the Reference Manual for more information. The following changes were made in the previous release: * The AIX code to handle archive files has been fixed. * The fingerprint code now works on 64-bit systems. The following changes were made in the previous release: * Fixed a bug in the leading-dot removal code, and added an option to make it user-settable. Fixed a bug in the search_path depth code. The following changes were made in the previous release: * The c_incl program now correctly prints the names of absent include files, causing them to be cooked correctly in a greater number of cases. * Recipes with no ingredients are now only applied if the target is absent. To still use the previous behaviour, use the "set force" clause on the recipe. * It is now possible to supplement the last-modified time with a fingerprint, so cook does even fewer unnecesary recompilations than before. Put the statement set fingerprint; 2 readme(cook) readme(cook) somewhere near the top of your Howto.cook file for this to be the default for your project. * There is a new form of include directive: #include-cooked filename... When files are included in this way, cook will check to make sure they are up-to-date. If not, they will be cooked, and then cook will start again and re-read the cookbook. This is most often used for maintaining include-dependency files. * Cook now configured using a program called configure, distributed with the package. The configure program is generated by GNU Autoconf. See the BUILDING file for more details. * The semantics of search_list have been improved. It is now guaranteed that when ingredients change they result in targets earlier in the search_list being updated. * There is now a make2cook translator, to translate Makefile files into Howto.cook files. Most of the GNU Make extensions are understood. There is no exact semantic mapping between make and cook, so manual editing is sometimes required. See make2cook(1) for more information. * Cook now understands archive member references, in the same format as used by make, et al. Archive member references benefit from stat caching and fingerprinting, just as normal files do. Plus the usual crop of bug fixes and tinkering. For excruciating detail, and also acknowlegements of those who generously sent me feedback, please see the aux/CHANGES.1.9 file included in this distribution. HISTORY The cook program was originally developed (starting in 1988) because I was marooned on an operating system without anything even vaguely resembling make(1). Since I had to write my own, I added a few improvements. When I finally escaped back to UNIX, it took only two days to port cook to SystemV. I have since deleted all code for that original operating system, although clues to its identity are still present. There is no prize for guessing what it was. After I had cook up on UNIX, the progress the world had made caught up with me. It was gratifying that many of the features other make-oid authors had thought necessary were either already present, or easily and seamlessly added. 3 readme(cook) readme(cook) ARCHIVE SITE The latest version of cook is available by anonymous FTP from: Host: ftp.agso.gov.au Dir: /pub/Aegis File: README # what is in this directory File: README.html # ditto, but prettier File: cook.1.9.README # the README from the tar file File: cook.1.9.lsm # LSM format description File: cook.1.9.patch.gz # patch to take 1.8 to 1.9 File: cook.1.9.ps.gz # PostScript of the Manual File: cook.1.9.tar.gz # the complete source To use anonymous ftp, give "anonymous" as the user name (omit the quotes) and your email address as the password. This directory also contains a few other pieces of software written by me. Please have a look if you are interested. Mirrors The main FTP site has limited network bandwidth. The above directory is also mirrored by archie.au in the /pub/Aegis directory. This site has good bandwidth and connectivity, but limits the number of non-Australian users. Cook is also carried by sunsite.unc.edu in its Linux archives. You will be able to find Cook on any of its mirrors. Host: sunsite.unc.edu Dir: /pub/Linux/devel/make File: cook.1.9.README # the README from the tar file File: cook.1.9.lsm # LSM format description File: cook.1.9.patch.gz # patch to take 1.8 to 1.9 File: cook.1.9.ps.gz # PostScript of the Manual File: cook.1.9.tar.gz # the complete source This site is extensively mirrored around the world, so look for a copy near you (you will get much better response). ftp by email For those of you without ftp, I recommend the use of an ftp-by-email server. Here is a list of a few (there are many more): ftpmail@decwrl.dec.com ftpmail@cs.uow.edu.au In general, you can get a help message about how to use each system by sending email with a subject of "help" and a message body containing just the word "help". 4 readme(cook) readme(cook) MAILING LIST A mailing list has been created so that users of cook may exchange ideas about how to use the cook program. Discussion may include, but is not limited to: bugs, enhancements, and applications. The list is not moderated. The address of the mailing list is cook-users@agso.gov.au Please DO NOT send subscribe requests to this address. To subscribe to this mailing list, send an email message to majordomo@agso.gov.au with a message body containing the single line subscribe cook-users Please note that agso.gov.au is an Internet site, so if you have an address which is not readily derived from your mail headers (majordomo is only a Perl program, after all) you will need to use a message of the form: subscribe cook-users address where address is an email address which makes sense from an Internet site. The software which handles this mailing list CANNOT send you a copy of the cook program. Please use ftp or ftp-by- email, instead. BUILDING COOK Full instructions for building the cook program may be found in the BUILDING file included in this distribution. COPYRIGHT cook version 1.9 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996 Peter Miller; All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. It should be in the LICENSE file included with this 5 readme(cook) readme(cook) distribution. AUTHOR Peter Miller UUCP uunet!munnari!agso.gov.au!pmiller /\/\* Internet pmiller@agso.gov.au 6