


build(aegis)					     build(aegis)


NAME
	aegis -	project	change supervisor
	Copyright (C) 1990, 1991, 1992,	1993, 1994, 1995 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.

	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 >	/dev/null
		%

	By default, configure will arrange for the make	install
	command	to install the aegis package's files in
	/usr/local/bin,	/usr/local/man,	and /usr/local/lib/aegis.
	You can	specify	an installation	prefix other than
	/usr/local by giving configure the option --prefix=PATH.



								1





build(aegis)					     build(aegis)


	You can	specify	separate installation prefixes for
	architecture-specific files and	architecture-independent
	files.	If you give configure the option --exec-
	prefix=PATH the	aegis package will use PATH as the prefix
	for installing programs	and libraries.	Data files and
	documentation will still use the regular prefix.
	Normally, all files are	installed using	the same prefix.

	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.

   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.





								2





build(aegis)					     build(aegis)


	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.




								3





build(aegis)					     build(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	three files: aegis,
	fmtgen and txt2c.

	aegis	The aegis program is a project change supervisor.

	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.

	txt2c	The txt2c 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.

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 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, and
		in the same directory.	The cook program is
		available under	the terms of the GNU General



								4





build(aegis)					     build(aegis)


		Public License.

	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.

	GNU diff
		If the diff(1) utility supplied	by your	flavor of
		unix does not have the -c option, you will need
		GNU diff to make patch files, if you want to
		publish	software for FTP or on USENET.	Context
		differences are	also helpful for reviewing
		changes.

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

	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.

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.

	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



								5





build(aegis)					     build(aegis)


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

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



								6





build(aegis)					     build(aegis)


	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	Roff package,
	mentioned previously 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.

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



								7





build(aegis)					     build(aegis)


	The /usr/local/lib/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 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/lib/aegis directory, this directory
	only contains pointers.

PRINTED	MANUALS
	This distribution contains the sources to all of the
	documentation for aegis.  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.

	To print copies	of the README and BUILDING files, the
	following commands may be used
		% cd aux
		% groff	-t -man	*.man |	lpr
		% cd ..
		%
	This will produce about	12 pages.  The "-t" flag means
	preprocess with	the tbl(1) filter.

	To print copies	of the manual entries, the following
	commands may be	used
		% cd man1
		% groff	-s -t -man *.1 | lpr
		% cd ../man5
		% groff	-s -t -man *.5 | lpr
		% cd ..
		%
	This will produce about	60 pages.  The "-s" flag means
	preprocess with	the soelim(1) filter.

	To print a copy	of the User Guide, the following commands
	may be used
		% cd doc
		% groff	-s -t -p -ms aegis.ms |	lpr
		% cd ..
		%
	This will produce about	90 pages.  The "-p" flag means
	preprocess with	the pic(1) filter.  Alternatively, you
	could get a PostScript copy of the User	Guide from the
	archive	site.

	Please note while the User Guide is largely complete,



								8





build(aegis)					     build(aegis)


	some sections are still	being written.	Feedback on the
	form and content of this document would	be most	welcome.

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 the	aegis program, please do
	not hesitate to	contact	the author at
		Peter Miller <pmiller@agso.gov.au>
	Any and	all feedback is	welcome.

	When reporting problems, please	include	the version
	number given by	the
		% aegis	-version
		aegis version 2.3.D020
		...
		%
	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, the 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).





								9





build(aegis)					     build(aegis)


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





							       10





build(aegis)					     build(aegis)


	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	   UUCP:   uunet!munnari!agso.gov.au!pmiller
	/\/\*	       Internet:   pmiller@agso.gov.au










							       11


