


Build(Cook)                                           Build(Cook)


NAME
        cook - a file construction tool

SPACE REQUIREMENTS
        You will need about 5MB to unpack and build the Cook
        package.  Your milage may vary.

BEFORE YOU START
        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
        /usr/local (for example) you must ensure that the
        ./configure script is told to also look in
        /usr/local/include for include files (CFLAGS), and
        /usr/local/lib for library files (LDFLAGS).  Otherwise
        the ./configure script will incorrecly conclude that they
        have not been installed.

        GNU Gettext
                The Cook 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 before 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 --with-
                gnu-gettext 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 Cook 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
                yacc(1) you will need to fetch and install GNU
                Bison in order to build the Cook package.

        GCC     You may also want to consider fetching and



Reference Manual               Cook                             1





Build(Cook)                                           Build(Cook)


                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.

SITE CONFIGURATION
        The Cook package is configured using the configure
        program included in this distribution.

        The configure shell script attempts to guess correct
        values for various system-dependent variables used during
        compilation, and creates the Makefile and common/config.h
        files.  It also creates a shell script config.status that
        you can run in the future to recreate the current
        configuration.

        Normally, you just cd to the directory containing Cook's
        source code and type
                %% ./configure
                ...lots of output...
                %%
        If you're using csh on an old version of System V, you
        might need to type
                %% sh configure
                ...lots of output...
                %%
        instead to prevent csh from trying to execute configure
        itself.

        Running configure 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
        configure 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 Cook package in a different directory from
        the one containing the source code, you must use a
        version of make that supports the VPATH variable, such as
        GNU make.  cd to the directory where you want the object
        files and executables to go and run the configure script.
        configure automatically checks for the source code in the
        directory that configure is in and in ..  (the parent
        directory).  If for some reason configure 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 configure with the option --srcdir=DIR, where



Reference Manual               Cook                             2





Build(Cook)                                           Build(Cook)


        DIR is the directory that contains the source code.

        By default, configure will arrange for the make install
        command to install the Cook package's files in
        /usr/local/bin, /usr/local/lib, /usr/local/share and
        /usr/local/man.  There are a number of options which
        allow you to control the placement of these files.

        --prefix=PATH
                This specifies the path prefix to be used in the
                installation.  Defaults to /usr/local unless
                otherwise specified.

        --exec-prefix=PATH
                You can specify separate installation prefixes
                for architecture-specific files files.  Defaults
                to ${prefix} unless otherwise specified.

        --bindir=PATH
                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 ${exec__prefix}/bin unless otherwise specified.

        --datadir=PATH
                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 ${prefix}/share/cook unless
                otherwise specified.  A ``cook'' directory will
                be appended if there is none in the specified
                path.

        --libdir=PATH
                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
                ${exec__prefix}/lib/cook unless otherwise
                specified.  A ``cook'' directory will be appended
                if there is none in the specified path.

        --mandir=PATH
                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 ${prefix}/man unless
                otherwise specified.

        configure ignores most other arguments that you give it;
        use the --help option for a complete list.



Reference Manual               Cook                             3





Build(Cook)                                           Build(Cook)


        On systems that require unusual options for compilation
        or linking that the Cook package's configure script does
        not know about, you can give configure 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
                ...lots of output...
                $$
        Here are the make variables that you might want to
        override with environment variables when running
        configure.

        Variable: CC
                C compiler program.  The default is cc.

        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
                install if you have it, cp otherwise.

        Variable: LIBS
                Libraries to link with, in the form -l_f_o_o -l_b_a_r.
                The configure 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 configure
        could check whether to do them, and mail diffs or
        instructions to the author so that they can be included
        in the next release.

BUILDING COOK
        All you should need to do is use the
                %% make
                ...lots of output...
                %%
        command and wait.  When this finishes you should see a
        directory called bin containing nine files: _c__incl, cook,
        cookfp, cooktime, find__libs, make2cook and roffpp.

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

        cookfp  The cookfp program is a utility distributed with
                Cook which calculates the fingerprints of files.



Reference Manual               Cook                             4





Build(Cook)                                           Build(Cook)


                It uses the same algorithm as the fingerprints
                used by cook itself.  For more information, see
                cook(1) and cookfp(1).

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

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

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

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

        roffpp  The roffpp program is a utility distributed with
                Cook which acts as a proprocessor for *roff
                files, removing source (.so) directives.  It
                accepts include search path command line options
                just as /lib/cpp does.  For more information, see
                roffpp(1).

        You can remove the program binaries and object files from
        the source directory by using the
                %% make clean
                ...lots of output...
                %%
        command.  To remove all of the above files, and also
        remove the Makefile and common/config.h and config.status
        files, use the
                %% make distclean
                ...lots of output...
                %%
        command.

        The file etc/configure.in is used to create configure by
        a GNU program called autoconf.  You only need to know
        this if you want to regenerate configure using a newer
        version of autoconf.





Reference Manual               Cook                             5





Build(Cook)                                           Build(Cook)


TESTING COOK
        The Cook program comes with a test suite.  To run this
        test suite, use the command
                %% make sure
                ...lots of output...
                Passed All Tests
                %%

        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.

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

INSTALLING COOK
        As explained in the SITE CONFIGURATION section, above,
        the Cook package is installed under the /usr/local tree
        by default.  Use the --prefix=PATH option to configure if
        you want some other path.  More specific installation
        locations are assignable, use the --help option to
        configure for details.

        All that is required to install the Cook package is to
        use the
                %% make install
                ...lots of output...
                %%
        command.  Control of the directories used may be found in



Reference Manual               Cook                             6





Build(Cook)                                           Build(Cook)


        the first few lines of the Makefile file and the other
        files written by the configure script; it is best to
        reconfigure using the configure script, rather than
        attempting to do this by hand.

PRINTED MANUALS
        The easiest way to get copies of the manuals is to get
        the cook.2.20.rm.ps.gz and cook.2.20.ug.ps.gz 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 Cook.  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 before you
        run the configure script, the Makefile will contain
        instructions for constructing the documentation.  If you
        alreday used the make command, above, this has already
        been done.  The following command
                %% make groff_all
                ...lots of output...
                %%
        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 make
        output to see what other versions are available.

GETTING HELP
        If you need assistance with the Cook 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
                cook version 2.20.D001



Reference Manual               Cook                             7





Build(Cook)                                           Build(Cook)


                ...warranty disclaimer...
                %%
        command.  Please do not send this example; run the
        program for the exact version number.

        In the common/main.h file, there is a define of DEBUG 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
        -TRACIng command line option.

        When the -TRACing 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.

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

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

   Mounting Things
        You need to mount a directory onto /tmp, or lots of
        things, and especially bash(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:_) rather than with _a double slash (e.g. not //C_) unless
        its Windows-NT name starts with \\.

        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



Reference Manual               Cook                             8





Build(Cook)                                           Build(Cook)


        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!

   Before your start
        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 tsort command, so that GNU rx's
                ./configure 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 misc-utils/tsort.c by
                hand.

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

   Configure
        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.
                bash$ ./configure
                ...lots of output...
                bash$

   Build
        The build step is exactly the same as for UNIX, and you
        shouldn't notice any difference...
                bash$ make
                ...lots of output...
                bash$





Reference Manual               Cook                             9





Build(Cook)                                           Build(Cook)


   Test
        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!)
                bash$ make sure
                ...lots of output...
                Passed All Tests
                bash$

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

   Install
        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 ``/usr/local'' prefix (or any other install prefix)
        you mount it right at the start.  For anything other than
        the ``/usr/local'' default prefix, you also needed to
        give a `--prefix=blahblah'' argument to the configure
        script, right at the start.
                bash$ make install
                ...lots of output...
                bash$

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

        The Cook 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 LICENSE file included with this
        distribution.

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














Reference Manual               Cook                            10


