Provided by: cook_2.33-1_amd64 bug

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

        Peter Miller   E-Mail:   pmiller@opensource.org.au
        /\/\*             WWW:   http://miller.emu.id.au/pmiller/