.














                              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 1 August 2012.






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)


NNAAMMEE
       cook - a file construction tool

DDEESSCCRRIIPPTTIIOONN
       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!

AARRCCHHIIVVEE SSIITTEE
       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)


MMAAIILLIINNGG LLIISSTT
       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.

BBUUIILLDDIINNGG CCOOOOKK
       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.

CCOOPPYYRRIIGGHHTT
       _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.

AAUUTTHHOORR
       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)


NNEEWW IINN TTHHIISS RREELLEEAASSEE
       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.

   VVeerrssiioonn 22..2211
       * 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.

   VVeerrssiioonn 22..2200
       * 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.

   VVeerrssiioonn 22..1199
       * 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.

   VVeerrssiioonn 22..1188









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.

   VVeerrssiioonn 22..1177
       * 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.

   VVeerrssiioonn 22..1166
















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.

   VVeerrssiioonn 22..1155
       * 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.

   VVeerrssiioonn 22..1122
       * The _c___i_n_c_l program now has a --qquuoottee--ffiilleennaammeess 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.

   VVeerrssiioonn 22..1111










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.

   VVeerrssiioonn 22..1100
       * The _[_p_r_i_n_t_] and _[_w_r_i_t_e_] functions now work more sensably with the
       --SSCCrriipptt 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 --PPAARRaalllleell 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.

   VVeerrssiioonn 22..99
       * 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.

   VVeerrssiioonn 22..88












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.

   VVeerrssiioonn 22..77
       * 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.

   VVeerrssiioonn 22..66









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.

   RReelleeaassee 22..55
       * 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.

   RReelleeaassee 22..44
       * 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.

   RReelleeaassee 22..33




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.

   RReelleeaassee 22..22..22
       * 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.

   RReelleeaassee 22..22..11
       * 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.

   RReelleeaassee 22..22



















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.

   RReelleeaassee 22..11
       * 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.

   RReelleeaassee 22..00..11
       * An install problem in the generated Makefile, to do with the the
       manuals, has been fixed.

   RReelleeaassee 22..00




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.

   RReelleeaassee 11..1111
       * 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)


   RReelleeaassee 11..1100
       * 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.

   RReelleeaassee 11..99
       * 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)


   RReelleeaassee 11..88
       * 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.

   RReelleeaassee 11..77
       * The AIX code to handle archive files has been fixed.

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

   RReelleeaassee 11..66
       * 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.

   RReelleeaassee 11..55
       * 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.

       * CCooookk 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.

   RReelleeaassee 11..44
       * 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)


NNAAMMEE
        cook - a file construction tool

SSPPAACCEE RREEQQUUIIRREEMMEENNTTSS
        You will need about 5MB to unpack and build the _C_o_o_k package.  Your
        milage may vary.

BBEEFFOORREE YYOOUU SSTTAARRTT
        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)


SSIITTEE CCOONNFFIIGGUURRAATTIIOONN
        The CCooookk 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 CCooookk 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 CCooookk 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.

BBUUIILLDDIINNGG CCOOOOKK
        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.

        ccooookk    _c_o_o_k program is a file construction tool, and may invoke the
                following tools in some of its recipes.

        ccooookkffpp  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).

        ccooookkttiimmee
                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).

        cc__iinnccll  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).

        ffiinndd__lliibbss
                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).

        mmaakkee22ccooookk
                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)


        rrooffffpppp  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.

TTEESSTTIINNGG CCOOOOKK
        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_._._.
                PPaasssseedd AAllll TTeessttss
                %%

        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.

   KKnnoowwnn PPrroobblleemmss
        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.

IINNSSTTAALLLLIINNGG CCOOOOKK
        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.

PPRRIINNTTEEDD MMAANNUUAALLSS
        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)


GGEETTTTIINNGG HHEELLPP
        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
                ccooookk vveerrssiioonn _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 --TTRRAACCIInngg command line option.

        When the --TTRRAACCiinngg 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.

WWIINNDDOOWWSS--NNTT
        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.

   TThhee SSoouurrccee
        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.

   MMoouunnttiinngg TThhiinnggss
        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!

   BBeeffoorree yyoouurr ssttaarrtt
        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.

   CCoonnffiigguurree
        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.
                bbaasshh$$ ./configure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$

   BBuuiilldd
        The build step is exactly the same as for UNIX, and you shouldn't
        notice any difference...
                bbaasshh$$ make
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$

   TTeesstt
        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!)
                bbaasshh$$ make sure



Reference Manual               Cook                            24





Build(Cook)                                           Build(Cook)


                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                PPaasssseedd AAllll TTeessttss
                bbaasshh$$

        If test 12 fails, it probably means you don't have _/_b_i_n right.

   IInnssttaallll
        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 ``----pprreeffiixx==_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_.
                bbaasshh$$ _m_a_k_e _i_n_s_t_a_l_l
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$

CCOOPPYYRRIIGGHHTT
        _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.

AAUUTTHHOORR
        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)


NNAAMMEE
       Internationalization

DDEESSCCRRIIPPTTIIOONN
       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.

   IInntteerrnnaattiioonnaalliizzaattiioonn
       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.

   LLooccaalliizzaattiioonn
       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.

IINNSSTTRRUUCCTTIIOONNSS FFOORR UUSSEERRSS
       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)


DDIIRREECCTTOORRYY SSTTRRUUCCTTUURREE
       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.

   LLooccaalliizzaattiioonn DDiirreeccttoorryy NNaammeess
       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 |
                      +---------------------------------------+
   LLooccaalliizzaattiioonn DDiirreeccttoorryy CCoonntteennttss
       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)


IINNSSTTRRUUCCTTIIOONNSS FFOORR TTRRAANNSSLLAATTOORRSS
       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)


NNAAMMEE
        c_incl - determine dependencies

SSYYNNOOPPSSIISS
        cc__iinnccll [ _o_p_t_i_o_n...  ] _f_i_l_e_n_a_m_e
        cc__iinnccll --HHeellpp
        cc__iinnccll --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        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.

OOPPTTIIOONNSS
        The following options are understood.

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

        ----LLaanngguuaaggee==_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.

        --RRooffff   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''

        --VVeerrbboossee
                Tell what is happening.  --II_p_a_t_h
                Specify include path, a la _c_c(1).




Reference Manual               Cook                            29





C_INCL(1)                                               C_INCL(1)


        --II--
                Any directories you specify with --II options before the --II--
                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 --II options
                after  the --II--, these directories are searched for all
                _#_i_n_c_l_u_d_e directives.  (Ordinarily all --II 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.

        --AAbbssoolluuttee__PPaatthhss
                This option may be used to allow absolute paths in the output.
                This is usually the default.

        --NNoo__AAbbssoolluuttee__PPaatthhss
                This option may be used to exclude absolute paths from the
                output.

        --AAbbsseenntt__LLooccaall__IIggnnoorree
                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.

        --AAbbsseenntt__LLooccaall__MMeennttiioonn
                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).

        --AAbbsseenntt__LLooccaall__EErrrroorr
                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.

        --AAbbsseenntt__SSyysstteemm__IIggnnoorree
                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).

        --AAbbsseenntt__SSyysstteemm__MMeennttiioonn
                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.

        --AAbbsseenntt__SSyysstteemm__EErrrroorr
                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.

        --AAbbsseenntt__PPrrooggrraamm__IIggnnoorree
                If the file named on the command line cannot be found, behave
                as if the file were found, but was empty.

        --AAbbsseenntt__PPrrooggrraamm__EErrrroorr
                If the file named on the command line cannot be found, print a
                fatal error message.  This is the default.

        --EEssccaappee__NNeewwlliinneess
                This option may be used to request that newlines in the output
                are escaped with backslash (``\'') characters.

        --HHeellpp
                Give information on how to use _c___i_n_c_l.

        --EEXXcclluuddee _f_i_l_e_n_a_m_e
                This option may be used to nominate include file names which
                are not to be used.

        --VVEERRSSiioonn
                Tell what version of _c___i_n_c_l is being run.

        --IInntteerriioorr__FFiilleess _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.
                (NNoottee:: 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.)

        --NNoo__SSyysstteemm
                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.

        --CCAAcchhee
                This option may be used to turn caching on.  This is the
                default.

        --NNoo__CCaacchhee
                This option may be used to turn caching off.

        --PPRREEffiixx _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.

        --QQuuoottee__FFiilleeNNaammeess
                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)


        --SSUUFFffiixx _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.

        --OOuuttppuutt _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.

        --NNoo__SSoouurrccee__RReellaattiivvee__IInncclluuddeess
                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.

        --RREECCuurrssiioonn
                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.

        --NNoo__RREECCuurrssiioonn
                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
                -NNoo__CCaacchhee, unless a --CCaacchhee option is specified.

        --RReemmoovvee__LLeeaaddiinngg__PPaatthh _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]]''

        --SSTTrriippddoott
                This option may be used to specify that leading redundant dot
                directories are to be removed from paths before processing.
                This is the default.

        --NNoo__SSTTrriippddoott
                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.)

        --SSuubbssttiittuuttee__LLeeaaddiinngg__PPaatthh _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 --HHeellpp 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.

CCAACCHHIINNGG
        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.

EEXXIITT SSTTAATTUUSS
        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.

CCOOPPYYRRIIGGHHTT
        _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.

AAUUTTHHOORR
        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)


NNAAMMEE
        cook - a file construction tool

SSYYNNOOPPSSIISS
        ccooookk [ _o_p_t_i_o_n...  ][ _f_i_l_e_n_a_m_e...  ]
        ccooookk --HHeellpp
        ccooookk --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        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..oo
        from _f_i_l_e_n_a_m_e..cc

        Options and filenames may be arbitrarily mixed on the command line; no
        processing is done until all options and filenames on the command line
        have been scanned.

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

OOPPTTIIOONNSS
        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.

        --AAccttiioonn
                Execute the commands given in the recipes.  This is the
                default.

        --NNoo__AAccttiioonn
                Do not execute the commands given in the recipes.

        --BBooookk _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)


        --CCAASSccaaddee
                This option may be used to enable the use of cascaded
                ingredients.  This is the default.

        --NNoo__CCAASSccaaddee
                This option may be used to disable the use of cascaded
                ingredients.

        --CCoonnttiinnuuee
                If cooking a target should fail, continue with other recipes
                for which the failed target is not an ingredient, directly or
                indirectly.

        --NNoo__CCoonnttiinnuuee
                If cooking a target should fail, _c_o_o_k will exit.  This is the
                default.

        --EErrrrookk
                When a command is executed, the exit code will be ignored.

        --NNoo__EErrrrookk
                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.

        --FFiinnggeerrPPrriinntt
                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.

        --NNoo__FFiinnggeerrPPrriinntt
                Do not use fingerprints to supplement the last-modified time
                file information.  This is the default.

        --FFiinnggeerrPPrriinntt__UUppddaattee
                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.

        --FFoorrccee
                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.

        --NNoo__FFoorrccee
                Perform the actions of the recipes if any of the ingredients
                are logically out of date.  This is the default.

        --HHeellpp
                Provide information about how to execute _c_o_o_k on _s_t_d_o_u_t, and
                perform no other function.

        --IInncclluuddee _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.

        --IInncclluuddee__CCooookkeedd
                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.

        --NNoo__IInncclluuddee__CCooookkeedd
                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.

        --IInncclluuddee__CCooookkeedd__WWaarrnniinngg
                This option enables the warnings about derived dependencies in
                derived cookbooks.  This is usually the default.

        --NNoo__IInncclluuddee__CCooookkeedd__WWaarrnniinngg
                This option disables the warnings about derived dependencies
                in derived cookbooks.

        --LLiisstt
                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.

        --LLiisstt _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.

        --NNoo__LLiisstt
                No automatic redirection of the output of the session will be
                made.



Reference Manual               Cook                            37





COOK(1)                                                   COOK(1)


        --NNoo__LLiisstt _f_i_l_e_n_a_m_e
                No automatic redirection of the output of the session will be
                made, however subsequent --LLiisstt options will default to listing
                to the named file.

        --MMeetteerr
                After each command is executed, print a summary of the
                command's CPU usage.

        --NNoo__MMeetteerr
                Do not print a CPU usage summary after each command.  This is
                the default.

        --PPaaiirrss
                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.

        --PPAARRaalllleell [ _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.

        --NNoo__PPAARRaalllleell
                This option may be used to specify that a single execution
                thread is to be used.  This is the default.

        --PPrreecciioouuss
                When commands in the body of a recipe fail, do not delete the
                targets of the recipe.

        --NNoo__PPrreecciioouuss
                When commands in the body of a recipe fail, delete the targets
                of the recipe.  This is the default.

        --RReeaassoonn
                Two options are provided for tracing the inferences ccooookk makes
                when attempting to cook a target.  The --RReeaassoonn 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 ccooookk is acting strangely, or are just
                curious.

        --NNoo__RReeaassoonn
                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.

        --SSCCrriipptt
                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.

        --SSiilleenntt
                Do not echo commands before they are executed.

        --NNoo__SSiilleenntt
                Echo commands before they are executed.  This is the default.

        --SSTTaarr
                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.

        --NNoo__SSTTaarr
                Do not emit progress indicators.  This is the default.

        --SSttrriipp__DDoott
                Remove leading "./" from filenames before attempting to cook
                them; applies to all filenames and all recipes.  This is the
                default.

        --NNoo__SSttrriipp__DDoott
                Leave leading "./" on filenames while cooking.

        --TToouucchh
                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.

        --NNoo__TToouucchh
                Execute the actions bound to recipes, rather than update the
                last-modified times of the target files.  This is the default.

        --TTEErrmmiinnaall
                When listing, also send the output stream to the terminal.
                This is the default.





Reference Manual               Cook                            39





COOK(1)                                                   COOK(1)


        --NNoo__TTEErrmmiinnaall
                When listing, do not send the output to the terminal.

        --TTiimmee__AAddjjuusstt
                This option causes ccooookk 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.

        --NNoo__TTiimmee__AAddjjuusstt
                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.

        --WWeebb
                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 --HHeellpp 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.

EEXXIITT SSTTAATTUUSS
        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.

FFIILLEESS
        The following files are used by ccooookk:

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

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
        The following environment variables are used by ccooookk:

        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 --HHeellpp and --VVEERRSSiioonn 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.

CCOOPPYYRRIIGGHHTT
        _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.

AAUUTTHHOORR
        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)


NNAAMMEE
       cook_bom - bill of materials

SSYYNNOOPPSSIISS
       ccooookk__bboomm [ _o_p_t_i_o_n...  ] _d_i_r_n_a_m_e [ _o_u_t_f_i_l_e ]
       ccooookk__bboomm --HHeellpp
       ccooookk__bboomm --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
       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.

OOPPTTIIOONNSS
       The following options are understood:

       --DDIIRReeccttoorryy _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.

       --HHeellpp
               Provide some help with using the _c_o_o_k___b_o_m program.

       --IIGGnnoorree _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.

       --PPRREEffiixx _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.

       --SSUUFFffiixx _s_t_r_i_n_g
               This option may be manipulate the name of the manifest files.
               Defaults to ``/manifest.cook if not set.

       --VVEERRSSiioonn
               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 --HHeellpp 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.

EEXXIITT SSTTAATTUUSS
       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.

EEXXAAMMPPLLEE
       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.

CCOOPPYYRRIIGGHHTT
       _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.

AAUUTTHHOORR
       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)


NNAAMMEE
        cook - load balancing rsh

SSYYNNOOPPSSIISS
        ccooookk [ _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...  ]
        ccooookk --HHeellpp

DDEESSCCRRIIPPTTIIOONN
        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.

CCOOOOKKBBOOOOKKSS
        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.

DDEEFFIINNIINNGG TTHHEE CCLLAASSSSEESS
        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.

SSYYSSLLOOGG LLOOGGGGIINNGG
        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.

OOPPTTIIOONNSS
        This command is not usually given any options.

        --hh      Help - show usage info

        --vvPP     Verbose - report choice

        --TT_n     Trace value for testing

FFIILLEESS
        /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.

AAUUTTHHOORR
        Jerry Pendergraft <jerry@endocardial.com>


















































Reference Manual               Cook                            55





cookfp(1)                                               cookfp(1)


NNAAMMEE
       cookfp - calculate file fingerprint

SSYYNNOOPPSSIISS
       ccooookkffpp [ _o_p_t_i_o_n...  ][ _f_i_l_e_n_a_m_e...  ]
       ccooookkffpp --HHeellpp
       ccooookkffpp --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
       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.

OOPPTTIIOONNSS
       The following options are understood:

       --CChheecckkssuumm
               Print the CRC32 checksum and length of the named file(s).

       --IIddeennttiiffiieerr
               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.

       --HHeellpp
               Provide some help with using the _c_o_o_k_f_p program.

       --MMeessssaaggee__DDiiggeesstt
               Print the RSA Data Security, Inc. MD5 Message-Digest Algorithm
               hash of the named file(s).

       --SSnneeffrruu Print the Snefru hash of the named file(s), derived from the
               Xerox Secure Hash Function.

       --VVEERRSSiioonn
               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 --HHeellpp 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.

EEXXIITT SSTTAATTUUSS
       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.

CCOOPPYYRRIIGGHHTT
       _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)


AAUUTTHHOORR
       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)


NNAAMMEE
        cooktime - set file times

SSYYNNOOPPSSIISS
        ccooookkttiimmee [ _o_p_t_i_o_n...  ] _f_i_l_e_n_a_m_e...
        ccooookkttiimmee --HHeellpp
        ccooookkttiimmee --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        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.

OOPPTTIIOONNSS
        The following options are understood.

        --AAcccceessss _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.

        --MMooddiiffyy _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.

        --RReeppoorrtt
                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.

        --HHeellpp
                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 --HHeellpp 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.

EEXXIITT SSTTAATTUUSS
        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.

CCOOPPYYRRIIGGHHTT
        _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.

AAUUTTHHOORR
        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)


NNAAMMEE
        find_libs - find pathnames of libraries

SSYYNNOOPPSSIISS
        ffiinndd__lliibbss [ --LL_p_a_t_h ...  ][ --ll_n_a_m_e ...  ]
        ffiinndd__lliibbss --HHeellpp
        ffiinndd__lliibbss --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        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.

OOPPTTIIOONNSS
        The following options are understood.

        --LL_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.

        --ll_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.

        --HHeellpp
                Give some information on how to use the _f_i_n_d___l_i_b_s command.

        --VVEERRSSiioonn
                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 --HHeellpp 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)


EEXXIITT SSTTAATTUUSS
        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.

CCOOPPYYRRIIGGHHTT
        _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.

AAUUTTHHOORR
        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)


NNAAMMEE
        make2cook - translate makefiles into cookbooks

SSYYNNOOPPSSIISS
        mmaakkee22ccooookk [ _o_p_t_i_o_n...  ][ _i_n_f_i_l_e [ _o_u_t_f_i_l_e ]]
        mmaakkee22ccooookk --HHeellpp
        mmaakkee22ccooookk --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        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.

SSEEMMAANNTTIICCSS
        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.

   UUnnddeerrssttoooodd
        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.

        FFoorr bbeesstt rreessuullttss 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.

   NNoott UUnnddeerrssttoooodd
        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.

OOPPTTIIOONNSS
        The following options are understood:

        --HHeellpp
                Provide some help with using the _m_a_k_e_2_c_o_o_k command.

        --EEnnvviirroonnmmeenntt
                This option causes fragments to test for environment variables
                when performing the default settings for variables.  (This
                corresponds to the make -e option.)

        --HHiissttoorryy__CCoommmmaannddss
                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)


        --LLiinnee__NNuummbbeerrss
                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.

        --NNoo__IInntteerrnnaall__RRuulleess
                This option may be used to supress all generation of recipes
                corresponding to make's internal rules.  (This corresponds to
                the make -r option.)

        --VVEERRSSiioonn
                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 --HHeellpp 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.

EEXXIITT SSTTAATTUUSS
        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.

CCOOPPYYRRIIGGHHTT
        _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.

AAUUTTHHOORR
        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)


NNAAMMEE
        roffpp - replace .so requests within *roff sources

SSYYNNOOPPSSIISS
        rrooffffpppp [ _o_p_t_i_o_n...  ][ _i_n_f_i_l_e [ _o_u_t_f_i_l_e ]]
        rrooffffpppp --HHeellpp
        rrooffffpppp --VVEERRSSiioonn

DDEESSCCRRIIPPTTIIOONN
        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
                ..ssoo _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 ..llff directive.  The ..llff 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.

OOPPTTIIOONNSS
        The following options are understood.

        --II_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.

        --HHeellpp
                Give information on how to use _r_o_f_f_p_p.

        --VVEERRSSiioonn
                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 --HHeellpp 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.

EEXXIITT SSTTAATTUUSS
        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.

CCOOPPYYRRIIGGHHTT
        _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.

AAUUTTHHOORR
        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 -   cookbooks
                     translate 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   fingerprint
                                    file
c_incl(1)      29                     c_   incl - determine
                                           dependencies
make2cook(1)   63            make2cook -   into cookbooks
                     translate 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





Reference Manual               Cook                            iv





Permuted Index(Cook)                         Permuted Index(Cook)


make2cook(1)   63            make2cook -   makefiles into
                               translate   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
roffpp(1)      67   roffpp - replace .so   roff sources
                       requests within *
cook_rsh(1)    53        cook_rsh - load   rsh
                               balancing
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


