cook
COOK(1) COOK(1)
NAME
cook - a file construction tool
SYNOPSIS
cook [ option... ][ filename... ]
cook -Help
cook -VERSion
DESCRIPTION
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 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
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 currect 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.
OPTIONS
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.
-Action
Execute the commands given in the recipes. This
is the default.
-No_Action
Do not execute the commands given in the recipes.
-Book filename
Tells cook to used the named cookbook, rather
than the default ``Howto.cook'' file.
-CAScade
This option may be used to enable the use of
cascaded ingredients. This is the default.
-No_CAScade
This option may be used to disable the use of
cascaded ingredients.
-Continue
If cooking a target should fail, continue with
other recipes for which the failed target is not
an ingredient, directly or indirectly.
-No_Continue
If cooking a target should fail, cook will exit.
This is the default.
-Errok
When a command is executed, the exit code will be
ignored.
-No_Errok
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.
-FingerPrint
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.
-No_FingerPrint
Do not use fingerprints to supplement the last-
modified time file information. This is the
default.
-FingerPrint_Update
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 time.
-Force
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.
-No_Force
Perform the actions of the recipes if any of the
ingredients are logically out of date. This is
the default.
-Help
Provide information about how to execute cook on
stdout, and perform no other function.
-Include filename
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
/usr/share/cook.
-Include_Cooked
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.
-No_Include_Cooked
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 required.
-Include_Cooked_Warning
This option enables the warnings about derived
dependencies in derived cookbooks. This is
usually the default.
-No_Include_Cooked_Warning
This option disables the warnings about derived
dependencies in derived cookbooks.
-List
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.
-List filename
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_List
No automatic redirection of the output of the
session will be made.
-No_List filename
No automatic redirection of the output of the
session will be made, however subsequent -List
options will default to listing to the named
file.
-Meter
After each command is executed, print a summary
of the command's CPU usage.
-No_Meter
Do not print a CPU usage summary after each
command. This is the default.
-Pairs
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 debugging
cookbooks.
-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 variable.
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.
-No_PARallel
This option may be used to specify that a single
execution thread is to be used. This is the
default.
-Precious
When commands in the body of a recipe fail, do
not delete the targets of the recipe.
-No_Precious
When commands in the body of a recipe fail,
delete the targets of the recipe. This is the
default.
-Reason
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 curious.
-No_Reason
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.
-SCript
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.
-Silent
Do not echo commands before they are executed.
-No_Silent
Echo commands before they are executed. This is
the default.
-STar
Emit progress indicators once a second. These
progress indicators include
+ Reading the cookbook
- Executing a collect function
* Building the dependency graph
# Walking the dependency graph
-No_STar
Do not emit progress indicators. This is the
default.
-Strip_Dot
Remove leading "./" from filenames before
attempting to cook them; applies to all filenames
and all recipes. This is the default.
-No_Strip_Dot
Leave leading "./" on filenames while cooking.
-Touch
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 include file.
-No_Touch
Execute the actions bound to recipes, rather than
update the last-modified times of the target
files. This is the default.
-TErminal
When listing, also send the output stream to the
terminal. This is the default.
-No_TErminal
When listing, do not send the output to the
terminal.
-Time_Adjust
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 correspondes to the time-adjust
recipe flag.
-No_Time_Adjust
Do not update the file last-modified times after
performing the body of a recipe. This is the
default. This correspondes to the no-time-adjust
recipe flag.
-Web
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 cookbooks.
name=value
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.
EXIT STATUS
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.
FILES
The following files are used by cook:
Howto.cook
This file contains instructions to cook for how
to construct files.
/usr/share/cook
This directory contains "system" cookbooks for
various tools and activities.
.cook.fp
This text file is used to remember fingerprints
between invokations.
ENVIRONMENT VARIABLES
The following environment variables are used by cook:
COOK May be set to contain command-line options,
changing the default behaviour of cook. May be
overridden by the command line.
PAGER Use to paginate the output of the -Help and
-VERSion options. Defaults to more(1) if not
set.
COOK_AUTOMOUNT_POINTS
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 filesystem.
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 symlink.
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
distributions.
Defauls to ``/tmp_mnt:/a:/.automount'' if not
set.
COPYRIGHT
cook version 2.18
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
1995, 1996, 1997, 1998, 1999, 2000, 2001 Peter Miller;
All rights reserved.
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.
AUTHOR
Peter Miller E-Mail: millerp@canb.auug.org.au
/\/\* WWW: http://www.canb.auug.org.au/~millerp/
Reference Manual Cook 1