
			    InterViews 2.5

		      Imake Configuration Guide

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 generic 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 (IVarch.c), a platform-
specific definitions file (*.cf), a local site-specific definitions
file (IVlocal.def), and a project configuration file (IVproj.tmpl).
The *.cf files predefine some platform-dependent build parameters in
order to set special compiler flags, etc.  IVlocal.def predefines some
build parameters that you want to set across all platforms at your
site.  You should modify only these files if you need to change a
parameter.  IVImake.tmpl then includes a rule definitions file
(IVrules.def) and the Imakefile being processed (INCLUDE_IMAKEFILE).
IVrules.def defines rules in the form of macros.  The Imakefile
defines make variables and uses some of the rules provided by
IVrules.def.  Finally, IVImake.tmpl appends a set of common rules to
the bottom of the Makefile.

2.  Platform and machine architecture

The first file that IVImake.tmpl includes, IVarch.c, contains a series
of conditional blocks for identifying the platform and machine
architecture.  The conditional blocks assume that cpp defines an
unique preprocessor symbol which identifies the machine architecture.
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
IVarch.c.

Each conditional block defines several symbols (i.e., macros)
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.)  The Makefiles use MachineDep to create subdirectories in
which to store .o files and libraries.  You can use machinedep (which
defines a lower-case string) to generate filenames like vax.c, etc.,
in your Imakefiles.  IVImake.tmpl uses MacroIncludeFile to include the
.cf file for the platform.  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).
Undefining the symbol also allows Imakefiles to use filenames like
vax.c without having to worry about cpp replacing "vax" with "1".

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 .cf file is to:

     o  find a .cf file similar to yours or start with generic.cf.
     o  set the SystemV parameter if your OS is based on SVR2.
     o  set the OSName, OSMajorVersion, and OSMinorVersion parameters.
     o  look at the other .cf files, IVImake.tmpl, and IVproj.tmpl to
	see if there are any variables you'd like to set.  Common ones
	include:

		HasSockets, HasVFork, HasVoidSignalReturn, HasBsearch,
		HasPutenv, etc.

Even if you don't need to write a new .cf file, you should inspect the
.cf file and correct the major and minor version numbers for your
operating system if necessary.

You can predefine any parameter by including an appropriate definition
in the .cf file.  You can also predefine parameters in IVlocal.def.
If IVImake.tmpl finds any undefined parameters after including the .cf
file and IVlocal.def, it provides default values for them.  You can
predefine the following parameters:

    SystemV			whether or not based on SVR2
    OSMajorVersion		major version number of OS
    OSMinorVersion		minor version number of OS
    UnalignedReferencesAllowed	whether or not arbitrary addresses may be deref
    ExecableScripts		whether or not scripts with #! may be exec'ed
    BourneShell			full pathname of Bourne shell
    ConstructMFLAGS		whether or not to do MFLAGS with MAKEFLAGS
    HasLargeTmp			whether or not /tmp has over 1meg of space
    HasSockets			whether or not system has bsd sockets
    HasVFork			whether or not libc has vfork()
    HasPutenv			whether or not libc has putenv()
    HasVoidSignalReturn		whether or not signal() proc is type void
    HasBsearch			whether or not libc has bsearch()
    HasCfront			whether or not system has cfront translator
    CompileInMachineDepSubdir	whether or not to segregate .o files in subdirs
    StripInstalledPrograms	whether or not to strip installed programs
    RemoveAfterInstall		whether or not to remove a.out after install

    OptimizedCDebugFlags	C compiler flags to turn on optimizer
    DebuggableCDebugFlags	C compiler flags to turn on debugger
    NoOpCDebugFlags		C compiler default flags
    DefaultCDebugFlags		one of previous 3 for compiling programs
    LibraryCDebugFlags		one of previous 3 for compiling libraries
    InstPgmFlags		install options for stripping installed pgms
    InstBinFlags		install modes for program binaries
    InstUidFlags		install modes for setuid programs (xterm)
    InstLibFlags		install modes for libraries
    InstIncFlags		install modes for includes
    InstManFlags		install modes for manual pages
    InstDatFlags		install modes for data files
    InstKmemFlags		install modes for setgid kmem programs (xload)

    AfterInstallCmd		command to remove a.out after it's installed
    ArCmd			command to create and add to libraries
    BootstrapCFlags		initial -Dmacro for systems that don't have 'em
    BootstrapCpuCmd		command to identify this machine's cpu type
    CcCmd			command to run C compiler
    CplusplusCcCmd		command to run C++ compiler
    CppCmd			command to run C preprocessor
    PreProcessCmd		command to run cpp with C default defines
    DependCmd			command to run makedepend
    DependCFlags		default makedepend options
    GenclassCmd			command to run genclass
    ImakeCmd			command to run imake
    ImakeOpts			default imake options
    InstallCmd			command to do bsd-style install
    LdCmd			command to run loader
    CplusplusLdCmd		command to run loader for C++ programs
    LintCmd			command to run linter
    LintLibFlag			flag to tell lint to create a library
    LintOpts			default lint options
    CpCmd			command to copy a file
    LnCmd			command to soft link (if possible) a file
    MakeCmd			command to make from Makefile
    MkdirhierCmd		command to create directory hierarchies
    MvCmd			command to rename a file
    RanlibCmd			command to run after creating a library
    RanlibInstFlags		special flags to ranlib for installed libs
    RmCmd			command to remove a file
    TagsCmd			command to generate C tags
    TroffCmd			command to format a nroff/troff file on stdout
    StandardCppDefines		defines for cpp'ing scripts
    StandardIncludes		includes for C compiler
    StandardDefines		defines and flags for C compiler
    ExtraLibraries		special libraries at end of load line
    ExtraLoadFlags		special flags for load lines
    SrcDir			where C or C++ files are wrt .o files
    GenDir			where template-generated files are wrt .o files
    WindowSystem		window system to build InterViews for (X10/X11)

    InstallRelative		whether or not to install in $(TOP)/installed

    DestDir			path for parent dir of all following paths
    BinDir			path for installed window sys-dep programs
    LocalBinDir			path for installed window sys-indep programs
    IncRoot			path for parent dir of InterViews includes dir
    IncDir			path for installed InterViews includes
    UsrLibDir			path for installed libraries
    XConfigDir			path for installed platform .cf files
    ConfigDir			path for installed config files
    ManSuffix			suffix for program man pages
    LibManSuffix		suffix for library man pages
    ManDir			path for installed program man pages
    LibmanDir			path for installed library man pages

    RelativeBinDir		rel. path for installed window sys-dep programs
    RelativeLocalBinDir		rel. path for installed window sys-ind programs
    RelativeIncDir		rel. path for installed InterViews includes
    RelativeUsrLibDir		rel. path for installed libraries
    RelativeConfigDir		rel. path for installed config files
    RelativeManDir		rel. path for installed man pages

    InstallPlatformCfFiles	whether or not to install platform .cf files

4.  Local Site-specific definitions file

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

We distribute an IVlocal.def that sets InstallPlatformCfFiles YES
since most people have not yet installed any platform .cf files in
/usr/lib/X11/config.  You should set InstallPlatformCfFiles NO when
X11R4 comes out in order to use X11R4's platform .cf files.

The default values for our build parameters ensure that you can play
with InterViews entirely in place: ``make bootstrap,'' ``make
install,'' and ``make install.man'' will install everything under
$(TOP)/installed.  (Actually, for the sake of convenience, "make
install.man" installs man pages in BOTH /usr/man/mann AND
$(TOP)/installed/man.)  If you use ivmkmf to generate a Makefile from
an Imakefile outside of the source tree, imake will give the Makefile
the absolute paths for installed directories instead of the relative
paths.  It is up to you to somehow make the absolute paths and the
relative paths under $(TOP)/installed equivalent to each other.  You
can create symbolic links from your system area to the directories in
$(TOP)/installed or you can replace the directories in
$(TOP)/installed with symbolic links to your system area.  You still
can set InstallRelative NO if you really want to install InterViews
directly into your system area.

5.  Imakefiles

Individual Imakefiles may use any of the macros defined in
IVrules.def.  Some of these rules use make variables that the
Imakefile sometimes 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 the
installed InterViews configuration files, includes, binaries, and
libraries; the Makefile will not depend on anything in the InterViews
source tree.  For ivmkmf and the generated Makefile to work, you must
have ivmkmf, imake, and makedepend 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.
