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

	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.

	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.19.rm.ps.gz and cook.2.19.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.19.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!

   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$

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