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-.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 .md subdirectories throughout the source tree, and then rebuild everything with MAKEOBJDIR set to .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 $]