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 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.
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.
- -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 with it.)
- -No_CTime
- 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.)
- -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.
- -Page-Length number
- 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 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 |
|
| @ Writing fingerprint files. |
|
- -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.
- -SymLink-Ingredients
- 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.
- -No-SymLink-Ingredients
- Do not create top level symlinks to ingredients. This is
the default.
- -Tell_Position
-
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).
- -No_Tell_Position
-
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.
- -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 corresponds 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 corresponds 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
invocations.
ENVIRONMENT VARIABLES¶
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
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 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 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.
Defaults to ``/tmp_mnt:/a:/.automount'' if not set.
COPYRIGHT¶
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.
AUTHOR¶
