cde/config/imake/imake.man

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