diff options
Diffstat (limited to 'nx-X11/config/imake/imake.man')
| -rw-r--r-- | nx-X11/config/imake/imake.man | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/nx-X11/config/imake/imake.man b/nx-X11/config/imake/imake.man new file mode 100644 index 000000000..34d5b9403 --- /dev/null +++ b/nx-X11/config/imake/imake.man @@ -0,0 +1,262 @@ +.\" $Xorg: imake.man,v 1.4 2001/02/09 02:03:16 xorgcvs Exp $ +.\" 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. +.\" +.\" $XFree86: imake.man,v 1.8 2001/12/14 19:53:19 dawes Exp $ +.\" +.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 uses 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 uses \fIimake\fP extensively, for both full builds within +the source tree and external software. 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 +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 |