summaryrefslogtreecommitdiff
path: root/web/glasgow/lit2x-0.16/mkworld/docs/config-wrprc.ms
diff options
context:
space:
mode:
Diffstat (limited to 'web/glasgow/lit2x-0.16/mkworld/docs/config-wrprc.ms')
-rw-r--r--web/glasgow/lit2x-0.16/mkworld/docs/config-wrprc.ms691
1 files changed, 691 insertions, 0 deletions
diff --git a/web/glasgow/lit2x-0.16/mkworld/docs/config-wrprc.ms b/web/glasgow/lit2x-0.16/mkworld/docs/config-wrprc.ms
new file mode 100644
index 0000000000..21f0036cfe
--- /dev/null
+++ b/web/glasgow/lit2x-0.16/mkworld/docs/config-wrprc.ms
@@ -0,0 +1,691 @@
+.\" format with
+.\" xroff -ms % | lpr
+.\"
+.\" revision date - change whenever this file is edited
+.ds RD 24 July 1990
+.nr PO 1.2i \" page offset 1.2 inches
+.nr PD .7v \" inter-paragraph distance
+.\"
+.EH 'Multiple-project Imake'- % -''
+.OH ''- % -'Multiple-project Imake'
+.OF 'Revision date:\0\0\*(RD'\s+2\*-DRAFT\*-\s-2'Printed:\0\0\n(dy \*(MO 19\n(yr'
+.EF 'Revision date:\0\0\*(RD'\s+2\*-DRAFT\*-\s-2'Printed:\0\0\n(dy \*(MO 19\n(yr'
+.\"
+.\" I - italic font (taken from -ms and changed)
+.de I
+.nr PQ \\n(.f
+.if t \&\\$3\\f2\\$1\\fP\&\\$2
+.if n .if \\n(.$=1 \&\\$1
+.if n .if \\n(.$>1 \&\\$1\c
+.if n .if \\n(.$>1 \&\\$2
+..
+.TL
+Using Imake for Multiple Projects
+.sp .5v
+(document version 1.02)
+.AU
+Paul DuBois
+dubois@primate.wisc.edu
+.AI
+Wisconsin Regional Primate Research Center
+Revision date:\0\0\*(RD
+.NH
+Introduction
+.LP
+.I imake
+is a tool for generating makefiles and is used to allow software projects
+to be configured easily on a wide variety of target machines.
+It is distributed with projects such as the X Window System and the Kerberos
+authentication system.
+The tool
+.I makedepend
+is typically used in conjunction with
+.I imake
+to generate dependencies in makefiles.
+.I xmkmf
+is also used, for bootstrapping makefiles from imakefiles.
+.LP
+This document describes the particular way
+.I imake
+is used to configure projects at WRPRC.
+The method is patterned after the way
+.I imake
+is employed in the X Window System (version 11, release 4).
+The X11R4 method is significantly more developed than in X11R3.
+Presumably,
+.I imake
+as used in Kerberos (currently at protocol revision 4)
+might have been used as a base, but I judged it
+unsuitable for two reasons: (i) I learned
+.I imake
+from studying X, so I'm probably imprinted to it;
+(ii) development of the configuration files in Kerberos appears to be
+at a more primitive level even than in X11R3.
+.LP
+The X11R4 approach allows configuration files to be stored either
+in a well-known system-wide location (e.g.,
+.I /usr/lib/config ),
+or in a
+.I config
+directory under the project top-level directory.
+.LP
+A more-than-passing acquaintance with
+.I imake
+is assumed here.
+Helpful companion documentation includes ``Configuration Management in
+the X Window System,'' the configuration and
+.I README
+files in the X11R4 distribution (in the
+.I mit/config
+directory), and the WRPRC configuration files (see below for
+information on distribution and availability).
+.NH
+Statement of Problem
+.LP
+Because of the flexibility
+.I imake
+provides as a
+configuration tool (once you figure out how to use it!),
+I had begun to use it on all my projects.
+Since these were all developed at the same site, the projects naturally
+had quite a bit of configuration information in common.
+On the other hand, different projects just as naturally had their own
+individual requirements.
+.LP
+What I had been doing was creating a
+.I config
+directory in each project directory, with a copy of the configuration files
+in each, modified as necessary for the project (otherwise known as ``using
+brute force'').
+I did not use configuration files in a system-wide location
+because of differing project requirements.
+At the same time, there was a great deal of redundancy between sets of
+configuration files since projects were built and installed
+in similar ways.
+It seemed rather wasteful and silly not to take advantage of this overlap,
+besides the fact that the multiple copies of files contributed to a
+maintenance inefficiency when changes were made that affected all projects.
+.LP
+This (unsatisfactory) situation prompts the question:
+how can the number of files to be maintained be minimized and how can
+configuration files be shared among projects without sacrificing the ability
+to specify project-specific information as necessary?
+.NH
+Solution to Problem
+.LP
+Since
+.I imake
+possessed the ability to look through multiple directories when looking
+for configuration files, the simplest solution to the problem seemed to be:
+.IP (i)
+Create a set of standard configuration files and store them in a well-known
+location (referred to here as StdConfigDir).
+.IP (ii)
+Allow projects to define an alternate configuration directory (referred to
+here as ProjConfigDir, typically the
+.I config
+directory under the project directory).
+.IP (iii)
+Tell
+.I imake
+to look through ProjConfigDir, then StdConfigDir for configuration files.
+This means changing
+.I xmkmf ,
+which executes
+.I imake ,
+and the configuration file definitions that construct
+.I imake
+commands.
+.LP
+In other words,
+a standard set of configuration files is created and stored in a well-known
+location for use by multiple projects.
+However, should it be required,
+individual projects place configuration files in their own
+.I config
+directory, which takes precedence over StdConfigDir when
+searching for files.
+In the degenerate case, projects need supply nothing if
+the standard stuff is sufficient; only files in StdConfigDir will be
+used.
+.NH
+Implementation of Solution
+.NH 2
+Imake.tmpl Architecture
+.LP
+The architecture of the
+.I imake
+template,
+.I Imake.tmpl ,
+as used in X11R4 is, roughly:
+.LP
+.DS
+.ta 3i
+header block section
+#include <\fIplatform\fR.cf> (platform-specific definitions)
+#include <site.def> (site-specific definitions)
+system description, build and installation definitions
+#include <Project.tmpl> (project-specific definitions)
+#include <Imake.rules> (\fIimake\fR rules)
+#include "./Imakefile" (\fIImakefile\fR for current directory)
+.DE
+.LP
+The header block section determines the machine type and the
+platform-specific file
+.I platform .cf
+to be included.
+.LP
+To accommodate other project-specific files, extra
+#include's are introduced into
+.I Imake.tmpl .
+The resulting modified architecture becomes:
+.LP
+.DS
+header block section
+.sp .2v
+#include <\fIplatform\fR.pcf>
+#include <\fIplatform\fR.cf>
+.sp .2v
+#include <site.pdef>
+#include <site.def>
+.sp .2v
+system description, build and installation definitions
+.sp .2v
+#include <Project.ptmpl>
+#include <Project.tmpl>
+.sp .2v
+#include <Imake.prules>
+#include <Imake.rules>
+.sp .2v
+#include "./Imakefile"
+.DE
+.LP
+The header block section now additionally determines the name of the
+project-specific platform file
+.I platform .pcf.
+.LP
+The modification is based on the notion of override files.
+Before any of the platform, site, project or rules
+files are included, another related file is
+included which may contain project-specific information.
+Standard versions of these project-specific files
+.I *.pcf , (
+.I site.pdef ,
+.I Project.ptmpl
+and
+.I Imake.prules )
+are present in
+StdConfigDir (to prevent file-inclusion errors) but they are all empty.
+If a given project has special configuration requirements, it may
+supply its own private versions of any of these files in its
+.I config
+directory.
+Since
+.I imake
+will search that directory before StdConfigDir, the standard (empty)
+versions will be overridden.
+The project does not have to actually replace them.
+.LP
+.B "Example 1:"
+At the one extreme, when a project has
+no special project-specific configuration requirements (no
+.I config
+directory, or an empty one),
+only the files in StdConfigDir are used to create makefiles.
+Since the default project-specific files are empty, the new
+architecture of
+.I Imake.tmpl
+is functionally equivalent to the old.
+At the other extreme, a project can replace
+.I all
+the configuration files; nothing from StdConfigDir is used then.
+.LP
+.B "Example 2:"
+The standard
+.I site.def
+file might be used by the system administrator to set the value of
+BinDir to the directory in which programs are installed.
+A project might want them installed somewhere else; this could be done
+by defining BinDir in the project-specific site file
+.I site.pdef
+to override the value in
+.I site.def .
+.LP
+.B "Example 3:"
+Override files may also be used to extend the standard configuration
+by defining symbols not appearing at all in the standard files.
+For instance, if some programs were to be installed in the standard
+BinDir, but others were to be installed in a private directory, a
+symbol such as ProjBinDir could be defined for the latter purpose in
+.I Project.ptmpl .
+.LP
+One bothersome thing about this architecture is the naming of
+.I Project.tmpl
+and
+.I Project.ptmpl .
+If
+.I Project.tmpl
+contains ``project-specific'' information, then what does
+.I Project.ptmpl
+contain?
+``Project-project-specific'' information?
+Ugh.
+I prefer to consider
+.I Project.tmpl
+to contain ``standard'' (i.e., best-guess) project configuration
+parameters, and
+.I Project.ptmpl
+to contain the parameters which actually are specific to a given project.
+.LP
+The disadvantages of this architecture are obvious:
+.IP \(bu
+.I Imake.tmpl
+is somewhat more complex.
+.IP \(bu
+StdConfigDir must be populated with the additional
+.I *.pcf ,
+.I site.pdef ,
+.I Project.ptmpl
+and
+.I Imake.prules
+files (although this is easy since they are all empty).
+.LP
+The advantages are:
+.IP \(bu
+Configuration information is centralized, but flexibility is maintained.
+Projects may
+override definitions in the the standard configuration files
+without replacing those files directly, and multiple projects may use
+files in StdConfigDir cooperatively without interfering with each other.
+.IP \(bu
+Override files minimize the need for individual
+projects to modify the standard non-project specific files
+.I Imake.tmpl , (
+.I *.cf ,
+.I site.def ,
+.I Project.tmpl
+and
+.I Imake.rules )
+directly.
+The philosophy underlying the architecture is that the standard files
+describe a common ``baseline'' configuration, and
+individual projects need specify configuration information (using
+private
+.I *.pcf ,
+.I site.pdef ,
+.I Project.ptmpl
+and
+.I Imake.prules
+files) only to the extent that they
+.I differ
+from the standard.
+.IP \(bu
+When improvements are made to the standard files, the changes are
+immediately available to any project using them via a normal
+configuration step, i.e., ``make Makefile;make Makefiles''.
+(Of course, it also becomes possible to break a lot of projects if an
+erroneous change is made.)
+.IP \(bu
+Overall, fewer files need to be maintained, and less space is used.
+.NH 2
+Other Changes
+.LP
+.I xmkmf
+is used to bootstrap makefiles from imakefiles.
+To accommodate the above scheme, it was
+modified from the version distributed with X11R4 to search the project's
+.I config
+directory, then the standard configuration directory
+(i.e., ProjConfigDir then StdConfigDir, not just StdConfigDir).
+.LP
+The definition of the makefile variable IMAKE_CMD in the configuration
+files was also changed:
+.LP
+.DS
+Old (from X11R4):
+#ifdef UseInstalled
+ IRULESRC = $(CONFIGDIR)
+ IMAKE_CMD = $(IMAKE) -DUseInstalled \e
+ -I$(IRULESRC) \e
+ $(IMAKE_DEFINES)
+#else
+ IRULESRC = $(CONFIGSRC)
+ IMAKE_CMD = $(NEWTOP)$(IMAKE) \e
+ -I$(NEWTOP)$(IRULESRC) \e
+ $(IMAKE_DEFINES)
+#endif
+.DE
+.\" allow page break here if necessary...
+.DS
+New:
+#ifdef UseInstalled
+ IMAKE_CMD = $(IMAKE) -DUseInstalled \e
+ -I$(NEWTOP)$(PROJCONFIGDIR) \e
+ -I$(STDCONFIGDIR) \e
+ $(IMAKE_DEFINES)
+#else
+ IMAKE_CMD = $(NEWTOP)$(IMAKE) \e
+ -I$(NEWTOP)$(PROJCONFIGDIR) \e
+ -I$(STDCONFIGDIR) \e
+ $(IMAKE_DEFINES)
+#endif
+.DE
+.LP
+The old rule determines whether to use versions of
+.I imake
+(and
+.I makedepend )
+already installed in public directories or
+build them in the source tree based on whether UseInstalled is defined or not.
+That symbol also determines where to look for configuration files and
+defines the value of IRULESRC accordingly.
+If UseInstalled is undefined, searches look in CONFIGSRC, the project's
+.I config
+directory, otherwise in CONFIGDIR, the standard configuration directory.
+.LP
+This behavior is unsuitable for the purposes described here, since both of
+those directories should be searched, if they exist.
+The new rule makes UseInstalled relevant only for determining where
+to find (and possibly build)
+.I imake
+and
+.I makedepend ,
+not where to look for configuration files.
+.NH
+Test of Implementation
+.LP
+After making the changes described above, a flight test was arranged.
+Nine projects developed under six different logins were converted to use
+the standard files.
+Projects supplied override files where necessary.
+These projects were all initially developed using configuration files
+that bore a
+fairly strong relationship to the standard set, so it was expected
+that conversion would not be unbearably odious.
+The degree of relationship broke down as follows:
+.IP \(bu
+Two projects used configuration files that were identical (or nearly
+so) to the standards.
+Each of these projects, unlike the other seven, comprised only a
+single source directory.
+As expected, conversion was completely trivial, once the top-level
+.I Makefile
+was rebuilt with
+.I xmkmf .
+.IP \(bu
+Four projects required additional project-specific specification
+beyond the standard configuration
+(special include file directories, link libraries,
+installation directories, etc.).
+These usually required only
+.I site.pdef
+and
+.I Project.tmpl
+files in their local
+.I config
+directories.
+One project required a
+.I platform.pcf
+file.
+Project owner and group names (used for install operations) were moved
+out of
+.I site.def
+files into
+.I site.pdef .
+.IP \(bu
+Three projects diverged from the standard files fairly significantly,
+because although their configuration files were initially set up from
+files similar to the standards, less effort had been exerted to keep
+them in sync as project development progressed.
+Besides the changes made to the projects described in the previous
+paragraph, there were additional special commands for compilation, special
+.I Imakefile
+rules, etc.
+Nevertheless, conversion proceeded smoothly and without incident.
+.LP
+One thing I had done in the original
+.I Project.tmpl
+files was to define certain
+makefile variables directly (e.g., ``INCLUDESRC=$(TOP)/h''), rather
+than by using a previously #define'd
+.I cpp
+symbol (e.g., ``INCLUDESRC=IncludeSrc'', where IncludeSrc is #define'd
+within a #ifndef/#endif block).
+This was a short-cut, that works in a non-shared environment but
+needed to be fixed to work in a shared environment.
+A default value of IncludeSrc needs to be placed in
+.I Project.tmpl ,
+and individual projects redefine that symbol as necessary in
+.I Project.ptmpl .
+.LP
+It was necessary to place a number of
+.I cpp
+symbol definitions in
+.I Project.tmpl
+within #ifndef/#endif blocks, since they became liable to being
+overridden in
+.I Project.ptmpl .
+.LP
+In the top-level imakefiles for the multiple source directory
+projects, the ``make World'' rules had to be adjusted to account for
+whether UseInstalled is defined or not.
+If so, the build process does not need to try to build
+.I imake
+and
+.I makedepend
+in the project source tree.
+(That would be a mistake since the source for those programs would not
+necessarily be present.)
+.LP
+Overall, conversion was simple and straightforward.
+I judged the conversion odiousness coefficient acceptably low.
+.NH
+Another Problem\*-Project Groups
+.LP
+The mechanism described above allows a group of similarly-configured
+projects to share configuration files and selectively extend or
+override them as necessary.
+This provides a solution to the original problem (how to avoid
+maintaining multiple full sets of files while maintaining flexibility),
+but leads to another.
+Suppose that instead of a group of projects, there exist several
+groups of projects, such that projects within a group are similar, but
+differences between groups are quite large.
+This can happen, for instance, if projects designed and developed at one
+site under certain conventions are installed at another
+site where different conventions are used.
+.LP
+The difficulty here is that there are two sets of ``standard'' configuration
+files, and they cannot both be installed in the same well-known
+location.
+This problem can be overcome quite simply.
+Instead of using StdConfigDir as the single well-known location in which
+the standards are installed, define StdConfigPath to be that
+directory, and use it as the root of a set of
+subdirectories, each of which corresponds to a project group.
+Each group's standard configuration files are installed in the appropriate
+directory, and StdConfigDir for a given project group
+will be defined as that directory (e.g., StdConfigPath/\fIabc\fR for
+project \fIabc\fR).
+.LP
+To allow
+.I xmkmf
+to be used for bootstrapping,
+it was modified slightly again to select
+one of the subdirectories as the hardwired-in default, but allow
+another to be selected through a
+.B \-C
+option.
+For convenience, the argument following
+.B \-C
+may be absolute or relative.
+If absolute, it is used unchanged.
+If relative, StdConfigDir is prepended.
+.LP
+This modification makes
+.I xmkmf
+incompatible with the version distributed with X11R4, which is a
+problem for sites using that version.
+Assuming X configuration files are installed in
+.I /usr/lib/X11/config
+and the value of StdConfigPath is
+.I /usr/lib/config ,
+this incompatibility can be obviated as follows:
+.LP
+.DS
+mkdir /usr/lib/config
+cd /usr/lib/config
+ln -s /usr/lib/X11/config X11
+ln -s X11 default
+.DE
+.LP
+For sites without symbolic links, the files in
+.I /usr/lib/X11/config
+can be copied into
+.I /usr/lib/config/X11 ,
+and
+.I xmkmf
+can be hacked to use
+.I /usr/lib/config/X11
+instead of
+.I /usr/lib/config/default
+as the default.
+Ugly, but workable.
+(Also known as ``crude, but effective''.)
+.LP
+With these conventions,
+projects within groups can share redundant information, as before, and
+project groups can coexist peacefully.
+.LP
+The nine projects previously converted were tested against these
+additional modifications.
+They required only ``xmkmf;make Makefile;make Makefiles'' to properly
+reset the configuration information in the makefiles.
+.NH
+Distribution of Projects
+.LP
+The mechanism described in this document appears to solve
+the problem of reusing
+configuration files while allowing for extension and override within
+individual projects.
+However, when a project is packaged for distribution, it's very little
+use to include only those configuration files which are unique to the
+project, if the receiving site doesn't have the standard files.
+Several alternatives come to mind.
+.IP \(bu
+Provide the standards as a separate distribution, along with the
+sources to
+.I imake
+and
+.I makedepend .
+This is perhaps inconvenient for the receiver, as it is another
+distribution that needs to be retrieved.
+.IP \(bu
+Copy all the standard files into the project's
+.I config
+directory and distribute along with the project.
+One has to be careful when doing the copying not to destroy the
+project's override files,
+the resulting distribution size is larger, and
+distributing the standards is unnecessary if receiving site
+has them already.
+Also, it is not clear which files are actually unique to the project
+when this is done.
+.IP \(bu
+Keep the project's unique configuration files in
+.I config
+(where they are normally anyway), and copies of the standard files in
+.I config-std .
+If the receiver has the latter already, they can be jettisoned easily,
+otherwise installed in the project's StdConfigDir.
+.LP
+It is unclear whether any of these has any compelling advantage over
+the others.
+.NH
+Beginning New Projects
+.LP
+If a new project has special configuration requirements, a file
+.I README.{project-name}
+should be created in
+.I config
+explaining what they are.
+.NH 2
+Define UseInstalled, or Not?
+.LP
+If a project wants to use the installed versions of
+.I imake
+and
+.I makedepend ,
+the initial makefile should be created from the the imakefile by executing
+.I xmkmf
+with no arguments (or just
+.B \-C
+.I configdir )
+in the project top-level directory.
+This will cause -DUseInstalled to be passed to
+.I imake
+which will in turn cause the version of IMAKE_CMD that
+includes -DUseInstalled to be selected from the configuration files.
+Thus -DUseInstalled will propagate nicely through all future ``make Makefile''
+operations.
+.LP
+If
+.I imake
+and
+.I makedepend
+are to be built in the project source tree, UseInstalled should not be defined,
+and you must have the source under the project.
+.I imake
+source is in
+.I config
+and
+.I makedepend
+source is in
+.I util/makedepend
+or
+.I util/scripts ,
+depending on the definition of UseCCMakeDepend.
+Execute ``xmkmf \fB.\fR'' (note the \fB.\fR!) in the project top-level
+directory.
+This will run
+.I imake
+without -DUseInstalled, and the proper IMAKE_CMD in the config
+files will be selected.
+.LP
+One problematic aspect of
+.I xmkmf
+is that it really should always pass -DUseInstalled, since it assumes there
+is an installed version of
+.I imake
+anyway (it doesn't specify a path to it).
+But then the problem becomes how to turn UseInstalled off later?
+You can't run ``make Makefile'' because the version of IMAKE_CMD that
+uses -DUseInstalled has already been selected.
+.NH
+Distribution and Availability
+.LP
+The standard WRPRC configuration files are (or will be soon)
+available for anonymous
+.I ftp
+access in the
+.I ~ftp/pub/imake-stuff
+directory, in file
+.I config-WRPRC.shar.Z
+on host
+.I indri.primate.wisc.edu
+(Internet address 128.104.230.11).
+These files illustrate the concepts discussed in this document.
+.LP
+This distribution also includes parts of the X11R4
+.I mit/util
+source tree (where
+.I makedepend
+and
+.I xmkmf
+are found) as well as
+.I msub ,
+a locally-developed utility for yanking the values of
+variables directly from makefiles to produce target files from templates.
+.LP
+The X11R4 configuration files are in the same directory, in
+.I config-X11R4.shar.Z .