| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|---|
| 2 |
|
|---|
| 3 |
<!-- $Id$ --> |
|---|
| 4 |
|
|---|
| 5 |
<HEAD> |
|---|
| 6 |
<TITLE>Maintaining and updating configure.in and Makefile.in</TITLE> |
|---|
| 7 |
</HEAD> |
|---|
| 8 |
|
|---|
| 9 |
<BODY BGCOLOR="#ffffff"> |
|---|
| 10 |
|
|---|
| 11 |
<DIV ALIGN="CENTER"> |
|---|
| 12 |
<H1>Working with <TT>configure.in</TT> and <TT>Makefile.in</TT></H1> |
|---|
| 13 |
</DIV> |
|---|
| 14 |
|
|---|
| 15 |
<HR WIDTH="80%" NOSHADE> |
|---|
| 16 |
|
|---|
| 17 |
<H2>Basics</H2> |
|---|
| 18 |
|
|---|
| 19 |
<DL> |
|---|
| 20 |
<DT><B>Comments in <TT>configure.in</TT></B> |
|---|
| 21 |
<DD> |
|---|
| 22 |
<P> |
|---|
| 23 |
|
|---|
| 24 |
Two types of comments can be used in <TT>configure.in</TT>. The first |
|---|
| 25 |
is the relatively standard ``<TT>#</TT>'' comment. Lines beginning |
|---|
| 26 |
with this character are copied into the final <I>configure</I> script |
|---|
| 27 |
generated by <I>autoconf</I>(1). The other type is the <I>m4</I>(1) |
|---|
| 28 |
comment. Lines commented in this way begin with ``<TT>dnl</TT>'' and |
|---|
| 29 |
are <I>not</I> copied into the <I>configure</I> script. |
|---|
| 30 |
|
|---|
| 31 |
<P> |
|---|
| 32 |
<DT><B>Language used in <TT>configure.in</TT></B> |
|---|
| 33 |
<DD> |
|---|
| 34 |
<P> |
|---|
| 35 |
|
|---|
| 36 |
The scripting language used in <TT>configure.in</TT> is <I>sh</I>(1). |
|---|
| 37 |
All conditional statements must use the form: |
|---|
| 38 |
|
|---|
| 39 |
<PRE> |
|---|
| 40 |
if test "$some_var" = "some_val" ; then |
|---|
| 41 |
... |
|---|
| 42 |
fi |
|---|
| 43 |
</PRE> |
|---|
| 44 |
|
|---|
| 45 |
rather than: |
|---|
| 46 |
|
|---|
| 47 |
<PRE> |
|---|
| 48 |
if [ "$some_var" = "some_val" ] ; then |
|---|
| 49 |
... |
|---|
| 50 |
fi |
|---|
| 51 |
</PRE> |
|---|
| 52 |
|
|---|
| 53 |
The brackets are recognized as special characters by <I>m4</I>(1) and |
|---|
| 54 |
may not be copied into <I>configure</I> properly. |
|---|
| 55 |
|
|---|
| 56 |
<P> |
|---|
| 57 |
<DT><B>Multi-line parameters to Autoconf macros</B> |
|---|
| 58 |
<DD> |
|---|
| 59 |
<P> |
|---|
| 60 |
|
|---|
| 61 |
Parameters spanning multiple lines may be passed to Autoconf macros |
|---|
| 62 |
without using backslashes through a special block recognized by |
|---|
| 63 |
<I>m4</I>(1). Simply enclose the parameter in <TT>[]</TT>'s and it |
|---|
| 64 |
will be parsed as one parameter. Remember to be careful about the use |
|---|
| 65 |
of semi-colons for separating <I>sh</I>(1) statements within these |
|---|
| 66 |
blocks. |
|---|
| 67 |
|
|---|
| 68 |
<P> |
|---|
| 69 |
<DT><B>Custom preprocessor information</B> |
|---|
| 70 |
<DD> |
|---|
| 71 |
<P> |
|---|
| 72 |
|
|---|
| 73 |
Anything that defines preprocessor macros other than those generated |
|---|
| 74 |
by the Autoconf macros must be defined in <TT>acconfig.h</TT>. If they |
|---|
| 75 |
are not defined in this file, <I>autoheader</I>(1) will complain as it |
|---|
| 76 |
parses <TT>configure.in</TT> and finds these customizations. Follow |
|---|
| 77 |
the existing syntax and layout of <TT>acconfig.h</TT> when making |
|---|
| 78 |
additions to it. In general, additions only have to be made when a new |
|---|
| 79 |
<I>AC_DEFINE</I>, <I>AC_CHECK_TYPE</I>, etc. line is added to |
|---|
| 80 |
<TT>configure.in</TT>. |
|---|
| 81 |
|
|---|
| 82 |
<P> |
|---|
| 83 |
<DT><B>Including a common, external <TT>Makefile</TT></B> |
|---|
| 84 |
<DD> |
|---|
| 85 |
<P> |
|---|
| 86 |
|
|---|
| 87 |
Due to inconsistencies in the way various operating systems implement |
|---|
| 88 |
some sort of ``include'' directive in their <I>make</I>(1), there is no |
|---|
| 89 |
easy method for including a common, external <TT>Makefile</TT> |
|---|
| 90 |
containing variable assignments common to all <TT>Makefile</TT>s in the |
|---|
| 91 |
source tree such that it would be platform independent. The result of |
|---|
| 92 |
this is a lot of redundancy in the <TT>Makefile.in</TT> files. The use |
|---|
| 93 |
of GNU's version of <I>make</I>(1) on all build platforms may or may |
|---|
| 94 |
not simplify this issue. |
|---|
| 95 |
</DL> |
|---|
| 96 |
|
|---|
| 97 |
<HR WIDTH="80%" NOSHADE> |
|---|
| 98 |
<P> |
|---|
| 99 |
|
|---|
| 100 |
<H2>Layout of <TT>configure.in</TT></H2> |
|---|
| 101 |
|
|---|
| 102 |
<DL> |
|---|
| 103 |
<DT><B>Initialization</B> |
|---|
| 104 |
<DD> |
|---|
| 105 |
<P> |
|---|
| 106 |
|
|---|
| 107 |
The first short block of <TT>configure.in</TT> performs some very basic |
|---|
| 108 |
initialization tasks. The RCS revision number of the script is |
|---|
| 109 |
maintained here so that the user can verify that s/he has the most |
|---|
| 110 |
recent version of the actual <I>configure</I> script. A check for one |
|---|
| 111 |
file in the source tree is also made to perform a very general, inexact |
|---|
| 112 |
verification that things are where they are supposed to be. Currently, |
|---|
| 113 |
<I>configure</I> will check for the existence of |
|---|
| 114 |
<TT>Config/ChunkDesc.C</TT>. Finally, the header file created when |
|---|
| 115 |
done with the configuration process is named. This will most likely |
|---|
| 116 |
always be <TT>config.h</TT>. |
|---|
| 117 |
|
|---|
| 118 |
<P> |
|---|
| 119 |
<DT><B>Custom arguments</B> |
|---|
| 120 |
<DD> |
|---|
| 121 |
<P> |
|---|
| 122 |
|
|---|
| 123 |
In this block, the custom arguments for the <I>configure</I> script are |
|---|
| 124 |
defined. The first set defines the |
|---|
| 125 |
<TT>--with-<I>package</I>[=<I>arg</I>]</TT> and |
|---|
| 126 |
<TT>--without-<I>package</I></TT> arguments. These are intended to be |
|---|
| 127 |
used for choosing some external software package to use at compile |
|---|
| 128 |
time. They are also used for providing a small level of customization |
|---|
| 129 |
to how the external software is found and/or used. |
|---|
| 130 |
|
|---|
| 131 |
<P> |
|---|
| 132 |
|
|---|
| 133 |
The second set define the <TT>--enable-<I>feature</I>[=<I>arg</I>]</TT> |
|---|
| 134 |
and <TT>--disable-<I>feature</I></TT> arguments that allow the user |
|---|
| 135 |
to choose which optional features can be built. From the Autoconf |
|---|
| 136 |
2.12 documentation, ``These options should never make a feature behave |
|---|
| 137 |
differently or cause one feature to replace another.'' |
|---|
| 138 |
|
|---|
| 139 |
<P> |
|---|
| 140 |
|
|---|
| 141 |
For both sets of options, the <I>AC_ARG_WITH</I> and |
|---|
| 142 |
<I>AC_ARG_ENABLE</I> macros behave the same way. The first argument is |
|---|
| 143 |
the package/feature, the second is the description printed when the |
|---|
| 144 |
user runs <I>configure</I> with the ``<TT>--help</TT>'' option. The |
|---|
| 145 |
third argument sets a user-defined variable in the script to the |
|---|
| 146 |
contents of <TT>$withval</TT> or <TT>$enableval</TT> respectively. If |
|---|
| 147 |
no argument is given (e.g., the user specified |
|---|
| 148 |
``<TT>--enable-opengl</TT>''), the variable will get either ``yes'' or |
|---|
| 149 |
``no'' as its value depending upon whether the user used the positive |
|---|
| 150 |
or negative form of the argument. |
|---|
| 151 |
|
|---|
| 152 |
<P> |
|---|
| 153 |
<DT><B>System-dependent setup</B> |
|---|
| 154 |
<DD> |
|---|
| 155 |
<P> |
|---|
| 156 |
|
|---|
| 157 |
Here, a common set of script variables are given values that are |
|---|
| 158 |
usually dependent upon the system on which the script is being run. |
|---|
| 159 |
The new variables used are all set to have no value before the |
|---|
| 160 |
conditional <TT>case</TT> block begins. The subsequent conditional |
|---|
| 161 |
block compares the value in <TT>$host</TT> (obtained from the |
|---|
| 162 |
<I>AC_CANONICAL_HOST</I> macro) with known systems and sets values for |
|---|
| 163 |
the variables appropriately. |
|---|
| 164 |
|
|---|
| 165 |
<P> |
|---|
| 166 |
|
|---|
| 167 |
Some existing variables are modified here as well. These include |
|---|
| 168 |
<TT>$CFLAGS</TT>, <TT>$CXXFLAGS</TT> and <TT>$INCLUDES</TT>. Each of |
|---|
| 169 |
these could have been set as part of the user's environment variables |
|---|
| 170 |
or previously in the script as part of executing a macro. Thus, they |
|---|
| 171 |
should be treated carefully so as not to destroy any existing values |
|---|
| 172 |
that may be stored in them. |
|---|
| 173 |
|
|---|
| 174 |
<P> |
|---|
| 175 |
|
|---|
| 176 |
Besides setting values in variables, custom pre-processor macros are |
|---|
| 177 |
defined here using the <I>AC_DEFINE</I> macro. This macro takes two |
|---|
| 178 |
parameters: |
|---|
| 179 |
|
|---|
| 180 |
<P> |
|---|
| 181 |
<OL> |
|---|
| 182 |
<LI>The name of the macro to define. |
|---|
| 183 |
<LI>The value to which the macro is set by the pre-processor. |
|---|
| 184 |
</OL> |
|---|
| 185 |
<P> |
|---|
| 186 |
|
|---|
| 187 |
To do something similar to: |
|---|
| 188 |
|
|---|
| 189 |
<PRE> |
|---|
| 190 |
#define C2_DEF |
|---|
| 191 |
</PRE> |
|---|
| 192 |
|
|---|
| 193 |
use the following syntax: |
|---|
| 194 |
|
|---|
| 195 |
<PRE> |
|---|
| 196 |
AC_DEFINE(C2_DEF,) |
|---|
| 197 |
</PRE> |
|---|
| 198 |
|
|---|
| 199 |
Defining macros that take parameters cannot be done with |
|---|
| 200 |
<I>AC_DEFINE</I>. However, based on a check made for something (such |
|---|
| 201 |
as <I>sginap</I>(2)), such a macro can be defined at the bottom of |
|---|
| 202 |
<TT>acconfig.h</TT>. Refer to this file to see how a macro for |
|---|
| 203 |
<I>sginap</I>() is defined using <I>usleep</I>(2) in this manner. |
|---|
| 204 |
|
|---|
| 205 |
<P> |
|---|
| 206 |
<DT><B>External program checks</B> |
|---|
| 207 |
<DD> |
|---|
| 208 |
<P> |
|---|
| 209 |
|
|---|
| 210 |
This block is for standard program checks that <I>configure</I> does |
|---|
| 211 |
to ensure that software needed for compiling the package works. Using |
|---|
| 212 |
the values in several preset variables (including <TT>$CC</TT> for the |
|---|
| 213 |
C compiler and <TT>$CXX</TT> for the C++ compiler), it runs tests on |
|---|
| 214 |
the software and reports any problems it finds. |
|---|
| 215 |
|
|---|
| 216 |
<P> |
|---|
| 217 |
<DT><B>External library checks</B> |
|---|
| 218 |
<DD> |
|---|
| 219 |
<P> |
|---|
| 220 |
|
|---|
| 221 |
Checks for needed external libraries are made here. In this |
|---|
| 222 |
<I>configure</I> script, a great deal of processing is done in order |
|---|
| 223 |
to ensure that the source can be properly compiled and linked using |
|---|
| 224 |
certain external libraries. The basic process of checking for a |
|---|
| 225 |
library (say, the OpenGL library) involves first checking to see if |
|---|
| 226 |
the library can be linked, and if so, a check is then made for a |
|---|
| 227 |
standard header file associated with the library (in this case, |
|---|
| 228 |
<TT>GL/gl.h</TT>). In some cases, if a library cannot be found, a |
|---|
| 229 |
fallback check is provided. In the case of the POSIX threads library, |
|---|
| 230 |
an attempt to link against <TT>libpthread</TT> is made. If that fails |
|---|
| 231 |
(as it will on HP-UX 10.20), a check is made to link against |
|---|
| 232 |
<TT>libcma</TT>. |
|---|
| 233 |
|
|---|
| 234 |
<P> |
|---|
| 235 |
|
|---|
| 236 |
Upon successfully finding a library and a needed header file, various |
|---|
| 237 |
variables are usually set that are used later in the Makefile |
|---|
| 238 |
generation phase. This process tends to get complicated with the VR |
|---|
| 239 |
Juggler configuration process because some source is conditionally |
|---|
| 240 |
compiled in depending upon what is determined in this phase of |
|---|
| 241 |
processing. This is addressed in more detail in the section about |
|---|
| 242 |
<TT>Makefile.in</TT> files. If a library is not found, the script may |
|---|
| 243 |
simply issue a warning about the problem or it may exit altogether if |
|---|
| 244 |
the library's existence is crucial to the compiling process. |
|---|
| 245 |
|
|---|
| 246 |
<P> |
|---|
| 247 |
|
|---|
| 248 |
Adding new library checks can be complicated. The best method is to |
|---|
| 249 |
refer to the Autoconf 2.12 documentation and the existing checks. All |
|---|
| 250 |
follow basically the same structure. |
|---|
| 251 |
|
|---|
| 252 |
<P> |
|---|
| 253 |
<DT><B>Header file checks</B> |
|---|
| 254 |
<DD> |
|---|
| 255 |
<P> |
|---|
| 256 |
|
|---|
| 257 |
Checks for standard header files and user-specified header files are |
|---|
| 258 |
made here. The user-specified list is a space-separated list of |
|---|
| 259 |
header files that may not exist on all systems. If a header file is |
|---|
| 260 |
found, <TT>HAVE_<I>FILENAME</I>_H</TT> is defined in <TT>config.h</TT> |
|---|
| 261 |
when it is generated. |
|---|
| 262 |
|
|---|
| 263 |
<P> |
|---|
| 264 |
<DT><B><TT>typedef</TT>, <TT>struct</TT> and compiler characteristic |
|---|
| 265 |
checks</B> |
|---|
| 266 |
<DD> |
|---|
| 267 |
<P> |
|---|
| 268 |
|
|---|
| 269 |
Here, checks are made to determine if the host system has various |
|---|
| 270 |
types and structures defined or not. There are a few existing macros |
|---|
| 271 |
that check for specific examples of these, and it is possible to have |
|---|
| 272 |
user-defined checks. Currently, little is done in this block, and in |
|---|
| 273 |
fact the only user-specified check is to see if the host system has |
|---|
| 274 |
<TT>u_int</TT> defined. If not, it defines it (via the preprocessor, |
|---|
| 275 |
not <TT><B>typedef</B></TT>) to be <TT>unsigned int</TT> through the |
|---|
| 276 |
<I>AC_CHECK_TYPE</I> macro. To check for <TT>struct</TT>s, use |
|---|
| 277 |
<I>AC_TRY_COMPILE</I> or <I>AC_EGREP_CPP</I>. Refer to the Autoconf |
|---|
| 278 |
2.12 documentation section on ``Existing Tests'' for more detailed |
|---|
| 279 |
information. |
|---|
| 280 |
|
|---|
| 281 |
<P> |
|---|
| 282 |
<DT><B>Library function checks</B> |
|---|
| 283 |
<DD> |
|---|
| 284 |
<P> |
|---|
| 285 |
|
|---|
| 286 |
Here, checks are made for any library and system functions (e.g., |
|---|
| 287 |
<I>gettimeofday</I>(2), <I>socket</I>(2), <I>sginap</I>(2)) that may |
|---|
| 288 |
not exist on all systems. As with other sections, the user-specified |
|---|
| 289 |
list of functions to check is the space-separated parameter passed to |
|---|
| 290 |
the <I>AC_CHECK_FUNCS</I> macro. If found, <TT>HAVE_<I>FUNCNAME</I></TT> |
|---|
| 291 |
will be defined in <TT>config.h</TT>. |
|---|
| 292 |
|
|---|
| 293 |
<P> |
|---|
| 294 |
<DT><B>Makefile substitution</B> |
|---|
| 295 |
<DD> |
|---|
| 296 |
<P> |
|---|
| 297 |
|
|---|
| 298 |
Within this block of <TT>configure.in</TT>, special symbols in the |
|---|
| 299 |
<TT>Makefile.in</TT> files are slated for replacement with variable |
|---|
| 300 |
values. This is done through the <I>AC_SUBST</I> macro, and it simply |
|---|
| 301 |
replaces a ``tag'' in a <TT>Makefile.in</TT> with the value stored in |
|---|
| 302 |
the corresponding <I>configure</I> script variable. The following |
|---|
| 303 |
example illustrates what happens during the file generation phase |
|---|
| 304 |
(discussed next). |
|---|
| 305 |
|
|---|
| 306 |
Say that some <TT>Makefile.in</TT> contains the following line: |
|---|
| 307 |
|
|---|
| 308 |
<PRE> |
|---|
| 309 |
CUSTOM_VAR = @CUSTOM_VAR@ |
|---|
| 310 |
</PRE> |
|---|
| 311 |
|
|---|
| 312 |
The string enclosed by <TT>@</TT>'s is the tag that will be replaced |
|---|
| 313 |
when <TT>Makefile</TT> is generated. In <TT>configure.in</TT>, there |
|---|
| 314 |
following line must be present: |
|---|
| 315 |
|
|---|
| 316 |
<PRE> |
|---|
| 317 |
AC_SUBST(CUSTOM_VAR) |
|---|
| 318 |
</PRE> |
|---|
| 319 |
|
|---|
| 320 |
Note that the variable is not prepended by a `<TT>$</TT>' because |
|---|
| 321 |
variable interpolation should not be done here. Of course, |
|---|
| 322 |
<TT>$CUSTOM_VAR</TT> will generally have had some value set prior to |
|---|
| 323 |
this point. That is not required however. |
|---|
| 324 |
|
|---|
| 325 |
<P> |
|---|
| 326 |
|
|---|
| 327 |
It is in this phase of configuration that most of the system-dependent |
|---|
| 328 |
build work is done. This is similar to what Imake template files do. |
|---|
| 329 |
Virtually everything preceding this point set variables to have values |
|---|
| 330 |
appropriate to the host machine, and now they are put into the |
|---|
| 331 |
<TT>Makefile</TT>s to be used for compiling the code. There are |
|---|
| 332 |
several pre-defined variables that <I>configure</I> will substitute in |
|---|
| 333 |
the input template files. Refer to the section titled ``Preset Output |
|---|
| 334 |
Variables'' in the Autuconf 2.12 documentation for a list of these. |
|---|
| 335 |
|
|---|
| 336 |
<P> |
|---|
| 337 |
<DT><B>File generation</B> |
|---|
| 338 |
<DD> |
|---|
| 339 |
<P> |
|---|
| 340 |
|
|---|
| 341 |
In this last block, file generation is performed using the |
|---|
| 342 |
<I>AC_OUTPUT</I> macro. It iterates through its space-separated list |
|---|
| 343 |
of files and finds the associated <TT>.in</TT> template file. In |
|---|
| 344 |
general, this step is only used for generating Makefiles |
|---|
| 345 |
(<TT>config.h</TT> is defined automatically due to the |
|---|
| 346 |
<I>AC_CONFIG_HEADER</I> call at the top of <TT>configure.in</TT>). |
|---|
| 347 |
When a new directory and corresponding <TT>Makefile.in</TT> are added |
|---|
| 348 |
to the source tree, an entry for it must be added to this list. |
|---|
| 349 |
</DL> |
|---|
| 350 |
|
|---|
| 351 |
<HR WIDTH="80%" NOSHADE> |
|---|
| 352 |
<P> |
|---|
| 353 |
|
|---|
| 354 |
<H2>General Layout of a <TT>Makefile.in</TT> file</H2> |
|---|
| 355 |
|
|---|
| 356 |
<DL> |
|---|
| 357 |
<DT><B>Preset variables and variables local to the current file</B> |
|---|
| 358 |
<DD> |
|---|
| 359 |
<P> |
|---|
| 360 |
|
|---|
| 361 |
The first set of assignments is for preset variables (that is, those |
|---|
| 362 |
that are preset by <I>configure</I>) and for variables that are closely |
|---|
| 363 |
related to the preset variety. In general, many of these variables will |
|---|
| 364 |
have values that are specific to the current <TT>Makefile</TT> being |
|---|
| 365 |
generated. In other words, they cannot be shared via a common file |
|---|
| 366 |
that would be somehow included by the current <TT>Makefile</TT>. |
|---|
| 367 |
|
|---|
| 368 |
<P> |
|---|
| 369 |
<DT><B>System-dependent variables</B> |
|---|
| 370 |
<DD> |
|---|
| 371 |
<P> |
|---|
| 372 |
|
|---|
| 373 |
These variables are those that are dependent upon the host build system. |
|---|
| 374 |
They include paths to external programs, options passed to those |
|---|
| 375 |
programs, which C and C++ compilers to use, etc. For the most part, |
|---|
| 376 |
these variables will have the same values among all <TT>Makefile</TT>s. |
|---|
| 377 |
|
|---|
| 378 |
<P> |
|---|
| 379 |
|
|---|
| 380 |
In every <TT>Makefile.in</TT>, <TT>$OBJDIR</TT> is set to ``<TT>.</TT>'', |
|---|
| 381 |
but this is overridden at compile time with a value set by the top-level |
|---|
| 382 |
<TT>Makefile</TT> that is passed as an argument to recursive |
|---|
| 383 |
<I>make</I>(1) calls. Thus, the result is that when doing a full |
|---|
| 384 |
library build, all the object files are built in a common location. |
|---|
| 385 |
However, if a developer only wishes to compile files in a specific |
|---|
| 386 |
directory in the tree, the object files will be put in the current |
|---|
| 387 |
directory. |
|---|
| 388 |
|
|---|
| 389 |
<P> |
|---|
| 390 |
|
|---|
| 391 |
The <TT>${OPTIMIZER}</TT> variable is one that is set outside the |
|---|
| 392 |
generated <TT>Makefile</TT> by the top-level <TT>Makefile</TT> in its |
|---|
| 393 |
recursive calls to <I>make</I>(1). It is used for compiling debugging |
|---|
| 394 |
and optimized versions of the library, and this is decided in the |
|---|
| 395 |
top-level <TT>Makefile</TT>. When compiling only in a specific source |
|---|
| 396 |
directory, it can be overridden (as can all variables) on the command |
|---|
| 397 |
line. |
|---|
| 398 |
|
|---|
| 399 |
<P> |
|---|
| 400 |
|
|---|
| 401 |
The <TT>${VPATH}</TT> variable is a special one that tells <I>make</I>(1) |
|---|
| 402 |
where to find dependencies for object files when the source is in |
|---|
| 403 |
another directory. This allows easy compiling of common source for |
|---|
| 404 |
multiple platforms independently. This variable should be ``set'' to |
|---|
| 405 |
<TT>@srcdir@</TT> in <TT>Makefile.in</TT> rather than to |
|---|
| 406 |
<TT>${srcdir}</TT> because some implementations of <I>make</I>(1) may |
|---|
| 407 |
not handle the latter properly. |
|---|
| 408 |
|
|---|
| 409 |
<P> |
|---|
| 410 |
<DT><B>Compiler, source and object variables</B> |
|---|
| 411 |
<DD> |
|---|
| 412 |
<P> |
|---|
| 413 |
|
|---|
| 414 |
The first set in this group combines all the system-dependent variables |
|---|
| 415 |
related to the C and C++ compilers into <TT>${C_COMPILE}</TT> and |
|---|
| 416 |
<TT>${CXX_COMPILE}</TT> respectively. These are then used in the build |
|---|
| 417 |
targets for compiling C and C++ code. |
|---|
| 418 |
|
|---|
| 419 |
<P> |
|---|
| 420 |
|
|---|
| 421 |
Next, the source files that <I>makedepend</I>(1) will parse are |
|---|
| 422 |
listed. They are passed as arguments to this program when the |
|---|
| 423 |
<B>depend</B> target is built. The file names should not have any path |
|---|
| 424 |
prepended to them because this will interfere with the output from |
|---|
| 425 |
<I>makedepend</I>(1). When the <B>depend</B> target is built, it knows |
|---|
| 426 |
which directory contains the files to parse from the <TT>${srcdir}</TT> |
|---|
| 427 |
variable. |
|---|
| 428 |
|
|---|
| 429 |
<P> |
|---|
| 430 |
|
|---|
| 431 |
Finally, the object files to be built are listed. Each object file |
|---|
| 432 |
should have <TT>${OBJDIR}</TT> prepended to it. This is part of being |
|---|
| 433 |
able to build object files in a common directory or in the current |
|---|
| 434 |
directory depending on the context of the build. The variable |
|---|
| 435 |
containing the list of object files is used as the dependency for the |
|---|
| 436 |
<B>all</B>, <B>dbg</B>, <B>opt</B>, <B>dso</B>, <B>ddso</B> and |
|---|
| 437 |
<B>obj</B> targets. |
|---|
| 438 |
|
|---|
| 439 |
<P> |
|---|
| 440 |
|
|---|
| 441 |
This is the first occurrence of conditionally compiled files. Depending |
|---|
| 442 |
upon which platform the library is being built on and upon other factors |
|---|
| 443 |
(threading package, API, etc.), some files may need to be compiled while |
|---|
| 444 |
other do not (or cannot). This is decided by <I>configure</I> when it |
|---|
| 445 |
is run, and then the Makefile substitution phase takes care of it in |
|---|
| 446 |
the generated <TT>Makefile</TT>s. A simple example of how this is used |
|---|
| 447 |
can be found in <TT>SharedMem/Makefile.in</TT>. For the dependency |
|---|
| 448 |
sources and the object files, the following is done: |
|---|
| 449 |
|
|---|
| 450 |
<PRE> |
|---|
| 451 |
DEPEND_SRCS = C2Memory.C @SHAREDMEM_DEPEND_SRCS@ |
|---|
| 452 |
|
|---|
| 453 |
SHM_OBJECTS = ${OBJDIR}/C2Memory.o @SHAREDMEM_OBJS@ |
|---|
| 454 |
</PRE> |
|---|
| 455 |
|
|---|
| 456 |
Any extra platform- or implementation-specific files are defined when |
|---|
| 457 |
<TT>@SHAREDMEM_DEPEND_SRCS@</TT> and <TT>@SHAREDMEM_OBJS@</TT> are |
|---|
| 458 |
expanded by <I>configure</I>. Because these tags may sometimes be |
|---|
| 459 |
expanded to nothing, they should never be put on a separate line if |
|---|
| 460 |
the list is spanned across multiple lines with backslashes. In such a |
|---|
| 461 |
case, it is usually easiest to append the tag to the last line. |
|---|
| 462 |
|
|---|
| 463 |
<P> |
|---|
| 464 |
<DT><B>Miscellaneous variables</B> |
|---|
| 465 |
<DD> |
|---|
| 466 |
<P> |
|---|
| 467 |
|
|---|
| 468 |
Depending on which <TT>Makefile.in</TT> is being examined, any extra |
|---|
| 469 |
variables needed are set here. For example, in the top-level |
|---|
| 470 |
<TT>Makefile.in</TT>, the variables for the common build directory are |
|---|
| 471 |
set. For the most part, everything set here is local to the current |
|---|
| 472 |
file. |
|---|
| 473 |
|
|---|
| 474 |
<P> |
|---|
| 475 |
|
|---|
| 476 |
One special variable set in the top-level <TT>Makefile.in</TT> is |
|---|
| 477 |
<TT>${SUBDIRS}</TT>. This is the list of all subdirectories of the |
|---|
| 478 |
top source tree directory where compiling needs to be done. It is used |
|---|
| 479 |
in doing recursive calls to <I>make</I>(1). These recursive calls to |
|---|
| 480 |
<I>make</I>(1) are handled wherever other subdirectories exist--not |
|---|
| 481 |
just at the top level. Presently, the other locations where similar |
|---|
| 482 |
code exists are in the <TT>Input</TT>, <TT>test</TT> and |
|---|
| 483 |
<TT>test/ogl</TT> directories. |
|---|
| 484 |
|
|---|
| 485 |
<P> |
|---|
| 486 |
|
|---|
| 487 |
A final special tag is <TT>@SET_MAKE@</TT>. This is inserted here in |
|---|
| 488 |
case <I>make</I>(1) does not set <TT>${MAKE}</TT> when it runs. This |
|---|
| 489 |
check is performed by <I>configure</I>, and a macro telling it to do |
|---|
| 490 |
this check is in <TT>configure.in</TT>. |
|---|
| 491 |
|
|---|
| 492 |
<P> |
|---|
| 493 |
<DT><B>Library targets</B> |
|---|
| 494 |
<DD> |
|---|
| 495 |
<P> |
|---|
| 496 |
|
|---|
| 497 |
These build targets are where the bulk of the work in compiling the |
|---|
| 498 |
library is done. In the case when recursive calls to <I>make</I>(1) |
|---|
| 499 |
are not necessary, the structure in all <TT>Makefile.in</TT> files is |
|---|
| 500 |
the same. First, the <B>default</B> target is set and then any |
|---|
| 501 |
remaining targets are defined. Each file listed in the object file |
|---|
| 502 |
list defined prior to this point (including all files that may be |
|---|
| 503 |
compiled conditionally) must have a separate line giving the compile |
|---|
| 504 |
line for it. The only dependency needed is the C/C++ source file |
|---|
| 505 |
associated with the object file. Because <TT>${VPATH}</TT> is being |
|---|
| 506 |
used, the path to that source file is not needed. However, in the |
|---|
| 507 |
compile line, a path must be given. The <TT>${C2_SRCDIR}</TT> variable |
|---|
| 508 |
is used so that some flexibility is available at configuration time. |
|---|
| 509 |
Though it is not currently implemented, it could be possible to use |
|---|
| 510 |
either an absolute path (using <TT>${C2ROOT_ABS}</TT>) or a relative |
|---|
| 511 |
path (using <TT>${srcdir}</TT>). This would be implemented in |
|---|
| 512 |
<TT>configure.in</TT>, and <TT>${C2_SRCDIR}</TT> would simply have the |
|---|
| 513 |
current value substituted by <I>configure</I>. Obviously, these |
|---|
| 514 |
targets are specific to the given <TT>Makefile</TT>. |
|---|
| 515 |
|
|---|
| 516 |
<P> |
|---|
| 517 |
|
|---|
| 518 |
Standard suffix rules for compiling <TT>.c</TT> and <TT>.C</TT> source |
|---|
| 519 |
files into object files are given, but they are not currently used |
|---|
| 520 |
because they do not work. They fail because <I>make</I>(1) looks in |
|---|
| 521 |
the current directory for source files to compile, and when the source |
|---|
| 522 |
files are found in another directory (<TT>${srcdir}</TT> to be exact), |
|---|
| 523 |
the suffix rules cannot find them, even when <TT>${VPATH}</TT> is set. |
|---|
| 524 |
Why <I>make</I>(1) is implemented in this way is unclear. |
|---|
| 525 |
|
|---|
| 526 |
<P> |
|---|
| 527 |
|
|---|
| 528 |
For those cases when recursive calls to <I>make</I>(1) are required, |
|---|
| 529 |
a standard model is used. The recursive targets are named in such a |
|---|
| 530 |
way that they have ``-recursive'' appended to the non-recursive name. |
|---|
| 531 |
For example, if the user entered <TT><B>make ddso</B></TT> and a |
|---|
| 532 |
recursive ddso build was necessary, the <TT>Makefile.in</TT> would have |
|---|
| 533 |
the following: |
|---|
| 534 |
|
|---|
| 535 |
<PRE> |
|---|
| 536 |
ddso-recursive: |
|---|
| 537 |
<I>Some iterative shell code that recursively calls `<TT>${MAKE} ddso</TT>'</I> |
|---|
| 538 |
|
|---|
| 539 |
ddso: ddso-recursive |
|---|
| 540 |
</PRE> |
|---|
| 541 |
|
|---|
| 542 |
The ``iterative shell code'' is the same in all files where it is used. |
|---|
| 543 |
The only difference is which targets use it. The code loops over each |
|---|
| 544 |
directory name listed in <TT>${SUBDIRS}</TT>, changes into it, and runs |
|---|
| 545 |
whichever target was called. This is where <TT>${OPTIMIZER}</TT> and |
|---|
| 546 |
<TT>${OBJDIR}</TT> are overridden to use the value appropriate to the |
|---|
| 547 |
build being done. |
|---|
| 548 |
|
|---|
| 549 |
<P> |
|---|
| 550 |
|
|---|
| 551 |
Finally, the <B>depend</B> and <B>newdepend</B> targets are defined for |
|---|
| 552 |
generating dependencies for all the source files given. The |
|---|
| 553 |
<B>depend</B> target is built every time the user runs <I>make</I>(1) |
|---|
| 554 |
from the top-level directory, and thus it is dependent upon a file |
|---|
| 555 |
called <TT>.depend_done</TT> existing in the current subdirectory. If |
|---|
| 556 |
it is necessary to regenerate the dependency list, <B>newdepend</B> |
|---|
| 557 |
can be run. It removes <TT>.depend_done</TT> and then does a |
|---|
| 558 |
<TT><B>make depend</B></TT> in the current subdirectory. These are |
|---|
| 559 |
exactly the same in all <TT>Makefile.in</TT> files (where they are |
|---|
| 560 |
needed) through the use of the <TT>${srcdir}</TT> and |
|---|
| 561 |
<TT>${WORKDIR}</TT> variables defined at the top of the file. |
|---|
| 562 |
|
|---|
| 563 |
<P> |
|---|
| 564 |
<DT><B>Local targets</B> |
|---|
| 565 |
<DD> |
|---|
| 566 |
<P> |
|---|
| 567 |
|
|---|
| 568 |
These targets are for any source files that are not compiled into the |
|---|
| 569 |
library but are (for example) used as test code. This is one example |
|---|
| 570 |
of a time when it may be convenient to compile code in the current |
|---|
| 571 |
directory rather than in a common object file directory. Generally, |
|---|
| 572 |
these targets will be similar to the library targets. However, |
|---|
| 573 |
<I>makedepend</I>(1) is not run on these files. A local target for |
|---|
| 574 |
doing this could be defined in the same manner as the common |
|---|
| 575 |
<B>depend</B> and <B>newdepend</B> targets though. |
|---|
| 576 |
|
|---|
| 577 |
<P> |
|---|
| 578 |
<DT><B>Clean-up targets</B> |
|---|
| 579 |
<DD> |
|---|
| 580 |
<P> |
|---|
| 581 |
|
|---|
| 582 |
A simple <B>clean</B> target is defined here in most |
|---|
| 583 |
<TT>Makefile.in</TT> files. In those where recursive calls to |
|---|
| 584 |
<I>make</I>(1) are made, a recursive version is implemented. As usual, |
|---|
| 585 |
these targets just remove any files that are not needed when done |
|---|
| 586 |
compiling. |
|---|
| 587 |
|
|---|
| 588 |
<P> |
|---|
| 589 |
<DT><B>Dependencies</B> |
|---|
| 590 |
<DD> |
|---|
| 591 |
<P> |
|---|
| 592 |
|
|---|
| 593 |
Most <TT>Makefile.in</TT> files end with an area where all the source |
|---|
| 594 |
dependencies are appended when the <B>depend</B> and <B>newdepend</B> |
|---|
| 595 |
targets are built. The line marking this section must remain intact |
|---|
| 596 |
so that <I>makedepend</I>(1) will know where it is safe to begin |
|---|
| 597 |
overwriting the dependencies should it be run again. This line is: |
|---|
| 598 |
|
|---|
| 599 |
<PRE> |
|---|
| 600 |
# DO NOT DELETE THIS LINE -- make depend depends on it. |
|---|
| 601 |
</PRE> |
|---|
| 602 |
|
|---|
| 603 |
It is the default string recognized by <I>makedepend</I>(1), but it can |
|---|
| 604 |
be changed by specifying an alternate string as an argument to |
|---|
| 605 |
<I>makedepend</I>(1). |
|---|
| 606 |
</DL> |
|---|
| 607 |
|
|---|
| 608 |
<HR WIDTH="80%" NOSHADE> |
|---|
| 609 |
<P> |
|---|
| 610 |
|
|---|
| 611 |
<H2>References</H2> |
|---|
| 612 |
|
|---|
| 613 |
<DL> |
|---|
| 614 |
<DT><B>GNU Autoconf 2.12 Documentation</B> |
|---|
| 615 |
<DD> |
|---|
| 616 |
<P> |
|---|
| 617 |
|
|---|
| 618 |
The documentation comes with the Autoconf distribution and can be |
|---|
| 619 |
converted into HTML format. It is very comprehensive but also very |
|---|
| 620 |
long. On the ICEMT SGI workstations, the <TT>autoconf.info</TT> file |
|---|
| 621 |
is located in <TT>/usr/local/info</TT>. The documentation in HTML |
|---|
| 622 |
format is in <TT>~patrick/docs/autoconf</TT>. |
|---|
| 623 |
</DL> |
|---|
| 624 |
|
|---|
| 625 |
<HR WIDTH="80%" NOSHADE> |
|---|
| 626 |
<P> |
|---|
| 627 |
|
|---|
| 628 |
<FONT SIZE="-1"> |
|---|
| 629 |
<B>Last modified:</B> $Date$<BR> |
|---|
| 630 |
<B>Written by:</B> Patrick Hartling |
|---|
| 631 |
<<I><A HREF="mailto:patrick@icemt.iastate.edu">patrick@icemt.iastate.edu</A></I>><BR> |
|---|
| 632 |
</FONT> |
|---|
| 633 |
|
|---|
| 634 |
</BODY> |
|---|