Build(Cook)                                                        Build(Cook)



[1mNAME[0m
        cook - a file construction tool

[1mSPACE REQUIREMENTS[0m
        You will need about 5MB to unpack and build the [4mCook[24m package.  Your
        milage may vary.

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

        GNU Gettext
                The [4mCook[24m 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 [4mbefore[24m 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 [4m--with-gnu-gettext[0m
                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 [4mCook[24m 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 [4myacc[24m(1) you
                will need to fetch and install GNU Bison in order to build the
                [4mCook[24m 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.

[1mSITE CONFIGURATION[0m
        The [1mCook [22mpackage is configured using the [4mconfigure[24m program included in
        this distribution.

        The [4mconfigure[24m shell script attempts to guess correct values for
        various system-dependent variables used during compilation, and
        creates the [4mMakefile[24m and [4mcommon/config.h[24m files.  It also creates a
        shell script [4mconfig.status[24m that you can run in the future to recreate
        the current configuration.

        Normally, you just [4mcd[24m to the directory containing [4mCook[24m's source code
        and type
                [1m% [22m./configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        If you're using [4mcsh[24m on an old version of System V, you might need to
        type
                [1m% [22msh configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        instead to prevent [4mcsh[24m from trying to execute [4mconfigure[24m itself.

        Running [4mconfigure[24m 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 [4mconfigure[24m using the quiet option; for example,
                [1m% [22m./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 [1mCook [22mpackage in a different directory from the one
        containing the source code, you must use a version of [4mmake[24m that
        supports the [4mVPATH[24m [4mvariable,[24m such as [4mGNU[24m [4mmake[24m.  [4mcd[24m to the directory
        where you want the object files and executables to go and run the
        [4mconfigure[24m script.  [4mconfigure[24m automatically checks for the source code
        in the directory that [4mconfigure[24m is in and in [4m..[24m  (the parent
        directory).  If for some reason [4mconfigure[24m 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 [4mconfigure[24m with the option
        --srcdir=[4mDIR[24m, where [4mDIR[24m is the directory that contains the source
        code.

        By default, [4mconfigure[24m will arrange for the [4mmake[24m [4minstall[24m command to
        install the [1mCook [22mpackage's files in [4m/usr/local/bin[24m, [4m/usr/local/lib[24m,
        [4m/usr/local/share[24m and [4m/usr/local/man[24m.  There are a number of options
        which allow you to control the placement of these files.

        --prefix=[4mPATH[0m
                This specifies the path prefix to be used in the installation.
                Defaults to [4m/usr/local[24m unless otherwise specified.

        --exec-prefix=[4mPATH[0m
                You can specify separate installation prefixes for
                architecture-specific files files.  Defaults to [4m${prefix}[0m
                unless otherwise specified.

        --bindir=[4mPATH[0m
                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 [4m${exec_prefix}/bin[24m unless otherwise specified.

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

        --libdir=[4mPATH[0m
                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
                [4m${exec_prefix}/lib/cook[24m unless otherwise specified.  A
                ``cook'' directory will be appended if there is none in the
                specified path.

        --mandir=[4mPATH[0m
                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 [4m${prefix}/man[24m unless
                otherwise specified.

        [4mconfigure[24m 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 [4mCook[24m package's [4mconfigure[24m script does not know about, you can
        give [4mconfigure[24m initial values for variables by setting them in the
        environment.  In Bourne-compatible shells, you can do that on the
        command line like this:
                [1m$ [22mCC='gcc -traditional' LIBS=-lposix ./configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m$[0m
        Here are the [4mmake[24m variables that you might want to override with
        environment variables when running [4mconfigure[24m.

        Variable: CC
                C compiler program.  The default is [4mcc[24m.

        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 [4minstall[24m if
                you have it, [4mcp[24m otherwise.

        Variable: LIBS
                Libraries to link with, in the form -l[4mfoo[24m -l[4mbar[24m.  The
                [4mconfigure[24m 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 [4mconfigure[24m could check whether to do
        them, and mail diffs or instructions to the author so that they can be
        included in the next release.

[1mBUILDING COOK[0m
        All you should need to do is use the
                [1m% [22mmake
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command and wait.  When this finishes you should see a directory
        called [4mbin[24m containing nine files: [4mc_incl[24m, [4mcook[24m, [4mcookfp[24m, [4mcooktime[24m,
        [4mfind_libs[24m, [4mmake2cook[24m and [4mroffpp[24m.

        [1mcook    [4m[22mcook[24m program is a file construction tool, and may invoke the
                following tools in some of its recipes.

        [1mcookfp  [22mThe [4mcookfp[24m program is a utility distributed with [4mCook[24m which
                calculates the fingerprints of files.  It uses the same
                algorithm as the fingerprints used by [4mcook[24m itself.  For more
                information, see [4mcook[24m(1) and [4mcookfp[24m(1).

        [1mcooktime[0m
                The [4mcooktime[24m program is a utility distributed with [4mCook[24m which
                allows the time-last-modified and time-last-accessed stamps of
                files to be set to specific times.  For more information, see
                [4mcooktime[24m(1).

        [1mc_incl  [22mThe [4mc_incl[24m program is a utility distributed with [4mCook[24m which
                examines C files and determines all the files it includes
                directly and indirectly.  For more information, see [4mc_incl[24m(1).

        [1mfind_libs[0m
                The [4mfind_libs[24m program is a utility distributed with [4mCook[24m which
                tracks down the names of library files, given cc-style library
                options (-L and -l).  For more information, see [4mfind_libs[24m(1).

        [1mmake2cook[0m
                The [4mmake2cook[24m 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.

        [1mroffpp  [22mThe [4mroffpp[24m program is a utility distributed with [4mCook[24m which
                acts as a proprocessor for *roff files, removing source (.so)
                directives.  It accepts include search path command line
                options just as [4m/lib/cpp[24m does.  For more information, see
                [4mroffpp[24m(1).

        You can remove the program binaries and object files from the source
        directory by using the
                [1m% [22mmake clean
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command.  To remove all of the above files, and also remove the
        [4mMakefile[24m and [4mcommon/config.h[24m and [4mconfig.status[24m files, use the
                [1m% [22mmake distclean
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command.

        The file [4metc/configure.in[24m is used to create [4mconfigure[24m by a GNU program
        called [4mautoconf[24m.  You only need to know this if you want to regenerate
        [4mconfigure[24m using a newer version of [4mautoconf[24m.

[1mTESTING COOK[0m
        The [4mCook[24m program comes with a test suite.  To run this test suite, use
        the command
                [1m% [22mmake sure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mPassed All Tests[0m
                [1m%[0m

        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.

   [1mKnown Problems[0m
        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
                [1m% [22msetenv COOK_TMP /usr/tmp
                [1m%[0m
        is usually sufficient if you are using C shell, or
                [1m$ [22mCOOK_TMP=/usr/tmp
                [1m$ [22mexport COOK_TMP
                [1m$[0m
        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.

[1mINSTALLING COOK[0m
        As explained in the [4mSITE[24m [4mCONFIGURATION[24m section, above, the [4mCook[0m
        package is installed under the [4m/usr/local[24m tree by default.  Use the
        --prefix=[4mPATH[24m option to [4mconfigure[24m if you want some other path.  More
        specific installation locations are assignable, use the --help option
        to [4mconfigure[24m for details.

        All that is required to install the [4mCook[24m package is to use the
                [1m% [22mmake install
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        command.  Control of the directories used may be found in the first
        few lines of the [4mMakefile[24m file and the other files written by the
        [4mconfigure[24m script; it is best to reconfigure using the [4mconfigure[0m
        script, rather than attempting to do this by hand.

[1mPRINTED MANUALS[0m
        The easiest way to get copies of the manuals is to get the
        [4mcook.2.21.rm.ps.gz[24m and [4mcook.2.21.ug.ps.gz[24m 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
        [4mCook[24m.  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 [4mbefore[24m you run the
        [4mconfigure[24m script, the [4mMakefile[24m will contain instructions for
        constructing the documentation.  If you alreday used the [4mmake[24m command,
        above, this has already been done.  The following command
                [1m% [22mmake groff_all
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1m%[0m
        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
                [1m% [22mlpr lib/en/refman.ps lib/en/user-guide.ps
                [1m%[0m
        will print the English PostScript version of the Reference Manual and
        the User Guide.  Watch the [4mmake[24m output to see what other versions are
        available.

[1mGETTING HELP[0m
        If you need assistance with the [4mCook[24m 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
                [1m% [22mcook -version
                [1mcook version [4m[22m2.21.D001[0m
                [4m...warranty[24m [4mdisclaimer...[0m
                [1m%[0m
        command.  Please do not send this example; run the program for the
        exact version number.

        In the [4mcommon/main.h[24m file, there is a define of [4mDEBUG[24m 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 [1m-TRACIng [22mcommand line option.

        When the [1m-TRACing [22moption 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.

[1mWINDOWS-NT[0m
        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.

   [1mThe Source[0m
        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.

   [1mMounting Things[0m
        You need to mount a directory onto /tmp, or lots of things, and
        especially [4mbash[24m(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 ([4me.g.[24m C:[4m)[24m [4mrather[24m [4mthan[24m [4mwith[24m [4ma[24m [4mdouble[24m [4mslash[24m [4m(e.g.[0m
        [4mnot[24m //C[4m)[24m [4munless[24m [4mits[24m [4mWindows-NT[24m [4mname[24m [4mstarts[24m [4mwith[24m [4m\\.[0m

        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 ([4me.g.[0m
        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!

   [1mBefore your start[0m
        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
                [4mtsort[24m command, so that GNU rx's [4m./configure[24m 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 [4mmisc-utils/tsort.c[24m by hand.

        GNU rx  Once you have [4mtsort[24m installed, you will be able to get GNU rx
                configured.  Get a copy from your local GNU mirror.

   [1mConfigure[0m
        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.
                [1mbash$ [22m./configure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mbash$[0m

   [1mBuild[0m
        The build step is exactly the same as for UNIX, and you shouldn't
        notice any difference...
                [1mbash$ [22mmake
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mbash$[0m

   [1mTest[0m
        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!)
                [1mbash$ [22mmake sure
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mPassed All Tests[0m
                [1mbash$[0m

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

   [1mInstall[0m
        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 ``[4m/usr/local[24m'' prefix (or any
        other install prefix) you mount it right at the start.  For anything
        other than the ``[4m/usr/local[24m'' default prefix, you also needed to give
        a ``[1m--prefix=[4m[22mblahblah''[24m [4margument[24m [4mto[24m [4mthe[24m [4mconfigure[24m [4mscript,[24m [4mright[24m [4mat[24m [4mthe[0m
        [4mstart.[0m
                [1mbash$ [4m[22mmake[24m [4minstall[0m
                [4m...lots[24m [4mof[24m [4moutput...[0m
                [1mbash$[0m

[1mCOPYRIGHT[0m
        [4mcook[24m 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 [4mCook[24m 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 [4mLICENSE[24m file included with this distribution.

[1mAUTHOR[0m
        Peter Miller   E-Mail:   millerp@canb.auug.org.au
        /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/



Reference Manual                     Cook                          Build(Cook)
