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.




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.

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

        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.

        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.

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).
                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
                _._._._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                   Build(Cook)
