cook - a file construction tool
cook [ option... ][ filename... ]
The cook program is a tool for constructing files. It is given a set
of files to create, and instructions detailing how to construct them.
In any non-trivial program there will be prerequisites to performing
the actions necessary to creating any file, such as extraction from a
source-control system. The cook program provides a mechanism to
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
Options and filenames may be arbitrarily mixed on the command line; no
processing is done until all options and filenames on the command line
have been scanned.
The cook program will attempt to create the named files from the
recipes given to it. The recipes are contained in a file called
Howto.cook in the current directory. This file may, in turn, include
other files containing additional recipes.
If no filenames are given on the command line the targets of the first
recipe defined are cooked.
The valid options for cook are listed below. Any other options (words
on the command line beginning with ‘-’) will cause a diagnostic
message to be issued.
Execute the commands given in the recipes. This is the
Do not execute the commands given in the recipes.
Tells cook to used the named cookbook, rather than the default
This option may be used to enable the use of cascaded
ingredients. This is the default.
This option may be used to disable the use of cascaded
If cooking a target should fail, continue with other recipes
for which the failed target is not an ingredient, directly or
If cooking a target should fail, cook will exit. This is the
-CTime The inode st_ctime data is used to supplement the st_mtime
data when determining whether or not files have changed. This
is the default. (If you have no idea what this is, don’t mess
Do not supplement st_mtime with st_ctime. This may be
important when st_nlink changes at critical times, because
making and breaking hard links touches st_ctime. (If you have
no idea what this is, seriously, don’t mess with it.)
When a command is executed, the exit code will be ignored.
When a command is executed, if the exit code is positive it
will be deemed to fail, and thus the recipe containing it to
have failed. This is the default.
When cook examines a file to determine if it has changed, it
uses the last-modified time information available in the file
system. There are times when this is altered, but the file
contents do not actually change. The fingerprinting facility
examines the file contents when it appears to have changed,
and compares the old fingerprint against the present file
contents. (See cookfp(1) for a description of the
fingerprinting algorithm.) If the fingerprint did not change,
the last-modified time in the file system is ignored. Note
that this has implications if you are in the habit of using
the touch(1) command - cook will do nothing until you actually
change the file.
Do not use fingerprints to supplement the last-modified time
file information. This is the default.
This option may be used to scan the directory tree below the
current directory and update the file fingerprints. This
helps when you use another tool (such as RCS or ClearCase)
which alters the file but preserves the file’s modification
Always perform the actions of recipes, irrespective of the
last-modified times of any of the ingredients. This option is
useful if something beyond the scope of the cookbook has been
modified; for example, a bug fix in a compiler.
Perform the actions of the recipes if any of the ingredients
are logically out of date. This is the default.
Provide information about how to execute cook on stdout, and
perform no other function.
Search the named directory before the standard places for
included cookbooks. Each directory so named will be scanned
in the order given. The standard places are $HOME/.cook then
This option may be used to require the cooking of files named
on #include-cooked and #include-cooked-nowarn include lines in
cookbooks. The files named will be included, if present. If
the files named need to be updated or created, this will be
done, and then the cookbook re-read. This is the default.
This option may be used to inhibit the implicit cooking of
files named on #include-cooked and #include-cooked-nowarn
include lines in cookbooks. The files will be included, if
present, but they will not be updated or created, even if
This option enables the warnings about derived dependencies in
derived cookbooks. This is usually the default.
This option disables the warnings about derived dependencies
in derived cookbooks.
Causes cook to automatically redirect the stdout and stderr of
the session. Output will continue to come to the terminal,
unless cook is executing in the background. The name of the
file will be the name of the cookbook with any suffix removed
and ".list" appended; this will usually be Howto.list. This
is the default.
Causes cook to automatically redirect the stdout and stderr of
the session into the named file. Output will continue to come
to the terminal, unless cook is executing in the background.
No automatic redirection of the output of the session will be
No automatic redirection of the output of the session will be
made, however subsequent -List options will default to listing
to the named file.
After each command is executed, print a summary of the
command’s CPU usage.
Do not print a CPU usage summary after each command. This is
This option may be used to generate a list of pair-wise file
dependencies, similar to lorder(1) output. This may be used
to draw file dependency diagrams. It can also be useful when
This option may be used to set the length of the page, used
when Cook needs to paginate output. Defaults to what the
LINES environment variable tells it, or the terminal emulator
tells it if LINES isn’t set. -Page-Width number This option
may be used to set the width of the page, used when Cook needs
to wrap output (e.g. when it prints commends being executed).
Defaults to what the COLS environment variable tells it, or
the terminal emulator tells it if COLS isn’t set. The maximum
value for number is 32767.
-PARallel [ number ]
This option may be used to specify the number of parallel
executions threads. The number defaults to 4 if no specific
number of threads is specified. See also the parallel_jobs
Use of this option on single-processor machines needs to be
done with great care, as it can bring other processing to a
complete halt. Several users doing so simultaneously on a
multi-processor machine will have a similar effect. It is
also to rapidly run out of virtual memory and temporary disk
space if the parallel tasks are complex.
This option may be used to specify that a single execution
thread is to be used. This is the default.
When commands in the body of a recipe fail, do not delete the
targets of the recipe.
When commands in the body of a recipe fail, delete the targets
of the recipe. This is the default.
Two options are provided for tracing the inferences cook makes
when attempting to cook a target. The -Reason option will
cause cook will emit copious amounts of information about the
inferences it is making when cooking targets. This option may
be used when you think cook is acting strangely, or are just
This option may be used to cause cook will not emit
information about the inferences it is making when cooking
targets. This is the default.
This option may be used to request a shell script be printed
on the standard output. This shell script may be used to
construct the files; it captures many of the semantics of the
cookbook. This can be useful when a project needs to be
distributed, and the recipients do not have cook(1) installed.
It can also be very useful when debugging cookbooks.
Do not echo commands before they are executed.
Echo commands before they are executed. This is the default.
Emit progress indicators once a second. These progress
+ Reading the cookbook
- Executing a collect function
* Building the dependency graph
# Walking the dependency graph
@ Writing fingerprint files.
Do not emit progress indicators. This is the default.
Remove leading "./" from filenames before attempting to cook
them; applies to all filenames and all recipes. This is the
Leave leading "./" on filenames while cooking.
The option asks that, when using a search path, that non-top-
level recipe ingredients get a top-level symlink to the actual
file. This is intended for brain dead tools, like GNU
Autoconf, that don’t grok search paths.
Do not create top level symlinks to ingredients. This is the
This option may be used to cause the position of commands
(filename and line number) to be printed along with the
command just before it is executed (provided the -No_Silent
option is in force).
This option may be used to suppress printing the position of
commands (filename and line number) along with the command
just before it is executed. This is the default.
Update the last-modified times of the target files, rather
than execute the actions bound to recipes. This can be useful
if you have made a modification to a file that you know will
make a system of files logically out of date, but has no
significance; for example, adding a comment to a widely used
Execute the actions bound to recipes, rather than update the
last-modified times of the target files. This is the default.
When listing, also send the output stream to the terminal.
This is the default.
When listing, do not send the output to the terminal.
This option causes cook to check the last-modified time of the
targets of recipes, and updates them if necessary, to make
sure they are consistent with (younger than) the last-modified
times of the ingredients. This results in more system calls,
and can slow things down on some systems. This corresponds to
the time-adjust recipe flag.
Do not update the file last-modified times after performing
the body of a recipe. This is the default. This corresponds
to the no-time-adjust recipe flag.
This option may be used to request a HTML web page be printed
on the standard output. This web page may be used to document
the file dependencies; it captures many of the semantics of
the cookbook. It can also be very useful when debugging
Assign the value to the named variable. The value may contain
spaces if you can convince the shell to pass them through.
All options may be abbreviated; the abbreviation is documented as the
upper case letters, all lower case letters and underscores (_) are
optional. You must use consecutive sequences of optional letters.
All options are case insensitive, you may type them in upper case or
lower case or a combination of both, case is not important.
For example: the arguments "-help", "-HEL" and "-h" are all
interpreted to mean the -Help option. The argument "-hlp" will not be
understood, because consecutive optional characters were not supplied.
Options and other command line arguments may be mixed arbitrarily on
the command line.
The GNU long option names are understood. Since all option names for
cook are long, this means ignoring the extra leading ’-’. The
"--option=value" convention is also understood.
The cook command will exit with a status of 1 on any error. The cook
command will only exit with a status of 0 if there are no errors.
The following files are used by cook:
This file contains instructions to cook for how to construct
This directory contains "system" cookbooks for various tools
This text file is used to remember fingerprints between
The following environment variables are used by cook:
COOK May be set to contain command-line options, changing the
default behavior of cook. May be overridden by the command
PAGER Use to paginate the output of the -Help and -VERSion options.
Defaults to more(1) if not set.
A colon-separated list of directories which the automounter
may use to mount file systems. Use with extreme care, as this
distorts Cook’s idea of the shape of the file system.
This feature assumes that paths below the automounter’s mount
directory are echoes of paths without it. E.g. When /home is
the trigger, and /tmp_mnt/home is where the on-demand NFS
mount is performed, with /home appearing to processes to be a
This is the behavior of the Sun automounter. The AMD
automounter is capable of being configured in this way, though
it is not typical of the examples in the manual. Nor is it
typical of the out-of-the-box Linux AMD configuration in many
Defaults to ‘‘/tmp_mnt:/a:/.automount’’ if not set.
cook version 2.33
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
2008, 2009 Peter Miller
The cook program comes with ABSOLUTELY NO WARRANTY; for details use
the ’cook -VERSion License’ command. This is free software and you
are welcome to redistribute it under certain conditions; for details
use the ’cook -VERSion License’ command.
Peter Miller E-Mail: email@example.com
/\/\* WWW: http://miller.emu.id.au/pmiller/