diff options
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.ms | 691 |
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 . |