


Build(Cook)                                           Build(Cook)


NNAAMMEE
        cook - a file construction tool

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

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

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

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

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

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

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

        GCC     You may also want to consider fetching and installing the GNU
                C Compiler if you have not done so already.  This is not
                essential.

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






Reference Manual               Cook                             1





Build(Cook)                                           Build(Cook)


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

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

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

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

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

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

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

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



Reference Manual               Cook                             2





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                             3





Build(Cook)                                           Build(Cook)


                CFLAGS=-I/usr/local/include to access other installed
                packages.

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

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

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

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

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

        ccooookkffpp  The _c_o_o_k_f_p program is a utility distributed with _C_o_o_k which
                calculates the fingerprints of files.  It uses the same
                algorithm as the fingerprints used by _c_o_o_k itself.  For more
                information, see _c_o_o_k(1) and _c_o_o_k_f_p(1).

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

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

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

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



Reference Manual               Cook                             4





Build(Cook)                                           Build(Cook)


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

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

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

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

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

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

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

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



Reference Manual               Cook                             5





Build(Cook)                                           Build(Cook)


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

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

        All that is required to install the _C_o_o_k package is to use the
                %% make install
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %%
        command.  Control of the directories used may be found in the first
        few lines of the _M_a_k_e_f_i_l_e file and the other files written by the
        _c_o_n_f_i_g_u_r_e script; it is best to reconfigure using the _c_o_n_f_i_g_u_r_e
        script, rather than attempting to do this by hand.

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

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

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

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





Reference Manual               Cook                             6





Build(Cook)                                           Build(Cook)


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

        When reporting problems, please include the version number given by
        the
                %% cook -version
                ccooookk vveerrssiioonn _2_._2_1_._D_0_0_1
                _._._._w_a_r_r_a_n_t_y _d_i_s_c_l_a_i_m_e_r_._._.
                %%
        command.  Please do not send this example; run the program for the
        exact version number.

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

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

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

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

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

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

        You need to mount the Cygnus bin directory at /bin, otherwise shell
        scripts that start with #!/bin/sh don't work, among other things.
        This includes the ./configure script, and the scripts it writes (_e_._g_.
        config.status).



Reference Manual               Cook                             7





Build(Cook)                                           Build(Cook)


                mount Cygnus-Dir/H-i386-cygwin/bin /bin
        You will want to mount your various network drives onto the same
        places they appear on your UNIX hosts.  This means that your cookbooks
        will work without change, even if they contain absolute paths.  And
        your users don't need to learn two names for all the source files.

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

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

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

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

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

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

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

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

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

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



Reference Manual               Cook                             8





Build(Cook)                                           Build(Cook)


                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                PPaasssseedd AAllll TTeessttss
                bbaasshh$$

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

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

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

        The _C_o_o_k package is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
        General Public License for more details.

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

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
























Reference Manual               Cook                             9


