.














                              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 24 February 2011.






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.

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






Reference Manual               Cook                             3





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                             4





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                             5





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.

   VVeerrssiioonn 22..1111










Reference Manual               Cook                             6





Read Me(Cook)                                       Read Me(Cook)


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



Reference Manual               Cook                             7





Read Me(Cook)                                       Read Me(Cook)


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

       * 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












Reference Manual               Cook                             8





Read Me(Cook)                                       Read Me(Cook)


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









Reference Manual               Cook                             9





Read Me(Cook)                                       Read Me(Cook)


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




Reference Manual               Cook                            10





Read Me(Cook)                                       Read Me(Cook)


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



















Reference Manual               Cook                            11





Read Me(Cook)                                       Read Me(Cook)


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




Reference Manual               Cook                            12





Read Me(Cook)                                       Read Me(Cook)


       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.

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







Reference Manual               Cook                            13





Read Me(Cook)                                       Read Me(Cook)


   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.

   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.
















Reference Manual               Cook                            14





Read Me(Cook)                                       Read Me(Cook)


   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.

   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.



Reference Manual               Cook                            15





Read Me(Cook)                                       Read Me(Cook)


       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.

   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                            16





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






Reference Manual               Cook                            17





Build(Cook)                                           Build(Cook)


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



Reference Manual               Cook                            18





Build(Cook)                                           Build(Cook)


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

        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



Reference Manual               Cook                            19





Build(Cook)                                           Build(Cook)


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



Reference Manual               Cook                            20





Build(Cook)                                           Build(Cook)


        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.

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.



Reference Manual               Cook                            21





Build(Cook)                                           Build(Cook)


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





Reference Manual               Cook                            22





Build(Cook)                                           Build(Cook)


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
                _._._._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).



Reference Manual               Cook                            23





Build(Cook)                                           Build(Cook)


                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 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$$

   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



Reference Manual               Cook                            24





Build(Cook)                                           Build(Cook)


                _._._._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                            25





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.

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






Reference Manual               Cook                            26





Internationalization(Cook)             Internationalization(Cook)


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:
                    +-------------------------------------------+
                    | 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.




Reference Manual               Cook                            27





Internationalization(Cook)             Internationalization(Cook)


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                            28





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''

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




Reference Manual               Cook                            29





C_INCL(1)                                               C_INCL(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.

        --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,



Reference Manual               Cook                            30





C_INCL(1)                                               C_INCL(1)


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



Reference Manual               Cook                            31





C_INCL(1)                                               C_INCL(1)


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




Reference Manual               Cook                            32





C_INCL(1)                                               C_INCL(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.

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



Reference Manual               Cook                            33





C_INCL(1)                                               C_INCL(1)


        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                            34





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.

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



Reference Manual               Cook                            35





COOK(1)                                                   COOK(1)


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

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



Reference Manual               Cook                            36





COOK(1)                                                   COOK(1)


                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.

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



Reference Manual               Cook                            37





COOK(1)                                                   COOK(1)


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



Reference Manual               Cook                            38





COOK(1)                                                   COOK(1)


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





Reference Manual               Cook                            39





COOK(1)                                                   COOK(1)


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



Reference Manual               Cook                            40





COOK(1)                                                   COOK(1)


                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.

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

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





Reference Manual               Cook                            41





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.

       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.



Reference Manual               Cook                            42





cook_bom(1)                                           cook_bom(1)


       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.

       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                            43





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




GNU                            GPL                             44





GPL(GNU)             Free Software Foundation            GPL(GNU)


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























































GNU                            GPL                             45





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



GNU                            GPL                             46





GPL(GNU)             Free Software Foundation            GPL(GNU)


       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,

       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.




GNU                            GPL                             47





GPL(GNU)             Free Software Foundation            GPL(GNU)


       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.

       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



GNU                            GPL                             48





GPL(GNU)             Free Software Foundation            GPL(GNU)


       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.

       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                             49





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                             50





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                             51





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                             52





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



Reference Manual               Cook                            53





cook_rsh(1)                                           cook_rsh(1)


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



Reference Manual               Cook                            54





cook_rsh(1)                                           cook_rsh(1)


                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                            55





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

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



Reference Manual               Cook                            56





cookfp(1)                                               cookfp(1)


               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.

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.








Reference Manual               Cook                            57





cookfp(1)                                               cookfp(1)


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                            58





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 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                            59





COOKTIME(1)                                           COOKTIME(1)


        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                            60





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




Reference Manual               Cook                            61





FIND_LIBS(1)                                         FIND_LIBS(1)


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                            62





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.

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

        Traditional make assignments are macros, they are expanded on use,



Reference Manual               Cook                            63





make2cook(1)                                         make2cook(1)


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



Reference Manual               Cook                            64





make2cook(1)                                         make2cook(1)


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



Reference Manual               Cook                            65





make2cook(1)                                         make2cook(1)


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

        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                            66





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.

OOPPTTIIOONNSS
        The following options are understood.

        --II_p_a_t_h
                Specify include path, a la _c_c(1).  Include paths are searched



Reference Manual               Cook                            67





ROFFPP(1)                                               ROFFPP(1)


                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 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                          1000





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


         The README File . . . . . . . . . . . . . . . . . . . . . . . . .   1
         Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . .   4
         How to Build the Sources  . . . . . . . . . . . . . . . . . . . .  17
             Windows NT  . . . . . . . . . . . . . . . . . . . . . . . . .  23
         Internationalization  . . . . . . . . . . . . . . . . . . . . . .  26
c_incl(1)                                                                  determine include dependencies 29
cook(1)  a file construction tool  . . . . . . . . . . . . . . . . . . . .  35
cook_bom(1)                                                                bill of materials 42
cook_lic(1)                                                                GNU General Public License 44
cook_rsh(1)                                                                load balancing rsh 53
cookfp(1)                                                                  calculate file fingerprint 56
cooktime(1)                                                                set file times 59
find_libs(1)                                                               find pathnames of libraries 61
make2cook(1)                                                               translate makefiles into cookbooks 63
roffpp(1)                                                                  replace .so requests within *roff sources 67










































Reference Manual               Cook                           iii





Permuted Index(Cook)                         Permuted Index(Cook)


cook_rsh(1)    53             cook_rsh - load   balancing rsh
cook_bom(1)    42                  cook_bom -   bill of materials
cook_bom(1)    42                       cook_   bom - bill of materials
cookfp(1)      56                    cookfp -   calculate file
                                                fingerprint
c_incl(1)      29                               c_incl - determine
                                                dependencies
cook(1)        35               cook - a file   construction tool
cook(1)        35                               cook - a file
                                                construction tool
cook_bom(1)    42                               cook_bom - bill of
                                                materials
make2cook(1)   63       make2cook - translate   cookbooks
                               makefiles into
cookfp(1)      56                               cookfp - calculate file
                                                fingerprint
cook_rsh(1)    53                               cook_rsh - load balancing
                                                rsh
cooktime(1)    59                               cooktime - set file times
make2cook(1)   63                       make2   cook - translate
                                                makefiles into cookbooks
c_incl(1)      29          c_incl - determine   dependencies
c_incl(1)      29                    c_incl -   determine dependencies
cook(1)        35                    cook - a   file construction tool
cookfp(1)      56          cookfp - calculate   file fingerprint
cooktime(1)    59              cooktime - set   file times
find_libs(1)   61                               find_libs - find
                                                pathnames of libraries
find_libs(1)   61                 find_libs -   find pathnames of
                                                libraries
cookfp(1)      56     cookfp - calculate file   fingerprint
c_incl(1)      29                          c_   incl - determine
                                                dependencies
make2cook(1)   63       make2cook - translate   into cookbooks
                                    makefiles
find_libs(1)   61            find_libs - find   libraries
                                 pathnames of
find_libs(1)   61                       find_   libs - find pathnames of
                                                libraries
cook_rsh(1)    53                  cook_rsh -   load balancing rsh
make2cook(1)   63                               make2cook - translate
                                                makefiles into cookbooks
make2cook(1)   63       make2cook - translate   makefiles into cookbooks
cook_bom(1)    42          cook_bom - bill of   materials
find_libs(1)   61            find_libs - find   pathnames of libraries
roffpp(1)      67                    roffpp -   replace .so requests
                                                within *roff sources
roffpp(1)      67        roffpp - replace .so   requests within *roff
                                                sources
roffpp(1)      67                               roffpp - replace .so
                                                requests within *roff
                                                sources





Reference Manual               Cook                            iv





Permuted Index(Cook)                         Permuted Index(Cook)


roffpp(1)      67        roffpp - replace .so   roff sources
                            requests within *
cook_rsh(1)    53   cook_rsh - load balancing   rsh
cook_rsh(1)    53                       cook_   rsh - load balancing rsh
cooktime(1)    59                  cooktime -   set file times
roffpp(1)      67          roffpp - replace .   so requests within *roff
                                                sources
roffpp(1)      67        roffpp - replace .so   sources
                        requests within *roff
cooktime(1)    59         cooktime - set file   times
cook(1)        35               cook - a file   tool
                                 construction
make2cook(1)   63                 make2cook -   translate makefiles into
                                                cookbooks
roffpp(1)      67        roffpp - replace .so   within *roff sources
                                     requests









































Reference Manual               Cook                             v


