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.29.rm.ps.gz and cook.2.29.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.29.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.29
	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)
