| 1 |
.\" Copyright (c) 1993, 1994, 1998 The Open Group |
| 2 |
.\" |
| 3 |
.\" Permission to use, copy, modify, distribute, and sell this software and its |
| 4 |
.\" documentation for any purpose is hereby granted without fee, provided that |
| 5 |
.\" the above copyright notice appear in all copies and that both that |
| 6 |
.\" copyright notice and this permission notice appear in supporting |
| 7 |
.\" documentation. |
| 8 |
.\" |
| 9 |
.\" The above copyright notice and this permission notice shall be included |
| 10 |
.\" in all copies or substantial portions of the Software. |
| 11 |
.\" |
| 12 |
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS |
| 13 |
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
| 14 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
| 15 |
.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR |
| 16 |
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, |
| 17 |
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR |
| 18 |
.\" OTHER DEALINGS IN THE SOFTWARE. |
| 19 |
.\" |
| 20 |
.\" Except as contained in this notice, the name of The Open Group shall |
| 21 |
.\" not be used in advertising or otherwise to promote the sale, use or |
| 22 |
.\" other dealings in this Software without prior written authorization |
| 23 |
.\" from The Open Group. |
| 24 |
.\" |
| 25 |
.de EX |
| 26 |
.RS |
| 27 |
.nf |
| 28 |
.ft CW |
| 29 |
.. |
| 30 |
.de EE |
| 31 |
.ft |
| 32 |
.fi |
| 33 |
.RE |
| 34 |
.. |
| 35 |
.TH IMAKE 1 __xorgversion__ |
| 36 |
.SH NAME |
| 37 |
imake \- C preprocessor interface to the make utility |
| 38 |
.SH SYNOPSIS |
| 39 |
\fBimake\fP [ \fB\-D\fP\fIdefine\fP ] [ \fB\-I\fP\fIdir\fP ] |
| 40 |
[ \fB\-U\fP\fIdefine\fP ] |
| 41 |
[ \fB\-T\fP\fItemplate\fP ] |
| 42 |
[ \fB\-f\fP \fIfilename\fP ] [ \fB\-C\fP \fIfilename\fP ] |
| 43 |
[ \fB\-s\fP \fIfilename\fP ] [ \fB\-e\fP ] |
| 44 |
[ \fB\-v\fP ] |
| 45 |
.SH DESCRIPTION |
| 46 |
.I Imake |
| 47 |
is used to |
| 48 |
generate \fIMakefiles\fP from a template, a set of \fIcpp\fP macro functions, |
| 49 |
and a per-directory input file called an \fIImakefile\fP. This allows machine |
| 50 |
dependencies (such as compiler options, alternate command names, and special |
| 51 |
\fImake\fP rules) to be kept separate from the descriptions of the |
| 52 |
various items to be built. |
| 53 |
.SH OPTIONS |
| 54 |
The following command line options may be passed to \fIimake\fP: |
| 55 |
.TP 8 |
| 56 |
.B \-D\fIdefine\fP |
| 57 |
This option is passed directly to \fIcpp\fP. It is typically used to set |
| 58 |
directory-specific variables. For example, the X Window System used this |
| 59 |
flag to set \fITOPDIR\fP to the name of the directory containing the top |
| 60 |
of the core distribution and \fICURDIR\fP to the name of the current |
| 61 |
directory, relative to the top. |
| 62 |
.TP 8 |
| 63 |
.B \-I\fIdirectory\fP |
| 64 |
This option is passed directly to \fIcpp\fP. It is typically used to |
| 65 |
indicate the directory in which the \fIimake\fP template and configuration |
| 66 |
files may be found. |
| 67 |
.TP 8 |
| 68 |
.B \-U\fIdefine\fP |
| 69 |
This option is passed directly to \fIcpp\fP. It is typically used to |
| 70 |
unset variables when debugging \fIimake\fP configuration files. |
| 71 |
.TP 8 |
| 72 |
.B \-T\fItemplate\fP |
| 73 |
This option specifies the name of the master template file (which is usually |
| 74 |
located in the directory specified with \fI\-I\fP) used by \fIcpp\fP. |
| 75 |
The default is \fIImake.tmpl\fP. |
| 76 |
.TP 8 |
| 77 |
.B \-f \fIfilename\fP |
| 78 |
This option specifies the name of the per-directory input file. The default |
| 79 |
is \fIImakefile\fP. |
| 80 |
.TP 8 |
| 81 |
.B \-C \fIfilename\fP |
| 82 |
This option specifies the name of the .c file that is constructed in the |
| 83 |
current directory. The default is \fIImakefile.c\fP. |
| 84 |
.TP 8 |
| 85 |
.B \-s \fIfilename\fP |
| 86 |
This option specifies the name of the \fImake\fP description file to be |
| 87 |
generated but \fImake\fP should not be invoked. |
| 88 |
If the \fIfilename\fP is a dash (\-), the |
| 89 |
output is written to \fIstdout\fP. The default is to generate, but |
| 90 |
not execute, a \fIMakefile\fP. |
| 91 |
.TP 8 |
| 92 |
.B \-e |
| 93 |
This option indicates the \fIimake\fP should execute the generated |
| 94 |
\fIMakefile\fP. The default is to leave this to the user. |
| 95 |
.TP 8 |
| 96 |
.B \-v |
| 97 |
This option indicates that \fIimake\fP should print the \fIcpp\fP command line |
| 98 |
that it is using to generate the \fIMakefile\fP. |
| 99 |
.SH "HOW IT WORKS" |
| 100 |
\fIImake\fP invokes \fIcpp\fP with any \fI\-I\fP or \fI\-D\fP flags passed |
| 101 |
on the command line and passes the name of a file containing the |
| 102 |
following 3 lines: |
| 103 |
.EX |
| 104 |
|
| 105 |
\& #define IMAKE_TEMPLATE "Imake.tmpl" |
| 106 |
\& #define INCLUDE_IMAKEFILE <Imakefile> |
| 107 |
\& #include IMAKE_TEMPLATE |
| 108 |
|
| 109 |
.EE |
| 110 |
where \fIImake.tmpl\fP and \fIImakefile\fP may be overridden by the |
| 111 |
\fI\-T\fP and \fI\-f\fP command options, respectively. |
| 112 |
.PP |
| 113 |
The IMAKE_TEMPLATE typically |
| 114 |
reads in a file containing machine-dependent parameters |
| 115 |
(specified as \fIcpp\fP symbols), a site-specific parameters file, |
| 116 |
a file defining variables, |
| 117 |
a file |
| 118 |
containing \fIcpp\fP macro functions for generating \fImake\fP rules, and |
| 119 |
finally the \fIImakefile\fP (specified by INCLUDE_IMAKEFILE) in the current |
| 120 |
directory. The \fIImakefile\fP uses the macro functions to indicate what |
| 121 |
targets should be built; \fIimake\fP takes care of generating the appropriate |
| 122 |
rules. |
| 123 |
.PP |
| 124 |
.I Imake |
| 125 |
configuration files contain two types of variables, imake variables |
| 126 |
and make variables. The imake variables are interpreted by cpp when |
| 127 |
.I imake |
| 128 |
is run. By convention they are mixed case. The make variables are |
| 129 |
written into the |
| 130 |
.I Makefile |
| 131 |
for later interpretation by |
| 132 |
.I make. |
| 133 |
By convention make variables are upper case. |
| 134 |
.PP |
| 135 |
The rules file (usually named \fIImake.rules\fP in the configuration |
| 136 |
directory) contains a variety of \fIcpp\fP macro functions that are |
| 137 |
configured according to the current platform. \fIImake\fP replaces |
| 138 |
any occurrences of the string ``@@'' with a newline to allow macros that |
| 139 |
generate more than one line of \fImake\fP rules. |
| 140 |
For example, the macro |
| 141 |
.EX |
| 142 |
|
| 143 |
\& #define program_target(program, objlist) @@\e |
| 144 |
program: objlist @@\e |
| 145 |
$(CC) \-o $@ objlist $(LDFLAGS) |
| 146 |
|
| 147 |
|
| 148 |
.EE |
| 149 |
when called with |
| 150 |
.I "program_target(foo, foo1.o foo2.o)" |
| 151 |
will expand to |
| 152 |
.EX |
| 153 |
|
| 154 |
foo: foo1.o foo2.o |
| 155 |
$(CC) \-o $@ foo1.o foo2.o $(LDFLAGS) |
| 156 |
|
| 157 |
.EE |
| 158 |
.PP |
| 159 |
\fIImake\fP also replaces any occurrences of the word ``XCOMM'' with |
| 160 |
the character ``#'' to permit placing comments in the Makefile without |
| 161 |
causing ``invalid directive'' errors from the preprocessor. |
| 162 |
.PP |
| 163 |
Some complex \fIimake\fP macros require generated \fImake\fP variables |
| 164 |
local to each invocation of the macro, often because their value |
| 165 |
depends on parameters passed to the macro. |
| 166 |
Such variables can be created by using an \fIimake\fP variable |
| 167 |
of the form \fBXVARdef\fP\fIn\fP, where \fIn\fP is a single digit. |
| 168 |
A unique \fImake\fP variable will be substituted. Later occurrences |
| 169 |
of the variable \fBXVARuse\fP\fIn\fP will |
| 170 |
be replaced by the variable created by the corresponding |
| 171 |
\fBXVARdef\fP\fIn\fP. |
| 172 |
.PP |
| 173 |
On systems whose \fIcpp\fP reduces multiple tabs and spaces to a single |
| 174 |
space, \fIimake\fP attempts to put back any necessary tabs (\fImake\fP is |
| 175 |
very picky about the difference between tabs and spaces). For this reason, |
| 176 |
colons (:) in command lines must be preceded by a backslash (\\). |
| 177 |
.SH "USE WITH THE X WINDOW SYSTEM" |
| 178 |
The X Window System used \fIimake\fP extensively up through the X11R6.9 |
| 179 |
release, for both full builds within the source tree and external software. |
| 180 |
X has since moved to GNU autoconf and automake for its build system in |
| 181 |
X11R7.0 and later releases, but still maintains imake for building existing |
| 182 |
external software programs that have not yet converted. |
| 183 |
.PP |
| 184 |
As mentioned above, two special |
| 185 |
variables, \fITOPDIR\fP and \fICURDIR,\fP are set to make referencing files |
| 186 |
using relative path names easier. For example, the following command is |
| 187 |
generated automatically to build the \fIMakefile\fP in the directory |
| 188 |
\fIlib/X/\fP (relative to the top of the sources): |
| 189 |
.EX |
| 190 |
|
| 191 |
% ../.././config/imake \-I../.././config \\ |
| 192 |
\-DTOPDIR=../../. \-DCURDIR=./lib/X |
| 193 |
.EE |
| 194 |
When building X programs outside the source tree, a special symbol |
| 195 |
\fIUseInstalled\fP is defined and \fITOPDIR\fP and |
| 196 |
\fICURDIR\fP are omitted. If the configuration files have been |
| 197 |
properly installed, the script \fIxmkmf\fP(1) may be used. |
| 198 |
.SH "INPUT FILES" |
| 199 |
Here is a summary of the files read by |
| 200 |
.I imake |
| 201 |
as used by X. |
| 202 |
The indentation shows what files include what other files. |
| 203 |
.EX |
| 204 |
Imake.tmpl generic variables |
| 205 |
site.def site-specific, BeforeVendorCF defined |
| 206 |
*.cf machine-specific |
| 207 |
*Lib.rules shared library rules |
| 208 |
site.def site-specific, AfterVendorCF defined |
| 209 |
Imake.rules rules |
| 210 |
Project.tmpl X-specific variables |
| 211 |
*Lib.tmpl shared library variables |
| 212 |
Imakefile |
| 213 |
Library.tmpl library rules |
| 214 |
Server.tmpl server rules |
| 215 |
Threads.tmpl multi-threaded rules |
| 216 |
|
| 217 |
.EE |
| 218 |
.LP |
| 219 |
Note that \fIsite.def\fP gets included twice, once before the |
| 220 |
\fI*.cf\fP file and once after. Although most site customizations |
| 221 |
should be specified after the \fI*.cf\fP file, some, such as the |
| 222 |
choice of compiler, need to be specified before, because other |
| 223 |
variable settings may depend on them. |
| 224 |
.LP |
| 225 |
The first time \fIsite.def\fP is included, the variable BeforeVendorCF |
| 226 |
is defined, and the second time, the variable AfterVendorCF is |
| 227 |
defined. All code in \fIsite.def\fP should be inside an #ifdef for |
| 228 |
one of these symbols. |
| 229 |
.SH FILES |
| 230 |
.TP |
| 231 |
Imakefile.c |
| 232 |
temporary input file for cpp |
| 233 |
.TP |
| 234 |
/tmp/Imf.XXXXXX |
| 235 |
temporary Makefile for -s |
| 236 |
.TP |
| 237 |
/tmp/IIf.XXXXXX |
| 238 |
temporary Imakefile if specified Imakefile uses # comments |
| 239 |
.TP |
| 240 |
__cpp__ |
| 241 |
default C preprocessor |
| 242 |
.SH "SEE ALSO" |
| 243 |
make(1), xmkmf(1) |
| 244 |
.TP |
| 245 |
Paul DuBois |
| 246 |
imake-Related Software and Documentation, |
| 247 |
http://www.snake.net/software/imake-stuff/ |
| 248 |
.TP |
| 249 |
Paul DuBois |
| 250 |
Software Portability with imake, Second Edition, |
| 251 |
O'Reilly & Associates, 1996. |
| 252 |
.TP |
| 253 |
S. I. Feldman, |
| 254 |
Make \(em A Program for Maintaining Computer Programs |
| 255 |
.SH "ENVIRONMENT VARIABLES" |
| 256 |
The following environment variables may be set, however their use is not |
| 257 |
recommended as they introduce dependencies that are not readily apparent |
| 258 |
when \fIimake\fP is run: |
| 259 |
.TP 5 |
| 260 |
.B IMAKEINCLUDE |
| 261 |
If defined, this specifies a ``\-I'' include argument to pass to the |
| 262 |
C preprocessor. E.g., ``\-I/usr/X11/config''. |
| 263 |
.TP 5 |
| 264 |
.B IMAKECPP |
| 265 |
If defined, this should be a valid path to a preprocessor program. |
| 266 |
E.g., ``/usr/local/cpp''. |
| 267 |
By default, |
| 268 |
.I imake |
| 269 |
will use cc -E or __cpp__, depending on the OS specific configuration. |
| 270 |
.TP 5 |
| 271 |
.B IMAKEMAKE |
| 272 |
If defined, this should be a valid path to a make program, |
| 273 |
such as ``/usr/local/make''. |
| 274 |
By default, |
| 275 |
.I imake |
| 276 |
will use whatever |
| 277 |
.I make |
| 278 |
program is found using |
| 279 |
.I execvp(3). |
| 280 |
This variable is only used if the ``\-e'' option is specified. |
| 281 |
.SH "AUTHOR" |
| 282 |
Todd Brunhoff, Tektronix and MIT Project Athena; Jim Fulton, MIT X Consortium |