git.sesse.net Git - rdpsrv/blob - Xserver/config/imake/imake.man

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