
				X Window System
			   Imake Configuration Guide

				   Release 3



				   Abstract

This document describes the various parameters that are used to configure this
release of the X Window System.  It should be read by anyone who is porting X
to a new platform or attempting to change the default installation.




1.  Introduction

Because Makefiles are inherently unportable, this release uses a tool called
Imake to generate platform-specific Makefiles from machine-independent
descriptions called Imakefiles.  It makes very heavy use of the C preprocessor
both for constants and macro functions and can be somewhat tricky to master.
However, it is invaluable for making the release easy to configure on a wide
variety of machines.

Imakefiles usually contain definitions of make variables plus one or more
invocations of macro functions to build the desired parts of the Makefile.
Imake reads a template file containing definitions that are common to all
Makefiles, which includes a machine-specific file containing definitions for
the various commonly used commands and flags for enabling certain build
options.  It then includes a rules file in which all of the various macro
functions are defined followed by the Imakefile being processed.  Finally,
it appends a set of common rules to the bottom.




2.  The template file

All of the common configuration parameters and make rules are located in
the file Imake.tmpl.  The top of the file defines some useful constants
and then has a series of conditional blocks for setting the platform type.

This requires that there be a unique preprocessor symbol that can be used to
identify which configuration block to use.  Systems whose cpp does not define
such a symbol must add one to the cpp_argv table in ../imake/imake.c and build
with BOOTSTRAPCFLAGS set to the appropriate name.

Each block defines several symbol names representing the type of system
being configured:

	#define MacroIncludeFile	"PLATFORM.macros"
	#define MacroFile		PLATFORM.macros
	#define PLATFORMArchitecture

where PLATFORM is the type of the system being configured.  The redundant
versions are needed because one is used by cpp to include the file and the
other is used in generating filenames.  The Architecture variable may be
used in Imakefiles to obtain platform-specific rules or values.  The unique
symbols that were used to select the configuration block are then undefined
to prevent Imakefiles from using system-dependent rules as opposed to
platform-dependent (some platforms run on multiple systems).

The rest of the template file should not be edited.  Server-specific changes
can be made in the appropriate .macros file and site-specific changes can be
made in site.def.  Any parameter that is not set will be given a default value
in Imake.tmpl.  THESE DEFAULTS SHOULD NOT BE CHANGED.




3.  Server-specific .macros file

Differences between operating systems are handled by setting various
configuration parameters in the .macros files.  The easiest way to create
a new one is to:

     o  take Guess.macros, select the right portions based on whether or not
	your OS is System V.
     o  set LibraryDefines, ServerDefines, and ConnectionFlags.
     o  read Imake.tmpl to see if there is anything you'd like to override.
     o  look at some of the other .macros files for systems that might be
	similar to yours.

The make variables should be defined as follows:

    AR			command to generate object libraries;  usually set to
			    "ar clq".
    AS			command to assemble code into object file; usually set
			    to "as".
    BOOTSTRAPCFLAGS	special flags that are needed to build imake; this
			    is for cpp's that don't define unique symbols.
			    This must be set on the make World command line.
    CC			command to compile C files; usually set to "cc"
			    followed by any special flags.
    COMPRESS		command to compress(1) a file.
    CPP			name of C preprocessor program.
    INSTALL		name of BSD-compatible install program; usually set to
			    "install" or "bsdinstall".
    LD			name of loader program; usually set to "ld".
    LINT		name of lint program; usually set to "lint".
    LINTLIBFLAG		flag to make $(LINT) generate a lint library; usually
			    set to either "-C" or "-o".
    LINTOPTS		flags to pass to $(LINT).
    LN			command line to generate links; usually set to 
			    "ln -s" or "ln" if soft links aren't supported.
    MV			name of move file program; usually set to "mv".
    RANLIB		name of program to run after building a library;
			    usually set to "ranlib" or "/bin/true".
    RANLIBINSTFLAGS	some systems support a -t flag to ranlib telling it
			    it to just touch the archive explicitly for
			    installing libraries
    RM			command line to force a regular file to be removed;
			    usually set to "rm -f".
    STD_CPP_DEFINES	preprocessor definitions for passing things through
			    cpp; usually a subset of STD_DEFINES.
    STD_DEFINES		C compiler flags to be used on every compile; this is
			    where special options increasing table sizes are
			    put.  Also, System V sites should add -DSYSV.
    SYSLAST_LIBRARIES	libraries to put at the end of link lines; usually
			    left blank or set to the names of any emulation
			    libraries (such as DECnet or sockets).
    TAGS		name of ctags program; usually set to "ctags".


In addition, you will also have to set the following preprocessor definitions:

    LibraryDefines	any special flags for compiling libraries
    ServerDefines	any special flags for compiling the server
    ConnectionFlags	any of -DTCPCONN -DUNIXCONN -DDNETCONN

If you are going to build a server, you will need to define the following
parameters as well:

    XnameServer		where name is the name of the platform in lower case
    FontDefines		any of -DFONT_SNF -DFONT_BDF -DCOMPRESSED_FONTS

You'll then have to add sections to the server/Imakefile to build your
server.

A number of other parameters may be defined.  The file Imake.tmpl contains
defaults for all servers which can be overridden by including an appropriate
definition in the .macros file:

    SystemV			is System V based instead of BSD?  YES/NO
    BuildServer			build the server and fonts?  YES/NO
    UnalignedReferencesAllowed	arbitrary memory references okay?  YES/NO
    BourneShell			pathname of Bourne shell
    InstallxinitConfig		install sample xinit configuration?  YES/NO
    InstallxdmConfig		install sample xdm configuration?  YES/NO
    InstallAppDefFiles		install application default resources?   YES/NO
    ExpandManNames		expand Xlib man page filename?  YES/NO
    DebugLibX			build debuggable Xlib?  YES/NO
    DebugLibXArchive		build separate debug Xlib library?  YES/NO
    ProfileLibX			build profiled Xlib?  YES/NO
    ProfileLibXArchive		build separate profile Xlib library?  YES/NO
    DebugOldLibX		build debuggable X10 emul library?  YES/NO
    ProfileOldLibX		build profiled X10 emul library?  YES/NO
    DebugLibXt			build debuggable Xt library?  YES/NO
    ProfileLibXt		build profiled Xt library?  YES/NO
    DebugLibXaw			build debuggable Xaw library?  YES/NO
    ProfileLibXaw		build profiled Xaw library?  YES/NO
    DebugLibXext		build debuggable extensions library?  YES/NO
    ProfileLibXext		build profiled extensions library?  YES/NO
    DebugLibXmu			build debuggable Xmu library?  YES/NO
    ProfileLibXmu		build profiled Xmu library?  YES/NO
    ManDirectoryRoot		root of man page tree
    ManSuffix			suffix for program man pages
    LibManSuffix		suffix for library man pages
    ExtensionDefines		any of -DZOID -DBEZIER
    UNCOMPRESSPATH		full pathname of uncompress program
    UNCOMPRESSFILT		-D version of above
    BDFTOSNFFILT		-D version of bdftosnf program
    SHELLPATH			full pathname of Bourne shell
    ZBDFTOSNFFILT		command to uncompress BDF and compile
    PrimaryScreenResolution	dots per inch of main monitor
    DefaultFontPath		comma-separated list of directories
    DefaultRGBDatabase		pathname of RGB database
    FontCompilerFlags		flags to pass to font compiler
    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
    ServerCDebugFlags		debug vs. optimize flags for server
    CppSourcesPresent		are BSD cpp sources available?  YES/NO
    CppSources			pathname of directory with BSD cpp sources
    ConstructMFLAGS		set MFLAGS from MAKEFLAGS?  YES/NO
    DestDir			root of installation, should be blank
    UsrLibDir			directory to contain libraries
    BinDir			directory to contain programs
    IncDir			directory to contain header files
    AdmDir			directory in which server should put log file
    LibDir			directory to contain fonts, config files, etc.
    LintlibDir			directory to contain lint libraries
    FontDir			directory to contain fonts
    XinitDir			directory to contain xinit config files
    XdmDir			directory to contain xdm config files
    XdmConfigurationSubdirectory	subdir of xdm containing config
    UwmDir			directory to contain uwm config files
    AwmDir			directory to contain awm config files
    TwmDir			directory to contain twm config files
    ManPath			root of manual page tree
    ManSourcePath		name of man source directories to append to
    ManDir			directory to contain program man pages
    LibmanDir			directory to contain library man pages
    XAppLoadDir			directory to contain application defaults
    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
    InstAppFlags		install flags for application defaults
    InstKmemFlags		install flags for reading /dev/kmem
    BandAidLibraryNeeded	is a hack library needed in Xlib?  YES/NO
    OsNameDefines		definitions used to specify OS Name
    DefaultUserPath		path for xdm to use when starting user progs
    DefaultSystemPath		path for xdm to use when running Xstartup/reset
    DefaultSystemShell		contents of SHELL when running progs

See the various .macros files for examples.




4.  Site-specific site.def file

The site.def file is used to set configuration parameters that apply to all
all servers in a given site.  It should use #ifndef so that servers may 
still override it.

The second use for site.def is to define installation directories and flags.
We strongly recommend that people try to use the default directories if at
all possible so that X11 can coexist peacefully with X10.




5.  Imakefiles

Individual Imakefiles may use any of the macros defined in Imake.rules.  Many
of these rules use auxillary make variables:

    FILE		used by lint1 phase
    INSTALLFLAGS	used by default installs
    LINTLIBS		used by NormalLintTarget
    LOCAL_LIBRARIES	used by ComplexProgramTarget
    MAKEFILE_SUBDIR	used by MakeMakeSubdirs
    OBJS		used by ComplexProgramTarget
    OBJS1		used by ComplexProgramTarget_1
    OBJS2		used by ComplexProgramTarget_2
    OBJS3		used by ComplexProgramTarget_3
    PROGRAM		used by ComplexProgramTarget
    PROGRAMS		used by ComplexProgramTarget_1
    SRCS		used by DependTarget
    SRCS1		used by DependTarget
    SRCS2		used by DependTarget
    SRCS3		used by DependTarget

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