xenocara/util/imake/imake.man

.\" Copyright (c) 1993, 1994, 1998 The Open Group
.\"
.\" Permission to use, copy, modify, distribute, and sell this software and its
.\" documentation for any purpose is hereby granted without fee, provided that
.\" the above copyright notice appear in all copies and that both that
.\" copyright notice and this permission notice appear in supporting
.\" documentation.
.\"
.\" The above copyright notice and this permission notice shall be included
.\" in all copies or substantial portions of the Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
.\" OTHER DEALINGS IN THE SOFTWARE.
.\"
.\" Except as contained in this notice, the name of The Open Group shall
.\" not be used in advertising or otherwise to promote the sale, use or
.\" other dealings in this Software without prior written authorization
.\" from The Open Group.
.\"
.TH IMAKE 1 __xorgversion__
.SH NAME
imake \- C preprocessor interface to the make utility
.SH SYNOPSIS
\fBimake\fP [ \fB\-D\fP\fIdefine\fP ] [ \fB\-I\fP\fIdir\fP ]
[ \fB\-U\fP\fIdefine\fP ]
[ \fB\-T\fP\fItemplate\fP ]
[ \fB\-f\fP \fIfilename\fP ] [ \fB\-C\fP \fIfilename\fP ]
[ \fB\-s\fP \fIfilename\fP ] [ \fB\-e\fP ]
[ \fB\-v\fP ]
.SH DESCRIPTION
.I Imake
is used to
generate \fIMakefiles\fP from a template, a set of \fIcpp\fP macro functions,
and a per-directory input file called an \fIImakefile\fP.  This allows machine
dependencies (such as compiler options, alternate command names, and special
\fImake\fP rules) to be kept separate from the descriptions of the
various items to be built.
.SH OPTIONS
The following command line options may be passed to \fIimake\fP:
.TP 8
.B \-D\fIdefine\fP
This option is passed directly to \fIcpp\fP.  It is typically used to set
directory-specific variables.  For example, the X Window System used this
flag to set \fITOPDIR\fP to the name of the directory containing the top
of the core distribution and \fICURDIR\fP to the name of the current
directory, relative to the top.
.TP 8
.B \-I\fIdirectory\fP
This option is passed directly to \fIcpp\fP.  It is typically used to
indicate the directory in which the \fIimake\fP template and configuration
files may be found.
.TP 8
.B \-U\fIdefine\fP
This option is passed directly to \fIcpp\fP.  It is typically used to
unset variables when debugging \fIimake\fP configuration files.
.TP 8
.B \-T\fItemplate\fP
This option specifies the name of the master template file (which is usually
located in the directory specified with \fI\-I\fP) used by \fIcpp\fP.
The default is \fIImake.tmpl\fP.
.TP 8
.B \-f \fIfilename\fP
This option specifies the name of the per-directory input file.  The default
is \fIImakefile\fP.
.TP 8
.B \-C \fIfilename\fP
This option specifies the name of the .c file that is constructed in the
current directory.  The default is \fIImakefile.c\fP.
.TP 8
.B \-s \fIfilename\fP
This option specifies the name of the \fImake\fP description file to be
generated but \fImake\fP should not be invoked.
If the \fIfilename\fP is a dash (\-), the
output is written to \fIstdout\fP.  The default is to generate, but
not execute, a \fIMakefile\fP.
.TP 8
.B \-e
This option indicates the \fIimake\fP should execute the generated
\fIMakefile\fP.  The default is to leave this to the user.
.TP 8
.B \-v
This option indicates that \fIimake\fP should print the \fIcpp\fP command line
that it is using to generate the \fIMakefile\fP.
.SH "HOW IT WORKS"
\fIImake\fP invokes \fIcpp\fP with any \fI\-I\fP or \fI\-D\fP flags passed
on the command line and passes the name of a file containing the
following 3 lines:
.sp
.nf
\&		#define IMAKE_TEMPLATE "Imake.tmpl"
\&		#define INCLUDE_IMAKEFILE <Imakefile>
\&		#include IMAKE_TEMPLATE
.fi
.sp
where \fIImake.tmpl\fP and \fIImakefile\fP may be overridden by the
\fI\-T\fP and \fI\-f\fP command options, respectively.
.PP
The IMAKE_TEMPLATE typically
reads in a file containing machine-dependent parameters
(specified as \fIcpp\fP symbols), a site-specific parameters file,
a file defining variables,
a file
containing \fIcpp\fP macro functions for generating \fImake\fP rules, and
finally the \fIImakefile\fP (specified by INCLUDE_IMAKEFILE) in the current
directory.  The \fIImakefile\fP uses the macro functions to indicate what
targets should be built; \fIimake\fP takes care of generating the appropriate
rules.
.PP
.I Imake
configuration files contain two types of variables, imake variables
and make variables.  The imake variables are interpreted by cpp when
.I imake
is run.  By convention they are mixed case.  The make variables are
written into the
.I Makefile
for later interpretation by
.I make.
By convention make variables are upper case.
.PP
The rules file (usually named \fIImake.rules\fP in the configuration
directory) contains a variety of \fIcpp\fP macro functions that are
configured according to the current platform.  \fIImake\fP replaces
any occurrences of the string ``@@'' with a newline to allow macros that
generate more than one line of \fImake\fP rules.
For example, the macro
.ta 1i 1.6i 5i
.nf

\& #define	program_target(program, objlist)	@@\e
 program:	objlist		@@\e
	$(CC)  \-o  $@  objlist  $(LDFLAGS)

.fi
when called with
.I "program_target(foo, foo1.o  foo2.o)"
will expand to
.nf

 foo:	foo1.o  foo2.o
	$(CC)  \-o  $@  foo1.o  foo2.o  $(LDFLAGS)

.fi
.PP
\fIImake\fP also replaces any occurrences of the word ``XCOMM'' with
the character ``#'' to permit placing comments in the Makefile without
causing ``invalid directive'' errors from the preprocessor.
.PP
Some complex \fIimake\fP macros require generated \fImake\fP variables
local to each invocation of the macro, often because their value
depends on parameters passed to the macro.
Such variables can be created by using an \fIimake\fP variable
of the form \fBXVARdef\fP\fIn\fP, where \fIn\fP is a single digit.
A unique \fImake\fP variable will be substituted.  Later occurrences
of the variable \fBXVARuse\fP\fIn\fP will
be replaced by the variable created by the corresponding
\fBXVARdef\fP\fIn\fP.
.PP
On systems whose \fIcpp\fP reduces multiple tabs and spaces to a single
space, \fIimake\fP attempts to put back any necessary tabs (\fImake\fP is
very picky about the difference between tabs and spaces).  For this reason,
colons (:) in command lines must be preceded by a backslash (\\).
.SH "USE WITH THE X WINDOW SYSTEM"
The X Window System used \fIimake\fP extensively up through the X11R6.9
release, for both full builds within the source tree and external software.
X has since moved to GNU autoconf and automake for its build system in
X11R7.0 and later releases, but still maintains imake for building existing
external software programs that have not yet converted.
.PP
As mentioned above, two special
variables, \fITOPDIR\fP and \fICURDIR,\fP are set to make referencing files
using relative path names easier.  For example, the following command is
generated automatically to build the \fIMakefile\fP in the directory
\fIlib/X/\fP (relative to the top of the sources):
.sp
.nf
	%  ../.././config/imake  \-I../.././config  \\
		\-DTOPDIR=../../.   \-DCURDIR=./lib/X
.fi
.sp
When building X programs outside the source tree, a special symbol
\fIUseInstalled\fP is defined and \fITOPDIR\fP and
\fICURDIR\fP are omitted.  If the configuration files have been
properly installed, the script \fIxmkmf\fP(1) may be used.
.SH "INPUT FILES"
Here is a summary of the files read by
.I imake
as used by X.
The indentation shows what files include what other files.
.nf
.sp
.ta 3i
    Imake.tmpl	generic variables
        site.def	site-specific, BeforeVendorCF defined
        *.cf	machine-specific
            *Lib.rules	shared library rules
        site.def	site-specific, AfterVendorCF defined
        Imake.rules	rules
        Project.tmpl	X-specific variables
            *Lib.tmpl	shared library variables
        Imakefile
            Library.tmpl	library rules
            Server.tmpl	server rules
            Threads.tmpl	multi-threaded rules
.fi
.LP
Note that \fIsite.def\fP gets included twice, once before the
\fI*.cf\fP file and once after.  Although most site customizations
should be specified after the \fI*.cf\fP file, some, such as the
choice of compiler, need to be specified before, because other
variable settings may depend on them.
.LP
The first time \fIsite.def\fP is included, the variable BeforeVendorCF
is defined, and the second time, the variable AfterVendorCF is
defined.  All code in \fIsite.def\fP should be inside an #ifdef for
one of these symbols.
.SH FILES
.ta 3i
Imakefile.c	temporary input file for cpp
.br
/tmp/Imf.XXXXXX	temporary Makefile for -s
.br
/tmp/IIf.XXXXXX	temporary Imakefile if specified Imakefile uses # comments
.br
__cpp__	default C preprocessor
.DT
.SH "SEE ALSO"
make(1), xmkmf(1)
.br
Paul DuBois,
.I
imake-Related Software and Documentation,
http://www.snake.net/software/imake-stuff/
.br
Paul DuBois,
.I
Software Portability with imake, Second Edition,
O'Reilly & Associates, 1996.
.br
S. I. Feldman,
.I
Make \(em A Program for Maintaining Computer Programs
.SH "ENVIRONMENT VARIABLES"
The following environment variables may be set, however their use is not
recommended as they introduce dependencies that are not readily apparent
when \fIimake\fP is run:
.TP 5
.B IMAKEINCLUDE
If defined, this specifies a ``\-I'' include argument to pass to the
C preprocessor.  E.g., ``\-I/usr/X11/config''.
.TP 5
.B IMAKECPP
If defined, this should be a valid path to a preprocessor program.
E.g., ``/usr/local/cpp''.
By default,
.I imake
will use cc -E or __cpp__, depending on the OS specific configuration.
.TP 5
.B IMAKEMAKE
If defined, this should be a valid path to a make program,
such as ``/usr/local/make''.
By default,
.I imake
will use whatever
.I make
program is found using
.I execvp(3).
This variable is only used if the ``\-e'' option is specified.
.SH "AUTHOR"
Todd Brunhoff, Tektronix and MIT Project Athena; Jim Fulton, MIT X Consortium