Build(Aegis)					     Build(Aegis)

NAME
	aegis -	project	change supervisor
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,
	1998, 1999, 2000, 2001 Peter Miller; All rights	reserved.

	The aegis program is distributed under the terms of the
	GNU General Public License.  See the LICENSE section,
	below, for more	details.

	aegis (ee.j.iz)	n., a protection, a defence.

SPACE REQUIREMENTS
	You will need up to 15MB to unpack and build the aegis
	program.  (This	is the worst case seen so far, most
	systems	have binaries about 60%	as big as this,	10MB is
	more typical.)	Your mileage may vary.

SITE CONFIGURATION
	The aegis package is configured	using the configure shell
	script 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.

   Before You Start
	Before you start configuring, it is worth reading the
	OTHER USEFUL SOFTWARE section, below.

	The configure script checks for	the internationalization
	library	and functions.	If your	system does not	have
	them, it is worth fetching and installing GNU Gettext
	before you run the configure script.  Make sure	that the
	msgfmt command from GNU	Gettext	appears	earlier	in your
	command	search PATH than the existing system ones, if any
	(this is very important	for SunOS and Solaris).	 You must
	do the GNU gettext install before running the configure
	script,	or the error messages, even for	English	speakers,
	will be	terse and uninformative.  Remember to use the GNU
	gettext	configure --with-gnu-gettext option if your
	system has native gettext tools.

	The configure script checks for	the compression	library
	and functions.	If your	system does not	have them, it is
	worth fetching and installing GNU zlib compression
	library	before you run the configure script.  (See
	http://www.cdrom.com/pub/infozip/zlib/ for download.)
	This is	essential, becaise Aegis will not build.  without
	it.  (Note: this is not	the same thing as zlibc	which
	does something completely different.)

	The configure script checks for	the regular expression
	library	and functions.	If your	system does not	have
	them, it is worth fetching and installing GNU rx
	compression library before you run the configure script.
	(Note: test 81 will fail if the	POSIX regular expression
	functions are not available.)

   Running Configure
	Normally, you just cd to the directory containing aegis'
	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 with its standard output redirected to
	/dev/null; 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	32 fails (see below) this is probably the reason.

	By default, configure will arrange for the make	install
	command	to install the aegis package's files in
	/usr/local/bin,	/usr/local/com/aegis,
	/usr/local/lib/aegis, /usr/local/man and
	/usr/local/share/aegis.	 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	and architecture-
		independent 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, reports and shell scripts
		distributed with Aegis.	 On a network, this
		directory may be shared	between	all machines; it
		may be mounted read-only.  Defaults to
		${prefix}/share/aegis unless otherwise specified.
		An ``aegis'' 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/aegis unless	otherwise
		specified.  An ``aegis'' 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.

	--sharedstatedir=PATH
		This directory contains	share state information,
		such as	the Aegis lock file, and information on
		the location of	the various Aegis projects.  On	a
		network, this directory	may be shared between all
		machines; it MUST be mounted READ-WRITE.
		Defaults to ${prefix}/com/aegis	unless otherwise
		specified.  An ``aegis'' directory will	be
		appended if there is none in the specified path.

	configure ignores any other arguments that you give it.

	On systems that	require	unusual	options	for compilation
	or linking that	the aegis 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: 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.

	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.

   Common Problem
	It is very common that other packages, such as gettext,
	rx and zlib are	installed using	/usr/local as the prefix.
	However, the configure script can't work this out, even
	when it, too, is using /usr/local as the prefix.

	To cope	with this, you need to say
		$ CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib ./configure
		...lots	of output...
		$
	when running configure.	 Substitute the	appropriate
	prefix if you are using	something other	than /usr/local.
	Watch the output... it should now find your installed
	packages correctly.

   PRIVILEGES
	There are a number of items in the generated Makefile and
	common/config.h	file which affect the way aegis	works.
	If they	are altered too	far, aegis will	not be able to
	function correctly.

	AEGIS_MIN_UID
		This specifies the minimum unprivileged	uid on
		your system.  UIDs less	than this may not own
		projects, or play any other role in an aegis
		project.  The default value is 100.

	AEGIS_MIN_GID
		This specifies the minimum unprivileged	GID on
		your system.  GIDs less	than this may not own
		projects, or play any other role in an aegis
		project.  The default value is 10.

	AEGIS_USER_UID
		This is	the owner of files used	by aegis to
		record pointers	to your	projects.  It is not used
		to own projects	(i.e. it must be less than
		AEGIS_MIN_UID).	 If possible, the configure
		script tries to	work out what value was	used
		previously, but	you must specify the --prefix
		option correctly for this to work.  Because of
		operating system inconsistencies, this is
		specified numerically so that aegis will work
		across NFS.  The default value is 3.

	AEGIS_USER_GID
		This is	the group of files used	by aegis to
		record pointers	to your	projects.  It is not used
		as the group for projects (i.e.	it must	be less
		than AEGIS_MIN_GID).  If possible, the configure
		script tries to	work out what value was	used
		previously, but	you must specify the --prefix
		option correctly for this to work.  Because of
		operating system inconsistencies, this is
		specified numerically so that aegis will work
		across NFS.  The default value is 3.

	DEFAULT_UMASK
		When aegis runs	commands for you, or creates
		files or directories for you, it will use the
		defined	project	umask.	This is	a project
		attribute, and may be altered using the	aepa(1)
		command.  The DEFAULT_UMASK is the umask
		initially given	to all new projects created by
		the aenpr(1) command.  The default value of
		DEFAULT_UMASK is 026.  See the comments	in the
		common/config.h	file for an explanation	of the
		alternatives.

	It is required that aegis run set-uid-root for all of its
	functionality to be available.	It is NOT possible to
	create an "aegis" account and make aegis run set-uid-
	aegis.	This is	because	aegis does things as various
	different user IDs, sometimes as many as 3 in the one
	command.  This allows aegis to use UNIX	security rather
	than inventing its own,	and also allows	aegis to work
	across NFS.  To	be able	to do these things, aegis must be
	set-uid-root.  Appendix	D of the Aegis User Guide
	explains why aegis must	run set-uid-root; please read it
	if you have concerns.

   Remember Your Settings
	It is important	to remember your configuration settings.
	This way, it will be a simple matter when it comes time
	to upgrade Aegis.

BUILDING AEGIS
	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	several	files: aegis,
	aereport, aefind, aefp,	find_sizes and fmtgen.

	aegis	The aegis program is a project change supervisor.

	aefp	The aefp program may be	used to	``fingerprint''
		files.	It is used to test Aegis (see the testing
		section, below)	but it isn't installed.

	aereport
		The aereport program is	used to	query Aegis'
		database.

	aefind	The aefind program is used to find files.

	find_sizes
		The find_sizes program is a utility used to build
		the aegis package; it is not intended for general
		use and	should not be installed.

	fmtgen	The fmtgen program is a	utility	used to	build the
		aegis package; it is not intended for general use
		and should not be installed.

	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 aux/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.

   Upgrading
	When upgrading from one	release	to a newer one,	it is
	important that all of the machines on your network are
	running	the same release of Aegis.  This minimises the
	possibility of database	incompatibilities.  In general,
	Aegis is backwards compatible with earlier releases, but
	not forwards compatible	in the face of new capabilities.

OTHER USEFUL SOFTWARE
	Before describing how to test aegis, you may need to grab
	some other free	software, because the tests require it in
	some cases, and	because	it is generally	useful in others.

	cook	This is	a dependency maintenance tool (DMT).  An
		example	of a well-known	DMT is make(1),	however
		this old faithful is mostly not	sufficiently
		capable	to meet	the demands placed on it by the
		aegis program, but cook	certainly is.  The cook
		package	is written by the same author as aegis.
		The cook package is necessary if test 11 is to be
		meaningful.  It	is also	used in	the
		documentation.	The cook program may be	found at
		the same archive site as the aegis program.  The
		cook program is	available under	the terms of the
		GNU General Public License.

	GNU diff
		If the diff(1) utility supplied	by your	flavor of
		unix does not have the -c option, you will need
		GNU diff for aepatch(1)	to work	(and the
		aepatch(1) tests to pass).  Context differences
		are also helpful for reviewing changes.	 GNU diff
		is essential for Solaris, because the Solaris
		diff has bugs that Aegis' tests	uncover.

	RCS	This is	a source control package, and is
		available from any of the GNU archives.	 The
		tests use RCS as the history mechanism,	so it is
		necessary to have RCS for most of the tests to
		pass.  (It is best to compile and install RCS
		after GNU diff.	 This is because the RCS
		configuration hard-codes the pathnames of the GNU
		diff utilities it needs	into the RCS
		executables.)

	GNU Gettext
		Many systems do	not yet	supply the gettext(3)
		function.  Aegis uses this function to
		internationalize its error messages.  If your
		system does not	have this function, you	should
		fetch and install GNU Gettext before running the
		configure script.  If you do not, Aegis	will
		still work, but	the error messages will	be rather
		terse, even for	English	speakers.  (You	will be
		able to	tell if	your system has	the
		internationalization library and functions,
		because	the configure script will report finding
		-lintl and (CWlibintl.h	and msgfmt in its running
		commentary.)  Please note that the GNU Gettext
		implementation is likely to be superior	to the
		one supplied with your system, if any.	Remember
		to use the GNU gettext configure --with-gnu-
		gettext	option if your system has native gettext
		tools.

		Please note: if	you install GNU	gettext	package
		into /usr/local	(for example) you must ensure
		that the Aegis ./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 not been installed.

	GNU Groff
		This GNU software replaces the documentation
		tools which (sometimes)	come with UNIX.	 They
		produce	superior error messages, and support a
		wider range of functionality and fonts.	 The
		Aegis User Guide was prepared with GNU Groff.
		You need GNU Groff 1.14	or later.

	bison	This GNU software is a replacement for yacc(1).
		Some systems have very sick yaccs, and bison may
		be necessary if	your system include files
		disagree strongly with your system's yacc.  The
		generated Makefile will	use bison if you have it.

	fhist	This software, available under the terms of the
		GNU General Public License, is a set of	file
		history	and comparison utilities.  It was
		originally written by David I. Bell, and is based
		on the minimal difference algorithm by Eugene W.
		Myers.	This copy is enhanced and maintained by
		the same author	as Aegis, and may be found at the
		same archive site, in the same directory.

	rx	This library provides POSIX regular expressions,
		for systems which don't	have them.  (Note: test
		81 will	fail if	the POSIX regular expression
		functions are not available.)

	zlib	This library provides access to	the GNU	Zip
		(de)compression	algorithm(s).  It is essential to
		have this installed before you build Aegis.  The
		home page may be found at
		http://www.cdrom.com/pub/infozip/zlib/ if you
		need to	download it.  Note: this is not	the same
		as zlibc which is Linux	specific.

	tkdiff	This program shows the difference between two
		text files, nicely highlighted in color.  This is
		used by	the tkaer and aecomp scripts (and
		probably others	as they	are contributed).  By
		John M.	Klassa,	http://www.ede.com/free/tkdiff

	The tests also depend on the presence of a number of
	common UNIX programs, including	but not	limited	to: cc,
	cmp, diff, ed, find, make, the RCS package, etc.
	Depending on your version of UNIX, some	or all of these
	programs may be	in optional packages.  (This is
	especially true	of Linux.)  You	need to	ensure that these
	programs are correctly installed before	you run	the
	tests.

TESTING	AEGIS
	The Aegis 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 minute	or two each, with a few	very
	fast, and a couple very	slow, but it varies greatly
	depending on your CPU.

   Known Problems
	The tests assume that the RCS commands "ci", "co", "rlog"
	and "rcs" are somewhere	in the command search PATH.

	The test/00/t0011a.sh file assumes the cook(1) command by
	the author is somewhere	in the command search path.  This
	test reproduces	the example used in Chapter 3 of the User
	Guide.	If the cook(1) command is not available, this
	test gives a pass result without testing anything.

	If you are using HPUX and GCC, test 32 fails if	you use
	-O2.  You need to edit the Makefile to only optimize at
	-O, delete the objects and rebuild.

	If you are using Solaris' diff,	test 133 will report ``no
	result''.  You need to install GNU diff, because the
	Solaris	diff has bugs.

	If you are using Sun's tmpfs file system as your /tmp
	directory, the tests will fail.	 This is because the
	tmpfs file system does not support file	locking.  Set the
	AEGIS_TMP environment variable to somewhere else before
	running	the tests.  Something like
		% setenv AEGIS_TMP /usr/tmp
		%
	is usually sufficient if you are using C shell,	or
		$ AEGIS_TMP=/usr/tmp
		$ export AEGIS_TMP
		$
	if you are using Bourne	shell.	Remember, this must be
	done before running the	tests.

	If the tests fail due to errors	complaining of "user too
	privileged" you	will need to adjust the	AEGIS_MIN_UID
	defined	in the common/config.h file.  Similarly	for
	"group too privileged",	although this is rarer.	 This
	error message will also	occur if you run the tests as
	root: the tests	must be	run as a mortal	each time.

	If the POSIX regular expression	functions are not
	available, test	81 will	fail.  The GNU rx library
	provides these.	 Installing it and re-configuring and re-
	building Aegis will solve the problem.

TESTING	SET-UID-ROOT
	If the Aegis program is	not set-uid-root then it runs in
	"test" mode which gives	you some confidence that Aegis is
	working	before being tested again when it is set-uid-
	root.  Two pass	testing	like this means	that you need not
	trust your system to a set-uid-root program which is not
	known to work.

	You will need to do a little of	the install, to	create
	the directory which will contain Aegis'	lock file.
		# make install-libdir
		mkdir /usr/local/lib/aegis
		chown 3	/usr/local/lib/aegis
		chgrp 3	/usr/local/lib/aegis
		chmod 0755 /usr/local/lib/aegis
		mkdir /usr/local/com/aegis
		chown 3	/usr/local/com/aegis
		chgrp 3	/usr/local/com/aegis
		chmod 0755 /usr/local/com/aegis
		chown root bin/aegis
		chmod 4755 bin/aegis
		#
	As you can see,	the previous command also changed Aegis
	to be set-uid-root.  Once this has been	done, Aegis
	should be tested again,	in the same manner as before.
		% make sure
		...lots	of output...
		Passed All Tests
		%

	You should test	Aegis as a mortal in both passes, rather
	than as	root, to be sure the set-uid-root functionality
	is working correctly.

	It is required that Aegis run set-uid-root for all of its
	functionality to be available.	It is NOT possible to
	create an "aegis" account and make Aegis run set-uid-
	aegis.	This is	because	Aegis does things as various
	different user IDs, sometimes as many as 3 in the one
	command.  This allows Aegis to use UNIX	security rather
	than inventing its own,	and also allows	Aegis to work
	across NFS.  To	be able	to do these things, Aegis must be
	set-uid-root.  Appendix	D of the Aegis User Guide
	explains why Aegis must	run set-uid-root; please read it
	if you have concerns.

INSTALLING AEGIS
	As explained in	the SITE CONFIGURATION section,	above,
	the Aegis package is installed under the /usr/local tree
	by default.  Use the --prefix=PATH option to configure if
	you want some other path.

	All that is required to	install	the Aegis 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 if you	want to
	bypass the configure script.

	The above procedure assumes that the soelim(1) command is
	somewhere in the command search	PATH.  The soelim(1)
	command	is available as	part of	the GNU	Groff package,
	mentioned below	in the PRINTED MANUALS section.	 If you
	don't have it, but you do have the cook	package, then a
	link from roffpp to soelim will	also work.

	The above procedure also assumes that the
	$(prefix)/man/man1 and $(prefix)/man/man5 directories
	already	exist.	If they	do not,	you will need to mkdir
	them manually.

USER CONFIGURATION
	The Aegis command is assumed to	be in a	generally
	accessible place, otherwise users will need to add the
	relevant directory to their PATH.  Users should	add
		source /usr/local/lib/aegis/cshrc
	to the end of their .cshrc file	for the	recommended
	aliases.  (This	may be in a different place, if	you
	specified a --prefix option.)

	There is also a	profile	for users of the Bourne	shell (it
	assumes	you have a version of the Bourne shell which has
	functions).  Users should add
		. /usr/local/share/aegis/profile
	to the end of their .profile file for the recommended
	aliases.  (This	profile	assumes	that users are using a
	Bourne shell which understands functions.)

	The /usr/local/com/aegis/state file contains pointers to
	"system" projects.  Users may add their	own project
	pointers (to their own projects) by putting a search path
	into the AEGIS_PATH environment	variable.  The system
	part is	always automatically appended by Aegis.	 The
	default, already set by	the /usr/local/lib/aegis/cshrc
	file, is $HOME/lib/aegis.  Do not create this directory,
	Aegis is finicky and wants to do this itself.

	Where projects reside is completely flexible, be they
	system projects	or user	projects.  They	are not	kept
	under the /usr/local/com/aegis directory, this directory
	only contains pointers.

	If you have a Web server, and the aegis.cgi was
	installed, you can set its AEGIS_PATH environment
	variable, if you want it to be able to see more	projects
	than just the global projects.	You do this by creating	a
	/usr/local/lib/aegis.cgi.conf file (there isn't	one, by
	default) and setting the AEGIS_PATH environment	variable
	in it.	This is	a fragment of Bourne shell script, not
	just the name.

PRINTED	MANUALS
	This distribution contains the sources to all of the
	documentation for Aegis, however the simplest way to get
	the documentation is by	anonymous FTP; PostScript files
	of the User Guide and Reference	Manual are available from
	the FTP	sites listed in	the README file.

	The Reference Manual contains the README and BUILDING
	files, as well as all of the section 1 and section 5
	manual pages.  The Reference Manual is about 200 pages
	long.

	The User Guide contains	information about how to use
	Aegis, including a fully worked	example.  The User Guide
	is about 100 pages long.

TIME SYNCHRONIZATION
	The Aegis program uses time stamps to remember whether
	various	events have happened and when.	If you are using
	Aegis in a networked environment, typically a server and
	data-less workstations,	you need to make absolutely sure
	that all of the	machines agree about the time.

	If possible, use the time daemon.  Otherwise, use
	rdate(8) via cron(8) every hour	or less.

GETTING	HELP
	If you need assistance with Aegis, 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
		% aegis	-version
		aegis version 3.29
		...
		%
	command.  Please run this command to get the exact
	number,	do not send the	text of	this example.

   Runtime Checking
	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
	-TRAce command line option.

	When the -TRAce	command	line option is followed	by one or
	more file names, it turns on execution traces in those
	source files.  It is usually best to place this	on the
	end of the command line	so that	names of the files to be
	traced are not confused	with other file	names or strings
	on the command line.

   Problem Reports
	If you send email to the author, please	include	the
	following information:

	1. The type of UNIX
		The author will	need to	know the brand and
		version	of UNIX	you are	using, or if it	is not
		UNIX but something else.  The output of	"uname
		-sr" is	usually	sufficient (but	not all	systems
		have it).

	2. The Version Number
		In any information you send, please include the
		version	number reported	in the
		common/patchlevel.h file, or `aegis -vers` if you
		can get	it to compile.

	3. The Archive Site
		When and where you obtained this version of
		Aegis.	If you tell me nothing else, tell me this
		(and, hopefully, why you did nothing else).

	4. Unpacking
		Did you	have problems unpacking	Aegis?	This
		probably isn't a problem with the .tar.Z
		distribution, but you could have obtained a shar
		format copy.

	5. Building
		Did you	have problems building Aegis?  This could
		have been the instructions included, it	could
		have been the configure	script,	it could have
		been the Makefile, or anything else.

	6. Testing, Non-Set-Uid
		Did you	have problems with the tests?  You could
		have had problems running them,	or some	of them
		could have failed.  If some tests fail but not
		others,	please let me know which ones failed, and
		include	the fact that Aegis was	not set-uid-root
		at the time.  The -k option to make can	be useful
		if some	tests fail but not others.

	7. Testing, Set-Uid-Root
		Did you	have problems with the tests when Aegis
		was set-uid-root?  You could have had problems
		running	them, or some of them could have failed.
		If some	tests fail but not others, please let me
		know which ones	failed,	and include the	fact that
		Aegis was set-uid-root at the time.

	8. Installation
		Did you	have problems installing Aegis?	 This
		could have been	the instructions, or anything
		else.

	At this	point it would probably	be a very good idea to
	print out the manual entries and read them carefully.
	You will also want to print a copy of the User Guide; if
	you don't gave groff, there should be a	PostScript copy
	at the archive site.  It is a known flaw that the User
	Guide is incomplete, it	is something the author	is
	working	on "at this moment".

	9. The Example Project
		After reading the User Guide, it is often useful
		to manually run	through	the example in chapter 3.
		You will need to do more than one change,
		hopefully several; the first change is not
		representative of the system.  Did you manually
		do the example?	 Did you find flaws in the User
		Guide or manual	entries?

	10. Using Aegis
		Did you	have problems using Aegis?  This is a
		whole can of worms.  If	possible, include a shell
		script similar to the tests which accompany
		Aegis, which reproduces	the bug.  Exit code 1 on
		failure	(bug), exit code 0 on success (for when
		bug is fixed).

	11. The	Source Code
		Did you	read the code?	Did you	write some code?
		If you read the	code and found problems, fixed
		them, or extended Aegis, these contributions are
		most welcome.  I reserve the right to modify or
		reject such contributions.

	The above list is inclusive, not exclusive.  Any and all
	feedback is greatly appreciated, as is the effort and
	interest required to produce it.

LICENSE
	The Aegis program is free software; you	can redistribute
	it and/or modify it under the terms of the GNU General
	Public License as published by the Free	Software
	Foundation; either version 2 of	the License, or	(at your
	option)	any later version.

	The Aegis program 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 in this
	distribution.

AUTHOR
	Peter Miller   E-Mail:	 millerp@canb.auug.org.au
	/\/\*		  WWW:	 http://www.canb.auug.org.au/~millerp/

WINDOWS-NT
	It is possible to build	Aegis for Windows-NT.  I have
	only done this using the Cygnus	freeware CygWin32 system,
	though it may be possible with other Unix porting layers
	also.

   Caveat
	This document only describes a single user port	of Aegis
	to Windows NT.

	Aegis depends on the underlying	security provided by the
	operating system (rather than re-invent	yet another
	security mechanism).  However, in order	to do this, Aegis
	uses the POSIX seteuid(2) system call, which has no
	direct equivalent on Windows NT.  This makes porting
	difficult.  Single user	ports are possible (e.g. using
	Cygwin (http://www.cygwin.com/), but are not usually what
	folks want.

	Compounding this is the	fact that many sites want to
	develop	their software for both	Unix and Windows NT
	simultaneously.	 This means that the security of the
	repository needs to be guaranteed to be	handled	in the
	same way by both operating systems, otherwise one can act
	as a ``back door'' into	the repository.	 Many sites do
	not have the same users	and permissions	(sourced from the
	same network register of users)	on both	Unix and Windows
	NT, making the mapping almost impossible even if the
	security models	did actually correspond.

	Most sites using Aegis and Windows NT together do so by
	running	Aegis on the Unix systems, but building	and
	testing	on the NT systems.  The	work areas and repository
	are accessed via Samba or NFS.

   The Source
	You need to FTP	the Cygwin system from RedHat.	It can be
	found at
		http://www.cygwin.com/
	and then follow	the links.  The	original version used was
	B20.1, but more	recently 1.1.7 has been	used.

	It is absolutely essential to run the mkpasswd and
	mkgroup	commands, otherwise Aegis will give fatal errors
	about unknown users and	groups.	 See the Cygwin	README
	for instructions.

   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 follow the install instructions about
	/bin/sh, 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).

	You will want to mount your various network drives onto
	the same places	they appear on your Unix hosts.	 This way
	you don't need to learn	two names for all your files.

	Mounts persist across Cygwin sessions.	They are stored
	in a registry file somewhere.  You will	not need to do
	all this every time!

   Too Much Administrator
	If you have administrator privilege on your Windows NT
	box, you need to get rid of it.	 (Have a second	admin
	account	instead.)  This	is because Windows NT will make
	the files belong to the	wrong user for files on	some
	partitions, like /tmp.	(This took me days to work out!)
	This confuses both Aegis and RCS.

	If you get weird ``Permission denied'' errors from
	amazingly unlikely causes, this	is probably why.

   Before You Start
	There are several pieces of software you need before you
	can build Aegis	on Cygwin.

	I'm going to keep mentioning ``your local GNU mirror''.
	You can	find
		GNU at http://www.gnu.org, however you are better
		off using a local mirror, and these are	scattered
		around the globe.  Follow the ``mirrors'' link on
		their front page to find your closest mirror.
		Also, it's often a good	idea to	configure these
		packages with the ``--with-gnu-gettext'' option
		to their ./configure commands.

	Do not use WinZip to unpack the	tarball.  It has a nasty
	habit of
		turning	all of the newlines into CRLFs.	 This
		will confuse lots of utilities,	especially GNU
		Groff.	Use the	``tar xzf aegis-3.29.tar.gz''
		command	from within Cygwin.

	Make sure the Cygwin you are using has GNU Groff 1.15 or
	later
		(use a ``groff -v'' command).  Grab and	install
		the latest from	your local GNU mirror, if it
		isn't.

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

	zlib	You need to grab a copy	of zlib; the same source
		as works for Unix will work for	Cygwin.	 It will
		install	as a static library.

	GNU diffutils
		You need GNU diffults, because when you	come to
		configure GNU RCS (next) it would otherwise
		complain about a stupid	diff and a missing diff3
		command.  The install-sh script	is broken, so
		you'll need to do the final step in the	install
		by hand.

	GNU RCS	All of Aegis' tests assume RCS is present.  Also,
		you are	going to need something	for a history
		tool.  The install-sh script is	broken,	so you'll
		need to	do the final step in the install by hand.

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

	Sharutils
		You need the uudecode command for several of the
		tests, and this	may be found in	the GNU	Sharutils
		package.  You can get a	copy from your local GNU
		mirror.

	The configure step is almost the same as for Unix.  I
	know you are itching to	get typing, but	read through 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
		bash$

   Test
	The tests are run in the same way as the Unix tests, but
	you don't need to run the set-uid-root variants, because
	no such	thing exists under Windows NT.
		bash$ make sure
		...lots	of output...
		Passed All Tests
		bash$

	Unfortunately, it isn't	that simple.  There are	a number
	of things you will see go wrong...

	+o Several tests	fail because ed	isn't there.

	+o Several tests	fail because ci	(RCS 5.7) dumps	core much
	  too often for	my liking.

	+o A couple of tests fail because they don't expect the
	  ``.exe'' extension on	executable files.

	+o A couple of tests (notably, the aedist tests)	fail
	  because of the CRLF vs NL dichotomy.	This means that
	  the expected results don't match, not	that it	isn't
	  working.

	Despite	all the	bad news, the vast majority of tests
	pass, and the others have good excuses.

   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$

Reference Manual	      Aegis				1
