.














                              Cook

                    A File Construction Tool





                        Reference Manual







                          Peter Miller

                    _m_i_l_l_e_r_p_@_c_a_n_b_._a_u_u_g_._o_r_g_._a_u
































.












This document describes Cook version 2.21
and was prepared 13 March 2007.






This  document  describing the Cook program, and the Cook program
itself, are
Copyright (C) 1988, 1989, 1990, 1991,  1992,  1993,  1994,  1995,
1996, 1997, 1998, 1999, 2000, 2001, 2002 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 Foun-
dation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,  USA.























                                                                0





Read Me(Cook)                                       Read Me(Cook)


NNAAMMEE
       cook - a file construction tool

DDEESSCCRRIIPPTTIIOONN
       The _c_o_o_k 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 _c_o_o_k 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 _c_o_o_k 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 _c_o_o_k 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 _f_i_l_e_n_a_m_e.o from _f_i_l_e_n_a_m_e.c

       * Cook is a replacement for   * There is a _m_a_k_e_2_c_o_o_k
       the traditional _m_a_k_e(1)       utility included in the
       tool.                         distribution to help
       * Cook is more powerful       convert makefiles into
       than the traditional _m_a_k_e     cookbooks.
       tool.
       * Cook has true variables,    * Cook has a simple but
       not simple macros.            powerful string-based
       * Cook has user defined       description language with
       functions.                    many built-in functions.
                                     This allows sophisticated
                                     filename specification and
                                     manipulation without loss
                                     of readability or
                                     performance.
       * Cook can build in           * Cook is able to build
       parallel.                     your project with multiple
       * Cook can distribute         parallel threads, with
       builds across your LAN.       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.







Reference Manual               Cook                             1





Read Me(Cook)                                       Read Me(Cook)


       * Cook is able to use         * Cook can be configured
       fingerprints to supplement    with an explicit list of
       file modification times.      primary source files.  This
       This allows build             allow the dependency graph
       optimization without          to be constructed faster by
       contorted rules.              not going down dead ends,
       * In addition to walking      and also allows better
       the dependency graph, Cook    error messages when the
       can turn the input rules      graph can't be constructed.
       into a shell script, or a     This requires an accurate
       web page.                     source file manifest.
       * Cook runs on almost any     * Cook has special _c_a_s_c_a_d_e
       flavor of UNIX.  The source   dependencies, allowing
       distribution is self          powerful include dependency
       configuring using a GNU       specification, amongst
       Autoconf generated            other things.
       configure script.

       If you are putting together a source-code distribution and
       planning to write a makefile, consider writing a cookbook
       instead.  Although Cook takes a day or two to learn, it is
       much more powerful and a bit more intuitave than the
       traditional _m_a_k_e(1) tool.  And Cook doesn't interpret tab
       differently to 8 space characters!

AARRCCHHIIVVEE SSIITTEE
       The latest version of _c_o_o_k is available on the Web from:
           URL:    http://www.canb.auug.org.au/~millerp/cook/
           File:   cook-2.21.README     # the README from the tar file
           File:   cook-2.21.lsm        # LSM format description
           File:   cook-2.21.spec       # RedHat package specification
           File:   cook-2.21.rm.ps.gz   # PostScript of the Reference Manual
           File:   cook-2.21.ug.ps.gz   # PostScript of the User Guide
           File:   cook-2.21.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.21.README     # the README from the tar file
           File:   cook-2.21.lsm        # LSM format description
           File:   cook-2.21.spec       # RedHat package specification
           File:   cook-2.21.rm.ps.gz   # PostScript of the Reference Manual
           File:   cook-2.21.ug.ps.gz   # PostScript of the User Guide
           File:   cook-2.21.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).






Reference Manual               Cook                             2





Read Me(Cook)                                       Read Me(Cook)


MMAAIILLIINNGG LLIISSTT
       A mailing list has been created so that users of _c_o_o_k may
       exchange ideas about how to use the _c_o_o_k 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 _a_d_d_r_e_s_s
       where _a_d_d_r_e_s_s is the email address to which you want
       messages sent.

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

BBUUIILLDDIINNGG CCOOOOKK
       Full instructions for building the _c_o_o_k program may be
       found in the _B_U_I_L_D_I_N_G file included in this distribution.

CCOOPPYYRRIIGGHHTT
       _c_o_o_k version 2.21
       Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
       1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 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 _L_I_C_E_N_S_E file included with this
       distribution.



Reference Manual               Cook                             3





Read Me(Cook)                                       Read Me(Cook)


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






















































Reference Manual               Cook                             4





Read Me(Cook)                                       Read Me(Cook)


NNEEWW IINN TTHHIISS RREELLEEAASSEE
       A number of features have been added to _c_o_o_k 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 _e_t_c_/_C_H_A_N_G_E_S_._*
       files included in this distribution.

   VVeerrssiioonn 22..2211
       * The _c___i_n_c_l(1) command now accepts the -stripdot and
       -nostripdot options.  These may be used to control the
       removal of redundant leading dot directories.

       * A bug has been fixed where cascade recipes failed to
       heed the stripdot setting.

       * There is a new [stripdot] function, so that you can
       strip leading dot directories from file names within
       functions.

       * A bug has been fixed in how the builtin functions which
       manipulate build graphs were called.  This fixed a problem
       with freeing a string which had already been freed.

   VVeerrssiioonn 22..2200
       * There is a fix for the build problems caused by recent
       GNU Gettext releases.

       * The fingerprint handling is now more robust,
       particularly when faced with files that move backwards in
       time.

       * There is a fix for the build problems caused by recent
       Bison releases.

   VVeerrssiioonn 22..1199
       * Some introduced with recent versions of GNU Bison have
       been fixed.  Bison's include file insulation didn't use YY
       in the insulating symbol (just to be completely
       inconsistent) and in another case a namespace clash
       occurred for a function name.

       * The generated Makefile has been improved, along with
       other small build and install improvements.

       * A top-level _f_a_i_l statement how halts the parse as soon
       as it is executed.  This will make it more useful for
       checking build environments.

       * Documentation about _c_o_o_k___r_s_h(1) has been added to the
       Parallel chapter of the User Guide.

   VVeerrssiioonn 22..1188





Reference Manual               Cook                             5





Read Me(Cook)                                       Read Me(Cook)


       * A bug has been fixed in the _i_n_g_r_e_d_i_e_n_t_s_-_f_i_n_g_e_r_p_r_i_n_t
       recipe attribute.  It was failing to save the fingerprint
       cache file in some cases, and thus came to incorrect
       conclusions on following runs.

       * The _(_e_x_i_s_t_s_) ingredients attribute has been fixed so
       that it no longer implies behavious rimilar to _s_e_t
       _s_h_a_l_l_o_w.

       * There is a new _c_o_o_k___r_s_h(1) program, for use with the
       _h_o_s_t_-_b_i_n_d_i_n_g recipe attribute, which allows you to load
       balance builds across classes of hosts.  See _c_o_o_k___r_s_h(1)
       and the Parallel chapter of the User Guide for more
       information.

       * Some build problems have been fixed on various
       platforms.

       * More keywords are now understood for M4 include
       directives.

   VVeerrssiioonn 22..1177
       * When using file fingerprints, the way the _._c_o_o_k_._f_p file
       is written has been changed, so that the timestamp of the
       containing directory is modified much less often.  This is
       useul in combination with the _c_o_o_k___b_o_m(1) utility.

       * A bug has been fixed under Cygwin, where archive members
       were not being fingerprinted correctly.

       * A bug has been fixed in the [quote] function.  It now
       quotes all _s_h(1), _c_s_h(1) and _b_a_s_h(1) special characters
       correctly.

       * A bug has been fixed in the [uptodate] function.  It now
       works as advertised.

       * There is a new _i_n_g_r_e_d_i_e_n_t_s_-_f_i_n_g_e_r_p_r_i_n_t recipe flag.
       This means that you can now cause a recipe to re-trigger
       when the ingredients list changes.  This is especially
       useful when a library has a file removed.

       * The dependency graph can now have the edge types
       specified.  The ``weak'' edge type if useful for managing
       links, and the ``exists'' edge type is useful for managing
       version stamps.  See the User Guide for more information.

   VVeerrssiioonn 22..1166









Reference Manual               Cook                             6





Read Me(Cook)                                       Read Me(Cook)


       * The _s_t_r_i_n_g_s_e_t function now accepts a `+' operator.
       While union is implicit, the apparrently redundant `+'
       operator is useful for cancelling the other operators.

       * The ``reason and fingerprint bug'' has been fixed.  This
       caused a mysterious error message to appear sometimes when
       using the -reson option incombination with fingerprints.

       * The % and %_n patterns are now allowed to match the empty
       string, provided they aren't the first thing in the
       pattern (otherwise undesirable absolute path problems can
       occur).

       * The _c___i_n_c_l(1) command now accepts `-' as a file name on
       the command line, meaning standard input.

       * Some improvements have been made to the Cygwin support,
       extending the ``.exe'' automatic executable suffix
       coverage to a couple more places.

       * A bug in the ``c'' cookbook has been fixed, which was
       getting .h dependency files wrong.

   VVeerrssiioonn 22..1155
       * The _C___i_n_c_l(1) problem with absolute paths has been
       fixed.

       * A bug has been fixed which caused problems on Solaris
       and SGI, where Cook would report a No child processes
       error.

   VVeerrssiioonn 22..1122
       * The _c___i_n_c_l program now has a --qquuoottee--ffiilleennaammeess option,
       which means that you can have filenames with spaces and
       special characters in them.

       * A bug in the _c___i_n_c_l program's path flattening has been
       fixed.

       * A small Y2K bug has been fixed in the date parsing used
       by the _c_o_o_k_t_i_m_e(1) command.

       * A bug which caused the -parallel option to lose track of
       processes when you used [execute] in a recipe body has
       been fixed.

       * The restrictions on the placement of the placement of %0
       in a pattern have been dropped; too many people didn't
       like it.  This does _n_o_t break any cookbooks.

       * Cook now copes with the absence of the HOME environment
       variable.  This was a problem for CGI scripts.





Reference Manual               Cook                             7





Read Me(Cook)                                       Read Me(Cook)


   VVeerrssiioonn 22..1111
       * Numerous portability problems have been fixed in the
       configure and build.

       * A bug has been fixed which prevented Cook from working
       correctly when run by some versions of _c_r_o_n(8) and _a_t(1).

       * There is a new _c_o_o_k___b_o_m _-_-_i_g_n_o_r_e option, allowing you to
       nominate file patterns that you don't want in the file
       lists.

       * There is a new [__FUNCTION__] variable, which contains
       the name of the executing function, which suppliments the
       existing [__FILE__] and [__LINE__] variables.

       * Functions now have local variables, just put the word
       local on the left-hand-side of the first assignment.
       Local variables are reentrant and thread-safe.

   VVeerrssiioonn 22..1100
       * The _[_p_r_i_n_t_] and _[_w_r_i_t_e_] functions now work more sensably
       with the --SSCCrriipptt option.

       * The fingerprint code has been improved.  It now does
       considerably fewer redundant fingeprint calculations,
       resulting is some very welcome speed improvements.

       * The behaviour of the remote shell invocation to cope
       with rshd at the remote end failing to spawn a shell, and
       it copes with the default shell at the remote end not
       being the Bourne shell.

       * The --PPAARRaalllleell behaviour has been improved, so that it
       now looks for child process who have finished _m_o_r_e _t_h_a_n it
       looks for recipes to run.  This doesn't change the
       semantics any, but it matches user expectations far better
       (and results in shorter-lived zombie processes).

       * The _s_e_t _m_e_t_e_r recipe flag works once more.  (It stopped
       working when the parallel modifications were made, and
       mysteriously forgotten until now.)

       * There are some changes made to the fingerprinting code
       to detect when files under ClearCase move backwards in
       time (because the underlying file version is
       ``uncovered'') meaning that the derived (object) files
       need to be rebuilt.

       * There is a new [mtime-seconds] function, similar to the
       [mtime] function, except that it returns seconds since the
       epoch, rather than a human readable date.  More useful to
       handing to [expr].

       * A bug has been fixed on SGI IRIX which failed to cope



Reference Manual               Cook                             8





Read Me(Cook)                                       Read Me(Cook)


       with not being able to create directories because they
       already exist.

       * Ingredient recipes (ones with no body) may now have a
       double colon rather than a single colon, even when there
       is more than on target specified.  Some users may find
       this a more natural syntax for ingredients recipes.

       * The [expr] function now reports an error when given a
       number too big to represent, rather than quietly returning
       wrong answers.  The range of representable values depends
       on your system.

       * Cook now works with GNU Regex correctly on Windows-NT.

   VVeerrssiioonn 22..99
       * There is a new ``for each'' style looping construct.
       See the User Guide for more information.

       * It is now possible to use regular expression patterns,
       instead of Cook's native patterns.  You can set this for a
       whole cookbook or individual recipes.  The default is to
       use Cook's native patterns.  See the _F_i_l_e _N_a_m_e _P_a_t_t_e_r_n_s
       chapter of the User Guide for more information.

       * A bug which caused _h_o_s_t_-_b_i_n_d_i_n_g and _s_i_n_g_l_e_-_t_h_r_e_a_d to
       core dump has been fixed.

       * All text file input now copes with CRLF sequences, so
       mixing NT and Unix builds on the one file server no longer
       creates problems.

       * Fingerprints are now cached per-directory, rather than
       one huge file for an entire directory tree.  This is more
       useful in recursive build and [search_list] situations.

       * The [cando], [cook] and [uptodate] functions now return
       lists of successful files, rather than a simple true/false
       result.

       * The [in] and [matches] functions now return the list
       index (1 based) of the matching word.  See the User Guide
       for more information.

       * There is a new _c_o_o_k _-_w_e_b option, to print a HTML web
       page on the standard output, representing the dependency
       graph.  This is useful in documenting the build process,
       or debugging cookbooks.

       * There is a new _c_o_o_k _-_-_f_i_n_g_e_r_p_r_i_n_t_-_u_p_d_a_t_e option which
       scans the directory tree below the current directory and
       updates 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.



Reference Manual               Cook                             9





Read Me(Cook)                                       Read Me(Cook)


       * There is a new [write] function for writing text files.
       This is useful for coping with Windows-NT's absurdly short
       command lines.

   VVeerrssiioonn 22..88
       * The remote _h_o_s_t_-_b_i_n_d_i_n_g code has been improved to cope
       with staggeringly long commands (which tended to make
       _r_s_h(1) barf), and also wierd and wonderfull $SHELL
       settings.

       * The #include directive now accepts more than one file,
       to be more symmetric with the #include-cooked directive.

       * A bug has been fixed where cooktime gave an incorrect
       error message if setting the file's utimes failed.

       * The configure script has been improved for use on non-
       UNIX systems.

       * There is a new builtin [cook] function, a natural
       companion for the [cando] and [uptodate] functions.  See
       the Cook User Guide for more information.

   VVeerrssiioonn 22..77
       * There is a new _c_o_o_k___b_o_m(1) command (Bill Of Materials).
       This may be used to efficiently scan a directory tree for
       files, so that ingredients lists may be produced
       automatically.  See _c_o_o_k___b_o_m(1) for more information.

       * There is a new assign-append statement, so you can now
       use += to append to the value of a variable.  See the User
       Guide for more information.

       * There is a new _g_a_t_e_-_f_i_r_s_t recipe flag, which causes the
       recipe gate to be evaluated before the ingredients are
       derived, rather than after.

       * The _c___i_n_c_l(1) command has a new --interior-files option,
       so you can tell it about include files that don't exist
       yet.  This is helpful when they are generated, _i_._e_. they
       are interior files of the dependency graph, hence the
       option name.

       * There is a new [interior-files] function, which returns
       the files interior to the dependency graph (constructed by
       a recipe), and a complementatry [leaf-files] function,
       which returns the leaf files of the dependency graph (not
       constructed by any recipe).

       * There is a new ``no-include-cooked-warning'' flag, if
       you want to suppress the warnings about derived file
       dependencies in include-cooked files.

       * There is a new _r_e_l_a_t_i_v_e___d_i_r_n_a_m_e built-in function,



Reference Manual               Cook                            10





Read Me(Cook)                                       Read Me(Cook)


       similar to the existing _d_i_r_n_a_m_e function, but it returns
       ``.'' for files with no directory part, rather than the
       absolute path of the current directory.

   VVeerrssiioonn 22..66
       * Cook has been ported to Windows-NT using CygWin32.  See
       the BUILDING file for details.

       * There are two new functions (_d_o_s_-_p_a_t_h and _u_n_-_d_o_s_-_p_a_t_h)
       for use when invoking non-CygWin32 WindowsNT programs.
       See the Cook User Guide for more information.

       * Fingerprints now work meaningfully with directories.

       * A bug has been fixed in the pattern matching code.  It
       would sometimes cause core dumps.

       * A bug involving fingerprints in combination with the
       search_list has been fixed.  Cook would occasionally
       conclude that a shallow target was up-to-date when a
       shallow ingredient was edited to be the same as a deeper
       ingredient.

       * A bug has been fixed in cooktime.  It would use an
       inappropriate timezone offset on some systems.

   RReelleeaassee 22..55
       * 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.

   RReelleeaassee 22..44



















Reference Manual               Cook                            11





Read Me(Cook)                                       Read Me(Cook)


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

   RReelleeaassee 22..33
       * 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 _a_c_c_e_p_t
       forms), and non-leave of the graph (the _r_e_j_e_c_t 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.

   RReelleeaassee 22..22..22
       * 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



Reference Manual               Cook                            12





Read Me(Cook)                                       Read Me(Cook)


       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.

   RReelleeaassee 22..22..11
       * 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.

   RReelleeaassee 22..22
       * The _c___i_n_c_l 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___i_n_c_l(1) for more information.

       * The _c___i_n_c_l utility also has a new --no-absolute-path
       option, to supress scanning and reporting of such files.
       See _c___i_n_c_l(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 _m_a_k_e_2_c_o_o_k did not
       correctly translate ``%'' into sematicly equivalent Cook
       constructs.

   RReelleeaassee 22..11














Reference Manual               Cook                            13





Read Me(Cook)                                       Read Me(Cook)


       * 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, _e_t_c, which are unique to a thread.

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

   RReelleeaassee 22..00..11
       * An install problem in the generated Makefile, to do with
       the the manuals, has been fixed.

   RReelleeaassee 22..00
       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 _[_p_a_r_a_l_l_e_l___j_o_b_s_] variable.  By
       using the _[_o_s _n_o_d_e_] function, the _[_p_a_r_a_l_l_e_l___j_o_b_s_] 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___i_n_c_l(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.



Reference Manual               Cook                            14





Read Me(Cook)                                       Read Me(Cook)


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

   RReelleeaassee 11..1111
       * 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.

   RReelleeaassee 11..1100
       * 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.








Reference Manual               Cook                            15





Read Me(Cook)                                       Read Me(Cook)


   RReelleeaassee 11..99
       * 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 _f_i_n_d___l_i_b_s 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
       than the youngest ingredient.  This is usually an
       adjustment into the recent past.

   RReelleeaassee 11..88
       * 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 _m_k_d_i_r recipe flag.  This creates recipe
       target directories before the recipe body is run.  See the
       Reference Manual for more information.

       * There is a new _u_n_l_i_n_k recipe flag.  This unlinks recipe
       targets before the recipe body is run.  See the Reference
       Manual for more information.

       * There is a new _r_e_c_u_r_s_e 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.






Reference Manual               Cook                            16





Read Me(Cook)                                       Read Me(Cook)


   RReelleeaassee 11..77
       * The AIX code to handle archive files has been fixed.

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

   RReelleeaassee 11..66
       * 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.

   RReelleeaassee 11..55
       * The _c___i_n_c_l 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 _H_o_w_t_o_._c_o_o_k file for this to
       be the default for your project.

       * There is a new form of include directive:
              #include-cooked _f_i_l_e_n_a_m_e...
       When files are included in this way, _c_o_o_k will check to
       make sure they are up-to-date.  If not, they will be
       cooked, and then _c_o_o_k will start again and re-read the
       cookbook.  This is most often used for maintaining
       include-dependency files.

       * CCooookk now configured using a program called _c_o_n_f_i_g_u_r_e,
       distributed with the package.  The _c_o_n_f_i_g_u_r_e program is
       generated by GNU Autoconf.  See the _B_U_I_L_D_I_N_G file for more
       details.

       * The semantics of _s_e_a_r_c_h___l_i_s_t have been improved.  It is
       now guaranteed that when ingredients change they result in
       targets earlier in the _s_e_a_r_c_h___l_i_s_t being updated.

       * There is now a _m_a_k_e_2_c_o_o_k translator, to translate
       _M_a_k_e_f_i_l_e files into _H_o_w_t_o_._c_o_o_k files.  Most of the GNU
       Make extensions are understood.  There is no exact
       semantic mapping between _m_a_k_e and _c_o_o_k_, so manual editing
       is sometimes required.  See _m_a_k_e_2_c_o_o_k(1) for more
       information.

       * _C_o_o_k now understands archive member references, in the
       same format as used by _m_a_k_e, et al.  Archive member
       references benefit from stat caching and fingerprinting,
       just as normal files do.



Reference Manual               Cook                            17





Read Me(Cook)                                       Read Me(Cook)


   RReelleeaassee 11..44
       * The _c_o_o_k 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 _c_o_o_k 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                            18





Build(Cook)                                           Build(Cook)


NNAAMMEE
        cook - a file construction tool

SSPPAACCEE RREEQQUUIIRREEMMEENNTTSS
        You will need about 5MB to unpack and build the _C_o_o_k
        package.  Your milage may vary.

BBEEFFOORREE YYOOUU SSTTAARRTT
        There are a few pieces of software you may want to fetch
        and install before you proceed with your installation of
        Cook.

        Please note: if you install these packages into
        _/_u_s_r_/_l_o_c_a_l (for example) you must ensure that the
        _._/_c_o_n_f_i_g_u_r_e script is told to also look in
        _/_u_s_r_/_l_o_c_a_l_/_i_n_c_l_u_d_e for include files (CFLAGS), and
        _/_u_s_r_/_l_o_c_a_l_/_l_i_b for library files (LDFLAGS).  Otherwise
        the _._/_c_o_n_f_i_g_u_r_e script will incorrecly conclude that they
        have not been installed.

        GNU Gettext
                The _C_o_o_k package has been internationalized.  It
                can now print error messages in any of the
                supported languages.  In order to do this, the
                GNU Gettext package must be installed _b_e_f_o_r_e you
                run the configure script as detailed in the next
                section.  This is because the configure script
                looks for it.  On systems which use the GNU C
                library, version 2.0 or later, there is no need
                to explictly do this as GNU Gettext is included.
                Remember to use the GNU Gettext configure _-_-_w_i_t_h_-
                _g_n_u_-_g_e_t_t_e_x_t option if your system has native
                gettext tools.

        GNU rx
                Cook needs regular expressions to operate
                correctly.  Get a copy from your nearest GNU
                mirror.  On systems which use the GNU C library,
                version 2.0 or later, there is no need to
                explictly do this as GNU rx is included.

        GNU Groff
                The documentation for the _C_o_o_k package was
                prepared using the GNU Groff package.  This
                distribution includes full documentation, which
                may be processed into PostScript or DVI files at
                install time - if GNU Groff has been installed.
                You must use GNU Groff version 1.15 or later.

        Bison   If your operating system does not have a native
                _y_a_c_c(1) you will need to fetch and install GNU
                Bison in order to build the _C_o_o_k package.

        GCC     You may also want to consider fetching and



Reference Manual               Cook                            19





Build(Cook)                                           Build(Cook)


                installing the GNU C Compiler if you have not
                done so already.  This is not essential.

        The GNU FTP archives may be found at ftp.gnu.org, and are
        mirrored around the world.

SSIITTEE CCOONNFFIIGGUURRAATTIIOONN
        The CCooookk package is configured using the _c_o_n_f_i_g_u_r_e
        program included in this distribution.

        The _c_o_n_f_i_g_u_r_e shell script attempts to guess correct
        values for various system-dependent variables used during
        compilation, and creates the _M_a_k_e_f_i_l_e and _c_o_m_m_o_n_/_c_o_n_f_i_g_._h
        files.  It also creates a shell script _c_o_n_f_i_g_._s_t_a_t_u_s that
        you can run in the future to recreate the current
        configuration.

        Normally, you just _c_d to the directory containing _C_o_o_k's
        source code and type
                %% ./configure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        If you're using _c_s_h on an old version of System V, you
        might need to type
                %% sh configure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        instead to prevent _c_s_h from trying to execute _c_o_n_f_i_g_u_r_e
        itself.

        Running _c_o_n_f_i_g_u_r_e takes a minute or two.  While it is
        running, it prints some messages that tell what it is
        doing.  If you don't want to see the messages, run
        _c_o_n_f_i_g_u_r_e using the quiet option; for example,
                %% ./configure --quiet
                %

        There is a known problem with GCC 2.8.3 and HP/UX.  You
        will need to set CFLAGS = -O in the generated Makefile.
        (The configure script sets it to CFLAGS = -O2.)  This is
        because the code optimization breaks the fingerprints.
        If test 46 fails (see below) this is probably the reason.

        To compile the CCooookk package in a different directory from
        the one containing the source code, you must use a
        version of _m_a_k_e that supports the _V_P_A_T_H _v_a_r_i_a_b_l_e_, such as
        _G_N_U _m_a_k_e.  _c_d to the directory where you want the object
        files and executables to go and run the _c_o_n_f_i_g_u_r_e script.
        _c_o_n_f_i_g_u_r_e automatically checks for the source code in the
        directory that _c_o_n_f_i_g_u_r_e is in and in _._.  (the parent
        directory).  If for some reason _c_o_n_f_i_g_u_r_e is not in the
        source code directory that you are configuring, then it
        will report that it can't find the source code.  In that
        case, run _c_o_n_f_i_g_u_r_e with the option --srcdir=_D_I_R, where



Reference Manual               Cook                            20





Build(Cook)                                           Build(Cook)


        _D_I_R is the directory that contains the source code.

        By default, _c_o_n_f_i_g_u_r_e will arrange for the _m_a_k_e _i_n_s_t_a_l_l
        command to install the CCooookk package's files in
        _/_u_s_r_/_l_o_c_a_l_/_b_i_n, _/_u_s_r_/_l_o_c_a_l_/_l_i_b, _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e and
        _/_u_s_r_/_l_o_c_a_l_/_m_a_n.  There are a number of options which
        allow you to control the placement of these files.

        --prefix=_P_A_T_H
                This specifies the path prefix to be used in the
                installation.  Defaults to _/_u_s_r_/_l_o_c_a_l unless
                otherwise specified.

        --exec-prefix=_P_A_T_H
                You can specify separate installation prefixes
                for architecture-specific files files.  Defaults
                to _$_{_p_r_e_f_i_x_} unless otherwise specified.

        --bindir=_P_A_T_H
                This directory contains executable programs.  On
                a network, this directory may be shared between
                machines with identical hardware and operating
                systems; it may be mounted read-only.  Defaults
                to _$_{_e_x_e_c___p_r_e_f_i_x_}_/_b_i_n unless otherwise specified.

        --datadir=_P_A_T_H
                This directory contains installed data, such as
                the documentation and cookbooks distributed with
                Cook.  On a network, this directory may be shared
                between all machines; it may be mounted read-
                only.  Defaults to _$_{_p_r_e_f_i_x_}_/_s_h_a_r_e_/_c_o_o_k unless
                otherwise specified.  A ``cook'' directory will
                be appended if there is none in the specified
                path.

        --libdir=_P_A_T_H
                This directory contains installed data, such as
                the error message catalogues.  On a network, this
                directory may be shared between machines with
                identical hardware and operating systems; it may
                be mounted read-only.  Defaults to
                _$_{_e_x_e_c___p_r_e_f_i_x_}_/_l_i_b_/_c_o_o_k unless otherwise
                specified.  A ``cook'' directory will be appended
                if there is none in the specified path.

        --mandir=_P_A_T_H
                This directory contains the on-line manual
                entries.  On a network, this directory may be
                shared between all machines; it may be mounted
                read-only.  Defaults to _$_{_p_r_e_f_i_x_}_/_m_a_n unless
                otherwise specified.

        _c_o_n_f_i_g_u_r_e ignores most other arguments that you give it;
        use the --help option for a complete list.



Reference Manual               Cook                            21





Build(Cook)                                           Build(Cook)


        On systems that require unusual options for compilation
        or linking that the _C_o_o_k package's _c_o_n_f_i_g_u_r_e script does
        not know about, you can give _c_o_n_f_i_g_u_r_e initial values for
        variables by setting them in the environment.  In Bourne-
        compatible shells, you can do that on the command line
        like this:
                $$ CC='gcc -traditional' LIBS=-lposix ./configure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                $$
        Here are the _m_a_k_e variables that you might want to
        override with environment variables when running
        _c_o_n_f_i_g_u_r_e.

        Variable: CC
                C compiler program.  The default is _c_c.

        Variable: CPPFLAGS
                Preprocessor flags, commonly defines and include
                search paths.  Defaults to empty.  It is common
                to use CFLAGS=-I/usr/local/include to access
                other installed packages.

        Variable: INSTALL
                Program to use to install files.  The default is
                _i_n_s_t_a_l_l if you have it, _c_p otherwise.

        Variable: LIBS
                Libraries to link with, in the form -l_f_o_o -l_b_a_r.
                The _c_o_n_f_i_g_u_r_e script will append to this, rather
                than replace it.  It is common to use
                LIBS=-L/usr/local/lib to access other installed
                packages.

        If you need to do unusual things to compile the package,
        the author encourages you to figure out how _c_o_n_f_i_g_u_r_e
        could check whether to do them, and mail diffs or
        instructions to the author so that they can be included
        in the next release.

BBUUIILLDDIINNGG CCOOOOKK
        All you should need to do is use the
                %% make
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        command and wait.  When this finishes you should see a
        directory called _b_i_n containing nine files: _c___i_n_c_l, _c_o_o_k,
        _c_o_o_k_f_p, _c_o_o_k_t_i_m_e, _f_i_n_d___l_i_b_s, _m_a_k_e_2_c_o_o_k and _r_o_f_f_p_p.

        ccooookk    _c_o_o_k program is a file construction tool, and may
                invoke the following tools in some of its
                recipes.

        ccooookkffpp  The _c_o_o_k_f_p program is a utility distributed with
                _C_o_o_k which calculates the fingerprints of files.



Reference Manual               Cook                            22





Build(Cook)                                           Build(Cook)


                It uses the same algorithm as the fingerprints
                used by _c_o_o_k itself.  For more information, see
                _c_o_o_k(1) and _c_o_o_k_f_p(1).

        ccooookkttiimmee
                The _c_o_o_k_t_i_m_e program is a utility distributed
                with _C_o_o_k which allows the time-last-modified and
                time-last-accessed stamps of files to be set to
                specific times.  For more information, see
                _c_o_o_k_t_i_m_e(1).

        cc__iinnccll  The _c___i_n_c_l program is a utility distributed with
                _C_o_o_k which examines C files and determines all
                the files it includes directly and indirectly.
                For more information, see _c___i_n_c_l(1).

        ffiinndd__lliibbss
                The _f_i_n_d___l_i_b_s program is a utility distributed
                with _C_o_o_k which tracks down the names of library
                files, given cc-style library options (-L and
                -l).  For more information, see _f_i_n_d___l_i_b_s(1).

        mmaakkee22ccooookk
                The _m_a_k_e_2_c_o_o_k program is a utility to help
                convert Makefiles into cookbooks.  An exact 1:1
                semantic mapping is not possible, so some
                addition editing is often required.

        rrooffffpppp  The _r_o_f_f_p_p program is a utility distributed with
                _C_o_o_k which acts as a proprocessor for *roff
                files, removing source (.so) directives.  It
                accepts include search path command line options
                just as _/_l_i_b_/_c_p_p does.  For more information, see
                _r_o_f_f_p_p(1).

        You can remove the program binaries and object files from
        the source directory by using the
                %% make clean
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        command.  To remove all of the above files, and also
        remove the _M_a_k_e_f_i_l_e and _c_o_m_m_o_n_/_c_o_n_f_i_g_._h and _c_o_n_f_i_g_._s_t_a_t_u_s
        files, use the
                %% make distclean
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        command.

        The file _e_t_c_/_c_o_n_f_i_g_u_r_e_._i_n is used to create _c_o_n_f_i_g_u_r_e by
        a GNU program called _a_u_t_o_c_o_n_f.  You only need to know
        this if you want to regenerate _c_o_n_f_i_g_u_r_e using a newer
        version of _a_u_t_o_c_o_n_f.





Reference Manual               Cook                            23





Build(Cook)                                           Build(Cook)


TTEESSTTIINNGG CCOOOOKK
        The _C_o_o_k program comes with a test suite.  To run this
        test suite, use the command
                %% make sure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                PPaasssseedd AAllll TTeessttss
                %%

        The tests take a few seconds each, with a few very fast,
        and a couple very slow, but it varies greatly depending
        on your CPU.

        If all went well, the message
                Passed All Tests
        should appear at the end of the make.

   KKnnoowwnn PPrroobblleemmss
        If test 46 fails, this is often caused by optimization
        bugs in gcc.  Edit the Makefile to change -O2 to -O, and
        delete common/fp/*.o to cause them to be re-built.  Make
        and test again.

        If you are using Sun's tmpfs file system as your /tmp
        directory, some tests will fail.  This is because the
        tmpfs file system does not support file locking.  Set the
        COOK_TMP environment variable to somewhere else before
        running the tests.  Something like
                %% setenv COOK_TMP /usr/tmp
                %%
        is usually sufficient if you are using C shell, or
                $$ COOK_TMP=/usr/tmp
                $$ export COOK_TMP
                $$
        if you are using Bourne shell.  Remember, this must be
        done before running the tests.

        Tests 121 and 122 can sometimes have problems on Solaris,
        where they give false negatives.  If you work out why,
        please let the author know.

IINNSSTTAALLLLIINNGG CCOOOOKK
        As explained in the _S_I_T_E _C_O_N_F_I_G_U_R_A_T_I_O_N section, above,
        the _C_o_o_k package is installed under the _/_u_s_r_/_l_o_c_a_l tree
        by default.  Use the --prefix=_P_A_T_H option to _c_o_n_f_i_g_u_r_e if
        you want some other path.  More specific installation
        locations are assignable, use the --help option to
        _c_o_n_f_i_g_u_r_e for details.

        All that is required to install the _C_o_o_k package is to
        use the
                %% make install
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        command.  Control of the directories used may be found in



Reference Manual               Cook                            24





Build(Cook)                                           Build(Cook)


        the first few lines of the _M_a_k_e_f_i_l_e file and the other
        files written by the _c_o_n_f_i_g_u_r_e script; it is best to
        reconfigure using the _c_o_n_f_i_g_u_r_e script, rather than
        attempting to do this by hand.

PPRRIINNTTEEDD MMAANNUUAALLSS
        The easiest way to get copies of the manuals is to get
        the _c_o_o_k_._2_._2_1_._r_m_._p_s_._g_z and _c_o_o_k_._2_._2_1_._u_g_._p_s_._g_z files from
        the archive site.  These are compressed PostScript files
        of the Reference Manual and User Guide, respectively.
        The Reference Manual (about 36 pages) contains the README
        file, the BUILDING file and internationalization notes,
        as well as all of the manual pages for all of the
        commands.  The User Guide (about 56 pages) tells you how
        to use the Cook package.

        This distribution contains the sources to all of the
        documentation for _C_o_o_k.  The author used the GNU groff
        package and a postscript printer to prepare the
        documentation.  If you do not have this software, you
        will need to substitute commands appropriate to your
        site.

        If you have the GNU Groff package installed _b_e_f_o_r_e you
        run the _c_o_n_f_i_g_u_r_e script, the _M_a_k_e_f_i_l_e will contain
        instructions for constructing the documentation.  If you
        alreday used the _m_a_k_e command, above, this has already
        been done.  The following command
                %% make groff_all
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        can be used to do this explicitly, if you managed to get
        to this point without doing it.  Please note that there
        may be some warnings from groff, particularly for the
        .txt files; this is normal.

        Once the documents have been formatted, you only need to
        print them.  The following command
                %% lpr lib/en/refman.ps lib/en/user-guide.ps
                %%
        will print the English PostScript version of the
        Reference Manual and the User Guide.  Watch the _m_a_k_e
        output to see what other versions are available.

GGEETTTTIINNGG HHEELLPP
        If you need assistance with the _C_o_o_k program, please do
        not hesitate to contact the author at
                Peter Miller <millerp@canb.auug.org.au>
        Any and all feedback is welcome.

        When reporting problems, please include the version
        number given by the
                %% cook -version
                ccooookk vveerrssiioonn _2_._2_1_._D_0_0_1



Reference Manual               Cook                            25





Build(Cook)                                           Build(Cook)


                _._._._w_a_r_r_a_n_t_y _d_i_s_c_l_a_i_m_e_r_._._.
                %%
        command.  Please do not send this example; run the
        program for the exact version number.

        In the _c_o_m_m_o_n_/_m_a_i_n_._h file, there is a define of _D_E_B_U_G in
        comments.  If the comments are removed, extensive
        debugging is turned on.  This causes some performance
        loss, but performs much run-time checking and adds the
        --TTRRAACCIInngg command line option.

        When the --TTRRAACCiinngg option is followed by one or more file
        names, it turns on execution traces in those source
        files.  It is best to put this option on the end of the
        command, so that the names of the files to be traced are
        not confused with any other filenames or strings on the
        command line.

WWIINNDDOOWWSS--NNTT
        It is possible to build Cook for Windows-NT.  I have done
        this using the Cygnus freeware CygWin32 system, and I
        believe it has also once been done using the commercial
        NutCracker system.  This document only describes the
        CygWin32 port.

   TThhee SSoouurrccee
        You need to FTP the CygWin32 system from Cygnus.  It can
        be found at
                http://sourceware.cygnus.com/cygwin/
        and then follow the links.  The version I used was B20.1.

   MMoouunnttiinngg TThhiinnggss
        You need to mount a directory onto /tmp, or lots of
        things, and especially _b_a_s_h(1), don't work.  If you are
        in a heavily networked environment, like me, you need to
        know that using a networked drive for /tmp just doesn't
        work.  I have no idea why.  Use
                mount C:/temp /tmp
        instead.  (Or some other local drive.)

        Just a tip for all of you who, like me, know UNIX much
        better than you know Windows-NT: the left-hand mount
        argument needs to be specified with a drive letter (_e_._g_.
        C:_) _r_a_t_h_e_r _t_h_a_n _w_i_t_h _a _d_o_u_b_l_e _s_l_a_s_h _(_e_._g_. _n_o_t //C_) _u_n_l_e_s_s
        _i_t_s _W_i_n_d_o_w_s_-_N_T _n_a_m_e _s_t_a_r_t_s _w_i_t_h _\_\_.

        You need to mount the Cygnus bin directory at /bin,
        otherwise shell scripts that start with #!/bin/sh don't
        work, among other things.  This includes the ./configure
        script, and the scripts it writes (_e_._g_. config.status).
                mount Cygnus-Dir/H-i386-cygwin/bin /bin
        You will want to mount your various network drives onto
        the same places they appear on your UNIX hosts.  This
        means that your cookbooks will work without change, even



Reference Manual               Cook                            26





Build(Cook)                                           Build(Cook)


        if they contain absolute paths.  And your users don't
        need to learn two names for all the source files.

        Don't forget your home directory.  The trick is to set
        HOME in the cygnus.bat file, before bash starts.  (How
        you do this with one batch file and multiple users I
        haven't yet figured out.)

        You also need to set the LOGNAME and USER environment
        variables appropriately, or test 14 will fail.

        Mounts persist across Cygwin sessions.  They are stored
        in a registry file somewhere.  You will not need to do
        all this every time!

   BBeeffoorree yyoouurr ssttaarrtt
        You will need to install a couple of other pieces of
        software before you build Cook.

        util-linux
                You need to get GNU rx, but to make it work you
                have to find a _t_s_o_r_t command, so that GNU rx's
                _._/_c_o_n_f_i_g_u_r_e script works.  Try the latest copy of
                system/misc/util-linux-?.?.tar.gz from the
                sunsite.unc.edu Linux archive (or a mirror).
                Simply build and install _m_i_s_c_-_u_t_i_l_s_/_t_s_o_r_t_._c by
                hand.

        GNU rx  Once you have _t_s_o_r_t installed, you will be able
                to get GNU rx configured.  Get a copy from your
                local GNU mirror.

   CCoonnffiigguurree
        The configure and build step should be the same as for
        UNIX, as described above.  All the problems I encountered
        were to do with getting the mounts just right.  (But
        expect it to be dog slow compared to Linux or FreeBSD on
        the same box.)

        The configure step is almost the same as for UNIX.  I
        know you are itching to get typing, but read throught to
        the install section before you configure anything.
                bbaasshh$$ ./configure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$

   BBuuiilldd
        The build step is exactly the same as for UNIX, and you
        shouldn't notice any difference...
                bbaasshh$$ make
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$





Reference Manual               Cook                            27





Build(Cook)                                           Build(Cook)


   TTeesstt
        All of the tests should pass, you only need to run them
        to convince yourself the build worked...  (a constant
        surprize to me, I must say!)
                bbaasshh$$ make sure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                PPaasssseedd AAllll TTeessttss
                bbaasshh$$

        If test 12 fails, it probably means you don't have _/_b_i_n
        right.

   IInnssttaallll
        Installing the software works as usual, though you need
        to make some choices right at the start (I told you to
        read this all the way through first).  If you want to use
        the ``_/_u_s_r_/_l_o_c_a_l'' prefix (or any other install prefix)
        you mount it right at the start.  For anything other than
        the ``_/_u_s_r_/_l_o_c_a_l'' default prefix, you also needed to
        give a ``----pprreeffiixx==_b_l_a_h_b_l_a_h_'_' _a_r_g_u_m_e_n_t _t_o _t_h_e _c_o_n_f_i_g_u_r_e
        _s_c_r_i_p_t_, _r_i_g_h_t _a_t _t_h_e _s_t_a_r_t_.
                bbaasshh$$ _m_a_k_e _i_n_s_t_a_l_l
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$

CCOOPPYYRRIIGGHHTT
        _c_o_o_k version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
        Miller; All rights reserved.

        The _C_o_o_k package 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.

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

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














Reference Manual               Cook                            28





Internationalization(Cook)             Internationalization(Cook)


NNAAMMEE
       Internationalization

DDEESSCCRRIIPPTTIIOONN
       The Cook package has gone international; it can now speak
       many languages.  This is accomplished by using the GNU
       Gettext library and utilities.  In order to do this, is is
       necessary to install GNU Gettext prior to configuring,
       making and installing the Cook package, as described in
       the _B_U_I_L_D_I_N_G file.

   IInntteerrnnaattiioonnaalliizzaattiioonn
       This is the process of identifying all of the error
       messages in the source code, and providing error message
       catalogues in a variety of languages.  The error message
       identification was performed by the Cook package's author,
       and the various GNU translation teams provided the
       translations.  Users of the Cook package do not need to do
       anything to internationalize it, this has already been
       done.

   LLooccaalliizzaattiioonn
       The programs in the Cook package are "localizable" when
       properly installed; the programs they contain can be made
       to speak your own native language.

       By default, the Cook package will be installed to allow
       translation of messages.  It will automatically detect
       whether the system provides a usable `gettext' function.

IINNSSTTRRUUCCTTIIOONNSS FFOORR UUSSEERRSS
       As a user, if your language has been installed for this
       package, you only have to set the `LANG' environment
       variable to the appropriate ISO 639 two-letter code prior
       to using the programs in the package.  For example, let's
       suppose that you speak German.  At the shell prompt,
       merely execute
              setenv LANG de
       (in `csh'), or
              LANG=de; export LANG
       (in `sh').  This can be done from your _._c_s_h_r_c or _._p_r_o_f_i_l_e
       file, setting this automatically each time you login.

       An operating system might already offer message
       localization for many of its programs, while other
       programs have been installed locally with the full
       capabilities of GNU Gettext.  Using the GNU Gettext
       extended syntax for the `LANG' environment variable may
       break the localization of already available through the
       operating system.  In this case, users should set both the
       `LANGUAGE' and `LANG' environment variables, as programs
       using GNU Gettext give preference to the `LANGUAGE'
       environment variable.




Reference Manual               Cook                            29





Internationalization(Cook)             Internationalization(Cook)


       For example, some Swedish users would rather read
       translations in German when Swedish is not available.
       This is easily accomplished by setting `LANGUAGE' to
       `sv:de' while leaving `LANG' set to `sv'.

DDIIRREECCTTOORRYY SSTTRRUUCCTTUURREE
       All files which may require translation are located below
       the _l_i_b directory of the source distribution.  It is
       organized as one directory below _l_i_b for each
       localization.  Localizations include all documentation as
       well as the error messages.

   LLooccaalliizzaattiioonn DDiirreeccttoorryy NNaammeess
       Each localization is contained in a sub-directory of the
       _l_i_b directory, with a unique name.  Each localization sub-
       directory has a name of the form:
localization +--------+
------------+_l-_a-_n-_g-_u-_a-_g-_e-+-------------------------------------------------
                        +   --  +-------+  +    +    + -+------+   +
                         --------_t+_e-_r-_r-_i-_t-_o-_r-_y+--       --+. --+_c-_o-_d-_e-_s-_e-_t+--


       _l_a_n_g_u_a_g_e  is one of the 2-letter names from the ISO 639
                 standard.  See _h_t_t_p_:_/_/_w_w_w_._i_c_s_._u_c_i_._e_d_u_/_p_u_b_/_i_e_t_f_/_-
                 _h_t_t_p_/_r_e_l_a_t_e_d_/_i_s_o_6_3_9_._t_x_t for a list.

       _t_e_r_r_i_t_o_r_y is one of the 2-letter country codes from the
                 ISO 3166 standard.  See _f_t_p_:_/_/_r_s_._i_n_t_e_r_n_i_c_._n_e_t_/_-
                 _n_e_t_i_n_f_o_/_i_s_o_3_1_6_6_-_c_o_u_n_t_r_y_c_o_d_e_s for a list.

       _c_o_d_e_s_e_t   is one of the codeset names defined in RFC 1345.
                 This simplifies the task of moving localizations
                 between charsets, because GNU Recode understands
                 them.  See _h_t_t_p_:_/_/_i_n_f_o_._i_n_t_e_r_n_e_t_._i_s_i_._e_d_u_/_1_s_/_-
                 _i_n_-_n_o_t_e_s_/_r_f_c_/_f_i_l_e_s_/_r_f_c_1_3_4_5_._t_x_t for a list.

       Here are some examples of localization names:
                +---------------------------------------+
                |   Name             Description        |
                +---------------------------------------+
                |en.ascii      English, ASCII encoding  |
                |en_us.ascii   English with US spelling |
                |de.latin1     German, Latin-1 encoding |
                +---------------------------------------+
   LLooccaalliizzaattiioonn DDiirreeccttoorryy CCoonntteennttss
       Each localization sub-directory in turn contains sub-
       directories.  These are:










Reference Manual               Cook                            30





Internationalization(Cook)             Internationalization(Cook)


              +-------------------------------------------+
              | Directory              Contents           |
              +-------------------------------------------+
              |LC_MESSAGES   The error message (PO) files |
              |building      The BUILDING file            |
              |man1          The section 1 manual entries |
              |readme        The README file              |
              |refman        The Reference Manual         |
              |user-guide    The User Guide               |
              +-------------------------------------------+
       The structure is identical below each of the localization
       directories.  The sub-directories of all localizations
       will have the same names.

IINNSSTTRRUUCCTTIIOONNSS FFOORR TTRRAANNSSLLAATTOORRSS
       When translating the error messages, all of the
       substitutions described in _c_o_o_k___s_u_b(5) are also available.
       Substitution variable names and function names may be
       abbreviated, in the same way that command line options are
       abbreviated, but abbreviation should probably be avoided.
       Substitution names will _n_e_v_e_r be internationalized,
       otherwise the substitutions will stop working, Catch-22.

       While Cook was written by an English speaker, the English
       localization is necessary, to translate the ``terse
       programmer'' style error messages into something more user
       friendly.

       Messages which include command line options need to leave
       the command line options untranslated, because they are
       not yet internationalized, though they may be one day.

       Each LC_MESSAGES directory within each localization
       contains a number of PO files.  There is one for each
       program in the Cook package, plus one called common.po
       containing messages common to all of them.  The MO file
       for each program is generated by naming the program
       specific PO file and also the common PO file.



















Reference Manual               Cook                            31





C_INCL(1)                                               C_INCL(1)


NNAAMMEE
        c_incl - determine dependencies

SSYYNNOOPPSSIISS
        cc__iinnccll [ _o_p_t_i_o_n...  ] _f_i_l_e_n_a_m_e
        cc__iinnccll --HHeellpp
        cc__iinnccll --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        The _c___i_n_c_l program is used to traverse source files
        looking for include dependencies suitable for
        [collect]ion or #include-cooked-ing by cook.

        The filename ``-'' is understood to mean the standard
        input.  When you use this file name, caching is ignored.

        Several input languages are supported, see the options
        list for details.

OOPPTTIIOONNSS
        The following options are understood.

        --CC      The source file is a C source file.  It is
                assumed that it will have the dependencies
                resolved by the _c_p_p(1) command.  The same include
                semantics as the _c_p_p(1) command will be employed.
                This is the default.  This is short-hand for
                ``--language=c''

        ----LLaanngguuaaggee==_n_a_m_e
                This option may be used to specify the language
                of the source file.  Know names include ``C'',
                ``M4'', ``optimistic'' and ``roff''.

                The ``optimistic'' language will take on almost
                anything.  It accepts an include keyword in any
                case, including mixed, with leading white space,
                but at most one leading punctuation character.
                It assumes that the filename follows the include
                keyword and does not contain white space, and
                does not start or end with punctuation characters
                (it strips off any it may find).  The rest of the
                line is ignored.  The drawback is that it will
                sometimes recognise commands and other text as
                unintended include directives, hence the name.
                This is often used to recognise include
                directives in a wide variety of assembler input.

        --RRooffff   The source file is a *roff source file.  It is
                assumed that it will have the dependencies
                resolved by the _r_o_f_f_p_p(1) command.  The same
                include semantics as the _r_o_f_f_p_p(1) command will
                be employed.  This is short-hand for
                ``--language=roff''



Reference Manual               Cook                            32





C_INCL(1)                                               C_INCL(1)


        --VVeerrbboossee
                Tell what is happening.  --II_p_a_t_h
                Specify include path, a la _c_c(1).

        --II--
                Any directories you specify with --II options
                before the --II-- option are searched only for the
                case of _#_i_n_c_l_u_d_e _"_f_i_l_e_"; they  are  not  searched
                for _#_i_n_c_l_u_d_e _<_f_i_l_e_>.

                If  additional  directories are specified with --II
                options after  the --II--, these directories are
                searched for all _#_i_n_c_l_u_d_e directives.
                (Ordinarily all --II directories are used this
                way.)

                In addition, the _-_I_- option inhibits the  use  of
                the current directory (where the current input
                file came from) as the first search directory for
                _#_i_n_c_l_u_d_e _"_f_i_l_e_".  There is no way to override
                this effect of _-_I_-.  With _-_I_. you can specify
                searching the directory which was current when
                c_incl was invoked.  That is not exactly the same
                as what the preprocessor does by default, but it
                is often satisfactory.

                The _-_I_- option does not inhibit the use of the
                standard system directories for header files.
                Thus, _-_I_- and _-_N_o___S_y_s_t_e_m are independent.

        --AAbbssoolluuttee__PPaatthhss
                This option may be used to allow absolute paths
                in the output.  This is usually the default.

        --NNoo__AAbbssoolluuttee__PPaatthhss
                This option may be used to exclude absolute paths
                from the output.

        --AAbbsseenntt__LLooccaall__IIggnnoorree
                For files included using a _#_i_n_c_l_u_d_e
                _'_'_f_i_l_e_n_a_m_e_._h_'_' directive, ignore the file if it
                cannot be found.

        --AAbbsseenntt__LLooccaall__MMeennttiioonn
                For files included using a _#_i_n_c_l_u_d_e
                _'_'_f_i_l_e_n_a_m_e_._h_'_' directive, print the file name
                even if the file cannot be found.  This is the
                default (it probably needs to be built).

        --AAbbsseenntt__LLooccaall__EErrrroorr
                For files included using a _#_i_n_c_l_u_d_e
                _'_'_f_i_l_e_n_a_m_e_._h_'_' directive, print a fatal error if
                the file cannot be found.




Reference Manual               Cook                            33





C_INCL(1)                                               C_INCL(1)


        --AAbbsseenntt__SSyysstteemm__IIggnnoorree
                For files included with a _#_i_n_c_l_u_d_e _<_f_i_l_e_n_a_m_e_._h_>
                directive, ignore the file if it cannot be found.
                This is the default (it was probably ifdef'ed
                out).

        --AAbbsseenntt__SSyysstteemm__MMeennttiioonn
                For files included with a _#_i_n_c_l_u_d_e _<_f_i_l_e_n_a_m_e_._h_>
                directive, print the file name even if the file
                cannot be found.

        --AAbbsseenntt__SSyysstteemm__EErrrroorr
                For files included with a _#_i_n_c_l_u_d_e _<_f_i_l_e_n_a_m_e_._h_>
                directive, print a fatal error if the file cannot
                be found.

        --AAbbsseenntt__PPrrooggrraamm__IIggnnoorree
                If the file named on the command line cannot be
                found, behave as if the file were found, but was
                empty.

        --AAbbsseenntt__PPrrooggrraamm__EErrrroorr
                If the file named on the command line cannot be
                found, print a fatal error message.  This is the
                default.

        --EEssccaappee__NNeewwlliinneess
                This option may be used to request that newlines
                in the output are escaped with backslash (``\'')
                characters.

        --HHeellpp
                Give information on how to use _c___i_n_c_l.

        --EEXXcclluuddee _f_i_l_e_n_a_m_e
                This option may be used to nominate include file
                names which are not to be used.

        --VVEERRSSiioonn
                Tell what version of _c___i_n_c_l is being run.

        --IInntteerriioorr__FFiilleess _f_i_l_e_n_a_m_e...
                This option may be used to tell _c___i_n_c_l about
                include files which don't exist yet.  This is
                because they are interior to the dependency
                graph, but _c_o_o_k(1) hasn't finished walking it
                yet.  Often used with Cook's [interior-files]
                function.  (NNoottee:: the _f_i_l_e_n_a_m_e list has an
                arbitrary number of files; it ends at the next
                option or end-of-line, so you need to be careful
                where you put the input filename.)

        --NNoo__SSyysstteemm
                Do not search the _/_u_s_r_/_i_n_c_l_u_d_e directory.  By



Reference Manual               Cook                            34





C_INCL(1)                                               C_INCL(1)


                default this is searched last.  This option
                implies the -No_Absolute_Paths option, unless
                explicitly contradicted.

        --CCAAcchhee
                This option may be used to turn caching on.  This
                is the default.

        --NNoo__CCaacchhee
                This option may be used to turn caching off.

        --PPRREEffiixx _s_t_r_i_n_g
                This option may be used to print a string before
                any of the filenames are printed.  It will not be
                printed if no file names are printed.

        --QQuuoottee__FFiilleeNNaammeess
                This option may be used to have _c___i_n_c_l quote
                filenames.  This permits filenames to contain
                characters which are special to Cook, including
                spaces.

        --SSUUFFffiixx _s_t_r_i_n_g
                This option may be used to print a string after
                all of the filenames are printed.  It will not be
                printed if no file names are printed.

        --OOuuttppuutt _f_i_l_e_n_a_m_e
                This option may be used to specify the output
                file.  Defaults to the standard output if not
                set.

        --NNoo__SSoouurrccee__RReellaattiivvee__IInncclluuddeess
                This option will give a fatal error if a _#_i_n_c_l_u_d_e
                _'_'_f_i_l_e_n_a_m_e_._h_'_' directive is used.  This is
                necessary when you are using Cook's search_list
                functionality to stitch together a baseline and a
                private work area.

        --RREECCuurrssiioonn
                This option may be used to specify that nested
                include files are to be scanned, so that their
                includes may also be discovered.  This is the
                default.

        --NNoo__RREECCuurrssiioonn
                This option may be use to specify that nested
                include files are _n_o_t to be scanned.  This option
                is recommended for use with the Cook cascade-for
                recipes.  This option implies -NNoo__CCaacchhee, unless a
                --CCaacchhee option is specified.

        --RReemmoovvee__LLeeaaddiinngg__PPaatthh _p_a_t_h
                This option may be used to remove path prefixes



Reference Manual               Cook                            35





C_INCL(1)                                               C_INCL(1)


                from the included filenames.  May be used more
                than once.  This is necessary when you are using
                Cook's search_list functionality to stitch
                together a baseline and a private work area;
                usually as ``[prepost "-rlp=" "" [search_list]]''

        --SSTTrriippddoott
                This option may be used to specify that leading
                redundant dot directories are to be removed from
                paths before processing.  This is the default.

        --NNoo__SSTTrriippddoott
                This option may be used to specify that leading
                redundant dot directories need not be removed
                from paths before processing.  (Some path
                flattening may still occur.)

        --SSuubbssttiittuuttee__LLeeaaddiinngg__PPaatthh _f_r_o_m _t_o
                This option may be used to modify path prefixes
                from the included filenames.  May be used more
                than once.  This is necessary when you are
                performing heterogeneous builds in the same
                directory tree.  By using an ``arch'' variable to
                hold the architecture, and placing each
                architecture's objects in a separate directory
                tree, this option may be used as ``-slp [arch]
                "'[arch]'"'' (The outer quotes protect from Cook,
                the inner quotes protect from the shell.)  If you
                need more intricate editing, used _s_e_d(1).

        Any other options will generate an error.

        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 --HHeellpp 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 _c___i_n_c_l are long, this means ignoring the
        extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention is
        also understood.




Reference Manual               Cook                            36





C_INCL(1)                                               C_INCL(1)


CCAACCHHIINNGG
        The caching mechanism use by the _c___i_n_c_l program caches
        the results of searching files for include files (in a
        file called _._c___i_n_c_l_r_c in the current directory).  The
        cache is only refreshed when a file changes.

        The use of this cache has been shown to dramatically
        increase the performance of the _c___i_n_c_l program.
        Typically, only a small proportions files in a project
        change between builds, resulting in a very high cache hit
        rate.

        When using caching, always use the same command line
        options, otherwise weird and wonderful things will
        happen.

        The _._c___i_n_c_l_r_c file is a binary file.  If you wish to
        rebuild the cache, simply delete this file with the _r_m(1)
        command.  Being a binary file, the _._c___i_n_c_l_r_c file is not
        portable across machines or operating systems, so you
        will need to delete it when you move your sources.  It is
        a binary file for performance.

        Accesses to the _._c___i_n_c_l_r_c file use file locking, so
        recipies using _c___i_n_c_l need not use the single-thread
        clause.

EEXXIITT SSTTAATTUUSS
        The _c___i_n_c_l command will exit with a status of 1 on any
        error.  The _c___i_n_c_l command will only exit with a status
        of 0 if there are no errors.

CCOOPPYYRRIIGGHHTT
        _c___i_n_c_l version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
        Miller; All rights reserved.

        The _c___i_n_c_l program comes with ABSOLUTELY NO WARRANTY; for
        details use the '_c___i_n_c_l _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.  This
        is free software and you are welcome to redistribute it
        under certain conditions; for details use the '_c___i_n_c_l
        _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.

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










Reference Manual               Cook                            37





COOK(1)                                                   COOK(1)


NNAAMMEE
        cook - a file construction tool

SSYYNNOOPPSSIISS
        ccooookk [ _o_p_t_i_o_n...  ][ _f_i_l_e_n_a_m_e...  ]
        ccooookk --HHeellpp
        ccooookk --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        The _c_o_o_k 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 _c_o_o_k
        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 _c_o_o_k 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 _c_o_o_k 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 _f_i_l_e_n_a_m_e..oo from _f_i_l_e_n_a_m_e..cc

        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 _c_o_o_k program will attempt to create the named files
        from the recipes given to it.  The recipes are contained
        in a file called _H_o_w_t_o_._c_o_o_k in the currect directory.
        This file may, in turn, include other files containing
        additional recipes.

        If no _f_i_l_e_n_a_m_es are given on the command line the targets
        of the first recipe defined are cooked.

OOPPTTIIOONNSS
        The valid options for _c_o_o_k are listed below.  Any other
        options (words on the command line beginning with `--')
        will cause a diagnostic message to be issued.

        --AAccttiioonn
                Execute the commands given in the recipes.  This
                is the default.

        --NNoo__AAccttiioonn
                Do not execute the commands given in the recipes.



Reference Manual               Cook                            38





COOK(1)                                                   COOK(1)


        --BBooookk _f_i_l_e_n_a_m_e
                Tells cook to used the named cookbook, rather
                than the default ``Howto.cook'' file.

        --CCAASSccaaddee
                This option may be used to enable the use of
                cascaded ingredients.  This is the default.

        --NNoo__CCAASSccaaddee
                This option may be used to disable the use of
                cascaded ingredients.

        --CCoonnttiinnuuee
                If cooking a target should fail, continue with
                other recipes for which the failed target is not
                an ingredient, directly or indirectly.

        --NNoo__CCoonnttiinnuuee
                If cooking a target should fail, _c_o_o_k will exit.
                This is the default.

        --EErrrrookk
                When a command is executed, the exit code will be
                ignored.

        --NNoo__EErrrrookk
                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.

        --FFiinnggeerrPPrriinntt
                When _c_o_o_k 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 _c_o_o_k_f_p(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 _t_o_u_c_h(1) command - _c_o_o_k will do nothing
                until you actually change the file.

        --NNoo__FFiinnggeerrPPrriinntt
                Do not use fingerprints to supplement the last-
                modified time file information.  This is the
                default.





Reference Manual               Cook                            39





COOK(1)                                                   COOK(1)


        --FFiinnggeerrPPrriinntt__UUppddaattee
                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.

        --FFoorrccee
                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.

        --NNoo__FFoorrccee
                Perform the actions of the recipes if any of the
                ingredients are logically out of date.  This is
                the default.

        --HHeellpp
                Provide information about how to execute _c_o_o_k on
                _s_t_d_o_u_t, and perform no other function.

        --IInncclluuddee _f_i_l_e_n_a_m_e
                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 _$_H_O_M_E_/_._c_o_o_k then
                _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_c_o_o_k.

        --IInncclluuddee__CCooookkeedd
                This option may be used to require the cooking of
                files named on _#_i_n_c_l_u_d_e_-_c_o_o_k_e_d and _#_i_n_c_l_u_d_e_-
                _c_o_o_k_e_d_-_n_o_w_a_r_n 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.

        --NNoo__IInncclluuddee__CCooookkeedd
                This option may be used to inhibit the implicit
                cooking of files named on _#_i_n_c_l_u_d_e_-_c_o_o_k_e_d and
                _#_i_n_c_l_u_d_e_-_c_o_o_k_e_d_-_n_o_w_a_r_n include lines in
                cookbooks.  The files will be included, if
                present, but they will not be updated or created,
                even if required.

        --IInncclluuddee__CCooookkeedd__WWaarrnniinngg
                This option enables the warnings about derived
                dependencies in derived cookbooks.  This is
                usually the default.




Reference Manual               Cook                            40





COOK(1)                                                   COOK(1)


        --NNoo__IInncclluuddee__CCooookkeedd__WWaarrnniinngg
                This option disables the warnings about derived
                dependencies in derived cookbooks.

        --LLiisstt
                Causes _c_o_o_k to automatically redirect the _s_t_d_o_u_t
                and _s_t_d_e_r_r of the session.  Output will continue
                to come to the terminal, unless _c_o_o_k 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
                _H_o_w_t_o_._l_i_s_t.  This is the default.

        --LLiisstt _f_i_l_e_n_a_m_e
                Causes _c_o_o_k to automatically redirect the _s_t_d_o_u_t
                and _s_t_d_e_r_r of the session into the named file.
                Output will continue to come to the terminal,
                unless _c_o_o_k is executing in the background.

        --NNoo__LLiisstt
                No automatic redirection of the output of the
                session will be made.

        --NNoo__LLiisstt _f_i_l_e_n_a_m_e
                No automatic redirection of the output of the
                session will be made, however subsequent --LLiisstt
                options will default to listing to the named
                file.

        --MMeetteerr
                After each command is executed, print a summary
                of the command's CPU usage.

        --NNoo__MMeetteerr
                Do not print a CPU usage summary after each
                command.  This is the default.

        --PPaaiirrss
                This option may be used to generate a list of
                pair-wise file dependencies, similar to _l_o_r_d_e_r(1)
                output.  This may be used to draw file dependency
                diagrams.  It can also be useful when debugging
                cookbooks.

        --PPAARRaalllleell [ _n_u_m_b_e_r ]
                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 _p_a_r_a_l_l_e_l___j_o_b_s 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-



Reference Manual               Cook                            41





COOK(1)                                                   COOK(1)


                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.

        --NNoo__PPAARRaalllleell
                This option may be used to specify that a single
                execution thread is to be used.  This is the
                default.

        --PPrreecciioouuss
                When commands in the body of a recipe fail, do
                not delete the targets of the recipe.

        --NNoo__PPrreecciioouuss
                When commands in the body of a recipe fail,
                delete the targets of the recipe.  This is the
                default.

        --RReeaassoonn
                Two options are provided for tracing the
                inferences ccooookk makes when attempting to cook a
                target.  The --RReeaassoonn option will cause _c_o_o_k will
                emit copious amounts of information about the
                inferences it is making when cooking targets.
                This option may be used when you think ccooookk is
                acting strangely, or are just curious.

        --NNoo__RReeaassoonn
                This option may be used to cause _c_o_o_k will not
                emit information about the inferences it is
                making when cooking targets.  This is the
                default.

        --SSCCrriipptt
                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
                _c_o_o_k_(_1_) installed.  It can also be very useful
                when debugging cookbooks.

        --SSiilleenntt
                Do not echo commands before they are executed.

        --NNoo__SSiilleenntt
                Echo commands before they are executed.  This is
                the default.

        --SSTTaarr
                Emit progress indicators once a second.  These
                progress indicators include



Reference Manual               Cook                            42





COOK(1)                                                   COOK(1)


                        +   Reading the cookbook
                        -   Executing a collect function
                        *   Building the dependency graph
                        #   Walking the dependency graph
                        @   Writing fingerprint files.

        --NNoo__SSTTaarr
                Do not emit progress indicators.  This is the
                default.

        --SSttrriipp__DDoott
                Remove leading "./" from filenames before
                attempting to cook them; applies to all filenames
                and all recipes.  This is the default.

        --NNoo__SSttrriipp__DDoott
                Leave leading "./" on filenames while cooking.

        --TToouucchh
                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.

        --NNoo__TToouucchh
                Execute the actions bound to recipes, rather than
                update the last-modified times of the target
                files.  This is the default.

        --TTEErrmmiinnaall
                When listing, also send the output stream to the
                terminal.  This is the default.

        --NNoo__TTEErrmmiinnaall
                When listing, do not send the output to the
                terminal.

        --TTiimmee__AAddjjuusstt
                This option causes ccooookk 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 _t_i_m_e_-_a_d_j_u_s_t
                recipe flag.

        --NNoo__TTiimmee__AAddjjuusstt
                Do not update the file last-modified times after
                performing the body of a recipe.  This is the
                default.  This correspondes to the _n_o_-_t_i_m_e_-_a_d_j_u_s_t



Reference Manual               Cook                            43





COOK(1)                                                   COOK(1)


                recipe flag.

        --WWeebb
                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.

        _n_a_m_e==_v_a_l_u_e
                Assign the _v_a_l_u_e 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 --HHeellpp 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 _c_o_o_k are long, this means ignoring the
        extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention is
        also understood.

EEXXIITT SSTTAATTUUSS
        The _c_o_o_k command will exit with a status of 1 on any
        error.  The _c_o_o_k command will only exit with a status of
        0 if there are no errors.

FFIILLEESS
        The following files are used by ccooookk:

        _H_o_w_t_o_._c_o_o_k
                This file contains instructions to _c_o_o_k for how
                to construct files.

        _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_c_o_o_k
                This directory contains "system" cookbooks for
                various tools and activities.





Reference Manual               Cook                            44





COOK(1)                                                   COOK(1)


        _._c_o_o_k_._f_p
                This text file is used to remember fingerprints
                between invokations.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
        The following environment variables are used by ccooookk:

        COOK    May be set to contain command-line options,
                changing the default behaviour of _c_o_o_k.  May be
                overridden by the command line.

        PAGER   Use to paginate the output of the --HHeellpp and
                --VVEERRSSiioonn options.  Defaults to _m_o_r_e(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.

CCOOPPYYRRIIGGHHTT
        _c_o_o_k version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
        Miller; All rights reserved.

        The _c_o_o_k program comes with ABSOLUTELY NO WARRANTY; for
        details use the '_c_o_o_k _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.  This is
        free software and you are welcome to redistribute it
        under certain conditions; for details use the '_c_o_o_k
        _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.








Reference Manual               Cook                            45





COOK(1)                                                   COOK(1)


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






















































Reference Manual               Cook                            46





cook_bom(1)                                           cook_bom(1)


NNAAMMEE
       cook_bom - bill of materials

SSYYNNOOPPSSIISS
       ccooookk__bboomm [ _o_p_t_i_o_n...  ] _d_i_r_n_a_m_e [ _o_u_t_f_i_l_e ]
       ccooookk__bboomm --HHeellpp
       ccooookk__bboomm --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
       The _c_o_o_k___b_o_m program is used to scan a directory and
       generate a cookbook fragment containing a bill of
       materials for that directory.  It also includes a
       recursive reference, via an ``#include-cooked'' directive,
       to the bills of materials for nested directories.

       Output is sent to the standard output unless an output
       filename is specified.

OOPPTTIIOONNSS
       The following options are understood:

       --DDIIRReeccttoorryy _p_a_t_h_n_a_m_e
               This option may be used to specify a directory
               search path, similar to _c_o_o_k(1) [search_list]
               functionality.

       --HHeellpp
               Provide some help with using the _c_o_o_k___b_o_m program.

       --IIGGnnoorree _s_t_r_i_n_g
               This option may be used to specify filename
               patterns to be ignored.  It may be given as many
               times as required.

       --PPRREEffiixx _s_t_r_i_n_g
               This option may be manipulate the name of the
               manifest files.  Defaults to the empty string if
               not set.

       --SSUUFFffiixx _s_t_r_i_n_g
               This option may be manipulate the name of the
               manifest files.  Defaults to ``/manifest.cook if
               not set.

       --VVEERRSSiioonn
               Print the version of the _c_o_o_k___b_o_m program being
               executed.

       All other options will produce a diagnostic error.

       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.



Reference Manual               Cook                            47





cook_bom(1)                                           cook_bom(1)


       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 --HHeellpp 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 _c_o_o_k___b_o_m are long, this means ignoring
       the extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention is
       also understood.

EEXXIITT SSTTAATTUUSS
       The _c_o_o_k___b_o_m command will exit with a status of 1 on any
       error.  The _c_o_o_k___b_o_m command will only exit with a status
       of 0 if there are no errors.

EEXXAAMMPPLLEE
       The intended use of this command is to automatically
       generate a project file manifest in an efficient way.  If
       you have a cookbook of the form
              all_files_in_. = ;
              #include manifest.cook
              manifest = [all_files_in_.];

              set fingerprint mkdir unlink;

              %0manifest.cook: ["if" [in "%0" ""] "then" "." "else" "%0"]
              {
                      cook_bom
                              [addprefix '--dir=' [search_list]]
                              "--ignore='*~'"
                              [need]
                              [target]
                              ;
              }
       At the end of this fragment, the manifest variable
       contains a complete list of all files in the directory
       tree.  This variable may then be taken apart with the
       match_mask function to build ingredients lists.

       The constructed _m_a_n_i_f_e_s_t_._c_o_o_k files work for both whole-
       project and recursive (not recommended) builds.

CCOOPPYYRRIIGGHHTT
       _c_o_o_k___b_o_m version 2.21
       Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
       1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
       Miller; All rights reserved.



Reference Manual               Cook                            48





cook_bom(1)                                           cook_bom(1)


       The _c_o_o_k___b_o_m program comes with ABSOLUTELY NO WARRANTY;
       for details use the '_c_o_o_k___b_o_m _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.
       This is free software and you are welcome to redistribute
       it under certain conditions; for details use the '_c_o_o_k___b_o_m
       _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.

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
















































Reference Manual               Cook                            49





GPL(GNU)             Free Software Foundation            GPL(GNU)


                       GNU GENERAL PUBLIC LICENSE
                          Version 2, June 1991

       Copyright (C) 1989, 1991 Free Software Foundation, Inc.
       59 Temple Place, Suite 330, Boston, MA 02111, USA
       Everyone is permitted to copy and distribute verbatim
       copies of this license document, but changing it is not
       allowed.

                                Preamble

       The licenses for most software are designed to take away
       your freedom to share and change it.  By contrast, the GNU
       General Public License is intended to guarantee your
       freedom to share and change free software--to make sure
       the software is free for all its users.  This General
       Public License applies to most of the Free Software
       Foundation's software and to any other program whose
       authors commit to using it.  (Some other Free Software
       Foundation software is covered by the GNU Library General
       Public License instead.)  You can apply it to your
       programs, too.

       When we speak of free software, we are referring to
       freedom, not price.  Our General Public Licenses are
       designed to make sure that you have the freedom to
       distribute copies of free software (and charge for this
       service if you wish), that you receive source code or can
       get it if you want it, that you can change the software or
       use pieces of it in new free programs; and that you know
       you can do these things.

       To protect your rights, we need to make restrictions that
       forbid anyone to deny you these rights or to ask you to
       surrender the rights.  These restrictions translate to
       certain responsibilities for you if you distribute copies
       of the software, or if you modify it.

       For example, if you distribute copies of such a program,
       whether gratis or for a fee, you must give the recipients
       all the rights that you have.  You must make sure that
       they, too, receive or can get the source code.  And you
       must show them these terms so they know their rights.

       We protect your rights with two steps: (1) copyright the
       software, and (2) offer you this license which gives you
       legal permission to copy, distribute and/or modify the
       software.

       Also, for each author's protection and ours, we want to
       make certain that everyone understands that there is no
       warranty for this free software.  If the software is
       modified by someone else and passed on, we want its
       recipients to know that what they have is not the



GNU                            GPL                             50





GPL(GNU)             Free Software Foundation            GPL(GNU)


       original, so that any problems introduced by others will
       not reflect on the original authors' reputations.

       Finally, any free program is threatened constantly by
       software patents.  We wish to avoid the danger that
       redistributors of a free program will individually obtain
       patent licenses, in effect making the program proprietary.
       To prevent this, we have made it clear that any patent
       must be licensed for everyone's free use or not licensed
       at all.

       The precise terms and conditions for copying, distribution
       and modification follow.












































GNU                            GPL                             51





GPL(GNU)             Free Software Foundation            GPL(GNU)


                       GNU GENERAL PUBLIC LICENSE
       TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

       0. This License applies to any program or other work which
       contains a notice placed by the copyright holder saying it
       may be distributed under the terms of this General Public
       License.  The "Program", below, refers to any such program
       or work, and a "work based on the Program" means either
       the Program or any derivative work under copyright law:
       that is to say, a work containing the Program or a portion
       of it, either verbatim or with modifications and/or
       translated into another language.  (Hereinafter,
       translation is included without limitation in the term
       "modification".)  Each licensee is addressed as "you".

       Activities other than copying, distribution and
       modification are not covered by this License; they are
       outside its scope.  The act of running the Program is not
       restricted, and the output from the Program is covered
       only if its contents constitute a work based on the
       Program (independent of having been made by running the
       Program).  Whether that is true depends on what the
       Program does.

       1. You may copy and distribute verbatim copies of the
       Program's source code as you receive it, in any medium,
       provided that you conspicuously and appropriately publish
       on each copy an appropriate copyright notice and
       disclaimer of warranty; keep intact all the notices that
       refer to this License and to the absence of any warranty;
       and give any other recipients of the Program a copy of
       this License along with the Program.

       You may charge a fee for the physical act of transferring
       a copy, and you may at your option offer warranty
       protection in exchange for a fee.

       2. You may modify your copy or copies of the Program or
       any portion of it, thus forming a work based on the
       Program, and copy and distribute such modifications or
       work under the terms of Section 1 above, provided that you
       also meet all of these conditions:

       a)  You must cause the modified files to carry prominent
           notices stating that you changed the files and the
           date of any change.

       b)  You must cause any work that you distribute or
           publish, that in whole or in part contains or is
           derived from the Program or any part thereof, to be
           licensed as a whole at no charge to all third parties
           under the terms of this License.

       c)  If the modified program normally reads commands



GNU                            GPL                             52





GPL(GNU)             Free Software Foundation            GPL(GNU)


           interactively when run, you must cause it, when
           started running for such interactive use in the most
           ordinary way, to print or display an announcement
           including an appropriate copyright notice and a notice
           that there is no warranty (or else, saying that you
           provide a warranty) and that users may redistribute
           the program under these conditions, and telling the
           user how to view a copy of this License.  (Exception:
           if the Program itself is interactive but does not
           normally print such an announcement, your work based
           on the Program is not required to print an
           announcement.)

       These requirements apply to the modified work as a whole.
       If identifiable sections of that work are not derived from
       the Program, and can be reasonably considered independent
       and separate works in themselves, then this License, and
       its terms, do not apply to those sections when you
       distribute them as separate works.  But when you
       distribute the same sections as part of a whole which is a
       work based on the Program, the distribution of the whole
       must be on the terms of this License, whose permissions
       for other licensees extend to the entire whole, and thus
       to each and every part regardless of who wrote it.

       Thus, it is not the intent of this section to claim rights
       or contest your rights to work written entirely by you;
       rather, the intent is to exercise the right to control the
       distribution of derivative or collective works based on
       the Program.

       In addition, mere aggregation of another work not based on
       the Program with the Program (or with a work based on the
       Program) on a volume of a storage or distribution medium
       does not bring the other work under the scope of this
       License.

       3. You may copy and distribute the Program (or a work
       based on it, under Section 2) in object code or executable
       form under the terms of Sections 1 and 2 above provided
       that you also do one of the following:

       a)  Accompany it with the complete corresponding machine-
           readable source code, which must be distributed under
           the terms of Sections 1 and 2 above on a medium
           customarily used for software interchange; or,

       b)  Accompany it with a written offer, valid for at least
           three years, to give any third party, for a charge no
           more than your cost of physically performing source
           distribution, a complete machine-readable copy of the
           corresponding source code, to be distributed under the
           terms of Sections 1 and 2 above on a medium
           customarily used for software interchange; or,



GNU                            GPL                             53





GPL(GNU)             Free Software Foundation            GPL(GNU)


       c)  Accompany it with the information you received as to
           the offer to distribute corresponding source code.
           (This alternative is allowed only for noncommercial
           distribution and only if you received the program in
           object code or executable form with such an offer, in
           accord with Subsection b above.)

       The source code for a work means the preferred form of the
       work for making modifications to it.  For an executable
       work, complete source code means all the source code for
       all modules it contains, plus any associated interface
       definition files, plus the scripts used to control
       compilation and installation of the executable.  However,
       as a special exception, the source code distributed need
       not include anything that is normally distributed (in
       either source or binary form) with the major components
       (compiler, kernel, and so on) of the operating system on
       which the executable runs, unless that component itself
       accompanies the executable.

       If distribution of executable or object code is made by
       offering access to copy from a designated place, then
       offering equivalent access to copy the source code from
       the same place counts as distribution of the source code,
       even though third parties are not compelled to copy the
       source along with the object code.

       4. You may not copy, modify, sublicense, or distribute the
       Program except as expressly provided under this License.
       Any attempt otherwise to copy, modify, sublicense or
       distribute the Program is void, and will automatically
       terminate your rights under this License.  However,
       parties who have received copies, or rights, from you
       under this License will not have their licenses terminated
       so long as such parties remain in full compliance.

       5. You are not required to accept this License, since you
       have not signed it.  However, nothing else grants you
       permission to modify or distribute the Program or its
       derivative works.  These actions are prohibited by law if
       you do not accept this License.  Therefore, by modifying
       or distributing the Program (or any work based on the
       Program), you indicate your acceptance of this License to
       do so, and all its terms and conditions for copying,
       distributing or modifying the Program or works based on
       it.











GNU                            GPL                             54





GPL(GNU)             Free Software Foundation            GPL(GNU)


       6. Each time you redistribute the Program (or any work
       based on the Program), the recipient automatically
       receives a license from the original licensor to copy,
       distribute or modify the Program subject to these terms
       and conditions.  You may not impose any further
       restrictions on the recipients' exercise of the rights
       granted herein.  You are not responsible for enforcing
       compliance by third parties to this License.

       7. If, as a consequence of a court judgment or allegation
       of patent infringement or for any other reason (not
       limited to patent issues), conditions are imposed on you
       (whether by court order, agreement or otherwise) that
       contradict the conditions of this License, they do not
       excuse you from the conditions of this License.  If you
       cannot distribute so as to satisfy simultaneously your
       obligations under this License and any other pertinent
       obligations, then as a consequence you may not distribute
       the Program at all.  For example, if a patent license
       would not permit royalty-free redistribution of the
       Program by all those who receive copies directly or
       indirectly through you, then the only way you could
       satisfy both it and this License would be to refrain
       entirely from distribution of the Program.

       If any portion of this section is held invalid or
       unenforceable under any particular circumstance, the
       balance of the section is intended to apply and the
       section as a whole is intended to apply in other
       circumstances.

       It is not the purpose of this section to induce you to
       infringe any patents or other property right claims or to
       contest validity of any such claims; this section has the
       sole purpose of protecting the integrity of the free
       software distribution system, which is implemented by
       public license practices.  Many people have made generous
       contributions to the wide range of software distributed
       through that system in reliance on consistent application
       of that system; it is up to the author/donor to decide if
       he or she is willing to distribute software through any
       other system and a licensee cannot impose that choice.

       This section is intended to make thoroughly clear what is
       believed to be a consequence of the rest of this License.












GNU                            GPL                             55





GPL(GNU)             Free Software Foundation            GPL(GNU)


       8. If the distribution and/or use of the Program is
       restricted in certain countries either by patents or by
       copyrighted interfaces, the original copyright holder who
       places the Program under this License may add an explicit
       geographical distribution limitation excluding those
       countries, so that distribution is permitted only in or
       among countries not thus excluded.  In such case, this
       License incorporates the limitation as if written in the
       body of this License.

       9. The Free Software Foundation may publish revised and/or
       new versions of the General Public License from time to
       time.  Such new versions will be similar in spirit to the
       present version, but may differ in detail to address new
       problems or concerns.

       Each version is given a distinguishing version number.  If
       the Program specifies a version number of this License
       which applies to it and "any later version", you have the
       option of following the terms and conditions either of
       that version or of any later version published by the Free
       Software Foundation.  If the Program does not specify a
       version number of this License, you may choose any version
       ever published by the Free Software Foundation.

       10. If you wish to incorporate parts of the Program into
       other free programs whose distribution conditions are
       different, write to the author to ask for permission.  For
       software which is copyrighted by the Free Software
       Foundation, write to the Free Software Foundation; we
       sometimes make exceptions for this.  Our decision will be
       guided by the two goals of preserving the free status of
       all derivatives of our free software and of promoting the
       sharing and reuse of software generally.

                              NO WARRANTY

       11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE
       IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
       APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING
       THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
       PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
       EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
       PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
       PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
       PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
       NECESSARY SERVICING, REPAIR OR CORRECTION.

       12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
       AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY
       OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM
       AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
       INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR



GNU                            GPL                             56





GPL(GNU)             Free Software Foundation            GPL(GNU)


       CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY
       TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
       DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED
       BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
       OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
       OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGES.

                      END OF TERMS AND CONDITIONS
















































GNU                            GPL                             57





GPL(GNU)             Free Software Foundation            GPL(GNU)


        Appendix: How to Apply These Terms to Your New Programs

       If you develop a new program, and you want it to be of the
       greatest possible use to the public, the best way to
       achieve this is to make it free software which everyone
       can redistribute and change under these terms.

       To do so, attach the following notices to the program.  It
       is safest to attach them to the start of each source file
       to most effectively convey the exclusion of warranty; and
       each file should have at least the "copyright" line and a
       pointer to where the full notice is found.

           < one line to give the program's name and a brief idea
           of what it does.  >
           Copyright (C) 19yy < name of author >

           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.

       Also add information on how to contact you by electronic
       and paper mail.

       If the program is interactive, make it output a short
       notice like this when it starts in an interactive mode:

           Gnomovision version 69, Copyright (C) 19yy name of
           author
           Gnomovision comes with ABSOLUTELY NO WARRANTY; for
           details type `show w'.  This is free software, and you
           are welcome to redistribute it under certain
           conditions; type `show c' for details.

       The hypothetical commands `show w' and `show c' should
       show the appropriate parts of the General Public License.
       Of course, the commands you use may be called something
       other than `show w' and `show c'; they could even be
       mouse-clicks or menu items--whatever suits your program.





GNU                            GPL                             58





GPL(GNU)             Free Software Foundation            GPL(GNU)


       You should also get your employer (if you work as a
       programmer) or your school, if any, to sign a "copyright
       disclaimer" for the program, if necessary.  Here is a
       sample; alter the names:

           Yoyodyne, Inc., hereby disclaims all copyright
           interest in the program `Gnomovision' (which makes
           passes at compilers) written by James Hacker.

           < signature of Ty Coon, > 1 April 1989
           Ty Coon, President of Vice

       This General Public License does not permit incorporating
       your program into proprietary programs.  If your program
       is a subroutine library, you may consider it more useful
       to permit linking proprietary applications with the
       library.  If this is what you want to do, use the GNU
       Library General Public License instead of this License.







































GNU                            GPL                             59





cook_rsh(1)                                           cook_rsh(1)


NNAAMMEE
        cook - load balancing rsh

SSYYNNOOPPSSIISS
        ccooookk [ _o_p_t_i_o_n...  ] _a_r_c_h_i_t_e_c_t_u_r_e _c_o_m_m_a_n_d [ _a_r_g_u_m_e_n_t...  ]
        ccooookk --HHeellpp

DDEESSCCRRIIPPTTIIOONN
        The _c_o_o_k program is a wrapper around _r_s_h(1) which does
        simple load balancing.  It obtains its load information
        by running the _r_u_p(1) command, and selects the most
        suitable host hased on the architecture you specify, and
        the least load of all hosts of that architecture.

        The first command line argument is the architecture name
        which is used to get the list of possible hosts.  From
        that list the _r_u_p(1) command is run to determine the host
        with the lowest load, which is in turn used as the first
        argument of the eventual _r_s_h(1) command.

CCOOOOKKBBOOOOKKSS
        In order to make use of this program, somewhere in your
        cookbook, you need to add a line which reads
                parallel_rsh = "cook";
        If the host chosen is the same as the caller (build host)
        then this program just exec the command skipping the rsh.
        So it costs nothing to use this in a one machine network!

        For each recipe you want distributed to a remote host,
        you need to add a host-binding attribute to.  Typical
        usage is where you have a muti-architecture build.
                %1/%0%.o: %0%.c
                    host-binding %1 {
                    cc -o [target] -c [resolve %0%.c]; }
        In the recipe given here, each architecture has its
        object files placed into a separate architecture-specific
        directory tree.  The architecture name (%1) is used in
        the host-binding, so that the compiles may be load-
        balanced to all machines of that architecture.

        If you need a command to run on a specific host (say,
        because that's where a specific application license
        resides), then simply use the host name in the host-
        binding attribute, rather than an architecture name.

DDEEFFIINNIINNGG TTHHEE CCLLAASSSSEESS
        The _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_c_o_o_k_/_h_o_s_t___l_i_s_t_s_._p_l file is expected
        to exist, and to contain variable definitions used to
        determine if hosts are members of particular
        architectures.

        The _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_c_o_o_k_/_h_o_s_t___l_i_s_t_s_._p_l file defines a
        perl HOL "hash of lists" The hash is %ArchNames and it
        maps names of architectures as user want to see them, to



Reference Manual               Cook                            60





cook_rsh(1)                                           cook_rsh(1)


        list references as the actual lists are stored.

        The names of each architecture could be any form you wish
        but the convention is to use the GNUish names such as
        "sparc-sun-solaris2.8".

        For each architecture, define one or more lists of
        machines according to what function each machine set may
        do.  This can be as simple or as elaborate as required.
        The form of the list variable name can be any valid perl
        identifier but may as well be like the architecture name
        with dash changed to underbar and dot removed, and the
        type added.  For example one might define solaris hosts
        as:
                @sparc_sun_solaris28_hosts = (
                   "mickey", "minny", "scrooge" );
        And linux hosts as:
                @i386_linux22_hosts = (
                   "goofy", "scrooge" );

        If there is a need to define different sets of machines
        for different types of jobs then add a suffix to the
        names in the  _h_o_s_t_-_b_i_n_d_i_n_g directive on each of the
        recipes, and lists here with the same suffix.

        The hash to map argument names to lists is defined like:
                %ArchNames = (
                  "sparc-solaris2.8",     =>
                @sparc_solaris28_hosts,
                  "i586-unknown-linux22", => @i386_linux22_hosts,
                );

        Of course if users have differing opinions as to what the
        architecture names should look like, you can define
        "alias" mappings as well.
                  "sun4-SunOS-5.8",       =>
                @sparc_solaris28_hosts,
        Or maybe the level is of no importance, then define
                  "sparc-solaris",        =>
                @sparc_solaris28_hosts,
                  "sparc-solaris2.7",     =>
                @sparc_solaris28_hosts,
        Also, this list isn't allowed to be empty.

        And finally, curtesy of Perl, the last line of the file
        must read
                1; for obscure and magical reasons.

SSYYSSLLOOGG LLOOGGGGIINNGG
        Typical commands seen during a build would look like
                sh -c 'cd /aegis/dd/gumby2.2.C079 && \ sh -ce
                /aegis/dd/gumby2.2.C079/.6.1; \ echo $? >
                /aegis/dd/gumby2.2.C079/.6.2'
        So we can extract the project/ change from the command



Reference Manual               Cook                            61





cook_rsh(1)                                           cook_rsh(1)


        quite easily and logging it via syslog would be a trivial
        addition.

OOPPTTIIOONNSS
        This command is not usually given any options.

        --hh      Help - show usage info

        --vvPP     Verbose - report choice

        --TT_n     Trace value for testing

FFIILLEESS
        /usr/local/share/cook/exclude.hosts
                This file is used to list those host which must
                not be used by this script.  Simply list excuded
                hosts, one hostname per line.  If the file is
                absent, all hosts reported by rup(1) may be used.

        /usr/local/share/cook/host_lists.pl
                This file defines the classes of hosts for each
                architecture.

AAUUTTHHOORR
        Jerry Pendergraft <jerry@endocardial.com>
































Reference Manual               Cook                            62





cookfp(1)                                               cookfp(1)


NNAAMMEE
       cookfp - calculate file fingerprint

SSYYNNOOPPSSIISS
       ccooookkffpp [ _o_p_t_i_o_n...  ][ _f_i_l_e_n_a_m_e...  ]
       ccooookkffpp --HHeellpp
       ccooookkffpp --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
       The _c_o_o_k_f_p program is used to calculate the fingerprints
       of files.  A fingerprint is a hash of the contents of a
       file.  The default fingerprint is cryptographically
       strong, so the probability of two different files having
       the same fingerprint is less than 1 in 2**200.

       The fingerprint is based on Dan Berstien
       <djb@silverton.berkeley.edu> public domain fingerprint
       0.50 beta package 930809, posted to the alt.sources
       newsgroup.  This program produces identical results; the
       expected test results were generated using Dan's package.

       The fingerprint is a base-64-sanely-encoded fingerprint of
       the input.  Imagine this fingerprint as something
       universal and permanent.  A fingerprint is 76 characters
       long, containing the following:

       1.  A Snefru-8 (version 2.5, 8 passes, 512->256) hash.
           (Derived from the Xerox Secure Hash Function.)

       2.  An MD5 hash, as per RFC 1321.  (Derived from the
           RSADSI MD5 Message-Digest Algorithm.)

       3.  A CRC checksum, as in the new cksum utility.

       4.  Length modulo 2^40.

       The output format is not expected to be compatible with
       anything.  However, options are available to produce the
       purported output of Merkle's snefru program, the purported
       output of RSADSI's mddriver -x, or the purported output of
       the POSIX cksum program.

       If no files are named as input, the standard input will be
       used.  The special file name ``-'' is understood to mean
       the standard input.

OOPPTTIIOONNSS
       The following options are understood:

       --CChheecckkssuumm
               Print the CRC32 checksum and length of the named
               file(s).





Reference Manual               Cook                            63





cookfp(1)                                               cookfp(1)


       --IIddeennttiiffiieerr
               Print a condensed form of the fingerprint
               (obtained by performing a CRC32 checksum on the
               full fingerprint described above - a definite
               overkill).  This is an 8-digit hexadecimal number,
               useful for generating unique short identifiers out
               of long names.  The first character is forced to
               be a letter (g-p), so there is no problem in using
               the output as a variable name.

       --HHeellpp
               Provide some help with using the _c_o_o_k_f_p program.

       --MMeessssaaggee__DDiiggeesstt
               Print the RSA Data Security, Inc. MD5 Message-
               Digest Algorithm hash of the named file(s).

       --SSnneeffrruu Print the Snefru hash of the named file(s),
               derived from the Xerox Secure Hash Function.

       --VVEERRSSiioonn
               Print the version of the _c_o_o_k_f_p program being
               executed.

       All other options will produce a diagnostic error.

       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 --HHeellpp 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 _c_o_o_k_f_p are long, this means ignoring the
       extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention is
       also understood.

EEXXIITT SSTTAATTUUSS
       The _c_o_o_k_f_p command will exit with a status of 1 on any
       error.  The _c_o_o_k_f_p command will only exit with a status of
       0 if there are no errors.





Reference Manual               Cook                            64





cookfp(1)                                               cookfp(1)


CCOOPPYYRRIIGGHHTT
       _c_o_o_k_f_p version 2.21
       Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
       1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
       Miller; All rights reserved.

       The _c_o_o_k_f_p program comes with ABSOLUTELY NO WARRANTY; for
       details use the '_c_o_o_k_f_p _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.  This
       is free software and you are welcome to redistribute it
       under certain conditions; for details use the '_c_o_o_k_f_p
       _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.

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

       Portions of this program are derived from sources from
       other people, sometimes with liberal copyrights, and
       sometimes in the public domain.  These include:

       Dan Bernstien
               See _c_o_m_m_o_n_/_f_p_/_R_E_A_D_M_E for details.

       Gary S Brown.
               See _c_o_m_m_o_n_/_f_p_/_c_r_c_3_2_._c for details.

       RSA Data Security, Inc.
               See _c_o_m_m_o_n_/_f_p_/_m_d_5_._c for details.

       Xerox Corporation
               See _c_o_m_m_o_n_/_f_p_/_s_n_e_f_r_u_._c for details.

       In addition to the above copyright holders, there have
       been numerous authors and contributors, see the named
       files for details.  Files names are relative to the root
       of the _c_o_o_k distribution.





















Reference Manual               Cook                            65





COOKTIME(1)                                           COOKTIME(1)


NNAAMMEE
        cooktime - set file times

SSYYNNOOPPSSIISS
        ccooookkttiimmee [ _o_p_t_i_o_n...  ] _f_i_l_e_n_a_m_e...
        ccooookkttiimmee --HHeellpp
        ccooookkttiimmee --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        The _c_o_o_k_t_i_m_e program is used to set the modified time or
        access time of a file.  This can be used to defend
        against unwanted logical dependencies when making "minor"
        changes to files.

        If no option is specified, the default action is as if
        "_-_M_o_d_i_f_y _n_o_w" was specified.

OOPPTTIIOONNSS
        The following options are understood.

        --AAcccceessss _d_a_t_e
                This option may be used to set the last-access
                time of the files.  The date is relatively free-
                format; rember to use quotes to insulate spaces
                from the shell.

        --MMooddiiffyy _d_a_t_e
                This option may be used to set the last-modify
                time of the files.  The date is relatively free-
                format; rember to use quotes to insulate spaces
                from the shell.

        --RReeppoorrtt
                When use alone, produces a listing of access
                times and modify times for the named files.  When
                used with -Access or -Modify, produces a listing
                of the changes made.

        --HHeellpp
                Give some information on how to use the _c_o_o_k_t_i_m_e
                command.

        Any other option will generate a diagnostic error.

        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



Reference Manual               Cook                            66





COOKTIME(1)                                           COOKTIME(1)


        all interpreted to mean the --HHeellpp 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 _c_o_o_k_t_i_m_e are long, this means ignoring
        the extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention
        is also understood.

EEXXIITT SSTTAATTUUSS
        The _c_o_o_k_t_i_m_e command will exit with a status of 1 on any
        error.  The _c_o_o_k_t_i_m_e command will only exit with a status
        of 0 if there are no errors.

CCOOPPYYRRIIGGHHTT
        _c_o_o_k_t_i_m_e version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
        Miller; All rights reserved.

        The _c_o_o_k_t_i_m_e program comes with ABSOLUTELY NO WARRANTY;
        for details use the '_c_o_o_k_t_i_m_e _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.
        This is free software and you are welcome to redistribute
        it under certain conditions; for details use the
        '_c_o_o_k_t_i_m_e _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.

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

























Reference Manual               Cook                            67





FIND_LIBS(1)                                         FIND_LIBS(1)


NNAAMMEE
        find_libs - find pathnames of libraries

SSYYNNOOPPSSIISS
        ffiinndd__lliibbss [ --LL_p_a_t_h ...  ][ --ll_n_a_m_e ...  ]
        ffiinndd__lliibbss --HHeellpp
        ffiinndd__lliibbss --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        The _f_i_n_d___l_i_b_s program is used to find the actual pathname
        of a library specified on a _c_c(1) command line.  This
        allows _c_o_o_k(1) to know these dependencies.

OOPPTTIIOONNSS
        The following options are understood.

        --LL_p_a_t_h
                Specify a path to search for libraries on.  If
                more than one is specified, they will be scanned
                in the order given before the standard _/_u_s_r_/_l_i_b
                and _/_l_i_b places.  This is like the same argument
                to _c_c(1), and the usual find_libs option
                abbreviation rules do not apply.

        --ll_n_a_m_e
                Name a library to be searched for.  This is like
                the same argument to _c_c(1), and the usual
                find_libs option abbreviation rules do not apply.

        --HHeellpp
                Give some information on how to use the _f_i_n_d___l_i_b_s
                command.

        --VVEERRSSiioonn
                Tell the version of the _f_i_n_d___l_i_b_s command
                currently executing.

        All other options will result in a diagnostic error.

        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 --HHeellpp option.  The argument
        "-hlp" will not be understood, because consecutive
        optional characters were not supplied.

        Options and other command line arguments may be mixed



Reference Manual               Cook                            68





FIND_LIBS(1)                                         FIND_LIBS(1)


        arbitrarily on the command line.

        The GNU long option names are understood.  Since all
        option names for _f_i_n_d___l_i_b_s are long, this means ignoring
        the extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention
        is also understood.

EEXXIITT SSTTAATTUUSS
        The _f_i_n_d___l_i_b_s command will exit with a status of 1 on any
        error.  The _f_i_n_d___l_i_b_s command will only exit with a
        status of 0 if there are no errors.

CCOOPPYYRRIIGGHHTT
        _f_i_n_d___l_i_b_s version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
        Miller; All rights reserved.

        The _f_i_n_d___l_i_b_s program comes with ABSOLUTELY NO WARRANTY;
        for details use the '_f_i_n_d___l_i_b_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.
        This is free software and you are welcome to redistribute
        it under certain conditions; for details use the
        '_f_i_n_d___l_i_b_s _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.

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






























Reference Manual               Cook                            69





make2cook(1)                                         make2cook(1)


NNAAMMEE
        make2cook - translate makefiles into cookbooks

SSYYNNOOPPSSIISS
        mmaakkee22ccooookk [ _o_p_t_i_o_n...  ][ _i_n_f_i_l_e [ _o_u_t_f_i_l_e ]]
        mmaakkee22ccooookk --HHeellpp
        mmaakkee22ccooookk --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        The _m_a_k_e_2_c_o_o_k program is used to translate _M_a_k_e_f_i_l_es into
        cookbooks.  This command is provided to ease the
        transition to using the _c_o_o_k command.

        If no input file is named, or the special name  ``-'' is
        used, input will be taken from the standard input.  If no
        output file is named, or the special name  ``-'' is used,
        output will be taken from the standard output.

SSEEMMAANNTTIICCSS
        There is no one-to-one semantic mapping between _m_a_k_e
        semantics and _c_o_o_k semantics, so the results will
        probably need some manual editing.

        The functionality provided by classic _m_a_k_e _(_1_)
        implementations is accurately reproduced.  Extensions,
        such as those offered by GNU Make or BSD make, are not
        always understood, or are sometimes not reproduced
        identically.

        The following subsections enumerate a few of the things
        which are understood and not understood.  They are
        probably not complete.

   UUnnddeerrssttoooodd
        The _c_o_o_k program requires variables to be defined before
        they are used, whereas _m_a_k_e will default them to be
        empty.  This is understood, and empty definitions are
        inserted as required.

        Most of the builtin variables of GNU Make are understood.

        Most of the builtin rules of classic make, GNU Make and
        BSD make are reproduced.

        FFoorr bbeesstt rreessuullttss there should be a blank line after every
        rule, so that there can be no confusion where one rule
        ends and a new one begins.

        Builtin variables are defaulted from the environment, if
        an environment variable of the same name is set.

        The GNU Make _o_v_e_r_r_i_d_e variable assignment is understood.

        The GNU Make ``+='' assignment is understood.



Reference Manual               Cook                            70





make2cook(1)                                         make2cook(1)


        The GNU Make ``:='' variable assignment is understood.

        Traditional make assignments are macros, they are
        expanded on use, rather than on assignment.  The _c_o_o_k
        program has only variables.  Assignment statements are
        re-arranged to ensure the correct results when variables
        are referenced.

        Single and double suffix rules are understood.  The
        .SUFFIXES rules are understood and honoured.  Hint: if
        you want to suppress the builtin-recipes, use a .SUFFIXES
        rule with no dependencies.

        The .PHONY rule is understood, and is translated into a
        _s_e_t _f_o_r_c_e_d flag in appropriate recipes, except files from
        implicit recipes.

        The .PRECIOUS rule is understood, and is translated into
        a _s_e_t _p_r_e_c_i_o_u_s flag in the appropriate recipes, except
        files from implicit recipes.

        The .DEFAULT rule is understood, and is translated into
        an implicit recipe.

        The .IGNORE rule is understood, and is translated into a
        _s_e_t _e_r_r_o_k statement.

        The .SILENT rule is understood, and is translated into a
        _s_e_t _s_i_l_e_n_t statement.

        Most GNU Make functions are understood.  The _f_i_l_t_e_r and
        _f_i_l_t_e_r_-_o_u_t functions only understand a single pattern.
        The _s_o_r_t function does not remove duplicates (wrap the
        _s_t_r_i_n_g_s_e_t function around it if you need this).

        The GNU Make static pattern rules are understood.  They
        are translated into recipe predicates.

        The GNU Make and BSD make _i_n_c_l_u_d_e variants are
        understood.

        The bizarre irregularities surrounding archive files in
        automatic variables and suffix rules are understood, and
        translated into consistent readable recipes.  The _m_a_k_e
        semantics are preserved.

        The BSD make _._C_U_R_D_I_R variable is understood, and
        translated to an equivalent expression.  It cannot be
        assigned to.

        The GNU Make and BSD make conditionals are understood,
        provided that they bracket whole segments of the
        makefile, and that these segments are syntactically
        valid.  Cconditionals may also appear within rule body



Reference Manual               Cook                            71





make2cook(1)                                         make2cook(1)


        commands.  Conditionals are _n_o_t understood within the
        lines of a _d_e_f_i_n_e.

        The GNU Make _d_e_f_i_n_e is understood, but its use as a kind
        of ``function definition'' is _n_o_t understood.

        The GNU Make _e_x_p_o_r_t and _u_n_e_x_p_o_r_t directives are
        understood.

   NNoott UUnnddeerrssttoooodd
        The _c_o_o_k program tokenizes its input, whereas make does
        textual replacement.  The shennanigans required to
        construct a make macro containing a single space are not
        understood.  The translation will result in a _c_o_o_k
        variable which is empty.

        References to automatic variables within macro
        definitions will not work.

        The GNU Make _f_o_r_e_a_c_h function is olny partially
        understood.  This has no exact _c_o_o_k equivalent.

        The GNU Make _o_r_i_g_i_n function is not understood.  This has
        no _c_o_o_k equivalent.

        The _a_r_c_h_i_v_e((_m_e_m_b_e_r)) notation is not understood.  These
        semantics are not available from _c_o_o_k.

        The _M_A_K_E_F_I_L_E_S and _M_A_K_E_L_E_V_E_L variables are not translated,
        If you wish to reproduce this functionality, you must
        edit the output.

        The _M_A_K_E_F_L_A_G_S and _M_F_L_A_G_S variables will be translated to
        use the Cook _o_p_t_i_o_n_s function, which has a different
        range of values.

        Many variants of make can use builtin rules to make the
        Makefile if it is absent.  _C_o_o_k is unable to cook the
        cookbook if it is absent.

        Wildcards are not understood in rule targets, rule
        dependencies or include directives.  If you want these,
        you will have to edit the output to use the _[_w_i_l_d_c_a_r_d_]
        function.

        Home directory tildes (~) are not understood in targets
        and dependencies.  If you want this, you will have to
        edit the output to use the _[_h_o_m_e_] function.

        The -l_h_o_m_e dependency is not understood to mean a
        library.  If you want this, you will have to edit the
        output to use the _[_c_o_l_l_e_c_t _f_i_n_d_l_i_b_s _-_lname_] function.

        The _._E_X_P_O_R_T___A_L_L___V_A_R_I_A_B_L_E_S rule is not understood.  This



Reference Manual               Cook                            72





make2cook(1)                                         make2cook(1)


        has no _c_o_o_k equivalent.

OOPPTTIIOONNSS
        The following options are understood:

        --HHeellpp
                Provide some help with using the _m_a_k_e_2_c_o_o_k
                command.

        --EEnnvviirroonnmmeenntt
                This option causes fragments to test for
                environment variables when performing the default
                settings for variables.  (This corresponds to the
                make -e option.)

        --HHiissttoorryy__CCoommmmaannddss
                This option causes _m_a_k_e_2_c_o_o_k to include recipes
                for _R_C_S and _S_C_C_S in the output.

        --LLiinnee__NNuummbbeerrss
                Insert line number directives into the output, so
                that it is possible to tell where the lines came
                from.  Most useful when debugging.  _m_a_k_e_2_c_o_o_k
                program.

        --NNoo__IInntteerrnnaall__RRuulleess
                This option may be used to supress all generation
                of recipes corresponding to make's internal
                rules.  (This corresponds to the make -r option.)

        --VVEERRSSiioonn
                Print the version of the _m_a_k_e_2_c_o_o_k program being
                executed.

        All other options will produce a diagnostic error.

        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 --HHeellpp 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.





Reference Manual               Cook                            73





make2cook(1)                                         make2cook(1)


        The GNU long option names are understood.  Since all
        option names for _m_a_k_e_2_c_o_o_k are long, this means ignoring
        the extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention
        is also understood.

EEXXIITT SSTTAATTUUSS
        The _m_a_k_e_2_c_o_o_k command will exit with a status of 1 on any
        error.  The _m_a_k_e_2_c_o_o_k command will only exit with a
        status of 0 if there are no errors.

CCOOPPYYRRIIGGHHTT
        _m_a_k_e_2_c_o_o_k version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
        Miller; All rights reserved.

        The _m_a_k_e_2_c_o_o_k program comes with ABSOLUTELY NO WARRANTY;
        for details use the '_m_a_k_e_2_c_o_o_k _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.
        This is free software and you are welcome to redistribute
        it under certain conditions; for details use the
        '_m_a_k_e_2_c_o_o_k _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.

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
































Reference Manual               Cook                            74





ROFFPP(1)                                               ROFFPP(1)


NNAAMMEE
        roffpp - replace .so requests within *roff sources

SSYYNNOOPPSSIISS
        rrooffffpppp [ _o_p_t_i_o_n...  ][ _i_n_f_i_l_e [ _o_u_t_f_i_l_e ]]
        rrooffffpppp --HHeellpp
        rrooffffpppp --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        The _r_o_f_f_p_p command may be used to copies the input file
        to the output file, including files named using _._s_o
        directives along the way, and removing the _._s_o
        directives.

        This is useful when processing large multi-file documents
        with filters such as _t_b_l(1) or _e_q_n(1) which do not
        understand the _._s_o directive.  The _._n_x directive is not
        understood.  The _r_o_f_f_p_p program is not a general *roff
        interpreter, so many constructs will be beyond it,
        fortunately, most of them have nothing to do with include
        files.  Include files which cannot be found, probably
        from uninterpreted *roff constructs, if the files really
        does exist, will simply be passed through unchanged, for
        *roff to interpret at a later time.

        The _r_o_f_f_p_p program also allows the user to specify an
        include search path.  This allows, for example, common
        files to be kept in a central location.

        Only directives of the form
                ..ssoo _f_i_l_e_n_a_m_e
        are processed.  If the directive is introduced using the
        single quote form, or the dot is not the first character
        of the line, the directive will be ignored.

        Any extra arguments on the line are ignored, and quoting
        is not understood.  All characters are interpreted
        literally.

        Examples of directives which will be ignored include
                'so /usr/lib/tmac/tmac.an
                .if n .so yuck
        This list is not exhaustive.

        The special file name `--' on the command line means the
        standard input or standard output, as appropriate.  Files
        which are omitted are also assumed to be the standard
        input or standard output, as appropriate.

        The output attempts to keep file names and line numbers
        in sync by using the ..llff directive.  The ..llff directive is
        also understood as input.  This is compatible with
        _g_r_o_f_f(1) and the other GNU text utilities included in the
        groff package.



Reference Manual               Cook                            75





ROFFPP(1)                                               ROFFPP(1)


OOPPTTIIOONNSS
        The following options are understood.

        --II_p_a_t_h
                Specify include path, a la _c_c(1).  Include paths
                are searched in the order specified.  The include
                search path defaults to the current directory if
                and only if the user does not specify any include
                search paths.

        --HHeellpp
                Give information on how to use _r_o_f_f_p_p.

        --VVEERRSSiioonn
                Tell what version of _r_o_f_f_p_p is being run.

        Any other option will generate a diagnostic error.

        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 --HHeellpp 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 _r_o_f_f_p_p are long, this means ignoring the
        extra leading '-'.  The "----_o_p_t_i_o_n==_v_a_l_u_e" convention is
        also understood.

EEXXIITT SSTTAATTUUSS
        The _r_o_f_f_p_p command will exit with a status of 1 on any
        error.  The _r_o_f_f_p_p command will only exit with a status
        of 0 if there are no errors.

CCOOPPYYRRIIGGHHTT
        _r_o_f_f_p_p version 2.21
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002 Peter
        Miller; All rights reserved.

        The _r_o_f_f_p_p program comes with ABSOLUTELY NO WARRANTY; for
        details use the '_r_o_f_f_p_p _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.  This
        is free software and you are welcome to redistribute it



Reference Manual               Cook                            76





ROFFPP(1)                                               ROFFPP(1)


        under certain conditions; for details use the '_r_o_f_f_p_p
        _-_V_E_R_S_i_o_n _L_i_c_e_n_s_e' command.

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



















































Reference Manual               Cook                            77





ROFFPP(1)                                               ROFFPP(1)



























































Reference Manual               Cook                          1000





Table of Contents(Cook)                   Table of Contents(Cook)


         The README File  . . . . . . . . . . . . . . . . . .   1
         Release Notes  . . . . . . . . . . . . . . . . . . .   5
         How to Build the Sources . . . . . . . . . . . . . .  19
             Windows NT . . . . . . . . . . . . . . . . . . .  26
         Internationalization . . . . . . . . . . . . . . . .  29
c_incl(1)                                                     determine include dependencies 32
cook(1)  a file construction tool . . . . . . . . . . . . . .  38
cook_bom(1)                                                   bill of materials 47
cook_lic(1)                                                   GNU General Public License 50
cook_rsh(1)                                                   load balancing rsh 60
cookfp(1)                                                     calculate file fingerprint 63
cooktime(1)                                                   set file times 66
find_libs(1)                                                  find pathnames of libraries 68
make2cook(1)                                                  translate makefiles into cookbooks 70
roffpp(1)                                                     replace .so requests within *roff sources 75










































Reference Manual               Cook                           iii





Permuted Index(Cook)                         Permuted Index(Cook)


cook_rsh(1)    60             cook_rsh - load   balancing rsh
cook_bom(1)    47                  cook_bom -   bill of materials
cook_bom(1)    47                       cook_   bom - bill of materials
cookfp(1)      63                    cookfp -   calculate file
                                                fingerprint
c_incl(1)      32                               c_incl - determine
                                                dependencies
cook(1)        38               cook - a file   construction tool
cook(1)        38                               cook - a file
                                                construction tool
cook_bom(1)    47                               cook_bom - bill of
                                                materials
make2cook(1)   70       make2cook - translate   cookbooks
                               makefiles into
cookfp(1)      63                               cookfp - calculate file
                                                fingerprint
cook_rsh(1)    60                               cook_rsh - load balancing
                                                rsh
cooktime(1)    66                               cooktime - set file times
make2cook(1)   70                       make2   cook - translate
                                                makefiles into cookbooks
c_incl(1)      32          c_incl - determine   dependencies
c_incl(1)      32                    c_incl -   determine dependencies
cook(1)        38                    cook - a   file construction tool
cookfp(1)      63          cookfp - calculate   file fingerprint
cooktime(1)    66              cooktime - set   file times
find_libs(1)   68                               find_libs - find
                                                pathnames of libraries
find_libs(1)   68                 find_libs -   find pathnames of
                                                libraries
cookfp(1)      63     cookfp - calculate file   fingerprint
c_incl(1)      32                          c_   incl - determine
                                                dependencies
make2cook(1)   70       make2cook - translate   into cookbooks
                                    makefiles
find_libs(1)   68            find_libs - find   libraries
                                 pathnames of
find_libs(1)   68                       find_   libs - find pathnames of
                                                libraries
cook_rsh(1)    60                  cook_rsh -   load balancing rsh
make2cook(1)   70                               make2cook - translate
                                                makefiles into cookbooks
make2cook(1)   70       make2cook - translate   makefiles into cookbooks
cook_bom(1)    47          cook_bom - bill of   materials
find_libs(1)   68            find_libs - find   pathnames of libraries
roffpp(1)      75                    roffpp -   replace .so requests
                                                within *roff sources
roffpp(1)      75        roffpp - replace .so   requests within *roff
                                                sources
roffpp(1)      75                               roffpp - replace .so
                                                requests within *roff
                                                sources





Reference Manual               Cook                            iv





Permuted Index(Cook)                         Permuted Index(Cook)


roffpp(1)      75        roffpp - replace .so   roff sources
                            requests within *
cook_rsh(1)    60   cook_rsh - load balancing   rsh
cook_rsh(1)    60                       cook_   rsh - load balancing rsh
cooktime(1)    66                  cooktime -   set file times
roffpp(1)      75          roffpp - replace .   so requests within *roff
                                                sources
roffpp(1)      75        roffpp - replace .so   sources
                        requests within *roff
cooktime(1)    66         cooktime - set file   times
cook(1)        38               cook - a file   tool
                                 construction
make2cook(1)   70                 make2cook -   translate makefiles into
                                                cookbooks
roffpp(1)      75        roffpp - replace .so   within *roff sources
                                     requests









































Reference Manual               Cook                             v


