
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.

	Edit the unix/config.h file that controls the first, `Unix' version
	of pmake.

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.
	
4.	First PMake installation.

	Define the macros 

	DESTDIR			Installation root
	BINDIR			where pmake should be installed.
	LIBDIR			place to store pmake's canned makefiles
				(e.g. system.mk -- DEFSYSPATH in config.h)
	SYSTEM_MK    	    	Actual name for the system makefile. I
				use system.mk.

	either in the top makefile or on the command line and `make install'
	to put the preliminary pmake in place.

	You might want to test it with the stuff in ./tests.

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 customs/config.h and ./config.mk to tailor the customs/pmake
	build and installation.  For general hints about customs
	configuration, read customs/README.  Be sure to read, and
	understand, the file SECURITY.  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 itself let me know.

	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 (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 -C 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'.

	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.  customs/README gives some hints.

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

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.

A. Stolcke, 2/22/92

[$Id: INSTALL,v 1.4 1992/04/21 18:33:11 stolcke Exp $]
