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
        mileage 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 incorrectly conclude that they have not been installed.

        ANSI C compiler
                You will need an ANSI C compiler to be able to compile cook.
                If you don't have one, you may wish to consider installing the
                GNU C compiler, it's free.

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

                On Solaris, you may need to edit the Makefile to change the
                groff -man and -mm options to -mgan and -mgm instead.

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

        --with-nlsdir=PATH
                This directory contains the install 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 --libdir unless otherwise
                specified.

        configure 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 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 -lfoo -lbar.  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.

        Variable: NLSDIR
                Similar to the --with-nlsdir option.

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

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 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.33.rm.ps.gz and cook.2.33.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 already 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 <pmiller@opensource.org.au>
        Any and all feedback is welcome.

        When reporting problems, please include the version number given by
        the
                % cook -version
                cook version 2.33.D001
                ...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 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!

   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 through 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$

   Test
        All of the tests should pass, you only need to run them to convince
        yourself the build worked...  (a constant surprise 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.33
        Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
        1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
        2008, 2009 Peter Miller

        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:   pmiller@opensource.org.au
        /\/\*             WWW:   http://miller.emu.id.au/pmiller/

Reference Manual                     Cook                          Build(Cook)
