WRPRC2 Configuration File Distribution
Release 2.10
13 December 1996
Paul DuBois
dubois@primate.wisc.edu
http://www.primate.wisc.edu/people/dubois

NOTE: xmkmf is NEVER used to build ANYTHING in this distribution.

NOTE: it's assumed you have a version of imake from X11R6 or higher.
If not, see the note about XCOMM at the top of config/Imake.tmpl.

This distribution contains the WRPRC2 imake configuration files, i.e.,
Release 2 of the Wisconsin Regional Primate Research Center
configuration files.  The Release 2 configuration files are not
upward-compatible with the Release 1 files.

Changes for each release of this distribution are listed in the
Changes-2.xx files.

If you need information about imake, see the "boa book":

	Software Portability with imake, 2nd edition
	Paul DuBois
	O'Reilly & Associates
	ISBN: 1-56592-226-3
	URL: http://www.ora.com/catalog/imake2
	Email: books@ora.com

There are also some shorter imake-related papers available at:

	http://www.primate.wisc.edu/software/imake-stuff/
	ftp://ftp.primate.wisc.edu/software/imake-stuff/

The WRPRC2 distribution does not contain source for the configuration
programs imboot, imake, mkdirhier, or makedepend.  You'll need those
programs to use the WRPRC2 files.  If you don't have them, retrieve the
itools distribution from the imake-book archive using one of the
locators below:

	http://www.primate.wisc.edu/software/imake-book/
	ftp://ftp.primate.wisc.edu/software/imake-book/

Instructions for building the itools distribution are available in
Appendix B of the boa book.  If you don't have the book, this appendix
is available online in the imake-book archive.

-------------------------------------------------------------------------------
Configuring and Installing the Distribution
-------------------------------------------------------------------------------

Instructions for building the distribution are given below.  If the
instructions don't work for you, let me know.

- The distribution consists of a main directory WRPRC2, a config directory
containing the configuration files, and an examples directory containing
some sample Imakefiles.  R1-docs contains the Release 1 documents, which
may be of some historical interest.

- You should review the configuration files first to see whether the parameter
values are appropriate for your system.  You may find it helpful to read the
reference document, reference.ms.

- You may need to modify your vendor file and/or site.def file (located
in the config directory).  If you have installed an earlier release of
the WRPRC2 files before, you may already have modified the vendor and
site.def files from that release.  If so, consult them so you know what
changes you'll have to make to the corresponding files in this
distribution.  (Don't just install the new files on top of the old ones
without looking.)

- If there's no vendor-specific file for your system in this distribution,
you'll have to write one.  These are the files ending in .cf.  Use the
ones provided as a guide and read "Using the WRPRC2 Configuration Files
On a New Platform" below.  Also, contact me if you'd like some advice.

- Modify site.def.  Use it to specify site-specific preferences for which
the defaults aren't suitable for your site.  For instance, if you want
to use /usr/local for the value of LocalBinDir rather than the default
of /usr/local/bin, put the following in site.def:

	#ifndef LocalBinDir
	#define LocalBinDir /usr/local
	#endif

Similarly, if you want to use groff instead of troff, write this:

	#ifndef TroffCmd
	#define TroffCmd groff
	#endif

Determine the value that imboot uses for the configuration root (take a
look at the imboot script on your machine).  The value of ConfigRootDir
must match what your copy of imboot uses.  By default this value is
/usr/local/lib/config.  If it's different on your machine (for
instance, /var/lib/config), put the following in site.def to override
the default:

	#ifndef ConfigRootDir
	#define ConfigRootDir /var/lib/config
	#endif

This is to make sure that "make install" installs the configuration files
into the right place, i.e., where imboot can find them.

Pay particular attention to the LocalXXXDir parameters.  They're set up
as counterparts to several standard system directories, but they're all
located under /usr/local by default.  Imakefiles written for the WRPRC2
configuration files will often use the LocalXXXDir parameters as
installation destintations, so you should make sure they point to where
you want locally installed files to go.

To move the local directories to a different root point, define
LocalRootDir as that root point.  To relocate individual local
directories, define individual LocalXXXDir parameters.  To make the
local directories the same as the standard directories, define
LocalBinDir as $(BINDIR), LocalIncludeRoot as $(INCLUDEROOT), etc.

Take a look at the other comments in site.def to see if there are other
parameters you might want to set.

When you decide to override a parameter in site.def , take a look at
your vendor file.  If the vendor file overrides the parameter, that
takes precedence over a definition in the site file.  In that case,
modify the vendor file instead.

- Note for Cray systems:  InstallCmd is defined as install.sh in
cray.cf.  For this to work, install.sh must be installed on your
system.  If you don't have it, get it from the itools distribution
mentioned above (or from the X11 distribution if you have it) and
install it as install.sh in some directory that's in your path.  (Don't
forget to make install.sh executable.)

- Note for HP systems:  InstallCmd is defined as install.sh.  See above
note for Cray systems, or change InstallCmd to bsdinst if you like.  I
find that install.sh works better than bsdinst on HP systems (fewer
useless warning messages).

Now follow the steps below in the WRPRC2 distribution top-level directory
to configure the Makefiles for this distribution.

1) Type:

	% make World

This should rebuild the Makefiles properly for your system.  If "make World"
dies, try bootstrapping the Makefiles like this:

	% imboot
	% make Makefiles

2) If you want to see what values are actually chosen on your machine for
the configuration parameters, change into the config directory and run the
following command:

	% make test | more

The make command shows you many of the configuration parameter values.  This
can be useful for determining whether or not you need to override values in
the vendor or site files.  You can change parameters, rebuild the Makefile
with "make Makefile", and then run "make test" again to check your changes.
When you're done in the config directory, change back into project root.

3) If you want to verify that the files will be installed into the correct
directory, use this command:

	% make -n install

4) To actually install the distribution, do this (you may need to become root
first):

	% make install

5) Some filenames changed between Release 2.00 and Release 2.01.  If
you have files named Project.tmpl, Project.p-tmpl, System.tmpl, and
System.p-tmpl in your installation directory, you can remove them.

-------------------------------------------------------------------------------
Configuring Projects with the WRPRC2 Configuration Files
-------------------------------------------------------------------------------

Read the tutorial document for general information about writing
Imakefiles for use with the WRPRC2 files.

When you have a project that has Imakefiles written for use with
the WRPRC2 files, build the project's Makefiles using the following
commands in the project root directory:

	% imboot -C WRPRC2
	% make Makefiles		(if the project has subdirectories)

Thereafter, you can build the Makefiles like this:

	% make Makefile
	% make Makefiles		(if the project has subdirectories)

-------------------------------------------------------------------------------
Using the WRPRC2 Configuration Files On a New Platform
-------------------------------------------------------------------------------

This release has been tested on at least the following platforms:

	SunOS 4.1.1B
	Solaris 2.5.1 (SunOS 5.5)
	RISC/os 4.01
	HP-UX 9.05
	MkLinux DR2
	FreeBSD 2.1.5

It should not be difficult to port the distribution to a new platform,
although you'll need to build imake if you don't already have it.  For
general information on building imake, see Appendix B of the boa book,
or retrieve the file appb.ps from the same place you get the itools
distribution mentioned above.

Briefly, you'll need to do four things:

1) Determine an appropriate vendor symbol that uniquely identifies your
platform.  There may be one already -- check Imake.cf from a recent X11
distribution, or from the itools distribution.

2) Build imake so it defines the vendor symbol when it invokes cpp.

3) Put a vendor block for your platform in Imake.cf.  (Check whether
there is one already; if not, write one using those already there as a
pattern.)

4) Write a vendor.cf file for your system, and create an empty vendor.p-cf
file.  The config/untested directory contains some *.cf vendor files for
various platforms.  You may be able to use one of them as a basis for your
system.  (These files are from an older release of X11 and should be considered
only as an approximation to what you'll need.)

If you port the WRPRC2 files to a new platform, please send me the changes.

-------------------------------------------------------------------------------
Mips Compatibility Problem with Release 1.
-------------------------------------------------------------------------------

Release 1 used "mipsriscos" as the vendor symbol for Mips machines running
RISC/os.  Release 2 uses "Mips", to be consistent with the X11R5
configuration files.  If you're using the Release 1 configuration files to
configure projects on a Mips machine, and you want to continue to use them
after installing the Release 2 files, you'll need to build a version of
imake that defines both symbols.  In a source distribution that builds
imake, the value of BOOTSTRAPCFLAGS should include both "-DMips" and
"-Dmipsriscos", and the predefs[] table in imakemdep.h should have entries
for both symbols when Mips is defined.
