.\" format with
.\" tbl % | xroff -ms | lpr
.\"
.\" revision date - change whenever this file is edited
.ds Rd 28 January 1991
.\" document revision number - change each time document is released
.ds Rn 1.01
.\"
.nr PO 1.2i	\" page offset 1.2 inches
.nr PD .7v	\" inter-paragraph distance
.\"
.EH 'Imake in X11R4'- % -''
.OH ''- % -'Imake in X11R4'
.OF 'Revision date:\0\0\*(Rd'\s+1\*-MORE DRAFT SCRIBBLINGS\*-\s-1'Printed:\0\0\n(dy \*(MO 19\n(yr'
.EF 'Revision date:\0\0\*(Rd'\s+1\*-MORE DRAFT SCRIBBLINGS\*-\s-1'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
..
.\" start block.  LP gives a bit extra space. Can say .Ds .IP C, etc.
.de Ds
.if \\n(.$<1 .LP
.if \\n(.$>=1 \\$1
.if \\n(.$<2 .DS
.if \\n(.$>=2 .DS \\$2 \\$3 \\$4 \\$5
..
.\" end block.  If arg is given, it replaces the .LP (e.g., .De .IP).
.de De
.DE
.if \\n(.$<1 .LP
.if \\n(.$>=1 \\$1 \\$2 \\$3 \\$4 \\$5
..
.\" if the Sy definition changes, there are four symbols which had to be
.\" manually formatted and which need to be changed manually,
.\" UNCOMPRESSFILT, BDFTOSNFFILT, SHELLPATH, ZBDFTOSNFFILT
.de Sy		\" symbol definition
.br
.ta 6iR
\fB\\$1\fR	\\$3
.br
\0\0default: \\$2
..
.de Ru		\" imake rule
.br
.ne 3v
.B \\$1
..
.NH
Appendix
.LP
.I cpp
symbols and
.I make
variables defined in the X configuration files are listed and described here.
Much of this information can be found in those files and in
.I mit/config/README .
.LP
There are a number of places where I confess ignorance.
If you fill me in on the missing pieces, I'll revise this document.
.LP
Besides symbols used for rule macros, symbols may be classed in
three categories.
Some are used as booleans and are defined as YES or NO.
Some are simply defined as nothing or left undefined.
Boolean and defined/not-defined symbols are rarely if ever
associated with variables appearing in
.I Makefiles ;
rather, they are used for control purposes to modify the configuration
and build process.
.LP
The other symbols are general-purpose, usually (but not always)
having a value that is assigned to some
.I Makefile
variable.
The value may be empty (that is, the symbol may be defined as nothing):
.Ds
.ta 1i 2i
#define	\fIsymbol\fR	/* as nothing */
.De
The descriptions below give symbol names, and their defaults and
symbol class where applicable.
A default of ``nothing'' means the empty definition.
.LP
.B Note:
The symbol UseInstalled is not defined in any of the configuration
files.
It should be defined (by you, as nothing) in
.I site.def
if you want to use installed versions of
.I imake ,
.I makedepend
and the configuration files.
It can be defined in
.I site.def ,
but you must leave it undefined on the initial build,
obviously, since the configuration programs
and files will not have been installed yet.
.NH
Imake.tmpl
.NH 2
Global Constant Definitions
.LP
This section defines the two symbols YES and NO:
.Ds
.ta 1i 2i
#define	YES	1
#define	NO	0
.De
These are heavily used to define boolean symbols.
.NH 2
Header Blocks
.LP
Every header block in this section of
.I Imake.tmpl
defines two symbols:
.LP
.Sy MacroIncludeFile <generic.cf> general
.Sy MacroFile generic.cf general
.IP
Both of these name the platform-specific file to be included by the
template after the header block section.
The defaults are deliberately rebarbative and are selected only if the
correct header block for your system was not triggered.
Otherwise these symbols will have values like
.I platform .cf> <
and
.I platform .cf,
where
.I platform
is ``ultrix'', ``sun'', ``hp'', ``apollo'', etc.
.IP
There are two symbols associated with this name because it is used two
different ways.
MacroIncludeFile is used by
.I cpp
to include the platform file.
MacroFile is used to generate file names.
.IP
In addition to the above two symbols, header blocks may define one or more
of the following symbols to indicate the software and/or hardware platform.
.Ds .IP
.ta 3i
AIXArchitecture	PS2Architecture
ATTArchitecture	PegasusArchitecture
ApolloArchitecture	RtArchitecture
CrayArchitecture	SGIArchitecture
HPArchitecture	SonyArchitecture
IBMArchitecture	StellarArchitecture
M4330Architecture	SunArchitecture
MacIIArchitecture	UltrixArchitecture
MipsArchitecture	VaxArchitecture
.De .IP
Some of these symbols may be defined in more than one header block.
The platform file may also define other \fIxxx\fRArchitecture symbols
.I sun.cf (
does so, for instance, to allow SPARC- or i386-dependencies to be selected.)
.NH
System/Build Definitions
.NH 2
Preprocessor Symbols
.LP
Symbols are listed in order of their appearance in
.I Imake.tmpl .
The default value of some symbols is determined based
on whether SystemV is YES or NO.
For these symbols both defaults are listed, with the SystemV=YES case first.
.LP
.Sy SystemV varies boolean
.IP
SystemV indicates whether your system is System V based (YES) or not
(NO).
If not, that usually means BSD based.
The default value of many other symbols depends on SystemV, so it is
usually set explicitly early
in the platform-specific file to make sure it's correct.
.LP
.Sy OSMajorVersion "0" general
.Sy OSMinorVersion "0" general
.IP
These two symbols indicate the major and minor version numbers of the
operating system.
They are often used as control symbols in the platform files
to select symbol values that vary depending on the OS version.
For this reason, they are usually set in the platform file.
.IP
Example: if some feature of your OS didn't appear until version 5.7,
you could test for that with:
.Ds .IP
/**/# these definitions would go in the platform file
# ifndef OSMajorVersion
# define OSMajorVersion 5
# endif
# ifndef OSMinorVersion
# define OSMinorVersion 7
# endif

/**/# this test would go wherever you need to test for 5.7 and up
# if OSMajorVersion >= 5 && OSMinorVersion >= 7
	/**/# 5.7-and-up specific stuff here
# endif
.De
.LP
.Sy UnalignedReferencesAllowed "NO" boolean
.IP
Some processors can dereference pointers to arbitrary addresses.
Others cannot\*-inability to dereference odd addresses is a typical problem
for such processors.
If your pointers must be specifically aligned (e.g., on word
boundaries), define UnalignedReferencesAllowed as NO.
The default reflects a conservative approach.
.LP
.Sy ExecableScripts "NO/YES" boolean
.IP
Whether the kernel
.I exec ()
system call correctly executes scripts beginning with ``#!''.
ExecableScripts determines the way the CppScriptTarget() rule macro is
expanded and thus the way shell scripts are built.
.IP
Script prototypes begin with a line that says ``#!/bin/sh''.
If ExecableScripts is NO, that line is stripped out and replaced with
one that says ``:''.\**
.FS
I would say that a better way to do it might be to explicitly write
a line into the script using the value of ${SHELL} if ExecableScripts
is YES and ``:'' otherwise.
This would allow the value of SHELL to propagate into scripts were it
defined as something other than
.I /bin/sh .
.FE
.LP
.Sy BourneShell "/bin/sh" general
.IP
Path name of Bourne shell.
This is used to set the value of SHELL, and in construction of some
commands that run shell scripts.
.LP
.Sy ConstructMFLAGS "YES/NO" boolean
.IP
Whether to construct MFLAGS
.I make
variable from MAKEFLAGS.
This is used (I think) for compatibility with versions of
.I make
that use MFLAGS instead of MAKEFLAGS.
.LP
.Sy HasLargeTmp "NO" boolean
.IP
Whether the file system on which
.I /tmp
resides has lots of free space.
The meaning of ``lots'' is roughly 1MB, although that may need to be revised
upward for future releases.
This symbol determines the default value of ArCmd.
.LP
.Sy HasSockets "NO/YES" boolean
.IP
Whether the system has BSD socket support.
.LP
.Sy HasVFork "NO/YES" boolean
.IP
Whether the
.I vfork ()
system call is supported.
Presumably this causes
.I fork()
to be used instead of
.I vfork()
if HaveVFork is NO.
.LP
.Sy HasPutenv "NO" boolean
.IP
Whether the
.I putenv ()
C library call is supported.
.LP
.Sy HasVoidSignalReturn "YES/NO" boolean
.IP
Whether the
.I signal ()
C library call returns
.I void *
(YES)
or
.I int *
(NO).
The default is YES for System V platforms, but
if you have a BSD platform, you should not assume NO.
Some BSD-based systems (e.g., Ultrix and Sun) have changed from
.I int *
to
.I void *
in new OS releases.
Some machines try to support both sets of semantics.
.LP
.Sy HasBsearch "YES/NO" boolean
.IP
Whether the
.I bsearch ()
C library call is supported.
.LP
.Sy HasSaberC "NO" boolean
.IP
Whether the system has the Saber C development environment.
The default value of this symbol will usually be overridden in the
platform file.
.B Warning:
some of the platform files define HasSaberC as YES, so be sure to
check this and change it if necessary.
.LP
.Sy HasFortran "NO" boolean
.IP
Whether the system has a FORTRAN compiler.
Needed for GKS support.
.LP
.Sy HasNdbm "NO" boolean
.IP
Whether the system has the NDBM database manager (supercedes DBM).
.LP
.Sy HasDESLibrary "NO" boolean
.IP
Whether the system has a DES (digital encryption standard) library.
.LP
.Sy NeedFunctionPrototypes "NO" boolean
.Sy NeedWidePrototypes "YES" boolean
.IP
These are used to support use of function prototypes.
Apparently they are not well-liked judging from the deprecatory comments
in the latter part of
.I Imake.tmpl .
.LP
.Sy HasSunOSSharedLibraries "NO" boolean
.IP
Whether SunOS shared libraries are supported.
.LP
.Sy SharedCodeDef "varies" general
.IP
Flags to compile sharable library code.
.LP
.Sy SharedLibraryDef "varies" general
.IP
Flags to turn on use of shared libraries.
.LP
.Sy HasSharedLibraries "varies" boolean
.IP
Whether shared libraries are supported.
.B Note:
This symbol is defined
.I inside
the (convoluted) definition of SharedLibraryDef.
.LP
.Sy StripInstalledPrograms "NO" boolean
.IP
If YES, strip symbol table from installed programs, otherwise leave intact.
Setting to YES can save lots of disk space on some machines, but
leaving it as NO can help during debugging.
This symbol affects use of InstPgmFlags.
.LP
.Sy DestDir nothing general
.IP
Prefix to prepend to installation directory pathnames.
Normally this is left empty.
If you want to install under an alternate root, the X folks recommend that
you compile with the default value, then install with
.Ds .IP
make install DESTDIR=/alt/root
.De .LP
.Sy UsrLibDir "$(DESTDIR)/usr/lib" general
.IP
Directory under which to install system libraries (e.g.,
.I lint
libraries; see description of LintlibDir under
.I Project.tmpl ).
This is also used as the basis for the default value of LibDir (in
.i Project.tmpl ), which is used for installation of libraries for
.I xdm ,
.I awm ,
.I twm ...
.LP
.Sy IncRoot "$(DESTDIR)/usr/include" general
.IP
Path to root of system header file hierarchy.
X11 header files are installed under this.
(A default for this symbol is also included in
.I Project.tmpl ;
you can ignore it because the definition in
.I Imake.tmpl
occurs first and will override it.)
.LP
.Sy UNCOMPRESSPATH "/usr/ucb/uncompress" general
.IP
Command to run the
.I uncompress
program.
I think this is used to uncompress compressed font files.
If you override this symbol, the definition should probably be a full
path name.
.LP
.Sy OptimizedCDebugFlags "\-O" general
.IP
C compiler flags to turn on optimization.
.LP
.Sy DebuggableCDebugFlags "\-g" general
.IP
C compiler flags to turn on debugging information.
.LP
.Sy NoOpCDebugFlags nothing general
.IP
C compiler flags to not turn on optimization or debugging.
.LP
.Sy DefaultCDebugFlags "OptimizedCDebugFlags" general
.IP
C compiler flags to turn on optimization for programs.
.LP
.Sy LibraryCDebugFlags "OptimizedCDebugFlags" general
.IP
C compiler flags to turn on optimization for libraries.
.LP
.Sy DefaultCCOptions nothing general
.IP
Special C compiler flags (other than \-I's and \-D's?
See StandardDefines, StandardCppDefines).
Useful, e.g., for turning on floating point options.
.LP
.Sy LibraryCCOptions "DefaultCCOptions" general
.IP
Special C compiler flags for compiling libraries.
.LP
.Sy ServerCCOptions "DefaultCCOptions" general
.IP
Special C compiler flags for compiling the server.
(This is X-specific and should be in
.I Project.tmpl ,
perhaps?)
.LP
.Sy PexCDebugFlags "\-g" general
.IP
C compiler flags to turn on debugging information for PEX.
(This is X-specific and should be in
.I Project.tmpl ,
perhaps?)
.LP
.Sy InstPgmFlags "\-s" general
.IP
Flags for installing programs.
The default strips symbol tables.
This symbol is used in conjunction with StripInstalledPrograms to set
the
.I make
variable INSTPGMFLAGS.
Note that INSTPGMFLAGS applies to installs of
binary programs and also shell
scripts; some systems give a warning when you try to strip a script
because they have no symbol table (such warnings can be ignored).
.LP
.Sy InstBinFlags "\-m 0755" general
.IP
Flags for setting the mode of installed executable files.
.LP
.Sy InstUidFlags "\-m 4755" general
.IP
Flags for setting the mode of installed set-user-id files (e.g.,
.I xterm
needs to
.I chown
pty's).
.LP
.Sy InstLibFlags "\-m 0664" general
.IP
Flags for setting the mode of installed libraries.
.LP
.Sy InstIncFlags "\-m 0444" general
.IP
Flags for setting the mode of installed header files.
.LP
.Sy InstManFlags "\-m 0444" general
.IP
Flags for setting the mode of installed manual pages.
.LP
.Sy InstDatFlags "\-m 0444" general
.IP
Flags for setting the mode of installed data (non-executable) files.
.LP
.Sy InstKmemFlags "InstUidFlags" general
.IP
Flags for installing programs that need to read
.I /dev/kmem ,
e.g.,
.I xload .
The default makes such programs setuid, which is overkill, since
typically all that's needed is setgid to the group having access to
.I /dev/kmem .
InstKmemFlags
is a good symbol to define in
.I site.def .
Be sure to include the correct group, e.g., ``\-g kmem \-m 2755''.
The group is not set in the default value of this symbol because
it's difficult to determine a good default group.
.LP
.Sy ArCmd "varies" general
.IP
Command to create archive files.
If HasLargeTmp is YES,
.I /tmp
is used for temp file space, otherwise the current directory is used.
.LP
.Sy BootstrapCFlags nothing general
.IP
Defines needed to get
.I ccimake
compiled and by
.I imake
to get
.I cpp
to select the correct header block in
.I Imake.tmpl .
.LP
.Sy CcCmd "cc" general
.IP
Command to run the C compiler.
.LP
.Sy HasGcc "NO" boolean
.IP
Whether GNU CC,
.I gcc ,
is available.
.LP
.Sy ServerCcCmd "CcCmd" general
.IP
Command to run the C compiler to compile the server.
(This is X-specific and should be in
.I Project.tmpl ,
perhaps?)
.LP
.Sy LibraryCcCmd "CcCmd" general
.IP
Command to run the C compiler to compile libraries.
.LP
.Sy FortranCmd "f77" general
.IP
Command to run the FORTRAN compiler.
.LP
.Sy FortranFlags nothing general
.IP
General flags for FORTRAN compiler.
.LP
.Sy FortranDebugFlags nothing general
.IP
Flags for FORTRAN compiler to turn on debugging information.
.LP
.Sy AsCmd "as" general
.IP
Command to run the assembler.
.LP
.Sy CompressCmd "compress" general
.IP
Command to run
.I compress .
.LP
.Sy CppCmd "/lib/cpp" general
.IP
Command to run C preprocessor.
.LP
.Sy PreProcessCmd "CcCmd \-E" general
.IP
Command to preprocess input.
This is used by the script version of
.I makedepend .
.LP
.Sy InstallCmd "$(SCRIPTSRC)/bsdinst.sh / install" general
.IP
Command to install files.
It should be compatible with the BSD version of
.I install .
.LP
.Sy LdCmd "ld" general
.IP
Command to run the loader.
.LP
.Sy LintCmd "lint" general
.IP
Command to run
.I lint .
.LP
.Sy LintLibFlag "\-o/\-C" general
.IP
Flags to build
.I lint
libraries.
.LP
.Sy LintOpts "\-ax/\-axz" general
.IP
Flags to tell
.I lint
how picky to be.
.LP
.Sy CpCmd "cp" general
.IP
Command to copy files.
.LP
.Sy LnCmd "ln/ln \-s" general
.IP
Command to link files.
Symbolic links are used if available (not System V).
.LP
.Sy MakeCmd "make" general
.IP
Command to run
.I make .
.LP
.Sy MvCmd "mv" general
.IP
Command to rename files.
.LP
.Sy RanlibCmd "/bin/true / ranlib" general
.IP
Command to run
.I ranlib .
On System V platforms this command is missing.
.I /bin/true ,
a nop, is used instead.
.I /bin/true "" (
always succeeds, which is important for
.I make .)
.LP
.Sy RanlibInstFlags nothing general
.IP
Flags to pass to
.I ranlib
when run on libraries that have already been installed.
``\-t'' is a good option here, if you have it.
.LP
.Sy RmCmd "rm \-f" general
.IP
Command to remove files.
.LP
.Sy StandardCppDefines "\-DSYSV/nothing" general
.IP
\-D's for C preprocessor.
.LP
.Sy StandardIncludes nothing general
.IP
\-I's for C compiler.
.LP
.Sy StandardDefines "\-DSYSV/nothing" general
.IP
\-D's for C compiler.
.LP
.Sy NdbmDefines "varies" general
.IP
Flags to turn on NDBM support.
Affected by HasNdbm.
.LP
.Sy ExtraLibraries nothing general
.IP
Extra libraries needed to get programs to compile.
.LP
.Sy ExtraLoadFlags nothing general
.IP
Extra flags needed to get loader to work.
.LP
.Sy LdCombineFlags "\-X \-r" general
.IP
Flags for incremental loader support.
.LP
.Sy CompatibilityFlags nothing general
.IP
Flags to turn on R3 backward compatibility support.
.LP
.Sy TagsCmd "ctags" general
.IP
Command to generate tags files.
.LP
.Sy LoaderLibPrefix nothing general
.IP
Flags to specify before libraries (see
.I cray.cf ).
.LP
.Sy TOPDIR "." general
.Sy CURDIR "." general
.IP
Top of source tree, and current directory. 
The
.I make
variables associated with these (TOP, CURRENT_DIR)
are overridden by recursive
.I make
rules.
The defaults are correct for the top of the source tree.
TOP and CURRENT_DIR are reset for each
.I Makefile
during ``make Makefiles''.
TOP is the path to the top of the source tree, from the current
directory.
CURRENT_DIR is the path to the current directory from the top of the
source tree.
.LP
.Sy FilesToClean "*.CKP *.ln *.BAK *.bak *.o core errs ,* *~ *.a .emacs_* tags TAGS make.log MakeOut" general
.IP
List of files to be removed by ``make clean''.
Note that ``*~'' is in this list, and see discussion of the
RemoveProgramTarget() rule.
If you are in the habit of using ``cp x x~'' to make a backup copy of
files you modify, ``make clean'' will remove those copies, which may
not be what you want.
.NH 2
Make Variables
.LP
Many of the
.I make
variables in
.I Imake.tmpl
are simply set to the preprocessor variable of the same name (e.g.,
INSTBINFLAGS = InstBinFlags).
.LP
Most
.I make
variables referring to commands are set to the preprocessor symbol having
the same name and a suffix ``Cmd''.
For instance, CC and MAKE are set to CcCmd and MakeCmd, respectively.
.LP
The rest of the variables are set to
preprocessor symbols with names that differ a bit from the variable
name (e.g., SHELL = BourneShell), or are defined in terms of other
.I make
variables (e.g., MFLAGS = -$(MAKEFLAGS)), or a combination of
preprocessor symbols and
.I make
variables (e.g., RM_CMD = $(RM) FilesToClean).
.NH
platform.cf
.LP
Symbols which definitely should be set here are
BuildServer (and X\fIxxx\fRServer if BuildServer is YES),
OSName, OSMajorVersion, and OSMinorVersion.
Some other symbols you should think about setting are
CCompilerMajorVersion,
CCompilerMinorVersion,
BootstrapCFlags,
SystemV,
UnalignedReferencesAllowed,
SetTtyGroup,
ExecableScripts,
and
ConstructMFLAGS.
.NH
site.def
.LP
You should read through the
.I site.def
file and follow the comments there which tell whether you should
supply
override definitions for a number of symbols.
This is the place to indicate whether you have a large temp area
(HasLargeTmp), whether you have GNU
.I cc
(HasGcc), whether you want to compile in R3 backward compatibility
(CompatibilityFlags), etc.
It's also a good place to set symbols such as InstKmemFlags and
BuildExamples.
.NH
Project.tmpl
.NH 2
Preprocessor Symbols
.LP
Symbols are listed in order of their appearance in
.I Project.tmpl .
.LP
.Sy ProjectX 4 general
.IP
X11 Release number.
The
.I README
says this is a boolean, which is incorrect.
.LP
.Sy BuildServer YES boolean
.IP
Whether to build the server.
This should be defined as NO in
.I site.def
on client-only systems.
On platforms which have no server implementation, the value of
BuildServer may already be set to NO in the platform file.
.LP
.Sy BuildExamples YES boolean
.IP
Whether to build the example programs.
It will speed up your builds to override this as NO, and less disk
space will be used.
.IP
It is probably possible to build selected examples only.
Define BuildExamples as YES, then build all the Makefiles from the
source root.
Then build the ``clean'' and ``depend'' targets.
Define BuildExamples as NO and rebuild the Makefiles.
The examples directories should be left alone since BuildExamples
is NO, but you can then go into an example directory and build the
program since its
.I Makefile
should be correct.
(This is all conjecture.)
.LP
.Sy BuildXawBC NO boolean
.IP
Whether to build backward-compatible X Athena Widgets (I think).
.LP
.Sy InstallXinitConfig NO boolean
.IP
Whether to install sample
.I xinit
configuration files.
.LP
.Sy InstallXdmConfig NO boolean
.IP
Whether to install sample
.I xdm
configuration files.
.LP
.Sy InstallAppDefFiles YES boolean
.IP
Whether to install application defaults
files.
.LP
.Sy InstallOldHeaderFiles NO boolean
.IP
Whether to install R3 header files.
.LP
.Sy DebugLibX NO boolean
.IP
Whether to build debugging into the X library.
.LP
.Sy DebugLibXArchive NO boolean
.IP
Whether to build debugging into the archive file version of the X library.
.LP
.Sy ProfileLibX NO boolean
.IP
Whether to build profiling into the X library.
.LP
.Sy ProfileLibXArchive NO boolean
.IP
Whether to build profiling into the archive file version of the X library.
.LP
.Sy DebugOldLibX NO boolean
.Sy ProfileOldLibX NO boolean
.Sy DebugLibXt NO boolean
.Sy ProfileLibXt NO boolean
.Sy DebugLibXaw NO boolean
.Sy ProfileLibXaw NO boolean
.Sy DebugLibXext NO boolean
.Sy ProfileLibXext NO boolean
.Sy DebugLibXmu NO boolean
.Sy ProfileLibXmu NO boolean
.IP
Whether to build debugging and/or profiling into the old X library, X
Toolkit library, X Athena Widget library, X Extension library or the
X mu library.
.LP
.Sy NeedBerklibInXlib NO boolean
.IP
Whether BSD emulation is needed in Xlib.
If YES, then BandAidLibrary is set to YES, some other related symbols
are defined, and the BandAidLibraryMake() rule macro is defined.
.LP
.Sy ManDirectoryRoot /usr/man general
.IP
Path to the top of the manual page hierarchy relative to the default root
directory.
See also ManPath.
.LP
.Sy ManSuffix n general
.IP
Suffix for program manual pages.
See ManSourcePath, ManDir.
.LP
.Sy LibManSuffix 3 general
.IP
Suffix for library manual pages.
See ManSourcePath, LibmanDir.
.LP
.br
.ta 6iR
\fBUNCOMPRESSFILT\fR	general
.br
\0\0default: \-DUNCOMPRESSFILT=\e"UNCOMPRESSPATH\e"
.IP
\-D's to run
.I uncompress .
.LP
.br
.ta 6iR
\fBBDFTOSNFFILT\fR (default:	general
.br
\0\0default: \-DBDFTOSNFFILT=\e"$(BINDIR)/bdftosnf\e"
.IP
\-D's to run
.I bdftosnf
to convert fonts from binary distribution format to server natural
format.
.LP
.br
.ta 6iR
\fBSHELLPATH\fR	general
.br
\0\0default: \-DSHELLPATH=\e"/bin/sh\e"
.IP
\-D's for command to run the shell.
.LP
.br
.ta 6iR
\fBZBDFTOSNFFILT\fR	general
.br
\0\0default: \-DZBDFTOSNFFILT=\e"UNCOMPRESSPATH" | $(BINDIR)/bdftosnf $(FONTCFLAGS)\e""
.IP
\-D's to run
.I uncompress
and
.I bdftosnf
to convert compressed binary distribution format font files to server natural
format.
.LP
.Sy FontFilters "UNCOMPRESSFILT BDFTOSNFFILT SHELLPATH ZBDFTOSNFFILT" general
.IP
\-D's for font conversion filters.
.LP
.Sy PrimaryScreenResolution 72 general
.IP
Resolution of default server screen, in dots per inch (dpi).
This number applies both to horizontal and to vertical resolution; X
assumes square pixels.
.LP
.Sy DefaultFontPath varies general
.IP
Path to font directory.
If not set somewhere else, a default is guessed, based
on PrimaryScreenResolution, to select between 75 dpi and 100 dpi fonts.
.LP
.Sy DefaultRGBDatabase $(LIBDIR)/rgb general
.IP
Path to RGB color database.
.LP
.Sy FontCompilerFlags \-t general
.IP
Flags for
.I bdftosnf .
.LP
.Sy ConnectionFlags "\-DTCPCONN \-DUNIXCONN" general
.IP
What kinds of connections the server will accept.
Common values are \-DTCPCONN, \-DUNIXCONN, \-DSTREAMSCONN.
More than one can be specified.
If the server is built, at least one must be specified.
.LP
.Sy FontDefines "\-DFONT_SNF \-DFONT_BDF \-DCOMPRESSED_FONTS" general
.IP
\-D's for font options.
.LP
.Sy ExtensionDefines nothing general
.IP
\-D's for server extensions.
Default is nothing, for ``no extensions''.
This is typically overridden in the platform file for servers that
know about particular extensions, or in
.I site.def .
.LP
.Sy ServerCDebugFlags OptimizedCDebugFlags general
.IP
C compiler flags to turn on optimization/debugging in server.
.LP
.Sy LibraryDefines StandardDefines general
.IP
\-D's for compiling libraries.
.LP
.Sy ServerDefines "StandardDefines ExtensionDefines" general
.IP
\-D's for compiling the server.
.LP
.Sy CppSourcesPresent NO boolean
.IP
Whether you have BSD
.I cpp
sources.
.LP
.Sy CppSources /usr/src/lib/cpp general
.IP
Path to BSD
.I cpp
sources.
Not used if CppSourcesPresent is NO.
.LP
.Sy BinDir $(DESTDIR)/usr/bin/X11 general
.IP
Where to install programs.
.LP
.Sy IncRoot $(DESTDIR)/usr/include general
.IP
IGNORE this symbol in
.I Project.tmpl ;
it's redundant.
See its definition in the system/build section of
.I Imake.tmpl .
.LP
.Sy BuildIncRoot $(TOP) general
.IP
Relative path to (parent of) top of header file tree within source tree.
.LP
.Sy BuildIncTop .. general
.IP
Top of header file tree within source tree, relative to $(TOP)/X11.
.LP
.Sy LibDir $(USRLIBDIR)/X11 general
.IP
X library installation directory (other directories are installed under
this, e.g., FontDir, XinitDir).
.LP
.Sy ConfigDir $(LIBDIR)/config general
.IP
Where to install configuration files.
.LP
.Sy LintlibDir $(USRLIBDIR)/lint general
.IP
Where to install lint libraries.
Note that the default uses USRLIBDIR, not LIBDIR.
Also note that the name of this symbol is LintlibDir, not LintLibDir.
.LP
.Sy FontDir $(LIBDIR)/fonts general
.IP
Where to install fonts.
.LP
.Sy AdmDir $(DESTDIR)/usr/adm general
.IP
Where system log files are found.
.LP
.Sy XinitDir $(LIBDIR)/xinit general
.IP
Where to install
.I xinit
files.
.LP
.Sy XdmDir $(LIBDIR)/xdm general
.IP
Where to install
.I xdm
files.
.LP
.Sy XdmConfigurationSubdirectory config/default general
.IP
Default
.I xdm
configuration directory.
.LP
.Sy AwmDir $(LIBDIR)/awm general
.IP
Where to install
.I awm
files.
.LP
.Sy TwmDir $(LIBDIR)/twm general
.IP
Where to install
.I twm
files.
.LP
.Sy GwmDir $(LIBDIR)/gwm general
.IP
Where to install
.I gwm
files.
.LP
.Sy ManPath $(DESTDIR)ManDirectoryRoot general
.IP
Full path to top of manual page hierarchy.
.LP
.Sy ManSourcePath $(MANPATH)/man general
.IP
Path to top of manual page hierarchy, plus common suffix of manual page
directories there.
.LP
.Sy ManDir $(MANSOURCEPATH)ManSuffix general
.IP
Where to install program manual pages.
.LP
.Sy LibmanDir $(MANSOURCEPATH)LibManSuffix general
.IP
Where to install library manual pages.
.LP
.Sy XAppLoadDir $(LIBDIR)/app-defaults general
.IP
Where to install application defaults files.
.LP
.Sy OsNameDefines nothing general
.IP
I don't know what this is used for.
It's referenced in
.I lib/Xdmcp/Imakefile
and
.I lib/Xmu/Imakefile .
.LP
.Sy DefaultUserPath :/bin:/usr/bin:$(BINDIR):/usr/ucb general
.IP
Default
.I xdm
user PATH environment variable.
.LP
.Sy DefaultSystemPath /etc:/bin:/usr/bin:$(BINDIR):/usr/ucb general
.IP
Default
.I xdm
system PATH environment variable.
.LP
.Sy DefaultSystemShell BourneShell general
.IP
Default shell.
.LP
.Sy UseCCMakeDepend NO boolean
.IP
Whether to use the slow shell script version of
.I makedepend
(uses
.I "cc \-E" ).
It's best to use the compiled version if it works on your system.
If the compiled version does not work as supplied with the distribution,
it's probably
worth a little effort to see if you can get it to work
(particularly if you can't get the shell script version to work,
either, which sometimes happens!).
Possible problems:
.I /usr/include
is hardwired into the code; if you use
.I gcc ,
the library path is hardwired, too.
.LP
.Sy DependDir "varies" general
.IP
Path to
.I makedepend
sources.
The default is dependent on UseCCMakeDepend.
.LP
.Sy ContribDir $(TOP)/../contrib general
.IP
Top of user-contributed source tree.
.LP
.Sy DependCmd $(DEPENDSRC)/makedepend general
.IP
Command to run
.I makedepend.
.LP
.Sy RemoveTargetProgramByMoving NO boolean
.IP
This symbol affects expansion of the RemoveProgramTarget() rule.
``Program'' in that rule's name is misleading; it can be used to remove any
file, not just programs.
.LP
.Sy AllocateLocalDefines nothing general
.IP
\-D's to turn on
.I alloca ().
.LP
.Sy SharedLibX varies boolean
.Sy SharedOldLibX varies boolean
.Sy SharedLibXt varies boolean
.Sy SharedLibXaw varies boolean
.Sy SharedLibXmu varies boolean
.Sy SharedLibXext varies boolean
.IP
Whether to build shared versions of the X, old X, X Toolkit, X Athena
Widget, X mu or X Extension libraries.
The defaults are YES if HasSunOSSharedLibraries is YES, NO otherwise.
.LP
.Sy SharedXlibRev 4.2 general
.Sy SharedOldXRev 4.0 general
.Sy SharedXtRev 4.0 general
.Sy SharedXawRev 4.0 general
.Sy SharedXmuRev 4.0 general
.Sy SharedXextRev 4.0 general
.IP
Version (revision) numbers of shared libraries.
.LP
.Sy HasInputExtension YES boolean
.IP
Whether there are any input extensions.
.LP
.Sy DoInstallExtensionsIntoXlib NO boolean
.IP
Whether the extension library should be merged into the X library.
.LP
.Sy BandAidLibraryNeeded YES boolean
.Sy BandAidLibrarySources Berklib.c general
.Sy BandAidLibraryObjects Berklib.o general
.LP
.LP
.Sy BandAidLibraryMake() "take a look" general
.LP
.LP
.Sy BandAidLibraryNeeded NO boolean
.IP
Whether a band-aid library is needed.
This will be YES if NeedBerklibInXlib is YES.
.IP
I'm not sure what all the band-aid stuff is for.
Perhaps for BSD socket emulation on System V platforms.
.LP
.Sy XawClientDepLibs "$(DEPXAWLIB) $(DEPXMULIB) $(DEPXTOOLLIB) $(DEPXLIB)" general
.IP
Library dependencies for clients using the Athena Widgets (DEPLIBS).
.LP
.Sy XawClientLibs "$(XAWLIB) $(XMULIB) $(XTOOLLIB) $(XLIB)" general
.IP
Library needed by clients using the Athena Widgets (LOCAL_LIBRARIES).
.LP
.Sy NeedDefaultDepLibs YES boolean
.LP
Affects the definitions of DEPLIBS, DEPLIBS1, DEPLIBS1, DEPLIBS3.
.LP
.NH 2
Make Variables
.LP
Many of the
.I make
variables in
.I Project.tmpl ,
like those in
.I Imake.tmpl ,
bear a direct name relationship to proprocessor symbols with which they are
associated.
.LP
Since much of the project source and installation directory layout
is specified in this file, the number of variables defined in terms of other
.I make
variables (e.g., XMUSRC = $(LIBSRC)Xmu, DEMOSRC = $(TOP)/demos) is quite large.
.NH
Imake.rules
.LP
The X
.I Imake.rules
file rule definitions make heavy use of the following techniques:
.IP (1)
Use of the ``::'' construct is quite prevalent.
In a
.I make
rule, if a target name is followed by ``:'', it's assumed to be the
only rule for that target.
If another rule with the same target is found, it's an error.
If target names are followed by ``::'', there may be multiple rules
for the targets.
The X configuration files rely on this property of ``::'' in the
following ways:
.RS
.IP (a)
To make sure that certain targets are always present in the
.I Makefile ,
even if they are not otherwise generated from expansion of the macros
in
.I Imakefile .
This way, subdirectory-traversing
.I make
operations can rely on those targets being present.
For instance, many rules that build programs automatically generate a
``clean'' target to remove the program.
But if no such rule is used in the
.I Imakefile ,
there might be no ``clean'' target in the
.I Makefile ,
and ``make clean'' fails.
That's not a disaster, but a ``make clean'' from the root of the
source tree can result in a lot of apparent errors.
To avoid this, an empty ``clean'' target is written to the
.I Makefile ,
using ``clean::''.
If there is another ``clean'' target, the empty one doesn't hurt anything.
If there isn't, the empty one prevents error messages.
.IP
Other default targets generated are ``tags'', ``install'',
``install.man'', ``Makefile'', ``Makefiles'' and ``includes''.
.IP (b)
To allow commands like ``make all'' to trigger builds of an arbitrary
number of targets.
Without the ``::'' construct, the configuration process would need to
be able to determine exactly which targets ``make all'' should
generate, and produce a single ``all: target1 target2 ...'' rule.
This would be a difficult task.
Using ``::'', each program-building rule can generate its own ``all::
target'' and they are all triggered.
.RE
.IP (2)
Definitions are allowed to be overridden.
All rules are defined using the following construct:
.Ds .IP
# ifndef \fIrulename\fR
# define \fIrulename(arguments)\fR ...
# endif
.De .IP
This should look familiar because it's the same construct used
in the other configuration files to allow symbol values to be overridden.
Since
.I Imake.rules
is the last configuration file read during a
.I Makefile
build,
.I any
of its rules may be redefined.
Doing so can have far-reaching consequences, of course, so that's not
something you want to do without thinking it through first.
Nevertheless, it's sometimes useful, or even necessary.
.IP
The likely places for such overriding to occur are:
.IP
.I platform.cf \*-if
a system does things in some strange way that's
not easy to compensate for by defining the usual configuration symbols
properly.
For example, the file
.I sgi.cf
redefines a couple of rules, to account for non-standard file
extensions.
.IP
.I site.def \*-if
a rule just isn't right for your site, for some reason.
.IP
.I Imakefile \*-it's
sometimes useful to override a rule in a particular directory, which
can be done by defining the rule in that directory's
.I Imakefile .
The file
.I config/Imakefile
does this, for instance.
Such redefinitions do
.I not
carry down through subdirectories.
Also, since
.I Imake.rules
is seen before
.I Imakefile ,
you need to #undef the macro before redefining it.
.IP (3)
If a directory has subdirectories, and
.I make
operations in that directory should recurse down through the
subdirectories, there should be a line that says
.Ds .IP
# define IHaveSubdirs
.De .IP
at the top of the
.I Imakefile .
This causes recursive ``install'', ``install.man'',
``clean'', ``tags'', ``Makefile'' and ``includes'' target rules to be
written into the
.I Makefile
(see end of
.I Imake.tmpl ;
the
.I make
variable SUBDIRS should set to the names of the subdirectories involved, as
well).
If you want CDEBUGFLAGS passed along to subdirectories, put another
line at the top of the
.I Imakefile
that says
.Ds .IP
# define PassCDebugFlags 'CDEBUGFLAGS=$(CDEBUGFLAGS)'
.De .IP (4)
As you scan through the rules, you'll notice that
.I if
constructs are not written like this:
.Ds .IP
if \fIcondition\fR then; \fIaction\fR; fi
.De .IP
Instead, they're written like this:
.Ds .IP
if \fIcondition\fR then; \fIaction\fR; else exit 0; fi
.De .IP
The reason for this is to deal with differing behaviors of
.I if
on various systems.
On some systems, if you write ``if \fIcondition\fR; then \fIaction\fR; fi''
and
.I condition
is false, the value of the statement is zero (on the grounds that the
test executed to completion without error).
On other systems, the value of the statement is non-zero (on the grounds
that the test failed).
The latter behavior is broken behavior; Ultrix in particular is guilty
of it.
.IP
In the X rules,
.I if
tests are usually used to check whether some preliminary action needs to be
performed before proceeding to the next step.
Systems that return false when the
.I if
test fails cause
.I make
to exit early if the preliminary action does not need to be done, and
the next step is\*-incorrectly\*-never executed.
.IP
In order to get around this, all
.I if
statements explicitly include an
.I else
clause to return zero when the condition fails, so that
.I make
will continue whether the condition is true or not.
.NH 2
Commonly Used Rules
.LP
Rules for building programs:
.Ds
NormalProgramTarget()
SimpleProgramTarget()
ComplexProgramTarget()
ComplexProgramTarget_1()
ComplexProgramTarget_2()
ComplexProgramTarget_3()
.De
Rules for building shell scripts:
.Ds
CppScriptTarget()
MakeScriptFromCpp()
.De
Rules for building libraries:
.Ds
NormalLibraryObjectRule()
NormalLibraryTarget()
.De
Rules for installing files:
.Ds
InstallProgram()
InstallLibrary()
InstallManPage()
InstallNonExec()
InstallSubdirs()
.De
Rules for cleaning up:
.Ds
RemoveTargetProgram()
CleanTarget()
CleanSubdirs()
.De
Rules for generating Makefiles and dependencies:
.Ds
MakefileTarget()
MakefileSubdirs()
DependTarget()
DependSubdirs()
.De
Many rules that compile programs also generate ``clean'' and ``all''
targets.
.NH 2
Rule Descriptions
.LP
Each rule-generating macro in
.I Imake.rules
is described below, in the order in which they appear in that file.
You should still read through the text of a rule before you use it
to write your own
.I Imakefile .
.LP
.B Disclaimer:
I myself do not, for the most part, use the X rules, except in
modified form for my own projects.
There are likely to be a number of errors of understanding here.
.LP
.Ru SaberProgramTarget(program,srclist,objlist,locallibs,syslibs)
.IP
If HasSaberC is NO, this is a nop, otherwise it expands to a rule for
``saber-\fIprogram\fR'' and causes Saber C to load source and object
files for the program.
Odd that ``#'' is in front of the rules, though.
.LP
.Ru RemoveTargetProgram(program)
.IP
Removes
.I program
(actually this symbol is misnamed because it can be used to remove any
file, not just programs).
If RemoveTargetProgramByMoving (from
.I Project.tmpl )
is YES,
.I program
is moved to
.I program~
instead.
This allows you to keep the previous version around.
Note that ``*~'' is in the list of files removed by CleanTarget(), so
unless you override FilesToClean, ``make clean'' will remove these
previous target versions.
.LP
.Ru BuildIncludes(srclist,dstsubdir,dstupdir)
.IP
Builds the header file directories in the source tree,
and populates them.
.LP
.Ru NormalProgramTarget(program,objects,deplibs,locallibs,syslibs)
.IP
Builds one program.
All object files and libraries are explicitly listed in the macro invocation.
.I program
is the program to be built.
.I objects
names the object files needed to build it from, e.g.,
.I junk.o .
.I deplibs
names the libraries that must exist before linking is done.
.I locallibs
names the libraries in the source tree that should be linked in.
.I syslibs
names the system libraries (e.g., in
.I /usr/lib )
that should be linked in.
These are named with
.I \-l ,
e.g.,
.I \-lm .
.IP
A ``clean'' rule is also generated to remove the program (but not the
objects).
.IP
Since this rule does not assume any default sources, you can use it
several times in an
.I Imakefile
to build multiple programs.
You should also set SRCS to the names of all the programs'
source files and invoke DependTarget() in the
.I Imakefile .
Also invoke AllTarget(), giving it the names
of all programs to build, and you'll need to include a rule to
generate
an ``install'' target for each program and an ``install.man'' target if
there is a manual page.
If you're a lint kind of person, you'll also want
LintTarget().
.LP
.Ru SingleProgramTarget(program,objects,locallibs,syslibs)
.IP
This rule is deprecated.
Don't use it.
.LP
.Ru SimpleProgramTarget(program)
.IP
This macro is used when the
.I Imakefile
is supposed to build a single program, and that program consists of a single
source file.
The macro sets SRCS to
.I program.c ,
OBJS to
.I program.o
and calls ComplexProgramTarget().
The effect is to set up everything to generate rules to build the program,
install it and its man page, clean the program, generate dependencies,
and lint the program.
A real whiz bang.
See description of ComplexProgramTarget().
.LP
.Ru ComplexProgramTarget(program)
.IP
This macro is used in an
.I Imakefile
that builds a single program.
Given the name of the program, rules are generated to build it, as well as
generate ``all'', ``install'', ``install.man'', ``depend'' and ``lint''
targets, and to remove the program.
Several assumptions are made by this macro:
.RS
.IP (1)
SRCS has been set to the list of source files (so the ``depend'' target works).
.IP (2)
OBJS has been set to the list of object files (so the program build works).
.IP (3)
The
.I deplibs ,
.I locallibs
and
.I syslibs
arguments as used in NormalProgramTarget() are assumed to be DEPLIBS,
LOCAL_LIBRARIES and LDLIBS.
.RE
.LP
.Ru ComplexProgramTarget_1(program,locallib,syslib)
.br
.Ru ComplexProgramTarget_2(program,locallib,syslib)
.br
.Ru ComplexProgramTarget_3(program,locallib,syslib)
.IP
These rules are use in an
.I Imakefile
that builds 1, 2 or 3 programs.
Actually, just 2 or 3 programs.
If you were building a single program, you'd use ComplexProgramTarget().
Each macro takes 3 arguments.
.I program
is the name of the program to build.
.I locallib
names libraries built in the source tree that should be linked in
(e.g., XMULIB).
.I syslib
names system libraries to be linked in (e.g.,
.I \-lm ).
.IP
The values of certain
.I make
variables are assumed to be set (by you).
SRCS1, SRCS2 and SRCS3 name the sources for each program.
(These are used to set SRCS so the ``depend'' target works.)
OBJS1, OBJS2 and OBJS3 name the objects for each program.
DEPLIBS1, DEPLIBS2 and DEPLIBS3 name the library dependencies for each program.
PROGRAMS names the programs to be built.
.IP
If you're only building 2 programs, then SRCS3, OBJS3, etc., do not
need to be set and will be assumed to have the empty value.
PROGRAMS should be the names of 2 programs, not 3.
.LP
.Ru ServerTarget(server,subdirs,objects,libs,syslibs)
.IP
Generates rules to build a server.
.I libs
doubles as
.I deplibs
and
.I locallibs
as those are used in NormalProgramTarget().
The directories named by
.I subdirs
are used as dependencies and must exist before the target can be built.
.LP
.Ru InstallLibrary(libname,dest)
.IP
Installs
.I liblibname.a
into
.I dest/liblibname.a
and runs the command named by RANLIB on it.
The installation flags INSTLIBFLAGS are used.
.LP
.Ru MergeIntoInstalledLibrary(tolib,fromlib)
.IP
Merges
.I fromlib
into
.I tolib
using the
.I mergelib
script in the SCRIPTSRC directory.
.LP
.Ru InstallSharedLibrary(libname,rev,dest)
.IP
Installs
.I liblibname.so.rev
into
.I dest/liblibname.so.rev ,
using INSTLIBFLAGS.
.LP
.Ru InstallSharedLibraryData(libname,rev,dest)
.IP
Installs
.I liblibname.sa.rev
into
.I dest/liblibname.sa.rev ,
using INSTLIBFLAGS.
.LP
.Ru InstallLibraryAlias(libname,alias,dest)
.IP
In
.I dest ,
makes
.I libalias.a
an alias for
.I liblibname.a
by generating a link.
.LP
.Ru InstallLintLibrary(libname,dest)
.IP
Installs
.I llib-llibname.ln
into the
.I dest
directory using library installation flags INSTLIBFLAGS.
.LP
.Ru InstallManPageLong(file,destdir,dest)
.IP
Generate rule to install a manual page and rename it.
The source manual page is
.I file.man
and is installed in
.I destdir/dest. ManSuffix
using installation flags INSTMANFLAGS.
This is used to install pages whose names are long enough to tickle
brain damage on systems that don't understand long file names.
.LP
.Ru InstallManPage(file,dest)
.IP
Generate rule to install the manual page
.I file.man
in
.I dest/file. ManSuffix
using installation flags INSTMANFLAGS.
.LP
.Ru InstallNonExec(file,dest)
.IP
Generate rules to install a non-executable file using installation
flags INSTDATFLAGS.
.LP
.Ru InstallProgramWithFlags(program,dest,flags)
.IP
Generate rules to install an executable program using the specified
flags.
.LP
.Ru InstallProgram(program,dest)
.IP
Generate rules to install an executable program.
The comments in
.I Imake.rules
for this macro say something about INSTALLFLAGS, but that variable
isn't actually used in the expansion of this macro, so I claim the
flags used are
simply INSTPGMFLAGS until someone demonstrates otherwise.
.LP
.Ru InstallScript(program,dest)
.IP
Generate rules to install
.I program.script
into
.I dest/program
using installation flags INSTPGMFLAGS.
.IP
This rule is obsolete.
Use CppScriptTarget() and InstallProgram().
.LP
.Ru LinkFileList(step,list,dir,sub)
.IP
Generates rules for a target
.I step
to make links to all files in
.I list
in directory
.I dir .
The links are created in directory
.I sub .
Judging from the definition of this macro,
.I sub
is presumably so named because the rule changes directories into
.I dir
first and appears to expect
.I sub
to be a subdirectory.
(Strictly speaking, that need not be true, since
(i)
.I sub
could legally be an absolute path;
(ii)
.I sub
could have a value such as ``../..''.
But both those possibilities probably subvert the intent of the
macro.)
.LP
.Ru InstallMultipleDestFlags(step,list,dest,flags)
.IP
Generates rules for a target
.I step
(e.g., ``install'') to install all the files in
.I list
into the directory
.I dir
using installation flags
.I flags .
The files in
.I list
are made the rule dependencies.
.LP
.Ru InstallMultipleDest(step,list,dest)
.IP
Like InstallMultipleDestFlags(), but assuming INSTALLFLAGS as the
installation flags.
Note: INSTALLFLAGS is not set by the X configuration files;
you must give it a value in your
.I Imakefile .
.LP
.Ru InstallMultiple(list,dest)
.IP
Like InstallMultipleDest(), but assuming ``install'' as the
.I step
argument.
.LP
.Ru InstallMultipleFlags(list,dest,flags)
.IP
Like InstallMultipleDestFlags(), but assuming ``install'' as the
.I step
argument.
.LP
.Ru InstallMultipleMan(list,dest)
.IP
Like InstallMultipleDest(), but assuming ``install.man'' as the
.I step
argument.
.LP
.Ru InstallAppDefaults(class)
.IP
If InstallAppDefFiles (from
.I Project.tmpl )
is #define'd, generates an ``install'' target to install
.I class.ad
into
.I $(XAPPLOADDIR)/class
using installation flags INSTAPPFLAGS.
.IP
INSTAPPFLAGS appears to be deprecated in
.I Project.tmpl .
.LP
.Ru DependDependency()
.IP
If UseInstalled is not #define'd, this macro generates rules to check for the
existence of
.I makedepend
in the source tree and build it if it's missing.
This differs from the R3 rules, which failed if
.I makedepend
was missing.
.LP
.Ru DependTarget()
.IP
Generate rule to determine dependencies for source files named by SRCS.
You have to define the value of SRCS yourself, unless you are using
rules such as
SimpleProgramTarget() or ComplexProgramTarget_{1,2,3}(), which do it
for you.
In the latter case, you need to define SRCS1, SRCS2 and SRCS3.
.IP
This macro uses DependDependency() to check for the existence of
.I makedepend
and build it if necessary.
.LP
.Ru CleanTarget()
.IP
Removes all the files named by FilesToClean and files whose names
begin with ``#''.
.IP
To understand how this rule works, see how RM_CMD is defined in
.I Imake.tmpl .
.LP
.Ru TagsTarget()
.IP
Generate rule to build a
.I TAGS
file from all
.I *.c
and
.I *.h
files.
.LP
.Ru ImakeDependency(target)
.IP
If UseInstalled is not #define'd, this macro generates rules to check for the
existence of
.I imake
in the source tree and build it if it's missing.
This differs from the R3 rules, which failed if
.I imake
was missing.
.LP
.Ru BuildMakefileTarget(imakefile,imakeflags)
.IP
Generate rules to build
.I Makefile .
The
.I imakefile
argument is superfluous (a bug?).
Since it's ignored,
.I Imakefile
is assumed as the source from which to build
.I Makefile .
.I imakeflags
is any special flags you want passed to the
.I imake
command.
.IP
This macro uses ImakeDependency() to check for the existence of
.I imake
and build it if necessary.
.IP
You don't use this rule explicitly unless you've #define'd
IHaveSpecialMakefileTarget in your
.I Imakefile .
.LP
.Ru MakefileTarget()
.IP
Generate rules to build a
.I Makefile
target from
.I Imakefile ,
so you can say ``make Makefile''.
This target is automatically included in your
.I Makefile
when it is rebuilt by
.I imake ,
unless ``#define IHaveSpecialMakefileTarget'' is present
in your
.I Imakefile ,
in which case you should include an invocation of
BuildMakefileTarget() to build
.I Makefile .
.LP
.Ru NormalLibraryObjectRule()
.IP
Generate rule to turn a
.I .c
file into a
.I .o
file.
Include this macro (once) in your
.I Imakefile
if you're building a library from C source.
.LP
.Ru NormalFortranObjectRule()
.IP
Generate rule to turn a
.I .f
file into a
.I .o
file.
Include this macro (once) in your
.I Imakefile
if you're building a library from FORTRAN source.
(FORTRAN?
Isn't that something used to build COBOL compilers?)
.LP
.Ru ProfiledLibraryObjectRule()
.IP
Like NormalLibraryObjectRule(), but in addition to building the normal
target, a profiled target is built in the
.I profiled
subdirectory of the current directory.
.I profiled
is created if necessary.
A ``clean'' target to remove profiled objects is also generated.
.LP
.Ru DebuggedLibraryObjectRule()
.IP
Like ProfiledLibraryObjectRule(), but instead of profiled targets in
.I profiled ,
debuggable targets are built in the
.I debugger
subdirectory.
.LP
.Ru DebuggedAndProfiledLibraryObjectRule()
.IP
A combination of ProfiledLibraryObjectRule() and DebuggedLibraryObjectRule().
.LP
.Ru SharedLibraryObjectRule()
.IP
Like ProfiledLibraryObjectRule(), but instead of profiled targets in
.I profiled ,
sharable targets are built in the
.I shared
subdirectory.
.LP
.Ru SharedAndDebuggedLibraryObjectRule()
.IP
A combination of SharedLibraryObjectRule() and DebuggedLibraryObjectRule().
.LP
.Ru SpecialSharedAndDebuggedObjectRule(objs,depends,options)
.IP
Like SharedAndDebuggedLibraryObjectRule(), but allows targets
.I objs ), (
dependencies and special compiler flags to be specified.
.LP
.Ru SpecialSharedObjectRule(objs,depends,options)
.IP
Like SharedLibraryObjectRule(), but allows targets
.I objs ), (
dependencies and special compiler flags to be specified.
.LP
.Ru SpecialObjectRule(objs,depends,options)
.IP
Like NormalLibraryObjectRule(), but allows targets
.I objs ), (
dependencies and special compiler flags to be specified.
.LP
.Ru SpecialProfiledObjectRule(objs,depends,options)
.IP
Like ProfiledLibraryObjectRule(), but allows targets
.I objs ), (
dependencies and special compiler flags to be specified.
.LP
.Ru SpecialDebuggedObjectRule(objs,depends,options)
.IP
Like DebuggedLibraryObjectRule(), but allows targets
.I objs ), (
dependencies and special compiler flags to be specified.
.LP
.Ru SpecialDebuggedAndProfiledObjectRule(objs,depends,options)
.IP
Like DebuggedAndProfiledLibraryObjectRule(), but allows targets
.I objs ), (
dependencies and special compiler flags to be specified.
.LP
.Ru NormalLibraryTarget(libname,objlist)
.IP
Generate rules to create the library
.I liblibname.a
from the object files named by
.I objlist .
The library is RANLIB'd after being created.
.LP
.Ru NormalSharedLibraryTarget(libname,rev,solist)
.IP
Generate rules to create a shared library
.I liblibname.so.rev .
The library is created under a different name and then moved onto the
target name to maximize availability of any existing version.
.LP
.Ru NormalSharedLibraryDataTarget(libname,rev,salist)
.IP
Like NormalSharedLibraryTarget(), but for shared data
.I liblibname.sa.rev .
The comments claim
the library is created under a different name and then moved onto the
target name as for NormalSharedLibraryTarget() but that doesn't appear
to be true from the text of the macro.
.LP
.Ru NormalLibraryTarget2(libname,objlist1,objlist2)
.IP
Like NormalLibraryTarget(), but adds two lists of files to the
library, in two steps.
Used to create libraries with large numbers of files.
.LP
.Ru ProfiledLibraryTarget(libname,objlist)
.IP
Generate rules to create the library
.I liblibname_p.a
from the profiled objects in the
.I profiled
subdirectory.
.LP
.Ru DebuggedLibraryTarget(libname,objlist)
.IP
Generate rules to create the library
.I liblibname_d.a
from the debuggable objects in the
.I debugger
subdirectory.
.LP
.Ru AliasedLibraryTarget(libname,alias)
.IP
Generate rules to make
.I libalias.a
a link to
.I liblibname.a .
.LP
.Ru NormalRelocatableTarget(objname,objlist)
.IP
Generate rules to produce a relocatable object file
.I objname.o
from the object files named in
.I objlist .
This is built using the loader LD, called with flags LDCOMBINEFLAGS.
.LP
.Ru ProfiledRelocatableTarget(objname,objlist)
.IP
Like NormalRelocatableTarget(), but builds
.I objname_p.o
and uses loader flag
\-X instead of LDCOMBINEFLAGS, to produce a profiled relocatable
object file.
.LP
.Ru DebuggedRelocatableTarget(objname,objlist)
.IP
Like NormalRelocatableTarget(), but builds
.I objname_d.o
and uses loader flag
\-X instead of LDCOMBINEFLAGS, to produce a debuggable relocatable
object file.
.LP
.Ru LintLibraryTarget(libname,srclist)
.IP
Generate rules for a ``lintlib'' target that builds
.I llib-llibname.ln
from the source files named by
.I srclist .
.LP
.Ru NormalLintTarget(srclist)
.IP
Generate rules for a ``lint'' target that lints the source files named
by
.I srclist ,
and for a ``lint1'' target that lints the file named by the
.I make
variable FILE (which you must set in
.I Imakefile ).
.LP
.Ru LintTarget()
.IP
Generate rules to lint files named by SRCS.
SRCS might be set by you in
.I Imakefile ,
or, if you invoke macros such as SimpleProgramTarget() or
ComplexProgramTarget_{1,2,3}(), it will be done for you
automatically.
.LP
.Ru LinkSourceFile(src,dir)
.IP
Generate rule to make a link to a file in another directory.
The macro can be used to create links
to non-source files, too, of course.
.LP
.Ru MakeSubincludesForBuild(step,dir,srclist)
.IP
Generate rules for target
.I step
to ... to ... uh, I don't know!
.LP
.Ru NamedTargetSubdirs(name,dirs,verb,flags,subname)
.IP
Generate rules for a target
.I name
(e.g., ``depend'', ``install'') that causes the target
.I subname
to be built in the subdirectories named by
.I dirs .
This is done by changing into each subdirectory in turn and invoking
.I make
for the
.I subname
target.
.I flags
is any extra flags that should be passed to those
.I make
processes.
.I verb
is the -ing form of
.I name ,
e.g., if
.i name
is ``make'', then
.I verb
is ``making''.
This is used to echo an indication of what
.I make
is doing in each directory as it proceeds.
.IP
This macro is used by virtually all other macros that have names like
XXXSubdirs().
.LP
.Ru NamedMakeSubdirs(name,dirs)
.IP
Invokes NamedTargetSubdirs() to generate rules for a target
.I name
that causes the ``all'' target to be built in the
subdirectories named by
.I dirs .
.IP
If you want CDEBUGFLAGS passed to the
.I make
processes forked in each subdirectory, the
.I Imakefile
should have a line at the top that says:
.RS
.Ds
# define PassCDebugFlags 'CDEBUGFLAGS=$(CDEBUGFLAGS)'
.De
.RE
.LP
.Ru MakeSubdirs(dirs)
.IP
Equivalent to NamedMakeSubdirs(all,dirs).
.LP
.Ru DependSubdirs(dirs)
.IP
Invokes NamedTargetSubdirs() to generate rules for a ``depend''
target that causes the ``depend'' target to be built in the
subdirectories named by
.I dirs .
.LP
.Ru InstallSubdirs(dirs)
.IP
Invokes NamedTargetSubdirs() to generate rules for a ``install''
target that causes the ``install'' target to be built in the
subdirectories named by
.I dirs .
.IP
This macro is automatically invoked if IHaveSubdirs is #define'd in
.I Imakefile ,
in which case SUBDIRS should be set to the names of the subdirectories
involved.
.LP
.Ru InstallManSubdirs(dirs)
.IP
Invokes NamedTargetSubdirs() to generate rules for a ``install.man''
target that causes the ``install.man'' target to be built in the
subdirectories named by
.I dirs .
.IP
This macro is automatically invoked if IHaveSubdirs is #define'd in
.I Imakefile ,
in which case SUBDIRS should be set to the names of the subdirectories
involved.
.LP
.Ru IncludesSubdirs(dirs)
.IP
Invokes NamedTargetSubdirs() to generate rules for a ``includes''
target that causes the ``includes'' target to be built in the
subdirectories named by
.I dirs .
.IP
This macro is automatically invoked if IHaveSubdirs is #define'd in
.I Imakefile ,
in which case SUBDIRS should be set to the names of the subdirectories
involved.
.LP
.Ru NamedCleanSubdirs(name,dirs)
.IP
Invokes NamedTargetSubdirs() to generate rules for a target
.I name
that causes the ``clean'' target to be built in the
subdirectories named by
.I dirs .
.LP
.Ru CleanSubdirs(dirs)
.IP
Equivalent to NamedCleanSubdirs(clean,dirs).
.IP
This macro is automatically invoked if IHaveSubdirs is #define'd in
.I Imakefile ,
in which case SUBDIRS should be set to the names of the subdirectories
involved.
.LP
.Ru NamedTagSubdirs(name,dirs)
.IP
Invokes NamedTargetSubdirs() to generate rules for a target
.I name
that causes the ``tags'' target to be built in the
subdirectories named by
.I dirs .
.LP
.Ru TagSubdirs(dirs)
.IP
Equivalent to NamedTagSubdirs(tags,dirs).
.IP
This macro is automatically invoked if IHaveSubdirs is #define'd in
.I Imakefile ,
in which case SUBDIRS should be set to the names of the subdirectories
involved.
.LP
.Ru MakeLintSubdirs(dirs,target,subtarget)
.IP
Invokes NamedTargetSubdirs() to generate rules for a target
.I target
that causes the target
.I subtarget
to be built in the subdirectories named by
.I dirs .
.LP
.Ru LintSubdirs(dirs)
.IP
Equivalent to MakeLintSubdirs(dirs,lint,lint).
.IP
This macro is
.I not
automatically invoked if IHaveSubdirs is #define'd in
.I Imakefile ;
you need to do so yourself.
.LP
.Ru MakeLintLibSubdirs(dirs)
.IP
Equivalent to MakeLintSubdirs(dirs,lintlib,lintlib).
.LP
.Ru MakeMakeSubdirs(dirs,target)
.IP
Generate rules for a target
.I target
to generate a
.I Makefile
in the subdirectories named by
.I dirs .
.IP
In R4, ``Makefiles'' rules handle values of ${TOP} that are either
relative or absolute.
The R3 rule only handled relative values.
.LP
.Ru MakeNsubdirMakefiles()
.IP
Generate a set of very very very ugly but quite wonderful rules for
use by MakeMakeSubdirs().
Automatically invoked by MakefileSubdirs(); you shouldn't need to do
so yourself.
.LP
.Ru MakefileSubdirs(dirs)
.IP
Generate rules to build ``Makefiles''
targets in the given subdirectories.
.IP
This macro is automatically invoked if IHaveSubdirs is #define'd in
.I Imakefile ,
in which case SUBDIRS should be set to the names of the subdirectories
involved.
.LP
.Ru CppScriptTarget(dst,src,defs,deplist)
.IP
Generate rules to build a shell script
.I dst
from
.I src .
It figures out how to do this correctly for the current platform
depending on the value of ExecableScripts.
.I defs
is any extra flags, such as \-D's, to pass through to the
preprocessor.
.I deplist
names any targets that must exist before
.I dst
can be built.
.LP
.Ru MakeScriptFromCpp(name,defs)
.IP
Generate rule to build a script
.I name
from
.I name.cpp .
.I defs
is as for CppScriptTarget().
.LP
.Ru MakeDirectories(step,dirs)
.IP
Generate rules for target
.I step
to create the directories named by
.I dirs .
This is often used to make sure that installation directories exist
before trying to install files in them.
(Not all verions of
.I install
create missing directories.)
.LP
.Ru MakeFonts()
.IP
Generate rules for ``fonts.dir'' target to build font database
.I fonts.dir .
The
.I make
variable OBJS must be set to the name of the files that should exist
before the database is built.
.LP
.Ru InstallFonts(dest)
.IP
Generate rules to install the directory
.I fonts.dir
into
.I dest
using installation flags INSTDATFLAGS.
.LP
.Ru InstallFontAliases(dest)
.IP
Generate rules to install font alias database
.I fonts.alias
into
.I dest
using installation flags INSTDATFLAGS.
.LP
.Ru FontTarget(basename)
.IP
Generate rules to create a font file by converting
.I basename.bdf
to
.I basename.snf .
.LP
.Ru CompressedFontTarget(basename)
.IP
Generate rules to create a compressed font file by converting
.I basename.bdf
(to
.I basename.snf.Z ,
I suppose).
.LP
.Ru AllTarget(depends)
.IP
Generate rule for an ``all'' target to build targets named by
.I depends .
.LP
.NH
Imakefile
.LP
If HasSaberC is #define'd, some special Saber-C rules are generated.
.LP
Some symbols that you may want to #define (as nothing) at the top of
.I Imakefile
are:
.LP
.Ru IHaveSpecialMakefileTarget
.IP
If not #define'd (the normal case), MakefileTarget() is automatically
invoked.
If #define'd, it's assumed that you want to explicitly invoke a
.I Makefile -building
macro yourself.
.LP
.Ru MakefileAdditions
.IP
If #define'd, MakefileAdditions() is automatically invoked.
However, MakefileAdditions() appears not to be defined
anywhere, and I have no idea what it is supposed to do.
.LP
.Ru IHaveSubdirs
.IP
If #define'd, you should set SUBDIRS to the names of the current
directory's subdirectories, and subdirectory-traversing rules for
generating ``Makefile'', ``install'', ``install.man'', ``clean'',
``tags'' and ``includes'' targets will be automatically invoked.