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. 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 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. 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 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. 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.28.rm.ps.gz and cook.2.28.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 Any and all feedback is welcome. When reporting problems, please include the version number given by the % cook -version cook version 2.28.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 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$ 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.28 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 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 Build(Cook)