WRPRC2 Configuration Files
Release 2.09
13 December 1996


This document accompanies the WRPRC2 imake configuration files, and
describes the various parameters provided by them.  It should be read
by anyone who is porting the files to a new platform or attempting to
change the defaults.  Parts of this document are derived from the
mit/config/README file in the X11R4 distribution.

The WRPRC2 configuration files are used with imake, and assume that imake,
makedepend, imboot, mkdirhier, and msub are installed.  If you need those
programs, see the README file in the top-level directory of the WRPRC2
distribution.

1.  Introduction

Because Makefiles are inherently unportable, a tool called imake generates
platform-specific Makefiles from machine-independent descriptions called
Imakefiles.  It makes very heavy use of the C preprocessor both for constants
and macro functions.  imake can be somewhat tricky to master; however, it is
invaluable for making projects easy to configure on different systems.

Imakefiles usually contain definitions of make variables plus one or more
invocations of macro functions to build the desired parts of the Makefile.
imake reads a template file containing definitions that are common to all
Makefiles, which includes machine, project, and site-specific files
containing definitions for the various commonly used commands and flags for
enabling certain build options.  It then includes a rules file in which all
of the various macro functions are defined, followed by the Imakefile being
processed.  Finally, it appends a set of common rules to the bottom.


2.  The configuration files

In the config directory, there is a set of configuration files, which may be
divided into two categories:

- Baseline configuration files which define the most probable defaults
  for parameter values.
- Override files, which specify project-specific configuration information.

The baseline configuration files are:

	Imake.tmpl	Template defining the order in which other files are
			processed
	Imake.cf	Vendor block selection
	Imake.params	General system and project parameters
	Imake.rules	Rules for generating Makefile target entries
	vendor.cf	Vendor-specific parameters
	site.def	Site-specific parameters

The override files have names and functions similar to those of the baseline
files.  They are intended to be used by individual projects for which it's
necessary to override or extend the configuration information provided by the
baseline files:

	Imake.p-cf
	Imake.p-params
	Imake.p-rules
	vendor.p-cf
	site.p-def

The baseline files and a set of dummy (i.e., empty) override files are
installed into the directory under ConfigRootDir named by ConfigName (by
default, WRPRC2).  Should a project wish to override configuration
parameters or define new ones, it may do so by providing project-specific
override files in a config directory under the project top-level directory.
imake searches for configuration files in such a way that project-specific
override files are found before and take precedence over the dummy override
files in the public configuration file directory.

Before you install the configuration files, look over your vendor file and
make sure it's correct for your system.  You may also want to modify site.def
to provide site-specific values of parameters to override the defaults.

To see what values the parameters will have, build the Makefile in the
config directory, then type:

	% make test | more


3.  The template file Imake.tmpl

Imake.tmpl defines the order in which the other files are processed.  The
top of the file defines some useful constants and then includes a file
Imake.cf that contains a series of conditional "vendor blocks" for setting
the platform type.

This requires that there be a unique preprocessor symbol that can be used to
identify which configuration block to use.  It's assumed that your imake
defines the proper symbol for your system as necessary.  If it doesn't,
you'll need to rebuild imake so it does.

Each conditional block in Imake.cf defines several symbol names representing
the type of system being configured:

	#define VendorIncludeFile		<PLATFORM.cf>
	#define VendorFile			PLATFORM.cf
	#define ProjectVendorIncludeFile	<PLATFORM.p-cf>
	#define ProjectVendorFile		PLATFORM.p-cf
	#define PLATFORMArchitecture

where PLATFORM is the type of the system being configured.  The redundant
versions are needed because one is used by cpp to include the file and the
other is used in generating filenames.  The Architecture symbol may be
used in Imakefiles to obtain vendor-specific rules or values.  The unique
symbols that were used to select the configuration block are then undefined
to prevent Imakefiles from using system-dependent rules as opposed to
platform-dependent (some platforms run on multiple systems).  Under certain
conditions, more than one Architecture symbol will be defined.  For instance,
if a vendor's OS has releases which run under different chipsets and it's
necessary to be able to distinguish between them, hardware and software
architecture symbols can both be defined.

The template file should not be edited.  Platform-specific changes can be
made in the appropriate *.cf files and site-specific changes can be made in
site.def.  Project-specific changes can be made in Imake.p-params, the *.p-cf
files, and site.p-def under the project's private config directory.  Any
parameter that is not set will be given a default value in Imake.params.


4.  The parameters file Imake.params

All of the common system and project description parameters are located in
the file Imake.params.

Boolean symbols should be defined as YES or NO.

Imake.params provides defaults for the following variables, presented below
by functional groups:

General system characteristics:

	HasExecableScripts	boolean for systems that can exec() #!/bin/sh
	HasGcc			boolean for whether or not to use gcc
	HasGcc2			boolean for whether or not to use gcc 2.x
	HasRanlibCmd		boolean for presence of ranlib program
	HasSoelim		boolean for nroff/troff .so eliminator program
	HasSymLinks		boolean for symbolic links
	HasStdarg		boolean for presence of <stdarg.h>
	HasUnistdH		boolean for presence of <unistd.h>
	HasVarargs		boolean for presence of <varargs.h>
	HasVFork		boolean for presence of vfork() system call
	HasVoidSignalReturn	boolean for POSIX signal() procs
	OSMajorVersion		major version number of operating system
	OSMinorVersion		minor version number of operating system
	OSTeenyVersion		teeny version number of operating system
	SystemV			boolean for systems that are at least SVR2
	SystemV4		boolean for SVR4 systems

Configuration directory and program information:

	DependCmd		command to run makedepend
	ImbootCmd		command to run imboot
	MkdirHierCmd		command to create directories
	MsubCmd			command to run msub

Configuration and project identification information:

	ConfigMajorRelease	major release level of the group
	ConfigMinorRelease	minor release level of the group
	ConfigName		name of this group of configuration files
	ConfigRelease		release level of the group
	ConfigRootDir		path to root of public config file dirs
	ProjectMajorRelease	major release level of the project
	ProjectMinorRelease	minor release level of the project
	ProjectName		name of the project
	ProjectRelease		release level of the project

Directory and filename information:

	AdmDir			directory for administrative files
	BinDir			directory for user programs
	CURDIR			current directory relative to top of sources
	EtcDir			directory for system maint. programs, servers
	IncludeRoot		top of system include file hierarchy
	LintLibDir		directory for lint libraries
	LocalAdmDir		local directory for administrative program
	LocalBinDir		local directory for user programs
	LocalEtcDir		local directory for system maint. programs
	LocalIncludeRoot	top of local include file hierarchy
	LocalLintLibDir		local directory for lint libraries
	LocalRootDir		root of local directory hierarchy
	LocalUsrLibDir		local directory for library files
	ManDir			directory in which to install program man pages
	ManRoot			top of system manpage hierarchy
	ManSourcePath		common prefix of man page directories
	ManSuffix		man suffix for programs
	TOPDIR			relative path to top of sources
	TmpDir			directory for temporary files
	UsrLibDir		directory for system library files

Names of commands used during project build and install processes:

	ArCmd			command used to create libraries
	AsCmd			command used to run assembler
	AwkCmd			command to run awk
	BourneShell		command used to run Bourne Shell
	CatCmd			command to run cat
	CcCmd			command to run C compiler
	ChdirCmd		command to change directories
	ChmodCmd		command to run chmod
	CmpCmd			command to run cmp
	CommCmd			command to run comm
	CpCmd			command to copy one file to another
	CppCmd			command to run C preprocessor
	InstallCmd		command to install files
	LdCmd			command to run loader
	LintCmd			command to run lint
	LnCmd			command to link two files
	MakeCmd			command to run make
	MvCmd			command to rename a file
	PerlCmd			command to run perl
	PerlPath		pathname of perl
	Perl5Cmd		command to run perl 5
	Perl5Path		pathname of perl 5
	RanlibCmd		command to clean up libraries
	RmCmd			command to delete files
	SedCmd			command to run sed
	SortCmd			command to run sort
	TagsCmd			command to run tags
	UniqCmd			command to run uniq

Local programs:

	DistarCmd		distributed-archive interface
	FigenCmd		form-info generator

Flags to commands used during the build/install process:

	DefaultCCOptions	default special C compiler options
	DefaultCDebugFlags	default C compiler flags for debugging
	FilesToClean		files to delete in make clean
	InstCopy		install flags to copy without removing original
	InstDatFlags		install flags for non-executables
	InstDatMode		install mode for non-executables
	InstGidProgFlags	install flags for setgid programs
	InstGidProgMode		install mode for setgid programs
	InstGroup		install flags to set group
	InstIncFlags		install flags for include files
	InstIncMode		install mode for include files
	InstLibFlags		install flags for libraries
	InstLibMode		install mode for libraries
	InstManFlags		install flags for man pages
	InstManMode		install mode for man pages
	InstOwner		install flags to set owner
	InstProgFlags		install flags for programs
	InstProgMode		install mode for programs
	InstScriptFlags		install flags for executable scripts
	InstScriptMode		install mode for executable scripts
	InstStrip		install flags to strip installed programs
	InstUGidProgFlags	install flags for setuid/setgid programs
	InstUGidProgMode	install mode for setuid/setgid programs
	InstUidProgFlags	install flags for setuid programs
	InstUidProgMode		install mode for setuid programs
	LintLibFlag		flags to generate lint libraries
	LintLibs		libraries needed to run lint
	LintOpts		lint options to control strictness
	LoaderLibPrefix		loader flags before library pathnames
	ProjectDefines		any special project defines
	ProjectIncludes		any special project include directories
	ProjectLoadFlags	any special project loader flags
	ProjectLoadLibs		any special project libraries needed to link
	RanlibInstFlags		flags to ranlib after copying
	StandardCppDefines	-D's for running cpp
	StandardDefines		-D's for running C compiler
	StandardIncludes	-I's for running C compiler
	StandardLoadFlags	system-specific loader flags
	StandardLoadLibs	system-specific libraries needed to link

Document preparation command names and flags:

	EqnCmd			equation layout program
	ManMacros		macros for formatting manual pages
	MeMacros		macros for formatting other documents
	MmMacros		macros for formatting other documents
	MsMacros		macros for formatting other documents
	NeqnCmd			nroff version of eqn
	NroffCmd		non-typesetter formatting program
	PicCmd			picture layout program
	SoelimCmd		.so-request eliminator
	TblCmd			table layout program
	TroffCmd		typesetter formatting program

Miscellaneous:

	ConstructMFLAGS		System V option to set MFLAGS make variable

Library specifiers:

	There are many of these, two forms for each.  Typically, for a
	library xxx, XxxLib is the link library specifier, and DepXxxLib is
	the dependency specifier.


5.  Vendor-specific *.cf files


The template files contain defaults for all platforms which can be
overridden by including an appropriate definition in the .cf file.

Differences between operating systems are handled by setting various
configuration parameters in the vendor-specific *.cf files.

The easiest way to create a new vendor file is to:

     o	Find a configuration similar to yours or start with generic.cf.
     o	Set the SystemV variable if your OS is based on SVR2 or SVR3.
     o	Set the SystemV4 variable if your OS is based on SVR4.
     o	Set the OSMajorVersion and OSMinorVersion variables.
     o	read Imake.params to see if there is anything you'd like to override.
     o	look at the other *.cf files to see if there are any variables you'd
	like to set; common ones include Has* symbols and *Cmd symbols.

EVEN IF THERE IS ALREADY A VENDOR FILE FOR YOUR PLATFORM, BE SURE TO READ IT!
It may contain other information you need to know before a build will proceed
properly.  It doesn't hurt to read several different vendor files to get a feel
for how they work.

If you add support for a particular vendor, please send your changes to
dubois@primate.wisc.edu.


6.  Site-specific site.def file

The site.def file is used to set configuration parameters that apply to a
given site.  Use the #ifndef/#endif construction so that values you define
may still be overridden in the vendor-specific files.

Some important things that can be done in site.def are:

Override values of parameters that specify system and local directories
layout, such as TmpDir, IncludeRoot, LocalIncludeRoot, etc.  Values of
the LocalXXXDir parameters default to be the same as the corresponding
XXXDir parameters.  Change them if you want.  Pay particular attention
to the LocalXXXDir parameters, since install rule invocations in
projects configured with the WRPRC2 files will often refer to one of
these directories as the installation destination.

Select document preparation preferences.  The WRPRC2 defaults are
surely wrong for many sites and should be changed.  We use xroff,
pstroff, and groff, all of which have been the default at different
times.  The soelim command is used in document formatting rules if you
have it (i.e., if HasSoelim is YES).  This is useful when running files
through tbl, eqn, etc., since otherwise tables and equations in .so
files don't get processed.  An additional reason for using soelim at
WRPRC is that our troff's are accessed through a mechanism that chooses
the least loaded machine and runs the job there over the network; in
this environment, .so files fail if troff isn't running on the local
machine.


7.  Imakefiles

The easiest way to write an Imakefile is to find another one that does
something similar and modify it.  Look in the examples directory for sample
Imakefiles.

Individual Imakefiles may use any of the macros defined in Imake.rules.  Many
of these rules use auxiliary make variables that may be defined in your
Imakefile for directory-specific purposes:

	SUBDIRS		used by numerous directory-traversing rules
	SRCS		used by DependTarget
	DEFINES		extra flags used to compile C programs
	INCLUDES	extra include directories used to compile C programs

Conventions

Rules that generate an entry to build a target "prog" usually also generate
"all" and "clean" targets.  Install rules for a program generate "install"
and "i.prog" targets.  Manual page install rules generate "install.man" and
"i.prog.man" targets.

This strategy allows "make all" and "make install" to build and install
all programs in a directory in one fell swoop, yet also allows "make prog"
and "make i.prog" to make or install a single program.  "make install.man"
installs all manual pages, and "make i.prog.man" installs a page for a single
program.

If there are files which should be removed by the "make clean" operation,
specify them in the StuffToClean() rule.


8.  Some differences between X11 and WRPRC configuration files

Much of the WRPRC2 distribution was derived originally from the X11
configuration files, although there are now many differences.  Some things
that have been retained but in a slightly different form are listed below.
If you are used to the X11 form of these, note the differences.

X11's RemoveTargetProgram() rule is here known as RemoveTarget().  (The
rule is more generally-useful than just for programs, so I renamed it.)

The X11 Symbol ExecableScripts is HasExecableScripts in this project.

X11 LibmanDir is WRPRC LibManDir.

X11 LintlibDir is WRPRC LintLibDir.

X11 NamedSubdirsTarget() has one more argument than WRPRC NamedSubdirsTarget().

X11 CleanTarget() removes *~ files.  WRPRC CleanTarget() doesn't.
