
	     Imake Configuration Guide for InterViews 2.5

0. Abstract

This document describes the various parameters that configure how your
Makefiles will build this release of InterViews.  Anyone who builds
InterViews 2.5 for the first time, ports InterViews to a new platform,
or wants to change the default installation should read it.

We adapted this document from the X Window System Imake Configuration
Guide, Release 3 (./util/imake.includes/README in the X11R3
distribution).  We wish to express our gratitude to Jim Fulton
(jim@expo.lcs.mit.edu) for providing the platform-specific .cf files,
the model template and rules files which we adapted for InterViews,
and improvements to imake and makedepend.

1.  Introduction

Because Makefiles are inherently unportable, InterViews uses a tool
called imake to generate platform-specific Makefiles from machine-
independent descriptions called Imakefiles.  Imake makes very heavy
use of the C preprocessor for both constants and macros which can make
writing Imakefiles somewhat tricky to master.  However, imake is
invaluable for making InterViews easy to build on a wide variety of
machines.

Imakefiles usually contain definitions of make variables plus one or
more macro invocations to build the desired parts of the Makefile.
Imake processes a template file called IVImake.tmpl which contains
definitions that are common to all Makefiles.  The template file
includes an architecture definition file (Arch.c), a platform-
specific .cf file, a site-specific defaults file (IVsite.def), and a
project configuration file (Project.tmpl).  The platform-specific .cf
file overrides default values for some platform-dependent build
parameters in order to set special compiler flags, etc.  IVsite.def
overrides default values for some build parameters that you want to
set across all platforms at your site.  Project.tmpl defines default
values for the most important build parameters used by InterViews.
IVImake.tmpl then includes a rules file (Imake.rules) and the
Imakefile being processed (INCLUDE_IMAKEFILE).  Imake.rules defines
macros used by IVImake.tmpl and the Imakefile while the Imakefile
defines make variables and rules using macros.  Finally, IVImake.tmpl
appends a set of common rules to the bottom of the Makefile.

2.  Platform type

The first configuration file IVImake.tmpl includes, Arch.c, contains a
series of conditional blocks for setting the platform type.  The
conditional blocks require that cpp define an unique preprocessor
symbol in order to identify the platform type.  If you have a machine
whose cpp does not define such a symbol or you have to add support for
another platform, follow the instructions in Arch.c.

Each conditional block defines several symbol names representing the
machine being configured:

	#define PLATFORMArchitecture
	#define MachineDep CPU
	#define machinedep cpu
	#define MacroIncludeFile "PLATFORM.cf"
	#define MacroFile PLATFORM.cf

where PLATFORM is the type of the system being configured (Sun, Hp,
etc.) and CPU is the type of the machine's hardware (SUN3, SUN4,
HP300, etc.)  Project.tmpl uses MachineDep to define the make variable
M which it uses in the libraries' pathnames.  You can use machinedep
(which defines a lower-case string) to generate filenames in your
Imakefiles.  IVImake.tmpl uses MacroIncludeFile to include the .cf
file for the platform and MacroFile to define a make variable.  You
can use PLATFORMArchitecture in Imakefiles to obtain platform-specific
rules.  The conditional block undefines the unique symbol that was
used to select it to prevent Imakefiles from using machine-dependent
rules as opposed to platform-dependent rules (some platforms run on
multiple machines).

3.  Build parameters

Imake handles differences between operating systems by using
platform-specific .cf files to set various build parameters.  The
easiest way to create a new file is to look at some of the other .cf
files for machines that might be similar to yours.  Your .cf file must
set at a minimum the correct operating system name and version numbers
in the build parameters OSName, OSMajorVersion, and OSMinorVersion.
Even if you don't need to write a new .cf file, you must inspect the
.cf file and correct the major or minor version numbers for your
operating system if necessary.

You may override the default value for any parameter by including an
appropriate definition in the .cf file.  You can also override the
default value in IVsite.def (more on that later).  IVImake.tmpl
defines default values for these parameters:

    SystemV			is System V based instead of BSD?  YES/NO
    UnalignedReferencesAllowed	arbitrary memory references okay?  YES/NO
    ExecableScripts		can kernel exec() handle #! ? YES/NO
    ConstructMFLAGS		set MFLAGS from MAKEFLAGS?  YES/NO
    HasSockets			does system have IPC sockets?  YES/NO
    HasVFork			does system have vfork()? YES/NO

    BourneShell			full pathname of Bourne shell
    OptimizedCDebugFlags	flags to pass to compiler for optimized code
    DebuggableCDebugFlags	flags to pass to compiler for debuggable code
    NoOpCDebugFlags		flags to pass to compiler to do neither
    DefaultCDebugFlags		default debug vs. optimize flags 
    LibraryCDebugFlags		debug vs. optimize flags for libraries
    InstBinFlags		install flags for programs
    InstUidFlags		install flags for setuid programs
    InstLibFlags		install flags for libraries
    InstIncFlags		install flags for header files
    InstManFlags		install flags for man pages
    InstDatFlags		install flags for data files
    InstKmemFlags		install flags for reading /dev/kmem

    ArCmd			command to generate object libraries
    BootstrapCFlags		special flags that are needed to build imake
    BootstrapCpuCmd		command to determine this machine's cpu type
    CcCmd			command to compile a C file
    AsCmd			command to assemble code into object file
    CompressCmd			command to compress(1) a file
    CppCmd			command to run cpp without defines
    PreProcessCmd		command to run cpp with defines used by CcCmd
    DependCmd			command to generate Makefile dependencies
    GenclassCmd			command to instantiate generic classes
    ImakeCmd			command to generate Makefiles
    InstallCmd			command to install a program (with BSD options)
    LdCmd			command to link a C program
    LintCmd			command to lint a C file
    LintLibFlag			flag to make lint generate a lint library
    LintOpts			flags to pass to lint
    CpCmd			command to copy a file
    LnCmd			command to generate links
    MakeCmd			command to run make
    MkdirhierCmd		command to create directory hierarchies
    MvCmd			command to move (rename) a file
    RanlibCmd			command to run after building a library
    RanlibInstFlags		flag to just touch the archive explicitly
    RmCmd			command to remove a file
    StandardCppDefines		C preprocessor flags subset of StandardDefines
    StandardDefines		C compiler flags to be used on every compile;
				put special options increasing table sizes here
    ExtraLibraries		libraries to put at the end of link lines;
				put the names of any emulation libraries here
    ExtraLoadFlags		load flags to put at the end of link lines
    TagsCmd			command to build a tags file
    TOPDIR			root of source tree; usually set to "."

Project.tmpl defines default values for additional parameters, some of
which are more appropriately set in IVsite.def for all platforms than
in a .cf file, however:

    WindowSystem		window system to build InterViews for? X10/X11
    CompileInMachineDepSubdir	put .o files in subdirectory? YES/NO
    StripProgram		strip programs when installing them? YES/NO
    RemoveAfterInstall		remove programs after installing them?  YES/NO
    InstallPlatformCfFiles	install platform .cf files? YES/NO

    CplusplusCcCmd		command to compile a C++ file
    CplusplusLdCmd		command to link a C++ program
    DependCFlags		flags to pass to makedepend; put flags silently
				passed to cpp by CplusplusCcCmd here
    GenDir			where template-generated files are wrt .o files
    SrcDir			where C or C++ files are wrt .o files

    InstallRelative		install InterViews relative to $(TOP)? YES/NO
    DestDir			root of installation, should be blank
    BinDir			directory to contain window system clients
    RelativeBinDir		same, but relative to $(TOP)
    LocalBinDir			directory to contain window sys-indep programs
    RelativeLocalBinDir		same, but relative to $(TOP)
    IncRoot			directory to contain header files' directory
    RelativeIncRoot		same, but relative to $(TOP)
    UsrLibDir			directory to contain libraries
    RelativeUsrLibDir		same, but relative to $(TOP)

    LibDir			directory to contain config directory
    ConfigDir			directory to contain platform .cf files
    IVConfigDir			directory to contain InterViews config files
    ManDirectoryRoot		root of man page tree
    ManPath			root of manual page tree
    ManSourcePath		name of man source directories to append to
    ManSuffix			suffix for program man pages
    LibManSuffix		suffix for library man pages
    ManDir			directory to contain program man pages
    LibmanDir			directory to contain library man pages

    PrintCmd			command to send a file to the printer
    TroffCmd			command to format a nroff/troff file on stdout

4.  Site-specific defaults file

You can use IVsite.def to set build parameters across all platforms at
your site.  You should nest #defines inside #ifndef..#endif pairs so
platform-specific .cf files still can override IVsite.def.

We distribute an IVsite.def that sets InstallPlatformCfFiles YES since
most people have not yet installed any platform .cf files in
/usr/lib/X11/config.  We plan to use the same platform .cf files that
X11R4 will use so we will set InstallPlatformCfFiles NO when X11R4
comes out.

The default values for our build parameters ensure that you can play
with InterViews entirely in place: both ``make bootstrap'' and ``make
install'' will use only pathnames relative to $(TOP).  ``make
install.config'' and ``make install.man'' still use absolute pathnames
since there is no purpose in installing them in another place relative
to $(TOP).  If you use ivmkmf to generate a Makefile from an Imakefile
outside of the source tree, the Makefile automatically uses absolute
paths instead of relative pathnames for its installation directories.
You can install InterViews without setting InstallRelative NO in your
IVsite.def if you create symbolic links from your system area to
InterViews or replace $(TOP)/bin, $(TOP)/include, and $(TOP)/lib with
symbolic links to your system area.  The only reason you would set
InstallRelative NO would be if you wanted to install InterViews
directly into your system area.

5.  Imakefiles

Individual Imakefiles may use any of the macros defined in
Imake.rules.  Some of these rules use make variables that the
Imakefile usually must define itself:

    CC			set to CplusplusCcCmd, but you can override with CcCmd
    CDEBUGFLAGS		set to NoOpCDebugFlags, but you can override it
    INCLUDES		set for C++, but you can override it for C
    SRCS		files to be read by makedepend; $(SRC)//**/*.c fine
    OBJS		.o files to be loaded together
    LOCAL_LIBRARIES	lib*.a files to be linked with: $(LIBINTERVIEWS), etc.
    SYS_LIBRARIES	system libraries to be linked; usually -l$X -lm

The easiest way to write an Imakefile is to find another one that does
the same thing and modify it.

6. Generating Makefiles from Imakefiles

We distribute InterViews with Makefiles already generated throughout
the source tree.  ``make World'' automatically regenerates these
Makefiles for your platform.  If you ever need to regenerate a
particular Makefile again, say because you edited the Imakefile or you
edited one of the configuration files, just say ``make Makefile''.  If
you want to regenerate the Makefiles in that directory's
subdirectories as well, say ``make Makefiles''.  Since regenerating a
Makefile throws away its automatically generated dependencies, you
should always follow "make Makefile" or "make Makefiles" with "make
depend".  You can safely skip "make depend" only if you will be
building in a clean directory tree without any .o files; otherwise the
Makefile may fail to update some .o files.

If you install the InterViews configuration files, you'll find it very
easy to use Imakefiles outside of the InterViews source tree as well
as inside it.  You use the shell script ivmkmf when you need to
generate a Makefile for the first time.  It takes no options; you just
say ``ivmkmf''.  Ivmkmf generates a Makefile that will use your system
area for everything it would have used in the InterViews source tree.
For ivmkmf to work, the header files, configuration files, and
libraries must be installed in the system area and ivmkmf, imake,
makedepend, and possibly genclass (used by src/libInterViews but not
by any program in src/bin) must lie in one of the directories in your
PATH.  Once you've generated a Makefile with ivmkmf the first time,
you can say ``make Makefile'' or ``make Makefiles'' from then on
exactly as if you were still inside the InterViews source tree.  Even
though ``make install'' uses relative pathnames inside the source
tree, it will automatically use absolute pathnames outside the source
tree so you can install your program as well as compile it.
