Appendix B
Installing Configuration Software

Table of Contents

• Distribution Layout
• Finding out What You Already Have
• Preparing To Install the Distribution
  • Installing with Limited Privileges
• Building the Distribution--Quick Instructions
• Installing the Software
• Building the Distribution--Detailed Instructions
  • Writing the Vendor Block
  • Writing the Vendor File
  • Configuring imake
    • imakemdep.h--Part 1 (for ccimake)
    • imakemdep.h--Part 2 (for imake)
    • imakemdep.h--Part 3 (for makedepend)
  • Building imake
  • Building the Rest of the Distribution

[ This document consists of the text of Appendix B of Software Portability with imake, by Paul DuBois. Copyright (c) 1996 O'Reilly and Associates, Inc. All rights reserved. Permission is granted to copy this document for personal use only. This copyright notice must be retained in all copies. ]

This appendix describes how to build and install imake and related configuration software if you do not already have it on your machine. The software (referred to here as "the distribution") is available as itools.tar.gz or itools.tar.Z from the archive sites listed in Appendix A, Obtaining Configuration Software.

The essential programs you will need for working your way through this book are:

imake

Makefile generator

xmkmf

Bootstrapper that uses the X11 configuration files

imboot

General purpose bootstrapper

makedepend

Header file dependency generator

mkdirhier

Directory creation tool

Some of these may be new to you, particularly if you are looking at this appendix without reading the rest of the book first. imake, of course, is discussed throughout the book. xmkmf, makedepend, and mkdirhier are discussed in Chapter 2, A Tour of imake. imboot is discussed in Chapter 10, Coordinating Sets of Configuration Files, and Chapter 15, Designing Extensible Configuration Files.

The distribution also includes the X11 configuration files and some miscellaneous programs like msub and imdent.

Most of the distribution is based on the current release of X11 (X11R6.1, public patch 1 at the time of writing), but some programs are not part of the standard X11 distribution, e.g., imboot, msub, and imdent.

Distribution Layout

   % cd itools

cf

The X11 configuration files.

imake

The source for imake.

makedepend

Source for the C version of makedepend. Several programs go by this name; the version included here is intended for use with imake and is written by Todd Brunhoff, imake's author.

util

Source for xmkmf, mkdirhier, bsdinst, install.sh, lndir, mkshadow, and some other miscellaneous scripts, such as which and a script version of makedepend (if you can't get the C version to work).

extras

Source for imboot, msub, and imdent.

misc

Miscellaneous bits and pieces: portions of the X11 Release Notes that pertain to imake; any errors that have been found in this appendix since publication; troubleshooting information too detailed or specialized to be included in this appendix; reader-contributed notes about porting imake to systems not covered by the distribution, etc.

Finding out What You Already Have

To find programs, use the which command. It will tell you either where a program is located, or, if it couldn't find it, which directories it looked in (usually the directories named in your PATH variable). In the following example, which tells you that imake is installed in /usr/local/bin:

   % which imake
   /usr/local/bin/imake

   % which imake
   no imake in . /usr/local/bin /usr/bin/X11 /usr/ucb /bin /usr/bin

In many instances, if you discover that a program included in the distribution is already installed, you don't need to install it. However, you should make exceptions when you have out-of-date or broken versions of programs:

• Use the X11R6.1 version of imake if you have an earlier version.
  
• The current versions of makedepend and xmkmf each understand a -a option. Older versions (distributed prior to X11R5) do not. The current version of makedepend also has improved parsing of cpp preprocessor conditional directives, which results in more accurate results than with earlier versions. Install the versions in the distribution to update your system.
  
• The versions of imake and xmkmf distributed with Sun systems are nonstandard and modified specially for use with OpenWindows. If the pathnames for your versions of imake and xmkmf have openwin in them (e.g., /usr/openwin/bin/imake), you may be better off installing the standard X11 versions because the OpenWindows versions do not work very well to configure non-OpenWindows software. See Appendix J, Using imake with OpenWindows, for further discussion of this issue.
  

Preparing To Install the Distribution

Suppose you want to install programs in /usr/local/bin and the X11 configuration files in /var/X11R6.1/lib/X11/config, and that you want to use /var/lib/config for the imboot configuration root. Make the changes as follows:

• To change the program installation directory, add the following to the second half of config/cf/site.def:
  

     #ifndef BinDir
     #define BinDir /usr/local/bin
     #endif
  

• To change the X11 configuration file installation directory, add the following to the second half of config/cf/site.def:
  

     #ifndef ConfigDir
     #define ConfigDir /var/X11R6.1/lib/X11/config
     #endif
  

• To change the configuration root directory used by imboot, edit this line in config/extras/Imakefile:
  

     CONFIGROOTDIR = /usr/local/lib/config
  

  Change it to this:
  

     CONFIGROOTDIR = /var/lib/config
  

Installing with Limited Privileges

Building the Distribution--Quick Instructions

Change into the config/cf directory and look around; you'll see the configuration files listed below:

   % cd config/cf
   % ls
   Amoeba.cf     Server.tmpl   hp.cf         necLib.rules  site.def
   DGUX.cf       Threads.tmpl  hpLib.rules   necLib.tmpl   site.sample
   FreeBSD.cf    Win32.cf      hpLib.tmpl    noop.rules    sony.cf
   Imake.cf      Win32.rules   ibm.cf        oldlib.rules  sun.cf
   Imake.rules   WinLib.tmpl   ibmLib.rules  osf1.cf       sunLib.rules
   Imake.tmpl    apollo.cf     ibmLib.tmpl   osfLib.rules  sunLib.tmpl
   Imakefile     bsd.cf        linux.cf      osfLib.tmpl   sv4Lib.rules
   Library.tmpl  bsdLib.rules  lnxLib.rules  pegasus.cf    sv4Lib.tmpl
   Makefile      bsdLib.tmpl   lnxLib.tmpl   sco.cf        svr4.cf
   Mips.cf       bsdi.cf       luna.cf       scoLib.rules  ultrix.cf
   NetBSD.cf     convex.cf     macII.cf      sequent.cf    usl.cf
   Oki.cf        cray.cf       moto.cf       sgi.cf        x386.cf
   Project.tmpl  fujitsu.cf    ncr.cf        sgiLib.rules  xf86.rules
   README        generic.cf    nec.cf        sgiLib.tmpl   xfree86.cf

Find the definitions of OSMajorVersion, OSMinorVersion, and OSTeenyVersion in your vendor file. They represent the major, minor, and subminor release numbers for your operating system. Check that they are correct, and change them if they are not. Suppose linux.cf specifies Linux 1.2.11:

   #ifndef OSMajorVersion
   #define OSMajorVersion  1
   #endif
   #ifndef OSMinorVersion
   #define OSMinorVersion  2
   #endif
   #ifndef OSTeenyVersion
   #define OSTeenyVersion  11
   #endif

   #ifndef OSTeenyVersion
   #define OSTeenyVersion  8
   #endif

Look over site.def to see whether you want to change anything. In particular, to use gcc (version 2.x.x) as your C compiler, define HasGcc2 as YES by uncommenting the #define that is already there.

The distribution should build on many systems at this point. In the distribution root (the itools directory) execute the following command:

   % make World >& world.log

   $ make World > world.log 2>&1

   nmake World.Win32 > world.log

In the distribution root, execute the following command, replacing flags with the appropriate bootstrap flags for your system:

   % make World BOOTSTRAPCFLAGS="flags" >& world.log

   % make World BOOTSTRAPCFLAGS="-Dsun -DSVR4" >& world.log
   % make World BOOTSTRAPCFLAGS="-Dhpux" >& world.log

Installing the Software

   % make install

• In cf, install the X11 configuration files:
  

     % make install.cffiles
  

• In imake, install imake:
  

     % make install.imake
  

  Do not install ccimake; it is only needed for compiling imake.
  
• In makedepend, if you built the compiled version of makedepend (the default on most systems), install it:
  

     % make install.makedepend
  

  If you did not build the compiled version, the script version will be installed from the util directory.
  
• In util, install various scripts:
  

     % make install.xmkmf
     % make install.mkdirhier
  

  If you have a System V version of install instead of a BSD-compatible one, the distribution contains two scripts bsdinst and install.sh that you can use instead. Some systems use one, others use the other. You can tell which one to install by watching what commands make has been executing as you've been installing the software above:
  

     % make install.bsdinst  (or)
     % make install.install.sh
  

  If you built the script version of makedepend, install it:
  

     % make install.makedepend
  

• In extras, install imboot, msub, and imdent:
  

     % make install.imboot
     % make install.msub
     % make install.imdent
  

Building the Distribution--Detailed Instructions

If you're porting imake to a system on which it's not currently supported, use one of the following locators to see if there's any information for your type of system:

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

When imake runs, it invokes cpp to process the configuration files. Default values for most configuration parameters are defined in Imake.tmpl, Project.tmpl, etc. Also included among the configuration files are many vendor files, each of which contains parameter values that override any defaults that are inappropriate for a particular vendor's systems. Since there are several different vendor files from which to choose, cpp has to figure out which is the right one for the machine you are actually using. cpp does this by checking various symbols known to identify different types of systems. The one that is defined determines the current system type.

The symbol that identifies your system can come from a couple of sources. Some vendors ship a cpp that predefines a symbol unique to that vendor's systems. For instance, on Ultrix, cpp predefines ultrix, which makes it easy to ascertain the system type:

   #ifdef ultrix
     /* it's Ultrix, all right... */
   #endif

It might even be that your preprocessor predefines no useful system-indicating symbols at all. ANSI C takes a dim view of most predefined symbols, so ANSI cpps tend to provide few symbols that can be used to determine the system type. Here, too, you invent an identifier symbol and make sure imake defines it so cpp can determine which vendor file to use.

Thus, to port imake to your machine, you must satisfy three requirements:

• The configuration files must contain a block of code that "recognizes" your system type and selects the correct vendor file. The block is called the vendor block and the system-identifier symbol that activates it is called the trigger symbol. In the X11 configuration files, the vendor blocks are located in the Imake.cf file.
  
• You need a vendor file that describes your system and contains any information needed to override default values of parameters specified in the other configuration files.
  
• imake must make sure the trigger symbol is defined when cpp starts up if cpp doesn't predefine it.
  

Writing the Vendor Block

   #ifdef linux
   # define MacroIncludeFile <linux.cf>
   # define MacroFile linux.cf
   # undef linux
   # define LinuxArchitecture
   # define i386Architecture
   # undef i386
   #endif /* linux */

   #ifdef sun
   # define MacroIncludeFile <sun.cf>
   # define MacroFile sun.cf
   # ifdef SVR4
   #  undef SVR4
   #  define SVR4Architecture
   # endif
   # ifdef sparc
   #  undef sparc
   # define SparcArchitecture
   # endif
   # ifdef mc68000
   #  undef mc68000
   # define Sun3Architecture
   # endif
   # ifdef i386
   #  undef i386
   #  define i386Architecture
   # endif
   # undef sun
   # define SunArchitecture
   #endif /* sun */

• It defines the name of the vendor file. The name is defined two different ways because it is used in different contexts later.
  
• It undefines the trigger symbol and any other OS- or processor-specific symbols that cpp might have predefined.
  
• It defines a vendor-specific OS architecture symbol. If the OS runs on more than one type of processor, a processor-specific architecture symbol is usually defined, too (e.g., SparcArchitecture, Sun3Architecture, and i386Architecture in the SunOS vendor block). Architecture symbols are useful in Imakefiles when it is necessary to know the OS or hardware type.
  

   #ifdef brandxyz
   # define MacroIncludeFile <brandxyz.cf>
   # define MacroFile brandxyz.cf
   # undef brandxyz
   # define BrandXYZArchitecture
   #endif

   #define BootstrapCFlags -Dbrandxyz

Writing the Vendor File

There are a few symbols you must define in the vendor file:

• Define the major and minor release numbers for your operating system, and, if necessary, the subminor number. For instance, if your OS is at release 3.4.1, write this:
  

     #ifndef OSMajorVersion
     #define OSMajorVersion 3
     #endif
     #ifndef OSMinorVersion
     #define OSMinorVersion 4
     #endif
     #ifndef OSTeenyVersion
     #define OSTeenyVersion 1
     #endif
  

  The OS numbers are used when you need to select parameter values that vary for different releases of the system. Define them even if you don't use them anywhere else in the vendor file, because Imakefile writers sometimes need to know the release numbers.
  
• If your system is based on System V Release 2 or 3, define SystemV:
  

     #define SystemV YES
  

  If your system is based on System V Release 4, define SystemV4:
  

     #define SystemV4 YES
  

  If your system isn't based on System V, don't define either symbol.
  

To some extent, you find out which defaults to override by trial and error: write a minimal vendor file containing only the symbols described above, then try to build the distribution. If the build fails because a parameter value is incorrect, put the correct value in the vendor file and try again. However, you can minimize trial and error by taking advantage of the experience of those who've gone before you. Existing vendor files serve as a guide to help you figure out what should go in your own vendor file by giving you some idea of the parameters most likely to need special treatment. If any existing files are for operating systems that are similar to yours, your vendor file is likely to be similar to those files.

You now have the vendor block and the vendor file written; all you need is imake.

Configuring imake

Makefile.ini builds imake in two steps because some systems require special flags to ensure proper compilation of all but the most trivial programs. imake isn't especially complex, but it isn't trivial, either, so a small helper program ccimake is compiled first. ccimake is designed to be simple enough to compile with no special treatment, and it figures out any extra flags needed to get imake to compile without error on your platform. Those flags are added to the imake-building command.

To build ccimake and imake, you'll run the following make command (but don't run it yet; we won't be ready for a few pages):

   % make -f Makefile.ini BOOTSTRAPCFLAGS="flags"
   cc -o ccimake -O -I../../include ccimake.c
   cc -c -O -I../../include './ccimake' imake.c
   cc -o imake imake.o

   % make -f Makefile.ini BOOTSTRAPCFLAGS=""

Makefile.ini incorporates the value of BOOTSTRAPCFLAGS into CFLAGS and generates the three commands just shown. The first compiles ccimake. The second invokes ccimake and includes the result in the arguments passed to the command that compiles imake.o. The third produces the imake executable.

The trigger symbol passed in through BOOTSTRAPCFLAGS is used to determine the platform type, but in different ways for each program. The key to understanding trigger use is imakemdep.h in the config/imake directory. This header file is included by the source for ccimake and imake and has one part for each. (It is also used by makedepend and has a third part for that program; we'll get to that shortly.)

The contents of imakemdep.h are organized like this:

   #ifdef CCIMAKE
        /* part 1 (for ccimake) */
   #else
   # ifndef MAKEDEPEND
        /* part 2 (for imake) */
   # else
        /* part 3 (for makedepend) */
   # endif
   #endif

For a new port of imake, you must add the proper information for your system to each part of imakemdep.h. For existing ports you need to verify that the information already there is correct, and fix it if it isn't. The following discussion shows how to set up each part of imakemdep.h.

imakemdep.h--Part 1 (for ccimake)

The first part of imakemdep.h consists of a bunch of #ifdef/#endif blocks. Each of them defines imake_ccflags as a string containing the flags needed to get imake to compile on a particular platform. The proper definition is selected according to the trigger symbol that is defined when ccimake is compiled.

Some flags commonly specified in the definition of imake_ccflags are -DSYSV (System V Release 2 or 3), -DSVR4 (System V Release 4), or -DUSG to indicate USG systems. For instance, if Brand XYZ systems are based on System V Release 4, specify the following:

   #ifdef brandxyz
   #define imake_ccflags "-DSVR4"
   #endif

If no special flags are necessary to compile imake, there need not be any block for your system, and imake_ccflags is given a default definition (currently -O).

If you don't know whether or not ccimake needs to produce any special flags, experiment by trying to compile imake by hand. Once you figure out how to do it, make your knowledge explicit by defining imake_ccflags appropriately in imakemdep.h.

imakemdep.h--Part 2 (for imake)

The second part of imakemdep.h contains four sections. Each of them poses a question:

• Do you have a working dup2() system call? If not, define a work-around for it.
  
• Does your cpp collapse tabs in macro expansions? If not, define FIXUP_CPP_WHITESPACE or your Makefiles will not have tabs where necessary and the @@\ sequences will not be stripped out properly.
  
• Do you want to use the default preprocessor /lib/cpp? If not, choose an alternate by defining DEFAULT_CPP. The value of DEFAULT_CPP must be a full pathname and only a pathname (no arguments). You can specify an alternate preprocessor at imake runtime by setting the IMAKECPP environment variable, but it is better to compile it in using DEFAULT_CPP so imake knows the correct value automatically. This may sound nonportable, and it is. But that's okay, because on the particular machine where you're building imake, you want it to know exactly where cpp is so you don't have to tell it.
  
• Are there arguments you want imake to pass to cpp automatically? This section initializes a string array cpp_argv[] with those arguments. The most important entry is a definition for the trigger symbol used to select the correct vendor block in Imake.tmpl, but other entries may be necessary, too.
  

   #ifdef trigger
     "-Dtrigger",
   #endif

For Brand XYZ systems, add the following entry to cpp_argv[]:

   #ifdef brandxyz
     "-Dbrandxyz",
   #endif

If you need to pass more than one argument to cpp, add the definitions for each argument as separate strings:

   #ifdef brandxyz
     "-Dbrandxyz",
     "-DSVR4",
   #endif

imakemdep.h--Part 3 (for makedepend)

The third part of imakemdep.h applies to the compiled version of makedepend. (This has nothing to do with compiling imake, but since we're talking about imakemdep.h, we might as well cover it here.)

This part of imakemdep.h puts entries in the predefs[] string array based on which of various system- and compiler-related definitions are predefined by cpp. makedepend uses this information to be smart about which header files to pay attention to when it generates header file dependencies. Consider the following C program fragment:

   #ifdef ultrix
   #include "headera.h"
   #else
   #include "headerb.h"
   #endif

For existing ports, you can leave this part of imakemdep.h alone. For a new port, add symbols appropriate for your system if they are not already listed among the predefs[] initializers. First, find the lines that end the predefs[] initialization:

     /* add any additional symbols before this line */
     {NULL, NULL}

   #ifdef sym1
     {"sym1", "1"},
   #endif
   #ifdef sym2
     {"sym2", "1"},
   #endif
     /* add any additional symbols before this line */
     {NULL, NULL}

Building imake

   % make -f Makefile.ini clean
   rm -f ccimake imake.o imake
   rm -f *.CKP *.ln *.BAK *.bak *.o core errs ,* *~ *.a tags TAGS make.log \#*

   % make -f Makefile.ini BOOTSTRAPCFLAGS="flags"

   % make -f Makefile.ini BOOTSTRAPCFLAGS="-Dbrandxyz"
   making imake with BOOTSTRAPCFLAGS=-Dbrandxyz
   cc -o ccimake -Dbrandxyz -O -I../../include ccimake.c
   cc -c -Dbrandxyz -O -I../../include './ccimake' imake.c
   cc -o imake imake.o

   % imake -v -T/dev/null -f/dev/null -s/dev/null
   cpp -I. -Uunix -Dbrandxyz Imakefile.c

   % echo "trigger" | /lib/cpp

Building the Rest of the Distribution

   % make World BOOTSTRAPCFLAGS="flags" >& world.log

If you can build imake but make World still fails, try building the distribution in stages to get an idea of where the problem lies. First, build the Makefiles from the distribution root:

   % ./config/imake/imake -I./config/cf
   % make Makefiles

   % make clean
   % make depend
   % make

If you can't get any of this to work, read misc/Porting to see if it contains any helpful advice.