
PMAKE/CUSTOMS INSTALLATION HINTS

The installation of pmake with customs is somewhat tricky.  It took me a while
to figure it out from the original documentation, and then I changed it 
somewhat to improve configurability, so this is intended as a quick guide
along the way.

The overall strategy is to build pmake twice, first in a stripped-down
version without job exportation (only local parallelism).  Then
the resulting pmake is used to build the customs system and a second
version of pmake that uses customs for job exportation.

Here is how it all works.

1. 	PMake configuration.

	Look over the unix/config.h file that controls the first, `Unix'
	version of pmake.  Hopefully, no changes will actually be necessary
	on the systems PMake has been tested on.

	Also make the necessary changes to the following macros in the
	top-level 'makefile':

	DESTDIR			Installation root
	BINDIR			where pmake should be installed.
	LIBDIR			place to store pmake's canned makefiles

2.	First PMake build.

	Do a `make' in the top-level directory. This builds the list and sprite
	libraries (in the lib subdirectory), as well as the simple pmake in
	the top-level directory using `makefiles' (small `m') in the various
	directories.  The compiler used is the standard `cc' on your system.
	If this works but isn't optimal, don't worry, since the resulting
	binary won't be the final version anyway.  If you absolutely have to
	you can tweak MACHFLAGS macro in the top-level makefile.

3.	PMake environment for your system.

	Goto lib/mk.  The system.mk file is supposed to define default make
	rules and standard macros for pmake.  The way I set it up is to
	figure out by itself what systems it is running on (near the top),
	and then #include a sys-<system>.mk file that contains actual
	system dependencies.  That way I can share the entire pmake lib
	directory across platforms and isolate the system dependencies
	neatly.  The sys-foo.mk files should also define a couple of
	unique macros much like the C compiler, e.g., `sun' and `sparc'
	on a Sun4.  That way you can use them in #ifdef's later in
	pmakefiles.  System V systems should also define SYSV.  This is
	later used extensively in the customs build.

	You may be lucky and find your system already defined there.
	If you port to a new system let me know of the changes that were
	required.

	NOTE: If you change unix/config.h to use a SPECIAL_CHAR other than
	`#' (e.g., `.' for BSD compatility), then the system makefiles
	in lib/mk will no longer work.  You will have to edit them yourself
	to replace directives starting with `#' to use the new SPECIAL_CHAR.
	
4.	First PMake installation.

	Assuming the makefile was already set up correctly in step 1,
	just run `make install' to put the preliminary pmake in place.

	You might want to test it with the stuff in ./tests.
	To do so, run `TESTALL pmake'.

5.	Customs configuration.

	Now for the biggy. Customs is a system of daemons that monitors
	machine availability and provides a job import/export service to
	client programs (hence the name).  Read the papers in
	./doc/customs and the man pages in ./doc for general and specific
	information about how it works.

	Edit config.mk in the toplevel directory.  You should adjust
	the target directories changed in 'makefile' as part of step 1,
	as well as some additional install directories for customs
	related things.  Other than that you may want to adjust the
	choice of compiler, debug flags, etc.  To understand what you
	can do in config.mk you'll have to understand some of the
	wonderful features of pmake, ifdef's, conditional assignments,
	etc.  Also take a look at customs/Makefile since config.mk
	mostly modifies the defaults there.  If you have to tweak
	customs/Makefile unless you are trying to port to a new
	platform.

	Edit customs/config.h to tailor various aspects of customs 
	operation, although the defaults should mostly work. Read the
	comments in that file, as well as customs/README for context.
	If you change any of the security-related options be sure to
	understand what etc/SECURITY says.

	A tricky point is the file name space, which is supposed to be
	uniform across machine for remote job execution to work.  The
	original pmake comes with the `prefix' system as one solution
	to this problem.  I prefer using a standard automounter (such as
	Sun automount or amd) in an NFS environment.  Whatever your
	choice is, pathnames obtained by `pwd' may need some editing
	to be usable on a remote system (such as stripping /tmp_mnt
	or similar).  If that is the case you have to edit the
	Customs_NormPath() routine in customs/customslib.c and set #define's
	accordingly in customs/config.h.

6.	Testing PMake/Rebuilding libraries (optional).

	At this point you may want to recompile the auxiliary
	libraries.  Goto to ./lib and do a `pmake' there, using the pmake
	you built earlier.  This compile will use the `Makefiles' (big M)
	and the config.mk file.

7.	Customs and 2nd PMake build + installation.

	Goto ./customs and try `pmake depend'.  This uses the `makedepend'
	program to generate header file dependencies in the file
	dependencies.mk.  If you don't have makedepend (e.g., from the MIT
	X11 distribution) create an empty dependencies.mk.  Now try `pmake'.
	This builds the new pmake.  `pmake all' will build the remaining
	programs that make up the customs system.  `pmake install' will
	install everything into the places specified during configuration.

	You may also want to install the man pages.  Goto ./doc, maybe
	edit config.mk to override the installation points in doc/Makefile,
	and do `pmake install'.

	You can use the 4.4BSD MAKEOBJDIR environment variable to
	have objects and binaries placed in subdirectories (see pmake.1).
	This is very convenient on the second build since you can now
	keep multiple binaries in the same source tree.
	The top-level make target `new' will clean the objects from
	the first build, create <platform>.md subdirectories throughout
	the source tree, and then rebuild everything with MAKEOBJDIR
	set to <platform>.md.  Top-level `make install' installs both
	binaries and man pages.

	One more thing: The default install targets assume you have a
	Berkeley-style install program.  It won't work with System 5
	/etc/install.  You could use the install script that comes with
	the MIT X11 distribution, or try to tailor the INSTALL and *MODE
	macros to do the right thing.

8.	Get the customs system working.  Basically, you have to start the
	customs daemon on each machine you want to participate in the
	scheme.  The minimal way to do this to run

		customs -master ALL

	on each machine.  customs/README gives more information, and you'll
	have to study the customs man page to get the benefit of the numerous
	run-time options.

	To verify that it works, check the following things:

	a - cctrl -all should result in an `alive' message from each
	    machine that has a daemon running.
	b - importquota should report sensible availability criteria
	    for the local system (provided that it runs customs, too).
	c - reginfo should show that status of all machine on the customs
	    network (those machine with the same -net parameter as the
	    local one).  If the network is large (like 50 machines)
	    it can take several minutes to reginfo to report all machines.
	d - `export command' should successfully start `command' on an
	    available remote machine.
	e - `pmake target' should successfully export commands.  Try
	    `pmake test' in the customs directory for a simple test.
	    Rerun the tests in ./tests using the new pmake and using
	    job exportation, and make sure the output is identical
	    to non-exporting pmake (modulo the interleaving of printed
	    text).

	Should the customs daemon fail for some reason the problem may be
	something in the configuration that was omitted.  Running
	the daemon in debugging mode

		customs -debug -nolog -verbose -master ALL

	may be helpful to figuring out what's wrong.  The other possibility,
	of course, is a genuine bug.

9.	Tailor the customs network configuration.  You can use the -bias
	option to give faster machines preference in remote host allocation.
	The customs.conf script gives some ideas on how to do daemon
	configuration automatically in a larger pool of machines of
	various kinds.

10.	Enjoy!  Pmake/customs is a great piece of software and we should be
	thankful to Adam for the excellent idea and high-quality
	implementation.

If you can't get it to work, try reading etc/FAQ, a list of common problems
and solutions put together by a kind soul that once shared your fate!

A. Stolcke, 2/22/92

[$Id: INSTALL,v 1.12 1999/08/22 23:20:41 stolcke Exp $]
