Debian Codegraph @

imake/imake.man

raw
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