Read Me(Cook)					    Read Me(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

       * Cook has a simple but powerful	string-based description
	 language with many built-in functions.	 This allows
	 sophisticated filename	specification and manipulation
	 without loss of readability or	performance.

       * Cook is able to use fingerprints to supplement	file
	 modification times.  This allows build	optimization
	 without contorted rules.

       * Cook is able to build your project with multiple
	 parallel threads, with	support	for rules which	must be
	 single	threaded.  It is possible to distribute	parallel
	 builds	over your LAN, allowing	you to turn your network
	 into a	virtual	parallel build engine.

       * Cook can be configured	with an	explicit list of primary
	 source	files.	This allow the dependency graph	to be
	 constructed faster by not going down dead ends, and also
	 allows	better error messages when the graph can't be
	 constructed.  This requires an	accurate source	file
	 manifest.

Reference Manual	       Cook				1

Read Me(Cook)					    Read Me(Cook)

ARCHIVE	SITE
       The latest version of cook is available on the Web from:
	   URL:	   http://www.canb.auug.org.au/~millerp/
	   File:   cook-2.5.README     # the README from the tar file
	   File:   cook-2.5.lsm	       # LSM format description
	   File:   cook-2.5.spec       # RedHat	package	specification
	   File:   cook-2.5.rm.ps.gz   # PostScript of the Reference Manual
	   File:   cook-2.5.ug.ps.gz   # PostScript of the User	Guide
	   File:   cook-2.5.tar.gz     # the complete source

       This Web	page also contains a few other pieces of software
       written by me.  Please have a look if you are interested.

       Cook is also carried by sunsite.unc.edu in its Linux
       archives.  You will be able to find Cook	on any of its
       mirrors.
	   URL:	   ftp://sunsite.unc.edu/pub/Linux/devel/make/
	   File:   cook-2.5.README     # the README from the tar file
	   File:   cook-2.5.lsm	       # LSM format description
	   File:   cook-2.5.spec       # RedHat	package	specification
	   File:   cook-2.5.rm.ps.gz   # PostScript of the Reference Manual
	   File:   cook-2.5.ug.ps.gz   # PostScript of the User	Guide
	   File:   cook-2.5.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).

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@canb.auug.org.au
       Please DO NOT send subscribe requests to	this address.

       To subscribe to this mailing list, send an email	message
       to majordomo@canb.auug.org.au with a message body
       containing the single line
	      subscribe	cook-users
       If you have an email 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	the email address to which you want
       messages	sent.

       The software which handles this mailing list CANNOT send
       you a copy of the cook program.

Reference Manual	       Cook				2

Read Me(Cook)					    Read Me(Cook)

BUILDING COOK
       Full instructions for building the cook program may be
       found in	the BUILDING file included in this distribution.

COPYRIGHT
       cook version 2.5
       Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
       1995, 1996, 1997, 1998 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., 59 Temple Place, Suite 330,
       Boston, MA 02111, USA.

       It should be in the LICENSE file	included with this
       distribution.

AUTHOR
       Peter Miller   E-Mail:	millerp@canb.auug.org.au
       /\/\*	      WWW:	http://www.canb.auug.org.au/~millerp/

Reference Manual	       Cook				3

Read Me(Cook)					    Read Me(Cook)

NEW IN THIS RELEASE
       A number	of features have been added to cook with this
       release.	 The following list is only a summary; for
       excruciating detail, and	also acknowlegements of	those who
       generously sent me feedback, please see the etc/CHANGES.*
       files included in this distribution.

   Release 2.5
       * A problem which caused	some tests to fail on Solaris'
       tmpfs now has a work-around.

       * The ``setenv''	statement has finally been documented.
       It's been in the	code tfor years, but I could never figure
       out why folks weren't using it!

       * A number of build problems on various systems have been
       fixed.

   Release 2.4
       * There is a new	form of	dependencies.  Known as	cascaded
       dependencies, they allow	the user to associate additional
       dependencies with an ingredient.	 For example, a	C source
       file can	be associated with cascaded include dependencies.
       This means that all files which depend on the C source
       file, also depend on the	included files.	 The Cook
       Reference Manual	has been updated to include this new
       functionality.

       * There is a new	section	of the Cook Reference Manual
       giving suggestions and a	template for building large
       projects.

       * There is a new	[expr] function, to calculate simple
       arithmetic expressions.	See the	User Guide for more
       information.

       * There is a new	c_incl -no-recursion option, to	prevent
       scanning	nested includes.  This is of most use when
       combined	with the new cascade dependencies.

       * There is a new	[exists-symlink] function, which may be
       used to test for	the existence of symlinks.  The	[exists]
       function	follows	symbolic links,	and is not useful when
       manipulating the	links themselves.

   Release 2.3

Reference Manual	       Cook				4

Read Me(Cook)					    Read Me(Cook)

       * There are 6 new special variables: graph_leaf_file,
       graph_leaf_pattern, graph_interior_file,
       graph_interior_pattern, graph_exterior_file and
       graph_exterior_pattern.	These variables	may be used to
       define the leaves of the	derivation graph (the accept
       forms), and non-leave of	the graph (the reject forms).
       This can	make the graph derivation faster, and greatly
       improves	some error messages.  This functionality is of
       most use	when you have an exact source file manifest, e.g.
       from a software configuration management	system.	 See the
       User Guide for more information.

       * The %0	pattern	element	has been extended to permit the
       matching	of absolute paths.

   Release 2.2.2
       * There is a new	statement type,	allowing functions to be
       invoked as subroutines in any place where a command may be
       invoked.	 See the User Guide for	more information.

       * A number of problems with installing Cook have	been
       fixed.  This includes changing -mgm to -mm for the
       documnetation formatting, and missing include dependencies
       and missing rules for installing	the man	pages.

       * There is a new	``print'' builtin function.  When
       combined	with the new function call statement, this
       provides	a way of printing information without invoking
       ``echo''.  See the User Guide for more information.

       * Cook now defaults the language	to ``en'' internally if
       neoither	the LANG nor LANGUAGE environment variable was
       set.  This gives	better error messages.

   Release 2.2.1
       * A bug was fixed where a recipe	would fail to trigger if
       some, but not all, of its targets were not present, but
       the existing targets were up-to-date.  This bug was
       introduced in the inference engine re-write.

   Release 2.2

Reference Manual	       Cook				5

Read Me(Cook)					    Read Me(Cook)

       * The c_incl utility has	had two	new languages added.  It
       now understands M4, and also has	an ``optimistic''
       language	which can scan many assemblers and even	some
       high-level languages.  See c_incl(1) for	more information.

       * The c_incl utility also has a new --no-absolute-path
       option, to supress scanning and reporting of such files.
       See c_incl(1) for more information.

       * There is a new	warning	added for dependencies on derived
       ingredients when	this information resides solely	in
       derived cookbooks included using	the #include-cooked
       facility.  This assists in detecting problems which may
       preclude	a successful ``clean'' build.

       * This release adds a number of cookbook	functions to the
       distrubuted cookbooks.  These may be used by adding a
	   #include "functions"
       line to your cookbook.  See the Cook User Guide for more
       information.

       * This release fixes a bug where	the graph walking phase
       ignored interrupts until	something went wrong.

       * This release fixes a bug where	make2cook did not
       correctly translate ``%'' into sematicly	equivalent Cook
       constructs.

   Release 2.1
       * It is possible	to specify that	a command is to	be
       executed	on a specific machine or machines.  This can be
       useful for restrictively	licensed third party software
       tools.

       * The parallel functionality has	been extended to
       implement a virtual parallel machine on a LAN.

       * Fingerprinting	has been enhanced to be	more informative,
       and to adjust file modification times so	that subsequest
       fingerprint-less	runs will not find too much to do.

       * The #line directive is	now available, for better
       diagnostics of generated	cookbooks.  The	__FILE__ and
       __LINE__	variable are also available.

       * There is now a	thread-id variable, to obtain a	thread-
       unique value for	use in generating temporary file names or
       variable	names, etc, which are unique to	a thread.

       * Added the wordlist function and the command-line-goals
       variable	for compatibility with GNU Make.  Updated
       make2cook to understand them.

Reference Manual	       Cook				6

Read Me(Cook)					    Read Me(Cook)

   Release 2.0.1
       * An install problem in the generated Makefile, to do with
       the the manuals,	has been fixed.

   Release 2.0
       Development of this release was generously supported by
       Endocardial Solutions, Inc.

       * Parallel execution is now supported.  If you have a
       multi-processor machine,	you can	specify	the number of
       parallel	processing threads with	the -PARallel command
       line option, or via the [parallel_jobs] variable.  By
       using the [os node] function, the [parallel_jobs] variable
       can be set appropriately	for the	host machine
       automatically by	the cookbook.  There is	a new single-
       thread keyword to support single	threading recipes which
       cannot be paralleized.

       * The dependency	graph is now constructed differently.
       This gives exactly the same results, but	the order of
       evaluation of recipes is	a little more random.  This
       different graph construction is able to give better error
       messages, better	-Reason	information, and allows	the
       introduction of parallel	recipe evaluation if you have a
       multi-processor computer.

       * Recipes which use c_incl(1) to	calculate their
       dependencies in the ingredients section will need a small
       modification - they will	need to	use the	--Absent-Program-
       Ignore option.  See the User Guide for more information.

       * You can now print pair-wise file dependencies by using
       the -PAirs option.

       * You can now print a shell script which	approximates the
       actions cook would take when building the targets by using
       the -SCript option.

       * There is a new	``shallow'' recipe flag, allowing you to
       specify that the	targets	of a recipe are	required to be in
       the top-level directory,	not further down the search_list
       path.

       * You may now define user-written functions in the
       cookbook	to supplement the built-in functions.  Your
       functions will be called	in the same manner as built-in
       functions.  There are new function and return keywords to
       support definition of functions.

       * The progress indicators produced by the -STar option now
       have more detail: + means that the cook book is being
       read, * means that the graph is being constructed, and #
       means that the graph is being walked.

Reference Manual	       Cook				7

Read Me(Cook)					    Read Me(Cook)

   Release 1.11
       * Fixed a bug in	the pattern matching which caused %0
       (when not at the	start of the pattern) to fail to match
       the empty string.

       * The install locations have been changed slightly to
       conform better to the GNU filesystem standards, and to
       take advantage of the additional	install	location options
       of the configure	scripts	generated by GNU Autoconf.

   Release 1.10
       * Error messages	have been internationalized.  It is now
       possible	to get error messages in your native language, if
       it is supported.

       * The cook command now accepts a	-no-include-cooked
       option, to disable any cooking of the #include-cooked
       files.

       * The cook -TRace option	has been renamed -Reason.  This
       is thought to more accurately reflect what it does.

       * The cook -Reason output has been changed to cite
       cookbook	file names and line numbers, in	order to be more
       useful.	In addition, more reason messages carry	location
       information.

   Release 1.9
       * 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.

       * There is a new	``set time-adjust-back'' flag, which sets
       recipe target times to be exactly one (1) second	younger

Reference Manual	       Cook				8

Read Me(Cook)					    Read Me(Cook)

       than the	youngest ingredient.  This is usually an
       adjustment into the recent past.

   Release 1.8
       * 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.

   Release 1.7
       * The AIX code to handle	archive	files has been fixed.

       * The fingerprint code now works	on 64-bit systems.

   Release 1.6
       * 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.

   Release 1.5
       * 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;
       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

Reference Manual	       Cook				9

Read Me(Cook)					    Read Me(Cook)

       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.

   Release 1.4
       * The cook program is now known to work on more systems.
       Most changes were aimed at improving portability, or
       avoiding	problems specific to some systems.

       * The GNU long option name convention is	now understood.
       Option names for	cook were always long, so this mostly
       consists	of ignoring the	extra leading '-'.  The
       "--foo=bar" convention is also understood for options with
       arguments.

       * Tests which fail now tell you what it was they	were
       testing for.  This will give the	user some idea of what is
       happening.

Reference Manual	       Cook			       10
