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.

		On Solaris, you	may need to edit the [4mMakefile[24m to change	the
		groff -man and -mm options to -mgan and	-mgm instead.

	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.24.rm.ps.gz[24m and [4mcook.2.24.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.24.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.24
	Copyright (C) 1988, 1989, 1990,	1991, 1992, 1993, 1994,	1995, 1996,
	1997, 1998, 1999, 2000,	2001, 2002, 2003 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)
