


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.

        GNU Groff patch
                There is a patch for GNU Groff available, which
                gives _g_r_o_f_f(1) and _g_s_o_e_l_i_m(1) a --BB_p_a_t_h option.
                This adds an include file search path, similar to
                _c_p_p(1).  The Makefile assumes this is available.
                The patch is at



Reference Manual               Cook                             1





Build(Cook)                                           Build(Cook)


                http://www.canb.auug.org.au/~millerp/groff-1.11.patch
                or its mirrors.

        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.

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



Reference Manual               Cook                             2





Build(Cook)                                           Build(Cook)


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

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





Reference Manual               Cook                             3





Build(Cook)                                           Build(Cook)


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



Reference Manual               Cook                             4





Build(Cook)                                           Build(Cook)


        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.

        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



Reference Manual               Cook                             5





Build(Cook)                                           Build(Cook)


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

        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



Reference Manual               Cook                             6





Build(Cook)                                           Build(Cook)


        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_._1_6_._r_m_._p_s_._g_z and _c_o_o_k_._2_._1_6_._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                             7





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



Reference Manual               Cook                             8





Build(Cook)                                           Build(Cook)


        _i_t_s _W_i_n_d_o_w_s_-_N_T _n_a_m_e _s_t_a_r_t_s _w_i_t_h _\_\_.

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



Reference Manual               Cook                             9





Build(Cook)                                           Build(Cook)


                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
                _._._._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.16
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994,
        1995, 1996, 1997, 1998, 1999, 2000 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                            10


