| 0 | |
\input texinfo @c -*-texinfo-*-
|
| 1 | |
@comment ========================================================
|
| 2 | |
@comment %**start of header
|
| 3 | |
@setfilename autoconf.info
|
| 4 | |
@include version.texi
|
| 5 | |
@settitle Autoconf
|
| 6 | |
@setchapternewpage odd
|
| 7 | |
@ifnothtml
|
| 8 | |
@setcontentsaftertitlepage
|
| 9 | |
@end ifnothtml
|
| 10 | |
@finalout
|
| 11 | |
|
| 12 | |
@c @ovar(ARG)
|
| 13 | |
@c ----------
|
| 14 | |
@c The ARG is an optional argument. To be used for macro arguments in
|
| 15 | |
@c their documentation (@defmac).
|
| 16 | |
@macro ovar{varname}
|
| 17 | |
@r{[}@var{\varname\}@r{]}@c
|
| 18 | |
@end macro
|
| 19 | |
|
| 20 | |
@c @dvar(ARG, DEFAULT)
|
| 21 | |
@c -------------------
|
| 22 | |
@c The ARG is an optional argument, defaulting to DEFAULT. To be used
|
| 23 | |
@c for macro arguments in their documentation (@defmac).
|
| 24 | |
@macro dvar{varname, default}
|
| 25 | |
@r{[}@var{\varname\} = @samp{\default\}@r{]}@c
|
| 26 | |
@end macro
|
| 27 | |
|
| 28 | |
@c Handling the indexes with Texinfo yields several different problems.
|
| 29 | |
@c
|
| 30 | |
@c Because we want to drop out the AC_ part of the macro names in the
|
| 31 | |
@c printed manual, but not in the other outputs, we need a layer above
|
| 32 | |
@c the usual @acindex{} etc. That's why we first define indexes such as
|
| 33 | |
@c acx meant to become the macro @acindex. First of all, using ``ac_''
|
| 34 | |
@c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
|
| 35 | |
@c So use something more regular ``acx''. Then you finish with a printed
|
| 36 | |
@c index saying ``index is not existent''. Of course: you ought to use
|
| 37 | |
@c two letters :( So you use capitals.
|
| 38 | |
@c
|
| 39 | |
@c Second, when defining a macro in the TeX world, following spaces are
|
| 40 | |
@c eaten. But then, since we embed @acxindex commands that use the end
|
| 41 | |
@c of line as an end marker, the whole things wrecks itself. So make
|
| 42 | |
@c sure you do *force* an additional end of line, add a ``@c''.
|
| 43 | |
@c
|
| 44 | |
@c Finally, you might want to get rid of TeX expansion, using --expand
|
| 45 | |
@c with texi2dvi. But then you wake up an old problem: we use macros
|
| 46 | |
@c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
|
| 47 | |
|
| 48 | |
@c Define an environment variable index, for variables users may set
|
| 49 | |
@c in their environment or on the configure command line.
|
| 50 | |
@defcodeindex ev
|
| 51 | |
@c Define an output variable index, for commonly AC_SUBST'ed variables.
|
| 52 | |
@defcodeindex ov
|
| 53 | |
@c Define a cache variable index, for variables matching *_cv_*.
|
| 54 | |
@defcodeindex CA
|
| 55 | |
@c Other shell variables not fitting the above categories should be
|
| 56 | |
@c listed in the predefined vrindex, which we merge in the concept index.
|
| 57 | |
@syncodeindex vr cp
|
| 58 | |
@c Define a CPP preprocessor macro index, for #define'd strings.
|
| 59 | |
@defcodeindex cv
|
| 60 | |
@c Define an Autoconf macro index that @defmac doesn't write to.
|
| 61 | |
@defcodeindex AC
|
| 62 | |
@c Define an Autotest macro index that @defmac doesn't write to.
|
| 63 | |
@defcodeindex AT
|
| 64 | |
@c Define an M4sugar macro index that @defmac doesn't write to.
|
| 65 | |
@defcodeindex MS
|
| 66 | |
@c Define an index for *foreign* programs: `mv' etc. Used for the
|
| 67 | |
@c portability sections and so on.
|
| 68 | |
@defindex pr
|
| 69 | |
|
| 70 | |
@c shortindexflag
|
| 71 | |
@c --------------
|
| 72 | |
@c Shall we factor AC_ out of the Autoconf macro index etc.?
|
| 73 | |
@iftex
|
| 74 | |
@set shortindexflag
|
| 75 | |
@end iftex
|
| 76 | |
|
| 77 | |
@c @acindex{MACRO}
|
| 78 | |
@c ---------------
|
| 79 | |
@c Registering an AC_\MACRO\.
|
| 80 | |
@ifset shortindexflag
|
| 81 | |
@macro acindex{macro}
|
| 82 | |
@ACindex \macro\
|
| 83 | |
@c
|
| 84 | |
@end macro
|
| 85 | |
@end ifset
|
| 86 | |
@ifclear shortindexflag
|
| 87 | |
@macro acindex{macro}
|
| 88 | |
@ACindex AC_\macro\
|
| 89 | |
@end macro
|
| 90 | |
@end ifclear
|
| 91 | |
|
| 92 | |
@c @ahindex{MACRO}
|
| 93 | |
@c ---------------
|
| 94 | |
@c Registering an AH_\MACRO\.
|
| 95 | |
@macro ahindex{macro}
|
| 96 | |
@ACindex AH_\macro\
|
| 97 | |
@c
|
| 98 | |
@end macro
|
| 99 | |
|
| 100 | |
@c @asindex{MACRO}
|
| 101 | |
@c ---------------
|
| 102 | |
@c Registering an AS_\MACRO\.
|
| 103 | |
@ifset shortindexflag
|
| 104 | |
@macro asindex{macro}
|
| 105 | |
@MSindex \macro\
|
| 106 | |
@c
|
| 107 | |
@end macro
|
| 108 | |
@end ifset
|
| 109 | |
@ifclear shortindexflag
|
| 110 | |
@macro asindex{macro}
|
| 111 | |
@MSindex AS_\macro\
|
| 112 | |
@end macro
|
| 113 | |
@end ifclear
|
| 114 | |
|
| 115 | |
@c @atindex{MACRO}
|
| 116 | |
@c ---------------
|
| 117 | |
@c Registering an AT_\MACRO\.
|
| 118 | |
@ifset shortindexflag
|
| 119 | |
@macro atindex{macro}
|
| 120 | |
@ATindex \macro\
|
| 121 | |
@c
|
| 122 | |
@end macro
|
| 123 | |
@end ifset
|
| 124 | |
@ifclear shortindexflag
|
| 125 | |
@macro atindex{macro}
|
| 126 | |
@ATindex AT_\macro\
|
| 127 | |
@end macro
|
| 128 | |
@end ifclear
|
| 129 | |
|
| 130 | |
@c @auindex{MACRO}
|
| 131 | |
@c ---------------
|
| 132 | |
@c Registering an AU_\MACRO\.
|
| 133 | |
@macro auindex{macro}
|
| 134 | |
@ACindex AU_\macro\
|
| 135 | |
@c
|
| 136 | |
@end macro
|
| 137 | |
|
| 138 | |
@c @hdrindex{MACRO}
|
| 139 | |
@c ----------------
|
| 140 | |
@c Indexing a header.
|
| 141 | |
@macro hdrindex{macro}
|
| 142 | |
@prindex @file{\macro\}
|
| 143 | |
@c
|
| 144 | |
@end macro
|
| 145 | |
|
| 146 | |
@c @msindex{MACRO}
|
| 147 | |
@c ---------------
|
| 148 | |
@c Registering an m4_\MACRO\.
|
| 149 | |
@ifset shortindexflag
|
| 150 | |
@macro msindex{macro}
|
| 151 | |
@MSindex \macro\
|
| 152 | |
@c
|
| 153 | |
@end macro
|
| 154 | |
@end ifset
|
| 155 | |
@ifclear shortindexflag
|
| 156 | |
@macro msindex{macro}
|
| 157 | |
@MSindex m4_\macro\
|
| 158 | |
@end macro
|
| 159 | |
@end ifclear
|
| 160 | |
|
| 161 | |
|
| 162 | |
@c @caindex{VARIABLE}
|
| 163 | |
@c ------------------
|
| 164 | |
@c Registering an ac_cv_\VARIABLE\ cache variable.
|
| 165 | |
@ifset shortindexflag
|
| 166 | |
@macro caindex{macro}
|
| 167 | |
@CAindex \macro\
|
| 168 | |
@end macro
|
| 169 | |
@end ifset
|
| 170 | |
@ifclear shortindexflag
|
| 171 | |
@macro caindex{macro}
|
| 172 | |
@CAindex ac_cv_\macro\
|
| 173 | |
@end macro
|
| 174 | |
@end ifclear
|
| 175 | |
|
| 176 | |
@c Define an index for functions: `alloca' etc. Used for the
|
| 177 | |
@c portability sections and so on. We can't use `fn' (aka `fnindex),
|
| 178 | |
@c since `@defmac' goes into it => we'd get all the macros too.
|
| 179 | |
|
| 180 | |
@c FIXME: Aaarg! It seems there are too many indices for TeX :(
|
| 181 | |
@c
|
| 182 | |
@c ! No room for a new @write .
|
| 183 | |
@c l.112 @defcodeindex fu
|
| 184 | |
@c
|
| 185 | |
@c so don't define yet another one :( Just put some tags before each
|
| 186 | |
@c @prindex which is actually a @funindex.
|
| 187 | |
@c
|
| 188 | |
@c @defcodeindex fu
|
| 189 | |
@c
|
| 190 | |
@c
|
| 191 | |
@c @c Put the programs and functions into their own index.
|
| 192 | |
@c @syncodeindex fu pr
|
| 193 | |
|
| 194 | |
@comment %**end of header
|
| 195 | |
@comment ========================================================
|
| 196 | |
|
| 197 | |
@copying
|
| 198 | |
|
| 199 | |
This manual (@value{UPDATED}) is for GNU Autoconf
|
| 200 | |
(version @value{VERSION}),
|
| 201 | |
a package for creating scripts to configure source code packages using
|
| 202 | |
templates and an M4 macro package.
|
| 203 | |
|
| 204 | |
Copyright @copyright{} 1992-1996, 1998-2012 Free Software Foundation,
|
| 205 | |
Inc.
|
| 206 | |
|
| 207 | |
@quotation
|
| 208 | |
Permission is granted to copy, distribute and/or modify this document
|
| 209 | |
under the terms of the GNU Free Documentation License,
|
| 210 | |
Version 1.3 or any later version published by the Free Software
|
| 211 | |
Foundation; with no Invariant Sections, no Front-Cover texts, and
|
| 212 | |
no Back-Cover Texts. A copy of the license is included in the section
|
| 213 | |
entitled ``GNU Free Documentation License.''
|
| 214 | |
@end quotation
|
| 215 | |
@end copying
|
| 216 | |
|
| 217 | |
|
| 218 | |
|
| 219 | |
@dircategory Software development
|
| 220 | |
@direntry
|
| 221 | |
* Autoconf: (autoconf). Create source code configuration scripts.
|
| 222 | |
@end direntry
|
| 223 | |
|
| 224 | |
@dircategory Individual utilities
|
| 225 | |
@direntry
|
| 226 | |
* autoscan: (autoconf)autoscan Invocation.
|
| 227 | |
Semi-automatic @file{configure.ac} writing
|
| 228 | |
* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
|
| 229 | |
* autoconf-invocation: (autoconf)autoconf Invocation.
|
| 230 | |
How to create configuration scripts
|
| 231 | |
* autoreconf: (autoconf)autoreconf Invocation.
|
| 232 | |
Remaking multiple @command{configure} scripts
|
| 233 | |
* autoheader: (autoconf)autoheader Invocation.
|
| 234 | |
How to create configuration templates
|
| 235 | |
* autom4te: (autoconf)autom4te Invocation.
|
| 236 | |
The Autoconf executables backbone
|
| 237 | |
* configure: (autoconf)configure Invocation. Configuring a package.
|
| 238 | |
* autoupdate: (autoconf)autoupdate Invocation.
|
| 239 | |
Automatic update of @file{configure.ac}
|
| 240 | |
* config.status: (autoconf)config.status Invocation. Recreating configurations.
|
| 241 | |
* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
|
| 242 | |
@end direntry
|
| 243 | |
|
| 244 | |
@titlepage
|
| 245 | |
@title Autoconf
|
| 246 | |
@subtitle Creating Automatic Configuration Scripts
|
| 247 | |
@subtitle for version @value{VERSION}, @value{UPDATED}
|
| 248 | |
@author David MacKenzie
|
| 249 | |
@author Ben Elliston
|
| 250 | |
@author Akim Demaille
|
| 251 | |
@page
|
| 252 | |
@vskip 0pt plus 1filll
|
| 253 | |
@insertcopying
|
| 254 | |
@end titlepage
|
| 255 | |
|
| 256 | |
@contents
|
| 257 | |
|
| 258 | |
|
| 259 | |
@ifnottex
|
| 260 | |
@node Top
|
| 261 | |
@top Autoconf
|
| 262 | |
@insertcopying
|
| 263 | |
@end ifnottex
|
| 264 | |
|
| 265 | |
@c The master menu, created with texinfo-master-menu, goes here.
|
| 266 | |
|
| 267 | |
@menu
|
| 268 | |
* Introduction:: Autoconf's purpose, strengths, and weaknesses
|
| 269 | |
* The GNU Build System:: A set of tools for portable software packages
|
| 270 | |
* Making configure Scripts:: How to organize and produce Autoconf scripts
|
| 271 | |
* Setup:: Initialization and output
|
| 272 | |
* Existing Tests:: Macros that check for particular features
|
| 273 | |
* Writing Tests:: How to write new feature checks
|
| 274 | |
* Results:: What to do with results from feature checks
|
| 275 | |
* Programming in M4:: Layers on top of which Autoconf is written
|
| 276 | |
* Programming in M4sh:: Shell portability layer
|
| 277 | |
* Writing Autoconf Macros:: Adding new macros to Autoconf
|
| 278 | |
* Portable Shell:: Shell script portability pitfalls
|
| 279 | |
* Portable Make:: Makefile portability pitfalls
|
| 280 | |
* Portable C and C++:: C and C++ portability pitfalls
|
| 281 | |
* Manual Configuration:: Selecting features that can't be guessed
|
| 282 | |
* Site Configuration:: Local defaults for @command{configure}
|
| 283 | |
* Running configure Scripts:: How to use the Autoconf output
|
| 284 | |
* config.status Invocation:: Recreating a configuration
|
| 285 | |
* Obsolete Constructs:: Kept for backward compatibility
|
| 286 | |
* Using Autotest:: Creating portable test suites
|
| 287 | |
* FAQ:: Frequent Autoconf Questions, with answers
|
| 288 | |
* History:: History of Autoconf
|
| 289 | |
* GNU Free Documentation License:: License for copying this manual
|
| 290 | |
* Indices:: Indices of symbols, concepts, etc.
|
| 291 | |
|
| 292 | |
@detailmenu
|
| 293 | |
--- The Detailed Node Listing ---
|
| 294 | |
|
| 295 | |
The GNU Build System
|
| 296 | |
|
| 297 | |
* Automake:: Escaping makefile hell
|
| 298 | |
* Gnulib:: The GNU portability library
|
| 299 | |
* Libtool:: Building libraries portably
|
| 300 | |
* Pointers:: More info on the GNU build system
|
| 301 | |
|
| 302 | |
Making @command{configure} Scripts
|
| 303 | |
|
| 304 | |
* Writing Autoconf Input:: What to put in an Autoconf input file
|
| 305 | |
* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
|
| 306 | |
* ifnames Invocation:: Listing the conditionals in source code
|
| 307 | |
* autoconf Invocation:: How to create configuration scripts
|
| 308 | |
* autoreconf Invocation:: Remaking multiple @command{configure} scripts
|
| 309 | |
|
| 310 | |
Writing @file{configure.ac}
|
| 311 | |
|
| 312 | |
* Shell Script Compiler:: Autoconf as solution of a problem
|
| 313 | |
* Autoconf Language:: Programming in Autoconf
|
| 314 | |
* Autoconf Input Layout:: Standard organization of @file{configure.ac}
|
| 315 | |
|
| 316 | |
Initialization and Output Files
|
| 317 | |
|
| 318 | |
* Initializing configure:: Option processing etc.
|
| 319 | |
* Versioning:: Dealing with Autoconf versions
|
| 320 | |
* Notices:: Copyright, version numbers in @command{configure}
|
| 321 | |
* Input:: Where Autoconf should find files
|
| 322 | |
* Output:: Outputting results from the configuration
|
| 323 | |
* Configuration Actions:: Preparing the output based on results
|
| 324 | |
* Configuration Files:: Creating output files
|
| 325 | |
* Makefile Substitutions:: Using output variables in makefiles
|
| 326 | |
* Configuration Headers:: Creating a configuration header file
|
| 327 | |
* Configuration Commands:: Running arbitrary instantiation commands
|
| 328 | |
* Configuration Links:: Links depending on the configuration
|
| 329 | |
* Subdirectories:: Configuring independent packages together
|
| 330 | |
* Default Prefix:: Changing the default installation prefix
|
| 331 | |
|
| 332 | |
Substitutions in Makefiles
|
| 333 | |
|
| 334 | |
* Preset Output Variables:: Output variables that are always set
|
| 335 | |
* Installation Directory Variables:: Other preset output variables
|
| 336 | |
* Changed Directory Variables:: Warnings about @file{datarootdir}
|
| 337 | |
* Build Directories:: Supporting multiple concurrent compiles
|
| 338 | |
* Automatic Remaking:: Makefile rules for configuring
|
| 339 | |
|
| 340 | |
Configuration Header Files
|
| 341 | |
|
| 342 | |
* Header Templates:: Input for the configuration headers
|
| 343 | |
* autoheader Invocation:: How to create configuration templates
|
| 344 | |
* Autoheader Macros:: How to specify CPP templates
|
| 345 | |
|
| 346 | |
Existing Tests
|
| 347 | |
|
| 348 | |
* Common Behavior:: Macros' standard schemes
|
| 349 | |
* Alternative Programs:: Selecting between alternative programs
|
| 350 | |
* Files:: Checking for the existence of files
|
| 351 | |
* Libraries:: Library archives that might be missing
|
| 352 | |
* Library Functions:: C library functions that might be missing
|
| 353 | |
* Header Files:: Header files that might be missing
|
| 354 | |
* Declarations:: Declarations that may be missing
|
| 355 | |
* Structures:: Structures or members that might be missing
|
| 356 | |
* Types:: Types that might be missing
|
| 357 | |
* Compilers and Preprocessors:: Checking for compiling programs
|
| 358 | |
* System Services:: Operating system services
|
| 359 | |
* Posix Variants:: Special kludges for specific Posix variants
|
| 360 | |
* Erlang Libraries:: Checking for the existence of Erlang libraries
|
| 361 | |
|
| 362 | |
Common Behavior
|
| 363 | |
|
| 364 | |
* Standard Symbols:: Symbols defined by the macros
|
| 365 | |
* Default Includes:: Includes used by the generic macros
|
| 366 | |
|
| 367 | |
Alternative Programs
|
| 368 | |
|
| 369 | |
* Particular Programs:: Special handling to find certain programs
|
| 370 | |
* Generic Programs:: How to find other programs
|
| 371 | |
|
| 372 | |
Library Functions
|
| 373 | |
|
| 374 | |
* Function Portability:: Pitfalls with usual functions
|
| 375 | |
* Particular Functions:: Special handling to find certain functions
|
| 376 | |
* Generic Functions:: How to find other functions
|
| 377 | |
|
| 378 | |
Header Files
|
| 379 | |
|
| 380 | |
* Header Portability:: Collected knowledge on common headers
|
| 381 | |
* Particular Headers:: Special handling to find certain headers
|
| 382 | |
* Generic Headers:: How to find other headers
|
| 383 | |
|
| 384 | |
Declarations
|
| 385 | |
|
| 386 | |
* Particular Declarations:: Macros to check for certain declarations
|
| 387 | |
* Generic Declarations:: How to find other declarations
|
| 388 | |
|
| 389 | |
Structures
|
| 390 | |
|
| 391 | |
* Particular Structures:: Macros to check for certain structure members
|
| 392 | |
* Generic Structures:: How to find other structure members
|
| 393 | |
|
| 394 | |
Types
|
| 395 | |
|
| 396 | |
* Particular Types:: Special handling to find certain types
|
| 397 | |
* Generic Types:: How to find other types
|
| 398 | |
|
| 399 | |
Compilers and Preprocessors
|
| 400 | |
|
| 401 | |
* Specific Compiler Characteristics:: Some portability issues
|
| 402 | |
* Generic Compiler Characteristics:: Language independent tests and features
|
| 403 | |
* C Compiler:: Checking its characteristics
|
| 404 | |
* C++ Compiler:: Likewise
|
| 405 | |
* Objective C Compiler:: Likewise
|
| 406 | |
* Objective C++ Compiler:: Likewise
|
| 407 | |
* Erlang Compiler and Interpreter:: Likewise
|
| 408 | |
* Fortran Compiler:: Likewise
|
| 409 | |
* Go Compiler:: Likewise
|
| 410 | |
|
| 411 | |
Writing Tests
|
| 412 | |
|
| 413 | |
* Language Choice:: Selecting which language to use for testing
|
| 414 | |
* Writing Test Programs:: Forging source files for compilers
|
| 415 | |
* Running the Preprocessor:: Detecting preprocessor symbols
|
| 416 | |
* Running the Compiler:: Detecting language or header features
|
| 417 | |
* Running the Linker:: Detecting library features
|
| 418 | |
* Runtime:: Testing for runtime features
|
| 419 | |
* Systemology:: A zoology of operating systems
|
| 420 | |
* Multiple Cases:: Tests for several possible values
|
| 421 | |
|
| 422 | |
Writing Test Programs
|
| 423 | |
|
| 424 | |
* Guidelines:: General rules for writing test programs
|
| 425 | |
* Test Functions:: Avoiding pitfalls in test programs
|
| 426 | |
* Generating Sources:: Source program boilerplate
|
| 427 | |
|
| 428 | |
Results of Tests
|
| 429 | |
|
| 430 | |
* Defining Symbols:: Defining C preprocessor symbols
|
| 431 | |
* Setting Output Variables:: Replacing variables in output files
|
| 432 | |
* Special Chars in Variables:: Characters to beware of in variables
|
| 433 | |
* Caching Results:: Speeding up subsequent @command{configure} runs
|
| 434 | |
* Printing Messages:: Notifying @command{configure} users
|
| 435 | |
|
| 436 | |
Caching Results
|
| 437 | |
|
| 438 | |
* Cache Variable Names:: Shell variables used in caches
|
| 439 | |
* Cache Files:: Files @command{configure} uses for caching
|
| 440 | |
* Cache Checkpointing:: Loading and saving the cache file
|
| 441 | |
|
| 442 | |
Programming in M4
|
| 443 | |
|
| 444 | |
* M4 Quotation:: Protecting macros from unwanted expansion
|
| 445 | |
* Using autom4te:: The Autoconf executables backbone
|
| 446 | |
* Programming in M4sugar:: Convenient pure M4 macros
|
| 447 | |
* Debugging via autom4te:: Figuring out what M4 was doing
|
| 448 | |
|
| 449 | |
M4 Quotation
|
| 450 | |
|
| 451 | |
* Active Characters:: Characters that change the behavior of M4
|
| 452 | |
* One Macro Call:: Quotation and one macro call
|
| 453 | |
* Quoting and Parameters:: M4 vs. shell parameters
|
| 454 | |
* Quotation and Nested Macros:: Macros calling macros
|
| 455 | |
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
|
| 456 | |
* Quadrigraphs:: Another way to escape special characters
|
| 457 | |
* Balancing Parentheses:: Dealing with unbalanced parentheses
|
| 458 | |
* Quotation Rule Of Thumb:: One parenthesis, one quote
|
| 459 | |
|
| 460 | |
Using @command{autom4te}
|
| 461 | |
|
| 462 | |
* autom4te Invocation:: A GNU M4 wrapper
|
| 463 | |
* Customizing autom4te:: Customizing the Autoconf package
|
| 464 | |
|
| 465 | |
Programming in M4sugar
|
| 466 | |
|
| 467 | |
* Redefined M4 Macros:: M4 builtins changed in M4sugar
|
| 468 | |
* Diagnostic Macros:: Diagnostic messages from M4sugar
|
| 469 | |
* Diversion support:: Diversions in M4sugar
|
| 470 | |
* Conditional constructs:: Conditions in M4
|
| 471 | |
* Looping constructs:: Iteration in M4
|
| 472 | |
* Evaluation Macros:: More quotation and evaluation control
|
| 473 | |
* Text processing Macros:: String manipulation in M4
|
| 474 | |
* Number processing Macros:: Arithmetic computation in M4
|
| 475 | |
* Set manipulation Macros:: Set manipulation in M4
|
| 476 | |
* Forbidden Patterns:: Catching unexpanded macros
|
| 477 | |
|
| 478 | |
Programming in M4sh
|
| 479 | |
|
| 480 | |
* Common Shell Constructs:: Portability layer for common shell constructs
|
| 481 | |
* Polymorphic Variables:: Support for indirect variable names
|
| 482 | |
* Initialization Macros:: Macros to establish a sane shell environment
|
| 483 | |
* File Descriptor Macros:: File descriptor macros for input and output
|
| 484 | |
|
| 485 | |
Writing Autoconf Macros
|
| 486 | |
|
| 487 | |
* Macro Definitions:: Basic format of an Autoconf macro
|
| 488 | |
* Macro Names:: What to call your new macros
|
| 489 | |
* Reporting Messages:: Notifying @command{autoconf} users
|
| 490 | |
* Dependencies Between Macros:: What to do when macros depend on other macros
|
| 491 | |
* Obsoleting Macros:: Warning about old ways of doing things
|
| 492 | |
* Coding Style:: Writing Autoconf macros @`a la Autoconf
|
| 493 | |
|
| 494 | |
Dependencies Between Macros
|
| 495 | |
|
| 496 | |
* Prerequisite Macros:: Ensuring required information
|
| 497 | |
* Suggested Ordering:: Warning about possible ordering problems
|
| 498 | |
* One-Shot Macros:: Ensuring a macro is called only once
|
| 499 | |
|
| 500 | |
Portable Shell Programming
|
| 501 | |
|
| 502 | |
* Shellology:: A zoology of shells
|
| 503 | |
* Invoking the Shell:: Invoking the shell as a command
|
| 504 | |
* Here-Documents:: Quirks and tricks
|
| 505 | |
* File Descriptors:: FDs and redirections
|
| 506 | |
* Signal Handling:: Shells, signals, and headaches
|
| 507 | |
* File System Conventions:: File names
|
| 508 | |
* Shell Pattern Matching:: Pattern matching
|
| 509 | |
* Shell Substitutions:: Variable and command expansions
|
| 510 | |
* Assignments:: Varying side effects of assignments
|
| 511 | |
* Parentheses:: Parentheses in shell scripts
|
| 512 | |
* Slashes:: Slashes in shell scripts
|
| 513 | |
* Special Shell Variables:: Variables you should not change
|
| 514 | |
* Shell Functions:: What to look out for if you use them
|
| 515 | |
* Limitations of Builtins:: Portable use of not so portable /bin/sh
|
| 516 | |
* Limitations of Usual Tools:: Portable use of portable tools
|
| 517 | |
|
| 518 | |
Portable Make Programming
|
| 519 | |
|
| 520 | |
* $< in Ordinary Make Rules:: $< in ordinary rules
|
| 521 | |
* Failure in Make Rules:: Failing portably in rules
|
| 522 | |
* Special Chars in Names:: Special Characters in Macro Names
|
| 523 | |
* Backslash-Newline-Empty:: Empty lines after backslash-newline
|
| 524 | |
* Backslash-Newline Comments:: Spanning comments across line boundaries
|
| 525 | |
* Long Lines in Makefiles:: Line length limitations
|
| 526 | |
* Macros and Submakes:: @code{make macro=value} and submakes
|
| 527 | |
* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
|
| 528 | |
* The Make Macro SHELL:: @code{$(SHELL)} portability issues
|
| 529 | |
* Parallel Make:: Parallel @command{make} quirks
|
| 530 | |
* Comments in Make Rules:: Other problems with Make comments
|
| 531 | |
* Newlines in Make Rules:: Using literal newlines in rules
|
| 532 | |
* Comments in Make Macros:: Other problems with Make comments in macros
|
| 533 | |
* Trailing whitespace in Make Macros:: Macro substitution problems
|
| 534 | |
* Command-line Macros and whitespace:: Whitespace trimming of values
|
| 535 | |
* obj/ and Make:: Don't name a subdirectory @file{obj}
|
| 536 | |
* make -k Status:: Exit status of @samp{make -k}
|
| 537 | |
* VPATH and Make:: @code{VPATH} woes
|
| 538 | |
* Single Suffix Rules:: Single suffix rules and separated dependencies
|
| 539 | |
* Timestamps and Make:: Subsecond timestamp resolution
|
| 540 | |
|
| 541 | |
@code{VPATH} and Make
|
| 542 | |
|
| 543 | |
* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts
|
| 544 | |
* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
|
| 545 | |
* $< in Explicit Rules:: @code{$<} does not work in ordinary rules
|
| 546 | |
* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
|
| 547 | |
* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
|
| 548 | |
* Make Target Lookup:: More details about @code{VPATH} lookup
|
| 549 | |
|
| 550 | |
Portable C and C++ Programming
|
| 551 | |
|
| 552 | |
* Varieties of Unportability:: How to make your programs unportable
|
| 553 | |
* Integer Overflow:: When integers get too large
|
| 554 | |
* Preprocessor Arithmetic:: @code{#if} expression problems
|
| 555 | |
* Null Pointers:: Properties of null pointers
|
| 556 | |
* Buffer Overruns:: Subscript errors and the like
|
| 557 | |
* Volatile Objects:: @code{volatile} and signals
|
| 558 | |
* Floating Point Portability:: Portable floating-point arithmetic
|
| 559 | |
* Exiting Portably:: Exiting and the exit status
|
| 560 | |
|
| 561 | |
Integer Overflow
|
| 562 | |
|
| 563 | |
* Integer Overflow Basics:: Why integer overflow is a problem
|
| 564 | |
* Signed Overflow Examples:: Examples of code assuming wraparound
|
| 565 | |
* Optimization and Wraparound:: Optimizations that break uses of wraparound
|
| 566 | |
* Signed Overflow Advice:: Practical advice for signed overflow issues
|
| 567 | |
* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
|
| 568 | |
|
| 569 | |
Manual Configuration
|
| 570 | |
|
| 571 | |
* Specifying Target Triplets:: Specifying target triplets
|
| 572 | |
* Canonicalizing:: Getting the canonical system type
|
| 573 | |
* Using System Type:: What to do with the system type
|
| 574 | |
|
| 575 | |
Site Configuration
|
| 576 | |
|
| 577 | |
* Help Formatting:: Customizing @samp{configure --help}
|
| 578 | |
* External Software:: Working with other optional software
|
| 579 | |
* Package Options:: Selecting optional features
|
| 580 | |
* Pretty Help Strings:: Formatting help string
|
| 581 | |
* Option Checking:: Controlling checking of @command{configure} options
|
| 582 | |
* Site Details:: Configuring site details
|
| 583 | |
* Transforming Names:: Changing program names when installing
|
| 584 | |
* Site Defaults:: Giving @command{configure} local defaults
|
| 585 | |
|
| 586 | |
Transforming Program Names When Installing
|
| 587 | |
|
| 588 | |
* Transformation Options:: @command{configure} options to transform names
|
| 589 | |
* Transformation Examples:: Sample uses of transforming names
|
| 590 | |
* Transformation Rules:: Makefile uses of transforming names
|
| 591 | |
|
| 592 | |
Running @command{configure} Scripts
|
| 593 | |
|
| 594 | |
* Basic Installation:: Instructions for typical cases
|
| 595 | |
* Compilers and Options:: Selecting compilers and optimization
|
| 596 | |
* Multiple Architectures:: Compiling for multiple architectures at once
|
| 597 | |
* Installation Names:: Installing in different directories
|
| 598 | |
* Optional Features:: Selecting optional features
|
| 599 | |
* Particular Systems:: Particular systems
|
| 600 | |
* System Type:: Specifying the system type
|
| 601 | |
* Sharing Defaults:: Setting site-wide defaults for @command{configure}
|
| 602 | |
* Defining Variables:: Specifying the compiler etc.
|
| 603 | |
* configure Invocation:: Changing how @command{configure} runs
|
| 604 | |
|
| 605 | |
Obsolete Constructs
|
| 606 | |
|
| 607 | |
* Obsolete config.status Use:: Obsolete convention for @command{config.status}
|
| 608 | |
* acconfig Header:: Additional entries in @file{config.h.in}
|
| 609 | |
* autoupdate Invocation:: Automatic update of @file{configure.ac}
|
| 610 | |
* Obsolete Macros:: Backward compatibility macros
|
| 611 | |
* Autoconf 1:: Tips for upgrading your files
|
| 612 | |
* Autoconf 2.13:: Some fresher tips
|
| 613 | |
|
| 614 | |
Upgrading From Version 1
|
| 615 | |
|
| 616 | |
* Changed File Names:: Files you might rename
|
| 617 | |
* Changed Makefiles:: New things to put in @file{Makefile.in}
|
| 618 | |
* Changed Macros:: Macro calls you might replace
|
| 619 | |
* Changed Results:: Changes in how to check test results
|
| 620 | |
* Changed Macro Writing:: Better ways to write your own macros
|
| 621 | |
|
| 622 | |
Upgrading From Version 2.13
|
| 623 | |
|
| 624 | |
* Changed Quotation:: Broken code which used to work
|
| 625 | |
* New Macros:: Interaction with foreign macros
|
| 626 | |
* Hosts and Cross-Compilation:: Bugward compatibility kludges
|
| 627 | |
* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
|
| 628 | |
* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources
|
| 629 | |
|
| 630 | |
Generating Test Suites with Autotest
|
| 631 | |
|
| 632 | |
* Using an Autotest Test Suite:: Autotest and the user
|
| 633 | |
* Writing Testsuites:: Autotest macros
|
| 634 | |
* testsuite Invocation:: Running @command{testsuite} scripts
|
| 635 | |
* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
|
| 636 | |
|
| 637 | |
Using an Autotest Test Suite
|
| 638 | |
|
| 639 | |
* testsuite Scripts:: The concepts of Autotest
|
| 640 | |
* Autotest Logs:: Their contents
|
| 641 | |
|
| 642 | |
Frequent Autoconf Questions, with answers
|
| 643 | |
|
| 644 | |
* Distributing:: Distributing @command{configure} scripts
|
| 645 | |
* Why GNU M4:: Why not use the standard M4?
|
| 646 | |
* Bootstrapping:: Autoconf and GNU M4 require each other?
|
| 647 | |
* Why Not Imake:: Why GNU uses @command{configure} instead of Imake
|
| 648 | |
* Defining Directories:: Passing @code{datadir} to program
|
| 649 | |
* Autom4te Cache:: What is it? Can I remove it?
|
| 650 | |
* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
|
| 651 | |
* Expanded Before Required:: Expanded Before Required
|
| 652 | |
* Debugging:: Debugging @command{configure} scripts
|
| 653 | |
|
| 654 | |
History of Autoconf
|
| 655 | |
|
| 656 | |
* Genesis:: Prehistory and naming of @command{configure}
|
| 657 | |
* Exodus:: The plagues of M4 and Perl
|
| 658 | |
* Leviticus:: The priestly code of portability arrives
|
| 659 | |
* Numbers:: Growth and contributors
|
| 660 | |
* Deuteronomy:: Approaching the promises of easy configuration
|
| 661 | |
|
| 662 | |
Indices
|
| 663 | |
|
| 664 | |
* Environment Variable Index:: Index of environment variables used
|
| 665 | |
* Output Variable Index:: Index of variables set in output files
|
| 666 | |
* Preprocessor Symbol Index:: Index of C preprocessor symbols defined
|
| 667 | |
* Cache Variable Index:: Index of documented cache variables
|
| 668 | |
* Autoconf Macro Index:: Index of Autoconf macros
|
| 669 | |
* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
|
| 670 | |
* Autotest Macro Index:: Index of Autotest macros
|
| 671 | |
* Program & Function Index:: Index of those with portability problems
|
| 672 | |
* Concept Index:: General index
|
| 673 | |
|
| 674 | |
@end detailmenu
|
| 675 | |
@end menu
|
| 676 | |
|
| 677 | |
@c ============================================================= Introduction.
|
| 678 | |
|
| 679 | |
@node Introduction
|
| 680 | |
@chapter Introduction
|
| 681 | |
@cindex Introduction
|
| 682 | |
|
| 683 | |
@flushright
|
| 684 | |
A physicist, an engineer, and a computer scientist were discussing the
|
| 685 | |
nature of God. ``Surely a Physicist,'' said the physicist, ``because
|
| 686 | |
early in the Creation, God made Light; and you know, Maxwell's
|
| 687 | |
equations, the dual nature of electromagnetic waves, the relativistic
|
| 688 | |
consequences@enddots{}'' ``An Engineer!,'' said the engineer, ``because
|
| 689 | |
before making Light, God split the Chaos into Land and Water; it takes a
|
| 690 | |
hell of an engineer to handle that big amount of mud, and orderly
|
| 691 | |
separation of solids from liquids@enddots{}'' The computer scientist
|
| 692 | |
shouted: ``And the Chaos, where do you think it was coming from, hmm?''
|
| 693 | |
|
| 694 | |
---Anonymous
|
| 695 | |
@end flushright
|
| 696 | |
@c (via Franc,ois Pinard)
|
| 697 | |
|
| 698 | |
Autoconf is a tool for producing shell scripts that automatically
|
| 699 | |
configure software source code packages to adapt to many kinds of
|
| 700 | |
Posix-like systems. The configuration scripts produced by Autoconf
|
| 701 | |
are independent of Autoconf when they are run, so their users do not
|
| 702 | |
need to have Autoconf.
|
| 703 | |
|
| 704 | |
The configuration scripts produced by Autoconf require no manual user
|
| 705 | |
intervention when run; they do not normally even need an argument
|
| 706 | |
specifying the system type. Instead, they individually test for the
|
| 707 | |
presence of each feature that the software package they are for might need.
|
| 708 | |
(Before each check, they print a one-line message stating what they are
|
| 709 | |
checking for, so the user doesn't get too bored while waiting for the
|
| 710 | |
script to finish.) As a result, they deal well with systems that are
|
| 711 | |
hybrids or customized from the more common Posix variants. There is
|
| 712 | |
no need to maintain files that list the features supported by each
|
| 713 | |
release of each variant of Posix.
|
| 714 | |
|
| 715 | |
For each software package that Autoconf is used with, it creates a
|
| 716 | |
configuration script from a template file that lists the system features
|
| 717 | |
that the package needs or can use. After the shell code to recognize
|
| 718 | |
and respond to a system feature has been written, Autoconf allows it to
|
| 719 | |
be shared by many software packages that can use (or need) that feature.
|
| 720 | |
If it later turns out that the shell code needs adjustment for some
|
| 721 | |
reason, it needs to be changed in only one place; all of the
|
| 722 | |
configuration scripts can be regenerated automatically to take advantage
|
| 723 | |
of the updated code.
|
| 724 | |
|
| 725 | |
@c "Those who do not understand Unix are condemned to reinvent it, poorly."
|
| 726 | |
@c --Henry Spencer, 1987 (see http://en.wikipedia.org/wiki/Unix_philosophy)
|
| 727 | |
Those who do not understand Autoconf are condemned to reinvent it, poorly.
|
| 728 | |
The primary goal of Autoconf is making the @emph{user's} life easier;
|
| 729 | |
making the @emph{maintainer's} life easier is only a secondary goal.
|
| 730 | |
Put another way, the primary goal is not to make the generation of
|
| 731 | |
@file{configure} automatic for package maintainers (although patches
|
| 732 | |
along that front are welcome, since package maintainers form the user
|
| 733 | |
base of Autoconf); rather, the goal is to make @file{configure}
|
| 734 | |
painless, portable, and predictable for the end user of each
|
| 735 | |
@dfn{autoconfiscated} package. And to this degree, Autoconf is highly
|
| 736 | |
successful at its goal --- most complaints to the Autoconf list are
|
| 737 | |
about difficulties in writing Autoconf input, and not in the behavior of
|
| 738 | |
the resulting @file{configure}. Even packages that don't use Autoconf
|
| 739 | |
will generally provide a @file{configure} script, and the most common
|
| 740 | |
complaint about these alternative home-grown scripts is that they fail
|
| 741 | |
to meet one or more of the GNU Coding Standards (@pxref{Configuration, , ,
|
| 742 | |
standards, The GNU Coding Standards}) that users
|
| 743 | |
have come to expect from Autoconf-generated @file{configure} scripts.
|
| 744 | |
|
| 745 | |
The Metaconfig package is similar in purpose to Autoconf, but the
|
| 746 | |
scripts it produces require manual user intervention, which is quite
|
| 747 | |
inconvenient when configuring large source trees. Unlike Metaconfig
|
| 748 | |
scripts, Autoconf scripts can support cross-compiling, if some care is
|
| 749 | |
taken in writing them.
|
| 750 | |
|
| 751 | |
Autoconf does not solve all problems related to making portable
|
| 752 | |
software packages---for a more complete solution, it should be used in
|
| 753 | |
concert with other GNU build tools like Automake and
|
| 754 | |
Libtool. These other tools take on jobs like the creation of a
|
| 755 | |
portable, recursive makefile with all of the standard targets,
|
| 756 | |
linking of shared libraries, and so on. @xref{The GNU Build System},
|
| 757 | |
for more information.
|
| 758 | |
|
| 759 | |
Autoconf imposes some restrictions on the names of macros used with
|
| 760 | |
@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
|
| 761 | |
|
| 762 | |
Autoconf requires GNU M4 version 1.4.6 or later in order to
|
| 763 | |
generate the scripts. It uses features that some versions of M4,
|
| 764 | |
including GNU M4 1.3, do not have. Autoconf works better
|
| 765 | |
with GNU M4 version 1.4.14 or later, though this is not
|
| 766 | |
required.
|
| 767 | |
|
| 768 | |
@xref{Autoconf 1}, for information about upgrading from version 1.
|
| 769 | |
@xref{History}, for the story of Autoconf's development. @xref{FAQ},
|
| 770 | |
for answers to some common questions about Autoconf.
|
| 771 | |
|
| 772 | |
See the @uref{http://@/www.gnu.org/@/software/@/autoconf/,
|
| 773 | |
Autoconf web page} for up-to-date information, details on the mailing
|
| 774 | |
lists, pointers to a list of known bugs, etc.
|
| 775 | |
|
| 776 | |
Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
|
| 777 | |
list}. Past suggestions are
|
| 778 | |
@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf/, archived}.
|
| 779 | |
|
| 780 | |
Mail bug reports to @email{bug-autoconf@@gnu.org, the
|
| 781 | |
Autoconf Bugs mailing list}. Past bug reports are
|
| 782 | |
@uref{http://@/lists.gnu.org/@/archive/@/html/@/bug-autoconf/, archived}.
|
| 783 | |
|
| 784 | |
If possible, first check that your bug is
|
| 785 | |
not already solved in current development versions, and that it has not
|
| 786 | |
been reported yet. Be sure to include all the needed information and a
|
| 787 | |
short @file{configure.ac} that demonstrates the problem.
|
| 788 | |
|
| 789 | |
Autoconf's development tree is accessible via @command{git}; see the
|
| 790 | |
@uref{http://@/savannah.gnu.org/@/projects/@/autoconf/, Autoconf
|
| 791 | |
Summary} for details, or view
|
| 792 | |
@uref{http://@/git.sv.gnu.org/@/gitweb/@/?p=autoconf.git, the actual
|
| 793 | |
repository}. Anonymous CVS access is also available, see
|
| 794 | |
@file{README} for more details. Patches relative to the
|
| 795 | |
current @command{git} version can be sent for review to the
|
| 796 | |
@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}, with
|
| 797 | |
discussion on prior patches
|
| 798 | |
@uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-@/patches/,
|
| 799 | |
archived}; and all commits are posted in the read-only
|
| 800 | |
@email{autoconf-commit@@gnu.org, Autoconf Commit mailing list}, which is
|
| 801 | |
also @uref{http://@/lists.gnu.org/@/archive/@/html/@/autoconf-commit/,
|
| 802 | |
archived}.
|
| 803 | |
|
| 804 | |
Because of its mission, the Autoconf package itself
|
| 805 | |
includes only a set of often-used
|
| 806 | |
macros that have already demonstrated their usefulness. Nevertheless,
|
| 807 | |
if you wish to share your macros, or find existing ones, see the
|
| 808 | |
@uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
|
| 809 | |
Archive}, which is kindly run by @email{simons@@cryp.to,
|
| 810 | |
Peter Simons}.
|
| 811 | |
|
| 812 | |
|
| 813 | |
@c ================================================= The GNU Build System
|
| 814 | |
|
| 815 | |
@node The GNU Build System
|
| 816 | |
@chapter The GNU Build System
|
| 817 | |
@cindex GNU build system
|
| 818 | |
|
| 819 | |
Autoconf solves an important problem---reliable discovery of
|
| 820 | |
system-specific build and runtime information---but this is only one
|
| 821 | |
piece of the puzzle for the development of portable software. To this
|
| 822 | |
end, the GNU project has developed a suite of integrated
|
| 823 | |
utilities to finish the job Autoconf started: the GNU build
|
| 824 | |
system, whose most important components are Autoconf, Automake, and
|
| 825 | |
Libtool. In this chapter, we introduce you to those tools, point you
|
| 826 | |
to sources of more information, and try to convince you to use the
|
| 827 | |
entire GNU build system for your software.
|
| 828 | |
|
| 829 | |
@menu
|
| 830 | |
* Automake:: Escaping makefile hell
|
| 831 | |
* Gnulib:: The GNU portability library
|
| 832 | |
* Libtool:: Building libraries portably
|
| 833 | |
* Pointers:: More info on the GNU build system
|
| 834 | |
@end menu
|
| 835 | |
|
| 836 | |
@node Automake
|
| 837 | |
@section Automake
|
| 838 | |
|
| 839 | |
The ubiquity of @command{make} means that a makefile is almost the
|
| 840 | |
only viable way to distribute automatic build rules for software, but
|
| 841 | |
one quickly runs into its numerous limitations. Its lack of
|
| 842 | |
support for automatic dependency tracking, recursive builds in
|
| 843 | |
subdirectories, reliable timestamps (e.g., for network file systems), and
|
| 844 | |
so on, mean that developers must painfully (and often incorrectly)
|
| 845 | |
reinvent the wheel for each project. Portability is non-trivial, thanks
|
| 846 | |
to the quirks of @command{make} on many systems. On top of all this is the
|
| 847 | |
manual labor required to implement the many standard targets that users
|
| 848 | |
have come to expect (@code{make install}, @code{make distclean},
|
| 849 | |
@code{make uninstall}, etc.). Since you are, of course, using Autoconf,
|
| 850 | |
you also have to insert repetitive code in your @file{Makefile.in} to
|
| 851 | |
recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
|
| 852 | |
provided by @command{configure}. Into this mess steps @dfn{Automake}.
|
| 853 | |
@cindex Automake
|
| 854 | |
|
| 855 | |
Automake allows you to specify your build needs in a @file{Makefile.am}
|
| 856 | |
file with a vastly simpler and more powerful syntax than that of a plain
|
| 857 | |
makefile, and then generates a portable @file{Makefile.in} for
|
| 858 | |
use with Autoconf. For example, the @file{Makefile.am} to build and
|
| 859 | |
install a simple ``Hello world'' program might look like:
|
| 860 | |
|
| 861 | |
@example
|
| 862 | |
bin_PROGRAMS = hello
|
| 863 | |
hello_SOURCES = hello.c
|
| 864 | |
@end example
|
| 865 | |
|
| 866 | |
@noindent
|
| 867 | |
The resulting @file{Makefile.in} (~400 lines) automatically supports all
|
| 868 | |
the standard targets, the substitutions provided by Autoconf, automatic
|
| 869 | |
dependency tracking, @code{VPATH} building, and so on. @command{make}
|
| 870 | |
builds the @code{hello} program, and @code{make install} installs it
|
| 871 | |
in @file{/usr/local/bin} (or whatever prefix was given to
|
| 872 | |
@command{configure}, if not @file{/usr/local}).
|
| 873 | |
|
| 874 | |
The benefits of Automake increase for larger packages (especially ones
|
| 875 | |
with subdirectories), but even for small programs the added convenience
|
| 876 | |
and portability can be substantial. And that's not all@enddots{}
|
| 877 | |
|
| 878 | |
@node Gnulib
|
| 879 | |
@section Gnulib
|
| 880 | |
|
| 881 | |
GNU software has a well-deserved reputation for running on
|
| 882 | |
many different types of systems. While our primary goal is to write
|
| 883 | |
software for the GNU system, many users and developers have
|
| 884 | |
been introduced to us through the systems that they were already using.
|
| 885 | |
|
| 886 | |
@cindex Gnulib
|
| 887 | |
Gnulib is a central location for common GNU code, intended to
|
| 888 | |
be shared among free software packages. Its components are typically
|
| 889 | |
shared at the source level, rather than being a library that gets built,
|
| 890 | |
installed, and linked against. The idea is to copy files from Gnulib
|
| 891 | |
into your own source tree. There is no distribution tarball; developers
|
| 892 | |
should just grab source modules from the repository. The source files
|
| 893 | |
are available online, under various licenses, mostly GNU
|
| 894 | |
GPL or GNU LGPL.
|
| 895 | |
|
| 896 | |
Gnulib modules typically contain C source code along with Autoconf
|
| 897 | |
macros used to configure the source code. For example, the Gnulib
|
| 898 | |
@code{stdbool} module implements a @file{stdbool.h} header that nearly
|
| 899 | |
conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
|
| 900 | |
This module contains a source file for the replacement header, along
|
| 901 | |
with an Autoconf macro that arranges to use the replacement header on
|
| 902 | |
old-fashioned systems.
|
| 903 | |
|
| 904 | |
@node Libtool
|
| 905 | |
@section Libtool
|
| 906 | |
|
| 907 | |
Often, one wants to build not only programs, but libraries, so that
|
| 908 | |
other programs can benefit from the fruits of your labor. Ideally, one
|
| 909 | |
would like to produce @emph{shared} (dynamically linked) libraries,
|
| 910 | |
which can be used by multiple programs without duplication on disk or in
|
| 911 | |
memory and can be updated independently of the linked programs.
|
| 912 | |
Producing shared libraries portably, however, is the stuff of
|
| 913 | |
nightmares---each system has its own incompatible tools, compiler flags,
|
| 914 | |
and magic incantations. Fortunately, GNU provides a solution:
|
| 915 | |
@dfn{Libtool}.
|
| 916 | |
@cindex Libtool
|
| 917 | |
|
| 918 | |
Libtool handles all the requirements of building shared libraries for
|
| 919 | |
you, and at this time seems to be the @emph{only} way to do so with any
|
| 920 | |
portability. It also handles many other headaches, such as: the
|
| 921 | |
interaction of Make rules with the variable suffixes of
|
| 922 | |
shared libraries, linking reliably with shared libraries before they are
|
| 923 | |
installed by the superuser, and supplying a consistent versioning system
|
| 924 | |
(so that different versions of a library can be installed or upgraded
|
| 925 | |
without breaking binary compatibility). Although Libtool, like
|
| 926 | |
Autoconf, can be used without Automake, it is most simply utilized in
|
| 927 | |
conjunction with Automake---there, Libtool is used automatically
|
| 928 | |
whenever shared libraries are needed, and you need not know its syntax.
|
| 929 | |
|
| 930 | |
@node Pointers
|
| 931 | |
@section Pointers
|
| 932 | |
|
| 933 | |
Developers who are used to the simplicity of @command{make} for small
|
| 934 | |
projects on a single system might be daunted at the prospect of
|
| 935 | |
learning to use Automake and Autoconf. As your software is
|
| 936 | |
distributed to more and more users, however, you otherwise
|
| 937 | |
quickly find yourself putting lots of effort into reinventing the
|
| 938 | |
services that the GNU build tools provide, and making the
|
| 939 | |
same mistakes that they once made and overcame. (Besides, since
|
| 940 | |
you're already learning Autoconf, Automake is a piece of cake.)
|
| 941 | |
|
| 942 | |
There are a number of places that you can go to for more information on
|
| 943 | |
the GNU build tools.
|
| 944 | |
|
| 945 | |
@itemize @minus
|
| 946 | |
|
| 947 | |
@item Web
|
| 948 | |
|
| 949 | |
The project home pages for
|
| 950 | |
@uref{http://@/www@/.gnu@/.org/@/software/@/autoconf/, Autoconf},
|
| 951 | |
@uref{http://@/www@/.gnu@/.org/@/software/@/automake/, Automake},
|
| 952 | |
@uref{http://@/www@/.gnu@/.org/@/software/@/gnulib/, Gnulib}, and
|
| 953 | |
@uref{http://@/www@/.gnu@/.org/@/software/@/libtool/, Libtool}.
|
| 954 | |
|
| 955 | |
@item Automake Manual
|
| 956 | |
|
| 957 | |
@xref{Top, , Automake, automake, GNU Automake}, for more
|
| 958 | |
information on Automake.
|
| 959 | |
|
| 960 | |
@item Books
|
| 961 | |
|
| 962 | |
The book @cite{GNU Autoconf, Automake and
|
| 963 | |
Libtool}@footnote{@cite{GNU Autoconf, Automake and Libtool},
|
| 964 | |
by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
|
| 965 | |
New Riders), 2000, ISBN 1578701902.} describes the complete GNU
|
| 966 | |
build environment. You can also find
|
| 967 | |
@uref{http://@/sources.redhat.com/@/autobook/, the entire book on-line}.
|
| 968 | |
|
| 969 | |
@end itemize
|
| 970 | |
|
| 971 | |
@c ================================================= Making configure Scripts.
|
| 972 | |
|
| 973 | |
@node Making configure Scripts
|
| 974 | |
@chapter Making @command{configure} Scripts
|
| 975 | |
@cindex @file{aclocal.m4}
|
| 976 | |
@cindex @command{configure}
|
| 977 | |
|
| 978 | |
The configuration scripts that Autoconf produces are by convention
|
| 979 | |
called @command{configure}. When run, @command{configure} creates several
|
| 980 | |
files, replacing configuration parameters in them with appropriate
|
| 981 | |
values. The files that @command{configure} creates are:
|
| 982 | |
|
| 983 | |
@itemize @minus
|
| 984 | |
@item
|
| 985 | |
one or more @file{Makefile} files, usually one in each subdirectory of the
|
| 986 | |
package (@pxref{Makefile Substitutions});
|
| 987 | |
|
| 988 | |
@item
|
| 989 | |
optionally, a C header file, the name of which is configurable,
|
| 990 | |
containing @code{#define} directives (@pxref{Configuration Headers});
|
| 991 | |
|
| 992 | |
@item
|
| 993 | |
a shell script called @file{config.status} that, when run, recreates
|
| 994 | |
the files listed above (@pxref{config.status Invocation});
|
| 995 | |
|
| 996 | |
@item
|
| 997 | |
an optional shell script normally called @file{config.cache}
|
| 998 | |
(created when using @samp{configure --config-cache}) that
|
| 999 | |
saves the results of running many of the tests (@pxref{Cache Files});
|
| 1000 | |
|
| 1001 | |
@item
|
| 1002 | |
a file called @file{config.log} containing any messages produced by
|
| 1003 | |
compilers, to help debugging if @command{configure} makes a mistake.
|
| 1004 | |
@end itemize
|
| 1005 | |
|
| 1006 | |
@cindex @file{configure.in}
|
| 1007 | |
@cindex @file{configure.ac}
|
| 1008 | |
To create a @command{configure} script with Autoconf, you need to write an
|
| 1009 | |
Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
|
| 1010 | |
@command{autoconf} on it. If you write your own feature tests to
|
| 1011 | |
supplement those that come with Autoconf, you might also write files
|
| 1012 | |
called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
|
| 1013 | |
file to contain @code{#define} directives, you might also run
|
| 1014 | |
@command{autoheader}, and you can distribute the generated file
|
| 1015 | |
@file{config.h.in} with the package.
|
| 1016 | |
|
| 1017 | |
Here is a diagram showing how the files that can be used in
|
| 1018 | |
configuration are produced. Programs that are executed are suffixed by
|
| 1019 | |
@samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
|
| 1020 | |
@command{autoconf} and @command{autoheader} also read the installed Autoconf
|
| 1021 | |
macro files (by reading @file{autoconf.m4}).
|
| 1022 | |
|
| 1023 | |
@noindent
|
| 1024 | |
Files used in preparing a software package for distribution, when using
|
| 1025 | |
just Autoconf:
|
| 1026 | |
@example
|
| 1027 | |
your source files --> [autoscan*] --> [configure.scan] --> configure.ac
|
| 1028 | |
|
| 1029 | |
@group
|
| 1030 | |
configure.ac --.
|
| 1031 | |
| .------> autoconf* -----> configure
|
| 1032 | |
[aclocal.m4] --+---+
|
| 1033 | |
| `-----> [autoheader*] --> [config.h.in]
|
| 1034 | |
[acsite.m4] ---'
|
| 1035 | |
@end group
|
| 1036 | |
|
| 1037 | |
Makefile.in
|
| 1038 | |
@end example
|
| 1039 | |
|
| 1040 | |
@noindent
|
| 1041 | |
Additionally, if you use Automake, the following additional productions
|
| 1042 | |
come into play:
|
| 1043 | |
|
| 1044 | |
@example
|
| 1045 | |
@group
|
| 1046 | |
[acinclude.m4] --.
|
| 1047 | |
|
|
| 1048 | |
[local macros] --+--> aclocal* --> aclocal.m4
|
| 1049 | |
|
|
| 1050 | |
configure.ac ----'
|
| 1051 | |
@end group
|
| 1052 | |
|
| 1053 | |
@group
|
| 1054 | |
configure.ac --.
|
| 1055 | |
+--> automake* --> Makefile.in
|
| 1056 | |
Makefile.am ---'
|
| 1057 | |
@end group
|
| 1058 | |
@end example
|
| 1059 | |
|
| 1060 | |
@noindent
|
| 1061 | |
Files used in configuring a software package:
|
| 1062 | |
@example
|
| 1063 | |
@group
|
| 1064 | |
.-------------> [config.cache]
|
| 1065 | |
configure* ------------+-------------> config.log
|
| 1066 | |
|
|
| 1067 | |
[config.h.in] -. v .-> [config.h] -.
|
| 1068 | |
+--> config.status* -+ +--> make*
|
| 1069 | |
Makefile.in ---' `-> Makefile ---'
|
| 1070 | |
@end group
|
| 1071 | |
@end example
|
| 1072 | |
|
| 1073 | |
@menu
|
| 1074 | |
* Writing Autoconf Input:: What to put in an Autoconf input file
|
| 1075 | |
* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
|
| 1076 | |
* ifnames Invocation:: Listing the conditionals in source code
|
| 1077 | |
* autoconf Invocation:: How to create configuration scripts
|
| 1078 | |
* autoreconf Invocation:: Remaking multiple @command{configure} scripts
|
| 1079 | |
@end menu
|
| 1080 | |
|
| 1081 | |
@node Writing Autoconf Input
|
| 1082 | |
@section Writing @file{configure.ac}
|
| 1083 | |
|
| 1084 | |
To produce a @command{configure} script for a software package, create a
|
| 1085 | |
file called @file{configure.ac} that contains invocations of the
|
| 1086 | |
Autoconf macros that test the system features your package needs or can
|
| 1087 | |
use. Autoconf macros already exist to check for many features; see
|
| 1088 | |
@ref{Existing Tests}, for their descriptions. For most other features,
|
| 1089 | |
you can use Autoconf template macros to produce custom checks; see
|
| 1090 | |
@ref{Writing Tests}, for information about them. For especially tricky
|
| 1091 | |
or specialized features, @file{configure.ac} might need to contain some
|
| 1092 | |
hand-crafted shell commands; see @ref{Portable Shell, , Portable Shell
|
| 1093 | |
Programming}. The @command{autoscan} program can give you a good start
|
| 1094 | |
in writing @file{configure.ac} (@pxref{autoscan Invocation}, for more
|
| 1095 | |
information).
|
| 1096 | |
|
| 1097 | |
Previous versions of Autoconf promoted the name @file{configure.in},
|
| 1098 | |
which is somewhat ambiguous (the tool needed to process this file is not
|
| 1099 | |
described by its extension), and introduces a slight confusion with
|
| 1100 | |
@file{config.h.in} and so on (for which @samp{.in} means ``to be
|
| 1101 | |
processed by @command{configure}''). Using @file{configure.ac} is now
|
| 1102 | |
preferred.
|
| 1103 | |
|
| 1104 | |
@menu
|
| 1105 | |
* Shell Script Compiler:: Autoconf as solution of a problem
|
| 1106 | |
* Autoconf Language:: Programming in Autoconf
|
| 1107 | |
* Autoconf Input Layout:: Standard organization of @file{configure.ac}
|
| 1108 | |
@end menu
|
| 1109 | |
|
| 1110 | |
@node Shell Script Compiler
|
| 1111 | |
@subsection A Shell Script Compiler
|
| 1112 | |
|
| 1113 | |
Just as for any other computer language, in order to properly program
|
| 1114 | |
@file{configure.ac} in Autoconf you must understand @emph{what} problem
|
| 1115 | |
the language tries to address and @emph{how} it does so.
|
| 1116 | |
|
| 1117 | |
The problem Autoconf addresses is that the world is a mess. After all,
|
| 1118 | |
you are using Autoconf in order to have your package compile easily on
|
| 1119 | |
all sorts of different systems, some of them being extremely hostile.
|
| 1120 | |
Autoconf itself bears the price for these differences: @command{configure}
|
| 1121 | |
must run on all those systems, and thus @command{configure} must limit itself
|
| 1122 | |
to their lowest common denominator of features.
|
| 1123 | |
|
| 1124 | |
Naturally, you might then think of shell scripts; who needs
|
| 1125 | |
@command{autoconf}? A set of properly written shell functions is enough to
|
| 1126 | |
make it easy to write @command{configure} scripts by hand. Sigh!
|
| 1127 | |
Unfortunately, even in 2008, where shells without any function support are
|
| 1128 | |
far and few between, there are pitfalls to avoid when making use of them.
|
| 1129 | |
Also, finding a Bourne shell that accepts shell functions is not trivial,
|
| 1130 | |
even though there is almost always one on interesting porting targets.
|
| 1131 | |
|
| 1132 | |
So, what is really needed is some kind of compiler, @command{autoconf},
|
| 1133 | |
that takes an Autoconf program, @file{configure.ac}, and transforms it
|
| 1134 | |
into a portable shell script, @command{configure}.
|
| 1135 | |
|
| 1136 | |
How does @command{autoconf} perform this task?
|
| 1137 | |
|
| 1138 | |
There are two obvious possibilities: creating a brand new language or
|
| 1139 | |
extending an existing one. The former option is attractive: all
|
| 1140 | |
sorts of optimizations could easily be implemented in the compiler and
|
| 1141 | |
many rigorous checks could be performed on the Autoconf program
|
| 1142 | |
(e.g., rejecting any non-portable construct). Alternatively, you can
|
| 1143 | |
extend an existing language, such as the @code{sh} (Bourne shell)
|
| 1144 | |
language.
|
| 1145 | |
|
| 1146 | |
Autoconf does the latter: it is a layer on top of @code{sh}. It was
|
| 1147 | |
therefore most convenient to implement @command{autoconf} as a macro
|
| 1148 | |
expander: a program that repeatedly performs @dfn{macro expansions} on
|
| 1149 | |
text input, replacing macro calls with macro bodies and producing a pure
|
| 1150 | |
@code{sh} script in the end. Instead of implementing a dedicated
|
| 1151 | |
Autoconf macro expander, it is natural to use an existing
|
| 1152 | |
general-purpose macro language, such as M4, and implement the extensions
|
| 1153 | |
as a set of M4 macros.
|
| 1154 | |
|
| 1155 | |
|
| 1156 | |
@node Autoconf Language
|
| 1157 | |
@subsection The Autoconf Language
|
| 1158 | |
@cindex quotation
|
| 1159 | |
|
| 1160 | |
The Autoconf language differs from many other computer
|
| 1161 | |
languages because it treats actual code the same as plain text. Whereas
|
| 1162 | |
in C, for instance, data and instructions have different syntactic
|
| 1163 | |
status, in Autoconf their status is rigorously the same. Therefore, we
|
| 1164 | |
need a means to distinguish literal strings from text to be expanded:
|
| 1165 | |
quotation.
|
| 1166 | |
|
| 1167 | |
When calling macros that take arguments, there must not be any white
|
| 1168 | |
space between the macro name and the open parenthesis.
|
| 1169 | |
|
| 1170 | |
@example
|
| 1171 | |
AC_INIT ([oops], [1.0]) # incorrect
|
| 1172 | |
AC_INIT([hello], [1.0]) # good
|
| 1173 | |
@end example
|
| 1174 | |
|
| 1175 | |
Arguments should
|
| 1176 | |
be enclosed within the quote characters @samp{[} and @samp{]}, and be
|
| 1177 | |
separated by commas. Any leading blanks or newlines in arguments are ignored,
|
| 1178 | |
unless they are quoted. You should always quote an argument that
|
| 1179 | |
might contain a macro name, comma, parenthesis, or a leading blank or
|
| 1180 | |
newline. This rule applies recursively for every macro
|
| 1181 | |
call, including macros called from other macros. For more details on
|
| 1182 | |
quoting rules, see @ref{Programming in M4}.
|
| 1183 | |
|
| 1184 | |
For instance:
|
| 1185 | |
|
| 1186 | |
@example
|
| 1187 | |
AC_CHECK_HEADER([stdio.h],
|
| 1188 | |
[AC_DEFINE([HAVE_STDIO_H], [1],
|
| 1189 | |
[Define to 1 if you have <stdio.h>.])],
|
| 1190 | |
[AC_MSG_ERROR([sorry, can't do anything for you])])
|
| 1191 | |
@end example
|
| 1192 | |
|
| 1193 | |
@noindent
|
| 1194 | |
is quoted properly. You may safely simplify its quotation to:
|
| 1195 | |
|
| 1196 | |
@example
|
| 1197 | |
AC_CHECK_HEADER([stdio.h],
|
| 1198 | |
[AC_DEFINE([HAVE_STDIO_H], 1,
|
| 1199 | |
[Define to 1 if you have <stdio.h>.])],
|
| 1200 | |
[AC_MSG_ERROR([sorry, can't do anything for you])])
|
| 1201 | |
@end example
|
| 1202 | |
|
| 1203 | |
@noindent
|
| 1204 | |
because @samp{1} cannot contain a macro call. Here, the argument of
|
| 1205 | |
@code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
|
| 1206 | |
interpreted as an argument separator. Also, the second and third arguments
|
| 1207 | |
of @samp{AC_CHECK_HEADER} must be quoted, since they contain
|
| 1208 | |
macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
|
| 1209 | |
and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
|
| 1210 | |
if you unwisely defined a macro with a name like @samp{Define} or
|
| 1211 | |
@samp{stdio} then they would need quoting. Cautious Autoconf users
|
| 1212 | |
would keep the quotes, but many Autoconf users find such precautions
|
| 1213 | |
annoying, and would rewrite the example as follows:
|
| 1214 | |
|
| 1215 | |
@example
|
| 1216 | |
AC_CHECK_HEADER(stdio.h,
|
| 1217 | |
[AC_DEFINE(HAVE_STDIO_H, 1,
|
| 1218 | |
[Define to 1 if you have <stdio.h>.])],
|
| 1219 | |
[AC_MSG_ERROR([sorry, can't do anything for you])])
|
| 1220 | |
@end example
|
| 1221 | |
|
| 1222 | |
@noindent
|
| 1223 | |
This is safe, so long as you adopt good naming conventions and do not
|
| 1224 | |
define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
|
| 1225 | |
@samp{h}. Though it is also safe here to omit the quotes around
|
| 1226 | |
@samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
|
| 1227 | |
message strings are more likely to inadvertently contain commas.
|
| 1228 | |
|
| 1229 | |
The following example is wrong and dangerous, as it is underquoted:
|
| 1230 | |
|
| 1231 | |
@example
|
| 1232 | |
AC_CHECK_HEADER(stdio.h,
|
| 1233 | |
AC_DEFINE(HAVE_STDIO_H, 1,
|
| 1234 | |
Define to 1 if you have <stdio.h>.),
|
| 1235 | |
AC_MSG_ERROR([sorry, can't do anything for you]))
|
| 1236 | |
@end example
|
| 1237 | |
|
| 1238 | |
In other cases, you may have to use text that also resembles a macro
|
| 1239 | |
call. You must quote that text even when it is not passed as a macro
|
| 1240 | |
argument. For example, these two approaches in @file{configure.ac}
|
| 1241 | |
(quoting just the potential problems, or quoting the entire line) will
|
| 1242 | |
protect your script in case autoconf ever adds a macro @code{AC_DC}:
|
| 1243 | |
|
| 1244 | |
@example
|
| 1245 | |
echo "Hard rock was here! --[AC_DC]"
|
| 1246 | |
[echo "Hard rock was here! --AC_DC"]
|
| 1247 | |
@end example
|
| 1248 | |
|
| 1249 | |
@noindent
|
| 1250 | |
which results in this text in @file{configure}:
|
| 1251 | |
|
| 1252 | |
@example
|
| 1253 | |
echo "Hard rock was here! --AC_DC"
|
| 1254 | |
echo "Hard rock was here! --AC_DC"
|
| 1255 | |
@end example
|
| 1256 | |
|
| 1257 | |
@noindent
|
| 1258 | |
When you use the same text in a macro argument, you must therefore have
|
| 1259 | |
an extra quotation level (since one is stripped away by the macro
|
| 1260 | |
substitution). In general, then, it is a good idea to @emph{use double
|
| 1261 | |
quoting for all literal string arguments}, either around just the
|
| 1262 | |
problematic portions, or over the entire argument:
|
| 1263 | |
|
| 1264 | |
@example
|
| 1265 | |
AC_MSG_WARN([[AC_DC] stinks --Iron Maiden])
|
| 1266 | |
AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
|
| 1267 | |
@end example
|
| 1268 | |
|
| 1269 | |
However, the above example triggers a warning about a possibly
|
| 1270 | |
unexpanded macro when running @command{autoconf}, because it collides
|
| 1271 | |
with the namespace of macros reserved for the Autoconf language. To be
|
| 1272 | |
really safe, you can use additional escaping (either a quadrigraph, or
|
| 1273 | |
creative shell constructs) to silence that particular warning:
|
| 1274 | |
|
| 1275 | |
@example
|
| 1276 | |
echo "Hard rock was here! --AC""_DC"
|
| 1277 | |
AC_MSG_WARN([[AC@@&t@@_DC stinks --Iron Maiden]])
|
| 1278 | |
@end example
|
| 1279 | |
|
| 1280 | |
You are now able to understand one of the constructs of Autoconf that
|
| 1281 | |
has been continually misunderstood@enddots{} The rule of thumb is that
|
| 1282 | |
@emph{whenever you expect macro expansion, expect quote expansion};
|
| 1283 | |
i.e., expect one level of quotes to be lost. For instance:
|
| 1284 | |
|
| 1285 | |
@example
|
| 1286 | |
AC_COMPILE_IFELSE(AC_LANG_SOURCE([char b[10];]), [],
|
| 1287 | |
[AC_MSG_ERROR([you lose])])
|
| 1288 | |
@end example
|
| 1289 | |
|
| 1290 | |
@noindent
|
| 1291 | |
is incorrect: here, the first argument of @code{AC_LANG_SOURCE} is
|
| 1292 | |
@samp{char b[10];} and is expanded once, which results in
|
| 1293 | |
@samp{char b10;}; and the @code{AC_LANG_SOURCE} is also expanded prior
|
| 1294 | |
to being passed to @code{AC_COMPILE_IFELSE}. (There was an idiom common
|
| 1295 | |
in Autoconf's past to
|
| 1296 | |
address this issue via the M4 @code{changequote} primitive, but do not
|
| 1297 | |
use it!) Let's take a closer look: the author meant the first argument
|
| 1298 | |
to be understood as a literal, and therefore it must be quoted twice;
|
| 1299 | |
likewise, the intermediate @code{AC_LANG_SOURCE} macro should be quoted
|
| 1300 | |
once so that it is only expanded after the rest of the body of
|
| 1301 | |
@code{AC_COMPILE_IFELSE} is in place:
|
| 1302 | |
|
| 1303 | |
@example
|
| 1304 | |
AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [],
|
| 1305 | |
[AC_MSG_ERROR([you lose])])
|
| 1306 | |
@end example
|
| 1307 | |
|
| 1308 | |
@noindent
|
| 1309 | |
Voil@`a, you actually produce @samp{char b[10];} this time!
|
| 1310 | |
|
| 1311 | |
On the other hand, descriptions (e.g., the last parameter of
|
| 1312 | |
@code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
|
| 1313 | |
are subject to line breaking, for example---and should not be double quoted.
|
| 1314 | |
Even if these descriptions are short and are not actually broken, double
|
| 1315 | |
quoting them yields weird results.
|
| 1316 | |
|
| 1317 | |
Some macros take optional arguments, which this documentation represents
|
| 1318 | |
as @ovar{arg} (not to be confused with the quote characters). You may
|
| 1319 | |
just leave them empty, or use @samp{[]} to make the emptiness of the
|
| 1320 | |
argument explicit, or you may simply omit the trailing commas. The
|
| 1321 | |
three lines below are equivalent:
|
| 1322 | |
|
| 1323 | |
@example
|
| 1324 | |
AC_CHECK_HEADERS([stdio.h], [], [], [])
|
| 1325 | |
AC_CHECK_HEADERS([stdio.h],,,)
|
| 1326 | |
AC_CHECK_HEADERS([stdio.h])
|
| 1327 | |
@end example
|
| 1328 | |
|
| 1329 | |
It is best to put each macro call on its own line in
|
| 1330 | |
@file{configure.ac}. Most of the macros don't add extra newlines; they
|
| 1331 | |
rely on the newline after the macro call to terminate the commands.
|
| 1332 | |
This approach makes the generated @command{configure} script a little
|
| 1333 | |
easier to read by not inserting lots of blank lines. It is generally
|
| 1334 | |
safe to set shell variables on the same line as a macro call, because
|
| 1335 | |
the shell allows assignments without intervening newlines.
|
| 1336 | |
|
| 1337 | |
You can include comments in @file{configure.ac} files by starting them
|
| 1338 | |
with the @samp{#}. For example, it is helpful to begin
|
| 1339 | |
@file{configure.ac} files with a line like this:
|
| 1340 | |
|
| 1341 | |
@example
|
| 1342 | |
# Process this file with autoconf to produce a configure script.
|
| 1343 | |
@end example
|
| 1344 | |
|
| 1345 | |
@node Autoconf Input Layout
|
| 1346 | |
@subsection Standard @file{configure.ac} Layout
|
| 1347 | |
|
| 1348 | |
The order in which @file{configure.ac} calls the Autoconf macros is not
|
| 1349 | |
important, with a few exceptions. Every @file{configure.ac} must
|
| 1350 | |
contain a call to @code{AC_INIT} before the checks, and a call to
|
| 1351 | |
@code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
|
| 1352 | |
rely on other macros having been called first, because they check
|
| 1353 | |
previously set values of some variables to decide what to do. These
|
| 1354 | |
macros are noted in the individual descriptions (@pxref{Existing
|
| 1355 | |
Tests}), and they also warn you when @command{configure} is created if they
|
| 1356 | |
are called out of order.
|
| 1357 | |
|
| 1358 | |
To encourage consistency, here is a suggested order for calling the
|
| 1359 | |
Autoconf macros. Generally speaking, the things near the end of this
|
| 1360 | |
list are those that could depend on things earlier in it. For example,
|
| 1361 | |
library functions could be affected by types and libraries.
|
| 1362 | |
|
| 1363 | |
@display
|
| 1364 | |
@group
|
| 1365 | |
Autoconf requirements
|
| 1366 | |
@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
|
| 1367 | |
information on the package
|
| 1368 | |
checks for programs
|
| 1369 | |
checks for libraries
|
| 1370 | |
checks for header files
|
| 1371 | |
checks for types
|
| 1372 | |
checks for structures
|
| 1373 | |
checks for compiler characteristics
|
| 1374 | |
checks for library functions
|
| 1375 | |
checks for system services
|
| 1376 | |
@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
|
| 1377 | |
@code{AC_OUTPUT}
|
| 1378 | |
@end group
|
| 1379 | |
@end display
|
| 1380 | |
|
| 1381 | |
|
| 1382 | |
@node autoscan Invocation
|
| 1383 | |
@section Using @command{autoscan} to Create @file{configure.ac}
|
| 1384 | |
@cindex @command{autoscan}
|
| 1385 | |
|
| 1386 | |
The @command{autoscan} program can help you create and/or maintain a
|
| 1387 | |
@file{configure.ac} file for a software package. @command{autoscan}
|
| 1388 | |
examines source files in the directory tree rooted at a directory given
|
| 1389 | |
as a command line argument, or the current directory if none is given.
|
| 1390 | |
It searches the source files for common portability problems and creates
|
| 1391 | |
a file @file{configure.scan} which is a preliminary @file{configure.ac}
|
| 1392 | |
for that package, and checks a possibly existing @file{configure.ac} for
|
| 1393 | |
completeness.
|
| 1394 | |
|
| 1395 | |
When using @command{autoscan} to create a @file{configure.ac}, you
|
| 1396 | |
should manually examine @file{configure.scan} before renaming it to
|
| 1397 | |
@file{configure.ac}; it probably needs some adjustments.
|
| 1398 | |
Occasionally, @command{autoscan} outputs a macro in the wrong order
|
| 1399 | |
relative to another macro, so that @command{autoconf} produces a warning;
|
| 1400 | |
you need to move such macros manually. Also, if you want the package to
|
| 1401 | |
use a configuration header file, you must add a call to
|
| 1402 | |
@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
|
| 1403 | |
also have to change or add some @code{#if} directives to your program in
|
| 1404 | |
order to make it work with Autoconf (@pxref{ifnames Invocation}, for
|
| 1405 | |
information about a program that can help with that job).
|
| 1406 | |
|
| 1407 | |
When using @command{autoscan} to maintain a @file{configure.ac}, simply
|
| 1408 | |
consider adding its suggestions. The file @file{autoscan.log}
|
| 1409 | |
contains detailed information on why a macro is requested.
|
| 1410 | |
|
| 1411 | |
@command{autoscan} uses several data files (installed along with Autoconf)
|
| 1412 | |
to determine which macros to output when it finds particular symbols in
|
| 1413 | |
a package's source files. These data files all have the same format:
|
| 1414 | |
each line consists of a symbol, one or more blanks, and the Autoconf macro to
|
| 1415 | |
output if that symbol is encountered. Lines starting with @samp{#} are
|
| 1416 | |
comments.
|
| 1417 | |
|
| 1418 | |
@command{autoscan} accepts the following options:
|
| 1419 | |
|
| 1420 | |
@table @option
|
| 1421 | |
@item --help
|
| 1422 | |
@itemx -h
|
| 1423 | |
Print a summary of the command line options and exit.
|
| 1424 | |
|
| 1425 | |
@item --version
|
| 1426 | |
@itemx -V
|
| 1427 | |
Print the version number of Autoconf and exit.
|
| 1428 | |
|
| 1429 | |
@item --verbose
|
| 1430 | |
@itemx -v
|
| 1431 | |
Print the names of the files it examines and the potentially interesting
|
| 1432 | |
symbols it finds in them. This output can be voluminous.
|
| 1433 | |
|
| 1434 | |
@item --debug
|
| 1435 | |
@itemx -d
|
| 1436 | |
Don't remove temporary files.
|
| 1437 | |
|
| 1438 | |
@item --include=@var{dir}
|
| 1439 | |
@itemx -I @var{dir}
|
| 1440 | |
Append @var{dir} to the include path. Multiple invocations accumulate.
|
| 1441 | |
|
| 1442 | |
@item --prepend-include=@var{dir}
|
| 1443 | |
@itemx -B @var{dir}
|
| 1444 | |
Prepend @var{dir} to the include path. Multiple invocations accumulate.
|
| 1445 | |
@end table
|
| 1446 | |
|
| 1447 | |
@node ifnames Invocation
|
| 1448 | |
@section Using @command{ifnames} to List Conditionals
|
| 1449 | |
@cindex @command{ifnames}
|
| 1450 | |
|
| 1451 | |
@command{ifnames} can help you write @file{configure.ac} for a software
|
| 1452 | |
package. It prints the identifiers that the package already uses in C
|
| 1453 | |
preprocessor conditionals. If a package has already been set up to have
|
| 1454 | |
some portability, @command{ifnames} can thus help you figure out what its
|
| 1455 | |
@command{configure} needs to check for. It may help fill in some gaps in a
|
| 1456 | |
@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
|
| 1457 | |
Invocation}).
|
| 1458 | |
|
| 1459 | |
@command{ifnames} scans all of the C source files named on the command line
|
| 1460 | |
(or the standard input, if none are given) and writes to the standard
|
| 1461 | |
output a sorted list of all the identifiers that appear in those files
|
| 1462 | |
in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
|
| 1463 | |
directives. It prints each identifier on a line, followed by a
|
| 1464 | |
space-separated list of the files in which that identifier occurs.
|
| 1465 | |
|
| 1466 | |
@noindent
|
| 1467 | |
@command{ifnames} accepts the following options:
|
| 1468 | |
|
| 1469 | |
@table @option
|
| 1470 | |
@item --help
|
| 1471 | |
@itemx -h
|
| 1472 | |
Print a summary of the command line options and exit.
|
| 1473 | |
|
| 1474 | |
@item --version
|
| 1475 | |
@itemx -V
|
| 1476 | |
Print the version number of Autoconf and exit.
|
| 1477 | |
@end table
|
| 1478 | |
|
| 1479 | |
@node autoconf Invocation
|
| 1480 | |
@section Using @command{autoconf} to Create @command{configure}
|
| 1481 | |
@cindex @command{autoconf}
|
| 1482 | |
|
| 1483 | |
To create @command{configure} from @file{configure.ac}, run the
|
| 1484 | |
@command{autoconf} program with no arguments. @command{autoconf} processes
|
| 1485 | |
@file{configure.ac} with the M4 macro processor, using the
|
| 1486 | |
Autoconf macros. If you give @command{autoconf} an argument, it reads that
|
| 1487 | |
file instead of @file{configure.ac} and writes the configuration script
|
| 1488 | |
to the standard output instead of to @command{configure}. If you give
|
| 1489 | |
@command{autoconf} the argument @option{-}, it reads from the standard
|
| 1490 | |
input instead of @file{configure.ac} and writes the configuration script
|
| 1491 | |
to the standard output.
|
| 1492 | |
|
| 1493 | |
The Autoconf macros are defined in several files. Some of the files are
|
| 1494 | |
distributed with Autoconf; @command{autoconf} reads them first. Then it
|
| 1495 | |
looks for the optional file @file{acsite.m4} in the directory that
|
| 1496 | |
contains the distributed Autoconf macro files, and for the optional file
|
| 1497 | |
@file{aclocal.m4} in the current directory. Those files can contain
|
| 1498 | |
your site's or the package's own Autoconf macro definitions
|
| 1499 | |
(@pxref{Writing Autoconf Macros}, for more information). If a macro is
|
| 1500 | |
defined in more than one of the files that @command{autoconf} reads, the
|
| 1501 | |
last definition it reads overrides the earlier ones.
|
| 1502 | |
|
| 1503 | |
@command{autoconf} accepts the following options:
|
| 1504 | |
|
| 1505 | |
@table @option
|
| 1506 | |
@item --help
|
| 1507 | |
@itemx -h
|
| 1508 | |
Print a summary of the command line options and exit.
|
| 1509 | |
|
| 1510 | |
@item --version
|
| 1511 | |
@itemx -V
|
| 1512 | |
Print the version number of Autoconf and exit.
|
| 1513 | |
|
| 1514 | |
@item --verbose
|
| 1515 | |
@itemx -v
|
| 1516 | |
Report processing steps.
|
| 1517 | |
|
| 1518 | |
@item --debug
|
| 1519 | |
@itemx -d
|
| 1520 | |
Don't remove the temporary files.
|
| 1521 | |
|
| 1522 | |
@item --force
|
| 1523 | |
@itemx -f
|
| 1524 | |
Remake @file{configure} even if newer than its input files.
|
| 1525 | |
|
| 1526 | |
@item --include=@var{dir}
|
| 1527 | |
@itemx -I @var{dir}
|
| 1528 | |
Append @var{dir} to the include path. Multiple invocations accumulate.
|
| 1529 | |
|
| 1530 | |
@item --prepend-include=@var{dir}
|
| 1531 | |
@itemx -B @var{dir}
|
| 1532 | |
Prepend @var{dir} to the include path. Multiple invocations accumulate.
|
| 1533 | |
|
| 1534 | |
@item --output=@var{file}
|
| 1535 | |
@itemx -o @var{file}
|
| 1536 | |
Save output (script or trace) to @var{file}. The file @option{-} stands
|
| 1537 | |
for the standard output.
|
| 1538 | |
|
| 1539 | |
@item --warnings=@var{category}
|
| 1540 | |
@itemx -W @var{category}
|
| 1541 | |
@evindex WARNINGS
|
| 1542 | |
Report the warnings related to @var{category} (which can actually be a
|
| 1543 | |
comma separated list). @xref{Reporting Messages}, macro
|
| 1544 | |
@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
|
| 1545 | |
values include:
|
| 1546 | |
|
| 1547 | |
@table @samp
|
| 1548 | |
@item all
|
| 1549 | |
report all the warnings
|
| 1550 | |
|
| 1551 | |
@item none
|
| 1552 | |
report none
|
| 1553 | |
|
| 1554 | |
@item error
|
| 1555 | |
treats warnings as errors
|
| 1556 | |
|
| 1557 | |
@item no-@var{category}
|
| 1558 | |
disable warnings falling into @var{category}
|
| 1559 | |
@end table
|
| 1560 | |
|
| 1561 | |
Warnings about @samp{syntax} are enabled by default, and the environment
|
| 1562 | |
variable @env{WARNINGS}, a comma separated list of categories, is
|
| 1563 | |
honored as well. Passing @option{-W @var{category}} actually behaves as if
|
| 1564 | |
you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To
|
| 1565 | |
disable the defaults and @env{WARNINGS}, and then
|
| 1566 | |
enable warnings about obsolete constructs, use @option{-W
|
| 1567 | |
none,obsolete}.
|
| 1568 | |
|
| 1569 | |
@cindex Back trace
|
| 1570 | |
@cindex Macro invocation stack
|
| 1571 | |
Because @command{autoconf} uses @command{autom4te} behind the scenes, it
|
| 1572 | |
displays a back trace for errors, but not for warnings; if you want
|
| 1573 | |
them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
|
| 1574 | |
examples.
|
| 1575 | |
|
| 1576 | |
@item --trace=@var{macro}[:@var{format}]
|
| 1577 | |
@itemx -t @var{macro}[:@var{format}]
|
| 1578 | |
Do not create the @command{configure} script, but list the calls to
|
| 1579 | |
@var{macro} according to the @var{format}. Multiple @option{--trace}
|
| 1580 | |
arguments can be used to list several macros. Multiple @option{--trace}
|
| 1581 | |
arguments for a single macro are not cumulative; instead, you should
|
| 1582 | |
just make @var{format} as long as needed.
|
| 1583 | |
|
| 1584 | |
The @var{format} is a regular string, with newlines if desired, and
|
| 1585 | |
several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
|
| 1586 | |
@ref{autom4te Invocation}, for details on the @var{format}.
|
| 1587 | |
|
| 1588 | |
@item --initialization
|
| 1589 | |
@itemx -i
|
| 1590 | |
By default, @option{--trace} does not trace the initialization of the
|
| 1591 | |
Autoconf macros (typically the @code{AC_DEFUN} definitions). This
|
| 1592 | |
results in a noticeable speedup, but can be disabled by this option.
|
| 1593 | |
@end table
|
| 1594 | |
|
| 1595 | |
|
| 1596 | |
It is often necessary to check the content of a @file{configure.ac}
|
| 1597 | |
file, but parsing it yourself is extremely fragile and error-prone. It
|
| 1598 | |
is suggested that you rely upon @option{--trace} to scan
|
| 1599 | |
@file{configure.ac}. For instance, to find the list of variables that
|
| 1600 | |
are substituted, use:
|
| 1601 | |
|
| 1602 | |
@example
|
| 1603 | |
@group
|
| 1604 | |
$ @kbd{autoconf -t AC_SUBST}
|
| 1605 | |
configure.ac:2:AC_SUBST:ECHO_C
|
| 1606 | |
configure.ac:2:AC_SUBST:ECHO_N
|
| 1607 | |
configure.ac:2:AC_SUBST:ECHO_T
|
| 1608 | |
@i{More traces deleted}
|
| 1609 | |
@end group
|
| 1610 | |
@end example
|
| 1611 | |
|
| 1612 | |
@noindent
|
| 1613 | |
The example below highlights the difference between @samp{$@@},
|
| 1614 | |
@samp{$*}, and @samp{$%}.
|
| 1615 | |
|
| 1616 | |
@example
|
| 1617 | |
@group
|
| 1618 | |
$ @kbd{cat configure.ac}
|
| 1619 | |
AC_DEFINE(This, is, [an
|
| 1620 | |
[example]])
|
| 1621 | |
$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
|
| 1622 | |
*: $*
|
| 1623 | |
%: $%'
|
| 1624 | |
@@: [This],[is],[an
|
| 1625 | |
[example]]
|
| 1626 | |
*: This,is,an
|
| 1627 | |
[example]
|
| 1628 | |
%: This:is:an [example]
|
| 1629 | |
@end group
|
| 1630 | |
@end example
|
| 1631 | |
|
| 1632 | |
@noindent
|
| 1633 | |
The @var{format} gives you a lot of freedom:
|
| 1634 | |
|
| 1635 | |
@example
|
| 1636 | |
@group
|
| 1637 | |
$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
|
| 1638 | |
$ac_subst@{"ECHO_C"@} = "configure.ac:2";
|
| 1639 | |
$ac_subst@{"ECHO_N"@} = "configure.ac:2";
|
| 1640 | |
$ac_subst@{"ECHO_T"@} = "configure.ac:2";
|
| 1641 | |
@i{More traces deleted}
|
| 1642 | |
@end group
|
| 1643 | |
@end example
|
| 1644 | |
|
| 1645 | |
@noindent
|
| 1646 | |
A long @var{separator} can be used to improve the readability of complex
|
| 1647 | |
structures, and to ease their parsing (for instance when no single
|
| 1648 | |
character is suitable as a separator):
|
| 1649 | |
|
| 1650 | |
@example
|
| 1651 | |
@group
|
| 1652 | |
$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
|
| 1653 | |
ACLOCAL|:::::|aclocal|:::::|$missing_dir
|
| 1654 | |
AUTOCONF|:::::|autoconf|:::::|$missing_dir
|
| 1655 | |
AUTOMAKE|:::::|automake|:::::|$missing_dir
|
| 1656 | |
@i{More traces deleted}
|
| 1657 | |
@end group
|
| 1658 | |
@end example
|
| 1659 | |
|
| 1660 | |
@node autoreconf Invocation
|
| 1661 | |
@section Using @command{autoreconf} to Update @command{configure} Scripts
|
| 1662 | |
@cindex @command{autoreconf}
|
| 1663 | |
|
| 1664 | |
Installing the various components of the GNU Build System can be
|
| 1665 | |
tedious: running @command{autopoint} for Gettext, @command{automake} for
|
| 1666 | |
@file{Makefile.in} etc.@: in each directory. It may be needed either
|
| 1667 | |
because some tools such as @command{automake} have been updated on your
|
| 1668 | |
system, or because some of the sources such as @file{configure.ac} have
|
| 1669 | |
been updated, or finally, simply in order to install the GNU Build
|
| 1670 | |
System in a fresh tree.
|
| 1671 | |
|
| 1672 | |
@command{autoreconf} runs @command{autoconf}, @command{autoheader},
|
| 1673 | |
@command{aclocal}, @command{automake}, @command{libtoolize}, and
|
| 1674 | |
@command{autopoint} (when appropriate) repeatedly to update the
|
| 1675 | |
GNU Build System in the specified directories and their
|
| 1676 | |
subdirectories (@pxref{Subdirectories}). By default, it only remakes
|
| 1677 | |
those files that are older than their sources. The environment variables
|
| 1678 | |
@env{AUTOM4TE}, @env{AUTOCONF}, @env{AUTOHEADER}, @env{AUTOMAKE},
|
| 1679 | |
@env{ACLOCAL}, @env{AUTOPOINT}, @env{LIBTOOLIZE}, @env{M4}, and @env{MAKE}
|
| 1680 | |
may be used to override the invocation of the respective tools.
|
| 1681 | |
|
| 1682 | |
If you install a new version of some tool, you can make
|
| 1683 | |
@command{autoreconf} remake @emph{all} of the files by giving it the
|
| 1684 | |
@option{--force} option.
|
| 1685 | |
|
| 1686 | |
@xref{Automatic Remaking}, for Make rules to automatically
|
| 1687 | |
rebuild @command{configure} scripts when their source files change. That
|
| 1688 | |
method handles the timestamps of configuration header templates
|
| 1689 | |
properly, but does not pass @option{--autoconf-dir=@var{dir}} or
|
| 1690 | |
@option{--localdir=@var{dir}}.
|
| 1691 | |
|
| 1692 | |
@cindex Gettext
|
| 1693 | |
@cindex @command{autopoint}
|
| 1694 | |
Gettext supplies the @command{autopoint} command to add translation
|
| 1695 | |
infrastructure to a source package. If you use @command{autopoint},
|
| 1696 | |
your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
|
| 1697 | |
@code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
|
| 1698 | |
Invocation, , Invoking the @code{autopoint} Program, gettext,
|
| 1699 | |
GNU @code{gettext} utilities}, for further details.
|
| 1700 | |
|
| 1701 | |
@noindent
|
| 1702 | |
@command{autoreconf} accepts the following options:
|
| 1703 | |
|
| 1704 | |
@table @option
|
| 1705 | |
@item --help
|
| 1706 | |
@itemx -h
|
| 1707 | |
Print a summary of the command line options and exit.
|
| 1708 | |
|
| 1709 | |
@item --version
|
| 1710 | |
@itemx -V
|
| 1711 | |
Print the version number of Autoconf and exit.
|
| 1712 | |
|
| 1713 | |
@item --verbose
|
| 1714 | |
@itemx -v
|
| 1715 | |
Print the name of each directory @command{autoreconf} examines and the
|
| 1716 | |
commands it runs. If given two or more times, pass @option{--verbose}
|
| 1717 | |
to subordinate tools that support it.
|
| 1718 | |
|
| 1719 | |
@item --debug
|
| 1720 | |
@itemx -d
|
| 1721 | |
Don't remove the temporary files.
|
| 1722 | |
|
| 1723 | |
@item --force
|
| 1724 | |
@itemx -f
|
| 1725 | |
Remake even @file{configure} scripts and configuration headers that are
|
| 1726 | |
newer than their input files (@file{configure.ac} and, if present,
|
| 1727 | |
@file{aclocal.m4}).
|
| 1728 | |
|
| 1729 | |
@item --install
|
| 1730 | |
@itemx -i
|
| 1731 | |
Install the missing auxiliary files in the package. By default, files
|
| 1732 | |
are copied; this can be changed with @option{--symlink}.
|
| 1733 | |
|
| 1734 | |
If deemed appropriate, this option triggers calls to
|
| 1735 | |
@samp{automake --add-missing},
|
| 1736 | |
@samp{libtoolize}, @samp{autopoint}, etc.
|
| 1737 | |
|
| 1738 | |
@item --no-recursive
|
| 1739 | |
Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
|
| 1740 | |
macro @code{AC_CONFIG_SUBDIRS}).
|
| 1741 | |
|
| 1742 | |
@item --symlink
|
| 1743 | |
@itemx -s
|
| 1744 | |
When used with @option{--install}, install symbolic links to the missing
|
| 1745 | |
auxiliary files instead of copying them.
|
| 1746 | |
|
| 1747 | |
@item --make
|
| 1748 | |
@itemx -m
|
| 1749 | |
When the directories were configured, update the configuration by
|
| 1750 | |
running @samp{./config.status --recheck && ./config.status}, and then
|
| 1751 | |
run @samp{make}.
|
| 1752 | |
|
| 1753 | |
@item --include=@var{dir}
|
| 1754 | |
@itemx -I @var{dir}
|
| 1755 | |
Append @var{dir} to the include path. Multiple invocations accumulate.
|
| 1756 | |
Passed on to @command{aclocal}, @command{autoconf} and
|
| 1757 | |
@command{autoheader} internally.
|
| 1758 | |
|
| 1759 | |
@item --prepend-include=@var{dir}
|
| 1760 | |
@itemx -B @var{dir}
|
| 1761 | |
Prepend @var{dir} to the include path. Multiple invocations accumulate.
|
| 1762 | |
Passed on to @command{autoconf} and @command{autoheader} internally.
|
| 1763 | |
|
| 1764 | |
@item --warnings=@var{category}
|
| 1765 | |
@itemx -W @var{category}
|
| 1766 | |
@evindex WARNINGS
|
| 1767 | |
Report the warnings related to @var{category} (which can actually be a
|
| 1768 | |
comma separated list).
|
| 1769 | |
|
| 1770 | |
@table @samp
|
| 1771 | |
@item cross
|
| 1772 | |
related to cross compilation issues.
|
| 1773 | |
|
| 1774 | |
@item obsolete
|
| 1775 | |
report the uses of obsolete constructs.
|
| 1776 | |
|
| 1777 | |
@item portability
|
| 1778 | |
portability issues
|
| 1779 | |
|
| 1780 | |
@item syntax
|
| 1781 | |
dubious syntactic constructs.
|
| 1782 | |
|
| 1783 | |
@item all
|
| 1784 | |
report all the warnings
|
| 1785 | |
|
| 1786 | |
@item none
|
| 1787 | |
report none
|
| 1788 | |
|
| 1789 | |
@item error
|
| 1790 | |
treats warnings as errors
|
| 1791 | |
|
| 1792 | |
@item no-@var{category}
|
| 1793 | |
disable warnings falling into @var{category}
|
| 1794 | |
@end table
|
| 1795 | |
|
| 1796 | |
Warnings about @samp{syntax} are enabled by default, and the environment
|
| 1797 | |
variable @env{WARNINGS}, a comma separated list of categories, is
|
| 1798 | |
honored as well. Passing @option{-W @var{category}} actually behaves as if
|
| 1799 | |
you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. To
|
| 1800 | |
disable the defaults and @env{WARNINGS}, and then
|
| 1801 | |
enable warnings about obsolete constructs, use @option{-W
|
| 1802 | |
none,obsolete}.
|
| 1803 | |
@end table
|
| 1804 | |
|
| 1805 | |
If you want @command{autoreconf} to pass flags that are not listed here
|
| 1806 | |
on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
|
| 1807 | |
Due to a limitation in the Autoconf implementation these flags currently
|
| 1808 | |
must be set on a single line in @file{Makefile.am}, without any
|
| 1809 | |
backslash-newlines.
|
| 1810 | |
|
| 1811 | |
@c ========================================= Initialization and Output Files.
|
| 1812 | |
|
| 1813 | |
@node Setup
|
| 1814 | |
@chapter Initialization and Output Files
|
| 1815 | |
|
| 1816 | |
Autoconf-generated @command{configure} scripts need some information about
|
| 1817 | |
how to initialize, such as how to find the package's source files and
|
| 1818 | |
about the output files to produce. The following sections describe the
|
| 1819 | |
initialization and the creation of output files.
|
| 1820 | |
|
| 1821 | |
@menu
|
| 1822 | |
* Initializing configure:: Option processing etc.
|
| 1823 | |
* Versioning:: Dealing with Autoconf versions
|
| 1824 | |
* Notices:: Copyright, version numbers in @command{configure}
|
| 1825 | |
* Input:: Where Autoconf should find files
|
| 1826 | |
* Output:: Outputting results from the configuration
|
| 1827 | |
* Configuration Actions:: Preparing the output based on results
|
| 1828 | |
* Configuration Files:: Creating output files
|
| 1829 | |
* Makefile Substitutions:: Using output variables in makefiles
|
| 1830 | |
* Configuration Headers:: Creating a configuration header file
|
| 1831 | |
* Configuration Commands:: Running arbitrary instantiation commands
|
| 1832 | |
* Configuration Links:: Links depending on the configuration
|
| 1833 | |
* Subdirectories:: Configuring independent packages together
|
| 1834 | |
* Default Prefix:: Changing the default installation prefix
|
| 1835 | |
@end menu
|
| 1836 | |
|
| 1837 | |
@node Initializing configure
|
| 1838 | |
@section Initializing @command{configure}
|
| 1839 | |
|
| 1840 | |
Every @command{configure} script must call @code{AC_INIT} before doing
|
| 1841 | |
anything else that produces output. Calls to silent macros, such as
|
| 1842 | |
@code{AC_DEFUN}, may also occur prior to @code{AC_INIT}, although these
|
| 1843 | |
are generally used via @file{aclocal.m4}, since that is implicitly
|
| 1844 | |
included before the start of @file{configure.ac}. The only other
|
| 1845 | |
required macro is @code{AC_OUTPUT} (@pxref{Output}).
|
| 1846 | |
|
| 1847 | |
@anchor{AC_INIT}
|
| 1848 | |
@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @
|
| 1849 | |
@ovar{tarname}, @ovar{url})
|
| 1850 | |
@acindex{INIT}
|
| 1851 | |
Process any command-line arguments and perform initialization
|
| 1852 | |
and verification.
|
| 1853 | |
|
| 1854 | |
Set the name of the @var{package} and its @var{version}. These are
|
| 1855 | |
typically used in @option{--version} support, including that of
|
| 1856 | |
@command{configure}. The optional argument @var{bug-report} should be
|
| 1857 | |
the email to which users should send bug reports. The package
|
| 1858 | |
@var{tarname} differs from @var{package}: the latter designates the full
|
| 1859 | |
package name (e.g., @samp{GNU Autoconf}), while the former is meant for
|
| 1860 | |
distribution tar ball names (e.g., @samp{autoconf}). It defaults to
|
| 1861 | |
@var{package} with @samp{GNU } stripped, lower-cased, and all characters
|
| 1862 | |
other than alphanumerics and underscores are changed to @samp{-}. If
|
| 1863 | |
provided, @var{url} should be the home page for the package.
|
| 1864 | |
|
| 1865 | |
The arguments of @code{AC_INIT} must be static, i.e., there should not
|
| 1866 | |
be any shell computation, quotes, or newlines, but they can be computed
|
| 1867 | |
by M4. This is because the package information strings are expanded at
|
| 1868 | |
M4 time into several contexts, and must give the same text at shell time
|
| 1869 | |
whether used in single-quoted strings, double-quoted strings, quoted
|
| 1870 | |
here-documents, or unquoted here-documents. It is permissible to use
|
| 1871 | |
@code{m4_esyscmd} or @code{m4_esyscmd_s} for computing a version string
|
| 1872 | |
that changes with every commit to a version control system (in fact,
|
| 1873 | |
Autoconf does just that, for all builds of the development tree made
|
| 1874 | |
between releases).
|
| 1875 | |
|
| 1876 | |
The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
|
| 1877 | |
(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
|
| 1878 | |
@code{PACKAGE_NAME}), are defined by @code{AC_INIT}:
|
| 1879 | |
|
| 1880 | |
@table @asis
|
| 1881 | |
@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
|
| 1882 | |
@acindex{PACKAGE_NAME}
|
| 1883 | |
@ovindex PACKAGE_NAME
|
| 1884 | |
@cvindex PACKAGE_NAME
|
| 1885 | |
Exactly @var{package}.
|
| 1886 | |
|
| 1887 | |
@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
|
| 1888 | |
@acindex{PACKAGE_TARNAME}
|
| 1889 | |
@ovindex PACKAGE_TARNAME
|
| 1890 | |
@cvindex PACKAGE_TARNAME
|
| 1891 | |
Exactly @var{tarname}, possibly generated from @var{package}.
|
| 1892 | |
|
| 1893 | |
@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
|
| 1894 | |
@acindex{PACKAGE_VERSION}
|
| 1895 | |
@ovindex PACKAGE_VERSION
|
| 1896 | |
@cvindex PACKAGE_VERSION
|
| 1897 | |
Exactly @var{version}.
|
| 1898 | |
|
| 1899 | |
@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
|
| 1900 | |
@acindex{PACKAGE_STRING}
|
| 1901 | |
@ovindex PACKAGE_STRING
|
| 1902 | |
@cvindex PACKAGE_STRING
|
| 1903 | |
Exactly @samp{@var{package} @var{version}}.
|
| 1904 | |
|
| 1905 | |
@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
|
| 1906 | |
@acindex{PACKAGE_BUGREPORT}
|
| 1907 | |
@ovindex PACKAGE_BUGREPORT
|
| 1908 | |
@cvindex PACKAGE_BUGREPORT
|
| 1909 | |
Exactly @var{bug-report}, if one was provided. Typically an email
|
| 1910 | |
address, or URL to a bug management web page.
|
| 1911 | |
|
| 1912 | |
@item @code{AC_PACKAGE_URL}, @code{PACKAGE_URL}
|
| 1913 | |
@acindex{PACKAGE_URL}
|
| 1914 | |
@ovindex PACKAGE_URL
|
| 1915 | |
@cvindex PACKAGE_URL
|
| 1916 | |
Exactly @var{url}, if one was provided. If @var{url} was empty, but
|
| 1917 | |
@var{package} begins with @samp{GNU }, then this defaults to
|
| 1918 | |
@samp{http://@/www.gnu.org/@/software/@/@var{tarname}/}, otherwise, no URL is
|
| 1919 | |
assumed.
|
| 1920 | |
@end table
|
| 1921 | |
@end defmac
|
| 1922 | |
|
| 1923 | |
If your @command{configure} script does its own option processing, it
|
| 1924 | |
should inspect @samp{$@@} or @samp{$*} immediately after calling
|
| 1925 | |
@code{AC_INIT}, because other Autoconf macros liberally use the
|
| 1926 | |
@command{set} command to process strings, and this has the side effect
|
| 1927 | |
of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
|
| 1928 | |
standard macros like @code{AC_ARG_ENABLE} instead of attempting to
|
| 1929 | |
implement your own option processing. @xref{Site Configuration}.
|
| 1930 | |
|
| 1931 | |
@node Versioning
|
| 1932 | |
@section Dealing with Autoconf versions
|
| 1933 | |
@cindex Autoconf version
|
| 1934 | |
@cindex version, Autoconf
|
| 1935 | |
|
| 1936 | |
The following optional macros can be used to help choose the minimum
|
| 1937 | |
version of Autoconf that can successfully compile a given
|
| 1938 | |
@file{configure.ac}.
|
| 1939 | |
|
| 1940 | |
@defmac AC_PREREQ (@var{version})
|
| 1941 | |
@acindex{PREREQ}
|
| 1942 | |
@cindex Version
|
| 1943 | |
Ensure that a recent enough version of Autoconf is being used. If the
|
| 1944 | |
version of Autoconf being used to create @command{configure} is
|
| 1945 | |
earlier than @var{version}, print an error message to the standard
|
| 1946 | |
error output and exit with failure (exit status is 63). For example:
|
| 1947 | |
|
| 1948 | |
@example
|
| 1949 | |
AC_PREREQ([@value{VERSION}])
|
| 1950 | |
@end example
|
| 1951 | |
|
| 1952 | |
This macro may be used before @code{AC_INIT}.
|
| 1953 | |
@end defmac
|
| 1954 | |
|
| 1955 | |
@defmac AC_AUTOCONF_VERSION
|
| 1956 | |
@acindex{AUTOCONF_VERSION}
|
| 1957 | |
This macro was introduced in Autoconf 2.62. It identifies the version
|
| 1958 | |
of Autoconf that is currently parsing the input file, in a format
|
| 1959 | |
suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in
|
| 1960 | |
other words, for this release of Autoconf, its value is
|
| 1961 | |
@samp{@value{VERSION}}. One potential use of this macro is for writing
|
| 1962 | |
conditional fallbacks based on when a feature was added to Autoconf,
|
| 1963 | |
rather than using @code{AC_PREREQ} to require the newer version of
|
| 1964 | |
Autoconf. However, remember that the Autoconf philosophy favors feature
|
| 1965 | |
checks over version checks.
|
| 1966 | |
|
| 1967 | |
You should not expand this macro directly; use
|
| 1968 | |
@samp{m4_defn([AC_AUTOCONF_VERSION])} instead. This is because some
|
| 1969 | |
users might
|
| 1970 | |
have a beta version of Autoconf installed, with arbitrary letters
|
| 1971 | |
included in its version string. This means it is possible for the
|
| 1972 | |
version string to contain the name of a defined macro, such that
|
| 1973 | |
expanding @code{AC_AUTOCONF_VERSION} would trigger the expansion of that
|
| 1974 | |
macro during rescanning, and change the version string to be different
|
| 1975 | |
than what you intended to check.
|
| 1976 | |
@end defmac
|
| 1977 | |
|
| 1978 | |
@node Notices
|
| 1979 | |
@section Notices in @command{configure}
|
| 1980 | |
@cindex Notices in @command{configure}
|
| 1981 | |
|
| 1982 | |
The following macros manage version numbers for @command{configure}
|
| 1983 | |
scripts. Using them is optional.
|
| 1984 | |
|
| 1985 | |
@defmac AC_COPYRIGHT (@var{copyright-notice})
|
| 1986 | |
@acindex{COPYRIGHT}
|
| 1987 | |
@cindex Copyright Notice
|
| 1988 | |
State that, in addition to the Free Software Foundation's copyright on
|
| 1989 | |
the Autoconf macros, parts of your @command{configure} are covered by the
|
| 1990 | |
@var{copyright-notice}.
|
| 1991 | |
|
| 1992 | |
The @var{copyright-notice} shows up in both the head of
|
| 1993 | |
@command{configure} and in @samp{configure --version}.
|
| 1994 | |
@end defmac
|
| 1995 | |
|
| 1996 | |
|
| 1997 | |
@defmac AC_REVISION (@var{revision-info})
|
| 1998 | |
@acindex{REVISION}
|
| 1999 | |
@cindex Revision
|
| 2000 | |
Copy revision stamp @var{revision-info} into the @command{configure}
|
| 2001 | |
script, with any dollar signs or double-quotes removed. This macro lets
|
| 2002 | |
you put a revision stamp from @file{configure.ac} into @command{configure}
|
| 2003 | |
without RCS or CVS changing it when you check in
|
| 2004 | |
@command{configure}. That way, you can determine easily which revision of
|
| 2005 | |
@file{configure.ac} a particular @command{configure} corresponds to.
|
| 2006 | |
|
| 2007 | |
For example, this line in @file{configure.ac}:
|
| 2008 | |
|
| 2009 | |
@c The @w prevents RCS from changing the example in the manual.
|
| 2010 | |
@example
|
| 2011 | |
AC_REVISION([@w{$}Revision: 1.30 $])
|
| 2012 | |
@end example
|
| 2013 | |
|
| 2014 | |
@noindent
|
| 2015 | |
produces this in @command{configure}:
|
| 2016 | |
|
| 2017 | |
@example
|
| 2018 | |
#!/bin/sh
|
| 2019 | |
# From configure.ac Revision: 1.30
|
| 2020 | |
@end example
|
| 2021 | |
@end defmac
|
| 2022 | |
|
| 2023 | |
|
| 2024 | |
@node Input
|
| 2025 | |
@section Finding @command{configure} Input
|
| 2026 | |
|
| 2027 | |
@anchor{AC_CONFIG_SRCDIR}
|
| 2028 | |
@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
|
| 2029 | |
@acindex{CONFIG_SRCDIR}
|
| 2030 | |
@var{unique-file-in-source-dir} is some file that is in the package's
|
| 2031 | |
source directory; @command{configure} checks for this file's existence to
|
| 2032 | |
make sure that the directory that it is told contains the source code in
|
| 2033 | |
fact does. Occasionally people accidentally specify the wrong directory
|
| 2034 | |
with @option{--srcdir}; this is a safety check. @xref{configure
|
| 2035 | |
Invocation}, for more information.
|
| 2036 | |
@end defmac
|
| 2037 | |
|
| 2038 | |
|
| 2039 | |
@c FIXME: Remove definitively once --install explained.
|
| 2040 | |
@c
|
| 2041 | |
@c Small packages may store all their macros in @code{aclocal.m4}. As the
|
| 2042 | |
@c set of macros grows, or for maintenance reasons, a maintainer may prefer
|
| 2043 | |
@c to split the macros in several files. In this case, Autoconf must be
|
| 2044 | |
@c told which files to load, and in which order.
|
| 2045 | |
@c
|
| 2046 | |
@c @defmac AC_INCLUDE (@var{file}@dots{})
|
| 2047 | |
@c @acindex{INCLUDE}
|
| 2048 | |
@c @c FIXME: There is no longer shell globbing.
|
| 2049 | |
@c Read the macro definitions that appear in the listed files. A list of
|
| 2050 | |
@c space-separated file names or shell globbing patterns is expected. The
|
| 2051 | |
@c files are read in the order they're listed.
|
| 2052 | |
@c
|
| 2053 | |
@c Because the order of definition of macros is important (only the last
|
| 2054 | |
@c definition of a macro is used), beware that it is @code{AC_INIT} that
|
| 2055 | |
@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
|
| 2056 | |
@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
|
| 2057 | |
@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
|
| 2058 | |
@c the latter case, non-macro lines from included files may end up in the
|
| 2059 | |
@c @file{configure} script, whereas in the former case, they'd be discarded
|
| 2060 | |
@c just like any text that appear before @code{AC_INIT}.
|
| 2061 | |
@c @end defmac
|
| 2062 | |
|
| 2063 | |
Packages that do manual configuration or use the @command{install} program
|
| 2064 | |
might need to tell @command{configure} where to find some other shell
|
| 2065 | |
scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
|
| 2066 | |
it looks are correct for most cases.
|
| 2067 | |
|
| 2068 | |
@defmac AC_CONFIG_AUX_DIR (@var{dir})
|
| 2069 | |
@acindex{CONFIG_AUX_DIR}
|
| 2070 | |
Use the auxiliary build tools (e.g., @file{install-sh},
|
| 2071 | |
@file{config.sub}, @file{config.guess}, Cygnus @command{configure},
|
| 2072 | |
Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
|
| 2073 | |
These are auxiliary files used in configuration. @var{dir} can be
|
| 2074 | |
either absolute or relative to @file{@var{srcdir}}. The default is
|
| 2075 | |
@file{@var{srcdir}} or @file{@var{srcdir}/..} or
|
| 2076 | |
@file{@var{srcdir}/../..}, whichever is the first that contains
|
| 2077 | |
@file{install-sh}. The other files are not checked for, so that using
|
| 2078 | |
@code{AC_PROG_INSTALL} does not automatically require distributing the
|
| 2079 | |
other auxiliary files. It checks for @file{install.sh} also, but that
|
| 2080 | |
name is obsolete because some @command{make} have a rule that creates
|
| 2081 | |
@file{install} from it if there is no makefile.
|
| 2082 | |
|
| 2083 | |
The auxiliary directory is commonly named @file{build-aux}.
|
| 2084 | |
If you need portability to DOS variants, do not name the
|
| 2085 | |
auxiliary directory @file{aux}. @xref{File System Conventions}.
|
| 2086 | |
@end defmac
|
| 2087 | |
|
| 2088 | |
@defmac AC_REQUIRE_AUX_FILE (@var{file})
|
| 2089 | |
@acindex{REQUIRE_AUX_FILE}
|
| 2090 | |
Declares that @var{file} is expected in the directory defined above. In
|
| 2091 | |
Autoconf proper, this macro does nothing: its sole purpose is to be
|
| 2092 | |
traced by third-party tools to produce a list of expected auxiliary
|
| 2093 | |
files. For instance it is called by macros like @code{AC_PROG_INSTALL}
|
| 2094 | |
(@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
|
| 2095 | |
(@pxref{Canonicalizing}) to register the auxiliary files they need.
|
| 2096 | |
@end defmac
|
| 2097 | |
|
| 2098 | |
Similarly, packages that use @command{aclocal} should declare where
|
| 2099 | |
local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
|
| 2100 | |
|
| 2101 | |
@defmac AC_CONFIG_MACRO_DIR (@var{dir})
|
| 2102 | |
@acindex{CONFIG_MACRO_DIR}
|
| 2103 | |
Specify @var{dir} as the location of additional local Autoconf macros.
|
| 2104 | |
This macro is intended for use by future versions of commands like
|
| 2105 | |
@command{autoreconf} that trace macro calls. It should be called
|
| 2106 | |
directly from @file{configure.ac} so that tools that install macros for
|
| 2107 | |
@command{aclocal} can find the macros' declarations.
|
| 2108 | |
|
| 2109 | |
Note that if you use @command{aclocal} from Automake to generate
|
| 2110 | |
@file{aclocal.m4}, you must also set @code{ACLOCAL_AMFLAGS = -I
|
| 2111 | |
@var{dir}} in your top-level @file{Makefile.am}. Due to a limitation in
|
| 2112 | |
the Autoconf implementation of @command{autoreconf}, these include
|
| 2113 | |
directives currently must be set on a single line in @file{Makefile.am},
|
| 2114 | |
without any backslash-newlines.
|
| 2115 | |
@end defmac
|
| 2116 | |
|
| 2117 | |
|
| 2118 | |
@node Output
|
| 2119 | |
@section Outputting Files
|
| 2120 | |
@cindex Outputting files
|
| 2121 | |
|
| 2122 | |
Every Autoconf script, e.g., @file{configure.ac}, should finish by
|
| 2123 | |
calling @code{AC_OUTPUT}. That is the macro that generates and runs
|
| 2124 | |
@file{config.status}, which in turn creates the makefiles and any
|
| 2125 | |
other files resulting from configuration. This is the only required
|
| 2126 | |
macro besides @code{AC_INIT} (@pxref{Input}).
|
| 2127 | |
|
| 2128 | |
@anchor{AC_OUTPUT}
|
| 2129 | |
@defmac AC_OUTPUT
|
| 2130 | |
@acindex{OUTPUT}
|
| 2131 | |
@cindex Instantiation
|
| 2132 | |
Generate @file{config.status} and launch it. Call this macro once, at
|
| 2133 | |
the end of @file{configure.ac}.
|
| 2134 | |
|
| 2135 | |
@file{config.status} performs all the configuration actions: all the
|
| 2136 | |
output files (see @ref{Configuration Files}, macro
|
| 2137 | |
@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
|
| 2138 | |
macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
|
| 2139 | |
Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
|
| 2140 | |
@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
|
| 2141 | |
to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
|
| 2142 | |
are honored.
|
| 2143 | |
|
| 2144 | |
The location of your @code{AC_OUTPUT} invocation is the exact point
|
| 2145 | |
where configuration actions are taken: any code afterwards is
|
| 2146 | |
executed by @command{configure} once @command{config.status} was run. If
|
| 2147 | |
you want to bind actions to @command{config.status} itself
|
| 2148 | |
(independently of whether @command{configure} is being run), see
|
| 2149 | |
@ref{Configuration Commands, , Running Arbitrary Configuration
|
| 2150 | |
Commands}.
|
| 2151 | |
@end defmac
|
| 2152 | |
|
| 2153 | |
Historically, the usage of @code{AC_OUTPUT} was somewhat different.
|
| 2154 | |
@xref{Obsolete Macros}, for a description of the arguments that
|
| 2155 | |
@code{AC_OUTPUT} used to support.
|
| 2156 | |
|
| 2157 | |
|
| 2158 | |
If you run @command{make} in subdirectories, you should run it using the
|
| 2159 | |
@command{make} variable @code{MAKE}. Most versions of @command{make} set
|
| 2160 | |
@code{MAKE} to the name of the @command{make} program plus any options it
|
| 2161 | |
was given. (But many do not include in it the values of any variables
|
| 2162 | |
set on the command line, so those are not passed on automatically.)
|
| 2163 | |
Some old versions of @command{make} do not set this variable. The
|
| 2164 | |
following macro allows you to use it even with those versions.
|
| 2165 | |
|
| 2166 | |
@anchor{AC_PROG_MAKE_SET}
|
| 2167 | |
@defmac AC_PROG_MAKE_SET
|
| 2168 | |
@acindex{PROG_MAKE_SET}
|
| 2169 | |
@ovindex SET_MAKE
|
| 2170 | |
If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
|
| 2171 | |
@code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
|
| 2172 | |
Otherwise, define @code{SET_MAKE} to a macro definition that sets
|
| 2173 | |
@code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
|
| 2174 | |
@code{SET_MAKE}.
|
| 2175 | |
@end defmac
|
| 2176 | |
|
| 2177 | |
If you use this macro, place a line like this in each @file{Makefile.in}
|
| 2178 | |
that runs @command{MAKE} on other directories:
|
| 2179 | |
|
| 2180 | |
@example
|
| 2181 | |
@@SET_MAKE@@
|
| 2182 | |
@end example
|
| 2183 | |
|
| 2184 | |
|
| 2185 | |
|
| 2186 | |
@node Configuration Actions
|
| 2187 | |
@section Performing Configuration Actions
|
| 2188 | |
@cindex Configuration actions
|
| 2189 | |
|
| 2190 | |
@file{configure} is designed so that it appears to do everything itself,
|
| 2191 | |
but there is actually a hidden slave: @file{config.status}.
|
| 2192 | |
@file{configure} is in charge of examining your system, but it is
|
| 2193 | |
@file{config.status} that actually takes the proper actions based on the
|
| 2194 | |
results of @file{configure}. The most typical task of
|
| 2195 | |
@file{config.status} is to @emph{instantiate} files.
|
| 2196 | |
|
| 2197 | |
@acindex{CONFIG_@var{ITEMS}}
|
| 2198 | |
This section describes the common behavior of the four standard
|
| 2199 | |
instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
|
| 2200 | |
@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
|
| 2201 | |
have this prototype:
|
| 2202 | |
|
| 2203 | |
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
|
| 2204 | |
@c awful.
|
| 2205 | |
@example
|
| 2206 | |
AC_CONFIG_@var{ITEMS}(@var{tag}@dots{}, @r{[}@var{commands}@r{]}, @r{[}@var{init-cmds}@r{]})
|
| 2207 | |
@end example
|
| 2208 | |
|
| 2209 | |
@noindent
|
| 2210 | |
where the arguments are:
|
| 2211 | |
|
| 2212 | |
@table @var
|
| 2213 | |
@item tag@dots{}
|
| 2214 | |
A blank-or-newline-separated list of tags, which are typically the names of
|
| 2215 | |
the files to instantiate.
|
| 2216 | |
|
| 2217 | |
You are encouraged to use literals as @var{tags}. In particular, you
|
| 2218 | |
should avoid
|
| 2219 | |
|
| 2220 | |
@example
|
| 2221 | |
@dots{} && my_foos="$my_foos fooo"
|
| 2222 | |
@dots{} && my_foos="$my_foos foooo"
|
| 2223 | |
AC_CONFIG_@var{ITEMS}([$my_foos])
|
| 2224 | |
@end example
|
| 2225 | |
|
| 2226 | |
@noindent
|
| 2227 | |
and use this instead:
|
| 2228 | |
|
| 2229 | |
@example
|
| 2230 | |
@dots{} && AC_CONFIG_@var{ITEMS}([fooo])
|
| 2231 | |
@dots{} && AC_CONFIG_@var{ITEMS}([foooo])
|
| 2232 | |
@end example
|
| 2233 | |
|
| 2234 | |
The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
|
| 2235 | |
special @var{tag} values: they may have the form @samp{@var{output}} or
|
| 2236 | |
@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
|
| 2237 | |
from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
|
| 2238 | |
|
| 2239 | |
@samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])},
|
| 2240 | |
for example, asks for
|
| 2241 | |
the creation of the file @file{Makefile} that contains the expansion of the
|
| 2242 | |
output variables in the concatenation of @file{boiler/top.mk} and
|
| 2243 | |
@file{boiler/bot.mk}.
|
| 2244 | |
|
| 2245 | |
The special value @samp{-} might be used to denote the standard output
|
| 2246 | |
when used in @var{output}, or the standard input when used in the
|
| 2247 | |
@var{inputs}. You most probably don't need to use this in
|
| 2248 | |
@file{configure.ac}, but it is convenient when using the command line
|
| 2249 | |
interface of @file{./config.status}, see @ref{config.status Invocation},
|
| 2250 | |
for more details.
|
| 2251 | |
|
| 2252 | |
The @var{inputs} may be absolute or relative file names. In the latter
|
| 2253 | |
case they are first looked for in the build tree, and then in the source
|
| 2254 | |
tree. Input files should be text files, and a line length below 2000
|
| 2255 | |
bytes should be safe.
|
| 2256 | |
|
| 2257 | |
@item commands
|
| 2258 | |
Shell commands output literally into @file{config.status}, and
|
| 2259 | |
associated with a tag that the user can use to tell @file{config.status}
|
| 2260 | |
which commands to run. The commands are run each time a @var{tag}
|
| 2261 | |
request is given to @file{config.status}, typically each time the file
|
| 2262 | |
@file{@var{tag}} is created.
|
| 2263 | |
|
| 2264 | |
The variables set during the execution of @command{configure} are
|
| 2265 | |
@emph{not} available here: you first need to set them via the
|
| 2266 | |
@var{init-cmds}. Nonetheless the following variables are precomputed:
|
| 2267 | |
|
| 2268 | |
@table @code
|
| 2269 | |
@item srcdir
|
| 2270 | |
@vrindex srcdir
|
| 2271 | |
The name of the top source directory, assuming that the working
|
| 2272 | |
directory is the top build directory. This
|
| 2273 | |
is what the @command{configure} option @option{--srcdir} sets.
|
| 2274 | |
|
| 2275 | |
@item ac_top_srcdir
|
| 2276 | |
@vrindex ac_top_srcdir
|
| 2277 | |
The name of the top source directory, assuming that the working
|
| 2278 | |
directory is the current build directory.
|
| 2279 | |
|
| 2280 | |
@item ac_top_build_prefix
|
| 2281 | |
@vrindex ac_top_build_prefix
|
| 2282 | |
The name of the top build directory, assuming that the working
|
| 2283 | |
directory is the current build directory.
|
| 2284 | |
It can be empty, or else ends with a slash, so that you may concatenate
|
| 2285 | |
it.
|
| 2286 | |
|
| 2287 | |
@item ac_srcdir
|
| 2288 | |
@vrindex ac_srcdir
|
| 2289 | |
The name of the corresponding source directory, assuming that the
|
| 2290 | |
working directory is the current build directory.
|
| 2291 | |
|
| 2292 | |
@item tmp
|
| 2293 | |
@vrindex tmp
|
| 2294 | |
The name of a temporary directory within the build tree, which you
|
| 2295 | |
can use if you need to create additional temporary files. The
|
| 2296 | |
directory is cleaned up when @command{config.status} is done or
|
| 2297 | |
interrupted. Please use package-specific file name prefixes to
|
| 2298 | |
avoid clashing with files that @command{config.status} may use
|
| 2299 | |
internally.
|
| 2300 | |
@end table
|
| 2301 | |
|
| 2302 | |
@noindent
|
| 2303 | |
The @dfn{current} directory refers to the directory (or
|
| 2304 | |
pseudo-directory) containing the input part of @var{tags}. For
|
| 2305 | |
instance, running
|
| 2306 | |
|
| 2307 | |
@example
|
| 2308 | |
AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
|
| 2309 | |
@end example
|
| 2310 | |
|
| 2311 | |
@noindent
|
| 2312 | |
with @option{--srcdir=../package} produces the following values:
|
| 2313 | |
|
| 2314 | |
@example
|
| 2315 | |
# Argument of --srcdir
|
| 2316 | |
srcdir='../package'
|
| 2317 | |
# Reversing deep/dir
|
| 2318 | |
ac_top_build_prefix='../../'
|
| 2319 | |
# Concatenation of $ac_top_build_prefix and srcdir
|
| 2320 | |
ac_top_srcdir='../../../package'
|
| 2321 | |
# Concatenation of $ac_top_srcdir and deep/dir
|
| 2322 | |
ac_srcdir='../../../package/deep/dir'
|
| 2323 | |
@end example
|
| 2324 | |
|
| 2325 | |
@noindent
|
| 2326 | |
independently of @samp{in/in.in}.
|
| 2327 | |
|
| 2328 | |
@item init-cmds
|
| 2329 | |
Shell commands output @emph{unquoted} near the beginning of
|
| 2330 | |
@file{config.status}, and executed each time @file{config.status} runs
|
| 2331 | |
(regardless of the tag). Because they are unquoted, for example,
|
| 2332 | |
@samp{$var} is output as the value of @code{var}. @var{init-cmds}
|
| 2333 | |
is typically used by @file{configure} to give @file{config.status} some
|
| 2334 | |
variables it needs to run the @var{commands}.
|
| 2335 | |
|
| 2336 | |
You should be extremely cautious in your variable names: all the
|
| 2337 | |
@var{init-cmds} share the same name space and may overwrite each other
|
| 2338 | |
in unpredictable ways. Sorry@enddots{}
|
| 2339 | |
@end table
|
| 2340 | |
|
| 2341 | |
All these macros can be called multiple times, with different
|
| 2342 | |
@var{tag} values, of course!
|
| 2343 | |
|
| 2344 | |
|
| 2345 | |
@node Configuration Files
|
| 2346 | |
@section Creating Configuration Files
|
| 2347 | |
@cindex Creating configuration files
|
| 2348 | |
@cindex Configuration file creation
|
| 2349 | |
|
| 2350 | |
Be sure to read the previous section, @ref{Configuration Actions}.
|
| 2351 | |
|
| 2352 | |
@anchor{AC_CONFIG_FILES}
|
| 2353 | |
@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
|
| 2354 | |
@acindex{CONFIG_FILES}
|
| 2355 | |
Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
|
| 2356 | |
file (by default @file{@var{file}.in}), substituting the output variable
|
| 2357 | |
values.
|
| 2358 | |
@c Before we used to have this feature, which was later rejected
|
| 2359 | |
@c because it complicates the writing of makefiles:
|
| 2360 | |
@c If the file would be unchanged, it is left untouched, to preserve
|
| 2361 | |
@c timestamp.
|
| 2362 | |
This macro is one of the instantiating macros; see @ref{Configuration
|
| 2363 | |
Actions}. @xref{Makefile Substitutions}, for more information on using
|
| 2364 | |
output variables. @xref{Setting Output Variables}, for more information
|
| 2365 | |
on creating them. This macro creates the directory that the file is in
|
| 2366 | |
if it doesn't exist. Usually, makefiles are created this way,
|
| 2367 | |
but other files, such as @file{.gdbinit}, can be specified as well.
|
| 2368 | |
|
| 2369 | |
Typical calls to @code{AC_CONFIG_FILES} look like this:
|
| 2370 | |
|
| 2371 | |
@example
|
| 2372 | |
AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
|
| 2373 | |
AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
|
| 2374 | |
@end example
|
| 2375 | |
|
| 2376 | |
You can override an input file name by appending to @var{file} a
|
| 2377 | |
colon-separated list of input files. Examples:
|
| 2378 | |
|
| 2379 | |
@example
|
| 2380 | |
AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
|
| 2381 | |
[lib/Makefile:boiler/lib.mk])
|
| 2382 | |
@end example
|
| 2383 | |
|
| 2384 | |
@noindent
|
| 2385 | |
Doing this allows you to keep your file names acceptable to
|
| 2386 | |
DOS variants, or
|
| 2387 | |
to prepend and/or append boilerplate to the file.
|
| 2388 | |
@end defmac
|
| 2389 | |
|
| 2390 | |
|
| 2391 | |
|
| 2392 | |
@node Makefile Substitutions
|
| 2393 | |
@section Substitutions in Makefiles
|
| 2394 | |
@cindex Substitutions in makefiles
|
| 2395 | |
@cindex Makefile substitutions
|
| 2396 | |
|
| 2397 | |
Each subdirectory in a distribution that contains something to be
|
| 2398 | |
compiled or installed should come with a file @file{Makefile.in}, from
|
| 2399 | |
which @command{configure} creates a file @file{Makefile} in that directory.
|
| 2400 | |
To create @file{Makefile}, @command{configure} performs a simple variable
|
| 2401 | |
substitution, replacing occurrences of @samp{@@@var{variable}@@} in
|
| 2402 | |
@file{Makefile.in} with the value that @command{configure} has determined
|
| 2403 | |
for that variable. Variables that are substituted into output files in
|
| 2404 | |
this way are called @dfn{output variables}. They are ordinary shell
|
| 2405 | |
variables that are set in @command{configure}. To make @command{configure}
|
| 2406 | |
substitute a particular variable into the output files, the macro
|
| 2407 | |
@code{AC_SUBST} must be called with that variable name as an argument.
|
| 2408 | |
Any occurrences of @samp{@@@var{variable}@@} for other variables are
|
| 2409 | |
left unchanged. @xref{Setting Output Variables}, for more information
|
| 2410 | |
on creating output variables with @code{AC_SUBST}.
|
| 2411 | |
|
| 2412 | |
A software package that uses a @command{configure} script should be
|
| 2413 | |
distributed with a file @file{Makefile.in}, but no makefile; that
|
| 2414 | |
way, the user has to properly configure the package for the local system
|
| 2415 | |
before compiling it.
|
| 2416 | |
|
| 2417 | |
@xref{Makefile Conventions, , Makefile Conventions, standards, The
|
| 2418 | |
GNU Coding Standards}, for more information on what to put in
|
| 2419 | |
makefiles.
|
| 2420 | |
|
| 2421 | |
@menu
|
| 2422 | |
* Preset Output Variables:: Output variables that are always set
|
| 2423 | |
* Installation Directory Variables:: Other preset output variables
|
| 2424 | |
* Changed Directory Variables:: Warnings about @file{datarootdir}
|
| 2425 | |
* Build Directories:: Supporting multiple concurrent compiles
|
| 2426 | |
* Automatic Remaking:: Makefile rules for configuring
|
| 2427 | |
@end menu
|
| 2428 | |
|
| 2429 | |
@node Preset Output Variables
|
| 2430 | |
@subsection Preset Output Variables
|
| 2431 | |
@cindex Output variables
|
| 2432 | |
|
| 2433 | |
Some output variables are preset by the Autoconf macros. Some of the
|
| 2434 | |
Autoconf macros set additional output variables, which are mentioned in
|
| 2435 | |
the descriptions for those macros. @xref{Output Variable Index}, for a
|
| 2436 | |
complete list of output variables. @xref{Installation Directory
|
| 2437 | |
Variables}, for the list of the preset ones related to installation
|
| 2438 | |
directories. Below are listed the other preset ones, many of which are
|
| 2439 | |
precious variables (@pxref{Setting Output Variables},
|
| 2440 | |
@code{AC_ARG_VAR}).
|
| 2441 | |
|
| 2442 | |
The preset variables which are available during @file{config.status}
|
| 2443 | |
(@pxref{Configuration Actions}) may also be used during
|
| 2444 | |
@command{configure} tests. For example, it is permissible to reference
|
| 2445 | |
@samp{$srcdir} when constructing a list of directories to pass via
|
| 2446 | |
option @option{-I} during a compiler feature check. When used in this
|
| 2447 | |
manner, coupled with the fact that @command{configure} is always run
|
| 2448 | |
from the top build directory, it is sufficient to use just
|
| 2449 | |
@samp{$srcdir} instead of @samp{$top_srcdir}.
|
| 2450 | |
|
| 2451 | |
@c Just say no to ASCII sorting! We're humans, not computers.
|
| 2452 | |
@c These variables are listed as they would be in a dictionary:
|
| 2453 | |
@c actor
|
| 2454 | |
@c Actress
|
| 2455 | |
@c actress
|
| 2456 | |
|
| 2457 | |
@defvar CFLAGS
|
| 2458 | |
@evindex CFLAGS
|
| 2459 | |
@ovindex CFLAGS
|
| 2460 | |
Debugging and optimization options for the C compiler. If it is not set
|
| 2461 | |
in the environment when @command{configure} runs, the default value is set
|
| 2462 | |
when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
|
| 2463 | |
uses this variable when compiling or linking programs to test for C features.
|
| 2464 | |
|
| 2465 | |
If a compiler option affects only the behavior of the preprocessor
|
| 2466 | |
(e.g., @option{-D@var{name}}), it should be put into @code{CPPFLAGS}
|
| 2467 | |
instead. If it affects only the linker (e.g., @option{-L@var{directory}}),
|
| 2468 | |
it should be put into @code{LDFLAGS} instead. If it
|
| 2469 | |
affects only the compiler proper, @code{CFLAGS} is the natural home for
|
| 2470 | |
it. If an option affects multiple phases of the compiler, though,
|
| 2471 | |
matters get tricky. One approach to put such options directly into
|
| 2472 | |
@code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
|
| 2473 | |
@code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
|
| 2474 | |
|
| 2475 | |
However, remember that some @file{Makefile} variables are reserved by
|
| 2476 | |
the GNU Coding Standards for the use of the ``user''---the person
|
| 2477 | |
building the package. For instance, @code{CFLAGS} is one such variable.
|
| 2478 | |
|
| 2479 | |
Sometimes package developers are tempted to set user variables such as
|
| 2480 | |
@code{CFLAGS} because it appears to make their job easier. However, the
|
| 2481 | |
package itself should never set a user variable, particularly not to
|
| 2482 | |
include switches that are required for proper compilation of the
|
| 2483 | |
package. Since these variables are documented as being for the package
|
| 2484 | |
builder, that person rightfully expects to be able to override any of
|
| 2485 | |
these variables at build time. If the package developer needs to add
|
| 2486 | |
switches without interfering with the user, the proper way to do that is
|
| 2487 | |
to introduce an additional variable. Automake makes this easy by
|
| 2488 | |
introducing @code{AM_CFLAGS} (@pxref{Flag Variables Ordering, , ,
|
| 2489 | |
automake, GNU Automake}), but the concept is the same even if
|
| 2490 | |
Automake is not used.
|
| 2491 | |
@end defvar
|
| 2492 | |
|
| 2493 | |
@defvar configure_input
|
| 2494 | |
@ovindex configure_input
|
| 2495 | |
A comment saying that the file was generated automatically by
|
| 2496 | |
@command{configure} and giving the name of the input file.
|
| 2497 | |
@code{AC_OUTPUT} adds a comment line containing this variable to the top
|
| 2498 | |
of every makefile it creates. For other files, you should
|
| 2499 | |
reference this variable in a comment at the top of each input file. For
|
| 2500 | |
example, an input shell script should begin like this:
|
| 2501 | |
|
| 2502 | |
@example
|
| 2503 | |
#!/bin/sh
|
| 2504 | |
# @@configure_input@@
|
| 2505 | |
@end example
|
| 2506 | |
|
| 2507 | |
@noindent
|
| 2508 | |
The presence of that line also reminds people editing the file that it
|
| 2509 | |
needs to be processed by @command{configure} in order to be used.
|
| 2510 | |
@end defvar
|
| 2511 | |
|
| 2512 | |
@defvar CPPFLAGS
|
| 2513 | |
@evindex CPPFLAGS
|
| 2514 | |
@ovindex CPPFLAGS
|
| 2515 | |
Preprocessor options for the C, C++, Objective C, and Objective C++
|
| 2516 | |
preprocessors and compilers. If
|
| 2517 | |
it is not set in the environment when @command{configure} runs, the default
|
| 2518 | |
value is empty. @command{configure} uses this variable when preprocessing
|
| 2519 | |
or compiling programs to test for C, C++, Objective C, and Objective C++
|
| 2520 | |
features.
|
| 2521 | |
|
| 2522 | |
This variable's contents should contain options like @option{-I},
|
| 2523 | |
@option{-D}, and @option{-U} that affect only the behavior of the
|
| 2524 | |
preprocessor. Please see the explanation of @code{CFLAGS} for what you
|
| 2525 | |
can do if an option affects other phases of the compiler as well.
|
| 2526 | |
|
| 2527 | |
Currently, @command{configure} always links as part of a single
|
| 2528 | |
invocation of the compiler that also preprocesses and compiles, so it
|
| 2529 | |
uses this variable also when linking programs. However, it is unwise to
|
| 2530 | |
depend on this behavior because the GNU Coding Standards do
|
| 2531 | |
not require it and many packages do not use @code{CPPFLAGS} when linking
|
| 2532 | |
programs.
|
| 2533 | |
|
| 2534 | |
@xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
|
| 2535 | |
might run into.
|
| 2536 | |
@end defvar
|
| 2537 | |
|
| 2538 | |
@defvar CXXFLAGS
|
| 2539 | |
@evindex CXXFLAGS
|
| 2540 | |
@ovindex CXXFLAGS
|
| 2541 | |
Debugging and optimization options for the C++ compiler. It acts like
|
| 2542 | |
@code{CFLAGS}, but for C++ instead of C.
|
| 2543 | |
@end defvar
|
| 2544 | |
|
| 2545 | |
@defvar DEFS
|
| 2546 | |
@ovindex DEFS
|
| 2547 | |
@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
|
| 2548 | |
is called, @command{configure} replaces @samp{@@DEFS@@} with
|
| 2549 | |
@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
|
| 2550 | |
variable is not defined while @command{configure} is performing its tests,
|
| 2551 | |
only when creating the output files. @xref{Setting Output Variables}, for
|
| 2552 | |
how to check the results of previous tests.
|
| 2553 | |
@end defvar
|
| 2554 | |
|
| 2555 | |
@defvar ECHO_C
|
| 2556 | |
@defvarx ECHO_N
|
| 2557 | |
@defvarx ECHO_T
|
| 2558 | |
@ovindex ECHO_C
|
| 2559 | |
@ovindex ECHO_N
|
| 2560 | |
@ovindex ECHO_T
|
| 2561 | |
How does one suppress the trailing newline from @command{echo} for
|
| 2562 | |
question-answer message pairs? These variables provide a way:
|
| 2563 | |
|
| 2564 | |
@example
|
| 2565 | |
echo $ECHO_N "And the winner is... $ECHO_C"
|
| 2566 | |
sleep 100000000000
|
| 2567 | |
echo "$@{ECHO_T@}dead."
|
| 2568 | |
@end example
|
| 2569 | |
|
| 2570 | |
@noindent
|
| 2571 | |
Some old and uncommon @command{echo} implementations offer no means to
|
| 2572 | |
achieve this, in which case @code{ECHO_T} is set to tab. You might not
|
| 2573 | |
want to use it.
|
| 2574 | |
@end defvar
|
| 2575 | |
|
| 2576 | |
@defvar ERLCFLAGS
|
| 2577 | |
@evindex ERLCFLAGS
|
| 2578 | |
@ovindex ERLCFLAGS
|
| 2579 | |
Debugging and optimization options for the Erlang compiler. If it is not set
|
| 2580 | |
in the environment when @command{configure} runs, the default value is empty.
|
| 2581 | |
@command{configure} uses this variable when compiling
|
| 2582 | |
programs to test for Erlang features.
|
| 2583 | |
@end defvar
|
| 2584 | |
|
| 2585 | |
@defvar FCFLAGS
|
| 2586 | |
@evindex FCFLAGS
|
| 2587 | |
@ovindex FCFLAGS
|
| 2588 | |
Debugging and optimization options for the Fortran compiler. If it
|
| 2589 | |
is not set in the environment when @command{configure} runs, the default
|
| 2590 | |
value is set when you call @code{AC_PROG_FC} (or empty if you don't).
|
| 2591 | |
@command{configure} uses this variable when compiling or linking
|
| 2592 | |
programs to test for Fortran features.
|
| 2593 | |
@end defvar
|
| 2594 | |
|
| 2595 | |
@defvar FFLAGS
|
| 2596 | |
@evindex FFLAGS
|
| 2597 | |
@ovindex FFLAGS
|
| 2598 | |
Debugging and optimization options for the Fortran 77 compiler. If it
|
| 2599 | |
is not set in the environment when @command{configure} runs, the default
|
| 2600 | |
value is set when you call @code{AC_PROG_F77} (or empty if you don't).
|
| 2601 | |
@command{configure} uses this variable when compiling or linking
|
| 2602 | |
programs to test for Fortran 77 features.
|
| 2603 | |
@end defvar
|
| 2604 | |
|
| 2605 | |
@defvar LDFLAGS
|
| 2606 | |
@evindex LDFLAGS
|
| 2607 | |
@ovindex LDFLAGS
|
| 2608 | |
Options for the linker. If it is not set
|
| 2609 | |
in the environment when @command{configure} runs, the default value is empty.
|
| 2610 | |
@command{configure} uses this variable when linking programs to test for
|
| 2611 | |
C, C++, Objective C, Objective C++, Fortran, and Go features.
|
| 2612 | |
|
| 2613 | |
This variable's contents should contain options like @option{-s} and
|
| 2614 | |
@option{-L} that affect only the behavior of the linker. Please see the
|
| 2615 | |
explanation of @code{CFLAGS} for what you can do if an option also
|
| 2616 | |
affects other phases of the compiler.
|
| 2617 | |
|
| 2618 | |
Don't use this variable to pass library names
|
| 2619 | |
(@option{-l}) to the linker; use @code{LIBS} instead.
|
| 2620 | |
@end defvar
|
| 2621 | |
|
| 2622 | |
@defvar LIBS
|
| 2623 | |
@evindex LIBS
|
| 2624 | |
@ovindex LIBS
|
| 2625 | |
@option{-l} options to pass to the linker. The default value is empty,
|
| 2626 | |
but some Autoconf macros may prepend extra libraries to this variable if
|
| 2627 | |
those libraries are found and provide necessary functions, see
|
| 2628 | |
@ref{Libraries}. @command{configure} uses this variable when linking
|
| 2629 | |
programs to test for C, C++, Objective C, Objective C++, Fortran, and Go
|
| 2630 | |
features.
|
| 2631 | |
@end defvar
|
| 2632 | |
|
| 2633 | |
@defvar OBJCFLAGS
|
| 2634 | |
@evindex OBJCFLAGS
|
| 2635 | |
@ovindex OBJCFLAGS
|
| 2636 | |
Debugging and optimization options for the Objective C compiler. It
|
| 2637 | |
acts like @code{CFLAGS}, but for Objective C instead of C.
|
| 2638 | |
@end defvar
|
| 2639 | |
|
| 2640 | |
@defvar OBJCXXFLAGS
|
| 2641 | |
@evindex OBJCXXFLAGS
|
| 2642 | |
@ovindex OBJCXXFLAGS
|
| 2643 | |
Debugging and optimization options for the Objective C++ compiler. It
|
| 2644 | |
acts like @code{CXXFLAGS}, but for Objective C++ instead of C++.
|
| 2645 | |
@end defvar
|
| 2646 | |
|
| 2647 | |
@defvar GOFLAGS
|
| 2648 | |
@evindex GOFLAGS
|
| 2649 | |
@ovindex GOFLAGS
|
| 2650 | |
Debugging and optimization options for the Go compiler. It acts like
|
| 2651 | |
@code{CFLAGS}, but for Go instead of C.
|
| 2652 | |
@end defvar
|
| 2653 | |
|
| 2654 | |
@defvar builddir
|
| 2655 | |
@ovindex builddir
|
| 2656 | |
Rigorously equal to @samp{.}. Added for symmetry only.
|
| 2657 | |
@end defvar
|
| 2658 | |
|
| 2659 | |
@defvar abs_builddir
|
| 2660 | |
@ovindex abs_builddir
|
| 2661 | |
Absolute name of @code{builddir}.
|
| 2662 | |
@end defvar
|
| 2663 | |
|
| 2664 | |
@defvar top_builddir
|
| 2665 | |
@ovindex top_builddir
|
| 2666 | |
The relative name of the top level of the current build tree. In the
|
| 2667 | |
top-level directory, this is the same as @code{builddir}.
|
| 2668 | |
@end defvar
|
| 2669 | |
|
| 2670 | |
@defvar top_build_prefix
|
| 2671 | |
@ovindex top_build_prefix
|
| 2672 | |
The relative name of the top level of the current build tree with final
|
| 2673 | |
slash if nonempty. This is the same as @code{top_builddir}, except that
|
| 2674 | |
it contains zero or more runs of @code{../}, so it should not be
|
| 2675 | |
appended with a slash for concatenation. This helps for @command{make}
|
| 2676 | |
implementations that otherwise do not treat @file{./file} and @file{file}
|
| 2677 | |
as equal in the toplevel build directory.
|
| 2678 | |
@end defvar
|
| 2679 | |
|
| 2680 | |
@defvar abs_top_builddir
|
| 2681 | |
@ovindex abs_top_builddir
|
| 2682 | |
Absolute name of @code{top_builddir}.
|
| 2683 | |
@end defvar
|
| 2684 | |
|
| 2685 | |
@defvar srcdir
|
| 2686 | |
@ovindex srcdir
|
| 2687 | |
The name of the directory that contains the source code for
|
| 2688 | |
that makefile.
|
| 2689 | |
@end defvar
|
| 2690 | |
|
| 2691 | |
@defvar abs_srcdir
|
| 2692 | |
@ovindex abs_srcdir
|
| 2693 | |
Absolute name of @code{srcdir}.
|
| 2694 | |
@end defvar
|
| 2695 | |
|
| 2696 | |
@defvar top_srcdir
|
| 2697 | |
@ovindex top_srcdir
|
| 2698 | |
The name of the top-level source code directory for the
|
| 2699 | |
package. In the top-level directory, this is the same as @code{srcdir}.
|
| 2700 | |
@end defvar
|
| 2701 | |
|
| 2702 | |
@defvar abs_top_srcdir
|
| 2703 | |
@ovindex abs_top_srcdir
|
| 2704 | |
Absolute name of @code{top_srcdir}.
|
| 2705 | |
@end defvar
|
| 2706 | |
|
| 2707 | |
@node Installation Directory Variables
|
| 2708 | |
@subsection Installation Directory Variables
|
| 2709 | |
@cindex Installation directories
|
| 2710 | |
@cindex Directories, installation
|
| 2711 | |
|
| 2712 | |
The following variables specify the directories for
|
| 2713 | |
package installation, see @ref{Directory Variables, , Variables for
|
| 2714 | |
Installation Directories, standards, The GNU Coding
|
| 2715 | |
Standards}, for more information. Each variable corresponds to an
|
| 2716 | |
argument of @command{configure}; trailing slashes are stripped so that
|
| 2717 | |
expressions such as @samp{$@{prefix@}/lib} expand with only one slash
|
| 2718 | |
between directory names. See the end of this section for
|
| 2719 | |
details on when and how to use these variables.
|
| 2720 | |
|
| 2721 | |
@defvar bindir
|
| 2722 | |
@ovindex bindir
|
| 2723 | |
The directory for installing executables that users run.
|
| 2724 | |
@end defvar
|
| 2725 | |
|
| 2726 | |
@defvar datadir
|
| 2727 | |
@ovindex datadir
|
| 2728 | |
The directory for installing idiosyncratic read-only
|
| 2729 | |
architecture-independent data.
|
| 2730 | |
@end defvar
|
| 2731 | |
|
| 2732 | |
@defvar datarootdir
|
| 2733 | |
@ovindex datarootdir
|
| 2734 | |
The root of the directory tree for read-only architecture-independent
|
| 2735 | |
data files.
|
| 2736 | |
@end defvar
|
| 2737 | |
|
| 2738 | |
@defvar docdir
|
| 2739 | |
@ovindex docdir
|
| 2740 | |
The directory for installing documentation files (other than Info and
|
| 2741 | |
man).
|
| 2742 | |
@end defvar
|
| 2743 | |
|
| 2744 | |
@defvar dvidir
|
| 2745 | |
@ovindex dvidir
|
| 2746 | |
The directory for installing documentation files in DVI format.
|
| 2747 | |
@end defvar
|
| 2748 | |
|
| 2749 | |
@defvar exec_prefix
|
| 2750 | |
@ovindex exec_prefix
|
| 2751 | |
The installation prefix for architecture-dependent files. By default
|
| 2752 | |
it's the same as @code{prefix}. You should avoid installing anything
|
| 2753 | |
directly to @code{exec_prefix}. However, the default value for
|
| 2754 | |
directories containing architecture-dependent files should be relative
|
| 2755 | |
to @code{exec_prefix}.
|
| 2756 | |
@end defvar
|
| 2757 | |
|
| 2758 | |
@defvar htmldir
|
| 2759 | |
@ovindex htmldir
|
| 2760 | |
The directory for installing HTML documentation.
|
| 2761 | |
@end defvar
|
| 2762 | |
|
| 2763 | |
@defvar includedir
|
| 2764 | |
@ovindex includedir
|
| 2765 | |
The directory for installing C header files.
|
| 2766 | |
@end defvar
|
| 2767 | |
|
| 2768 | |
@defvar infodir
|
| 2769 | |
@ovindex infodir
|
| 2770 | |
The directory for installing documentation in Info format.
|
| 2771 | |
@end defvar
|
| 2772 | |
|
| 2773 | |
@defvar libdir
|
| 2774 | |
@ovindex libdir
|
| 2775 | |
The directory for installing object code libraries.
|
| 2776 | |
@end defvar
|
| 2777 | |
|
| 2778 | |
@defvar libexecdir
|
| 2779 | |
@ovindex libexecdir
|
| 2780 | |
The directory for installing executables that other programs run.
|
| 2781 | |
@end defvar
|
| 2782 | |
|
| 2783 | |
@defvar localedir
|
| 2784 | |
@ovindex localedir
|
| 2785 | |
The directory for installing locale-dependent but
|
| 2786 | |
architecture-independent data, such as message catalogs. This directory
|
| 2787 | |
usually has a subdirectory per locale.
|
| 2788 | |
@end defvar
|
| 2789 | |
|
| 2790 | |
@defvar localstatedir
|
| 2791 | |
@ovindex localstatedir
|
| 2792 | |
The directory for installing modifiable single-machine data.
|
| 2793 | |
@end defvar
|
| 2794 | |
|
| 2795 | |
@defvar mandir
|
| 2796 | |
@ovindex mandir
|
| 2797 | |
The top-level directory for installing documentation in man format.
|
| 2798 | |
@end defvar
|
| 2799 | |
|
| 2800 | |
@defvar oldincludedir
|
| 2801 | |
@ovindex oldincludedir
|
| 2802 | |
The directory for installing C header files for non-GCC compilers.
|
| 2803 | |
@end defvar
|
| 2804 | |
|
| 2805 | |
@defvar pdfdir
|
| 2806 | |
@ovindex pdfdir
|
| 2807 | |
The directory for installing PDF documentation.
|
| 2808 | |
@end defvar
|
| 2809 | |
|
| 2810 | |
@defvar prefix
|
| 2811 | |
@ovindex prefix
|
| 2812 | |
The common installation prefix for all files. If @code{exec_prefix}
|
| 2813 | |
is defined to a different value, @code{prefix} is used only for
|
| 2814 | |
architecture-independent files.
|
| 2815 | |
@end defvar
|
| 2816 | |
|
| 2817 | |
@defvar psdir
|
| 2818 | |
@ovindex psdir
|
| 2819 | |
The directory for installing PostScript documentation.
|
| 2820 | |
@end defvar
|
| 2821 | |
|
| 2822 | |
@defvar sbindir
|
| 2823 | |
@ovindex sbindir
|
| 2824 | |
The directory for installing executables that system
|
| 2825 | |
administrators run.
|
| 2826 | |
@end defvar
|
| 2827 | |
|
| 2828 | |
@defvar sharedstatedir
|
| 2829 | |
@ovindex sharedstatedir
|
| 2830 | |
The directory for installing modifiable architecture-independent data.
|
| 2831 | |
@end defvar
|
| 2832 | |
|
| 2833 | |
@defvar sysconfdir
|
| 2834 | |
@ovindex sysconfdir
|
| 2835 | |
The directory for installing read-only single-machine data.
|
| 2836 | |
@end defvar
|
| 2837 | |
|
| 2838 | |
|
| 2839 | |
Most of these variables have values that rely on @code{prefix} or
|
| 2840 | |
@code{exec_prefix}. It is deliberate that the directory output
|
| 2841 | |
variables keep them unexpanded: typically @samp{@@datarootdir@@} is
|
| 2842 | |
replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
|
| 2843 | |
@samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
|
| 2844 | |
|
| 2845 | |
This behavior is mandated by the GNU Coding Standards, so that when
|
| 2846 | |
the user runs:
|
| 2847 | |
|
| 2848 | |
@table @samp
|
| 2849 | |
@item make
|
| 2850 | |
she can still specify a different prefix from the one specified to
|
| 2851 | |
@command{configure}, in which case, if needed, the package should hard
|
| 2852 | |
code dependencies corresponding to the make-specified prefix.
|
| 2853 | |
|
| 2854 | |
@item make install
|
| 2855 | |
she can specify a different installation location, in which case the
|
| 2856 | |
package @emph{must} still depend on the location which was compiled in
|
| 2857 | |
(i.e., never recompile when @samp{make install} is run). This is an
|
| 2858 | |
extremely important feature, as many people may decide to install all
|
| 2859 | |
the files of a package grouped together, and then install links from
|
| 2860 | |
the final locations to there.
|
| 2861 | |
@end table
|
| 2862 | |
|
| 2863 | |
In order to support these features, it is essential that
|
| 2864 | |
@code{datarootdir} remains defined as @samp{$@{prefix@}/share},
|
| 2865 | |
so that its value can be expanded based
|
| 2866 | |
on the current value of @code{prefix}.
|
| 2867 | |
|
| 2868 | |
A corollary is that you should not use these variables except in
|
| 2869 | |
makefiles. For instance, instead of trying to evaluate @code{datadir}
|
| 2870 | |
in @file{configure} and hard-coding it in makefiles using
|
| 2871 | |
e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
|
| 2872 | |
you should add
|
| 2873 | |
@option{-DDATADIR='$(datadir)'} to your makefile's definition of
|
| 2874 | |
@code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
|
| 2875 | |
|
| 2876 | |
Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
|
| 2877 | |
@code{bindir} and friends in your shell scripts and other files; instead,
|
| 2878 | |
let @command{make} manage their replacement. For instance Autoconf
|
| 2879 | |
ships templates of its shell scripts ending with @samp{.in}, and uses a
|
| 2880 | |
makefile snippet similar to the following to build scripts like
|
| 2881 | |
@command{autoheader} and @command{autom4te}:
|
| 2882 | |
|
| 2883 | |
@example
|
| 2884 | |
@group
|
| 2885 | |
edit = sed \
|
| 2886 | |
-e 's|@@bindir[@@]|$(bindir)|g' \
|
| 2887 | |
-e 's|@@pkgdatadir[@@]|$(pkgdatadir)|g' \
|
| 2888 | |
-e 's|@@prefix[@@]|$(prefix)|g'
|
| 2889 | |
@end group
|
| 2890 | |
|
| 2891 | |
@group
|
| 2892 | |
autoheader autom4te: Makefile
|
| 2893 | |
rm -f $@@ $@@.tmp
|
| 2894 | |
srcdir=''; \
|
| 2895 | |
test -f ./$@@.in || srcdir=$(srcdir)/; \
|
| 2896 | |
$(edit) $$@{srcdir@}$@@.in >$@@.tmp
|
| 2897 | |
@c $$ restore font-lock
|
| 2898 | |
chmod +x $@@.tmp
|
| 2899 | |
chmod a-w $@@.tmp
|
| 2900 | |
mv $@@.tmp $@@
|
| 2901 | |
@end group
|
| 2902 | |
|
| 2903 | |
@group
|
| 2904 | |
autoheader: $(srcdir)/autoheader.in
|
| 2905 | |
autom4te: $(srcdir)/autom4te.in
|
| 2906 | |
@end group
|
| 2907 | |
@end example
|
| 2908 | |
|
| 2909 | |
Some details are noteworthy:
|
| 2910 | |
|
| 2911 | |
@table @asis
|
| 2912 | |
@item @samp{@@bindir[@@]}
|
| 2913 | |
The brackets prevent @command{configure} from replacing
|
| 2914 | |
@samp{@@bindir@@} in the Sed expression itself.
|
| 2915 | |
Brackets are preferable to a backslash here, since
|
| 2916 | |
Posix says @samp{\@@} is not portable.
|
| 2917 | |
|
| 2918 | |
@item @samp{$(bindir)}
|
| 2919 | |
Don't use @samp{@@bindir@@}! Use the matching makefile variable
|
| 2920 | |
instead.
|
| 2921 | |
|
| 2922 | |
@item @samp{$(pkgdatadir)}
|
| 2923 | |
The example takes advantage of the variable @samp{$(pkgdatadir)}
|
| 2924 | |
provided by Automake; it is equivalent to @samp{$(datadir)/$(PACKAGE)}.
|
| 2925 | |
|
| 2926 | |
@item @samp{/}
|
| 2927 | |
Don't use @samp{/} in the Sed expressions that replace file names since
|
| 2928 | |
most likely the
|
| 2929 | |
variables you use, such as @samp{$(bindir)}, contain @samp{/}.
|
| 2930 | |
Use a shell metacharacter instead, such as @samp{|}.
|
| 2931 | |
|
| 2932 | |
@item special characters
|
| 2933 | |
File names, file name components, and the value of @code{VPATH} should
|
| 2934 | |
not contain shell metacharacters or white
|
| 2935 | |
space. @xref{Special Chars in Variables}.
|
| 2936 | |
|
| 2937 | |
@item dependency on @file{Makefile}
|
| 2938 | |
Since @code{edit} uses values that depend on the configuration specific
|
| 2939 | |
values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
|
| 2940 | |
the output depends on @file{Makefile}, not @file{configure.ac}.
|
| 2941 | |
|
| 2942 | |
@item @samp{$@@}
|
| 2943 | |
The main rule is generic, and uses @samp{$@@} extensively to
|
| 2944 | |
avoid the need for multiple copies of the rule.
|
| 2945 | |
|
| 2946 | |
@item Separated dependencies and single suffix rules
|
| 2947 | |
You can't use them! The above snippet cannot be (portably) rewritten
|
| 2948 | |
as:
|
| 2949 | |
|
| 2950 | |
@example
|
| 2951 | |
autoconf autoheader: Makefile
|
| 2952 | |
@group
|
| 2953 | |
.in:
|
| 2954 | |
rm -f $@@ $@@.tmp
|
| 2955 | |
$(edit) $< >$@@.tmp
|
| 2956 | |
chmod +x $@@.tmp
|
| 2957 | |
mv $@@.tmp $@@
|
| 2958 | |
@end group
|
| 2959 | |
@end example
|
| 2960 | |
|
| 2961 | |
@xref{Single Suffix Rules}, for details.
|
| 2962 | |
|
| 2963 | |
@item @samp{$(srcdir)}
|
| 2964 | |
Be sure to specify the name of the source directory,
|
| 2965 | |
otherwise the package won't support separated builds.
|
| 2966 | |
@end table
|
| 2967 | |
|
| 2968 | |
For the more specific installation of Erlang libraries, the following variables
|
| 2969 | |
are defined:
|
| 2970 | |
|
| 2971 | |
@defvar ERLANG_INSTALL_LIB_DIR
|
| 2972 | |
@ovindex ERLANG_INSTALL_LIB_DIR
|
| 2973 | |
@acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
|
| 2974 | |
The common parent directory of Erlang library installation directories.
|
| 2975 | |
This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
|
| 2976 | |
macro in @file{configure.ac}.
|
| 2977 | |
@end defvar
|
| 2978 | |
|
| 2979 | |
@defvar ERLANG_INSTALL_LIB_DIR_@var{library}
|
| 2980 | |
@ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
|
| 2981 | |
@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
|
| 2982 | |
The installation directory for Erlang library @var{library}.
|
| 2983 | |
This variable is set by using the
|
| 2984 | |
@samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR}
|
| 2985 | |
macro in @file{configure.ac}.
|
| 2986 | |
@end defvar
|
| 2987 | |
|
| 2988 | |
@xref{Erlang Libraries}, for details.
|
| 2989 | |
|
| 2990 | |
|
| 2991 | |
@node Changed Directory Variables
|
| 2992 | |
@subsection Changed Directory Variables
|
| 2993 | |
@cindex @file{datarootdir}
|
| 2994 | |
|
| 2995 | |
In Autoconf 2.60, the set of directory variables has changed, and the
|
| 2996 | |
defaults of some variables have been adjusted
|
| 2997 | |
(@pxref{Installation Directory Variables}) to changes in the
|
| 2998 | |
GNU Coding Standards. Notably, @file{datadir}, @file{infodir}, and
|
| 2999 | |
@file{mandir} are now expressed in terms of @file{datarootdir}. If you are
|
| 3000 | |
upgrading from an earlier Autoconf version, you may need to adjust your files
|
| 3001 | |
to ensure that the directory variables are substituted correctly
|
| 3002 | |
(@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
|
| 3003 | |
in place. For example, in a @file{Makefile.in}, adding
|
| 3004 | |
|
| 3005 | |
@example
|
| 3006 | |
datarootdir = @@datarootdir@@
|
| 3007 | |
@end example
|
| 3008 | |
|
| 3009 | |
@noindent
|
| 3010 | |
is usually sufficient. If you use Automake to create @file{Makefile.in},
|
| 3011 | |
it will add this for you.
|
| 3012 | |
|
| 3013 | |
To help with the transition, Autoconf warns about files that seem to use
|
| 3014 | |
@code{datarootdir} without defining it. In some cases, it then expands
|
| 3015 | |
the value of @code{$datarootdir} in substitutions of the directory
|
| 3016 | |
variables. The following example shows such a warning:
|
| 3017 | |
|
| 3018 | |
@example
|
| 3019 | |
$ @kbd{cat configure.ac}
|
| 3020 | |
AC_INIT
|
| 3021 | |
AC_CONFIG_FILES([Makefile])
|
| 3022 | |
AC_OUTPUT
|
| 3023 | |
$ @kbd{cat Makefile.in}
|
| 3024 | |
prefix = @@prefix@@
|
| 3025 | |
datadir = @@datadir@@
|
| 3026 | |
$ @kbd{autoconf}
|
| 3027 | |
$ @kbd{configure}
|
| 3028 | |
configure: creating ./config.status
|
| 3029 | |
config.status: creating Makefile
|
| 3030 | |
config.status: WARNING:
|
| 3031 | |
Makefile.in seems to ignore the --datarootdir setting
|
| 3032 | |
$ @kbd{cat Makefile}
|
| 3033 | |
prefix = /usr/local
|
| 3034 | |
datadir = $@{prefix@}/share
|
| 3035 | |
@end example
|
| 3036 | |
|
| 3037 | |
Usually one can easily change the file to accommodate both older and newer
|
| 3038 | |
Autoconf releases:
|
| 3039 | |
|
| 3040 | |
@example
|
| 3041 | |
$ @kbd{cat Makefile.in}
|
| 3042 | |
prefix = @@prefix@@
|
| 3043 | |
datarootdir = @@datarootdir@@
|
| 3044 | |
datadir = @@datadir@@
|
| 3045 | |
$ @kbd{configure}
|
| 3046 | |
configure: creating ./config.status
|
| 3047 | |
config.status: creating Makefile
|
| 3048 | |
$ @kbd{cat Makefile}
|
| 3049 | |
prefix = /usr/local
|
| 3050 | |
datarootdir = $@{prefix@}/share
|
| 3051 | |
datadir = $@{datarootdir@}
|
| 3052 | |
@end example
|
| 3053 | |
|
| 3054 | |
@acindex{DATAROOTDIR_CHECKED}
|
| 3055 | |
In some cases, however, the checks may not be able to detect that a suitable
|
| 3056 | |
initialization of @code{datarootdir} is in place, or they may fail to detect
|
| 3057 | |
that such an initialization is necessary in the output file. If, after
|
| 3058 | |
auditing your package, there are still spurious @file{configure} warnings about
|
| 3059 | |
@code{datarootdir}, you may add the line
|
| 3060 | |
|
| 3061 | |
@example
|
| 3062 | |
AC_DEFUN([AC_DATAROOTDIR_CHECKED])
|
| 3063 | |
@end example
|
| 3064 | |
|
| 3065 | |
@noindent
|
| 3066 | |
to your @file{configure.ac} to disable the warnings. This is an exception
|
| 3067 | |
to the usual rule that you should not define a macro whose name begins with
|
| 3068 | |
@code{AC_} (@pxref{Macro Names}).
|
| 3069 | |
|
| 3070 | |
|
| 3071 | |
|
| 3072 | |
@node Build Directories
|
| 3073 | |
@subsection Build Directories
|
| 3074 | |
@cindex Build directories
|
| 3075 | |
@cindex Directories, build
|
| 3076 | |
|
| 3077 | |
You can support compiling a software package for several architectures
|
| 3078 | |
simultaneously from the same copy of the source code. The object files
|
| 3079 | |
for each architecture are kept in their own directory.
|
| 3080 | |
|
| 3081 | |
To support doing this, @command{make} uses the @code{VPATH} variable to
|
| 3082 | |
find the files that are in the source directory. GNU Make
|
| 3083 | |
can do this. Most other recent @command{make} programs can do this as
|
| 3084 | |
well, though they may have difficulties and it is often simpler to
|
| 3085 | |
recommend GNU @command{make} (@pxref{VPATH and Make}). Older
|
| 3086 | |
@command{make} programs do not support @code{VPATH}; when using them, the
|
| 3087 | |
source code must be in the same directory as the object files.
|
| 3088 | |
|
| 3089 | |
If you are using GNU Automake, the remaining details in this
|
| 3090 | |
section are already covered for you, based on the contents of your
|
| 3091 | |
@file{Makefile.am}. But if you are using Autoconf in isolation, then
|
| 3092 | |
supporting @code{VPATH} requires the following in your
|
| 3093 | |
@file{Makefile.in}:
|
| 3094 | |
|
| 3095 | |
@example
|
| 3096 | |
srcdir = @@srcdir@@
|
| 3097 | |
VPATH = @@srcdir@@
|
| 3098 | |
@end example
|
| 3099 | |
|
| 3100 | |
Do not set @code{VPATH} to the value of another variable (@pxref{Variables
|
| 3101 | |
listed in VPATH}.
|
| 3102 | |
|
| 3103 | |
@command{configure} substitutes the correct value for @code{srcdir} when
|
| 3104 | |
it produces @file{Makefile}.
|
| 3105 | |
|
| 3106 | |
Do not use the @command{make} variable @code{$<}, which expands to the
|
| 3107 | |
file name of the file in the source directory (found with @code{VPATH}),
|
| 3108 | |
except in implicit rules. (An implicit rule is one such as @samp{.c.o},
|
| 3109 | |
which tells how to create a @file{.o} file from a @file{.c} file.) Some
|
| 3110 | |
versions of @command{make} do not set @code{$<} in explicit rules; they
|
| 3111 | |
expand it to an empty value.
|
| 3112 | |
|
| 3113 | |
Instead, Make command lines should always refer to source
|
| 3114 | |
files by prefixing them with @samp{$(srcdir)/}. For example:
|
| 3115 | |
|
| 3116 | |
@example
|
| 3117 | |
time.info: time.texinfo
|
| 3118 | |
$(MAKEINFO) '$(srcdir)/time.texinfo'
|
| 3119 | |
@end example
|
| 3120 | |
|
| 3121 | |
@node Automatic Remaking
|
| 3122 | |
@subsection Automatic Remaking
|
| 3123 | |
@cindex Automatic remaking
|
| 3124 | |
@cindex Remaking automatically
|
| 3125 | |
|
| 3126 | |
You can put rules like the following in the top-level @file{Makefile.in}
|
| 3127 | |
for a package to automatically update the configuration information when
|
| 3128 | |
you change the configuration files. This example includes all of the
|
| 3129 | |
optional files, such as @file{aclocal.m4} and those related to
|
| 3130 | |
configuration header files. Omit from the @file{Makefile.in} rules for
|
| 3131 | |
any of these files that your package does not use.
|
| 3132 | |
|
| 3133 | |
The @samp{$(srcdir)/} prefix is included because of limitations in the
|
| 3134 | |
@code{VPATH} mechanism.
|
| 3135 | |
|
| 3136 | |
The @file{stamp-} files are necessary because the timestamps of
|
| 3137 | |
@file{config.h.in} and @file{config.h} are not changed if remaking
|
| 3138 | |
them does not change their contents. This feature avoids unnecessary
|
| 3139 | |
recompilation. You should include the file @file{stamp-h.in} in your
|
| 3140 | |
package's distribution, so that @command{make} considers
|
| 3141 | |
@file{config.h.in} up to date. Don't use @command{touch}
|
| 3142 | |
(@pxref{touch, , Limitations of Usual Tools}); instead, use
|
| 3143 | |
@command{echo} (using
|
| 3144 | |
@command{date} would cause needless differences, hence CVS
|
| 3145 | |
conflicts, etc.).
|
| 3146 | |
|
| 3147 | |
@example
|
| 3148 | |
@group
|
| 3149 | |
$(srcdir)/configure: configure.ac aclocal.m4
|
| 3150 | |
cd '$(srcdir)' && autoconf
|
| 3151 | |
|
| 3152 | |
# autoheader might not change config.h.in, so touch a stamp file.
|
| 3153 | |
$(srcdir)/config.h.in: stamp-h.in
|
| 3154 | |
$(srcdir)/stamp-h.in: configure.ac aclocal.m4
|
| 3155 | |
cd '$(srcdir)' && autoheader
|
| 3156 | |
echo timestamp > '$(srcdir)/stamp-h.in'
|
| 3157 | |
|
| 3158 | |
config.h: stamp-h
|
| 3159 | |
stamp-h: config.h.in config.status
|
| 3160 | |
./config.status
|
| 3161 | |
|
| 3162 | |
Makefile: Makefile.in config.status
|
| 3163 | |
./config.status
|
| 3164 | |
|
| 3165 | |
config.status: configure
|
| 3166 | |
./config.status --recheck
|
| 3167 | |
@end group
|
| 3168 | |
@end example
|
| 3169 | |
|
| 3170 | |
@noindent
|
| 3171 | |
(Be careful if you copy these lines directly into your makefile, as you
|
| 3172 | |
need to convert the indented lines to start with the tab character.)
|
| 3173 | |
|
| 3174 | |
In addition, you should use
|
| 3175 | |
|
| 3176 | |
@example
|
| 3177 | |
AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
|
| 3178 | |
@end example
|
| 3179 | |
|
| 3180 | |
@noindent
|
| 3181 | |
so @file{config.status} ensures that @file{config.h} is considered up to
|
| 3182 | |
date. @xref{Output}, for more information about @code{AC_OUTPUT}.
|
| 3183 | |
|
| 3184 | |
@xref{config.status Invocation}, for more examples of handling
|
| 3185 | |
configuration-related dependencies.
|
| 3186 | |
|
| 3187 | |
@node Configuration Headers
|
| 3188 | |
@section Configuration Header Files
|
| 3189 | |
@cindex Configuration Header
|
| 3190 | |
@cindex @file{config.h}
|
| 3191 | |
|
| 3192 | |
When a package contains more than a few tests that define C preprocessor
|
| 3193 | |
symbols, the command lines to pass @option{-D} options to the compiler
|
| 3194 | |
can get quite long. This causes two problems. One is that the
|
| 3195 | |
@command{make} output is hard to visually scan for errors. More
|
| 3196 | |
seriously, the command lines can exceed the length limits of some
|
| 3197 | |
operating systems. As an alternative to passing @option{-D} options to
|
| 3198 | |
the compiler, @command{configure} scripts can create a C header file
|
| 3199 | |
containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
|
| 3200 | |
macro selects this kind of output. Though it can be called anywhere
|
| 3201 | |
between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
|
| 3202 | |
it right after @code{AC_INIT}.
|
| 3203 | |
|
| 3204 | |
The package should @samp{#include} the configuration header file before
|
| 3205 | |
any other header files, to prevent inconsistencies in declarations (for
|
| 3206 | |
example, if it redefines @code{const}).
|
| 3207 | |
|
| 3208 | |
To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
|
| 3209 | |
option (or @option{-I..}; whichever directory contains @file{config.h}).
|
| 3210 | |
Even if you use @samp{#include "config.h"}, the preprocessor searches only
|
| 3211 | |
the directory of the currently read file, i.e., the source directory, not
|
| 3212 | |
the build directory.
|
| 3213 | |
|
| 3214 | |
With the appropriate @option{-I} option, you can use
|
| 3215 | |
@samp{#include <config.h>}. Actually, it's a good habit to use it,
|
| 3216 | |
because in the rare case when the source directory contains another
|
| 3217 | |
@file{config.h}, the build directory should be searched first.
|
| 3218 | |
|
| 3219 | |
|
| 3220 | |
@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
|
| 3221 | |
@acindex{CONFIG_HEADERS}
|
| 3222 | |
@cvindex HAVE_CONFIG_H
|
| 3223 | |
This macro is one of the instantiating macros; see @ref{Configuration
|
| 3224 | |
Actions}. Make @code{AC_OUTPUT} create the file(s) in the
|
| 3225 | |
blank-or-newline-separated list @var{header} containing C preprocessor
|
| 3226 | |
@code{#define} statements, and replace @samp{@@DEFS@@} in generated
|
| 3227 | |
files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
|
| 3228 | |
The usual name for @var{header} is @file{config.h}.
|
| 3229 | |
|
| 3230 | |
If @var{header} already exists and its contents are identical to what
|
| 3231 | |
@code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
|
| 3232 | |
making some changes in the configuration without needlessly causing
|
| 3233 | |
object files that depend on the header file to be recompiled.
|
| 3234 | |
|
| 3235 | |
Usually the input file is named @file{@var{header}.in}; however, you can
|
| 3236 | |
override the input file name by appending to @var{header} a
|
| 3237 | |
colon-separated list of input files. For example, you might need to make
|
| 3238 | |
the input file name acceptable to DOS variants:
|
| 3239 | |
|
| 3240 | |
@example
|
| 3241 | |
AC_CONFIG_HEADERS([config.h:config.hin])
|
| 3242 | |
@end example
|
| 3243 | |
|
| 3244 | |
@end defmac
|
| 3245 | |
|
| 3246 | |
@defmac AH_HEADER
|
| 3247 | |
@ahindex{HEADER}
|
| 3248 | |
This macro is defined as the name of the first declared config header
|
| 3249 | |
and undefined if no config headers have been declared up to this point.
|
| 3250 | |
A third-party macro may, for example, require use of a config header
|
| 3251 | |
without invoking AC_CONFIG_HEADERS twice, like this:
|
| 3252 | |
|
| 3253 | |
@example
|
| 3254 | |
AC_CONFIG_COMMANDS_PRE(
|
| 3255 | |
[m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
|
| 3256 | |
@end example
|
| 3257 | |
|
| 3258 | |
@end defmac
|
| 3259 | |
|
| 3260 | |
@xref{Configuration Actions}, for more details on @var{header}.
|
| 3261 | |
|
| 3262 | |
@menu
|
| 3263 | |
* Header Templates:: Input for the configuration headers
|
| 3264 | |
* autoheader Invocation:: How to create configuration templates
|
| 3265 | |
* Autoheader Macros:: How to specify CPP templates
|
| 3266 | |
@end menu
|
| 3267 | |
|
| 3268 | |
@node Header Templates
|
| 3269 | |
@subsection Configuration Header Templates
|
| 3270 | |
@cindex Configuration Header Template
|
| 3271 | |
@cindex Header templates
|
| 3272 | |
@cindex @file{config.h.in}
|
| 3273 | |
|
| 3274 | |
Your distribution should contain a template file that looks as you want
|
| 3275 | |
the final header file to look, including comments, with @code{#undef}
|
| 3276 | |
statements which are used as hooks. For example, suppose your
|
| 3277 | |
@file{configure.ac} makes these calls:
|
| 3278 | |
|
| 3279 | |
@example
|
| 3280 | |
AC_CONFIG_HEADERS([conf.h])
|
| 3281 | |
AC_CHECK_HEADERS([unistd.h])
|
| 3282 | |
@end example
|
| 3283 | |
|
| 3284 | |
@noindent
|
| 3285 | |
Then you could have code like the following in @file{conf.h.in}.
|
| 3286 | |
The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H}
|
| 3287 | |
to 1, if and only if the system has @file{unistd.h}.
|
| 3288 | |
|
| 3289 | |
@example
|
| 3290 | |
@group
|
| 3291 | |
/* Define as 1 if you have unistd.h. */
|
| 3292 | |
#undef HAVE_UNISTD_H
|
| 3293 | |
@end group
|
| 3294 | |
@end example
|
| 3295 | |
|
| 3296 | |
The format of the template file is stricter than what the C preprocessor
|
| 3297 | |
is required to accept. A directive line should contain only whitespace,
|
| 3298 | |
@samp{#undef}, and @samp{HAVE_UNISTD_H}. The use of @samp{#define}
|
| 3299 | |
instead of @samp{#undef}, or of comments on the same line as
|
| 3300 | |
@samp{#undef}, is strongly discouraged. Each hook should only be listed
|
| 3301 | |
once. Other preprocessor lines, such as @samp{#ifdef} or
|
| 3302 | |
@samp{#include}, are copied verbatim from the template into the
|
| 3303 | |
generated header.
|
| 3304 | |
|
| 3305 | |
Since it is a tedious task to keep a template header up to date, you may
|
| 3306 | |
use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
|
| 3307 | |
|
| 3308 | |
During the instantiation of the header, each @samp{#undef} line in the
|
| 3309 | |
template file for each symbol defined by @samp{AC_DEFINE} is changed to an
|
| 3310 | |
appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not
|
| 3311 | |
been executed during the @command{configure} run, the @samp{#undef} line is
|
| 3312 | |
commented out. (This is important, e.g., for @samp{_POSIX_SOURCE}:
|
| 3313 | |
on many systems, it can be implicitly defined by the compiler, and
|
| 3314 | |
undefining it in the header would then break compilation of subsequent
|
| 3315 | |
headers.)
|
| 3316 | |
|
| 3317 | |
Currently, @emph{all} remaining @samp{#undef} lines in the header
|
| 3318 | |
template are commented out, whether or not there was a corresponding
|
| 3319 | |
@samp{AC_DEFINE} for the macro name; but this behavior is not guaranteed
|
| 3320 | |
for future releases of Autoconf.
|
| 3321 | |
|
| 3322 | |
Generally speaking, since you should not use @samp{#define}, and you
|
| 3323 | |
cannot guarantee whether a @samp{#undef} directive in the header
|
| 3324 | |
template will be converted to a @samp{#define} or commented out in the
|
| 3325 | |
generated header file, the template file cannot be used for conditional
|
| 3326 | |
definition effects. Consequently, if you need to use the construct
|
| 3327 | |
|
| 3328 | |
@example
|
| 3329 | |
@group
|
| 3330 | |
#ifdef THIS
|
| 3331 | |
# define THAT
|
| 3332 | |
#endif
|
| 3333 | |
@end group
|
| 3334 | |
@end example
|
| 3335 | |
|
| 3336 | |
@noindent
|
| 3337 | |
you must place it outside of the template.
|
| 3338 | |
If you absolutely need to hook it to the config header itself, please put
|
| 3339 | |
the directives to a separate file, and @samp{#include} that file from the
|
| 3340 | |
config header template. If you are using @command{autoheader}, you would
|
| 3341 | |
probably use @samp{AH_BOTTOM} to append the @samp{#include} directive.
|
| 3342 | |
|
| 3343 | |
|
| 3344 | |
@node autoheader Invocation
|
| 3345 | |
@subsection Using @command{autoheader} to Create @file{config.h.in}
|
| 3346 | |
@cindex @command{autoheader}
|
| 3347 | |
|
| 3348 | |
The @command{autoheader} program can create a template file of C
|
| 3349 | |
@samp{#define} statements for @command{configure} to use.
|
| 3350 | |
It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
|
| 3351 | |
@file{configure} sources to determine the name of the template.
|
| 3352 | |
(If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
|
| 3353 | |
input file name, @command{autoheader} uses the first one.)
|
| 3354 | |
|
| 3355 | |
It is recommended that only one input file is used. If you want to append
|
| 3356 | |
a boilerplate code, it is preferable to use
|
| 3357 | |
@samp{AH_BOTTOM([#include <conf_post.h>])}.
|
| 3358 | |
File @file{conf_post.h} is not processed during the configuration then,
|
| 3359 | |
which make things clearer. Analogically, @code{AH_TOP} can be used to
|
| 3360 | |
prepend a boilerplate code.
|
| 3361 | |
|
| 3362 | |
In order to do its job, @command{autoheader} needs you to document all
|
| 3363 | |
of the symbols that you might use. Typically this is done via an
|
| 3364 | |
@code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
|
| 3365 | |
is a literal symbol and whose third argument describes the symbol
|
| 3366 | |
(@pxref{Defining Symbols}). Alternatively, you can use
|
| 3367 | |
@code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
|
| 3368 | |
suitable input file for a subsequent configuration header file.
|
| 3369 | |
Symbols defined by Autoconf's builtin tests are already documented properly;
|
| 3370 | |
you need to document only those that you
|
| 3371 | |
define yourself.
|
| 3372 | |
|
| 3373 | |
You might wonder why @command{autoheader} is needed: after all, why
|
| 3374 | |
would @command{configure} need to ``patch'' a @file{config.h.in} to
|
| 3375 | |
produce a @file{config.h} instead of just creating @file{config.h} from
|
| 3376 | |
scratch? Well, when everything rocks, the answer is just that we are
|
| 3377 | |
wasting our time maintaining @command{autoheader}: generating
|
| 3378 | |
@file{config.h} directly is all that is needed. When things go wrong,
|
| 3379 | |
however, you'll be thankful for the existence of @command{autoheader}.
|
| 3380 | |
|
| 3381 | |
The fact that the symbols are documented is important in order to
|
| 3382 | |
@emph{check} that @file{config.h} makes sense. The fact that there is a
|
| 3383 | |
well-defined list of symbols that should be defined (or not) is
|
| 3384 | |
also important for people who are porting packages to environments where
|
| 3385 | |
@command{configure} cannot be run: they just have to @emph{fill in the
|
| 3386 | |
blanks}.
|
| 3387 | |
|
| 3388 | |
But let's come back to the point: the invocation of @command{autoheader}@dots{}
|
| 3389 | |
|
| 3390 | |
If you give @command{autoheader} an argument, it uses that file instead
|
| 3391 | |
of @file{configure.ac} and writes the header file to the standard output
|
| 3392 | |
instead of to @file{config.h.in}. If you give @command{autoheader} an
|
| 3393 | |
argument of @option{-}, it reads the standard input instead of
|
| 3394 | |
@file{configure.ac} and writes the header file to the standard output.
|
| 3395 | |
|
| 3396 | |
@command{autoheader} accepts the following options:
|
| 3397 | |
|
| 3398 | |
@table @option
|
| 3399 | |
@item --help
|
| 3400 | |
@itemx -h
|
| 3401 | |
Print a summary of the command line options and exit.
|
| 3402 | |
|
| 3403 | |
@item --version
|
| 3404 | |
@itemx -V
|
| 3405 | |
Print the version number of Autoconf and exit.
|
| 3406 | |
|
| 3407 | |
@item --verbose
|
| 3408 | |
@itemx -v
|
| 3409 | |
Report processing steps.
|
| 3410 | |
|
| 3411 | |
@item --debug
|
| 3412 | |
@itemx -d
|
| 3413 | |
Don't remove the temporary files.
|
| 3414 | |
|
| 3415 | |
@item --force
|
| 3416 | |
@itemx -f
|
| 3417 | |
Remake the template file even if newer than its input files.
|
| 3418 | |
|
| 3419 | |
@item --include=@var{dir}
|
| 3420 | |
@itemx -I @var{dir}
|
| 3421 | |
Append @var{dir} to the include path. Multiple invocations accumulate.
|
| 3422 | |
|
| 3423 | |
@item --prepend-include=@var{dir}
|
| 3424 | |
@itemx -B @var{dir}
|
| 3425 | |
Prepend @var{dir} to the include path. Multiple invocations accumulate.
|
| 3426 | |
|
| 3427 | |
@item --warnings=@var{category}
|
| 3428 | |
@itemx -W @var{category}
|
| 3429 | |
@evindex WARNINGS
|
| 3430 | |
Report the warnings related to @var{category} (which can actually be a
|
| 3431 | |
comma separated list). Current categories include:
|
| 3432 | |
|
| 3433 | |
@table @samp
|
| 3434 | |
@item obsolete
|
| 3435 | |
report the uses of obsolete constructs
|
| 3436 | |
|
| 3437 | |
@item all
|
| 3438 | |
report all the warnings
|
| 3439 | |
|
| 3440 | |
@item none
|
| 3441 | |
report none
|
| 3442 | |
|
| 3443 | |
@item error
|
| 3444 | |
treats warnings as errors
|
| 3445 | |
|
| 3446 | |
@item no-@var{category}
|
| 3447 | |
disable warnings falling into @var{category}
|
| 3448 | |
@end table
|
| 3449 | |
|
| 3450 | |
@end table
|
| 3451 | |
|
| 3452 | |
|
| 3453 | |
|
| 3454 | |
@node Autoheader Macros
|
| 3455 | |
@subsection Autoheader Macros
|
| 3456 | |
@cindex Autoheader macros
|
| 3457 | |
|
| 3458 | |
@command{autoheader} scans @file{configure.ac} and figures out which C
|
| 3459 | |
preprocessor symbols it might define. It knows how to generate
|
| 3460 | |
templates for symbols defined by @code{AC_CHECK_HEADERS},
|
| 3461 | |
@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
|
| 3462 | |
symbol, you must define a template for it. If there are missing
|
| 3463 | |
templates, @command{autoheader} fails with an error message.
|
| 3464 | |
|
| 3465 | |
The template for a @var{symbol} is created
|
| 3466 | |
by @command{autoheader} from
|
| 3467 | |
the @var{description} argument to an @code{AC_DEFINE};
|
| 3468 | |
see @ref{Defining Symbols}.
|
| 3469 | |
|
| 3470 | |
For special needs, you can use the following macros.
|
| 3471 | |
|
| 3472 | |
|
| 3473 | |
@defmac AH_TEMPLATE (@var{key}, @var{description})
|
| 3474 | |
@ahindex{TEMPLATE}
|
| 3475 | |
Tell @command{autoheader} to generate a template for @var{key}. This macro
|
| 3476 | |
generates standard templates just like @code{AC_DEFINE} when a
|
| 3477 | |
@var{description} is given.
|
| 3478 | |
|
| 3479 | |
For example:
|
| 3480 | |
|
| 3481 | |
@example
|
| 3482 | |
AH_TEMPLATE([CRAY_STACKSEG_END],
|
| 3483 | |
[Define to one of _getb67, GETB67, getb67
|
| 3484 | |
for Cray-2 and Cray-YMP systems. This
|
| 3485 | |
function is required for alloca.c support
|
| 3486 | |
on those systems.])
|
| 3487 | |
@end example
|
| 3488 | |
|
| 3489 | |
@noindent
|
| 3490 | |
generates the following template, with the description properly
|
| 3491 | |
justified.
|
| 3492 | |
|
| 3493 | |
@example
|
| 3494 | |
/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
|
| 3495 | |
Cray-YMP systems. This function is required for alloca.c
|
| 3496 | |
support on those systems. */
|
| 3497 | |
#undef CRAY_STACKSEG_END
|
| 3498 | |
@end example
|
| 3499 | |
@end defmac
|
| 3500 | |
|
| 3501 | |
|
| 3502 | |
@defmac AH_VERBATIM (@var{key}, @var{template})
|
| 3503 | |
@ahindex{VERBATIM}
|
| 3504 | |
Tell @command{autoheader} to include the @var{template} as-is in the header
|
| 3505 | |
template file. This @var{template} is associated with the @var{key},
|
| 3506 | |
which is used to sort all the different templates and guarantee their
|
| 3507 | |
uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
|
| 3508 | |
@end defmac
|
| 3509 | |
|
| 3510 | |
|
| 3511 | |
@defmac AH_TOP (@var{text})
|
| 3512 | |
@ahindex{TOP}
|
| 3513 | |
Include @var{text} at the top of the header template file.
|
| 3514 | |
@end defmac
|
| 3515 | |
|
| 3516 | |
|
| 3517 | |
@defmac AH_BOTTOM (@var{text})
|
| 3518 | |
@ahindex{BOTTOM}
|
| 3519 | |
Include @var{text} at the bottom of the header template file.
|
| 3520 | |
@end defmac
|
| 3521 | |
|
| 3522 | |
|
| 3523 | |
Please note that @var{text} gets included ``verbatim'' to the template file,
|
| 3524 | |
not to the resulting config header, so it can easily get mangled when the
|
| 3525 | |
template is processed. There is rarely a need for something other than
|
| 3526 | |
|
| 3527 | |
@example
|
| 3528 | |
AH_BOTTOM([#include <custom.h>])
|
| 3529 | |
@end example
|
| 3530 | |
|
| 3531 | |
|
| 3532 | |
|
| 3533 | |
@node Configuration Commands
|
| 3534 | |
@section Running Arbitrary Configuration Commands
|
| 3535 | |
@cindex Configuration commands
|
| 3536 | |
@cindex Commands for configuration
|
| 3537 | |
|
| 3538 | |
You can execute arbitrary commands before, during, and after
|
| 3539 | |
@file{config.status} is run. The three following macros accumulate the
|
| 3540 | |
commands to run when they are called multiple times.
|
| 3541 | |
@code{AC_CONFIG_COMMANDS} replaces the obsolete macro
|
| 3542 | |
@code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
|
| 3543 | |
|
| 3544 | |
@anchor{AC_CONFIG_COMMANDS}
|
| 3545 | |
@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
|
| 3546 | |
@acindex{CONFIG_COMMANDS}
|
| 3547 | |
Specify additional shell commands to run at the end of
|
| 3548 | |
@file{config.status}, and shell commands to initialize any variables
|
| 3549 | |
from @command{configure}. Associate the commands with @var{tag}.
|
| 3550 | |
Since typically the @var{cmds} create a file, @var{tag} should
|
| 3551 | |
naturally be the name of that file. If needed, the directory hosting
|
| 3552 | |
@var{tag} is created. This macro is one of the instantiating macros;
|
| 3553 | |
see @ref{Configuration Actions}.
|
| 3554 | |
|
| 3555 | |
Here is an unrealistic example:
|
| 3556 | |
@example
|
| 3557 | |
fubar=42
|
| 3558 | |
AC_CONFIG_COMMANDS([fubar],
|
| 3559 | |
[echo this is extra $fubar, and so on.],
|
| 3560 | |
[fubar=$fubar])
|
| 3561 | |
@end example
|
| 3562 | |
|
| 3563 | |
Here is a better one:
|
| 3564 | |
@example
|
| 3565 | |
AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
|
| 3566 | |
@end example
|
| 3567 | |
@end defmac
|
| 3568 | |
|
| 3569 | |
The following two macros look similar, but in fact they are not of the same
|
| 3570 | |
breed: they are executed directly by @file{configure}, so you cannot use
|
| 3571 | |
@file{config.status} to rerun them.
|
| 3572 | |
|
| 3573 | |
@c Yet it is good to leave them here. The user sees them together and
|
| 3574 | |
@c decides which best fits their needs.
|
| 3575 | |
|
| 3576 | |
@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
|
| 3577 | |
@acindex{CONFIG_COMMANDS_PRE}
|
| 3578 | |
Execute the @var{cmds} right before creating @file{config.status}.
|
| 3579 | |
|
| 3580 | |
This macro presents the last opportunity to call @code{AC_SUBST},
|
| 3581 | |
@code{AC_DEFINE}, or @code{AC_CONFIG_@var{ITEMS}} macros.
|
| 3582 | |
@end defmac
|
| 3583 | |
|
| 3584 | |
@defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
|
| 3585 | |
@acindex{CONFIG_COMMANDS_POST}
|
| 3586 | |
Execute the @var{cmds} right after creating @file{config.status}.
|
| 3587 | |
@end defmac
|
| 3588 | |
|
| 3589 | |
|
| 3590 | |
|
| 3591 | |
|
| 3592 | |
@node Configuration Links
|
| 3593 | |
@section Creating Configuration Links
|
| 3594 | |
@cindex Configuration links
|
| 3595 | |
@cindex Links for configuration
|
| 3596 | |
|
| 3597 | |
You may find it convenient to create links whose destinations depend upon
|
| 3598 | |
results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
|
| 3599 | |
creation of relative symbolic links can be delicate when the package is
|
| 3600 | |
built in a directory different from the source directory.
|
| 3601 | |
|
| 3602 | |
@anchor{AC_CONFIG_LINKS}
|
| 3603 | |
@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @
|
| 3604 | |
@ovar{init-cmds})
|
| 3605 | |
@acindex{CONFIG_LINKS}
|
| 3606 | |
@cindex Links
|
| 3607 | |
Make @code{AC_OUTPUT} link each of the existing files @var{source} to
|
| 3608 | |
the corresponding link name @var{dest}. Makes a symbolic link if
|
| 3609 | |
possible, otherwise a hard link if possible, otherwise a copy. The
|
| 3610 | |
@var{dest} and @var{source} names should be relative to the top level
|
| 3611 | |
source or build directory. This macro is one of the instantiating
|
| 3612 | |
macros; see @ref{Configuration Actions}.
|
| 3613 | |
|
| 3614 | |
For example, this call:
|
| 3615 | |
|
| 3616 | |
@example
|
| 3617 | |
AC_CONFIG_LINKS([host.h:config/$machine.h
|
| 3618 | |
object.h:config/$obj_format.h])
|
| 3619 | |
@end example
|
| 3620 | |
|
| 3621 | |
@noindent
|
| 3622 | |
creates in the current directory @file{host.h} as a link to
|
| 3623 | |
@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
|
| 3624 | |
link to @file{@var{srcdir}/config/$obj_format.h}.
|
| 3625 | |
|
| 3626 | |
The tempting value @samp{.} for @var{dest} is invalid: it makes it
|
| 3627 | |
impossible for @samp{config.status} to guess the links to establish.
|
| 3628 | |
|
| 3629 | |
One can then run:
|
| 3630 | |
@example
|
| 3631 | |
./config.status host.h object.h
|
| 3632 | |
@end example
|
| 3633 | |
@noindent
|
| 3634 | |
to create the links.
|
| 3635 | |
@end defmac
|
| 3636 | |
|
| 3637 | |
|
| 3638 | |
|
| 3639 | |
@node Subdirectories
|
| 3640 | |
@section Configuring Other Packages in Subdirectories
|
| 3641 | |
@cindex Configure subdirectories
|
| 3642 | |
@cindex Subdirectory configure
|
| 3643 | |
|
| 3644 | |
In most situations, calling @code{AC_OUTPUT} is sufficient to produce
|
| 3645 | |
makefiles in subdirectories. However, @command{configure} scripts
|
| 3646 | |
that control more than one independent package can use
|
| 3647 | |
@code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
|
| 3648 | |
packages in subdirectories.
|
| 3649 | |
|
| 3650 | |
@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
|
| 3651 | |
@acindex{CONFIG_SUBDIRS}
|
| 3652 | |
@ovindex subdirs
|
| 3653 | |
Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
|
| 3654 | |
@var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
|
| 3655 | |
be a literal, i.e., please do not use:
|
| 3656 | |
|
| 3657 | |
@example
|
| 3658 | |
@c If you change this example, adjust tests/torture.at:Non-literal AC_CONFIG_SUBDIRS.
|
| 3659 | |
if test "x$package_foo_enabled" = xyes; then
|
| 3660 | |
my_subdirs="$my_subdirs foo"
|
| 3661 | |
fi
|
| 3662 | |
AC_CONFIG_SUBDIRS([$my_subdirs])
|
| 3663 | |
@end example
|
| 3664 | |
|
| 3665 | |
@noindent
|
| 3666 | |
because this prevents @samp{./configure --help=recursive} from
|
| 3667 | |
displaying the options of the package @code{foo}. Instead, you should
|
| 3668 | |
write:
|
| 3669 | |
|
| 3670 | |
@example
|
| 3671 | |
if test "x$package_foo_enabled" = xyes; then
|
| 3672 | |
AC_CONFIG_SUBDIRS([foo])
|
| 3673 | |
fi
|
| 3674 | |
@end example
|
| 3675 | |
|
| 3676 | |
If a given @var{dir} is not found at @command{configure} run time, a
|
| 3677 | |
warning is reported; if the subdirectory is optional, write:
|
| 3678 | |
|
| 3679 | |
@example
|
| 3680 | |
if test -d "$srcdir/foo"; then
|
| 3681 | |
AC_CONFIG_SUBDIRS([foo])
|
| 3682 | |
fi
|
| 3683 | |
@end example
|
| 3684 | |
|
| 3685 | |
@c NB: Yes, below we mean configure.in, not configure.ac.
|
| 3686 | |
If a given @var{dir} contains @command{configure.gnu}, it is run instead
|
| 3687 | |
of @command{configure}. This is for packages that might use a
|
| 3688 | |
non-Autoconf script @command{Configure}, which can't be called through a
|
| 3689 | |
wrapper @command{configure} since it would be the same file on
|
| 3690 | |
case-insensitive file systems. Likewise, if a @var{dir} contains
|
| 3691 | |
@file{configure.in} but no @command{configure}, the Cygnus
|
| 3692 | |
@command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
|
| 3693 | |
|
| 3694 | |
The subdirectory @command{configure} scripts are given the same command
|
| 3695 | |
line options that were given to this @command{configure} script, with minor
|
| 3696 | |
changes if needed, which include:
|
| 3697 | |
|
| 3698 | |
@itemize @minus
|
| 3699 | |
@item
|
| 3700 | |
adjusting a relative name for the cache file;
|
| 3701 | |
|
| 3702 | |
@item
|
| 3703 | |
adjusting a relative name for the source directory;
|
| 3704 | |
|
| 3705 | |
@item
|
| 3706 | |
propagating the current value of @code{$prefix}, including if it was
|
| 3707 | |
defaulted, and if the default values of the top level and of the subdirectory
|
| 3708 | |
@file{configure} differ.
|
| 3709 | |
@end itemize
|
| 3710 | |
|
| 3711 | |
This macro also sets the output variable @code{subdirs} to the list of
|
| 3712 | |
directories @samp{@var{dir} @dots{}}. Make rules can use
|
| 3713 | |
this variable to determine which subdirectories to recurse into.
|
| 3714 | |
|
| 3715 | |
This macro may be called multiple times.
|
| 3716 | |
@end defmac
|
| 3717 | |
|
| 3718 | |
@node Default Prefix
|
| 3719 | |
@section Default Prefix
|
| 3720 | |
@cindex Install prefix
|
| 3721 | |
@cindex Prefix for install
|
| 3722 | |
|
| 3723 | |
By default, @command{configure} sets the prefix for files it installs to
|
| 3724 | |
@file{/usr/local}. The user of @command{configure} can select a different
|
| 3725 | |
prefix using the @option{--prefix} and @option{--exec-prefix} options.
|
| 3726 | |
There are two ways to change the default: when creating
|
| 3727 | |
@command{configure}, and when running it.
|
| 3728 | |
|
| 3729 | |
Some software packages might want to install in a directory other than
|
| 3730 | |
@file{/usr/local} by default. To accomplish that, use the
|
| 3731 | |
@code{AC_PREFIX_DEFAULT} macro.
|
| 3732 | |
|
| 3733 | |
@defmac AC_PREFIX_DEFAULT (@var{prefix})
|
| 3734 | |
@acindex{PREFIX_DEFAULT}
|
| 3735 | |
Set the default installation prefix to @var{prefix} instead of
|
| 3736 | |
@file{/usr/local}.
|
| 3737 | |
@end defmac
|
| 3738 | |
|
| 3739 | |
It may be convenient for users to have @command{configure} guess the
|
| 3740 | |
installation prefix from the location of a related program that they
|
| 3741 | |
have already installed. If you wish to do that, you can call
|
| 3742 | |
@code{AC_PREFIX_PROGRAM}.
|
| 3743 | |
|
| 3744 | |
@anchor{AC_PREFIX_PROGRAM}
|
| 3745 | |
@defmac AC_PREFIX_PROGRAM (@var{program})
|
| 3746 | |
@acindex{PREFIX_PROGRAM}
|
| 3747 | |
If the user did not specify an installation prefix (using the
|
| 3748 | |
@option{--prefix} option), guess a value for it by looking for
|
| 3749 | |
@var{program} in @env{PATH}, the way the shell does. If @var{program}
|
| 3750 | |
is found, set the prefix to the parent of the directory containing
|
| 3751 | |
@var{program}, else default the prefix as described above
|
| 3752 | |
(@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
|
| 3753 | |
@var{program} is @code{gcc} and the @env{PATH} contains
|
| 3754 | |
@file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
|
| 3755 | |
@end defmac
|
| 3756 | |
|
| 3757 | |
|
| 3758 | |
|
| 3759 | |
@c ======================================================== Existing tests
|
| 3760 | |
|
| 3761 | |
@node Existing Tests
|
| 3762 | |
@chapter Existing Tests
|
| 3763 | |
|
| 3764 | |
These macros test for particular system features that packages might
|
| 3765 | |
need or want to use. If you need to test for a kind of feature that
|
| 3766 | |
none of these macros check for, you can probably do it by calling
|
| 3767 | |
primitive test macros with appropriate arguments (@pxref{Writing
|
| 3768 | |
Tests}).
|
| 3769 | |
|
| 3770 | |
These tests print messages telling the user which feature they're
|
| 3771 | |
checking for, and what they find. They cache their results for future
|
| 3772 | |
@command{configure} runs (@pxref{Caching Results}).
|
| 3773 | |
|
| 3774 | |
Some of these macros set output variables. @xref{Makefile
|
| 3775 | |
Substitutions}, for how to get their values. The phrase ``define
|
| 3776 | |
@var{name}'' is used below as a shorthand to mean ``define the C
|
| 3777 | |
preprocessor symbol @var{name} to the value 1''. @xref{Defining
|
| 3778 | |
Symbols}, for how to get those symbol definitions into your program.
|
| 3779 | |
|
| 3780 | |
@menu
|
| 3781 | |
* Common Behavior:: Macros' standard schemes
|
| 3782 | |
* Alternative Programs:: Selecting between alternative programs
|
| 3783 | |
* Files:: Checking for the existence of files
|
| 3784 | |
* Libraries:: Library archives that might be missing
|
| 3785 | |
* Library Functions:: C library functions that might be missing
|
| 3786 | |
* Header Files:: Header files that might be missing
|
| 3787 | |
* Declarations:: Declarations that may be missing
|
| 3788 | |
* Structures:: Structures or members that might be missing
|
| 3789 | |
* Types:: Types that might be missing
|
| 3790 | |
* Compilers and Preprocessors:: Checking for compiling programs
|
| 3791 | |
* System Services:: Operating system services
|
| 3792 | |
* Posix Variants:: Special kludges for specific Posix variants
|
| 3793 | |
* Erlang Libraries:: Checking for the existence of Erlang libraries
|
| 3794 | |
@end menu
|
| 3795 | |
|
| 3796 | |
@node Common Behavior
|
| 3797 | |
@section Common Behavior
|
| 3798 | |
@cindex Common autoconf behavior
|
| 3799 | |
|
| 3800 | |
Much effort has been expended to make Autoconf easy to learn. The most
|
| 3801 | |
obvious way to reach this goal is simply to enforce standard interfaces
|
| 3802 | |
and behaviors, avoiding exceptions as much as possible. Because of
|
| 3803 | |
history and inertia, unfortunately, there are still too many exceptions
|
| 3804 | |
in Autoconf; nevertheless, this section describes some of the common
|
| 3805 | |
rules.
|
| 3806 | |
|
| 3807 | |
@menu
|
| 3808 | |
* Standard Symbols:: Symbols defined by the macros
|
| 3809 | |
* Default Includes:: Includes used by the generic macros
|
| 3810 | |
@end menu
|
| 3811 | |
|
| 3812 | |
@node Standard Symbols
|
| 3813 | |
@subsection Standard Symbols
|
| 3814 | |
@cindex Standard symbols
|
| 3815 | |
|
| 3816 | |
All the generic macros that @code{AC_DEFINE} a symbol as a result of
|
| 3817 | |
their test transform their @var{argument} values to a standard alphabet.
|
| 3818 | |
First, @var{argument} is converted to upper case and any asterisks
|
| 3819 | |
(@samp{*}) are each converted to @samp{P}. Any remaining characters
|
| 3820 | |
that are not alphanumeric are converted to underscores.
|
| 3821 | |
|
| 3822 | |
For instance,
|
| 3823 | |
|
| 3824 | |
@example
|
| 3825 | |
AC_CHECK_TYPES([struct $Expensive*])
|
| 3826 | |
@end example
|
| 3827 | |
|
| 3828 | |
@noindent
|
| 3829 | |
defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
|
| 3830 | |
succeeds.
|
| 3831 | |
|
| 3832 | |
|
| 3833 | |
@node Default Includes
|
| 3834 | |
@subsection Default Includes
|
| 3835 | |
@cindex Default includes
|
| 3836 | |
@cindex Includes, default
|
| 3837 | |
|
| 3838 | |
Several tests depend upon a set of header files. Since these headers
|
| 3839 | |
are not universally available, tests actually have to provide a set of
|
| 3840 | |
protected includes, such as:
|
| 3841 | |
|
| 3842 | |
@example
|
| 3843 | |
@group
|
| 3844 | |
#ifdef TIME_WITH_SYS_TIME
|
| 3845 | |
# include <sys/time.h>
|
| 3846 | |
# include <time.h>
|
| 3847 | |
#else
|
| 3848 | |
# ifdef HAVE_SYS_TIME_H
|
| 3849 | |
# include <sys/time.h>
|
| 3850 | |
# else
|
| 3851 | |
# include <time.h>
|
| 3852 | |
# endif
|
| 3853 | |
#endif
|
| 3854 | |
@end group
|
| 3855 | |
@end example
|
| 3856 | |
|
| 3857 | |
@noindent
|
| 3858 | |
Unless you know exactly what you are doing, you should avoid using
|
| 3859 | |
unconditional includes, and check the existence of the headers you
|
| 3860 | |
include beforehand (@pxref{Header Files}).
|
| 3861 | |
|
| 3862 | |
Most generic macros use the following macro to provide the default set
|
| 3863 | |
of includes:
|
| 3864 | |
|
| 3865 | |
@defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
|
| 3866 | |
@acindex{INCLUDES_DEFAULT}
|
| 3867 | |
Expand to @var{include-directives} if defined, otherwise to:
|
| 3868 | |
|
| 3869 | |
@example
|
| 3870 | |
@group
|
| 3871 | |
#include <stdio.h>
|
| 3872 | |
#ifdef HAVE_SYS_TYPES_H
|
| 3873 | |
# include <sys/types.h>
|
| 3874 | |
#endif
|
| 3875 | |
#ifdef HAVE_SYS_STAT_H
|
| 3876 | |
# include <sys/stat.h>
|
| 3877 | |
#endif
|
| 3878 | |
#ifdef STDC_HEADERS
|
| 3879 | |
# include <stdlib.h>
|
| 3880 | |
# include <stddef.h>
|
| 3881 | |
#else
|
| 3882 | |
# ifdef HAVE_STDLIB_H
|
| 3883 | |
# include <stdlib.h>
|
| 3884 | |
# endif
|
| 3885 | |
#endif
|
| 3886 | |
#ifdef HAVE_STRING_H
|
| 3887 | |
# if !defined STDC_HEADERS && defined HAVE_MEMORY_H
|
| 3888 | |
# include <memory.h>
|
| 3889 | |
# endif
|
| 3890 | |
# include <string.h>
|
| 3891 | |
#endif
|
| 3892 | |
#ifdef HAVE_STRINGS_H
|
| 3893 | |
# include <strings.h>
|
| 3894 | |
#endif
|
| 3895 | |
#ifdef HAVE_INTTYPES_H
|
| 3896 | |
# include <inttypes.h>
|
| 3897 | |
#endif
|
| 3898 | |
#ifdef HAVE_STDINT_H
|
| 3899 | |
# include <stdint.h>
|
| 3900 | |
#endif
|
| 3901 | |
#ifdef HAVE_UNISTD_H
|
| 3902 | |
# include <unistd.h>
|
| 3903 | |
#endif
|
| 3904 | |
@end group
|
| 3905 | |
@end example
|
| 3906 | |
|
| 3907 | |
If the default includes are used, then check for the presence of these
|
| 3908 | |
headers and their compatibility, i.e., you don't need to run
|
| 3909 | |
@code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
|
| 3910 | |
|
| 3911 | |
These headers are checked for in the same order as they are included.
|
| 3912 | |
For instance, on some systems @file{string.h} and @file{strings.h} both
|
| 3913 | |
exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
|
| 3914 | |
@code{HAVE_STRINGS_H}.
|
| 3915 | |
@end defmac
|
| 3916 | |
|
| 3917 | |
@node Alternative Programs
|
| 3918 | |
@section Alternative Programs
|
| 3919 | |
@cindex Programs, checking
|
| 3920 | |
|
| 3921 | |
These macros check for the presence or behavior of particular programs.
|
| 3922 | |
They are used to choose between several alternative programs and to
|
| 3923 | |
decide what to do once one has been chosen. If there is no macro
|
| 3924 | |
specifically defined to check for a program you need, and you don't need
|
| 3925 | |
to check for any special properties of it, then you can use one of the
|
| 3926 | |
general program-check macros.
|
| 3927 | |
|
| 3928 | |
@menu
|
| 3929 | |
* Particular Programs:: Special handling to find certain programs
|
| 3930 | |
* Generic Programs:: How to find other programs
|
| 3931 | |
@end menu
|
| 3932 | |
|
| 3933 | |
@node Particular Programs
|
| 3934 | |
@subsection Particular Program Checks
|
| 3935 | |
|
| 3936 | |
These macros check for particular programs---whether they exist, and
|
| 3937 | |
in some cases whether they support certain features.
|
| 3938 | |
|
| 3939 | |
@defmac AC_PROG_AWK
|
| 3940 | |
@acindex{PROG_AWK}
|
| 3941 | |
@ovindex AWK
|
| 3942 | |
@caindex prog_AWK
|
| 3943 | |
Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
|
| 3944 | |
order, and set output variable @code{AWK} to the first one that is found.
|
| 3945 | |
It tries @code{gawk} first because that is reported to be the
|
| 3946 | |
best implementation. The result can be overridden by setting the
|
| 3947 | |
variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}.
|
| 3948 | |
|
| 3949 | |
Using this macro is sufficient to avoid the pitfalls of traditional
|
| 3950 | |
@command{awk} (@pxref{awk, , Limitations of Usual Tools}).
|
| 3951 | |
@end defmac
|
| 3952 | |
|
| 3953 | |
@defmac AC_PROG_GREP
|
| 3954 | |
@acindex{PROG_GREP}
|
| 3955 | |
@ovindex GREP
|
| 3956 | |
@caindex prog_GREP
|
| 3957 | |
Look for the best available @code{grep} or @code{ggrep} that accepts the
|
| 3958 | |
longest input lines possible, and that supports multiple @option{-e} options.
|
| 3959 | |
Set the output variable @code{GREP} to whatever is chosen.
|
| 3960 | |
@xref{grep, , Limitations of Usual Tools}, for more information about
|
| 3961 | |
portability problems with the @command{grep} command family. The result
|
| 3962 | |
can be overridden by setting the @code{GREP} variable and is cached in the
|
| 3963 | |
@code{ac_cv_path_GREP} variable.
|
| 3964 | |
@end defmac
|
| 3965 | |
|
| 3966 | |
@defmac AC_PROG_EGREP
|
| 3967 | |
@acindex{PROG_EGREP}
|
| 3968 | |
@ovindex EGREP
|
| 3969 | |
@caindex prog_EGREP
|
| 3970 | |
Check whether @code{$GREP -E} works, or else look for the best available
|
| 3971 | |
@code{egrep} or @code{gegrep} that accepts the longest input lines possible.
|
| 3972 | |
Set the output variable @code{EGREP} to whatever is chosen. The result
|
| 3973 | |
can be overridden by setting the @code{EGREP} variable and is cached in the
|
| 3974 | |
@code{ac_cv_path_EGREP} variable.
|
| 3975 | |
@end defmac
|
| 3976 | |
|
| 3977 | |
@defmac AC_PROG_FGREP
|
| 3978 | |
@acindex{PROG_FGREP}
|
| 3979 | |
@ovindex FGREP
|
| 3980 | |
@caindex prog_FGREP
|
| 3981 | |
Check whether @code{$GREP -F} works, or else look for the best available
|
| 3982 | |
@code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
|
| 3983 | |
Set the output variable @code{FGREP} to whatever is chosen. The result
|
| 3984 | |
can be overridden by setting the @code{FGREP} variable and is cached in the
|
| 3985 | |
@code{ac_cv_path_FGREP} variable.
|
| 3986 | |
@end defmac
|
| 3987 | |
|
| 3988 | |
@defmac AC_PROG_INSTALL
|
| 3989 | |
@acindex{PROG_INSTALL}
|
| 3990 | |
@ovindex INSTALL
|
| 3991 | |
@ovindex INSTALL_PROGRAM
|
| 3992 | |
@ovindex INSTALL_DATA
|
| 3993 | |
@ovindex INSTALL_SCRIPT
|
| 3994 | |
@caindex path_install
|
| 3995 | |
Set output variable @code{INSTALL} to the name of a BSD-compatible
|
| 3996 | |
@command{install} program, if one is found in the current @env{PATH}.
|
| 3997 | |
Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
|
| 3998 | |
checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
|
| 3999 | |
default directories) to determine @var{dir} (@pxref{Output}). Also set
|
| 4000 | |
the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
|
| 4001 | |
@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
|
| 4002 | |
|
| 4003 | |
@samp{@@INSTALL@@} is special, as its value may vary for different
|
| 4004 | |
configuration files.
|
| 4005 | |
|
| 4006 | |
This macro screens out various instances of @command{install} known not to
|
| 4007 | |
work. It prefers to find a C program rather than a shell script, for
|
| 4008 | |
speed. Instead of @file{install-sh}, it can also use @file{install.sh},
|
| 4009 | |
but that name is obsolete because some @command{make} programs have a rule
|
| 4010 | |
that creates @file{install} from it if there is no makefile. Further, this
|
| 4011 | |
macro requires @command{install} to be able to install multiple files into a
|
| 4012 | |
target directory in a single invocation.
|
| 4013 | |
|
| 4014 | |
Autoconf comes with a copy of @file{install-sh} that you can use. If
|
| 4015 | |
you use @code{AC_PROG_INSTALL}, you must include either
|
| 4016 | |
@file{install-sh} or @file{install.sh} in your distribution; otherwise
|
| 4017 | |
@command{configure} produces an error message saying it can't find
|
| 4018 | |
them---even if the system you're on has a good @command{install} program.
|
| 4019 | |
This check is a safety measure to prevent you from accidentally leaving
|
| 4020 | |
that file out, which would prevent your package from installing on
|
| 4021 | |
systems that don't have a BSD-compatible @command{install} program.
|
| 4022 | |
|
| 4023 | |
If you need to use your own installation program because it has features
|
| 4024 | |
not found in standard @command{install} programs, there is no reason to use
|
| 4025 | |
@code{AC_PROG_INSTALL}; just put the file name of your program into your
|
| 4026 | |
@file{Makefile.in} files.
|
| 4027 | |
|
| 4028 | |
The result of the test can be overridden by setting the variable
|
| 4029 | |
@code{INSTALL} or the cache variable @code{ac_cv_path_install}.
|
| 4030 | |
@end defmac
|
| 4031 | |
|
| 4032 | |
@defmac AC_PROG_MKDIR_P
|
| 4033 | |
@acindex{PROG_MKDIR_P}
|
| 4034 | |
@ovindex MKDIR_P
|
| 4035 | |
@caindex path_mkdir
|
| 4036 | |
Set output variable @code{MKDIR_P} to a program that ensures that for
|
| 4037 | |
each argument, a directory named by this argument exists, creating it
|
| 4038 | |
and its parent directories if needed, and without race conditions when
|
| 4039 | |
two instances of the program attempt to make the same directory at
|
| 4040 | |
nearly the same time.
|
| 4041 | |
|
| 4042 | |
This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
|
| 4043 | |
falls back on invoking @command{install-sh} with the @option{-d} option,
|
| 4044 | |
so your package should
|
| 4045 | |
contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
|
| 4046 | |
An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
|
| 4047 | |
is vulnerable to race conditions, so if you want to support parallel
|
| 4048 | |
installs from
|
| 4049 | |
different packages into the same directory you need to make sure you
|
| 4050 | |
have an up-to-date @file{install-sh}. In particular, be careful about
|
| 4051 | |
using @samp{autoreconf -if} if your Automake predates Automake 1.10.
|
| 4052 | |
|
| 4053 | |
This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
|
| 4054 | |
in M4sh}), but it sets an output variable intended for use in other
|
| 4055 | |
files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
|
| 4056 | |
@command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
|
| 4057 | |
but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
|
| 4058 | |
might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
|
| 4059 | |
directory, and conversely a makefile should use @code{$(MKDIR_P) --
|
| 4060 | |
$(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
|
| 4061 | |
Finally, @code{AS_MKDIR_P} does not check for race condition
|
| 4062 | |
vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
|
| 4063 | |
|
| 4064 | |
@samp{@@MKDIR_P@@} is special, as its value may vary for different
|
| 4065 | |
configuration files.
|
| 4066 | |
|
| 4067 | |
The result of the test can be overridden by setting the variable
|
| 4068 | |
@code{MKDIR_P} or the cache variable @code{ac_cv_path_mkdir}.
|
| 4069 | |
@end defmac
|
| 4070 | |
|
| 4071 | |
@anchor{AC_PROG_LEX}
|
| 4072 | |
@defmac AC_PROG_LEX
|
| 4073 | |
@acindex{PROG_LEX}
|
| 4074 | |
@ovindex LEX
|
| 4075 | |
@ovindex LEXLIB
|
| 4076 | |
@cvindex YYTEXT_POINTER
|
| 4077 | |
@ovindex LEX_OUTPUT_ROOT
|
| 4078 | |
@caindex prog_LEX
|
| 4079 | |
If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
|
| 4080 | |
and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
|
| 4081 | |
place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
|
| 4082 | |
@option{-ll}, if found. If neither variant is available, set @code{LEX}
|
| 4083 | |
to @samp{:}; for packages that ship the generated @file{file.yy.c}
|
| 4084 | |
alongside the source @file{file.l}, this default allows users without a
|
| 4085 | |
lexer generator to still build the package even if the timestamp for
|
| 4086 | |
@file{file.l} is inadvertently changed.
|
| 4087 | |
|
| 4088 | |
Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
|
| 4089 | |
of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
|
| 4090 | |
the base of the file name that the lexer generates; usually
|
| 4091 | |
@file{lex.yy}, but sometimes something else. These results vary
|
| 4092 | |
according to whether @code{lex} or @code{flex} is being used.
|
| 4093 | |
|
| 4094 | |
You are encouraged to use Flex in your sources, since it is both more
|
| 4095 | |
pleasant to use than plain Lex and the C source it produces is portable.
|
| 4096 | |
In order to ensure portability, however, you must either provide a
|
| 4097 | |
function @code{yywrap} or, if you don't use it (e.g., your scanner has
|
| 4098 | |
no @samp{#include}-like feature), simply include a @samp{%noyywrap}
|
| 4099 | |
statement in the scanner's source. Once this done, the scanner is
|
| 4100 | |
portable (unless @emph{you} felt free to use nonportable constructs) and
|
| 4101 | |
does not depend on any library. In this case, and in this case only, it
|
| 4102 | |
is suggested that you use this Autoconf snippet:
|
| 4103 | |
|
| 4104 | |
@example
|
| 4105 | |
AC_PROG_LEX
|
| 4106 | |
if test "x$LEX" != xflex; then
|
| 4107 | |
LEX="$SHELL $missing_dir/missing flex"
|
| 4108 | |
AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
|
| 4109 | |
AC_SUBST([LEXLIB], [''])
|
| 4110 | |
fi
|
| 4111 | |
@end example
|
| 4112 | |
|
| 4113 | |
The shell script @command{missing} can be found in the Automake
|
| 4114 | |
distribution.
|
| 4115 | |
|
| 4116 | |
Remember that the user may have supplied an alternate location in
|
| 4117 | |
@env{LEX}, so if Flex is required, it is better to check that the user
|
| 4118 | |
provided something sufficient by parsing the output of @samp{$LEX
|
| 4119 | |
--version} than by simply relying on @code{test "x$LEX" = xflex}.
|
| 4120 | |
|
| 4121 | |
To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
|
| 4122 | |
(indirectly) this macro twice, which causes an annoying but benign
|
| 4123 | |
``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
|
| 4124 | |
of Automake will fix this issue; meanwhile, just ignore this message.
|
| 4125 | |
|
| 4126 | |
As part of running the test, this macro may delete any file in the
|
| 4127 | |
configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
|
| 4128 | |
|
| 4129 | |
The result of this test can be influenced by setting the variable
|
| 4130 | |
@code{LEX} or the cache variable @code{ac_cv_prog_LEX}.
|
| 4131 | |
@end defmac
|
| 4132 | |
|
| 4133 | |
@anchor{AC_PROG_LN_S}
|
| 4134 | |
@defmac AC_PROG_LN_S
|
| 4135 | |
@acindex{PROG_LN_S}
|
| 4136 | |
@ovindex LN_S
|
| 4137 | |
If @samp{ln -s} works on the current file system (the operating system
|
| 4138 | |
and file system support symbolic links), set the output variable
|
| 4139 | |
@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
|
| 4140 | |
@code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -pR}.
|
| 4141 | |
|
| 4142 | |
If you make a link in a directory other than the current directory, its
|
| 4143 | |
meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
|
| 4144 | |
create links using @samp{$(LN_S)}, either find out which form is used
|
| 4145 | |
and adjust the arguments, or always invoke @code{ln} in the directory
|
| 4146 | |
where the link is to be created.
|
| 4147 | |
|
| 4148 | |
In other words, it does not work to do:
|
| 4149 | |
@example
|
| 4150 | |
$(LN_S) foo /x/bar
|
| 4151 | |
@end example
|
| 4152 | |
|
| 4153 | |
Instead, do:
|
| 4154 | |
|
| 4155 | |
@example
|
| 4156 | |
(cd /x && $(LN_S) foo bar)
|
| 4157 | |
@end example
|
| 4158 | |
@end defmac
|
| 4159 | |
|
| 4160 | |
@defmac AC_PROG_RANLIB
|
| 4161 | |
@acindex{PROG_RANLIB}
|
| 4162 | |
@ovindex RANLIB
|
| 4163 | |
@c @caindex prog_RANLIB
|
| 4164 | |
@c @caindex prog_ac_ct_RANLIB
|
| 4165 | |
Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
|
| 4166 | |
is found, and otherwise to @samp{:} (do nothing).
|
| 4167 | |
@end defmac
|
| 4168 | |
|
| 4169 | |
@defmac AC_PROG_SED
|
| 4170 | |
@acindex{PROG_SED}
|
| 4171 | |
@ovindex SED
|
| 4172 | |
@caindex path_SED
|
| 4173 | |
Set output variable @code{SED} to a Sed implementation that conforms to
|
| 4174 | |
Posix and does not have arbitrary length limits. Report an error if no
|
| 4175 | |
acceptable Sed is found. @xref{sed, , Limitations of Usual Tools}, for more
|
| 4176 | |
information about portability problems with Sed.
|
| 4177 | |
|
| 4178 | |
The result of this test can be overridden by setting the @code{SED} variable
|
| 4179 | |
and is cached in the @code{ac_cv_path_SED} variable.
|
| 4180 | |
@end defmac
|
| 4181 | |
|
| 4182 | |
@defmac AC_PROG_YACC
|
| 4183 | |
@acindex{PROG_YACC}
|
| 4184 | |
@evindex YACC
|
| 4185 | |
@evindex YFLAGS
|
| 4186 | |
@ovindex YACC
|
| 4187 | |
@caindex prog_YACC
|
| 4188 | |
If @code{bison} is found, set output variable @code{YACC} to @samp{bison
|
| 4189 | |
-y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
|
| 4190 | |
@samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
|
| 4191 | |
The result of this test can be influenced by setting the variable
|
| 4192 | |
@code{YACC} or the cache variable @code{ac_cv_prog_YACC}.
|
| 4193 | |
@end defmac
|
| 4194 | |
|
| 4195 | |
@node Generic Programs
|
| 4196 | |
@subsection Generic Program and File Checks
|
| 4197 | |
|
| 4198 | |
These macros are used to find programs not covered by the ``particular''
|
| 4199 | |
test macros. If you need to check the behavior of a program as well as
|
| 4200 | |
find out whether it is present, you have to write your own test for it
|
| 4201 | |
(@pxref{Writing Tests}). By default, these macros use the environment
|
| 4202 | |
variable @env{PATH}. If you need to check for a program that might not
|
| 4203 | |
be in the user's @env{PATH}, you can pass a modified path to use
|
| 4204 | |
instead, like this:
|
| 4205 | |
|
| 4206 | |
@example
|
| 4207 | |
AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
|
| 4208 | |
[$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl
|
| 4209 | |
[/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc])
|
| 4210 | |
@end example
|
| 4211 | |
|
| 4212 | |
You are strongly encouraged to declare the @var{variable} passed to
|
| 4213 | |
@code{AC_CHECK_PROG} etc.@: as precious. @xref{Setting Output Variables},
|
| 4214 | |
@code{AC_ARG_VAR}, for more details.
|
| 4215 | |
|
| 4216 | |
@anchor{AC_CHECK_PROG}
|
| 4217 | |
@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @
|
| 4218 | |
@var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @
|
| 4219 | |
@ovar{reject})
|
| 4220 | |
@acindex{CHECK_PROG}
|
| 4221 | |
@caindex prog_@var{variable}
|
| 4222 | |
Check whether program @var{prog-to-check-for} exists in @var{path}. If
|
| 4223 | |
it is found, set @var{variable} to @var{value-if-found}, otherwise to
|
| 4224 | |
@var{value-if-not-found}, if given. Always pass over @var{reject} (an
|
| 4225 | |
absolute file name) even if it is the first found in the search path; in
|
| 4226 | |
that case, set @var{variable} using the absolute file name of the
|
| 4227 | |
@var{prog-to-check-for} found that is not @var{reject}. If
|
| 4228 | |
@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
|
| 4229 | |
@var{variable}. The result of this test can be overridden by setting the
|
| 4230 | |
@var{variable} variable or the cache variable
|
| 4231 | |
@code{ac_cv_prog_@var{variable}}.
|
| 4232 | |
@end defmac
|
| 4233 | |
|
| 4234 | |
@anchor{AC_CHECK_PROGS}
|
| 4235 | |
@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @
|
| 4236 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4237 | |
@acindex{CHECK_PROGS}
|
| 4238 | |
@caindex prog_@var{variable}
|
| 4239 | |
Check for each program in the blank-separated list
|
| 4240 | |
@var{progs-to-check-for} existing in the @var{path}. If one is found, set
|
| 4241 | |
@var{variable} to the name of that program. Otherwise, continue
|
| 4242 | |
checking the next program in the list. If none of the programs in the
|
| 4243 | |
list are found, set @var{variable} to @var{value-if-not-found}; if
|
| 4244 | |
@var{value-if-not-found} is not specified, the value of @var{variable}
|
| 4245 | |
is not changed. Calls @code{AC_SUBST} for @var{variable}. The result of
|
| 4246 | |
this test can be overridden by setting the @var{variable} variable or the
|
| 4247 | |
cache variable @code{ac_cv_prog_@var{variable}}.
|
| 4248 | |
@end defmac
|
| 4249 | |
|
| 4250 | |
@defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
|
| 4251 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4252 | |
@acindex{CHECK_TARGET_TOOL}
|
| 4253 | |
Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
|
| 4254 | |
with a prefix of the target type as determined by
|
| 4255 | |
@code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
|
| 4256 | |
If the tool cannot be found with a prefix, and if the build and target
|
| 4257 | |
types are equal, then it is also searched for without a prefix.
|
| 4258 | |
|
| 4259 | |
As noted in @ref{Specifying Target Triplets}, the
|
| 4260 | |
target is rarely specified, because most of the time it is the same
|
| 4261 | |
as the host: it is the type of system for which any compiler tool in
|
| 4262 | |
the package produces code. What this macro looks for is,
|
| 4263 | |
for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
|
| 4264 | |
compiler driver @r{(@command{gcc} for the GNU C Compiler)}
|
| 4265 | |
uses to produce objects, archives or executables}.
|
| 4266 | |
@end defmac
|
| 4267 | |
|
| 4268 | |
@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @
|
| 4269 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4270 | |
@acindex{CHECK_TOOL}
|
| 4271 | |
@c @caindex prog_@var{VARIABLE}
|
| 4272 | |
@c @caindex prog_ac_ct_@var{VARIABLE}
|
| 4273 | |
Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
|
| 4274 | |
with a prefix of the host type as specified by @option{--host}, followed by a
|
| 4275 | |
dash. For example, if the user runs
|
| 4276 | |
@samp{configure --build=x86_64-gnu --host=i386-gnu}, then this call:
|
| 4277 | |
@example
|
| 4278 | |
AC_CHECK_TOOL([RANLIB], [ranlib], [:])
|
| 4279 | |
@end example
|
| 4280 | |
@noindent
|
| 4281 | |
sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
|
| 4282 | |
@var{path}, or otherwise to @samp{ranlib} if that program exists in
|
| 4283 | |
@var{path}, or to @samp{:} if neither program exists.
|
| 4284 | |
|
| 4285 | |
When cross-compiling, this macro will issue a warning if no program
|
| 4286 | |
prefixed with the host type could be found.
|
| 4287 | |
For more information, see @ref{Specifying Target Triplets}.
|
| 4288 | |
@end defmac
|
| 4289 | |
|
| 4290 | |
@defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @
|
| 4291 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4292 | |
@acindex{CHECK_TARGET_TOOLS}
|
| 4293 | |
Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
|
| 4294 | |
@var{progs-to-check-for} are checked with a prefix of the target type as
|
| 4295 | |
determined by @code{AC_CANONICAL_TARGET}, followed by a dash
|
| 4296 | |
(@pxref{Canonicalizing}). If none of the tools can be found with a
|
| 4297 | |
prefix, and if the build and target types are equal, then the first one
|
| 4298 | |
without a prefix is used. If a tool is found, set @var{variable} to
|
| 4299 | |
the name of that program. If none of the tools in the list are found,
|
| 4300 | |
set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
|
| 4301 | |
is not specified, the value of @var{variable} is not changed. Calls
|
| 4302 | |
@code{AC_SUBST} for @var{variable}.
|
| 4303 | |
@end defmac
|
| 4304 | |
|
| 4305 | |
@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @
|
| 4306 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4307 | |
@acindex{CHECK_TOOLS}
|
| 4308 | |
Like @code{AC_CHECK_TOOL}, each of the tools in the list
|
| 4309 | |
@var{progs-to-check-for} are checked with a prefix of the host type as
|
| 4310 | |
determined by @code{AC_CANONICAL_HOST}, followed by a dash
|
| 4311 | |
(@pxref{Canonicalizing}). If none of the tools can be found with a
|
| 4312 | |
prefix, then the first one without a prefix is used. If a tool is found,
|
| 4313 | |
set @var{variable} to the name of that program. If none of the tools in
|
| 4314 | |
the list are found, set @var{variable} to @var{value-if-not-found}; if
|
| 4315 | |
@var{value-if-not-found} is not specified, the value of @var{variable}
|
| 4316 | |
is not changed. Calls @code{AC_SUBST} for @var{variable}.
|
| 4317 | |
|
| 4318 | |
When cross-compiling, this macro will issue a warning if no program
|
| 4319 | |
prefixed with the host type could be found.
|
| 4320 | |
For more information, see @ref{Specifying Target Triplets}.
|
| 4321 | |
@end defmac
|
| 4322 | |
|
| 4323 | |
@anchor{AC_PATH_PROG}
|
| 4324 | |
@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @
|
| 4325 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4326 | |
@acindex{PATH_PROG}
|
| 4327 | |
@caindex path_@var{variable}
|
| 4328 | |
Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
|
| 4329 | |
name of @var{prog-to-check-for} if found. The result of this test
|
| 4330 | |
can be overridden by setting the @var{variable} variable. A positive
|
| 4331 | |
result of this test is cached in the @code{ac_cv_path_@var{variable}}
|
| 4332 | |
variable.
|
| 4333 | |
@end defmac
|
| 4334 | |
|
| 4335 | |
@anchor{AC_PATH_PROGS}
|
| 4336 | |
@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @
|
| 4337 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4338 | |
@acindex{PATH_PROGS}
|
| 4339 | |
@caindex path_@var{variable}
|
| 4340 | |
Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
|
| 4341 | |
are found, set @var{variable} to the absolute name of the program
|
| 4342 | |
found. The result of this test can be overridden by setting the
|
| 4343 | |
@var{variable} variable. A positive result of this test is cached in
|
| 4344 | |
the @code{ac_cv_path_@var{variable}} variable.
|
| 4345 | |
@end defmac
|
| 4346 | |
|
| 4347 | |
@defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @
|
| 4348 | |
@var{progs-to-check-for}, @var{feature-test}, @
|
| 4349 | |
@ovar{action-if-not-found}, @dvar{path, $PATH})
|
| 4350 | |
@acindex{PATH_PROGS_FEATURE_CHECK}
|
| 4351 | |
@caindex path_@var{variable}
|
| 4352 | |
@vrindex ac_path_@var{variable}
|
| 4353 | |
@vrindex ac_path_@var{variable}_found
|
| 4354 | |
This macro was introduced in Autoconf 2.62. If @var{variable} is not
|
| 4355 | |
empty, then set the cache variable @code{ac_cv_path_@var{variable}} to
|
| 4356 | |
its value. Otherwise, check for each program in the blank-separated
|
| 4357 | |
list @var{progs-to-check-for} existing in @var{path}. For each program
|
| 4358 | |
found, execute @var{feature-test} with @code{ac_path_@var{variable}}
|
| 4359 | |
set to the absolute name of the candidate program. If no invocation of
|
| 4360 | |
@var{feature-test} sets the shell variable
|
| 4361 | |
@code{ac_cv_path_@var{variable}}, then @var{action-if-not-found} is
|
| 4362 | |
executed. @var{feature-test} will be run even when
|
| 4363 | |
@code{ac_cv_path_@var{variable}} is set, to provide the ability to
|
| 4364 | |
choose a better candidate found later in @var{path}; to accept the
|
| 4365 | |
current setting and bypass all further checks, @var{feature-test} can
|
| 4366 | |
execute @code{ac_path_@var{variable}_found=:}.
|
| 4367 | |
|
| 4368 | |
Note that this macro has some subtle differences from
|
| 4369 | |
@code{AC_CHECK_PROGS}. It is designed to be run inside
|
| 4370 | |
@code{AC_CACHE_VAL}, therefore, it should have no side effects. In
|
| 4371 | |
particular, @var{variable} is not set to the final value of
|
| 4372 | |
@code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically
|
| 4373 | |
run. Also, on failure, any action can be performed, whereas
|
| 4374 | |
@code{AC_CHECK_PROGS} only performs
|
| 4375 | |
@code{@var{variable}=@var{value-if-not-found}}.
|
| 4376 | |
|
| 4377 | |
Here is an example, similar to what Autoconf uses in its own configure
|
| 4378 | |
script. It will search for an implementation of @command{m4} that
|
| 4379 | |
supports the @code{indir} builtin, even if it goes by the name
|
| 4380 | |
@command{gm4} or is not the first implementation on @env{PATH}.
|
| 4381 | |
|
| 4382 | |
@example
|
| 4383 | |
AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4],
|
| 4384 | |
[AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4],
|
| 4385 | |
[[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4`
|
| 4386 | |
test "x$m4out" = x0 \
|
| 4387 | |
&& ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]],
|
| 4388 | |
[AC_MSG_ERROR([could not find m4 that supports indir])])])
|
| 4389 | |
AC_SUBST([M4], [$ac_cv_path_M4])
|
| 4390 | |
@end example
|
| 4391 | |
@end defmac
|
| 4392 | |
|
| 4393 | |
@defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
|
| 4394 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4395 | |
@acindex{PATH_TARGET_TOOL}
|
| 4396 | |
Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
|
| 4397 | |
name of the program if it is found.
|
| 4398 | |
@end defmac
|
| 4399 | |
|
| 4400 | |
@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @
|
| 4401 | |
@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 4402 | |
@acindex{PATH_TOOL}
|
| 4403 | |
Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
|
| 4404 | |
name of the program if it is found.
|
| 4405 | |
|
| 4406 | |
When cross-compiling, this macro will issue a warning if no program
|
| 4407 | |
prefixed with the host type could be found.
|
| 4408 | |
For more information, see @ref{Specifying Target Triplets}.
|
| 4409 | |
@end defmac
|
| 4410 | |
|
| 4411 | |
|
| 4412 | |
@node Files
|
| 4413 | |
@section Files
|
| 4414 | |
@cindex File, checking
|
| 4415 | |
|
| 4416 | |
You might also need to check for the existence of files. Before using
|
| 4417 | |
these macros, ask yourself whether a runtime test might not be a better
|
| 4418 | |
solution. Be aware that, like most Autoconf macros, they test a feature
|
| 4419 | |
of the host machine, and therefore, they die when cross-compiling.
|
| 4420 | |
|
| 4421 | |
@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @
|
| 4422 | |
@ovar{action-if-not-found})
|
| 4423 | |
@acindex{CHECK_FILE}
|
| 4424 | |
@caindex file_@var{file}
|
| 4425 | |
Check whether file @var{file} exists on the native system. If it is
|
| 4426 | |
found, execute @var{action-if-found}, otherwise do
|
| 4427 | |
@var{action-if-not-found}, if given. The result of this test is cached
|
| 4428 | |
in the @code{ac_cv_file_@var{file}} variable, with characters not
|
| 4429 | |
suitable for a variable name mapped to underscores.
|
| 4430 | |
@end defmac
|
| 4431 | |
|
| 4432 | |
@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @
|
| 4433 | |
@ovar{action-if-not-found})
|
| 4434 | |
@acindex{CHECK_FILES}
|
| 4435 | |
@caindex file_@var{file}
|
| 4436 | |
Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
|
| 4437 | |
Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
|
| 4438 | |
for each file found. The results of each test are cached in the
|
| 4439 | |
@code{ac_cv_file_@var{file}} variable, with characters not suitable for
|
| 4440 | |
a variable name mapped to underscores.
|
| 4441 | |
@end defmac
|
| 4442 | |
|
| 4443 | |
|
| 4444 | |
@node Libraries
|
| 4445 | |
@section Library Files
|
| 4446 | |
@cindex Library, checking
|
| 4447 | |
|
| 4448 | |
The following macros check for the presence of certain C, C++, Fortran,
|
| 4449 | |
or Go library archive files.
|
| 4450 | |
|
| 4451 | |
@anchor{AC_CHECK_LIB}
|
| 4452 | |
@defmac AC_CHECK_LIB (@var{library}, @var{function}, @
|
| 4453 | |
@ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
|
| 4454 | |
@acindex{CHECK_LIB}
|
| 4455 | |
@caindex lib_@var{library}_@var{function}
|
| 4456 | |
Test whether the library @var{library} is available by trying to link
|
| 4457 | |
a test program that calls function @var{function} with the library.
|
| 4458 | |
@var{function} should be a function provided by the library.
|
| 4459 | |
Use the base
|
| 4460 | |
name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
|
| 4461 | |
the @var{library} argument.
|
| 4462 | |
|
| 4463 | |
@var{action-if-found} is a list of shell commands to run if the link
|
| 4464 | |
with the library succeeds; @var{action-if-not-found} is a list of shell
|
| 4465 | |
commands to run if the link fails. If @var{action-if-found} is not
|
| 4466 | |
specified, the default action prepends @option{-l@var{library}} to
|
| 4467 | |
@code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
|
| 4468 | |
capitals). This macro is intended to support building @code{LIBS} in
|
| 4469 | |
a right-to-left (least-dependent to most-dependent) fashion such that
|
| 4470 | |
library dependencies are satisfied as a natural side effect of
|
| 4471 | |
consecutive tests. Linkers are sensitive to library ordering
|
| 4472 | |
so the order in which @code{LIBS} is generated is important to reliable
|
| 4473 | |
detection of libraries.
|
| 4474 | |
|
| 4475 | |
If linking with @var{library} results in unresolved symbols that would
|
| 4476 | |
be resolved by linking with additional libraries, give those libraries
|
| 4477 | |
as the @var{other-libraries} argument, separated by spaces:
|
| 4478 | |
e.g., @option{-lXt -lX11}. Otherwise, this macro may fail to detect
|
| 4479 | |
that @var{library} is present, because linking the test program can
|
| 4480 | |
fail with unresolved symbols. The @var{other-libraries} argument
|
| 4481 | |
should be limited to cases where it is desirable to test for one library
|
| 4482 | |
in the presence of another that is not already in @code{LIBS}.
|
| 4483 | |
|
| 4484 | |
@code{AC_CHECK_LIB} requires some care in usage, and should be avoided
|
| 4485 | |
in some common cases. Many standard functions like @code{gethostbyname}
|
| 4486 | |
appear in the standard C library on some hosts, and in special libraries
|
| 4487 | |
like @code{nsl} on other hosts. On some hosts the special libraries
|
| 4488 | |
contain variant implementations that you may not want to use. These
|
| 4489 | |
days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
|
| 4490 | |
[nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
|
| 4491 | |
|
| 4492 | |
The result of this test is cached in the
|
| 4493 | |
@code{ac_cv_lib_@var{library}_@var{function}} variable.
|
| 4494 | |
@end defmac
|
| 4495 | |
|
| 4496 | |
@anchor{AC_SEARCH_LIBS}
|
| 4497 | |
@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @
|
| 4498 | |
@ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
|
| 4499 | |
@acindex{SEARCH_LIBS}
|
| 4500 | |
@caindex search_@var{function}
|
| 4501 | |
Search for a library defining @var{function} if it's not already
|
| 4502 | |
available. This equates to calling
|
| 4503 | |
@samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
|
| 4504 | |
no libraries, then for each library listed in @var{search-libs}.
|
| 4505 | |
|
| 4506 | |
Prepend @option{-l@var{library}} to @code{LIBS} for the first library found
|
| 4507 | |
to contain @var{function}, and run @var{action-if-found}. If the
|
| 4508 | |
function is not found, run @var{action-if-not-found}.
|
| 4509 | |
|
| 4510 | |
If linking with @var{library} results in unresolved symbols that would
|
| 4511 | |
be resolved by linking with additional libraries, give those libraries
|
| 4512 | |
as the @var{other-libraries} argument, separated by spaces:
|
| 4513 | |
e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
|
| 4514 | |
that @var{function} is present, because linking the test program
|
| 4515 | |
always fails with unresolved symbols.
|
| 4516 | |
|
| 4517 | |
The result of this test is cached in the
|
| 4518 | |
@code{ac_cv_search_@var{function}} variable as @samp{none required} if
|
| 4519 | |
@var{function} is already available, as @samp{no} if no library
|
| 4520 | |
containing @var{function} was found, otherwise as the
|
| 4521 | |
@option{-l@var{library}} option that needs to be prepended to @code{LIBS}.
|
| 4522 | |
@end defmac
|
| 4523 | |
|
| 4524 | |
|
| 4525 | |
|
| 4526 | |
@node Library Functions
|
| 4527 | |
@section Library Functions
|
| 4528 | |
|
| 4529 | |
The following macros check for particular C library functions.
|
| 4530 | |
If there is no macro specifically defined to check for a function you need,
|
| 4531 | |
and you don't need to check for any special properties of
|
| 4532 | |
it, then you can use one of the general function-check macros.
|
| 4533 | |
|
| 4534 | |
@menu
|
| 4535 | |
* Function Portability:: Pitfalls with usual functions
|
| 4536 | |
* Particular Functions:: Special handling to find certain functions
|
| 4537 | |
* Generic Functions:: How to find other functions
|
| 4538 | |
@end menu
|
| 4539 | |
|
| 4540 | |
@node Function Portability
|
| 4541 | |
@subsection Portability of C Functions
|
| 4542 | |
@cindex Portability of C functions
|
| 4543 | |
@cindex C function portability
|
| 4544 | |
|
| 4545 | |
Most usual functions can either be missing, or be buggy, or be limited
|
| 4546 | |
on some architectures. This section tries to make an inventory of these
|
| 4547 | |
portability issues. By definition, this list always requires
|
| 4548 | |
additions. A much more complete list is maintained by the Gnulib
|
| 4549 | |
project (@pxref{Gnulib}), covering @ref{Function Substitutes, ,
|
| 4550 | |
Current Posix Functions, gnulib, GNU gnulib}, @ref{Legacy Function
|
| 4551 | |
Substitutes, , Legacy Functions, gnulib, GNU gnulib}, and @ref{Glibc
|
| 4552 | |
Function Substitutes, , Glibc Functions, gnulib, GNU gnulib}. Please
|
| 4553 | |
help us keep the gnulib list as complete as possible.
|
| 4554 | |
|
| 4555 | |
@table @asis
|
| 4556 | |
@item @code{exit}
|
| 4557 | |
@c @fuindex exit
|
| 4558 | |
@prindex @code{exit}
|
| 4559 | |
On ancient hosts, @code{exit} returned @code{int}.
|
| 4560 | |
This is because @code{exit} predates @code{void}, and there was a long
|
| 4561 | |
tradition of it returning @code{int}.
|
| 4562 | |
|
| 4563 | |
On current hosts, the problem more likely is that @code{exit} is not
|
| 4564 | |
declared, due to C++ problems of some sort or another. For this reason
|
| 4565 | |
we suggest that test programs not invoke @code{exit}, but return from
|
| 4566 | |
@code{main} instead.
|
| 4567 | |
|
| 4568 | |
@item @code{free}
|
| 4569 | |
@c @fuindex free
|
| 4570 | |
@prindex @code{free}
|
| 4571 | |
The C standard says a call @code{free (NULL)} does nothing, but
|
| 4572 | |
some old systems don't support this (e.g., NextStep).
|
| 4573 | |
|
| 4574 | |
@item @code{isinf}
|
| 4575 | |
@itemx @code{isnan}
|
| 4576 | |
@c @fuindex isinf
|
| 4577 | |
@c @fuindex isnan
|
| 4578 | |
@prindex @code{isinf}
|
| 4579 | |
@prindex @code{isnan}
|
| 4580 | |
The C99 standard says that @code{isinf} and @code{isnan} are
|
| 4581 | |
macros. On some systems just macros are available
|
| 4582 | |
(e.g., HP-UX and Solaris 10), on
|
| 4583 | |
some systems both macros and functions (e.g., glibc 2.3.2), and on some
|
| 4584 | |
systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
|
| 4585 | |
these functions are declared in nonstandard headers like
|
| 4586 | |
@code{<sunmath.h>} and defined in non-default libraries like
|
| 4587 | |
@option{-lm} or @option{-lsunmath}.
|
| 4588 | |
|
| 4589 | |
The C99 @code{isinf} and @code{isnan} macros work correctly with
|
| 4590 | |
@code{long double} arguments, but pre-C99 systems that use functions
|
| 4591 | |
typically assume @code{double} arguments. On such a system,
|
| 4592 | |
@code{isinf} incorrectly returns true for a finite @code{long double}
|
| 4593 | |
argument that is outside the range of @code{double}.
|
| 4594 | |
|
| 4595 | |
The best workaround for these issues is to use gnulib modules
|
| 4596 | |
@code{isinf} and @code{isnan} (@pxref{Gnulib}). But a lighter weight
|
| 4597 | |
solution involves code like the following.
|
| 4598 | |
|
| 4599 | |
@smallexample
|
| 4600 | |
#include <math.h>
|
| 4601 | |
|
| 4602 | |
#ifndef isnan
|
| 4603 | |
# define isnan(x) \
|
| 4604 | |
(sizeof (x) == sizeof (long double) ? isnan_ld (x) \
|
| 4605 | |
: sizeof (x) == sizeof (double) ? isnan_d (x) \
|
| 4606 | |
: isnan_f (x))
|
| 4607 | |
static inline int isnan_f (float x) @{ return x != x; @}
|
| 4608 | |
static inline int isnan_d (double x) @{ return x != x; @}
|
| 4609 | |
static inline int isnan_ld (long double x) @{ return x != x; @}
|
| 4610 | |
#endif
|
| 4611 | |
|
| 4612 | |
#ifndef isinf
|
| 4613 | |
# define isinf(x) \
|
| 4614 | |
(sizeof (x) == sizeof (long double) ? isinf_ld (x) \
|
| 4615 | |
: sizeof (x) == sizeof (double) ? isinf_d (x) \
|
| 4616 | |
: isinf_f (x))
|
| 4617 | |
static inline int isinf_f (float x)
|
| 4618 | |
@{ return !isnan (x) && isnan (x - x); @}
|
| 4619 | |
static inline int isinf_d (double x)
|
| 4620 | |
@{ return !isnan (x) && isnan (x - x); @}
|
| 4621 | |
static inline int isinf_ld (long double x)
|
| 4622 | |
@{ return !isnan (x) && isnan (x - x); @}
|
| 4623 | |
#endif
|
| 4624 | |
@end smallexample
|
| 4625 | |
|
| 4626 | |
Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
|
| 4627 | |
compilers that lack the @code{inline} keyword. Some optimizing
|
| 4628 | |
compilers mishandle these definitions, but systems with that bug
|
| 4629 | |
typically have many other floating point corner-case compliance problems
|
| 4630 | |
anyway, so it's probably not worth worrying about.
|
| 4631 | |
|
| 4632 | |
@item @code{malloc}
|
| 4633 | |
@c @fuindex malloc
|
| 4634 | |
@prindex @code{malloc}
|
| 4635 | |
The C standard says a call @code{malloc (0)} is implementation
|
| 4636 | |
dependent. It can return either @code{NULL} or a new non-null pointer.
|
| 4637 | |
The latter is more common (e.g., the GNU C Library) but is by
|
| 4638 | |
no means universal. @code{AC_FUNC_MALLOC}
|
| 4639 | |
can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
|
| 4640 | |
|
| 4641 | |
@item @code{putenv}
|
| 4642 | |
@c @fuindex putenv
|
| 4643 | |
@prindex @code{putenv}
|
| 4644 | |
Posix prefers @code{setenv} to @code{putenv}; among other things,
|
| 4645 | |
@code{putenv} is not required of all Posix implementations, but
|
| 4646 | |
@code{setenv} is.
|
| 4647 | |
|
| 4648 | |
Posix specifies that @code{putenv} puts the given string directly in
|
| 4649 | |
@code{environ}, but some systems make a copy of it instead (e.g.,
|
| 4650 | |
glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might
|
| 4651 | |
not free it, causing a memory leak (e.g., FreeBSD 4).
|
| 4652 | |
|
| 4653 | |
On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
|
| 4654 | |
environment, but this is not standard usage and it dumps core
|
| 4655 | |
on some systems (e.g., AIX).
|
| 4656 | |
|
| 4657 | |
On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
|
| 4658 | |
environment, rather than inserting it with an empty value.
|
| 4659 | |
|
| 4660 | |
@item @code{realloc}
|
| 4661 | |
@c @fuindex realloc
|
| 4662 | |
@prindex @code{realloc}
|
| 4663 | |
The C standard says a call @code{realloc (NULL, size)} is equivalent
|
| 4664 | |
to @code{malloc (size)}, but some old systems don't support this (e.g.,
|
| 4665 | |
NextStep).
|
| 4666 | |
|
| 4667 | |
@item @code{signal} handler
|
| 4668 | |
@c @fuindex signal
|
| 4669 | |
@prindex @code{signal}
|
| 4670 | |
@prindex @code{sigaction}
|
| 4671 | |
Normally @code{signal} takes a handler function with a return type of
|
| 4672 | |
@code{void}, but some old systems required @code{int} instead. Any
|
| 4673 | |
actual @code{int} value returned is not used; this is only a
|
| 4674 | |
difference in the function prototype demanded.
|
| 4675 | |
|
| 4676 | |
All systems we know of in current use return @code{void}. The
|
| 4677 | |
@code{int} was to support K&R C, where of course @code{void} is not
|
| 4678 | |
available. The obsolete macro @code{AC_TYPE_SIGNAL}
|
| 4679 | |
(@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in
|
| 4680 | |
all cases.
|
| 4681 | |
|
| 4682 | |
In most cases, it is more robust to use @code{sigaction} when it is
|
| 4683 | |
available, rather than @code{signal}.
|
| 4684 | |
|
| 4685 | |
@item @code{snprintf}
|
| 4686 | |
@c @fuindex snprintf
|
| 4687 | |
@prindex @code{snprintf}
|
| 4688 | |
@c @fuindex vsnprintf
|
| 4689 | |
@prindex @code{vsnprintf}
|
| 4690 | |
The C99 standard says that if the output array isn't big enough
|
| 4691 | |
and if no other errors occur, @code{snprintf} and @code{vsnprintf}
|
| 4692 | |
truncate the output and return the number of bytes that ought to have
|
| 4693 | |
been produced. Some older systems return the truncated length (e.g.,
|
| 4694 | |
GNU C Library 2.0.x or IRIX 6.5), some a negative value
|
| 4695 | |
(e.g., earlier GNU C Library versions), and some the buffer
|
| 4696 | |
length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
|
| 4697 | |
older systems ignore the length and overrun the buffer (e.g., 64-bit
|
| 4698 | |
Solaris 7).
|
| 4699 | |
|
| 4700 | |
@item @code{sprintf}
|
| 4701 | |
@c @fuindex sprintf
|
| 4702 | |
@prindex @code{sprintf}
|
| 4703 | |
@c @fuindex vsprintf
|
| 4704 | |
@prindex @code{vsprintf}
|
| 4705 | |
The C standard says @code{sprintf} and @code{vsprintf} return the
|
| 4706 | |
number of bytes written. On some ancient systems (SunOS 4 for
|
| 4707 | |
instance) they return the buffer pointer instead, but these no
|
| 4708 | |
longer need to be worried about.
|
| 4709 | |
|
| 4710 | |
@item @code{sscanf}
|
| 4711 | |
@c @fuindex sscanf
|
| 4712 | |
@prindex @code{sscanf}
|
| 4713 | |
On various old systems, e.g., HP-UX 9, @code{sscanf} requires
|
| 4714 | |
that its
|
| 4715 | |
input string be writable (though it doesn't actually change it). This
|
| 4716 | |
can be a problem when using @command{gcc} since it normally puts
|
| 4717 | |
constant strings in read-only memory (@pxref{Incompatibilities,
|
| 4718 | |
Incompatibilities of GCC, , gcc, Using and
|
| 4719 | |
Porting the GNU Compiler Collection}). Apparently in some cases even
|
| 4720 | |
having format strings read-only can be a problem.
|
| 4721 | |
|
| 4722 | |
@item @code{strerror_r}
|
| 4723 | |
@c @fuindex strerror_r
|
| 4724 | |
@prindex @code{strerror_r}
|
| 4725 | |
Posix specifies that @code{strerror_r} returns an @code{int}, but many
|
| 4726 | |
systems (e.g., GNU C Library version 2.2.4) provide a
|
| 4727 | |
different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
|
| 4728 | |
can detect which is in use (@pxref{Particular Functions}).
|
| 4729 | |
|
| 4730 | |
@item @code{strnlen}
|
| 4731 | |
@c @fuindex strnlen
|
| 4732 | |
@prindex @code{strnlen}
|
| 4733 | |
AIX 4.3 provides a broken version which produces the
|
| 4734 | |
following results:
|
| 4735 | |
|
| 4736 | |
@example
|
| 4737 | |
strnlen ("foobar", 0) = 0
|
| 4738 | |
strnlen ("foobar", 1) = 3
|
| 4739 | |
strnlen ("foobar", 2) = 2
|
| 4740 | |
strnlen ("foobar", 3) = 1
|
| 4741 | |
strnlen ("foobar", 4) = 0
|
| 4742 | |
strnlen ("foobar", 5) = 6
|
| 4743 | |
strnlen ("foobar", 6) = 6
|
| 4744 | |
strnlen ("foobar", 7) = 6
|
| 4745 | |
strnlen ("foobar", 8) = 6
|
| 4746 | |
strnlen ("foobar", 9) = 6
|
| 4747 | |
@end example
|
| 4748 | |
|
| 4749 | |
@item @code{sysconf}
|
| 4750 | |
@c @fuindex sysconf
|
| 4751 | |
@prindex @code{sysconf}
|
| 4752 | |
@code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX
|
| 4753 | |
9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
|
| 4754 | |
@code{#ifdef}.
|
| 4755 | |
|
| 4756 | |
@item @code{unlink}
|
| 4757 | |
@c @fuindex unlink
|
| 4758 | |
@prindex @code{unlink}
|
| 4759 | |
The Posix spec says that @code{unlink} causes the given file to be
|
| 4760 | |
removed only after there are no more open file handles for it. Some
|
| 4761 | |
non-Posix hosts have trouble with this requirement, though,
|
| 4762 | |
and some DOS variants even corrupt the file system.
|
| 4763 | |
|
| 4764 | |
@item @code{unsetenv}
|
| 4765 | |
@c @fuindex unsetenv
|
| 4766 | |
@prindex @code{unsetenv}
|
| 4767 | |
On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
|
| 4768 | |
can be removed with a call @code{putenv ("FOO=")}, as described under
|
| 4769 | |
@code{putenv} above.
|
| 4770 | |
|
| 4771 | |
@item @code{va_copy}
|
| 4772 | |
@c @fuindex va_copy
|
| 4773 | |
@prindex @code{va_copy}
|
| 4774 | |
The C99 standard provides @code{va_copy} for copying
|
| 4775 | |
@code{va_list} variables. It may be available in older environments
|
| 4776 | |
too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
|
| 4777 | |
pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
|
| 4778 | |
@code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
|
| 4779 | |
portability.
|
| 4780 | |
|
| 4781 | |
@item @code{va_list}
|
| 4782 | |
@c @fuindex va_list
|
| 4783 | |
@prindex @code{va_list}
|
| 4784 | |
@code{va_list} is not necessarily just a pointer. It can be a
|
| 4785 | |
@code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
|
| 4786 | |
not portable. Or it can be an array (e.g., @command{gcc} in some
|
| 4787 | |
PowerPC configurations), which means as a function parameter it can be
|
| 4788 | |
effectively call-by-reference and library routines might modify the
|
| 4789 | |
value back in the caller (e.g., @code{vsnprintf} in the GNU C Library
|
| 4790 | |
2.1).
|
| 4791 | |
|
| 4792 | |
@item Signed @code{>>}
|
| 4793 | |
Normally the C @code{>>} right shift of a signed type replicates the
|
| 4794 | |
high bit, giving a so-called ``arithmetic'' shift. But care should be
|
| 4795 | |
taken since Standard C doesn't require that behavior. On those
|
| 4796 | |
few processors without a native arithmetic shift (for instance Cray
|
| 4797 | |
vector systems) zero bits may be shifted in, the same as a shift of an
|
| 4798 | |
unsigned type.
|
| 4799 | |
|
| 4800 | |
@item Integer @code{/}
|
| 4801 | |
C divides signed integers by truncating their quotient toward zero,
|
| 4802 | |
yielding the same result as Fortran. However, before C99 the standard
|
| 4803 | |
allowed C implementations to take the floor or ceiling of the quotient
|
| 4804 | |
in some cases. Hardly any implementations took advantage of this
|
| 4805 | |
freedom, though, and it's probably not worth worrying about this issue
|
| 4806 | |
nowadays.
|
| 4807 | |
@end table
|
| 4808 | |
|
| 4809 | |
|
| 4810 | |
@node Particular Functions
|
| 4811 | |
@subsection Particular Function Checks
|
| 4812 | |
@cindex Function, checking
|
| 4813 | |
|
| 4814 | |
These macros check for particular C functions---whether they exist, and
|
| 4815 | |
in some cases how they respond when given certain arguments.
|
| 4816 | |
|
| 4817 | |
@anchor{AC_FUNC_ALLOCA}
|
| 4818 | |
@defmac AC_FUNC_ALLOCA
|
| 4819 | |
@acindex{FUNC_ALLOCA}
|
| 4820 | |
@cvindex C_ALLOCA
|
| 4821 | |
@cvindex HAVE_ALLOCA_H
|
| 4822 | |
@ovindex ALLOCA
|
| 4823 | |
@c @fuindex alloca
|
| 4824 | |
@prindex @code{alloca}
|
| 4825 | |
@hdrindex{alloca.h}
|
| 4826 | |
@c @caindex working_alloca_h
|
| 4827 | |
Check how to get @code{alloca}. Tries to get a builtin version by
|
| 4828 | |
checking for @file{alloca.h} or the predefined C preprocessor macros
|
| 4829 | |
@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
|
| 4830 | |
it defines @code{HAVE_ALLOCA_H}.
|
| 4831 | |
|
| 4832 | |
If those attempts fail, it looks for the function in the standard C
|
| 4833 | |
library. If any of those methods succeed, it defines
|
| 4834 | |
@code{HAVE_ALLOCA}. Otherwise, it sets the output variable
|
| 4835 | |
@code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
|
| 4836 | |
@code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
|
| 4837 | |
garbage collect). This variable is separate from @code{LIBOBJS} so
|
| 4838 | |
multiple programs can share the value of @code{ALLOCA} without needing
|
| 4839 | |
to create an actual library, in case only some of them use the code in
|
| 4840 | |
@code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
|
| 4841 | |
purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
|
| 4842 | |
|
| 4843 | |
This macro does not try to get @code{alloca} from the System V R3
|
| 4844 | |
@file{libPW} or the System V R4 @file{libucb} because those libraries
|
| 4845 | |
contain some incompatible functions that cause trouble. Some versions
|
| 4846 | |
do not even contain @code{alloca} or contain a buggy version. If you
|
| 4847 | |
still want to use their @code{alloca}, use @code{ar} to extract
|
| 4848 | |
@file{alloca.o} from them instead of compiling @file{alloca.c}.
|
| 4849 | |
|
| 4850 | |
Source files that use @code{alloca} should start with a piece of code
|
| 4851 | |
like the following, to declare it properly.
|
| 4852 | |
|
| 4853 | |
@example
|
| 4854 | |
@group
|
| 4855 | |
#ifdef STDC_HEADERS
|
| 4856 | |
# include <stdlib.h>
|
| 4857 | |
# include <stddef.h>
|
| 4858 | |
#else
|
| 4859 | |
# ifdef HAVE_STDLIB_H
|
| 4860 | |
# include <stdlib.h>
|
| 4861 | |
# endif
|
| 4862 | |
#endif
|
| 4863 | |
#ifdef HAVE_ALLOCA_H
|
| 4864 | |
# include <alloca.h>
|
| 4865 | |
#elif !defined alloca
|
| 4866 | |
# ifdef __GNUC__
|
| 4867 | |
# define alloca __builtin_alloca
|
| 4868 | |
# elif defined _AIX
|
| 4869 | |
# define alloca __alloca
|
| 4870 | |
# elif defined _MSC_VER
|
| 4871 | |
# include <malloc.h>
|
| 4872 | |
# define alloca _alloca
|
| 4873 | |
# elif !defined HAVE_ALLOCA
|
| 4874 | |
# ifdef __cplusplus
|
| 4875 | |
extern "C"
|
| 4876 | |
# endif
|
| 4877 | |
void *alloca (size_t);
|
| 4878 | |
# endif
|
| 4879 | |
#endif
|
| 4880 | |
@end group
|
| 4881 | |
@end example
|
| 4882 | |
@end defmac
|
| 4883 | |
|
| 4884 | |
@defmac AC_FUNC_CHOWN
|
| 4885 | |
@acindex{FUNC_CHOWN}
|
| 4886 | |
@cvindex HAVE_CHOWN
|
| 4887 | |
@c @fuindex chown
|
| 4888 | |
@prindex @code{chown}
|
| 4889 | |
@caindex func_chown_works
|
| 4890 | |
If the @code{chown} function is available and works (in particular, it
|
| 4891 | |
should accept @option{-1} for @code{uid} and @code{gid}), define
|
| 4892 | |
@code{HAVE_CHOWN}. The result of this macro is cached in the
|
| 4893 | |
@code{ac_cv_func_chown_works} variable.
|
| 4894 | |
@end defmac
|
| 4895 | |
|
| 4896 | |
@anchor{AC_FUNC_CLOSEDIR_VOID}
|
| 4897 | |
@defmac AC_FUNC_CLOSEDIR_VOID
|
| 4898 | |
@acindex{FUNC_CLOSEDIR_VOID}
|
| 4899 | |
@cvindex CLOSEDIR_VOID
|
| 4900 | |
@c @fuindex closedir
|
| 4901 | |
@prindex @code{closedir}
|
| 4902 | |
@caindex func_closedir_void
|
| 4903 | |
If the @code{closedir} function does not return a meaningful value,
|
| 4904 | |
define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
|
| 4905 | |
return value for an error indicator.
|
| 4906 | |
|
| 4907 | |
Currently this test is implemented by running a test program. When
|
| 4908 | |
cross compiling the pessimistic assumption that @code{closedir} does not
|
| 4909 | |
return a meaningful value is made.
|
| 4910 | |
|
| 4911 | |
The result of this macro is cached in the @code{ac_cv_func_closedir_void}
|
| 4912 | |
variable.
|
| 4913 | |
|
| 4914 | |
This macro is obsolescent, as @code{closedir} returns a meaningful value
|
| 4915 | |
on current systems. New programs need not use this macro.
|
| 4916 | |
@end defmac
|
| 4917 | |
|
| 4918 | |
@defmac AC_FUNC_ERROR_AT_LINE
|
| 4919 | |
@acindex{FUNC_ERROR_AT_LINE}
|
| 4920 | |
@c @fuindex error_at_line
|
| 4921 | |
@prindex @code{error_at_line}
|
| 4922 | |
@caindex lib_error_at_line
|
| 4923 | |
If the @code{error_at_line} function is not found, require an
|
| 4924 | |
@code{AC_LIBOBJ} replacement of @samp{error}.
|
| 4925 | |
|
| 4926 | |
The result of this macro is cached in the @code{ac_cv_lib_error_at_line}
|
| 4927 | |
variable.
|
| 4928 | |
|
| 4929 | |
The @code{AC_FUNC_ERROR_AT_LINE} macro is obsolescent. New programs
|
| 4930 | |
should use Gnulib's @code{error} module. @xref{Gnulib}.
|
| 4931 | |
@end defmac
|
| 4932 | |
|
| 4933 | |
@defmac AC_FUNC_FNMATCH
|
| 4934 | |
@acindex{FUNC_FNMATCH}
|
| 4935 | |
@c @fuindex fnmatch
|
| 4936 | |
@prindex @code{fnmatch}
|
| 4937 | |
@caindex func_fnmatch_works
|
| 4938 | |
If the @code{fnmatch} function conforms to Posix, define
|
| 4939 | |
@code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
|
| 4940 | |
the bugs in Solaris 2.4.
|
| 4941 | |
|
| 4942 | |
Unlike the other specific
|
| 4943 | |
@code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
|
| 4944 | |
broken/missing @code{fnmatch}. This is for historical reasons.
|
| 4945 | |
See @code{AC_REPLACE_FNMATCH} below.
|
| 4946 | |
|
| 4947 | |
The result of this macro is cached in the @code{ac_cv_func_fnmatch_works}
|
| 4948 | |
variable.
|
| 4949 | |
|
| 4950 | |
This macro is obsolescent. New programs should use Gnulib's
|
| 4951 | |
@code{fnmatch-posix} module. @xref{Gnulib}.
|
| 4952 | |
@end defmac
|
| 4953 | |
|
| 4954 | |
@defmac AC_FUNC_FNMATCH_GNU
|
| 4955 | |
@acindex{FUNC_FNMATCH_GNU}
|
| 4956 | |
@c @fuindex fnmatch
|
| 4957 | |
@prindex @code{fnmatch}
|
| 4958 | |
@caindex func_fnmatch_gnu
|
| 4959 | |
Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
|
| 4960 | |
whether @code{fnmatch} supports GNU extensions. Detect common
|
| 4961 | |
implementation bugs, for example, the bugs in the GNU C
|
| 4962 | |
Library 2.1.
|
| 4963 | |
|
| 4964 | |
The result of this macro is cached in the @code{ac_cv_func_fnmatch_gnu}
|
| 4965 | |
variable.
|
| 4966 | |
|
| 4967 | |
This macro is obsolescent. New programs should use Gnulib's
|
| 4968 | |
@code{fnmatch-gnu} module. @xref{Gnulib}.
|
| 4969 | |
@end defmac
|
| 4970 | |
|
| 4971 | |
@anchor{AC_FUNC_FORK}
|
| 4972 | |
@defmac AC_FUNC_FORK
|
| 4973 | |
@acindex{FUNC_FORK}
|
| 4974 | |
@cvindex HAVE_VFORK_H
|
| 4975 | |
@cvindex HAVE_WORKING_FORK
|
| 4976 | |
@cvindex HAVE_WORKING_VFORK
|
| 4977 | |
@cvindex vfork
|
| 4978 | |
@c @fuindex fork
|
| 4979 | |
@prindex @code{fork}
|
| 4980 | |
@c @fuindex vfork
|
| 4981 | |
@prindex @code{vfork}
|
| 4982 | |
@hdrindex{vfork.h}
|
| 4983 | |
@c @caindex func_fork
|
| 4984 | |
@c @caindex func_fork_works
|
| 4985 | |
This macro checks for the @code{fork} and @code{vfork} functions. If a
|
| 4986 | |
working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
|
| 4987 | |
checks whether @code{fork} is just a stub by trying to run it.
|
| 4988 | |
|
| 4989 | |
If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
|
| 4990 | |
@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
|
| 4991 | |
define @code{vfork} to be @code{fork} for backward compatibility with
|
| 4992 | |
previous versions of @command{autoconf}. This macro checks for several known
|
| 4993 | |
errors in implementations of @code{vfork} and considers the system to not
|
| 4994 | |
have a working @code{vfork} if it detects any of them. It is not considered
|
| 4995 | |
to be an implementation error if a child's invocation of @code{signal}
|
| 4996 | |
modifies the parent's signal handler, since child processes rarely change
|
| 4997 | |
their signal handlers.
|
| 4998 | |
|
| 4999 | |
Since this macro defines @code{vfork} only for backward compatibility with
|
| 5000 | |
previous versions of @command{autoconf} you're encouraged to define it
|
| 5001 | |
yourself in new code:
|
| 5002 | |
@example
|
| 5003 | |
@group
|
| 5004 | |
#ifndef HAVE_WORKING_VFORK
|
| 5005 | |
# define vfork fork
|
| 5006 | |
#endif
|
| 5007 | |
@end group
|
| 5008 | |
@end example
|
| 5009 | |
|
| 5010 | |
The results of this macro are cached in the @code{ac_cv_func_fork_works}
|
| 5011 | |
and @code{ac_cv_func_vfork_works} variables. In order to override the
|
| 5012 | |
test, you also need to set the @code{ac_cv_func_fork} and
|
| 5013 | |
@code{ac_cv_func_vfork} variables.
|
| 5014 | |
@end defmac
|
| 5015 | |
|
| 5016 | |
@defmac AC_FUNC_FSEEKO
|
| 5017 | |
@acindex{FUNC_FSEEKO}
|
| 5018 | |
@cvindex _LARGEFILE_SOURCE
|
| 5019 | |
@cvindex HAVE_FSEEKO
|
| 5020 | |
@c @fuindex fseeko
|
| 5021 | |
@prindex @code{fseeko}
|
| 5022 | |
@c @fuindex ftello
|
| 5023 | |
@prindex @code{ftello}
|
| 5024 | |
@c @caindex sys_largefile_source
|
| 5025 | |
If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
|
| 5026 | |
Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
|
| 5027 | |
visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
|
| 5028 | |
may occur when compiling with @code{AC_SYS_LARGEFILE} on
|
| 5029 | |
largefile-sensitive systems where @code{off_t} does not default to a
|
| 5030 | |
64bit entity. All systems with @code{fseeko} also supply @code{ftello}.
|
| 5031 | |
@end defmac
|
| 5032 | |
|
| 5033 | |
@defmac AC_FUNC_GETGROUPS
|
| 5034 | |
@acindex{FUNC_GETGROUPS}
|
| 5035 | |
@cvindex HAVE_GETGROUPS
|
| 5036 | |
@ovindex GETGROUPS_LIBS
|
| 5037 | |
@c @fuindex getgroups
|
| 5038 | |
@prindex @code{getgroups}
|
| 5039 | |
@caindex func_getgroups_works
|
| 5040 | |
If the @code{getgroups} function is available and works (unlike on
|
| 5041 | |
Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
|
| 5042 | |
@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
|
| 5043 | |
needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
|
| 5044 | |
@end defmac
|
| 5045 | |
|
| 5046 | |
@anchor{AC_FUNC_GETLOADAVG}
|
| 5047 | |
@defmac AC_FUNC_GETLOADAVG
|
| 5048 | |
@acindex{FUNC_GETLOADAVG}
|
| 5049 | |
@cvindex SVR4
|
| 5050 | |
@cvindex DGUX
|
| 5051 | |
@cvindex UMAX
|
| 5052 | |
@cvindex UMAX4_3
|
| 5053 | |
@cvindex HAVE_NLIST_H
|
| 5054 | |
@cvindex NLIST_NAME_UNION
|
| 5055 | |
@cvindex GETLOADAVG_PRIVILEGED
|
| 5056 | |
@cvindex NEED_SETGID
|
| 5057 | |
@cvindex C_GETLOADAVG
|
| 5058 | |
@ovindex LIBOBJS
|
| 5059 | |
@ovindex NEED_SETGID
|
| 5060 | |
@ovindex KMEM_GROUP
|
| 5061 | |
@ovindex GETLOADAVG_LIBS
|
| 5062 | |
@c @fuindex getloadavg
|
| 5063 | |
@prindex @code{getloadavg}
|
| 5064 | |
Check how to get the system load averages. To perform its tests
|
| 5065 | |
properly, this macro needs the file @file{getloadavg.c}; therefore, be
|
| 5066 | |
sure to set the @code{AC_LIBOBJ} replacement directory properly (see
|
| 5067 | |
@ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
|
| 5068 | |
|
| 5069 | |
If the system has the @code{getloadavg} function, define
|
| 5070 | |
@code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
|
| 5071 | |
necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
|
| 5072 | |
@code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
|
| 5073 | |
@samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
|
| 5074 | |
possibly define several other C preprocessor macros and output
|
| 5075 | |
variables:
|
| 5076 | |
|
| 5077 | |
@enumerate
|
| 5078 | |
@item
|
| 5079 | |
Define @code{C_GETLOADAVG}.
|
| 5080 | |
|
| 5081 | |
@item
|
| 5082 | |
Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
|
| 5083 | |
those systems.
|
| 5084 | |
|
| 5085 | |
@item
|
| 5086 | |
@hdrindex{nlist.h}
|
| 5087 | |
If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
|
| 5088 | |
|
| 5089 | |
@item
|
| 5090 | |
If @samp{struct nlist} has an @samp{n_un.n_name} member, define
|
| 5091 | |
@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
|
| 5092 | |
@code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
|
| 5093 | |
|
| 5094 | |
@item
|
| 5095 | |
Programs may need to be installed set-group-ID (or set-user-ID) for
|
| 5096 | |
@code{getloadavg} to work. In this case, define
|
| 5097 | |
@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
|
| 5098 | |
to @samp{true} (and otherwise to @samp{false}), and set
|
| 5099 | |
@code{KMEM_GROUP} to the name of the group that should own the installed
|
| 5100 | |
program.
|
| 5101 | |
@end enumerate
|
| 5102 | |
|
| 5103 | |
The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
|
| 5104 | |
use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
|
| 5105 | |
@end defmac
|
| 5106 | |
|
| 5107 | |
@anchor{AC_FUNC_GETMNTENT}
|
| 5108 | |
@defmac AC_FUNC_GETMNTENT
|
| 5109 | |
@acindex{FUNC_GETMNTENT}
|
| 5110 | |
@cvindex HAVE_GETMNTENT
|
| 5111 | |
@c @fuindex getmntent
|
| 5112 | |
@prindex @code{getmntent}
|
| 5113 | |
@caindex search_getmntent
|
| 5114 | |
Check for @code{getmntent} in the standard C library, and then in the
|
| 5115 | |
@file{sun}, @file{seq}, and @file{gen} libraries, for UNICOS,
|
| 5116 | |
IRIX 4, PTX, and UnixWare, respectively. Then, if
|
| 5117 | |
@code{getmntent} is available, define @code{HAVE_GETMNTENT} and set
|
| 5118 | |
@code{ac_cv_func_getmntent} to @code{yes}. Otherwise set
|
| 5119 | |
@code{ac_cv_func_getmntent} to @code{no}.
|
| 5120 | |
|
| 5121 | |
The result of this macro can be overridden by setting the cache variable
|
| 5122 | |
@code{ac_cv_search_getmntent}.
|
| 5123 | |
@end defmac
|
| 5124 | |
|
| 5125 | |
@defmac AC_FUNC_GETPGRP
|
| 5126 | |
@acindex{FUNC_GETPGRP}
|
| 5127 | |
@cvindex GETPGRP_VOID
|
| 5128 | |
@c @fuindex getpgid
|
| 5129 | |
@c @fuindex getpgrp
|
| 5130 | |
@prindex @code{getpgid}
|
| 5131 | |
@prindex @code{getpgrp}
|
| 5132 | |
@caindex func_getpgrp_void
|
| 5133 | |
Define @code{GETPGRP_VOID} if it is an error to pass 0 to
|
| 5134 | |
@code{getpgrp}; this is the Posix behavior. On older BSD
|
| 5135 | |
systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
|
| 5136 | |
behaves like Posix's @code{getpgid}.
|
| 5137 | |
|
| 5138 | |
@example
|
| 5139 | |
#ifdef GETPGRP_VOID
|
| 5140 | |
pid = getpgrp ();
|
| 5141 | |
#else
|
| 5142 | |
pid = getpgrp (0);
|
| 5143 | |
#endif
|
| 5144 | |
@end example
|
| 5145 | |
|
| 5146 | |
This macro does not check whether
|
| 5147 | |
@code{getpgrp} exists at all; if you need to work in that situation,
|
| 5148 | |
first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
|
| 5149 | |
|
| 5150 | |
The result of this macro is cached in the @code{ac_cv_func_getpgrp_void}
|
| 5151 | |
variable.
|
| 5152 | |
|
| 5153 | |
This macro is obsolescent, as current systems have a @code{getpgrp}
|
| 5154 | |
whose signature conforms to Posix. New programs need not use this macro.
|
| 5155 | |
@end defmac
|
| 5156 | |
|
| 5157 | |
@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
|
| 5158 | |
@acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
|
| 5159 | |
@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
|
| 5160 | |
@c @fuindex lstat
|
| 5161 | |
@prindex @code{lstat}
|
| 5162 | |
@caindex func_lstat_dereferences_slashed_symlink
|
| 5163 | |
If @file{link} is a symbolic link, then @code{lstat} should treat
|
| 5164 | |
@file{link/} the same as @file{link/.}. However, many older
|
| 5165 | |
@code{lstat} implementations incorrectly ignore trailing slashes.
|
| 5166 | |
|
| 5167 | |
It is safe to assume that if @code{lstat} incorrectly ignores
|
| 5168 | |
trailing slashes, then other symbolic-link-aware functions like
|
| 5169 | |
@code{unlink} also incorrectly ignore trailing slashes.
|
| 5170 | |
|
| 5171 | |
If @code{lstat} behaves properly, define
|
| 5172 | |
@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
|
| 5173 | |
@code{AC_LIBOBJ} replacement of @code{lstat}.
|
| 5174 | |
|
| 5175 | |
The result of this macro is cached in the
|
| 5176 | |
@code{ac_cv_func_lstat_dereferences_slashed_symlink} variable.
|
| 5177 | |
|
| 5178 | |
The @code{AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} macro is obsolescent.
|
| 5179 | |
New programs should use Gnulib's @code{lstat} module. @xref{Gnulib}.
|
| 5180 | |
@end defmac
|
| 5181 | |
|
| 5182 | |
@defmac AC_FUNC_MALLOC
|
| 5183 | |
@acindex{FUNC_MALLOC}
|
| 5184 | |
@cvindex HAVE_MALLOC
|
| 5185 | |
@cvindex malloc
|
| 5186 | |
@c @fuindex malloc
|
| 5187 | |
@prindex @code{malloc}
|
| 5188 | |
@caindex func_malloc_0_nonnull
|
| 5189 | |
If the @code{malloc} function is compatible with the GNU C
|
| 5190 | |
library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
|
| 5191 | |
pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
|
| 5192 | |
@code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
|
| 5193 | |
@samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
|
| 5194 | |
native @code{malloc} is not used in the main project.
|
| 5195 | |
|
| 5196 | |
Typically, the replacement file @file{malloc.c} should look like (note
|
| 5197 | |
the @samp{#undef malloc}):
|
| 5198 | |
|
| 5199 | |
@verbatim
|
| 5200 | |
#include <config.h>
|
| 5201 | |
#undef malloc
|
| 5202 | |
|
| 5203 | |
#include <sys/types.h>
|
| 5204 | |
|
| 5205 | |
void *malloc ();
|
| 5206 | |
|
| 5207 | |
/* Allocate an N-byte block of memory from the heap.
|
| 5208 | |
If N is zero, allocate a 1-byte block. */
|
| 5209 | |
|
| 5210 | |
void *
|
| 5211 | |
rpl_malloc (size_t n)
|
| 5212 | |
{
|
| 5213 | |
if (n == 0)
|
| 5214 | |
n = 1;
|
| 5215 | |
return malloc (n);
|
| 5216 | |
}
|
| 5217 | |
@end verbatim
|
| 5218 | |
|
| 5219 | |
The result of this macro is cached in the
|
| 5220 | |
@code{ac_cv_func_malloc_0_nonnull} variable.
|
| 5221 | |
@end defmac
|
| 5222 | |
|
| 5223 | |
@defmac AC_FUNC_MBRTOWC
|
| 5224 | |
@acindex{FUNC_MBRTOWC}
|
| 5225 | |
@cvindex HAVE_MBRTOWC
|
| 5226 | |
@c @fuindex mbrtowc
|
| 5227 | |
@prindex @code{mbrtowc}
|
| 5228 | |
@caindex func_mbrtowc
|
| 5229 | |
Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
|
| 5230 | |
type @code{mbstate_t} are properly declared.
|
| 5231 | |
|
| 5232 | |
The result of this macro is cached in the @code{ac_cv_func_mbrtowc}
|
| 5233 | |
variable.
|
| 5234 | |
@end defmac
|
| 5235 | |
|
| 5236 | |
@defmac AC_FUNC_MEMCMP
|
| 5237 | |
@acindex{FUNC_MEMCMP}
|
| 5238 | |
@ovindex LIBOBJS
|
| 5239 | |
@c @fuindex memcmp
|
| 5240 | |
@prindex @code{memcmp}
|
| 5241 | |
@caindex func_memcmp_working
|
| 5242 | |
If the @code{memcmp} function is not available, or does not work on
|
| 5243 | |
8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
|
| 5244 | |
bytes or more and with at least one buffer not starting on a 4-byte
|
| 5245 | |
boundary (such as the one on NeXT x86 OpenStep), require an
|
| 5246 | |
@code{AC_LIBOBJ} replacement for @samp{memcmp}.
|
| 5247 | |
|
| 5248 | |
The result of this macro is cached in the
|
| 5249 | |
@code{ac_cv_func_memcmp_working} variable.
|
| 5250 | |
|
| 5251 | |
This macro is obsolescent, as current systems have a working
|
| 5252 | |
@code{memcmp}. New programs need not use this macro.
|
| 5253 | |
@end defmac
|
| 5254 | |
|
| 5255 | |
@defmac AC_FUNC_MKTIME
|
| 5256 | |
@acindex{FUNC_MKTIME}
|
| 5257 | |
@ovindex LIBOBJS
|
| 5258 | |
@c @fuindex mktime
|
| 5259 | |
@prindex @code{mktime}
|
| 5260 | |
@caindex func_working_mktime
|
| 5261 | |
If the @code{mktime} function is not available, or does not work
|
| 5262 | |
correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
|
| 5263 | |
For the purposes of this test, @code{mktime} should conform to the
|
| 5264 | |
Posix standard and should be the inverse of
|
| 5265 | |
@code{localtime}.
|
| 5266 | |
|
| 5267 | |
The result of this macro is cached in the
|
| 5268 | |
@code{ac_cv_func_working_mktime} variable.
|
| 5269 | |
|
| 5270 | |
The @code{AC_FUNC_MKTIME} macro is obsolescent. New programs should
|
| 5271 | |
use Gnulib's @code{mktime} module. @xref{Gnulib}.
|
| 5272 | |
@end defmac
|
| 5273 | |
|
| 5274 | |
@anchor{AC_FUNC_MMAP}
|
| 5275 | |
@defmac AC_FUNC_MMAP
|
| 5276 | |
@acindex{FUNC_MMAP}
|
| 5277 | |
@cvindex HAVE_MMAP
|
| 5278 | |
@c @fuindex mmap
|
| 5279 | |
@prindex @code{mmap}
|
| 5280 | |
@caindex func_mmap_fixed_mapped
|
| 5281 | |
If the @code{mmap} function exists and works correctly, define
|
| 5282 | |
@code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
|
| 5283 | |
memory.
|
| 5284 | |
|
| 5285 | |
The result of this macro is cached in the
|
| 5286 | |
@code{ac_cv_func_mmap_fixed_mapped} variable.
|
| 5287 | |
@end defmac
|
| 5288 | |
|
| 5289 | |
@defmac AC_FUNC_OBSTACK
|
| 5290 | |
@acindex{FUNC_OBSTACK}
|
| 5291 | |
@cvindex HAVE_OBSTACK
|
| 5292 | |
@cindex obstack
|
| 5293 | |
@caindex func_obstack
|
| 5294 | |
If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
|
| 5295 | |
@code{AC_LIBOBJ} replacement for @samp{obstack}.
|
| 5296 | |
|
| 5297 | |
The result of this macro is cached in the @code{ac_cv_func_obstack}
|
| 5298 | |
variable.
|
| 5299 | |
@end defmac
|
| 5300 | |
|
| 5301 | |
@defmac AC_FUNC_REALLOC
|
| 5302 | |
@acindex{FUNC_REALLOC}
|
| 5303 | |
@cvindex HAVE_REALLOC
|
| 5304 | |
@cvindex realloc
|
| 5305 | |
@c @fuindex realloc
|
| 5306 | |
@prindex @code{realloc}
|
| 5307 | |
@caindex func_realloc_0_nonnull
|
| 5308 | |
If the @code{realloc} function is compatible with the GNU C
|
| 5309 | |
library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
|
| 5310 | |
valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
|
| 5311 | |
@code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
|
| 5312 | |
@samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
|
| 5313 | |
the native @code{realloc} is not used in the main project. See
|
| 5314 | |
@code{AC_FUNC_MALLOC} for details.
|
| 5315 | |
|
| 5316 | |
The result of this macro is cached in the
|
| 5317 | |
@code{ac_cv_func_realloc_0_nonnull} variable.
|
| 5318 | |
@end defmac
|
| 5319 | |
|
| 5320 | |
@defmac AC_FUNC_SELECT_ARGTYPES
|
| 5321 | |
@acindex{FUNC_SELECT_ARGTYPES}
|
| 5322 | |
@cvindex SELECT_TYPE_ARG1
|
| 5323 | |
@cvindex SELECT_TYPE_ARG234
|
| 5324 | |
@cvindex SELECT_TYPE_ARG5
|
| 5325 | |
@c @fuindex select
|
| 5326 | |
@prindex @code{select}
|
| 5327 | |
@c @caindex func_select_args
|
| 5328 | |
Determines the correct type to be passed for each of the
|
| 5329 | |
@code{select} function's arguments, and defines those types
|
| 5330 | |
in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
|
| 5331 | |
@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
|
| 5332 | |
to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
|
| 5333 | |
and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
|
| 5334 | |
|
| 5335 | |
This macro is obsolescent, as current systems have a @code{select} whose
|
| 5336 | |
signature conforms to Posix. New programs need not use this macro.
|
| 5337 | |
@end defmac
|
| 5338 | |
|
| 5339 | |
@defmac AC_FUNC_SETPGRP
|
| 5340 | |
@acindex{FUNC_SETPGRP}
|
| 5341 | |
@cvindex SETPGRP_VOID
|
| 5342 | |
@c @fuindex setpgrp
|
| 5343 | |
@prindex @code{setpgrp}
|
| 5344 | |
@caindex func_setpgrp_void
|
| 5345 | |
If @code{setpgrp} takes no argument (the Posix version), define
|
| 5346 | |
@code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes
|
| 5347 | |
two process IDs as arguments. This macro does not check whether
|
| 5348 | |
@code{setpgrp} exists at all; if you need to work in that situation,
|
| 5349 | |
first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
|
| 5350 | |
|
| 5351 | |
The result of this macro is cached in the @code{ac_cv_func_setpgrp_void}
|
| 5352 | |
variable.
|
| 5353 | |
|
| 5354 | |
This macro is obsolescent, as current systems have a @code{setpgrp}
|
| 5355 | |
whose signature conforms to Posix. New programs need not use this macro.
|
| 5356 | |
@end defmac
|
| 5357 | |
|
| 5358 | |
@defmac AC_FUNC_STAT
|
| 5359 | |
@defmacx AC_FUNC_LSTAT
|
| 5360 | |
@acindex{FUNC_STAT}
|
| 5361 | |
@acindex{FUNC_LSTAT}
|
| 5362 | |
@cvindex HAVE_STAT_EMPTY_STRING_BUG
|
| 5363 | |
@cvindex HAVE_LSTAT_EMPTY_STRING_BUG
|
| 5364 | |
@c @fuindex stat
|
| 5365 | |
@prindex @code{stat}
|
| 5366 | |
@c @fuindex lstat
|
| 5367 | |
@prindex @code{lstat}
|
| 5368 | |
@caindex func_stat_empty_string_bug
|
| 5369 | |
@caindex func_lstat_empty_string_bug
|
| 5370 | |
Determine whether @code{stat} or @code{lstat} have the bug that it
|
| 5371 | |
succeeds when given the zero-length file name as argument. The @code{stat}
|
| 5372 | |
and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
|
| 5373 | |
this.
|
| 5374 | |
|
| 5375 | |
If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
|
| 5376 | |
@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
|
| 5377 | |
replacement of it.
|
| 5378 | |
|
| 5379 | |
The results of these macros are cached in the
|
| 5380 | |
@code{ac_cv_func_stat_empty_string_bug} and the
|
| 5381 | |
@code{ac_cv_func_lstat_empty_string_bug} variables, respectively.
|
| 5382 | |
|
| 5383 | |
These macros are obsolescent, as no current systems have the bug.
|
| 5384 | |
New programs need not use these macros.
|
| 5385 | |
@end defmac
|
| 5386 | |
|
| 5387 | |
@anchor{AC_FUNC_STRCOLL}
|
| 5388 | |
@defmac AC_FUNC_STRCOLL
|
| 5389 | |
@acindex{FUNC_STRCOLL}
|
| 5390 | |
@cvindex HAVE_STRCOLL
|
| 5391 | |
@c @fuindex strcoll
|
| 5392 | |
@prindex @code{strcoll}
|
| 5393 | |
@caindex func_strcoll_works
|
| 5394 | |
If the @code{strcoll} function exists and works correctly, define
|
| 5395 | |
@code{HAVE_STRCOLL}. This does a bit more than
|
| 5396 | |
@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
|
| 5397 | |
definitions of @code{strcoll} that should not be used.
|
| 5398 | |
|
| 5399 | |
The result of this macro is cached in the @code{ac_cv_func_strcoll_works}
|
| 5400 | |
variable.
|
| 5401 | |
@end defmac
|
| 5402 | |
|
| 5403 | |
@defmac AC_FUNC_STRERROR_R
|
| 5404 | |
@acindex{FUNC_STRERROR_R}
|
| 5405 | |
@cvindex HAVE_STRERROR_R
|
| 5406 | |
@cvindex HAVE_DECL_STRERROR_R
|
| 5407 | |
@cvindex STRERROR_R_CHAR_P
|
| 5408 | |
@c @fuindex strerror_r
|
| 5409 | |
@caindex func_strerror_r_char_p
|
| 5410 | |
@prindex @code{strerror_r}
|
| 5411 | |
If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
|
| 5412 | |
it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
|
| 5413 | |
@code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
|
| 5414 | |
returns an @code{int} error number. The Thread-Safe Functions option of
|
| 5415 | |
Posix requires @code{strerror_r} to return @code{int}, but
|
| 5416 | |
many systems (including, for example, version 2.2.4 of the GNU C
|
| 5417 | |
Library) return a @code{char *} value that is not necessarily equal to
|
| 5418 | |
the buffer argument.
|
| 5419 | |
|
| 5420 | |
The result of this macro is cached in the
|
| 5421 | |
@code{ac_cv_func_strerror_r_char_p} variable.
|
| 5422 | |
@end defmac
|
| 5423 | |
|
| 5424 | |
@anchor{AC_FUNC_STRFTIME}
|
| 5425 | |
@defmac AC_FUNC_STRFTIME
|
| 5426 | |
@acindex{FUNC_STRFTIME}
|
| 5427 | |
@cvindex HAVE_STRFTIME
|
| 5428 | |
@c @fuindex strftime
|
| 5429 | |
@prindex @code{strftime}
|
| 5430 | |
Check for @code{strftime} in the @file{intl} library, for SCO Unix.
|
| 5431 | |
Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
|
| 5432 | |
|
| 5433 | |
This macro is obsolescent, as no current systems require the @file{intl}
|
| 5434 | |
library for @code{strftime}. New programs need not use this macro.
|
| 5435 | |
@end defmac
|
| 5436 | |
|
| 5437 | |
@defmac AC_FUNC_STRTOD
|
| 5438 | |
@acindex{FUNC_STRTOD}
|
| 5439 | |
@ovindex POW_LIB
|
| 5440 | |
@c @fuindex strtod
|
| 5441 | |
@prindex @code{strtod}
|
| 5442 | |
@caindex func_strtod
|
| 5443 | |
@caindex func_pow
|
| 5444 | |
If the @code{strtod} function does not exist or doesn't work correctly,
|
| 5445 | |
ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
|
| 5446 | |
because @file{strtod.c} is likely to need @samp{pow}, set the output
|
| 5447 | |
variable @code{POW_LIB} to the extra library needed.
|
| 5448 | |
|
| 5449 | |
This macro caches its result in the @code{ac_cv_func_strtod} variable
|
| 5450 | |
and depends upon the result in the @code{ac_cv_func_pow} variable.
|
| 5451 | |
|
| 5452 | |
The @code{AC_FUNC_STRTOD} macro is obsolescent. New programs should
|
| 5453 | |
use Gnulib's @code{strtod} module. @xref{Gnulib}.
|
| 5454 | |
@end defmac
|
| 5455 | |
|
| 5456 | |
@defmac AC_FUNC_STRTOLD
|
| 5457 | |
@acindex{FUNC_STRTOLD}
|
| 5458 | |
@cvindex HAVE_STRTOLD
|
| 5459 | |
@prindex @code{strtold}
|
| 5460 | |
@caindex func_strtold
|
| 5461 | |
If the @code{strtold} function exists and conforms to C99, define
|
| 5462 | |
@code{HAVE_STRTOLD}.
|
| 5463 | |
|
| 5464 | |
This macro caches its result in the @code{ac_cv_func_strtold} variable.
|
| 5465 | |
@end defmac
|
| 5466 | |
|
| 5467 | |
@defmac AC_FUNC_STRNLEN
|
| 5468 | |
@acindex{FUNC_STRNLEN}
|
| 5469 | |
@cvindex HAVE_STRNLEN
|
| 5470 | |
@c @fuindex strnlen
|
| 5471 | |
@prindex @code{strnlen}
|
| 5472 | |
@caindex func_strnlen_working
|
| 5473 | |
If the @code{strnlen} function is not available, or is buggy (like the one
|
| 5474 | |
from AIX 4.3), require an @code{AC_LIBOBJ} replacement for it.
|
| 5475 | |
|
| 5476 | |
This macro caches its result in the @code{ac_cv_func_strnlen_working}
|
| 5477 | |
variable.
|
| 5478 | |
@end defmac
|
| 5479 | |
|
| 5480 | |
@anchor{AC_FUNC_UTIME_NULL}
|
| 5481 | |
@defmac AC_FUNC_UTIME_NULL
|
| 5482 | |
@acindex{FUNC_UTIME_NULL}
|
| 5483 | |
@cvindex HAVE_UTIME_NULL
|
| 5484 | |
@c @fuindex utime
|
| 5485 | |
@prindex @code{utime}
|
| 5486 | |
@caindex func_utime_null
|
| 5487 | |
If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
|
| 5488 | |
the present, define @code{HAVE_UTIME_NULL}.
|
| 5489 | |
|
| 5490 | |
This macro caches its result in the @code{ac_cv_func_utime_null}
|
| 5491 | |
variable.
|
| 5492 | |
|
| 5493 | |
This macro is obsolescent, as all current systems have a @code{utime}
|
| 5494 | |
that behaves this way. New programs need not use this macro.
|
| 5495 | |
@end defmac
|
| 5496 | |
|
| 5497 | |
@anchor{AC_FUNC_VPRINTF}
|
| 5498 | |
@defmac AC_FUNC_VPRINTF
|
| 5499 | |
@acindex{FUNC_VPRINTF}
|
| 5500 | |
@cvindex HAVE_VPRINTF
|
| 5501 | |
@cvindex HAVE_DOPRNT
|
| 5502 | |
@c @fuindex vprintf
|
| 5503 | |
@prindex @code{vprintf}
|
| 5504 | |
@c @fuindex vsprintf
|
| 5505 | |
@prindex @code{vsprintf}
|
| 5506 | |
If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
|
| 5507 | |
@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
|
| 5508 | |
is available, you may assume that @code{vfprintf} and @code{vsprintf}
|
| 5509 | |
are also available.)
|
| 5510 | |
|
| 5511 | |
This macro is obsolescent, as all current systems have @code{vprintf}.
|
| 5512 | |
New programs need not use this macro.
|
| 5513 | |
@end defmac
|
| 5514 | |
|
| 5515 | |
@defmac AC_REPLACE_FNMATCH
|
| 5516 | |
@acindex{REPLACE_FNMATCH}
|
| 5517 | |
@c @fuindex fnmatch
|
| 5518 | |
@prindex @code{fnmatch}
|
| 5519 | |
@hdrindex{fnmatch.h}
|
| 5520 | |
@caindex func_fnmatch_works
|
| 5521 | |
If the @code{fnmatch} function does not conform to Posix (see
|
| 5522 | |
@code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
|
| 5523 | |
|
| 5524 | |
The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
|
| 5525 | |
in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
|
| 5526 | |
copy of the source code of GNU @code{fnmatch}. If necessary,
|
| 5527 | |
this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
|
| 5528 | |
@file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
|
| 5529 | |
included in place of the system @code{<fnmatch.h>}.
|
| 5530 | |
|
| 5531 | |
This macro caches its result in the @code{ac_cv_func_fnmatch_works}
|
| 5532 | |
variable.
|
| 5533 | |
|
| 5534 | |
This macro is obsolescent, as it assumes the use of particular source
|
| 5535 | |
files. New programs should use Gnulib's @code{fnmatch-posix} module,
|
| 5536 | |
which provides this macro along with the source files. @xref{Gnulib}.
|
| 5537 | |
@end defmac
|
| 5538 | |
|
| 5539 | |
|
| 5540 | |
|
| 5541 | |
@node Generic Functions
|
| 5542 | |
@subsection Generic Function Checks
|
| 5543 | |
|
| 5544 | |
These macros are used to find functions not covered by the ``particular''
|
| 5545 | |
test macros. If the functions might be in libraries other than the
|
| 5546 | |
default C library, first call @code{AC_CHECK_LIB} for those libraries.
|
| 5547 | |
If you need to check the behavior of a function as well as find out
|
| 5548 | |
whether it is present, you have to write your own test for
|
| 5549 | |
it (@pxref{Writing Tests}).
|
| 5550 | |
|
| 5551 | |
@anchor{AC_CHECK_FUNC}
|
| 5552 | |
@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @
|
| 5553 | |
@ovar{action-if-not-found})
|
| 5554 | |
@acindex{CHECK_FUNC}
|
| 5555 | |
@caindex func_@var{function}
|
| 5556 | |
If C function @var{function} is available, run shell commands
|
| 5557 | |
@var{action-if-found}, otherwise @var{action-if-not-found}. If you just
|
| 5558 | |
want to define a symbol if the function is available, consider using
|
| 5559 | |
@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
|
| 5560 | |
linkage even when @code{AC_LANG(C++)} has been called, since C is more
|
| 5561 | |
standardized than C++. (@pxref{Language Choice}, for more information
|
| 5562 | |
about selecting the language for checks.)
|
| 5563 | |
|
| 5564 | |
This macro caches its result in the @code{ac_cv_func_@var{function}}
|
| 5565 | |
variable.
|
| 5566 | |
@end defmac
|
| 5567 | |
|
| 5568 | |
@anchor{AC_CHECK_FUNCS}
|
| 5569 | |
@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @
|
| 5570 | |
@ovar{action-if-not-found})
|
| 5571 | |
@acindex{CHECK_FUNCS}
|
| 5572 | |
@cvindex HAVE_@var{function}
|
| 5573 | |
For each @var{function} enumerated in the blank-or-newline-separated argument
|
| 5574 | |
list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
|
| 5575 | |
If @var{action-if-found} is given, it is additional shell code to
|
| 5576 | |
execute when one of the functions is found. You can give it a value of
|
| 5577 | |
@samp{break} to break out of the loop on the first match. If
|
| 5578 | |
@var{action-if-not-found} is given, it is executed when one of the
|
| 5579 | |
functions is not found.
|
| 5580 | |
|
| 5581 | |
Results are cached for each @var{function} as in @code{AC_CHECK_FUNC}.
|
| 5582 | |
@end defmac
|
| 5583 | |
|
| 5584 | |
@defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
|
| 5585 | |
@acindex{CHECK_FUNCS_ONCE}
|
| 5586 | |
@cvindex HAVE_@var{function}
|
| 5587 | |
For each @var{function} enumerated in the blank-or-newline-separated argument
|
| 5588 | |
list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
|
| 5589 | |
This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
|
| 5590 | |
checking code at most once, so that @command{configure} is smaller and
|
| 5591 | |
faster; but the checks cannot be conditionalized and are always done once,
|
| 5592 | |
early during the @command{configure} run.
|
| 5593 | |
@end defmac
|
| 5594 | |
|
| 5595 | |
@sp 1
|
| 5596 | |
|
| 5597 | |
Autoconf follows a philosophy that was formed over the years by those
|
| 5598 | |
who have struggled for portability: isolate the portability issues in
|
| 5599 | |
specific files, and then program as if you were in a Posix
|
| 5600 | |
environment. Some functions may be missing or unfixable, and your
|
| 5601 | |
package must be ready to replace them.
|
| 5602 | |
|
| 5603 | |
Suitable replacements for many such problem functions are available from
|
| 5604 | |
Gnulib (@pxref{Gnulib}).
|
| 5605 | |
|
| 5606 | |
@defmac AC_LIBOBJ (@var{function})
|
| 5607 | |
@acindex{LIBOBJ}
|
| 5608 | |
@ovindex LIBOBJS
|
| 5609 | |
Specify that @samp{@var{function}.c} must be included in the executables
|
| 5610 | |
to replace a missing or broken implementation of @var{function}.
|
| 5611 | |
|
| 5612 | |
@vrindex ac_objext
|
| 5613 | |
Technically, it adds @samp{@var{function}.$ac_objext} to the output
|
| 5614 | |
variable @code{LIBOBJS} if it is not already in, and calls
|
| 5615 | |
@code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
|
| 5616 | |
directly change @code{LIBOBJS}, since this is not traceable.
|
| 5617 | |
@end defmac
|
| 5618 | |
|
| 5619 | |
@defmac AC_LIBSOURCE (@var{file})
|
| 5620 | |
@acindex{LIBSOURCE}
|
| 5621 | |
Specify that @var{file} might be needed to compile the project. If you
|
| 5622 | |
need to know what files might be needed by a @file{configure.ac}, you
|
| 5623 | |
should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
|
| 5624 | |
|
| 5625 | |
This macro is called automatically from @code{AC_LIBOBJ}, but you must
|
| 5626 | |
call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
|
| 5627 | |
that case, since shell variables cannot be traced statically, you must
|
| 5628 | |
pass to @code{AC_LIBSOURCE} any possible files that the shell variable
|
| 5629 | |
might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
|
| 5630 | |
a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
|
| 5631 | |
@code{"foo"} or @code{"bar"}, you should do:
|
| 5632 | |
|
| 5633 | |
@example
|
| 5634 | |
AC_LIBSOURCE([foo.c])
|
| 5635 | |
AC_LIBSOURCE([bar.c])
|
| 5636 | |
AC_LIBOBJ([$foo_or_bar])
|
| 5637 | |
@end example
|
| 5638 | |
|
| 5639 | |
@noindent
|
| 5640 | |
There is usually a way to avoid this, however, and you are encouraged to
|
| 5641 | |
simply call @code{AC_LIBOBJ} with literal arguments.
|
| 5642 | |
|
| 5643 | |
Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
|
| 5644 | |
slightly different semantics: the old macro took the function name,
|
| 5645 | |
e.g., @code{foo}, as its argument rather than the file name.
|
| 5646 | |
@end defmac
|
| 5647 | |
|
| 5648 | |
@defmac AC_LIBSOURCES (@var{files})
|
| 5649 | |
@acindex{LIBSOURCES}
|
| 5650 | |
Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
|
| 5651 | |
comma-separated M4 list. Thus, the above example might be rewritten:
|
| 5652 | |
|
| 5653 | |
@example
|
| 5654 | |
AC_LIBSOURCES([foo.c, bar.c])
|
| 5655 | |
AC_LIBOBJ([$foo_or_bar])
|
| 5656 | |
@end example
|
| 5657 | |
@end defmac
|
| 5658 | |
|
| 5659 | |
@defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
|
| 5660 | |
@acindex{CONFIG_LIBOBJ_DIR}
|
| 5661 | |
Specify that @code{AC_LIBOBJ} replacement files are to be found in
|
| 5662 | |
@var{directory}, a name relative to the top level of the
|
| 5663 | |
source tree. The replacement directory defaults to @file{.}, the top
|
| 5664 | |
level directory, and the most typical value is @file{lib}, corresponding
|
| 5665 | |
to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
|
| 5666 | |
|
| 5667 | |
@command{configure} might need to know the replacement directory for the
|
| 5668 | |
following reasons: (i) some checks use the replacement files, (ii) some
|
| 5669 | |
macros bypass broken system headers by installing links to the
|
| 5670 | |
replacement headers (iii) when used in conjunction with Automake,
|
| 5671 | |
within each makefile, @var{directory} is used as a relative path
|
| 5672 | |
from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
|
| 5673 | |
@code{LTLIBOBJS}, etc.
|
| 5674 | |
@end defmac
|
| 5675 | |
|
| 5676 | |
@sp 1
|
| 5677 | |
|
| 5678 | |
It is common to merely check for the existence of a function, and ask
|
| 5679 | |
for its @code{AC_LIBOBJ} replacement if missing. The following macro is
|
| 5680 | |
a convenient shorthand.
|
| 5681 | |
|
| 5682 | |
@defmac AC_REPLACE_FUNCS (@var{function}@dots{})
|
| 5683 | |
@acindex{REPLACE_FUNCS}
|
| 5684 | |
@cvindex HAVE_@var{function}
|
| 5685 | |
@ovindex LIBOBJS
|
| 5686 | |
Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
|
| 5687 | |
@var{action-if-not-found}. You can declare your replacement function by
|
| 5688 | |
enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
|
| 5689 | |
system has the function, it probably declares it in a header file you
|
| 5690 | |
should be including, so you shouldn't redeclare it lest your declaration
|
| 5691 | |
conflict.
|
| 5692 | |
@end defmac
|
| 5693 | |
|
| 5694 | |
@node Header Files
|
| 5695 | |
@section Header Files
|
| 5696 | |
@cindex Header, checking
|
| 5697 | |
|
| 5698 | |
The following macros check for the presence of certain C header files.
|
| 5699 | |
If there is no macro specifically defined to check for a header file you need,
|
| 5700 | |
and you don't need to check for any special properties of
|
| 5701 | |
it, then you can use one of the general header-file check macros.
|
| 5702 | |
|
| 5703 | |
@menu
|
| 5704 | |
* Header Portability:: Collected knowledge on common headers
|
| 5705 | |
* Particular Headers:: Special handling to find certain headers
|
| 5706 | |
* Generic Headers:: How to find other headers
|
| 5707 | |
@end menu
|
| 5708 | |
|
| 5709 | |
@node Header Portability
|
| 5710 | |
@subsection Portability of Headers
|
| 5711 | |
@cindex Portability of headers
|
| 5712 | |
@cindex Header portability
|
| 5713 | |
|
| 5714 | |
This section documents some collected knowledge about common headers,
|
| 5715 | |
and the problems they cause. By definition, this list always requires
|
| 5716 | |
additions. A much more complete list is maintained by the Gnulib
|
| 5717 | |
project (@pxref{Gnulib}), covering @ref{Header File Substitutes, ,
|
| 5718 | |
Posix Headers, gnulib, GNU gnulib} and @ref{Glibc Header File
|
| 5719 | |
Substitutes, , Glibc Headers, gnulib, GNU gnulib}. Please help us keep
|
| 5720 | |
the gnulib list as complete as possible.
|
| 5721 | |
|
| 5722 | |
@table @asis
|
| 5723 | |
|
| 5724 | |
@item @file{limits.h}
|
| 5725 | |
C99 says that @file{limits.h} defines @code{LLONG_MIN},
|
| 5726 | |
@code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
|
| 5727 | |
environments (e.g., default GCC 4.0.2 + glibc 2.4) do not
|
| 5728 | |
define them.
|
| 5729 | |
|
| 5730 | |
@item @file{inttypes.h} vs.@: @file{stdint.h}
|
| 5731 | |
@hdrindex{inttypes.h}
|
| 5732 | |
@hdrindex{stdint.h}
|
| 5733 | |
The C99 standard says that @file{inttypes.h} includes
|
| 5734 | |
@file{stdint.h}, so there's no need to include @file{stdint.h}
|
| 5735 | |
separately in a standard environment. Some implementations have
|
| 5736 | |
@file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
|
| 5737 | |
know of any implementation that has @file{stdint.h} but not
|
| 5738 | |
@file{inttypes.h}.
|
| 5739 | |
|
| 5740 | |
@item @file{linux/irda.h}
|
| 5741 | |
@hdrindex{linux/irda.h}
|
| 5742 | |
It requires @file{linux/types.h} and @file{sys/socket.h}.
|
| 5743 | |
|
| 5744 | |
@item @file{linux/random.h}
|
| 5745 | |
@hdrindex{linux/random.h}
|
| 5746 | |
It requires @file{linux/types.h}.
|
| 5747 | |
|
| 5748 | |
@item @file{net/if.h}
|
| 5749 | |
@hdrindex{net/if.h}
|
| 5750 | |
On Darwin, this file requires that @file{sys/socket.h} be included
|
| 5751 | |
beforehand. One should run:
|
| 5752 | |
|
| 5753 | |
@example
|
| 5754 | |
AC_CHECK_HEADERS([sys/socket.h])
|
| 5755 | |
AC_CHECK_HEADERS([net/if.h], [], [],
|
| 5756 | |
[#include <stdio.h>
|
| 5757 | |
#ifdef STDC_HEADERS
|
| 5758 | |
# include <stdlib.h>
|
| 5759 | |
# include <stddef.h>
|
| 5760 | |
#else
|
| 5761 | |
# ifdef HAVE_STDLIB_H
|
| 5762 | |
# include <stdlib.h>
|
| 5763 | |
# endif
|
| 5764 | |
#endif
|
| 5765 | |
#ifdef HAVE_SYS_SOCKET_H
|
| 5766 | |
# include <sys/socket.h>
|
| 5767 | |
#endif
|
| 5768 | |
])
|
| 5769 | |
@end example
|
| 5770 | |
|
| 5771 | |
@item @file{netinet/if_ether.h}
|
| 5772 | |
@hdrindex{netinet/if_ether.h}
|
| 5773 | |
On Darwin, this file requires that @file{stdio.h} and
|
| 5774 | |
@file{sys/socket.h} be included beforehand. One should run:
|
| 5775 | |
|
| 5776 | |
@example
|
| 5777 | |
AC_CHECK_HEADERS([sys/socket.h])
|
| 5778 | |
AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
|
| 5779 | |
[#include <stdio.h>
|
| 5780 | |
#ifdef STDC_HEADERS
|
| 5781 | |
# include <stdlib.h>
|
| 5782 | |
# include <stddef.h>
|
| 5783 | |
#else
|
| 5784 | |
# ifdef HAVE_STDLIB_H
|
| 5785 | |
# include <stdlib.h>
|
| 5786 | |
# endif
|
| 5787 | |
#endif
|
| 5788 | |
#ifdef HAVE_SYS_SOCKET_H
|
| 5789 | |
# include <sys/socket.h>
|
| 5790 | |
#endif
|
| 5791 | |
])
|
| 5792 | |
@end example
|
| 5793 | |
|
| 5794 | |
@item @file{stdint.h}
|
| 5795 | |
See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
|
| 5796 | |
|
| 5797 | |
@item @file{stdlib.h}
|
| 5798 | |
@hdrindex{stdlib.h}
|
| 5799 | |
On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
|
| 5800 | |
|
| 5801 | |
@item @file{sys/mount.h}
|
| 5802 | |
@hdrindex{sys/mount.h}
|
| 5803 | |
On FreeBSD 4.8 on ia32 and using gcc version 2.95.4,
|
| 5804 | |
@file{sys/params.h} is a prerequisite.
|
| 5805 | |
|
| 5806 | |
@item @file{sys/ptem.h}
|
| 5807 | |
@hdrindex{sys/ptem.h}
|
| 5808 | |
On Solaris 8, @file{sys/stream.h} is a prerequisite.
|
| 5809 | |
|
| 5810 | |
@item @file{sys/socket.h}
|
| 5811 | |
@hdrindex{sys/socket.h}
|
| 5812 | |
On Darwin, @file{stdlib.h} is a prerequisite.
|
| 5813 | |
|
| 5814 | |
@item @file{sys/ucred.h}
|
| 5815 | |
@hdrindex{sys/ucred.h}
|
| 5816 | |
On Tru64 5.1, @file{sys/types.h} is a prerequisite.
|
| 5817 | |
|
| 5818 | |
@item @file{X11/extensions/scrnsaver.h}
|
| 5819 | |
@hdrindex{X11/extensions/scrnsaver.h}
|
| 5820 | |
Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
|
| 5821 | |
so required that you might not even consider looking for it.
|
| 5822 | |
|
| 5823 | |
@example
|
| 5824 | |
AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
|
| 5825 | |
[[#include <X11/Xlib.h>
|
| 5826 | |
]])
|
| 5827 | |
@end example
|
| 5828 | |
@end table
|
| 5829 | |
|
| 5830 | |
|
| 5831 | |
@node Particular Headers
|
| 5832 | |
@subsection Particular Header Checks
|
| 5833 | |
|
| 5834 | |
These macros check for particular system header files---whether they
|
| 5835 | |
exist, and in some cases whether they declare certain symbols.
|
| 5836 | |
|
| 5837 | |
@defmac AC_CHECK_HEADER_STDBOOL
|
| 5838 | |
@acindex{CHECK_HEADER_STDBOOL}
|
| 5839 | |
@cvindex HAVE__BOOL
|
| 5840 | |
@hdrindex{stdbool.h}
|
| 5841 | |
@caindex header_stdbool_h
|
| 5842 | |
Check whether @file{stdbool.h} exists and conforms to C99, and cache the
|
| 5843 | |
result in the @code{ac_cv_header_stdbool_h} variable. If the type
|
| 5844 | |
@code{_Bool} is defined, define @code{HAVE__BOOL} to 1.
|
| 5845 | |
|
| 5846 | |
This macro is intended for use by Gnulib (@pxref{Gnulib}) and other
|
| 5847 | |
packages that supply a substitute @file{stdbool.h} on platforms lacking
|
| 5848 | |
a conforming one. The @code{AC_HEADER_STDBOOL} macro is better for code
|
| 5849 | |
that explicitly checks for @file{stdbool.h}.
|
| 5850 | |
@end defmac
|
| 5851 | |
|
| 5852 | |
@defmac AC_HEADER_ASSERT
|
| 5853 | |
@acindex{HEADER_ASSERT}
|
| 5854 | |
@cvindex NDEBUG
|
| 5855 | |
@hdrindex{assert.h}
|
| 5856 | |
Check whether to enable assertions in the style of @file{assert.h}.
|
| 5857 | |
Assertions are enabled by default, but the user can override this by
|
| 5858 | |
invoking @command{configure} with the @option{--disable-assert} option.
|
| 5859 | |
@end defmac
|
| 5860 | |
|
| 5861 | |
@anchor{AC_HEADER_DIRENT}
|
| 5862 | |
@defmac AC_HEADER_DIRENT
|
| 5863 | |
@acindex{HEADER_DIRENT}
|
| 5864 | |
@cvindex HAVE_DIRENT_H
|
| 5865 | |
@cvindex HAVE_NDIR_H
|
| 5866 | |
@cvindex HAVE_SYS_DIR_H
|
| 5867 | |
@cvindex HAVE_SYS_NDIR_H
|
| 5868 | |
@hdrindex{dirent.h}
|
| 5869 | |
@hdrindex{sys/ndir.h}
|
| 5870 | |
@hdrindex{sys/dir.h}
|
| 5871 | |
@hdrindex{ndir.h}
|
| 5872 | |
Check for the following header files. For the first one that is
|
| 5873 | |
found and defines @samp{DIR}, define the listed C preprocessor macro:
|
| 5874 | |
|
| 5875 | |
@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
|
| 5876 | |
@item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
|
| 5877 | |
@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
|
| 5878 | |
@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
|
| 5879 | |
@item @file{ndir.h} @tab @code{HAVE_NDIR_H}
|
| 5880 | |
@end multitable
|
| 5881 | |
|
| 5882 | |
The directory-library declarations in your source code should look
|
| 5883 | |
something like the following:
|
| 5884 | |
|
| 5885 | |
@example
|
| 5886 | |
@group
|
| 5887 | |
#include <sys/types.h>
|
| 5888 | |
#ifdef HAVE_DIRENT_H
|
| 5889 | |
# include <dirent.h>
|
| 5890 | |
# define NAMLEN(dirent) strlen ((dirent)->d_name)
|
| 5891 | |
#else
|
| 5892 | |
# define dirent direct
|
| 5893 | |
# define NAMLEN(dirent) ((dirent)->d_namlen)
|
| 5894 | |
# ifdef HAVE_SYS_NDIR_H
|
| 5895 | |
# include <sys/ndir.h>
|
| 5896 | |
# endif
|
| 5897 | |
# ifdef HAVE_SYS_DIR_H
|
| 5898 | |
# include <sys/dir.h>
|
| 5899 | |
# endif
|
| 5900 | |
# ifdef HAVE_NDIR_H
|
| 5901 | |
# include <ndir.h>
|
| 5902 | |
# endif
|
| 5903 | |
#endif
|
| 5904 | |
@end group
|
| 5905 | |
@end example
|
| 5906 | |
|
| 5907 | |
Using the above declarations, the program would declare variables to be
|
| 5908 | |
of type @code{struct dirent}, not @code{struct direct}, and would access
|
| 5909 | |
the length of a directory entry name by passing a pointer to a
|
| 5910 | |
@code{struct dirent} to the @code{NAMLEN} macro.
|
| 5911 | |
|
| 5912 | |
This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
|
| 5913 | |
|
| 5914 | |
This macro is obsolescent, as all current systems with directory
|
| 5915 | |
libraries have @code{<dirent.h>}. New programs need not use this macro.
|
| 5916 | |
|
| 5917 | |
Also see @code{AC_STRUCT_DIRENT_D_INO} and
|
| 5918 | |
@code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
|
| 5919 | |
@end defmac
|
| 5920 | |
|
| 5921 | |
@anchor{AC_HEADER_MAJOR}
|
| 5922 | |
@defmac AC_HEADER_MAJOR
|
| 5923 | |
@acindex{HEADER_MAJOR}
|
| 5924 | |
@cvindex MAJOR_IN_MKDEV
|
| 5925 | |
@cvindex MAJOR_IN_SYSMACROS
|
| 5926 | |
@hdrindex{sys/mkdev.h}
|
| 5927 | |
@hdrindex{sys/sysmacros.h}
|
| 5928 | |
If @file{sys/types.h} does not define @code{major}, @code{minor}, and
|
| 5929 | |
@code{makedev}, but @file{sys/mkdev.h} does, define
|
| 5930 | |
@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
|
| 5931 | |
@code{MAJOR_IN_SYSMACROS}.
|
| 5932 | |
@end defmac
|
| 5933 | |
|
| 5934 | |
@defmac AC_HEADER_RESOLV
|
| 5935 | |
@acindex{HEADER_RESOLV}
|
| 5936 | |
@cvindex HAVE_RESOLV_H
|
| 5937 | |
@hdrindex{resolv.h}
|
| 5938 | |
Checks for header @file{resolv.h}, checking for prerequisites first.
|
| 5939 | |
To properly use @file{resolv.h}, your code should contain something like
|
| 5940 | |
the following:
|
| 5941 | |
|
| 5942 | |
@verbatim
|
| 5943 | |
#ifdef HAVE_SYS_TYPES_H
|
| 5944 | |
# include <sys/types.h>
|
| 5945 | |
#endif
|
| 5946 | |
#ifdef HAVE_NETINET_IN_H
|
| 5947 | |
# include <netinet/in.h> /* inet_ functions / structs */
|
| 5948 | |
#endif
|
| 5949 | |
#ifdef HAVE_ARPA_NAMESER_H
|
| 5950 | |
# include <arpa/nameser.h> /* DNS HEADER struct */
|
| 5951 | |
#endif
|
| 5952 | |
#ifdef HAVE_NETDB_H
|
| 5953 | |
# include <netdb.h>
|
| 5954 | |
#endif
|
| 5955 | |
#include <resolv.h>
|
| 5956 | |
@end verbatim
|
| 5957 | |
@end defmac
|
| 5958 | |
|
| 5959 | |
@anchor{AC_HEADER_STAT}
|
| 5960 | |
@defmac AC_HEADER_STAT
|
| 5961 | |
@acindex{HEADER_STAT}
|
| 5962 | |
@cvindex STAT_MACROS_BROKEN
|
| 5963 | |
@hdrindex{sys/stat.h}
|
| 5964 | |
If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
|
| 5965 | |
@file{sys/stat.h} do not work properly (returning false positives),
|
| 5966 | |
define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
|
| 5967 | |
Amdahl UTS and Motorola System V/88.
|
| 5968 | |
|
| 5969 | |
This macro is obsolescent, as no current systems have the bug.
|
| 5970 | |
New programs need not use this macro.
|
| 5971 | |
@end defmac
|
| 5972 | |
|
| 5973 | |
@defmac AC_HEADER_STDBOOL
|
| 5974 | |
@acindex{HEADER_STDBOOL}
|
| 5975 | |
@cvindex HAVE_STDBOOL_H
|
| 5976 | |
@cvindex HAVE__BOOL
|
| 5977 | |
@hdrindex{stdbool.h}
|
| 5978 | |
@caindex header_stdbool_h
|
| 5979 | |
If @file{stdbool.h} exists and conforms to C99, define
|
| 5980 | |
@code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
|
| 5981 | |
@code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
|
| 5982 | |
program could contain the following code:
|
| 5983 | |
|
| 5984 | |
@example
|
| 5985 | |
@group
|
| 5986 | |
#ifdef HAVE_STDBOOL_H
|
| 5987 | |
# include <stdbool.h>
|
| 5988 | |
#else
|
| 5989 | |
# ifndef HAVE__BOOL
|
| 5990 | |
# ifdef __cplusplus
|
| 5991 | |
typedef bool _Bool;
|
| 5992 | |
# else
|
| 5993 | |
# define _Bool signed char
|
| 5994 | |
# endif
|
| 5995 | |
# endif
|
| 5996 | |
# define bool _Bool
|
| 5997 | |
# define false 0
|
| 5998 | |
# define true 1
|
| 5999 | |
# define __bool_true_false_are_defined 1
|
| 6000 | |
#endif
|
| 6001 | |
@end group
|
| 6002 | |
@end example
|
| 6003 | |
|
| 6004 | |
Alternatively you can use the @samp{stdbool} package of Gnulib
|
| 6005 | |
(@pxref{Gnulib}). It simplifies your code so that it can say just
|
| 6006 | |
@code{#include <stdbool.h>}, and it adds support for less-common
|
| 6007 | |
platforms.
|
| 6008 | |
|
| 6009 | |
This macro caches its result in the @code{ac_cv_header_stdbool_h}
|
| 6010 | |
variable.
|
| 6011 | |
|
| 6012 | |
This macro differs from @code{AC_CHECK_HEADER_STDBOOL} only in that it
|
| 6013 | |
defines @code{HAVE_STDBOOL_H} whereas @code{AC_CHECK_HEADER_STDBOOL}
|
| 6014 | |
does not.
|
| 6015 | |
@end defmac
|
| 6016 | |
|
| 6017 | |
@anchor{AC_HEADER_STDC}
|
| 6018 | |
@defmac AC_HEADER_STDC
|
| 6019 | |
@acindex{HEADER_STDC}
|
| 6020 | |
@cvindex STDC_HEADERS
|
| 6021 | |
@hdrindex{stdlib.h}
|
| 6022 | |
@hdrindex{stdarg.h}
|
| 6023 | |
@hdrindex{string.h}
|
| 6024 | |
@hdrindex{float.h}
|
| 6025 | |
@hdrindex{ctype.h}
|
| 6026 | |
@caindex header_stdc
|
| 6027 | |
Define @code{STDC_HEADERS} if the system has C header files
|
| 6028 | |
conforming to ANSI C89 (ISO C90).
|
| 6029 | |
Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
|
| 6030 | |
@file{string.h}, and @file{float.h}; if the system has those, it
|
| 6031 | |
probably has the rest of the C89 header files. This macro also
|
| 6032 | |
checks whether @file{string.h} declares @code{memchr} (and thus
|
| 6033 | |
presumably the other @code{mem} functions), whether @file{stdlib.h}
|
| 6034 | |
declare @code{free} (and thus presumably @code{malloc} and other related
|
| 6035 | |
functions), and whether the @file{ctype.h} macros work on characters
|
| 6036 | |
with the high bit set, as the C standard requires.
|
| 6037 | |
|
| 6038 | |
If you use this macro, your code can refer to @code{STDC_HEADERS} to
|
| 6039 | |
determine whether the system has conforming header files (and probably C
|
| 6040 | |
library functions).
|
| 6041 | |
|
| 6042 | |
This macro caches its result in the @code{ac_cv_header_stdc} variable.
|
| 6043 | |
|
| 6044 | |
This macro is obsolescent, as current systems have conforming header
|
| 6045 | |
files. New programs need not use this macro.
|
| 6046 | |
|
| 6047 | |
@hdrindex{string.h}
|
| 6048 | |
@hdrindex{strings.h}
|
| 6049 | |
Nowadays @file{string.h} is part of the C standard and declares functions like
|
| 6050 | |
@code{strcpy}, and @file{strings.h} is standardized by Posix and declares
|
| 6051 | |
BSD functions like @code{bcopy}; but
|
| 6052 | |
historically, string functions were a major sticking point in this area.
|
| 6053 | |
If you still want to worry about portability to ancient systems without
|
| 6054 | |
standard headers, there is so much variation
|
| 6055 | |
that it is probably easier to declare the functions you use than to
|
| 6056 | |
figure out exactly what the system header files declare. Some ancient systems
|
| 6057 | |
contained a mix of functions from the C standard and from BSD;
|
| 6058 | |
some were mostly standard but lacked @samp{memmove}; some defined the
|
| 6059 | |
BSD functions as macros in @file{string.h} or
|
| 6060 | |
@file{strings.h}; some had only the BSD functions but
|
| 6061 | |
@file{string.h}; some declared the memory functions in @file{memory.h},
|
| 6062 | |
some in @file{string.h}; etc. It is probably sufficient to check for
|
| 6063 | |
one string function and one memory function; if the library had the
|
| 6064 | |
standard versions of those then it probably had most of the others.
|
| 6065 | |
If you put the following in @file{configure.ac}:
|
| 6066 | |
|
| 6067 | |
@example
|
| 6068 | |
# This example is obsolescent.
|
| 6069 | |
# Nowadays you can omit these macro calls.
|
| 6070 | |
AC_HEADER_STDC
|
| 6071 | |
AC_CHECK_FUNCS([strchr memcpy])
|
| 6072 | |
@end example
|
| 6073 | |
|
| 6074 | |
@noindent
|
| 6075 | |
then, in your code, you can use declarations like this:
|
| 6076 | |
|
| 6077 | |
@example
|
| 6078 | |
@group
|
| 6079 | |
/* This example is obsolescent.
|
| 6080 | |
Nowadays you can just #include <string.h>. */
|
| 6081 | |
#ifdef STDC_HEADERS
|
| 6082 | |
# include <string.h>
|
| 6083 | |
#else
|
| 6084 | |
# ifndef HAVE_STRCHR
|
| 6085 | |
# define strchr index
|
| 6086 | |
# define strrchr rindex
|
| 6087 | |
# endif
|
| 6088 | |
char *strchr (), *strrchr ();
|
| 6089 | |
# ifndef HAVE_MEMCPY
|
| 6090 | |
# define memcpy(d, s, n) bcopy ((s), (d), (n))
|
| 6091 | |
# define memmove(d, s, n) bcopy ((s), (d), (n))
|
| 6092 | |
# endif
|
| 6093 | |
#endif
|
| 6094 | |
@end group
|
| 6095 | |
@end example
|
| 6096 | |
|
| 6097 | |
@noindent
|
| 6098 | |
If you use a function like @code{memchr}, @code{memset}, @code{strtok},
|
| 6099 | |
or @code{strspn}, which have no BSD equivalent, then macros don't
|
| 6100 | |
suffice to port to ancient hosts; you must provide an implementation of
|
| 6101 | |
each function. An easy
|
| 6102 | |
way to incorporate your implementations only when needed (since the ones
|
| 6103 | |
in system C libraries may be hand optimized) is to, taking @code{memchr}
|
| 6104 | |
for example, put it in @file{memchr.c} and use
|
| 6105 | |
@samp{AC_REPLACE_FUNCS([memchr])}.
|
| 6106 | |
@end defmac
|
| 6107 | |
|
| 6108 | |
@defmac AC_HEADER_SYS_WAIT
|
| 6109 | |
@acindex{HEADER_SYS_WAIT}
|
| 6110 | |
@cvindex HAVE_SYS_WAIT_H
|
| 6111 | |
@hdrindex{sys/wait.h}
|
| 6112 | |
@caindex header_sys_wait_h
|
| 6113 | |
If @file{sys/wait.h} exists and is compatible with Posix, define
|
| 6114 | |
@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
|
| 6115 | |
does not exist, or if it uses the old BSD @code{union wait} instead
|
| 6116 | |
of @code{int} to store a status value. If @file{sys/wait.h} is not
|
| 6117 | |
Posix compatible, then instead of including it, define the
|
| 6118 | |
Posix macros with their usual interpretations. Here is an
|
| 6119 | |
example:
|
| 6120 | |
|
| 6121 | |
@example
|
| 6122 | |
@group
|
| 6123 | |
#include <sys/types.h>
|
| 6124 | |
#ifdef HAVE_SYS_WAIT_H
|
| 6125 | |
# include <sys/wait.h>
|
| 6126 | |
#endif
|
| 6127 | |
#ifndef WEXITSTATUS
|
| 6128 | |
# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
|
| 6129 | |
#endif
|
| 6130 | |
#ifndef WIFEXITED
|
| 6131 | |
# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
|
| 6132 | |
#endif
|
| 6133 | |
@end group
|
| 6134 | |
@end example
|
| 6135 | |
|
| 6136 | |
@noindent
|
| 6137 | |
This macro caches its result in the @code{ac_cv_header_sys_wait_h}
|
| 6138 | |
variable.
|
| 6139 | |
|
| 6140 | |
This macro is obsolescent, as current systems are compatible with Posix.
|
| 6141 | |
New programs need not use this macro.
|
| 6142 | |
@end defmac
|
| 6143 | |
|
| 6144 | |
@cvindex _POSIX_VERSION
|
| 6145 | |
@hdrindex{unistd.h}
|
| 6146 | |
@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
|
| 6147 | |
Posix systems. If there is no @file{unistd.h}, it is definitely
|
| 6148 | |
not a Posix system. However, some non-Posix systems do
|
| 6149 | |
have @file{unistd.h}.
|
| 6150 | |
|
| 6151 | |
The way to check whether the system supports Posix is:
|
| 6152 | |
|
| 6153 | |
@example
|
| 6154 | |
@group
|
| 6155 | |
#ifdef HAVE_UNISTD_H
|
| 6156 | |
# include <sys/types.h>
|
| 6157 | |
# include <unistd.h>
|
| 6158 | |
#endif
|
| 6159 | |
|
| 6160 | |
#ifdef _POSIX_VERSION
|
| 6161 | |
/* Code for Posix systems. */
|
| 6162 | |
#endif
|
| 6163 | |
@end group
|
| 6164 | |
@end example
|
| 6165 | |
|
| 6166 | |
@anchor{AC_HEADER_TIME}
|
| 6167 | |
@defmac AC_HEADER_TIME
|
| 6168 | |
@acindex{HEADER_TIME}
|
| 6169 | |
@cvindex TIME_WITH_SYS_TIME
|
| 6170 | |
@hdrindex{time.h}
|
| 6171 | |
@hdrindex{sys/time.h}
|
| 6172 | |
@caindex header_time
|
| 6173 | |
If a program may include both @file{time.h} and @file{sys/time.h},
|
| 6174 | |
define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
|
| 6175 | |
@file{sys/time.h} included @file{time.h}, but @file{time.h} was not
|
| 6176 | |
protected against multiple inclusion, so programs could not explicitly
|
| 6177 | |
include both files. This macro is useful in programs that use, for
|
| 6178 | |
example, @code{struct timeval} as well as
|
| 6179 | |
@code{struct tm}. It is best used in conjunction with
|
| 6180 | |
@code{HAVE_SYS_TIME_H}, which can be checked for using
|
| 6181 | |
@code{AC_CHECK_HEADERS([sys/time.h])}.
|
| 6182 | |
|
| 6183 | |
@example
|
| 6184 | |
@group
|
| 6185 | |
#ifdef TIME_WITH_SYS_TIME
|
| 6186 | |
# include <sys/time.h>
|
| 6187 | |
# include <time.h>
|
| 6188 | |
#else
|
| 6189 | |
# ifdef HAVE_SYS_TIME_H
|
| 6190 | |
# include <sys/time.h>
|
| 6191 | |
# else
|
| 6192 | |
# include <time.h>
|
| 6193 | |
# endif
|
| 6194 | |
#endif
|
| 6195 | |
@end group
|
| 6196 | |
@end example
|
| 6197 | |
|
| 6198 | |
@noindent
|
| 6199 | |
This macro caches its result in the @code{ac_cv_header_time} variable.
|
| 6200 | |
|
| 6201 | |
This macro is obsolescent, as current systems can include both files
|
| 6202 | |
when they exist. New programs need not use this macro.
|
| 6203 | |
@end defmac
|
| 6204 | |
|
| 6205 | |
|
| 6206 | |
@defmac AC_HEADER_TIOCGWINSZ
|
| 6207 | |
@acindex{HEADER_TIOCGWINSZ}
|
| 6208 | |
@cvindex GWINSZ_IN_SYS_IOCTL
|
| 6209 | |
@hdrindex{sys/ioctl.h}
|
| 6210 | |
@hdrindex{termios.h}
|
| 6211 | |
@c FIXME: I need clarifications from Jim.
|
| 6212 | |
If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
|
| 6213 | |
define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
|
| 6214 | |
found in @file{<termios.h>}.
|
| 6215 | |
|
| 6216 | |
Use:
|
| 6217 | |
|
| 6218 | |
@example
|
| 6219 | |
@group
|
| 6220 | |
#ifdef HAVE_TERMIOS_H
|
| 6221 | |
# include <termios.h>
|
| 6222 | |
#endif
|
| 6223 | |
|
| 6224 | |
#ifdef GWINSZ_IN_SYS_IOCTL
|
| 6225 | |
# include <sys/ioctl.h>
|
| 6226 | |
#endif
|
| 6227 | |
@end group
|
| 6228 | |
@end example
|
| 6229 | |
@end defmac
|
| 6230 | |
|
| 6231 | |
@node Generic Headers
|
| 6232 | |
@subsection Generic Header Checks
|
| 6233 | |
|
| 6234 | |
These macros are used to find system header files not covered by the
|
| 6235 | |
``particular'' test macros. If you need to check the contents of a header
|
| 6236 | |
as well as find out whether it is present, you have to write your own
|
| 6237 | |
test for it (@pxref{Writing Tests}).
|
| 6238 | |
|
| 6239 | |
@anchor{AC_CHECK_HEADER}
|
| 6240 | |
@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @
|
| 6241 | |
@ovar{action-if-not-found}, @ovar{includes})
|
| 6242 | |
@acindex{CHECK_HEADER}
|
| 6243 | |
@caindex header_@var{header-file}
|
| 6244 | |
If the system header file @var{header-file} is compilable, execute shell
|
| 6245 | |
commands @var{action-if-found}, otherwise execute
|
| 6246 | |
@var{action-if-not-found}. If you just want to define a symbol if the
|
| 6247 | |
header file is available, consider using @code{AC_CHECK_HEADERS}
|
| 6248 | |
instead.
|
| 6249 | |
|
| 6250 | |
@var{includes} is decoded to determine the appropriate include
|
| 6251 | |
directives. If omitted or empty, @file{configure} will check for both header
|
| 6252 | |
existence (with the preprocessor) and usability (with the compiler),
|
| 6253 | |
using @code{AC_INCLUDES_DEFAULT} for the compile test. If
|
| 6254 | |
there is a discrepancy between the results, a warning is issued to the
|
| 6255 | |
user, and the compiler results are favored (@pxref{Present But
|
| 6256 | |
Cannot Be Compiled}). In general, favoring the compiler results means
|
| 6257 | |
that a header will be treated as not found even though the file exists,
|
| 6258 | |
because you did not provide enough prerequisites.
|
| 6259 | |
|
| 6260 | |
Providing a non-empty @var{includes} argument allows the code to provide
|
| 6261 | |
any prerequisites prior to including the header under test; it is common
|
| 6262 | |
to use the argument @code{AC_INCLUDES_DEFAULT} (@pxref{Default
|
| 6263 | |
Includes}). With an explicit fourth argument, no preprocessor test is
|
| 6264 | |
needed. As a special case, an @var{includes} of exactly @samp{-}
|
| 6265 | |
triggers the older preprocessor check, which merely determines existence
|
| 6266 | |
of the file in the preprocessor search path; this should only be used as
|
| 6267 | |
a last resort (it is safer to determine the actual prerequisites and
|
| 6268 | |
perform a compiler check, or else use @code{AC_PREPROC_IFELSE} to make
|
| 6269 | |
it obvious that only a preprocessor check is desired).
|
| 6270 | |
|
| 6271 | |
This macro caches its result in the @code{ac_cv_header_@var{header-file}}
|
| 6272 | |
variable, with characters not suitable for a variable name mapped to
|
| 6273 | |
underscores.
|
| 6274 | |
@end defmac
|
| 6275 | |
|
| 6276 | |
@anchor{AC_CHECK_HEADERS}
|
| 6277 | |
@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @
|
| 6278 | |
@ovar{action-if-found}, @ovar{action-if-not-found}, @
|
| 6279 | |
@ovar{includes})
|
| 6280 | |
@acindex{CHECK_HEADERS}
|
| 6281 | |
@cvindex HAVE_@var{header}
|
| 6282 | |
@caindex header_@var{header-file}
|
| 6283 | |
For each given system header file @var{header-file} in the
|
| 6284 | |
blank-separated argument list that exists, define
|
| 6285 | |
@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
|
| 6286 | |
is given, it is additional shell code to execute when one of the header
|
| 6287 | |
files is found. You can give it a value of @samp{break} to break out of
|
| 6288 | |
the loop on the first match. If @var{action-if-not-found} is given, it
|
| 6289 | |
is executed when one of the header files is not found.
|
| 6290 | |
|
| 6291 | |
@var{includes} is interpreted as in @code{AC_CHECK_HEADER}, in order to
|
| 6292 | |
choose the set of preprocessor directives supplied before the header
|
| 6293 | |
under test.
|
| 6294 | |
|
| 6295 | |
This macro caches its result in the @code{ac_cv_header_@var{header-file}}
|
| 6296 | |
variable, with characters not suitable for a variable name mapped to
|
| 6297 | |
underscores.
|
| 6298 | |
@end defmac
|
| 6299 | |
|
| 6300 | |
Previous versions of Autoconf merely checked whether the header was
|
| 6301 | |
accepted by the preprocessor. This was changed because the old test was
|
| 6302 | |
inappropriate for typical uses. Headers are typically used to compile,
|
| 6303 | |
not merely to preprocess, and the old behavior sometimes accepted
|
| 6304 | |
headers that clashed at compile-time (@pxref{Present But Cannot Be
|
| 6305 | |
Compiled}). If you need to check whether a header is preprocessable,
|
| 6306 | |
you can use @code{AC_PREPROC_IFELSE} (@pxref{Running the Preprocessor}).
|
| 6307 | |
|
| 6308 | |
Actually requiring a header to compile improves the robustness of the
|
| 6309 | |
test, but it also requires
|
| 6310 | |
that you make sure that headers that must be included before the
|
| 6311 | |
@var{header-file} be part of the @var{includes}, (@pxref{Default
|
| 6312 | |
Includes}). If looking for @file{bar.h}, which requires that
|
| 6313 | |
@file{foo.h} be included before if it exists, we suggest the following
|
| 6314 | |
scheme:
|
| 6315 | |
|
| 6316 | |
@verbatim
|
| 6317 | |
AC_CHECK_HEADERS([foo.h])
|
| 6318 | |
AC_CHECK_HEADERS([bar.h], [], [],
|
| 6319 | |
[#ifdef HAVE_FOO_H
|
| 6320 | |
# include <foo.h>
|
| 6321 | |
#endif
|
| 6322 | |
])
|
| 6323 | |
@end verbatim
|
| 6324 | |
|
| 6325 | |
The following variant generates smaller, faster @command{configure}
|
| 6326 | |
files if you do not need the full power of @code{AC_CHECK_HEADERS}.
|
| 6327 | |
|
| 6328 | |
@defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
|
| 6329 | |
@acindex{CHECK_HEADERS_ONCE}
|
| 6330 | |
@cvindex HAVE_@var{header}
|
| 6331 | |
For each given system header file @var{header-file} in the
|
| 6332 | |
blank-separated argument list that exists, define
|
| 6333 | |
@code{HAVE_@var{header-file}} (in all capitals).
|
| 6334 | |
This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
|
| 6335 | |
checking code at most once, so that @command{configure} is smaller and
|
| 6336 | |
faster; but the checks cannot be conditionalized and are always done once,
|
| 6337 | |
early during the @command{configure} run. Thus, this macro is only safe
|
| 6338 | |
for checking headers that do not have prerequisites beyond what
|
| 6339 | |
@code{AC_INCLUDES_DEFAULT} provides.
|
| 6340 | |
@end defmac
|
| 6341 | |
|
| 6342 | |
@node Declarations
|
| 6343 | |
@section Declarations
|
| 6344 | |
@cindex Declaration, checking
|
| 6345 | |
|
| 6346 | |
The following macros check for the declaration of variables and
|
| 6347 | |
functions. If there is no macro specifically defined to check for a
|
| 6348 | |
symbol you need, then you can use the general macros (@pxref{Generic
|
| 6349 | |
Declarations}) or, for more complex tests, you may use
|
| 6350 | |
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
|
| 6351 | |
|
| 6352 | |
@menu
|
| 6353 | |
* Particular Declarations:: Macros to check for certain declarations
|
| 6354 | |
* Generic Declarations:: How to find other declarations
|
| 6355 | |
@end menu
|
| 6356 | |
|
| 6357 | |
@node Particular Declarations
|
| 6358 | |
@subsection Particular Declaration Checks
|
| 6359 | |
|
| 6360 | |
There are no specific macros for declarations.
|
| 6361 | |
|
| 6362 | |
@node Generic Declarations
|
| 6363 | |
@subsection Generic Declaration Checks
|
| 6364 | |
|
| 6365 | |
These macros are used to find declarations not covered by the ``particular''
|
| 6366 | |
test macros.
|
| 6367 | |
|
| 6368 | |
@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @
|
| 6369 | |
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
|
| 6370 | |
@acindex{CHECK_DECL}
|
| 6371 | |
@caindex have_decl_@var{symbol}
|
| 6372 | |
If @var{symbol} (a function, variable, or constant) is not declared in
|
| 6373 | |
@var{includes} and a declaration is needed, run the shell commands
|
| 6374 | |
@var{action-if-not-found}, otherwise @var{action-if-found}.
|
| 6375 | |
@var{includes} is a series of include directives, defaulting to
|
| 6376 | |
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
|
| 6377 | |
prior to the declaration under test.
|
| 6378 | |
|
| 6379 | |
This macro actually tests whether @var{symbol} is defined as a macro or
|
| 6380 | |
can be used as an r-value, not whether it is really declared, because it
|
| 6381 | |
is much safer to avoid introducing extra declarations when they are not
|
| 6382 | |
needed. In order to facilitate use of C++ and overloaded function
|
| 6383 | |
declarations, it is possible to specify function argument types in
|
| 6384 | |
parentheses for types which can be zero-initialized:
|
| 6385 | |
|
| 6386 | |
@example
|
| 6387 | |
AC_CHECK_DECL([basename(char *)])
|
| 6388 | |
@end example
|
| 6389 | |
|
| 6390 | |
This macro caches its result in the @code{ac_cv_have_decl_@var{symbol}}
|
| 6391 | |
variable, with characters not suitable for a variable name mapped to
|
| 6392 | |
underscores.
|
| 6393 | |
@end defmac
|
| 6394 | |
|
| 6395 | |
@anchor{AC_CHECK_DECLS}
|
| 6396 | |
@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @
|
| 6397 | |
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
|
| 6398 | |
@acindex{CHECK_DECLS}
|
| 6399 | |
@cvindex HAVE_DECL_@var{symbol}
|
| 6400 | |
@caindex have_decl_@var{symbol}
|
| 6401 | |
For each of the @var{symbols} (@emph{comma}-separated list with optional
|
| 6402 | |
function argument types for C++ overloads), define
|
| 6403 | |
@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
|
| 6404 | |
@var{symbol} is declared, otherwise to @samp{0}. If
|
| 6405 | |
@var{action-if-not-found} is given, it is additional shell code to
|
| 6406 | |
execute when one of the function declarations is needed, otherwise
|
| 6407 | |
@var{action-if-found} is executed.
|
| 6408 | |
|
| 6409 | |
@var{includes} is a series of include directives, defaulting to
|
| 6410 | |
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
|
| 6411 | |
prior to the declarations under test.
|
| 6412 | |
|
| 6413 | |
This macro uses an M4 list as first argument:
|
| 6414 | |
@example
|
| 6415 | |
AC_CHECK_DECLS([strdup])
|
| 6416 | |
AC_CHECK_DECLS([strlen])
|
| 6417 | |
AC_CHECK_DECLS([malloc, realloc, calloc, free])
|
| 6418 | |
AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]])
|
| 6419 | |
AC_CHECK_DECLS([[basename(char *)], [dirname(char *)]])
|
| 6420 | |
@end example
|
| 6421 | |
|
| 6422 | |
Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
|
| 6423 | |
declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
|
| 6424 | |
of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
|
| 6425 | |
@emph{sure} that the check was performed, use
|
| 6426 | |
@code{HAVE_DECL_@var{symbol}} in @code{#if}:
|
| 6427 | |
|
| 6428 | |
@example
|
| 6429 | |
#if !HAVE_DECL_SYMBOL
|
| 6430 | |
extern char *symbol;
|
| 6431 | |
#endif
|
| 6432 | |
@end example
|
| 6433 | |
|
| 6434 | |
@noindent
|
| 6435 | |
If the test may have not been performed, however, because it is safer
|
| 6436 | |
@emph{not} to declare a symbol than to use a declaration that conflicts
|
| 6437 | |
with the system's one, you should use:
|
| 6438 | |
|
| 6439 | |
@example
|
| 6440 | |
#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
|
| 6441 | |
void *malloc (size_t *s);
|
| 6442 | |
#endif
|
| 6443 | |
@end example
|
| 6444 | |
|
| 6445 | |
@noindent
|
| 6446 | |
You fall into the second category only in extreme situations: either
|
| 6447 | |
your files may be used without being configured, or they are used during
|
| 6448 | |
the configuration. In most cases the traditional approach is enough.
|
| 6449 | |
|
| 6450 | |
This macro caches its results in @code{ac_cv_have_decl_@var{symbol}}
|
| 6451 | |
variables, with characters not suitable for a variable name mapped to
|
| 6452 | |
underscores.
|
| 6453 | |
@end defmac
|
| 6454 | |
|
| 6455 | |
@defmac AC_CHECK_DECLS_ONCE (@var{symbols})
|
| 6456 | |
@acindex{CHECK_DECLS_ONCE}
|
| 6457 | |
@cvindex HAVE_DECL_@var{symbol}
|
| 6458 | |
For each of the @var{symbols} (@emph{comma}-separated list), define
|
| 6459 | |
@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
|
| 6460 | |
@var{symbol} is declared in the default include files, otherwise to
|
| 6461 | |
@samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
|
| 6462 | |
generates the checking code at most once, so that @command{configure} is
|
| 6463 | |
smaller and faster; but the checks cannot be conditionalized and are
|
| 6464 | |
always done once, early during the @command{configure} run.
|
| 6465 | |
@end defmac
|
| 6466 | |
|
| 6467 | |
|
| 6468 | |
@node Structures
|
| 6469 | |
@section Structures
|
| 6470 | |
@cindex Structure, checking
|
| 6471 | |
|
| 6472 | |
The following macros check for the presence of certain members in C
|
| 6473 | |
structures. If there is no macro specifically defined to check for a
|
| 6474 | |
member you need, then you can use the general structure-member macros
|
| 6475 | |
(@pxref{Generic Structures}) or, for more complex tests, you may use
|
| 6476 | |
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
|
| 6477 | |
|
| 6478 | |
@menu
|
| 6479 | |
* Particular Structures:: Macros to check for certain structure members
|
| 6480 | |
* Generic Structures:: How to find other structure members
|
| 6481 | |
@end menu
|
| 6482 | |
|
| 6483 | |
@node Particular Structures
|
| 6484 | |
@subsection Particular Structure Checks
|
| 6485 | |
|
| 6486 | |
The following macros check for certain structures or structure members.
|
| 6487 | |
|
| 6488 | |
@defmac AC_STRUCT_DIRENT_D_INO
|
| 6489 | |
@acindex{STRUCT_DIRENT_D_INO}
|
| 6490 | |
@cvindex HAVE_STRUCT_DIRENT_D_INO
|
| 6491 | |
@c @caindex header_dirent_dirent_h
|
| 6492 | |
@c @caindex member_struct_dirent_d_ino
|
| 6493 | |
Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
|
| 6494 | |
Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
|
| 6495 | |
member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
|
| 6496 | |
|
| 6497 | |
@code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
|
| 6498 | |
@code{d_ino}, not whether its contents are always reliable.
|
| 6499 | |
Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
|
| 6500 | |
though current systems hide this detail from the user and never return
|
| 6501 | |
zero @code{d_ino} values.
|
| 6502 | |
Many current systems report an incorrect @code{d_ino} for a directory
|
| 6503 | |
entry that is a mount point.
|
| 6504 | |
@end defmac
|
| 6505 | |
|
| 6506 | |
@defmac AC_STRUCT_DIRENT_D_TYPE
|
| 6507 | |
@acindex{STRUCT_DIRENT_D_TYPE}
|
| 6508 | |
@cvindex HAVE_STRUCT_DIRENT_D_TYPE
|
| 6509 | |
@c @caindex header_dirent_dirent_h
|
| 6510 | |
@c @caindex member_struct_dirent_d_type
|
| 6511 | |
Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
|
| 6512 | |
Headers}). Then, if @code{struct dirent} contains a @code{d_type}
|
| 6513 | |
member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
|
| 6514 | |
@end defmac
|
| 6515 | |
|
| 6516 | |
@anchor{AC_STRUCT_ST_BLOCKS}
|
| 6517 | |
@defmac AC_STRUCT_ST_BLOCKS
|
| 6518 | |
@acindex{STRUCT_ST_BLOCKS}
|
| 6519 | |
@cvindex HAVE_STRUCT_STAT_ST_BLOCKS
|
| 6520 | |
@cvindex HAVE_ST_BLOCKS
|
| 6521 | |
@ovindex LIBOBJS
|
| 6522 | |
@caindex member_struct_stat_st_blocks
|
| 6523 | |
If @code{struct stat} contains an @code{st_blocks} member, define
|
| 6524 | |
@code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
|
| 6525 | |
@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
|
| 6526 | |
@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
|
| 6527 | |
future.
|
| 6528 | |
|
| 6529 | |
This macro caches its result in the @code{ac_cv_member_struct_stat_st_blocks}
|
| 6530 | |
variable.
|
| 6531 | |
@end defmac
|
| 6532 | |
|
| 6533 | |
@defmac AC_STRUCT_TM
|
| 6534 | |
@acindex{STRUCT_TM}
|
| 6535 | |
@cvindex TM_IN_SYS_TIME
|
| 6536 | |
@hdrindex{time.h}
|
| 6537 | |
@hdrindex{sys/time.h}
|
| 6538 | |
If @file{time.h} does not define @code{struct tm}, define
|
| 6539 | |
@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
|
| 6540 | |
had better define @code{struct tm}.
|
| 6541 | |
|
| 6542 | |
This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
|
| 6543 | |
current systems. New programs need not use this macro.
|
| 6544 | |
@end defmac
|
| 6545 | |
|
| 6546 | |
@anchor{AC_STRUCT_TIMEZONE}
|
| 6547 | |
@defmac AC_STRUCT_TIMEZONE
|
| 6548 | |
@acindex{STRUCT_TIMEZONE}
|
| 6549 | |
@cvindex HAVE_DECL_TZNAME
|
| 6550 | |
@cvindex HAVE_STRUCT_TM_TM_ZONE
|
| 6551 | |
@cvindex HAVE_TM_ZONE
|
| 6552 | |
@cvindex HAVE_TZNAME
|
| 6553 | |
@c @caindex member_struct_tm_tm_zone
|
| 6554 | |
@c @caindex struct_tm
|
| 6555 | |
Figure out how to get the current timezone. If @code{struct tm} has a
|
| 6556 | |
@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
|
| 6557 | |
obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
|
| 6558 | |
@code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
|
| 6559 | |
define @code{HAVE_DECL_TZNAME}.
|
| 6560 | |
@end defmac
|
| 6561 | |
|
| 6562 | |
@node Generic Structures
|
| 6563 | |
@subsection Generic Structure Checks
|
| 6564 | |
|
| 6565 | |
These macros are used to find structure members not covered by the
|
| 6566 | |
``particular'' test macros.
|
| 6567 | |
|
| 6568 | |
@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @
|
| 6569 | |
@ovar{action-if-found}, @ovar{action-if-not-found}, @
|
| 6570 | |
@dvar{includes, AC_INCLUDES_DEFAULT})
|
| 6571 | |
@acindex{CHECK_MEMBER}
|
| 6572 | |
@caindex member_@var{aggregate}_@var{member}
|
| 6573 | |
Check whether @var{member} is a member of the aggregate @var{aggregate}.
|
| 6574 | |
If no @var{includes} are specified, the default includes are used
|
| 6575 | |
(@pxref{Default Includes}).
|
| 6576 | |
|
| 6577 | |
@example
|
| 6578 | |
AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
|
| 6579 | |
[AC_MSG_ERROR([we need `passwd.pw_gecos'])],
|
| 6580 | |
[[#include <pwd.h>]])
|
| 6581 | |
@end example
|
| 6582 | |
|
| 6583 | |
You can use this macro for submembers:
|
| 6584 | |
|
| 6585 | |
@example
|
| 6586 | |
AC_CHECK_MEMBER(struct top.middle.bot)
|
| 6587 | |
@end example
|
| 6588 | |
|
| 6589 | |
This macro caches its result in the
|
| 6590 | |
@code{ac_cv_member_@var{aggregate}_@var{member}} variable, with
|
| 6591 | |
characters not suitable for a variable name mapped to underscores.
|
| 6592 | |
@end defmac
|
| 6593 | |
|
| 6594 | |
@anchor{AC_CHECK_MEMBERS}
|
| 6595 | |
@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @
|
| 6596 | |
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
|
| 6597 | |
@acindex{CHECK_MEMBERS}
|
| 6598 | |
@cvindex HAVE_@var{aggregate}_@var{member}
|
| 6599 | |
Check for the existence of each @samp{@var{aggregate}.@var{member}} of
|
| 6600 | |
@var{members} using the previous macro. When @var{member} belongs to
|
| 6601 | |
@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
|
| 6602 | |
capitals, with spaces and dots replaced by underscores). If
|
| 6603 | |
@var{action-if-found} is given, it is executed for each of the found
|
| 6604 | |
members. If @var{action-if-not-found} is given, it is executed for each
|
| 6605 | |
of the members that could not be found.
|
| 6606 | |
|
| 6607 | |
@var{includes} is a series of include directives, defaulting to
|
| 6608 | |
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
|
| 6609 | |
prior to the members under test.
|
| 6610 | |
|
| 6611 | |
This macro uses M4 lists:
|
| 6612 | |
@example
|
| 6613 | |
AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
|
| 6614 | |
@end example
|
| 6615 | |
@end defmac
|
| 6616 | |
|
| 6617 | |
|
| 6618 | |
@node Types
|
| 6619 | |
@section Types
|
| 6620 | |
@cindex Types
|
| 6621 | |
@cindex C types
|
| 6622 | |
|
| 6623 | |
The following macros check for C types, either builtin or typedefs. If
|
| 6624 | |
there is no macro specifically defined to check for a type you need, and
|
| 6625 | |
you don't need to check for any special properties of it, then you can
|
| 6626 | |
use a general type-check macro.
|
| 6627 | |
|
| 6628 | |
@menu
|
| 6629 | |
* Particular Types:: Special handling to find certain types
|
| 6630 | |
* Generic Types:: How to find other types
|
| 6631 | |
@end menu
|
| 6632 | |
|
| 6633 | |
@node Particular Types
|
| 6634 | |
@subsection Particular Type Checks
|
| 6635 | |
|
| 6636 | |
@hdrindex{sys/types.h}
|
| 6637 | |
@hdrindex{stdlib.h}
|
| 6638 | |
@hdrindex{stdint.h}
|
| 6639 | |
@hdrindex{inttypes.h}
|
| 6640 | |
These macros check for particular C types in @file{sys/types.h},
|
| 6641 | |
@file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
|
| 6642 | |
exist.
|
| 6643 | |
|
| 6644 | |
The Gnulib @code{stdint} module is an alternate way to define many of
|
| 6645 | |
these symbols; it is useful if you prefer your code to assume a
|
| 6646 | |
C99-or-better environment. @xref{Gnulib}.
|
| 6647 | |
|
| 6648 | |
@anchor{AC_TYPE_GETGROUPS}
|
| 6649 | |
@defmac AC_TYPE_GETGROUPS
|
| 6650 | |
@acindex{TYPE_GETGROUPS}
|
| 6651 | |
@cvindex GETGROUPS_T
|
| 6652 | |
@caindex type_getgroups
|
| 6653 | |
Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
|
| 6654 | |
is the base type of the array argument to @code{getgroups}.
|
| 6655 | |
|
| 6656 | |
This macro caches the base type in the @code{ac_cv_type_getgroups}
|
| 6657 | |
variable.
|
| 6658 | |
@end defmac
|
| 6659 | |
|
| 6660 | |
@defmac AC_TYPE_INT8_T
|
| 6661 | |
@acindex{TYPE_INT8_T}
|
| 6662 | |
@cvindex HAVE_INT8_T
|
| 6663 | |
@cvindex int8_t
|
| 6664 | |
@caindex c_int8_t
|
| 6665 | |
If @file{stdint.h} or @file{inttypes.h} does not define the type
|
| 6666 | |
@code{int8_t}, define @code{int8_t} to a signed
|
| 6667 | |
integer type that is exactly 8 bits wide and that uses two's complement
|
| 6668 | |
representation, if such a type exists.
|
| 6669 | |
If you are worried about porting to hosts that lack such a type, you can
|
| 6670 | |
use the results of this macro in C89-or-later code as follows:
|
| 6671 | |
|
| 6672 | |
@example
|
| 6673 | |
#if HAVE_STDINT_H
|
| 6674 | |
# include <stdint.h>
|
| 6675 | |
#endif
|
| 6676 | |
#if defined INT8_MAX || defined int8_t
|
| 6677 | |
@emph{code using int8_t}
|
| 6678 | |
#else
|
| 6679 | |
@emph{complicated alternative using >8-bit 'signed char'}
|
| 6680 | |
#endif
|
| 6681 | |
@end example
|
| 6682 | |
|
| 6683 | |
This macro caches the type in the @code{ac_cv_c_int8_t} variable.
|
| 6684 | |
@end defmac
|
| 6685 | |
|
| 6686 | |
@defmac AC_TYPE_INT16_T
|
| 6687 | |
@acindex{TYPE_INT16_T}
|
| 6688 | |
@cvindex HAVE_INT16_T
|
| 6689 | |
@cvindex int16_t
|
| 6690 | |
@caindex c_int16_t
|
| 6691 | |
This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
|
| 6692 | |
@end defmac
|
| 6693 | |
|
| 6694 | |
@defmac AC_TYPE_INT32_T
|
| 6695 | |
@acindex{TYPE_INT32_T}
|
| 6696 | |
@cvindex HAVE_INT32_T
|
| 6697 | |
@cvindex int32_t
|
| 6698 | |
@caindex c_int32_t
|
| 6699 | |
This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
|
| 6700 | |
@end defmac
|
| 6701 | |
|
| 6702 | |
@defmac AC_TYPE_INT64_T
|
| 6703 | |
@acindex{TYPE_INT64_T}
|
| 6704 | |
@cvindex HAVE_INT64_T
|
| 6705 | |
@cvindex int64_t
|
| 6706 | |
@caindex c_int64_t
|
| 6707 | |
This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
|
| 6708 | |
@end defmac
|
| 6709 | |
|
| 6710 | |
@defmac AC_TYPE_INTMAX_T
|
| 6711 | |
@acindex{TYPE_INTMAX_T}
|
| 6712 | |
@cvindex HAVE_INTMAX_T
|
| 6713 | |
@cvindex intmax_t
|
| 6714 | |
@c @caindex type_intmax_t
|
| 6715 | |
If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
|
| 6716 | |
define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
|
| 6717 | |
widest signed integer type.
|
| 6718 | |
@end defmac
|
| 6719 | |
|
| 6720 | |
@defmac AC_TYPE_INTPTR_T
|
| 6721 | |
@acindex{TYPE_INTPTR_T}
|
| 6722 | |
@cvindex HAVE_INTPTR_T
|
| 6723 | |
@cvindex intptr_t
|
| 6724 | |
@c @caindex type_intptr_t
|
| 6725 | |
If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
|
| 6726 | |
define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
|
| 6727 | |
signed integer type wide enough to hold a pointer, if such a type
|
| 6728 | |
exists.
|
| 6729 | |
@end defmac
|
| 6730 | |
|
| 6731 | |
@defmac AC_TYPE_LONG_DOUBLE
|
| 6732 | |
@acindex{TYPE_LONG_DOUBLE}
|
| 6733 | |
@cvindex HAVE_LONG_DOUBLE
|
| 6734 | |
@caindex type_long_double
|
| 6735 | |
If the C compiler supports a working @code{long double} type, define
|
| 6736 | |
@code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
|
| 6737 | |
same range and precision as @code{double}.
|
| 6738 | |
|
| 6739 | |
This macro caches its result in the @code{ac_cv_type_long_double}
|
| 6740 | |
variable.
|
| 6741 | |
|
| 6742 | |
This macro is obsolescent, as current C compilers support @code{long
|
| 6743 | |
double}. New programs need not use this macro.
|
| 6744 | |
@end defmac
|
| 6745 | |
|
| 6746 | |
@defmac AC_TYPE_LONG_DOUBLE_WIDER
|
| 6747 | |
@acindex{TYPE_LONG_DOUBLE_WIDER}
|
| 6748 | |
@cvindex HAVE_LONG_DOUBLE_WIDER
|
| 6749 | |
@caindex type_long_double_wider
|
| 6750 | |
If the C compiler supports a working @code{long double} type with more
|
| 6751 | |
range or precision than the @code{double} type, define
|
| 6752 | |
@code{HAVE_LONG_DOUBLE_WIDER}.
|
| 6753 | |
|
| 6754 | |
This macro caches its result in the @code{ac_cv_type_long_double_wider}
|
| 6755 | |
variable.
|
| 6756 | |
@end defmac
|
| 6757 | |
|
| 6758 | |
@defmac AC_TYPE_LONG_LONG_INT
|
| 6759 | |
@acindex{TYPE_LONG_LONG_INT}
|
| 6760 | |
@cvindex HAVE_LONG_LONG_INT
|
| 6761 | |
@caindex type_long_long_int
|
| 6762 | |
If the C compiler supports a working @code{long long int} type, define
|
| 6763 | |
@code{HAVE_LONG_LONG_INT}. However, this test does not test
|
| 6764 | |
@code{long long int} values in preprocessor @code{#if} expressions,
|
| 6765 | |
because too many compilers mishandle such expressions.
|
| 6766 | |
@xref{Preprocessor Arithmetic}.
|
| 6767 | |
|
| 6768 | |
This macro caches its result in the @code{ac_cv_type_long_long_int}
|
| 6769 | |
variable.
|
| 6770 | |
@end defmac
|
| 6771 | |
|
| 6772 | |
@defmac AC_TYPE_MBSTATE_T
|
| 6773 | |
@acindex{TYPE_MBSTATE_T}
|
| 6774 | |
@cvindex mbstate_t
|
| 6775 | |
@hdrindex{wchar.h}
|
| 6776 | |
@caindex type_mbstate_t
|
| 6777 | |
Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
|
| 6778 | |
@code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
|
| 6779 | |
@code{<wchar.h>} does not declare it.
|
| 6780 | |
|
| 6781 | |
This macro caches its result in the @code{ac_cv_type_mbstate_t}
|
| 6782 | |
variable.
|
| 6783 | |
@end defmac
|
| 6784 | |
|
| 6785 | |
@anchor{AC_TYPE_MODE_T}
|
| 6786 | |
@defmac AC_TYPE_MODE_T
|
| 6787 | |
@acindex{TYPE_MODE_T}
|
| 6788 | |
@cvindex mode_t
|
| 6789 | |
@caindex type_mode_t
|
| 6790 | |
Define @code{mode_t} to a suitable type, if standard headers do not
|
| 6791 | |
define it.
|
| 6792 | |
|
| 6793 | |
This macro caches its result in the @code{ac_cv_type_mode_t} variable.
|
| 6794 | |
@end defmac
|
| 6795 | |
|
| 6796 | |
@anchor{AC_TYPE_OFF_T}
|
| 6797 | |
@defmac AC_TYPE_OFF_T
|
| 6798 | |
@acindex{TYPE_OFF_T}
|
| 6799 | |
@cvindex off_t
|
| 6800 | |
@caindex type_off_t
|
| 6801 | |
Define @code{off_t} to a suitable type, if standard headers do not
|
| 6802 | |
define it.
|
| 6803 | |
|
| 6804 | |
This macro caches its result in the @code{ac_cv_type_off_t} variable.
|
| 6805 | |
@end defmac
|
| 6806 | |
|
| 6807 | |
@anchor{AC_TYPE_PID_T}
|
| 6808 | |
@defmac AC_TYPE_PID_T
|
| 6809 | |
@acindex{TYPE_PID_T}
|
| 6810 | |
@cvindex pid_t
|
| 6811 | |
@caindex type_pid_t
|
| 6812 | |
Define @code{pid_t} to a suitable type, if standard headers do not
|
| 6813 | |
define it.
|
| 6814 | |
|
| 6815 | |
This macro caches its result in the @code{ac_cv_type_pid_t} variable.
|
| 6816 | |
@end defmac
|
| 6817 | |
|
| 6818 | |
@anchor{AC_TYPE_SIZE_T}
|
| 6819 | |
@defmac AC_TYPE_SIZE_T
|
| 6820 | |
@acindex{TYPE_SIZE_T}
|
| 6821 | |
@cvindex size_t
|
| 6822 | |
@caindex type_size_t
|
| 6823 | |
Define @code{size_t} to a suitable type, if standard headers do not
|
| 6824 | |
define it.
|
| 6825 | |
|
| 6826 | |
This macro caches its result in the @code{ac_cv_type_size_t} variable.
|
| 6827 | |
@end defmac
|
| 6828 | |
|
| 6829 | |
@defmac AC_TYPE_SSIZE_T
|
| 6830 | |
@acindex{TYPE_SSIZE_T}
|
| 6831 | |
@cvindex ssize_t
|
| 6832 | |
@caindex type_ssize_t
|
| 6833 | |
Define @code{ssize_t} to a suitable type, if standard headers do not
|
| 6834 | |
define it.
|
| 6835 | |
|
| 6836 | |
This macro caches its result in the @code{ac_cv_type_ssize_t} variable.
|
| 6837 | |
@end defmac
|
| 6838 | |
|
| 6839 | |
@anchor{AC_TYPE_UID_T}
|
| 6840 | |
@defmac AC_TYPE_UID_T
|
| 6841 | |
@acindex{TYPE_UID_T}
|
| 6842 | |
@cvindex uid_t
|
| 6843 | |
@cvindex gid_t
|
| 6844 | |
@caindex type_uid_t
|
| 6845 | |
Define @code{uid_t} and @code{gid_t} to suitable types, if standard
|
| 6846 | |
headers do not define them.
|
| 6847 | |
|
| 6848 | |
This macro caches its result in the @code{ac_cv_type_uid_t} variable.
|
| 6849 | |
@end defmac
|
| 6850 | |
|
| 6851 | |
@defmac AC_TYPE_UINT8_T
|
| 6852 | |
@acindex{TYPE_UINT8_T}
|
| 6853 | |
@cvindex HAVE_UINT8_T
|
| 6854 | |
@cvindex uint8_t
|
| 6855 | |
@caindex c_uint8_t
|
| 6856 | |
If @file{stdint.h} or @file{inttypes.h} does not define the type
|
| 6857 | |
@code{uint8_t}, define @code{uint8_t} to an
|
| 6858 | |
unsigned integer type that is exactly 8 bits wide, if such a type
|
| 6859 | |
exists.
|
| 6860 | |
This is like @code{AC_TYPE_INT8_T}, except for unsigned integers.
|
| 6861 | |
@end defmac
|
| 6862 | |
|
| 6863 | |
@defmac AC_TYPE_UINT16_T
|
| 6864 | |
@acindex{TYPE_UINT16_T}
|
| 6865 | |
@cvindex HAVE_UINT16_T
|
| 6866 | |
@cvindex uint16_t
|
| 6867 | |
@caindex c_uint16_t
|
| 6868 | |
This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers.
|
| 6869 | |
@end defmac
|
| 6870 | |
|
| 6871 | |
@defmac AC_TYPE_UINT32_T
|
| 6872 | |
@acindex{TYPE_UINT32_T}
|
| 6873 | |
@cvindex HAVE_UINT32_T
|
| 6874 | |
@cvindex uint32_t
|
| 6875 | |
@caindex c_uint32_t
|
| 6876 | |
This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers.
|
| 6877 | |
@end defmac
|
| 6878 | |
|
| 6879 | |
@defmac AC_TYPE_UINT64_T
|
| 6880 | |
@acindex{TYPE_UINT64_T}
|
| 6881 | |
@cvindex HAVE_UINT64_T
|
| 6882 | |
@cvindex uint64_t
|
| 6883 | |
@caindex c_uint64_t
|
| 6884 | |
This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers.
|
| 6885 | |
@end defmac
|
| 6886 | |
|
| 6887 | |
@defmac AC_TYPE_UINTMAX_T
|
| 6888 | |
@acindex{TYPE_UINTMAX_T}
|
| 6889 | |
@cvindex HAVE_UINTMAX_T
|
| 6890 | |
@cvindex uintmax_t
|
| 6891 | |
@c @caindex type_uintmax_t
|
| 6892 | |
If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
|
| 6893 | |
define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
|
| 6894 | |
widest unsigned integer type.
|
| 6895 | |
@end defmac
|
| 6896 | |
|
| 6897 | |
@defmac AC_TYPE_UINTPTR_T
|
| 6898 | |
@acindex{TYPE_UINTPTR_T}
|
| 6899 | |
@cvindex HAVE_UINTPTR_T
|
| 6900 | |
@cvindex uintptr_t
|
| 6901 | |
@c @caindex type_uintptr_t
|
| 6902 | |
If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
|
| 6903 | |
define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
|
| 6904 | |
unsigned integer type wide enough to hold a pointer, if such a type
|
| 6905 | |
exists.
|
| 6906 | |
@end defmac
|
| 6907 | |
|
| 6908 | |
@defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
|
| 6909 | |
@acindex{TYPE_UNSIGNED_LONG_LONG_INT}
|
| 6910 | |
@cvindex HAVE_UNSIGNED_LONG_LONG_INT
|
| 6911 | |
@caindex type_unsigned_long_long_int
|
| 6912 | |
If the C compiler supports a working @code{unsigned long long int} type,
|
| 6913 | |
define @code{HAVE_UNSIGNED_LONG_LONG_INT}. However, this test does not test
|
| 6914 | |
@code{unsigned long long int} values in preprocessor @code{#if} expressions,
|
| 6915 | |
because too many compilers mishandle such expressions.
|
| 6916 | |
@xref{Preprocessor Arithmetic}.
|
| 6917 | |
|
| 6918 | |
This macro caches its result in the @code{ac_cv_type_unsigned_long_long_int}
|
| 6919 | |
variable.
|
| 6920 | |
@end defmac
|
| 6921 | |
|
| 6922 | |
@node Generic Types
|
| 6923 | |
@subsection Generic Type Checks
|
| 6924 | |
|
| 6925 | |
These macros are used to check for types not covered by the ``particular''
|
| 6926 | |
test macros.
|
| 6927 | |
|
| 6928 | |
@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @
|
| 6929 | |
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
|
| 6930 | |
@acindex{CHECK_TYPE}
|
| 6931 | |
@caindex type_@var{type}
|
| 6932 | |
Check whether @var{type} is defined. It may be a compiler builtin type
|
| 6933 | |
or defined by the @var{includes}. @var{includes} is a series of include
|
| 6934 | |
directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default
|
| 6935 | |
Includes}), which are used prior to the type under test.
|
| 6936 | |
|
| 6937 | |
In C, @var{type} must be a type-name, so that the expression @samp{sizeof
|
| 6938 | |
(@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The
|
| 6939 | |
same test is applied when compiling for C++, which means that in C++
|
| 6940 | |
@var{type} should be a type-id and should not be an anonymous
|
| 6941 | |
@samp{struct} or @samp{union}.
|
| 6942 | |
|
| 6943 | |
This macro caches its result in the @code{ac_cv_type_@var{type}}
|
| 6944 | |
variable, with @samp{*} mapped to @samp{p} and other characters not
|
| 6945 | |
suitable for a variable name mapped to underscores.
|
| 6946 | |
@end defmac
|
| 6947 | |
|
| 6948 | |
|
| 6949 | |
@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @
|
| 6950 | |
@ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
|
| 6951 | |
@acindex{CHECK_TYPES}
|
| 6952 | |
@cvindex HAVE_@var{type}
|
| 6953 | |
For each @var{type} of the @var{types} that is defined, define
|
| 6954 | |
@code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow
|
| 6955 | |
the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are
|
| 6956 | |
specified, the default includes are used (@pxref{Default Includes}). If
|
| 6957 | |
@var{action-if-found} is given, it is additional shell code to execute
|
| 6958 | |
when one of the types is found. If @var{action-if-not-found} is given,
|
| 6959 | |
it is executed when one of the types is not found.
|
| 6960 | |
|
| 6961 | |
This macro uses M4 lists:
|
| 6962 | |
@example
|
| 6963 | |
AC_CHECK_TYPES([ptrdiff_t])
|
| 6964 | |
AC_CHECK_TYPES([unsigned long long int, uintmax_t])
|
| 6965 | |
AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]])
|
| 6966 | |
@end example
|
| 6967 | |
|
| 6968 | |
@end defmac
|
| 6969 | |
|
| 6970 | |
Autoconf, up to 2.13, used to provide to another version of
|
| 6971 | |
@code{AC_CHECK_TYPE}, broken by design. In order to keep backward
|
| 6972 | |
compatibility, a simple heuristic, quite safe but not totally, is
|
| 6973 | |
implemented. In case of doubt, read the documentation of the former
|
| 6974 | |
@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
|
| 6975 | |
|
| 6976 | |
|
| 6977 | |
@node Compilers and Preprocessors
|
| 6978 | |
@section Compilers and Preprocessors
|
| 6979 | |
@cindex Compilers
|
| 6980 | |
@cindex Preprocessors
|
| 6981 | |
|
| 6982 | |
@ovindex EXEEXT
|
| 6983 | |
All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
|
| 6984 | |
@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
|
| 6985 | |
the output of the compiler, typically to the empty string if
|
| 6986 | |
Posix and @samp{.exe} if a DOS variant.
|
| 6987 | |
|
| 6988 | |
@ovindex OBJEXT
|
| 6989 | |
They also define the output variable @code{OBJEXT} based on the
|
| 6990 | |
output of the compiler, after @file{.c} files have been excluded, typically
|
| 6991 | |
to @samp{o} if Posix, @samp{obj} if a DOS variant.
|
| 6992 | |
|
| 6993 | |
If the compiler being used does not produce executables, the tests fail. If
|
| 6994 | |
the executables can't be run, and cross-compilation is not enabled, they
|
| 6995 | |
fail too. @xref{Manual Configuration}, for more on support for cross
|
| 6996 | |
compiling.
|
| 6997 | |
|
| 6998 | |
@menu
|
| 6999 | |
* Specific Compiler Characteristics:: Some portability issues
|
| 7000 | |
* Generic Compiler Characteristics:: Language independent tests and features
|
| 7001 | |
* C Compiler:: Checking its characteristics
|
| 7002 | |
* C++ Compiler:: Likewise
|
| 7003 | |
* Objective C Compiler:: Likewise
|
| 7004 | |
* Objective C++ Compiler:: Likewise
|
| 7005 | |
* Erlang Compiler and Interpreter:: Likewise
|
| 7006 | |
* Fortran Compiler:: Likewise
|
| 7007 | |
* Go Compiler:: Likewise
|
| 7008 | |
@end menu
|
| 7009 | |
|
| 7010 | |
@node Specific Compiler Characteristics
|
| 7011 | |
@subsection Specific Compiler Characteristics
|
| 7012 | |
|
| 7013 | |
Some compilers exhibit different behaviors.
|
| 7014 | |
|
| 7015 | |
@table @asis
|
| 7016 | |
@item Static/Dynamic Expressions
|
| 7017 | |
Autoconf relies on a trick to extract one bit of information from the C
|
| 7018 | |
compiler: using negative array sizes. For instance the following
|
| 7019 | |
excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
|
| 7020 | |
bytes wide:
|
| 7021 | |
|
| 7022 | |
@example
|
| 7023 | |
static int test_array[sizeof (int) == 4 ? 1 : -1];
|
| 7024 | |
@end example
|
| 7025 | |
|
| 7026 | |
@noindent
|
| 7027 | |
To our knowledge, there is a single compiler that does not support this
|
| 7028 | |
trick: the HP C compilers (the real ones, not only the
|
| 7029 | |
``bundled'') on HP-UX 11.00.
|
| 7030 | |
They incorrectly reject the above program with the diagnostic
|
| 7031 | |
``Variable-length arrays cannot have static storage.''
|
| 7032 | |
This bug comes from HP compilers' mishandling of @code{sizeof (int)},
|
| 7033 | |
not from the @code{? 1 : -1}, and
|
| 7034 | |
Autoconf works around this problem by casting @code{sizeof (int)} to
|
| 7035 | |
@code{long int} before comparing it.
|
| 7036 | |
@end table
|
| 7037 | |
|
| 7038 | |
@node Generic Compiler Characteristics
|
| 7039 | |
@subsection Generic Compiler Characteristics
|
| 7040 | |
|
| 7041 | |
@anchor{AC_CHECK_SIZEOF}
|
| 7042 | |
@defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @
|
| 7043 | |
@dvar{includes, AC_INCLUDES_DEFAULT})
|
| 7044 | |
@acindex{CHECK_SIZEOF}
|
| 7045 | |
@cvindex SIZEOF_@var{type-or-expr}
|
| 7046 | |
@caindex sizeof_@var{type-or-expr}
|
| 7047 | |
Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be
|
| 7048 | |
the size in bytes of @var{type-or-expr}, which may be either a type or
|
| 7049 | |
an expression returning a value that has a size. If the expression
|
| 7050 | |
@samp{sizeof (@var{type-or-expr})} is invalid, the result is 0.
|
| 7051 | |
@var{includes} is a series of include directives, defaulting to
|
| 7052 | |
@code{AC_INCLUDES_DEFAULT} (@pxref{Default Includes}), which are used
|
| 7053 | |
prior to the expression under test.
|
| 7054 | |
|
| 7055 | |
This macro now works even when cross-compiling. The @var{unused}
|
| 7056 | |
argument was used when cross-compiling.
|
| 7057 | |
|
| 7058 | |
For example, the call
|
| 7059 | |
|
| 7060 | |
@example
|
| 7061 | |
@c If you change this example, adjust tests/semantics.at:AC_CHECK_SIZEOF struct.
|
| 7062 | |
AC_CHECK_SIZEOF([int *])
|
| 7063 | |
@end example
|
| 7064 | |
|
| 7065 | |
@noindent
|
| 7066 | |
defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
|
| 7067 | |
|
| 7068 | |
This macro caches its result in the @code{ac_cv_sizeof_@var{type-or-expr}}
|
| 7069 | |
variable, with @samp{*} mapped to @samp{p} and other characters not
|
| 7070 | |
suitable for a variable name mapped to underscores.
|
| 7071 | |
@end defmac
|
| 7072 | |
|
| 7073 | |
@defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, AC_INCLUDES_DEFAULT})
|
| 7074 | |
@acindex{CHECK_ALIGNOF}
|
| 7075 | |
@cvindex ALIGNOF_@var{type}
|
| 7076 | |
@caindex alignof_@var{type-or-expr}
|
| 7077 | |
Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
|
| 7078 | |
alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as
|
| 7079 | |
a structure member declaration. If @samp{type} is unknown, the result
|
| 7080 | |
is 0. If no @var{includes} are specified, the default includes are used
|
| 7081 | |
(@pxref{Default Includes}).
|
| 7082 | |
|
| 7083 | |
This macro caches its result in the @code{ac_cv_alignof_@var{type-or-expr}}
|
| 7084 | |
variable, with @samp{*} mapped to @samp{p} and other characters not
|
| 7085 | |
suitable for a variable name mapped to underscores.
|
| 7086 | |
@end defmac
|
| 7087 | |
|
| 7088 | |
@defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @
|
| 7089 | |
@dvar{includes, AC_INCLUDES_DEFAULT}, @ovar{action-if-fails})
|
| 7090 | |
@acindex{COMPUTE_INT}
|
| 7091 | |
Store into the shell variable @var{var} the value of the integer
|
| 7092 | |
@var{expression}. The
|
| 7093 | |
value should fit in an initializer in a C variable of type @code{signed
|
| 7094 | |
long}. To support cross compilation (in which case, the macro only works on
|
| 7095 | |
hosts that use twos-complement arithmetic), it should be possible to evaluate
|
| 7096 | |
the expression at compile-time. If no @var{includes} are specified, the
|
| 7097 | |
default includes are used (@pxref{Default Includes}).
|
| 7098 | |
|
| 7099 | |
Execute @var{action-if-fails} if the value cannot be determined correctly.
|
| 7100 | |
@end defmac
|
| 7101 | |
|
| 7102 | |
@defmac AC_LANG_WERROR
|
| 7103 | |
@acindex{LANG_WERROR}
|
| 7104 | |
Normally Autoconf ignores warnings generated by the compiler, linker, and
|
| 7105 | |
preprocessor. If this macro is used, warnings count as fatal
|
| 7106 | |
errors for the current language. This macro is useful when the
|
| 7107 | |
results of configuration are used where warnings are unacceptable; for
|
| 7108 | |
instance, if parts of a program are built with the GCC
|
| 7109 | |
@option{-Werror}
|
| 7110 | |
option. If the whole program is built using @option{-Werror} it is
|
| 7111 | |
often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
|
| 7112 | |
etc.).
|
| 7113 | |
@end defmac
|
| 7114 | |
|
| 7115 | |
@defmac AC_OPENMP
|
| 7116 | |
@acindex{OPENMP}
|
| 7117 | |
@cvindex _OPENMP
|
| 7118 | |
@ovindex OPENMP_CFLAGS
|
| 7119 | |
@ovindex OPENMP_CXXFLAGS
|
| 7120 | |
@ovindex OPENMP_FFLAGS
|
| 7121 | |
@ovindex OPENMP_FCFLAGS
|
| 7122 | |
@caindex prog_c_openmp
|
| 7123 | |
@caindex prog_cxx_openmp
|
| 7124 | |
@caindex prog_f77_openmp
|
| 7125 | |
@caindex prog_fc_openmp
|
| 7126 | |
@uref{http://@/www.openmp.org/, OpenMP} specifies extensions of C, C++,
|
| 7127 | |
and Fortran that simplify optimization of shared memory parallelism,
|
| 7128 | |
which is a common problem on multicore CPUs.
|
| 7129 | |
|
| 7130 | |
If the current language is C, the macro @code{AC_OPENMP} sets the
|
| 7131 | |
variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
|
| 7132 | |
supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the
|
| 7133 | |
compiler already supports OpenMP, if it has no way to activate OpenMP
|
| 7134 | |
support, or if the user rejects OpenMP support by invoking
|
| 7135 | |
@samp{configure} with the @samp{--disable-openmp} option.
|
| 7136 | |
|
| 7137 | |
@code{OPENMP_CFLAGS} needs to be used when compiling programs, when
|
| 7138 | |
preprocessing program source, and when linking programs. Therefore you
|
| 7139 | |
need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
|
| 7140 | |
that use OpenMP@. If you preprocess OpenMP-specific C code, you also
|
| 7141 | |
need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of
|
| 7142 | |
OpenMP support is revealed at compile time by the preprocessor macro
|
| 7143 | |
@code{_OPENMP}.
|
| 7144 | |
|
| 7145 | |
Linking a program with @code{OPENMP_CFLAGS} typically adds one more
|
| 7146 | |
shared library to the program's dependencies, so its use is recommended
|
| 7147 | |
only on programs that actually require OpenMP.
|
| 7148 | |
|
| 7149 | |
If the current language is C++, @code{AC_OPENMP} sets the variable
|
| 7150 | |
@code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks
|
| 7151 | |
hold as for C.
|
| 7152 | |
|
| 7153 | |
If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
|
| 7154 | |
the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
|
| 7155 | |
respectively. Similar remarks as for C hold, except that
|
| 7156 | |
@code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
|
| 7157 | |
signals OpenMP support.
|
| 7158 | |
|
| 7159 | |
For portability, it is best to avoid spaces between @samp{#} and
|
| 7160 | |
@samp{pragma omp}. That is, write @samp{#pragma omp}, not
|
| 7161 | |
@samp{# pragma omp}. The Sun WorkShop 6.2 C compiler chokes on the
|
| 7162 | |
latter.
|
| 7163 | |
|
| 7164 | |
This macro caches its result in the @code{ac_cv_prog_c_openmp},
|
| 7165 | |
@code{ac_cv_prog_cxx_openmp}, @code{ac_cv_prog_f77_openmp}, or
|
| 7166 | |
@code{ac_cv_prog_fc_openmp} variable, depending on the current language.
|
| 7167 | |
@end defmac
|
| 7168 | |
|
| 7169 | |
@node C Compiler
|
| 7170 | |
@subsection C Compiler Characteristics
|
| 7171 | |
|
| 7172 | |
The following macros provide ways to find and exercise a C Compiler.
|
| 7173 | |
There are a few constructs that ought to be avoided, but do not deserve
|
| 7174 | |
being checked for, since they can easily be worked around.
|
| 7175 | |
|
| 7176 | |
@table @asis
|
| 7177 | |
@item Don't use lines containing solitary backslashes
|
| 7178 | |
They tickle a bug in the HP-UX C compiler (checked on
|
| 7179 | |
HP-UX 10.20,
|
| 7180 | |
11.00, and 11i). When given the following source:
|
| 7181 | |
|
| 7182 | |
@example
|
| 7183 | |
#ifdef __STDC__
|
| 7184 | |
/\
|
| 7185 | |
* A comment with backslash-newlines in it. %@{ %@} *\
|
| 7186 | |
\
|
| 7187 | |
/
|
| 7188 | |
char str[] = "\\
|
| 7189 | |
" A string with backslash-newlines in it %@{ %@} \\
|
| 7190 | |
"";
|
| 7191 | |
char apostrophe = '\\
|
| 7192 | |
\
|
| 7193 | |
'\
|
| 7194 | |
';
|
| 7195 | |
#endif
|
| 7196 | |
@end example
|
| 7197 | |
|
| 7198 | |
@noindent
|
| 7199 | |
the compiler incorrectly fails with the diagnostics ``Non-terminating
|
| 7200 | |
comment at end of file'' and ``Missing @samp{#endif} at end of file.''
|
| 7201 | |
Removing the lines with solitary backslashes solves the problem.
|
| 7202 | |
|
| 7203 | |
@item Don't compile several files at once if output matters to you
|
| 7204 | |
Some compilers, such as HP's, report names of files being
|
| 7205 | |
compiled when given more than one file operand. For instance:
|
| 7206 | |
|
| 7207 | |
@example
|
| 7208 | |
$ @kbd{cc a.c b.c}
|
| 7209 | |
a.c:
|
| 7210 | |
b.c:
|
| 7211 | |
@end example
|
| 7212 | |
|
| 7213 | |
@noindent
|
| 7214 | |
This can cause problems if you observe the output of the compiler to
|
| 7215 | |
detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
|
| 7216 | |
b.o} solves the issue.
|
| 7217 | |
|
| 7218 | |
@item Don't rely on @code{#error} failing
|
| 7219 | |
The IRIX C compiler does not fail when #error is preprocessed; it
|
| 7220 | |
simply emits a diagnostic and continues, exiting successfully. So,
|
| 7221 | |
instead of an error directive like @code{#error "Unsupported word size"}
|
| 7222 | |
it is more portable to use an invalid directive like @code{#Unsupported
|
| 7223 | |
word size} in Autoconf tests. In ordinary source code, @code{#error} is
|
| 7224 | |
OK, since installers with inadequate compilers like IRIX can simply
|
| 7225 | |
examine these compilers' diagnostic output.
|
| 7226 | |
|
| 7227 | |
@item Don't rely on correct @code{#line} support
|
| 7228 | |
On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
|
| 7229 | |
diagnoses @code{#line} directives whose line
|
| 7230 | |
numbers are greater than 32767. Nothing in Posix
|
| 7231 | |
makes this invalid. That is why Autoconf stopped issuing
|
| 7232 | |
@code{#line} directives.
|
| 7233 | |
@end table
|
| 7234 | |
|
| 7235 | |
@defmac AC_PROG_CC (@ovar{compiler-search-list})
|
| 7236 | |
@acindex{PROG_CC}
|
| 7237 | |
@evindex CC
|
| 7238 | |
@evindex CFLAGS
|
| 7239 | |
@ovindex CC
|
| 7240 | |
@ovindex CFLAGS
|
| 7241 | |
@caindex prog_cc_c89
|
| 7242 | |
Determine a C compiler to use. If @code{CC} is not already set in the
|
| 7243 | |
environment, check for @code{gcc} and @code{cc}, then for other C
|
| 7244 | |
compilers. Set output variable @code{CC} to the name of the compiler
|
| 7245 | |
found.
|
| 7246 | |
|
| 7247 | |
This macro may, however, be invoked with an optional first argument
|
| 7248 | |
which, if specified, must be a blank-separated list of C compilers to
|
| 7249 | |
search for. This just gives the user an opportunity to specify an
|
| 7250 | |
alternative search list for the C compiler. For example, if you didn't
|
| 7251 | |
like the default order, then you could invoke @code{AC_PROG_CC} like
|
| 7252 | |
this:
|
| 7253 | |
|
| 7254 | |
@example
|
| 7255 | |
AC_PROG_CC([gcc cl cc])
|
| 7256 | |
@end example
|
| 7257 | |
|
| 7258 | |
If the C compiler does not handle function prototypes correctly by
|
| 7259 | |
default, try to add an option to output variable @code{CC} to make it
|
| 7260 | |
so. This macro tries various options that select standard-conformance
|
| 7261 | |
modes on various systems.
|
| 7262 | |
|
| 7263 | |
After calling this macro you can check whether the C compiler has been
|
| 7264 | |
set to accept ANSI C89 (ISO C90); if not, the shell
|
| 7265 | |
variable
|
| 7266 | |
@code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
|
| 7267 | |
@code{AC_C_PROTOTYPES} below.
|
| 7268 | |
|
| 7269 | |
If using the GNU C compiler, set shell variable @code{GCC} to
|
| 7270 | |
@samp{yes}. If output variable @code{CFLAGS} was not already set, set
|
| 7271 | |
it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems
|
| 7272 | |
where GCC does not accept @option{-g}), or @option{-g} for
|
| 7273 | |
other compilers. If your package does not like this default, then it is
|
| 7274 | |
acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT}
|
| 7275 | |
and before @code{AC_PROG_CC} to select an empty default instead.
|
| 7276 | |
|
| 7277 | |
Many Autoconf macros use a compiler, and thus call
|
| 7278 | |
@samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been
|
| 7279 | |
determined before the body of the outermost @code{AC_DEFUN} macro.
|
| 7280 | |
Although @code{AC_PROG_CC} is safe to directly expand multiple times, it
|
| 7281 | |
performs certain checks (such as the proper value of @env{EXEEXT}) only
|
| 7282 | |
on the first invocation. Therefore, care must be used when invoking
|
| 7283 | |
this macro from within another macro rather than at the top level
|
| 7284 | |
(@pxref{Expanded Before Required}).
|
| 7285 | |
@end defmac
|
| 7286 | |
|
| 7287 | |
@anchor{AC_PROG_CC_C_O}
|
| 7288 | |
@defmac AC_PROG_CC_C_O
|
| 7289 | |
@acindex{PROG_CC_C_O}
|
| 7290 | |
@cvindex NO_MINUS_C_MINUS_O
|
| 7291 | |
@caindex prog_cc_@var{compiler}_c_o
|
| 7292 | |
If the C compiler does not accept the @option{-c} and @option{-o} options
|
| 7293 | |
simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
|
| 7294 | |
tests both the compiler found by @code{AC_PROG_CC}, and, if different,
|
| 7295 | |
the first @code{cc} in the path. The test fails if one fails. This
|
| 7296 | |
macro was created for GNU Make to choose the default C compilation
|
| 7297 | |
rule.
|
| 7298 | |
|
| 7299 | |
For the compiler @var{compiler}, this macro caches its result in the
|
| 7300 | |
@code{ac_cv_prog_cc_@var{compiler}_c_o} variable.
|
| 7301 | |
@end defmac
|
| 7302 | |
|
| 7303 | |
|
| 7304 | |
@defmac AC_PROG_CPP
|
| 7305 | |
@acindex{PROG_CPP}
|
| 7306 | |
@evindex CPP
|
| 7307 | |
@ovindex CPP
|
| 7308 | |
Set output variable @code{CPP} to a command that runs the
|
| 7309 | |
C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
|
| 7310 | |
It is only portable to run @code{CPP} on files with a @file{.c}
|
| 7311 | |
extension.
|
| 7312 | |
|
| 7313 | |
Some preprocessors don't indicate missing include files by the error
|
| 7314 | |
status. For such preprocessors an internal variable is set that causes
|
| 7315 | |
other macros to check the standard error from the preprocessor and
|
| 7316 | |
consider the test failed if any warnings have been reported.
|
| 7317 | |
For most preprocessors, though, warnings do not cause include-file
|
| 7318 | |
tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
|
| 7319 | |
@end defmac
|
| 7320 | |
|
| 7321 | |
@defmac AC_PROG_CPP_WERROR
|
| 7322 | |
@acindex{PROG_CPP_WERROR}
|
| 7323 | |
@ovindex CPP
|
| 7324 | |
This acts like @code{AC_PROG_CPP}, except it treats warnings from the
|
| 7325 | |
preprocessor as errors even if the preprocessor exit status indicates
|
| 7326 | |
success. This is useful for avoiding headers that generate mandatory
|
| 7327 | |
warnings, such as deprecation notices.
|
| 7328 | |
@end defmac
|
| 7329 | |
|
| 7330 | |
|
| 7331 | |
The following macros check for C compiler or machine architecture
|
| 7332 | |
features. To check for characteristics not listed here, use
|
| 7333 | |
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
|
| 7334 | |
@code{AC_RUN_IFELSE} (@pxref{Runtime}).
|
| 7335 | |
|
| 7336 | |
@defmac AC_PROG_CC_STDC
|
| 7337 | |
@acindex{PROG_CC_STDC}
|
| 7338 | |
@caindex prog_cc_stdc
|
| 7339 | |
If the C compiler cannot compile ISO Standard C (currently
|
| 7340 | |
C99), try to add an option to output variable @code{CC} to make it work.
|
| 7341 | |
If the compiler does not support C99, fall back to supporting
|
| 7342 | |
ANSI C89 (ISO C90).
|
| 7343 | |
|
| 7344 | |
After calling this macro you can check whether the C compiler has been
|
| 7345 | |
set to accept Standard C; if not, the shell variable
|
| 7346 | |
@code{ac_cv_prog_cc_stdc} is set to @samp{no}.
|
| 7347 | |
@end defmac
|
| 7348 | |
|
| 7349 | |
@defmac AC_PROG_CC_C89
|
| 7350 | |
@acindex{PROG_CC_C89}
|
| 7351 | |
@caindex prog_cc_c89
|
| 7352 | |
If the C compiler is not in ANSI C89 (ISO C90) mode by
|
| 7353 | |
default, try to add an option to output variable @code{CC} to make it
|
| 7354 | |
so. This macro tries various options that select ANSI C89 on
|
| 7355 | |
some system or another, preferring extended functionality modes over
|
| 7356 | |
strict conformance modes. It considers the compiler to be in
|
| 7357 | |
ANSI C89 mode if it handles function prototypes correctly.
|
| 7358 | |
|
| 7359 | |
After calling this macro you can check whether the C compiler has been
|
| 7360 | |
set to accept ANSI C89; if not, the shell variable
|
| 7361 | |
@code{ac_cv_prog_cc_c89} is set to @samp{no}.
|
| 7362 | |
|
| 7363 | |
This macro is called automatically by @code{AC_PROG_CC}.
|
| 7364 | |
@end defmac
|
| 7365 | |
|
| 7366 | |
@defmac AC_PROG_CC_C99
|
| 7367 | |
@acindex{PROG_CC_C99}
|
| 7368 | |
@caindex prog_cc_c99
|
| 7369 | |
If the C compiler is not in C99 mode by default, try to add an
|
| 7370 | |
option to output variable @code{CC} to make it so. This macro tries
|
| 7371 | |
various options that select C99 on some system or another, preferring
|
| 7372 | |
extended functionality modes over strict conformance modes. It
|
| 7373 | |
considers the compiler to be in C99 mode if it handles @code{_Bool},
|
| 7374 | |
@code{//} comments, flexible array members, @code{inline}, signed and
|
| 7375 | |
unsigned @code{long long int}, mixed code and declarations, named
|
| 7376 | |
initialization of structs,
|
| 7377 | |
@code{restrict}, @code{va_copy}, varargs macros, variable declarations
|
| 7378 | |
in @code{for} loops, and variable length arrays.
|
| 7379 | |
|
| 7380 | |
After calling this macro you can check whether the C compiler has been
|
| 7381 | |
set to accept C99; if not, the shell variable
|
| 7382 | |
@code{ac_cv_prog_cc_c99} is set to @samp{no}.
|
| 7383 | |
@end defmac
|
| 7384 | |
|
| 7385 | |
@defmac AC_C_BACKSLASH_A
|
| 7386 | |
@acindex{C_BACKSLASH_A}
|
| 7387 | |
@cvindex HAVE_C_BACKSLASH_A
|
| 7388 | |
Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
|
| 7389 | |
@samp{\a}.
|
| 7390 | |
|
| 7391 | |
This macro is obsolescent, as current C compilers understand @samp{\a}.
|
| 7392 | |
New programs need not use this macro.
|
| 7393 | |
@end defmac
|
| 7394 | |
|
| 7395 | |
@anchor{AC_C_BIGENDIAN}
|
| 7396 | |
@defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @
|
| 7397 | |
@ovar{action-if-unknown}, @ovar{action-if-universal})
|
| 7398 | |
@acindex{C_BIGENDIAN}
|
| 7399 | |
@cvindex WORDS_BIGENDIAN
|
| 7400 | |
@cindex Endianness
|
| 7401 | |
If words are stored with the most significant byte first (like Motorola
|
| 7402 | |
and SPARC CPUs), execute @var{action-if-true}. If words are stored with
|
| 7403 | |
the least significant byte first (like Intel and VAX CPUs), execute
|
| 7404 | |
@var{action-if-false}.
|
| 7405 | |
|
| 7406 | |
This macro runs a test-case if endianness cannot be determined from the
|
| 7407 | |
system header files. When cross-compiling, the test-case is not run but
|
| 7408 | |
grep'ed for some magic values. @var{action-if-unknown} is executed if
|
| 7409 | |
the latter case fails to determine the byte sex of the host system.
|
| 7410 | |
|
| 7411 | |
In some cases a single run of a compiler can generate code for multiple
|
| 7412 | |
architectures. This can happen, for example, when generating Mac OS X
|
| 7413 | |
universal binary files, which work on both PowerPC and Intel
|
| 7414 | |
architectures. In this case, the different variants might be for
|
| 7415 | |
different architectures whose endiannesses differ. If
|
| 7416 | |
@command{configure} detects this, it executes @var{action-if-universal}
|
| 7417 | |
instead of @var{action-if-unknown}.
|
| 7418 | |
|
| 7419 | |
The default for @var{action-if-true} is to define
|
| 7420 | |
@samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
|
| 7421 | |
nothing. The default for @var{action-if-unknown} is to
|
| 7422 | |
abort configure and tell the installer how to bypass this test.
|
| 7423 | |
And finally, the default for @var{action-if-universal} is to ensure that
|
| 7424 | |
@samp{WORDS_BIGENDIAN} is defined if and only if a universal build is
|
| 7425 | |
detected and the current code is big-endian; this default works only if
|
| 7426 | |
@command{autoheader} is used (@pxref{autoheader Invocation}).
|
| 7427 | |
|
| 7428 | |
If you use this macro without specifying @var{action-if-universal}, you
|
| 7429 | |
should also use @code{AC_CONFIG_HEADERS}; otherwise
|
| 7430 | |
@samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
|
| 7431 | |
binary files.
|
| 7432 | |
@end defmac
|
| 7433 | |
|
| 7434 | |
@anchor{AC_C_CONST}
|
| 7435 | |
@defmac AC_C_CONST
|
| 7436 | |
@acindex{C_CONST}
|
| 7437 | |
@cvindex const
|
| 7438 | |
@caindex c_const
|
| 7439 | |
If the C compiler does not fully support the @code{const} keyword,
|
| 7440 | |
define @code{const} to be empty. Some C compilers that do
|
| 7441 | |
not define @code{__STDC__} do support @code{const}; some compilers that
|
| 7442 | |
define @code{__STDC__} do not completely support @code{const}. Programs
|
| 7443 | |
can simply use @code{const} as if every C compiler supported it; for
|
| 7444 | |
those that don't, the makefile or configuration header file
|
| 7445 | |
defines it as empty.
|
| 7446 | |
|
| 7447 | |
Occasionally installers use a C++ compiler to compile C code, typically
|
| 7448 | |
because they lack a C compiler. This causes problems with @code{const},
|
| 7449 | |
because C and C++ treat @code{const} differently. For example:
|
| 7450 | |
|
| 7451 | |
@example
|
| 7452 | |
const int foo;
|
| 7453 | |
@end example
|
| 7454 | |
|
| 7455 | |
@noindent
|
| 7456 | |
is valid in C but not in C++. These differences unfortunately cannot be
|
| 7457 | |
papered over by defining @code{const} to be empty.
|
| 7458 | |
|
| 7459 | |
If @command{autoconf} detects this situation, it leaves @code{const} alone,
|
| 7460 | |
as this generally yields better results in practice. However, using a
|
| 7461 | |
C++ compiler to compile C code is not recommended or supported, and
|
| 7462 | |
installers who run into trouble in this area should get a C compiler
|
| 7463 | |
like GCC to compile their C code.
|
| 7464 | |
|
| 7465 | |
This macro caches its result in the @code{ac_cv_c_const} variable.
|
| 7466 | |
|
| 7467 | |
This macro is obsolescent, as current C compilers support @code{const}.
|
| 7468 | |
New programs need not use this macro.
|
| 7469 | |
@end defmac
|
| 7470 | |
|
| 7471 | |
@defmac AC_C_RESTRICT
|
| 7472 | |
@acindex{C_RESTRICT}
|
| 7473 | |
@cvindex restrict
|
| 7474 | |
@caindex c_restrict
|
| 7475 | |
If the C compiler recognizes a variant spelling for the @code{restrict}
|
| 7476 | |
keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
|
| 7477 | |
then define @code{restrict} to that; this is more likely to do the right
|
| 7478 | |
thing with compilers that support language variants where plain
|
| 7479 | |
@code{restrict} is not a keyword. Otherwise, if the C compiler
|
| 7480 | |
recognizes the @code{restrict} keyword, don't do anything.
|
| 7481 | |
Otherwise, define @code{restrict} to be empty.
|
| 7482 | |
Thus, programs may simply use @code{restrict} as if every C compiler
|
| 7483 | |
supported it; for those that do not, the makefile
|
| 7484 | |
or configuration header defines it away.
|
| 7485 | |
|
| 7486 | |
Although support in C++ for the @code{restrict} keyword is not
|
| 7487 | |
required, several C++ compilers do accept the keyword.
|
| 7488 | |
This macro works for them, too.
|
| 7489 | |
|
| 7490 | |
This macro caches @samp{no} in the @code{ac_cv_c_restrict} variable
|
| 7491 | |
if @code{restrict} is not supported, and a supported spelling otherwise.
|
| 7492 | |
@end defmac
|
| 7493 | |
|
| 7494 | |
@defmac AC_C_VOLATILE
|
| 7495 | |
@acindex{C_VOLATILE}
|
| 7496 | |
@cvindex volatile
|
| 7497 | |
If the C compiler does not understand the keyword @code{volatile},
|
| 7498 | |
define @code{volatile} to be empty. Programs can simply use
|
| 7499 | |
@code{volatile} as if every C compiler supported it; for those that do
|
| 7500 | |
not, the makefile or configuration header defines it as
|
| 7501 | |
empty.
|
| 7502 | |
|
| 7503 | |
If the correctness of your program depends on the semantics of
|
| 7504 | |
@code{volatile}, simply defining it to be empty does, in a sense, break
|
| 7505 | |
your code. However, given that the compiler does not support
|
| 7506 | |
@code{volatile}, you are at its mercy anyway. At least your
|
| 7507 | |
program compiles, when it wouldn't before.
|
| 7508 | |
@xref{Volatile Objects}, for more about @code{volatile}.
|
| 7509 | |
|
| 7510 | |
In general, the @code{volatile} keyword is a standard C feature, so
|
| 7511 | |
you might expect that @code{volatile} is available only when
|
| 7512 | |
@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
|
| 7513 | |
support volatile, but does not define @code{__STDC__}.
|
| 7514 | |
|
| 7515 | |
This macro is obsolescent, as current C compilers support @code{volatile}.
|
| 7516 | |
New programs need not use this macro.
|
| 7517 | |
@end defmac
|
| 7518 | |
|
| 7519 | |
@anchor{AC_C_INLINE}
|
| 7520 | |
@defmac AC_C_INLINE
|
| 7521 | |
@acindex{C_INLINE}
|
| 7522 | |
@cvindex inline
|
| 7523 | |
If the C compiler supports the keyword @code{inline}, do nothing.
|
| 7524 | |
Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
|
| 7525 | |
if it accepts one of those, otherwise define @code{inline} to be empty.
|
| 7526 | |
@end defmac
|
| 7527 | |
|
| 7528 | |
@anchor{AC_C_CHAR_UNSIGNED}
|
| 7529 | |
@defmac AC_C_CHAR_UNSIGNED
|
| 7530 | |
@acindex{C_CHAR_UNSIGNED}
|
| 7531 | |
@cvindex __CHAR_UNSIGNED__
|
| 7532 | |
If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
|
| 7533 | |
unless the C compiler predefines it.
|
| 7534 | |
|
| 7535 | |
These days, using this macro is not necessary. The same information can
|
| 7536 | |
be determined by this portable alternative, thus avoiding the use of
|
| 7537 | |
preprocessor macros in the namespace reserved for the implementation.
|
| 7538 | |
|
| 7539 | |
@example
|
| 7540 | |
#include <limits.h>
|
| 7541 | |
#if CHAR_MIN == 0
|
| 7542 | |
# define CHAR_UNSIGNED 1
|
| 7543 | |
#endif
|
| 7544 | |
@end example
|
| 7545 | |
@end defmac
|
| 7546 | |
|
| 7547 | |
@defmac AC_C_STRINGIZE
|
| 7548 | |
@acindex{C_STRINGIZE}
|
| 7549 | |
@cvindex HAVE_STRINGIZE
|
| 7550 | |
If the C preprocessor supports the stringizing operator, define
|
| 7551 | |
@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
|
| 7552 | |
found in macros such as this:
|
| 7553 | |
|
| 7554 | |
@example
|
| 7555 | |
#define x(y) #y
|
| 7556 | |
@end example
|
| 7557 | |
|
| 7558 | |
This macro is obsolescent, as current C compilers support the
|
| 7559 | |
stringizing operator. New programs need not use this macro.
|
| 7560 | |
@end defmac
|
| 7561 | |
|
| 7562 | |
@defmac AC_C_FLEXIBLE_ARRAY_MEMBER
|
| 7563 | |
@acindex{C_FLEXIBLE_ARRAY_MEMBER}
|
| 7564 | |
@cvindex FLEXIBLE_ARRAY_MEMBER
|
| 7565 | |
If the C compiler supports flexible array members, define
|
| 7566 | |
@code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
|
| 7567 | |
That way, a declaration like this:
|
| 7568 | |
|
| 7569 | |
@example
|
| 7570 | |
struct s
|
| 7571 | |
@{
|
| 7572 | |
size_t n_vals;
|
| 7573 | |
double val[FLEXIBLE_ARRAY_MEMBER];
|
| 7574 | |
@};
|
| 7575 | |
@end example
|
| 7576 | |
|
| 7577 | |
@noindent
|
| 7578 | |
will let applications use the ``struct hack'' even with compilers that
|
| 7579 | |
do not support flexible array members. To allocate and use such an
|
| 7580 | |
object, you can use code like this:
|
| 7581 | |
|
| 7582 | |
@example
|
| 7583 | |
size_t i;
|
| 7584 | |
size_t n = compute_value_count ();
|
| 7585 | |
struct s *p =
|
| 7586 | |
malloc (offsetof (struct s, val)
|
| 7587 | |
+ n * sizeof (double));
|
| 7588 | |
p->n_vals = n;
|
| 7589 | |
for (i = 0; i < n; i++)
|
| 7590 | |
p->val[i] = compute_value (i);
|
| 7591 | |
@end example
|
| 7592 | |
@end defmac
|
| 7593 | |
|
| 7594 | |
@defmac AC_C_VARARRAYS
|
| 7595 | |
@acindex{C_VARARRAYS}
|
| 7596 | |
@cvindex HAVE_C_VARARRAYS
|
| 7597 | |
If the C compiler supports variable-length arrays, define
|
| 7598 | |
@code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
|
| 7599 | |
storage duration whose length is determined at run time, when the array
|
| 7600 | |
is declared.
|
| 7601 | |
@end defmac
|
| 7602 | |
|
| 7603 | |
@defmac AC_C_TYPEOF
|
| 7604 | |
@acindex{C_TYPEOF}
|
| 7605 | |
@cvindex HAVE_TYPEOF
|
| 7606 | |
@cvindex typeof
|
| 7607 | |
If the C compiler supports GCC's @code{typeof} syntax either
|
| 7608 | |
directly or
|
| 7609 | |
through a different spelling of the keyword (e.g., @code{__typeof__}),
|
| 7610 | |
define @code{HAVE_TYPEOF}. If the support is available only through a
|
| 7611 | |
different spelling, define @code{typeof} to that spelling.
|
| 7612 | |
@end defmac
|
| 7613 | |
|
| 7614 | |
@defmac AC_C_PROTOTYPES
|
| 7615 | |
@acindex{C_PROTOTYPES}
|
| 7616 | |
@cvindex PROTOTYPES
|
| 7617 | |
@cvindex __PROTOTYPES
|
| 7618 | |
@cvindex PARAMS
|
| 7619 | |
If function prototypes are understood by the compiler (as determined by
|
| 7620 | |
@code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
|
| 7621 | |
Defining @code{__PROTOTYPES} is for the benefit of
|
| 7622 | |
header files that cannot use macros that infringe on user name space.
|
| 7623 | |
|
| 7624 | |
This macro is obsolescent, as current C compilers support prototypes.
|
| 7625 | |
New programs need not use this macro.
|
| 7626 | |
@end defmac
|
| 7627 | |
|
| 7628 | |
@anchor{AC_PROG_GCC_TRADITIONAL}
|
| 7629 | |
@defmac AC_PROG_GCC_TRADITIONAL
|
| 7630 | |
@acindex{PROG_GCC_TRADITIONAL}
|
| 7631 | |
@ovindex CC
|
| 7632 | |
Add @option{-traditional} to output variable @code{CC} if using the
|
| 7633 | |
GNU C compiler and @code{ioctl} does not work properly without
|
| 7634 | |
@option{-traditional}. That usually happens when the fixed header files
|
| 7635 | |
have not been installed on an old system.
|
| 7636 | |
|
| 7637 | |
This macro is obsolescent, since current versions of the GNU C
|
| 7638 | |
compiler fix the header files automatically when installed.
|
| 7639 | |
@end defmac
|
| 7640 | |
|
| 7641 | |
|
| 7642 | |
@node C++ Compiler
|
| 7643 | |
@subsection C++ Compiler Characteristics
|
| 7644 | |
|
| 7645 | |
|
| 7646 | |
@defmac AC_PROG_CXX (@ovar{compiler-search-list})
|
| 7647 | |
@acindex{PROG_CXX}
|
| 7648 | |
@evindex CXX
|
| 7649 | |
@evindex CXXFLAGS
|
| 7650 | |
@ovindex CXX
|
| 7651 | |
@ovindex CXXFLAGS
|
| 7652 | |
Determine a C++ compiler to use. Check whether the environment variable
|
| 7653 | |
@code{CXX} or @code{CCC} (in that order) is set; if so, then set output
|
| 7654 | |
variable @code{CXX} to its value.
|
| 7655 | |
|
| 7656 | |
Otherwise, if the macro is invoked without an argument, then search for
|
| 7657 | |
a C++ compiler under the likely names (first @code{g++} and @code{c++}
|
| 7658 | |
then other names). If none of those checks succeed, then as a last
|
| 7659 | |
resort set @code{CXX} to @code{g++}.
|
| 7660 | |
|
| 7661 | |
This macro may, however, be invoked with an optional first argument
|
| 7662 | |
which, if specified, must be a blank-separated list of C++ compilers to
|
| 7663 | |
search for. This just gives the user an opportunity to specify an
|
| 7664 | |
alternative search list for the C++ compiler. For example, if you
|
| 7665 | |
didn't like the default order, then you could invoke @code{AC_PROG_CXX}
|
| 7666 | |
like this:
|
| 7667 | |
|
| 7668 | |
@example
|
| 7669 | |
AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
|
| 7670 | |
@end example
|
| 7671 | |
|
| 7672 | |
If using the GNU C++ compiler, set shell variable @code{GXX} to
|
| 7673 | |
@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
|
| 7674 | |
it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on
|
| 7675 | |
systems where G++ does not accept @option{-g}), or @option{-g} for other
|
| 7676 | |
compilers. If your package does not like this default, then it is
|
| 7677 | |
acceptable to insert the line @samp{: $@{CXXFLAGS=""@}} after @code{AC_INIT}
|
| 7678 | |
and before @code{AC_PROG_CXX} to select an empty default instead.
|
| 7679 | |
|
| 7680 | |
@end defmac
|
| 7681 | |
|
| 7682 | |
@defmac AC_PROG_CXXCPP
|
| 7683 | |
@acindex{PROG_CXXCPP}
|
| 7684 | |
@evindex CXXCPP
|
| 7685 | |
@ovindex CXXCPP
|
| 7686 | |
Set output variable @code{CXXCPP} to a command that runs the C++
|
| 7687 | |
preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
|
| 7688 | |
It is portable to run @code{CXXCPP} only on files with a @file{.c},
|
| 7689 | |
@file{.C}, @file{.cc}, or @file{.cpp} extension.
|
| 7690 | |
|
| 7691 | |
Some preprocessors don't indicate missing include files by the error
|
| 7692 | |
status. For such preprocessors an internal variable is set that causes
|
| 7693 | |
other macros to check the standard error from the preprocessor and
|
| 7694 | |
consider the test failed if any warnings have been reported. However,
|
| 7695 | |
it is not known whether such broken preprocessors exist for C++.
|
| 7696 | |
@end defmac
|
| 7697 | |
|
| 7698 | |
@defmac AC_PROG_CXX_C_O
|
| 7699 | |
@acindex{PROG_CXX_C_O}
|
| 7700 | |
@cvindex CXX_NO_MINUS_C_MINUS_O
|
| 7701 | |
Test whether the C++ compiler accepts the options @option{-c} and
|
| 7702 | |
@option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
|
| 7703 | |
if it does not.
|
| 7704 | |
@end defmac
|
| 7705 | |
|
| 7706 | |
|
| 7707 | |
@node Objective C Compiler
|
| 7708 | |
@subsection Objective C Compiler Characteristics
|
| 7709 | |
|
| 7710 | |
|
| 7711 | |
@defmac AC_PROG_OBJC (@ovar{compiler-search-list})
|
| 7712 | |
@acindex{PROG_OBJC}
|
| 7713 | |
@evindex OBJC
|
| 7714 | |
@evindex OBJCFLAGS
|
| 7715 | |
@ovindex OBJC
|
| 7716 | |
@ovindex OBJCFLAGS
|
| 7717 | |
Determine an Objective C compiler to use. If @code{OBJC} is not already
|
| 7718 | |
set in the environment, check for Objective C compilers. Set output
|
| 7719 | |
variable @code{OBJC} to the name of the compiler found.
|
| 7720 | |
|
| 7721 | |
This macro may, however, be invoked with an optional first argument
|
| 7722 | |
which, if specified, must be a blank-separated list of Objective C compilers to
|
| 7723 | |
search for. This just gives the user an opportunity to specify an
|
| 7724 | |
alternative search list for the Objective C compiler. For example, if you
|
| 7725 | |
didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
|
| 7726 | |
like this:
|
| 7727 | |
|
| 7728 | |
@example
|
| 7729 | |
AC_PROG_OBJC([gcc objcc objc])
|
| 7730 | |
@end example
|
| 7731 | |
|
| 7732 | |
If using the GNU Objective C compiler, set shell variable
|
| 7733 | |
@code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
|
| 7734 | |
already set, set it to @option{-g -O2} for the GNU Objective C
|
| 7735 | |
compiler (@option{-O2} on systems where @command{gcc} does not accept
|
| 7736 | |
@option{-g}), or @option{-g} for other compilers.
|
| 7737 | |
@end defmac
|
| 7738 | |
|
| 7739 | |
@defmac AC_PROG_OBJCPP
|
| 7740 | |
@acindex{PROG_OBJCPP}
|
| 7741 | |
@evindex OBJCPP
|
| 7742 | |
@ovindex OBJCPP
|
| 7743 | |
Set output variable @code{OBJCPP} to a command that runs the Objective C
|
| 7744 | |
preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
|
| 7745 | |
@end defmac
|
| 7746 | |
|
| 7747 | |
|
| 7748 | |
@node Objective C++ Compiler
|
| 7749 | |
@subsection Objective C++ Compiler Characteristics
|
| 7750 | |
|
| 7751 | |
|
| 7752 | |
@defmac AC_PROG_OBJCXX (@ovar{compiler-search-list})
|
| 7753 | |
@acindex{PROG_OBJCXX}
|
| 7754 | |
@evindex OBJCXX
|
| 7755 | |
@evindex OBJCXXFLAGS
|
| 7756 | |
@ovindex OBJCXX
|
| 7757 | |
@ovindex OBJCXXFLAGS
|
| 7758 | |
Determine an Objective C++ compiler to use. If @code{OBJCXX} is not already
|
| 7759 | |
set in the environment, check for Objective C++ compilers. Set output
|
| 7760 | |
variable @code{OBJCXX} to the name of the compiler found.
|
| 7761 | |
|
| 7762 | |
This macro may, however, be invoked with an optional first argument
|
| 7763 | |
which, if specified, must be a blank-separated list of Objective C++ compilers
|
| 7764 | |
to search for. This just gives the user an opportunity to specify an
|
| 7765 | |
alternative search list for the Objective C++ compiler. For example, if you
|
| 7766 | |
didn't like the default order, then you could invoke @code{AC_PROG_OBJCXX}
|
| 7767 | |
like this:
|
| 7768 | |
|
| 7769 | |
@example
|
| 7770 | |
AC_PROG_OBJCXX([gcc g++ objcc++ objcxx])
|
| 7771 | |
@end example
|
| 7772 | |
|
| 7773 | |
If using the GNU Objective C++ compiler, set shell variable
|
| 7774 | |
@code{GOBJCXX} to @samp{yes}. If output variable @code{OBJCXXFLAGS} was not
|
| 7775 | |
already set, set it to @option{-g -O2} for the GNU Objective C++
|
| 7776 | |
compiler (@option{-O2} on systems where @command{gcc} does not accept
|
| 7777 | |
@option{-g}), or @option{-g} for other compilers.
|
| 7778 | |
@end defmac
|
| 7779 | |
|
| 7780 | |
@defmac AC_PROG_OBJCXXCPP
|
| 7781 | |
@acindex{PROG_OBJCXXCPP}
|
| 7782 | |
@evindex OBJCXXCPP
|
| 7783 | |
@ovindex OBJCXXCPP
|
| 7784 | |
Set output variable @code{OBJCXXCPP} to a command that runs the Objective C++
|
| 7785 | |
preprocessor. If @samp{$OBJCXX -E} doesn't work, @file{/lib/cpp} is used.
|
| 7786 | |
@end defmac
|
| 7787 | |
|
| 7788 | |
|
| 7789 | |
@node Erlang Compiler and Interpreter
|
| 7790 | |
@subsection Erlang Compiler and Interpreter Characteristics
|
| 7791 | |
@cindex Erlang
|
| 7792 | |
|
| 7793 | |
Autoconf defines the following macros for determining paths to the essential
|
| 7794 | |
Erlang/OTP programs:
|
| 7795 | |
|
| 7796 | |
@defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 7797 | |
@acindex{ERLANG_PATH_ERLC}
|
| 7798 | |
@evindex ERLC
|
| 7799 | |
@evindex ERLCFLAGS
|
| 7800 | |
@ovindex ERLC
|
| 7801 | |
@ovindex ERLCFLAGS
|
| 7802 | |
Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
|
| 7803 | |
environment, check for @command{erlc}. Set output variable @code{ERLC} to the
|
| 7804 | |
complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
|
| 7805 | |
is not set in the environment, set it to an empty value.
|
| 7806 | |
|
| 7807 | |
The two optional arguments have the same meaning as the two last arguments of
|
| 7808 | |
macro @code{AC_PATH_PROG} for looking for the @command{erlc} program. For
|
| 7809 | |
example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
|
| 7810 | |
directory:
|
| 7811 | |
|
| 7812 | |
@example
|
| 7813 | |
AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
|
| 7814 | |
@end example
|
| 7815 | |
@end defmac
|
| 7816 | |
|
| 7817 | |
@defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH})
|
| 7818 | |
@acindex{ERLANG_NEED_ERLC}
|
| 7819 | |
A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
|
| 7820 | |
error message and exits the @command{configure} script if the @command{erlc}
|
| 7821 | |
program is not found.
|
| 7822 | |
@end defmac
|
| 7823 | |
|
| 7824 | |
@defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH})
|
| 7825 | |
@acindex{ERLANG_PATH_ERL}
|
| 7826 | |
@evindex ERL
|
| 7827 | |
@ovindex ERL
|
| 7828 | |
Determine an Erlang interpreter to use. If @code{ERL} is not already
|
| 7829 | |
set in the
|
| 7830 | |
environment, check for @command{erl}. Set output variable @code{ERL} to the
|
| 7831 | |
complete path of the interpreter command found.
|
| 7832 | |
|
| 7833 | |
The two optional arguments have the same meaning as the two last arguments of
|
| 7834 | |
macro @code{AC_PATH_PROG} for looking for the @command{erl} program. For
|
| 7835 | |
example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
|
| 7836 | |
directory:
|
| 7837 | |
|
| 7838 | |
@example
|
| 7839 | |
AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
|
| 7840 | |
@end example
|
| 7841 | |
@end defmac
|
| 7842 | |
|
| 7843 | |
@defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH})
|
| 7844 | |
@acindex{ERLANG_NEED_ERL}
|
| 7845 | |
A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
|
| 7846 | |
error message and exits the @command{configure} script if the @command{erl}
|
| 7847 | |
program is not found.
|
| 7848 | |
@end defmac
|
| 7849 | |
|
| 7850 | |
|
| 7851 | |
@node Fortran Compiler
|
| 7852 | |
@subsection Fortran Compiler Characteristics
|
| 7853 | |
@cindex Fortran
|
| 7854 | |
@cindex F77
|
| 7855 | |
|
| 7856 | |
The Autoconf Fortran support is divided into two categories: legacy
|
| 7857 | |
Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
|
| 7858 | |
The former are intended for traditional Fortran 77 code, and have output
|
| 7859 | |
variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
|
| 7860 | |
are for newer programs that can (or must) compile under the newer
|
| 7861 | |
Fortran standards, and have output variables like @code{FC},
|
| 7862 | |
@code{FCFLAGS}, and @code{FCLIBS}.
|
| 7863 | |
|
| 7864 | |
Except for the macros @code{AC_FC_SRCEXT}, @code{AC_FC_FREEFORM},
|
| 7865 | |
@code{AC_FC_FIXEDFORM}, and @code{AC_FC_LINE_LENGTH} (see below), the
|
| 7866 | |
@code{FC} and @code{F77} macros behave almost identically, and so they
|
| 7867 | |
are documented together in this section.
|
| 7868 | |
|
| 7869 | |
|
| 7870 | |
@defmac AC_PROG_F77 (@ovar{compiler-search-list})
|
| 7871 | |
@acindex{PROG_F77}
|
| 7872 | |
@evindex F77
|
| 7873 | |
@evindex FFLAGS
|
| 7874 | |
@ovindex F77
|
| 7875 | |
@ovindex FFLAGS
|
| 7876 | |
@caindex f77_compiler_gnu
|
| 7877 | |
@caindex prog_f77_g
|
| 7878 | |
Determine a Fortran 77 compiler to use. If @code{F77} is not already
|
| 7879 | |
set in the environment, then check for @code{g77} and @code{f77}, and
|
| 7880 | |
then some other names. Set the output variable @code{F77} to the name
|
| 7881 | |
of the compiler found.
|
| 7882 | |
|
| 7883 | |
This macro may, however, be invoked with an optional first argument
|
| 7884 | |
which, if specified, must be a blank-separated list of Fortran 77
|
| 7885 | |
compilers to search for. This just gives the user an opportunity to
|
| 7886 | |
specify an alternative search list for the Fortran 77 compiler. For
|
| 7887 | |
example, if you didn't like the default order, then you could invoke
|
| 7888 | |
@code{AC_PROG_F77} like this:
|
| 7889 | |
|
| 7890 | |
@example
|
| 7891 | |
AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
|
| 7892 | |
@end example
|
| 7893 | |
|
| 7894 | |
If using @code{g77} (the GNU Fortran 77 compiler), then
|
| 7895 | |
set the shell variable @code{G77} to @samp{yes}.
|
| 7896 | |
If the output variable @code{FFLAGS} was not already set in the
|
| 7897 | |
environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
|
| 7898 | |
where @code{g77} does not accept @option{-g}). Otherwise, set
|
| 7899 | |
@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
|
| 7900 | |
|
| 7901 | |
The result of the GNU test is cached in the
|
| 7902 | |
@code{ac_cv_f77_compiler_gnu} variable, acceptance of @option{-g} in the
|
| 7903 | |
@code{ac_cv_prog_f77_g} variable.
|
| 7904 | |
@end defmac
|
| 7905 | |
|
| 7906 | |
@defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
|
| 7907 | |
@acindex{PROG_FC}
|
| 7908 | |
@evindex FC
|
| 7909 | |
@evindex FCFLAGS
|
| 7910 | |
@ovindex FC
|
| 7911 | |
@ovindex FCFLAGS
|
| 7912 | |
@caindex fc_compiler_gnu
|
| 7913 | |
@caindex prog_fc_g
|
| 7914 | |
Determine a Fortran compiler to use. If @code{FC} is not already set in
|
| 7915 | |
the environment, then @code{dialect} is a hint to indicate what Fortran
|
| 7916 | |
dialect to search for; the default is to search for the newest available
|
| 7917 | |
dialect. Set the output variable @code{FC} to the name of the compiler
|
| 7918 | |
found.
|
| 7919 | |
|
| 7920 | |
By default, newer dialects are preferred over older dialects, but if
|
| 7921 | |
@code{dialect} is specified then older dialects are preferred starting
|
| 7922 | |
with the specified dialect. @code{dialect} can currently be one of
|
| 7923 | |
Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
|
| 7924 | |
which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
|
| 7925 | |
and no attempt is made to guarantee that a particular language standard
|
| 7926 | |
is actually supported. Thus, it is preferable that you avoid the
|
| 7927 | |
@code{dialect} option, and use AC_PROG_FC only for code compatible with
|
| 7928 | |
the latest Fortran standard.
|
| 7929 | |
|
| 7930 | |
This macro may, alternatively, be invoked with an optional first argument
|
| 7931 | |
which, if specified, must be a blank-separated list of Fortran
|
| 7932 | |
compilers to search for, just as in @code{AC_PROG_F77}.
|
| 7933 | |
|
| 7934 | |
If using @code{gfortran} or @code{g77} (the GNU Fortran compilers), then
|
| 7935 | |
set the shell variable @code{GFC} to @samp{yes}.
|
| 7936 | |
If the output variable @code{FCFLAGS} was not already set in the
|
| 7937 | |
environment, then set it to @option{-g -02} for GNU @code{g77} (or
|
| 7938 | |
@option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
|
| 7939 | |
set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
|
| 7940 | |
|
| 7941 | |
The result of the GNU test is cached in the @code{ac_cv_fc_compiler_gnu}
|
| 7942 | |
variable, acceptance of @option{-g} in the @code{ac_cv_prog_fc_g}
|
| 7943 | |
variable.
|
| 7944 | |
@end defmac
|
| 7945 | |
|
| 7946 | |
@defmac AC_PROG_F77_C_O
|
| 7947 | |
@defmacx AC_PROG_FC_C_O
|
| 7948 | |
@acindex{PROG_F77_C_O}
|
| 7949 | |
@acindex{PROG_FC_C_O}
|
| 7950 | |
@cvindex F77_NO_MINUS_C_MINUS_O
|
| 7951 | |
@cvindex FC_NO_MINUS_C_MINUS_O
|
| 7952 | |
@caindex prog_f77_c_o
|
| 7953 | |
@caindex prog_fc_c_o
|
| 7954 | |
Test whether the Fortran compiler accepts the options @option{-c} and
|
| 7955 | |
@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
|
| 7956 | |
@code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
|
| 7957 | |
|
| 7958 | |
The result of the test is cached in the @code{ac_cv_prog_f77_c_o} or
|
| 7959 | |
@code{ac_cv_prog_fc_c_o} variable, respectively.
|
| 7960 | |
@end defmac
|
| 7961 | |
|
| 7962 | |
The following macros check for Fortran compiler characteristics.
|
| 7963 | |
To check for characteristics not listed here, use
|
| 7964 | |
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
|
| 7965 | |
@code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
|
| 7966 | |
current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
|
| 7967 | |
or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
|
| 7968 | |
|
| 7969 | |
|
| 7970 | |
@defmac AC_F77_LIBRARY_LDFLAGS
|
| 7971 | |
@defmacx AC_FC_LIBRARY_LDFLAGS
|
| 7972 | |
@acindex{F77_LIBRARY_LDFLAGS}
|
| 7973 | |
@ovindex FLIBS
|
| 7974 | |
@acindex{FC_LIBRARY_LDFLAGS}
|
| 7975 | |
@ovindex FCLIBS
|
| 7976 | |
@caindex prog_f77_v
|
| 7977 | |
@caindex prog_fc_v
|
| 7978 | |
@caindex f77_libs
|
| 7979 | |
@caindex fc_libs
|
| 7980 | |
Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
|
| 7981 | |
@dfn{Fortran intrinsic and runtime libraries} that are required to
|
| 7982 | |
successfully link a Fortran program or shared library. The output
|
| 7983 | |
variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
|
| 7984 | |
should be included after @code{LIBS} when linking).
|
| 7985 | |
|
| 7986 | |
This macro is intended to be used in those situations when it is
|
| 7987 | |
necessary to mix, e.g., C++ and Fortran source code in a single
|
| 7988 | |
program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
|
| 7989 | |
automake, GNU Automake}).
|
| 7990 | |
|
| 7991 | |
For example, if object files from a C++ and Fortran compiler must be
|
| 7992 | |
linked together, then the C++ compiler/linker must be used for linking
|
| 7993 | |
(since special C++-ish things need to happen at link time like calling
|
| 7994 | |
global constructors, instantiating templates, enabling exception
|
| 7995 | |
support, etc.).
|
| 7996 | |
|
| 7997 | |
However, the Fortran intrinsic and runtime libraries must be linked in
|
| 7998 | |
as well, but the C++ compiler/linker doesn't know by default how to add
|
| 7999 | |
these Fortran 77 libraries. Hence, this macro was created to determine
|
| 8000 | |
these Fortran libraries.
|
| 8001 | |
|
| 8002 | |
The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
|
| 8003 | |
@code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
|
| 8004 | |
link C/C++ with Fortran; see below. Further, it is highly recommended
|
| 8005 | |
that you use @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers})
|
| 8006 | |
because the complex defines that the function wrapper macros create
|
| 8007 | |
may not work with C/C++ compiler drivers.
|
| 8008 | |
|
| 8009 | |
These macros internally compute the flag needed to verbose linking
|
| 8010 | |
output and cache it in @code{ac_cv_prog_f77_v} or @code{ac_cv_prog_fc_v}
|
| 8011 | |
variables, respectively. The computed linker flags are cached in
|
| 8012 | |
@code{ac_cv_f77_libs} or @code{ac_cv_fc_libs}, respectively.
|
| 8013 | |
@end defmac
|
| 8014 | |
|
| 8015 | |
@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
|
| 8016 | |
AC_MSG_FAILURE})
|
| 8017 | |
@defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
|
| 8018 | |
AC_MSG_FAILURE})
|
| 8019 | |
@acindex{F77_DUMMY_MAIN}
|
| 8020 | |
@cvindex F77_DUMMY_MAIN
|
| 8021 | |
@acindex{FC_DUMMY_MAIN}
|
| 8022 | |
@cvindex FC_DUMMY_MAIN
|
| 8023 | |
@caindex f77_dummy_main
|
| 8024 | |
@caindex fc_dummy_main
|
| 8025 | |
With many compilers, the Fortran libraries detected by
|
| 8026 | |
@code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
|
| 8027 | |
their own @code{main} entry function that initializes things like
|
| 8028 | |
Fortran I/O, and which then calls a user-provided entry function named
|
| 8029 | |
(say) @code{MAIN__} to run the user's program. The
|
| 8030 | |
@code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
|
| 8031 | |
@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
|
| 8032 | |
this interaction.
|
| 8033 | |
|
| 8034 | |
When using Fortran for purely numerical functions (no I/O, etc.)@: often
|
| 8035 | |
one prefers to provide one's own @code{main} and skip the Fortran
|
| 8036 | |
library initializations. In this case, however, one may still need to
|
| 8037 | |
provide a dummy @code{MAIN__} routine in order to prevent linking errors
|
| 8038 | |
on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
|
| 8039 | |
detects whether any such routine is @emph{required} for linking, and
|
| 8040 | |
what its name is; the shell variable @code{F77_DUMMY_MAIN} or
|
| 8041 | |
@code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
|
| 8042 | |
was found, and @code{none} when no such dummy main is needed.
|
| 8043 | |
|
| 8044 | |
By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
|
| 8045 | |
@code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
|
| 8046 | |
@emph{if} it is required. @var{action-if-not-found} defaults to
|
| 8047 | |
exiting with an error.
|
| 8048 | |
|
| 8049 | |
In order to link with Fortran routines, the user's C/C++ program should
|
| 8050 | |
then include the following code to define the dummy main if it is
|
| 8051 | |
needed:
|
| 8052 | |
|
| 8053 | |
@example
|
| 8054 | |
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
|
| 8055 | |
#ifdef F77_DUMMY_MAIN
|
| 8056 | |
# ifdef __cplusplus
|
| 8057 | |
extern "C"
|
| 8058 | |
# endif
|
| 8059 | |
int F77_DUMMY_MAIN () @{ return 1; @}
|
| 8060 | |
#endif
|
| 8061 | |
@end example
|
| 8062 | |
|
| 8063 | |
(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
|
| 8064 | |
|
| 8065 | |
Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
|
| 8066 | |
or @code{AC_FC_WRAPPERS}; there is generally no need to call it
|
| 8067 | |
explicitly unless one wants to change the default actions.
|
| 8068 | |
|
| 8069 | |
The result of this macro is cached in the @code{ac_cv_f77_dummy_main} or
|
| 8070 | |
@code{ac_cv_fc_dummy_main} variable, respectively.
|
| 8071 | |
@end defmac
|
| 8072 | |
|
| 8073 | |
@defmac AC_F77_MAIN
|
| 8074 | |
@defmacx AC_FC_MAIN
|
| 8075 | |
@acindex{F77_MAIN}
|
| 8076 | |
@cvindex F77_MAIN
|
| 8077 | |
@acindex{FC_MAIN}
|
| 8078 | |
@cvindex FC_MAIN
|
| 8079 | |
@caindex f77_main
|
| 8080 | |
@caindex fc_main
|
| 8081 | |
As discussed above, many Fortran libraries allow you to provide an entry
|
| 8082 | |
point called (say) @code{MAIN__} instead of the usual @code{main}, which
|
| 8083 | |
is then called by a @code{main} function in the Fortran libraries that
|
| 8084 | |
initializes things like Fortran I/O@. The
|
| 8085 | |
@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
|
| 8086 | |
@emph{possible} to utilize such an alternate main function, and defines
|
| 8087 | |
@code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
|
| 8088 | |
alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
|
| 8089 | |
simply defined to @code{main}.)
|
| 8090 | |
|
| 8091 | |
Thus, when calling Fortran routines from C that perform things like I/O,
|
| 8092 | |
one should use this macro and declare the "main" function like so:
|
| 8093 | |
|
| 8094 | |
@example
|
| 8095 | |
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
|
| 8096 | |
#ifdef __cplusplus
|
| 8097 | |
extern "C"
|
| 8098 | |
#endif
|
| 8099 | |
int F77_MAIN (int argc, char *argv[]);
|
| 8100 | |
@end example
|
| 8101 | |
|
| 8102 | |
(Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
|
| 8103 | |
|
| 8104 | |
The result of this macro is cached in the @code{ac_cv_f77_main} or
|
| 8105 | |
@code{ac_cv_fc_main} variable, respectively.
|
| 8106 | |
@end defmac
|
| 8107 | |
|
| 8108 | |
@defmac AC_F77_WRAPPERS
|
| 8109 | |
@defmacx AC_FC_WRAPPERS
|
| 8110 | |
@acindex{F77_WRAPPERS}
|
| 8111 | |
@cvindex F77_FUNC
|
| 8112 | |
@cvindex F77_FUNC_
|
| 8113 | |
@acindex{FC_WRAPPERS}
|
| 8114 | |
@cvindex FC_FUNC
|
| 8115 | |
@cvindex FC_FUNC_
|
| 8116 | |
@caindex f77_mangling
|
| 8117 | |
@caindex fc_mangling
|
| 8118 | |
Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
|
| 8119 | |
@code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
|
| 8120 | |
mangle the names of C/C++ identifiers, and identifiers with underscores,
|
| 8121 | |
respectively, so that they match the name-mangling scheme used by the
|
| 8122 | |
Fortran compiler.
|
| 8123 | |
|
| 8124 | |
Fortran is case-insensitive, and in order to achieve this the Fortran
|
| 8125 | |
compiler converts all identifiers into a canonical case and format. To
|
| 8126 | |
call a Fortran subroutine from C or to write a C function that is
|
| 8127 | |
callable from Fortran, the C program must explicitly use identifiers in
|
| 8128 | |
the format expected by the Fortran compiler. In order to do this, one
|
| 8129 | |
simply wraps all C identifiers in one of the macros provided by
|
| 8130 | |
@code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
|
| 8131 | |
you have the following Fortran 77 subroutine:
|
| 8132 | |
|
| 8133 | |
@example
|
| 8134 | |
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
|
| 8135 | |
subroutine foobar (x, y)
|
| 8136 | |
double precision x, y
|
| 8137 | |
y = 3.14159 * x
|
| 8138 | |
return
|
| 8139 | |
end
|
| 8140 | |
@end example
|
| 8141 | |
|
| 8142 | |
You would then declare its prototype in C or C++ as:
|
| 8143 | |
|
| 8144 | |
@example
|
| 8145 | |
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
|
| 8146 | |
#define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
|
| 8147 | |
#ifdef __cplusplus
|
| 8148 | |
extern "C" /* prevent C++ name mangling */
|
| 8149 | |
#endif
|
| 8150 | |
void FOOBAR_F77 (double *x, double *y);
|
| 8151 | |
@end example
|
| 8152 | |
|
| 8153 | |
Note that we pass both the lowercase and uppercase versions of the
|
| 8154 | |
function name to @code{F77_FUNC} so that it can select the right one.
|
| 8155 | |
Note also that all parameters to Fortran 77 routines are passed as
|
| 8156 | |
pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, GNU
|
| 8157 | |
Automake}).
|
| 8158 | |
|
| 8159 | |
(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
|
| 8160 | |
|
| 8161 | |
Although Autoconf tries to be intelligent about detecting the
|
| 8162 | |
name-mangling scheme of the Fortran compiler, there may be Fortran
|
| 8163 | |
compilers that it doesn't support yet. In this case, the above code
|
| 8164 | |
generates a compile-time error, but some other behavior
|
| 8165 | |
(e.g., disabling Fortran-related features) can be induced by checking
|
| 8166 | |
whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
|
| 8167 | |
|
| 8168 | |
Now, to call that routine from a C program, we would do something like:
|
| 8169 | |
|
| 8170 | |
@example
|
| 8171 | |
@c If you change this example, adjust tests/fortran.at:AC_F77_DUMMY_MAIN usage.
|
| 8172 | |
@{
|
| 8173 | |
double x = 2.7183, y;
|
| 8174 | |
FOOBAR_F77 (&x, &y);
|
| 8175 | |
@}
|
| 8176 | |
@end example
|
| 8177 | |
|
| 8178 | |
If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
|
| 8179 | |
you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
|
| 8180 | |
@code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
|
| 8181 | |
because some Fortran compilers mangle names differently if they contain
|
| 8182 | |
an underscore.
|
| 8183 | |
|
| 8184 | |
The name mangling scheme is encoded in the @code{ac_cv_f77_mangling} or
|
| 8185 | |
@code{ac_cv_fc_mangling} cache variable, respectively, and also used for
|
| 8186 | |
the @code{AC_F77_FUNC} and @code{AC_FC_FUNC} macros described below.
|
| 8187 | |
@end defmac
|
| 8188 | |
|
| 8189 | |
@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
|
| 8190 | |
@defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
|
| 8191 | |
@acindex{F77_FUNC}
|
| 8192 | |
@acindex{FC_FUNC}
|
| 8193 | |
Given an identifier @var{name}, set the shell variable @var{shellvar} to
|
| 8194 | |
hold the mangled version @var{name} according to the rules of the
|
| 8195 | |
Fortran linker (see also @code{AC_F77_WRAPPERS} or
|
| 8196 | |
@code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
|
| 8197 | |
supplied, the shell variable is simply @var{name}. The purpose of
|
| 8198 | |
this macro is to give the caller a way to access the name-mangling
|
| 8199 | |
information other than through the C preprocessor as above, for example,
|
| 8200 | |
to call Fortran routines from some language other than C/C++.
|
| 8201 | |
@end defmac
|
| 8202 | |
|
| 8203 | |
@defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @
|
| 8204 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8205 | |
@defmacx AC_FC_PP_SRCEXT (@var{ext}, @ovar{action-if-success}, @
|
| 8206 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8207 | |
@acindex{FC_SRCEXT}
|
| 8208 | |
@acindex{FC_PP_SRCEXT}
|
| 8209 | |
@caindex fc_srcext_@var{ext}
|
| 8210 | |
@caindex fc_pp_srcext_@var{ext}
|
| 8211 | |
By default, the @code{FC} macros perform their tests using a @file{.f}
|
| 8212 | |
extension for source-code files. Some compilers, however, only enable
|
| 8213 | |
newer language features for appropriately named files, e.g., Fortran 90
|
| 8214 | |
features only for @file{.f90} files, or preprocessing only with
|
| 8215 | |
@file{.F} files or maybe other upper-case extensions. On the other
|
| 8216 | |
hand, some other compilers expect all source files to end in @file{.f}
|
| 8217 | |
and require special flags to support other file name extensions. The
|
| 8218 | |
@code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros deal with these
|
| 8219 | |
issues.
|
| 8220 | |
|
| 8221 | |
The @code{AC_FC_SRCEXT} macro tries to get the @code{FC} compiler to
|
| 8222 | |
accept files ending with the extension @file{.@var{ext}} (i.e.,
|
| 8223 | |
@var{ext} does @emph{not} contain the dot). If any special compiler
|
| 8224 | |
flags are needed for this, it stores them in the output variable
|
| 8225 | |
@code{FCFLAGS_@var{ext}}. This extension and these flags are then used
|
| 8226 | |
for all subsequent @code{FC} tests (until @code{AC_FC_SRCEXT} or
|
| 8227 | |
@code{AC_FC_PP_SRCEXT} is called another time).
|
| 8228 | |
|
| 8229 | |
For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
|
| 8230 | |
@file{.f90} extension in future tests, and it would set the
|
| 8231 | |
@code{FCFLAGS_f90} output variable with any extra flags that are needed
|
| 8232 | |
to compile such files.
|
| 8233 | |
|
| 8234 | |
Similarly, the @code{AC_FC_PP_SRCEXT} macro tries to get the @code{FC}
|
| 8235 | |
compiler to preprocess and compile files with the extension
|
| 8236 | |
@file{.@var{ext}}. When both @command{fpp} and @command{cpp} style
|
| 8237 | |
preprocessing are provided, the former is preferred, as the latter may
|
| 8238 | |
treat continuation lines, @code{//} tokens, and white space differently
|
| 8239 | |
from what some Fortran dialects expect. Conversely, if you do not want
|
| 8240 | |
files to be preprocessed, use only lower-case characters in the file
|
| 8241 | |
name extension. Like with @code{AC_FC_SRCEXT(f90)}, any needed flags
|
| 8242 | |
are stored in the @code{FCFLAGS_@var{ext}} variable.
|
| 8243 | |
|
| 8244 | |
The @code{FCFLAGS_@var{ext}} flags can @emph{not} be simply absorbed
|
| 8245 | |
into @code{FCFLAGS}, for two reasons based on the limitations of some
|
| 8246 | |
compilers. First, only one @code{FCFLAGS_@var{ext}} can be used at a
|
| 8247 | |
time, so files with different extensions must be compiled separately.
|
| 8248 | |
Second, @code{FCFLAGS_@var{ext}} must appear @emph{immediately} before
|
| 8249 | |
the source-code file name when compiling. So, continuing the example
|
| 8250 | |
above, you might compile a @file{foo.f90} file in your makefile with the
|
| 8251 | |
command:
|
| 8252 | |
|
| 8253 | |
@example
|
| 8254 | |
foo.o: foo.f90
|
| 8255 | |
$(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
|
| 8256 | |
@end example
|
| 8257 | |
|
| 8258 | |
If @code{AC_FC_SRCEXT} or @code{AC_FC_PP_SRCEXT} succeeds in compiling
|
| 8259 | |
files with the @var{ext} extension, it calls @var{action-if-success}
|
| 8260 | |
(defaults to nothing). If it fails, and cannot find a way to make the
|
| 8261 | |
@code{FC} compiler accept such files, it calls @var{action-if-failure}
|
| 8262 | |
(defaults to exiting with an error message).
|
| 8263 | |
|
| 8264 | |
The @code{AC_FC_SRCEXT} and @code{AC_FC_PP_SRCEXT} macros cache their
|
| 8265 | |
results in @code{ac_cv_fc_srcext_@var{ext}} and
|
| 8266 | |
@code{ac_cv_fc_pp_srcext_@var{ext}} variables, respectively.
|
| 8267 | |
@end defmac
|
| 8268 | |
|
| 8269 | |
@defmac AC_FC_PP_DEFINE (@ovar{action-if-success}, @dvar{action-if-failure, @
|
| 8270 | |
AC_MSG_FAILURE})
|
| 8271 | |
@acindex{FC_PP_DEFINE}
|
| 8272 | |
@caindex fc_pp_define
|
| 8273 | |
|
| 8274 | |
Find a flag to specify defines for preprocessed Fortran. Not all
|
| 8275 | |
Fortran compilers use @option{-D}. Substitute @code{FC_DEFINE} with
|
| 8276 | |
the result and call @var{action-if-success} (defaults to nothing) if
|
| 8277 | |
successful, and @var{action-if-failure} (defaults to failing with an
|
| 8278 | |
error message) if not.
|
| 8279 | |
|
| 8280 | |
This macro calls @code{AC_FC_PP_SRCEXT([F])} in order to learn how to
|
| 8281 | |
preprocess a @file{conftest.F} file, but restores a previously used
|
| 8282 | |
Fortran source file extension afterwards again.
|
| 8283 | |
|
| 8284 | |
The result of this test is cached in the @code{ac_cv_fc_pp_define}
|
| 8285 | |
variable.
|
| 8286 | |
@end defmac
|
| 8287 | |
|
| 8288 | |
@defmac AC_FC_FREEFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
|
| 8289 | |
AC_MSG_FAILURE})
|
| 8290 | |
@acindex{FC_FREEFORM}
|
| 8291 | |
@caindex fc_freeform
|
| 8292 | |
|
| 8293 | |
Try to ensure that the Fortran compiler (@code{$FC}) allows free-format
|
| 8294 | |
source code (as opposed to the older fixed-format style from Fortran
|
| 8295 | |
77). If necessary, it may add some additional flags to @code{FCFLAGS}.
|
| 8296 | |
|
| 8297 | |
This macro is most important if you are using the default @file{.f}
|
| 8298 | |
extension, since many compilers interpret this extension as indicating
|
| 8299 | |
fixed-format source unless an additional flag is supplied. If you
|
| 8300 | |
specify a different extension with @code{AC_FC_SRCEXT}, such as
|
| 8301 | |
@file{.f90}, then @code{AC_FC_FREEFORM} ordinarily succeeds without
|
| 8302 | |
modifying @code{FCFLAGS}. For extensions which the compiler does not
|
| 8303 | |
know about, the flag set by the @code{AC_FC_SRCEXT} macro might let
|
| 8304 | |
the compiler assume Fortran 77 by default, however.
|
| 8305 | |
|
| 8306 | |
If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
|
| 8307 | |
calls @var{action-if-success} (defaults to nothing). If it fails, it
|
| 8308 | |
calls @var{action-if-failure} (defaults to exiting with an error
|
| 8309 | |
message).
|
| 8310 | |
|
| 8311 | |
The result of this test, or @samp{none} or @samp{unknown}, is cached in
|
| 8312 | |
the @code{ac_cv_fc_freeform} variable.
|
| 8313 | |
@end defmac
|
| 8314 | |
|
| 8315 | |
@defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
|
| 8316 | |
AC_MSG_FAILURE})
|
| 8317 | |
@acindex{FC_FIXEDFORM}
|
| 8318 | |
@caindex fc_fixedform
|
| 8319 | |
|
| 8320 | |
Try to ensure that the Fortran compiler (@code{$FC}) allows the old
|
| 8321 | |
fixed-format source code (as opposed to free-format style). If
|
| 8322 | |
necessary, it may add some additional flags to @code{FCFLAGS}.
|
| 8323 | |
|
| 8324 | |
This macro is needed for some compilers alias names like @command{xlf95}
|
| 8325 | |
which assume free-form source code by default, and in case you want to
|
| 8326 | |
use fixed-form source with an extension like @file{.f90} which many
|
| 8327 | |
compilers interpret as free-form by default. If you specify a different
|
| 8328 | |
extension with @code{AC_FC_SRCEXT}, such as @file{.f}, then
|
| 8329 | |
@code{AC_FC_FIXEDFORM} ordinarily succeeds without modifying
|
| 8330 | |
@code{FCFLAGS}.
|
| 8331 | |
|
| 8332 | |
If @code{AC_FC_FIXEDFORM} succeeds in compiling fixed-form source, it
|
| 8333 | |
calls @var{action-if-success} (defaults to nothing). If it fails, it
|
| 8334 | |
calls @var{action-if-failure} (defaults to exiting with an error
|
| 8335 | |
message).
|
| 8336 | |
|
| 8337 | |
The result of this test, or @samp{none} or @samp{unknown}, is cached in
|
| 8338 | |
the @code{ac_cv_fc_fixedform} variable.
|
| 8339 | |
@end defmac
|
| 8340 | |
|
| 8341 | |
@defmac AC_FC_LINE_LENGTH (@ovar{length}, @ovar{action-if-success}, @
|
| 8342 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8343 | |
@acindex{FC_LINE_LENGTH}
|
| 8344 | |
@caindex fc_line_length
|
| 8345 | |
|
| 8346 | |
Try to ensure that the Fortran compiler (@code{$FC}) accepts long source
|
| 8347 | |
code lines. The @var{length} argument may be given as 80, 132, or
|
| 8348 | |
unlimited, and defaults to 132. Note that line lengths above 254
|
| 8349 | |
columns are not portable, and some compilers do not accept more than 132
|
| 8350 | |
columns at least for fixed format source. If necessary, it may add some
|
| 8351 | |
additional flags to @code{FCFLAGS}.
|
| 8352 | |
|
| 8353 | |
If @code{AC_FC_LINE_LENGTH} succeeds in compiling fixed-form source, it
|
| 8354 | |
calls @var{action-if-success} (defaults to nothing). If it fails, it
|
| 8355 | |
calls @var{action-if-failure} (defaults to exiting with an error
|
| 8356 | |
message).
|
| 8357 | |
|
| 8358 | |
The result of this test, or @samp{none} or @samp{unknown}, is cached in
|
| 8359 | |
the @code{ac_cv_fc_line_length} variable.
|
| 8360 | |
@end defmac
|
| 8361 | |
|
| 8362 | |
@defmac AC_FC_CHECK_BOUNDS (@ovar{action-if-success}, @
|
| 8363 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8364 | |
@acindex{FC_CHECK_BOUNDS}
|
| 8365 | |
@caindex fc_check_bounds
|
| 8366 | |
|
| 8367 | |
The @code{AC_FC_CHECK_BOUNDS} macro tries to enable array bounds checking
|
| 8368 | |
in the Fortran compiler. If successful, the @var{action-if-success}
|
| 8369 | |
is called and any needed flags are added to @code{FCFLAGS}. Otherwise,
|
| 8370 | |
@var{action-if-failure} is called, which defaults to failing with an error
|
| 8371 | |
message. The macro currently requires Fortran 90 or a newer dialect.
|
| 8372 | |
|
| 8373 | |
The result of the macro is cached in the @code{ac_cv_fc_check_bounds}
|
| 8374 | |
variable.
|
| 8375 | |
@end defmac
|
| 8376 | |
|
| 8377 | |
@defmac AC_F77_IMPLICIT_NONE (@ovar{action-if-success}, @
|
| 8378 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8379 | |
@defmacx AC_FC_IMPLICIT_NONE (@ovar{action-if-success}, @
|
| 8380 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8381 | |
@acindex{F77_IMPLICIT_NONE}
|
| 8382 | |
@acindex{FC_IMPLICIT_NONE}
|
| 8383 | |
@caindex f77_implicit_none
|
| 8384 | |
@caindex fc_implicit_none
|
| 8385 | |
|
| 8386 | |
Try to disallow implicit declarations in the Fortran compiler. If
|
| 8387 | |
successful, @var{action-if-success} is called and any needed flags
|
| 8388 | |
are added to @code{FFLAGS} or @code{FCFLAGS}, respectively. Otherwise,
|
| 8389 | |
@var{action-if-failure} is called, which defaults to failing with an error
|
| 8390 | |
message.
|
| 8391 | |
|
| 8392 | |
The result of these macros are cached in the
|
| 8393 | |
@code{ac_cv_f77_implicit_none} and @code{ac_cv_fc_implicit_none}
|
| 8394 | |
variables, respectively.
|
| 8395 | |
@end defmac
|
| 8396 | |
|
| 8397 | |
@defmac AC_FC_MODULE_EXTENSION
|
| 8398 | |
@acindex{FC_MODULE_EXTENSION}
|
| 8399 | |
@caindex fc_module_ext
|
| 8400 | |
@ovindex FC_MODEXT
|
| 8401 | |
|
| 8402 | |
Find the Fortran 90 module file name extension. Most Fortran 90
|
| 8403 | |
compilers store module information in files separate from the object
|
| 8404 | |
files. The module files are usually named after the name of the module
|
| 8405 | |
rather than the source file name, with characters possibly turned to
|
| 8406 | |
upper case, plus an extension, often @file{.mod}.
|
| 8407 | |
|
| 8408 | |
Not all compilers use module files at all, or by default. The Cray
|
| 8409 | |
Fortran compiler requires @option{-e m} in order to store and search
|
| 8410 | |
module information in @file{.mod} files rather than in object files.
|
| 8411 | |
Likewise, the Fujitsu Fortran compilers uses the @option{-Am} option to
|
| 8412 | |
indicate how module information is stored.
|
| 8413 | |
|
| 8414 | |
The @code{AC_FC_MODULE_EXTENSION} macro computes the module extension
|
| 8415 | |
without the leading dot, and stores that in the @code{FC_MODEXT}
|
| 8416 | |
variable. If the compiler does not produce module files, or the
|
| 8417 | |
extension cannot be determined, @code{FC_MODEXT} is empty. Typically,
|
| 8418 | |
the result of this macro may be used in cleanup @command{make} rules as
|
| 8419 | |
follows:
|
| 8420 | |
|
| 8421 | |
@example
|
| 8422 | |
clean-modules:
|
| 8423 | |
-test -z "$(FC_MODEXT)" || rm -f *.$(FC_MODEXT)
|
| 8424 | |
@end example
|
| 8425 | |
|
| 8426 | |
The extension, or @samp{unknown}, is cached in the
|
| 8427 | |
@code{ac_cv_fc_module_ext} variable.
|
| 8428 | |
@end defmac
|
| 8429 | |
|
| 8430 | |
@defmac AC_FC_MODULE_FLAG (@ovar{action-if-success}, @
|
| 8431 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8432 | |
@acindex{FC_MODULE_FLAG}
|
| 8433 | |
@caindex fc_module_flag
|
| 8434 | |
@ovindex FC_MODINC
|
| 8435 | |
@ovindex ac_empty
|
| 8436 | |
|
| 8437 | |
Find the compiler flag to include Fortran 90 module information from
|
| 8438 | |
another directory, and store that in the @code{FC_MODINC} variable.
|
| 8439 | |
Call @var{action-if-success} (defaults to nothing) if successful, and
|
| 8440 | |
set @code{FC_MODINC} to empty and call @var{action-if-failure} (defaults
|
| 8441 | |
to exiting with an error message) if not.
|
| 8442 | |
|
| 8443 | |
Most Fortran 90 compilers provide a way to specify module directories.
|
| 8444 | |
Some have separate flags for the directory to write module files to,
|
| 8445 | |
and directories to search them in, whereas others only allow writing to
|
| 8446 | |
the current directory or to the first directory specified in the include
|
| 8447 | |
path. Further, with some compilers, the module search path and the
|
| 8448 | |
preprocessor search path can only be modified with the same flag. Thus,
|
| 8449 | |
for portability, write module files to the current directory only and
|
| 8450 | |
list that as first directory in the search path.
|
| 8451 | |
|
| 8452 | |
There may be no whitespace between @code{FC_MODINC} and the following
|
| 8453 | |
directory name, but @code{FC_MODINC} may contain trailing white space.
|
| 8454 | |
For example, if you use Automake and would like to search @file{../lib}
|
| 8455 | |
for module files, you can use the following:
|
| 8456 | |
|
| 8457 | |
@example
|
| 8458 | |
AM_FCFLAGS = $(FC_MODINC). $(FC_MODINC)../lib
|
| 8459 | |
@end example
|
| 8460 | |
|
| 8461 | |
Inside @command{configure} tests, you can use:
|
| 8462 | |
|
| 8463 | |
@example
|
| 8464 | |
if test -n "$FC_MODINC"; then
|
| 8465 | |
FCFLAGS="$FCFLAGS $FC_MODINC. $FC_MODINC../lib"
|
| 8466 | |
fi
|
| 8467 | |
@end example
|
| 8468 | |
|
| 8469 | |
The flag is cached in the @code{ac_cv_fc_module_flag} variable.
|
| 8470 | |
The substituted value of @code{FC_MODINC} may refer to the
|
| 8471 | |
@code{ac_empty} dummy placeholder empty variable, to avoid losing
|
| 8472 | |
the significant trailing whitespace in a @file{Makefile}.
|
| 8473 | |
@end defmac
|
| 8474 | |
|
| 8475 | |
@defmac AC_FC_MODULE_OUTPUT_FLAG (@ovar{action-if-success}, @
|
| 8476 | |
@dvar{action-if-failure, AC_MSG_FAILURE})
|
| 8477 | |
@acindex{FC_MODULE_OUTPUT_FLAG}
|
| 8478 | |
@caindex fc_module_output_flag
|
| 8479 | |
@ovindex FC_MODOUT
|
| 8480 | |
|
| 8481 | |
Find the compiler flag to write Fortran 90 module information to
|
| 8482 | |
another directory, and store that in the @code{FC_MODOUT} variable.
|
| 8483 | |
Call @var{action-if-success} (defaults to nothing) if successful, and
|
| 8484 | |
set @code{FC_MODOUT} to empty and call @var{action-if-failure} (defaults
|
| 8485 | |
to exiting with an error message) if not.
|
| 8486 | |
|
| 8487 | |
Not all Fortran 90 compilers write module files, and of those that do,
|
| 8488 | |
not all allow writing to a directory other than the current one, nor
|
| 8489 | |
do all have separate flags for writing and reading; see the description
|
| 8490 | |
of @code{AC_FC_MODULE_FLAG} above. If you need to be able to write to
|
| 8491 | |
another directory, for maximum portability use @code{FC_MODOUT} before
|
| 8492 | |
any @code{FC_MODINC} and include both the current directory and the one
|
| 8493 | |
you write to in the search path:
|
| 8494 | |
|
| 8495 | |
@example
|
| 8496 | |
AM_FCFLAGS = $(FC_MODOUT)../mod $(FC_MODINC)../mod $(FC_MODINC). @dots{}
|
| 8497 | |
@end example
|
| 8498 | |
|
| 8499 | |
The flag is cached in the @code{ac_cv_fc_module_output_flag} variable.
|
| 8500 | |
The substituted value of @code{FC_MODOUT} may refer to the
|
| 8501 | |
@code{ac_empty} dummy placeholder empty variable, to avoid losing
|
| 8502 | |
the significant trailing whitespace in a @file{Makefile}.
|
| 8503 | |
@end defmac
|
| 8504 | |
|
| 8505 | |
|
| 8506 | |
@node Go Compiler
|
| 8507 | |
@subsection Go Compiler Characteristics
|
| 8508 | |
@cindex Go
|
| 8509 | |
|
| 8510 | |
Autoconf provides basic support for the Go programming language when
|
| 8511 | |
using the @code{gccgo} compiler (there is currently no support for the
|
| 8512 | |
@code{6g} and @code{8g} compilers).
|
| 8513 | |
|
| 8514 | |
@defmac AC_PROG_GO (@ovar{compiler-search-list})
|
| 8515 | |
Find the Go compiler to use. Check whether the environment variable
|
| 8516 | |
@code{GOC} is set; if so, then set output variable @code{GOC} to its
|
| 8517 | |
value.
|
| 8518 | |
|
| 8519 | |
Otherwise, if the macro is invoked without an argument, then search for
|
| 8520 | |
a Go compiler named @code{gccgo}. If it is not found, then as a last
|
| 8521 | |
resort set @code{GOC} to @code{gccgo}.
|
| 8522 | |
|
| 8523 | |
This macro may be invoked with an optional first argument which, if
|
| 8524 | |
specified, must be a blank-separated list of Go compilers to search for.
|
| 8525 | |
|
| 8526 | |
If output variable @code{GOFLAGS} was not already set, set it to
|
| 8527 | |
@option{-g -O2}. If your package does not like this default,
|
| 8528 | |
@code{GOFLAGS} may be set before @code{AC_PROG_GO}.
|
| 8529 | |
@end defmac
|
| 8530 | |
|
| 8531 | |
|
| 8532 | |
@node System Services
|
| 8533 | |
@section System Services
|
| 8534 | |
|
| 8535 | |
The following macros check for operating system services or capabilities.
|
| 8536 | |
|
| 8537 | |
@anchor{AC_PATH_X}
|
| 8538 | |
@defmac AC_PATH_X
|
| 8539 | |
@acindex{PATH_X}
|
| 8540 | |
@evindex XMKMF
|
| 8541 | |
@cindex X Window System
|
| 8542 | |
Try to locate the X Window System include files and libraries. If the
|
| 8543 | |
user gave the command line options @option{--x-includes=@var{dir}} and
|
| 8544 | |
@option{--x-libraries=@var{dir}}, use those directories.
|
| 8545 | |
|
| 8546 | |
If either or both were not given, get the missing values by running
|
| 8547 | |
@code{xmkmf} (or an executable pointed to by the @code{XMKMF}
|
| 8548 | |
environment variable) on a trivial @file{Imakefile} and examining the
|
| 8549 | |
makefile that it produces. Setting @code{XMKMF} to @samp{false}
|
| 8550 | |
disables this method.
|
| 8551 | |
|
| 8552 | |
If this method fails to find the X Window System, @command{configure}
|
| 8553 | |
looks for the files in several directories where they often reside.
|
| 8554 | |
If either method is successful, set the shell variables
|
| 8555 | |
@code{x_includes} and @code{x_libraries} to their locations, unless they
|
| 8556 | |
are in directories the compiler searches by default.
|
| 8557 | |
|
| 8558 | |
If both methods fail, or the user gave the command line option
|
| 8559 | |
@option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
|
| 8560 | |
otherwise set it to the empty string.
|
| 8561 | |
@end defmac
|
| 8562 | |
|
| 8563 | |
@anchor{AC_PATH_XTRA}
|
| 8564 | |
@defmac AC_PATH_XTRA
|
| 8565 | |
@acindex{PATH_XTRA}
|
| 8566 | |
@ovindex X_CFLAGS
|
| 8567 | |
@ovindex X_LIBS
|
| 8568 | |
@ovindex X_EXTRA_LIBS
|
| 8569 | |
@ovindex X_PRE_LIBS
|
| 8570 | |
@cvindex X_DISPLAY_MISSING
|
| 8571 | |
An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
|
| 8572 | |
that X needs to output variable @code{X_CFLAGS}, and the X linker flags
|
| 8573 | |
to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
|
| 8574 | |
available.
|
| 8575 | |
|
| 8576 | |
This macro also checks for special libraries that some systems need in
|
| 8577 | |
order to compile X programs. It adds any that the system needs to
|
| 8578 | |
output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
|
| 8579 | |
libraries that need to be linked with before @option{-lX11}, and adds
|
| 8580 | |
any found to the output variable @code{X_PRE_LIBS}.
|
| 8581 | |
|
| 8582 | |
@c This is an incomplete kludge. Make a real way to do it.
|
| 8583 | |
@c If you need to check for other X functions or libraries yourself, then
|
| 8584 | |
@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
|
| 8585 | |
@c @code{LIBS} temporarily, like this: (FIXME - add example)
|
| 8586 | |
@end defmac
|
| 8587 | |
|
| 8588 | |
@anchor{AC_SYS_INTERPRETER}
|
| 8589 | |
@defmac AC_SYS_INTERPRETER
|
| 8590 | |
@acindex{SYS_INTERPRETER}
|
| 8591 | |
Check whether the system supports starting scripts with a line of the
|
| 8592 | |
form @samp{#!/bin/sh} to select the interpreter to use for the script.
|
| 8593 | |
After running this macro, shell code in @file{configure.ac} can check
|
| 8594 | |
the shell variable @code{interpval}; it is set to @samp{yes}
|
| 8595 | |
if the system supports @samp{#!}, @samp{no} if not.
|
| 8596 | |
@end defmac
|
| 8597 | |
|
| 8598 | |
@defmac AC_SYS_LARGEFILE
|
| 8599 | |
@acindex{SYS_LARGEFILE}
|
| 8600 | |
@cvindex _FILE_OFFSET_BITS
|
| 8601 | |
@cvindex _LARGE_FILES
|
| 8602 | |
@ovindex CC
|
| 8603 | |
@cindex Large file support
|
| 8604 | |
@cindex LFS
|
| 8605 | |
Arrange for 64-bit file offsets, known as
|
| 8606 | |
@uref{http://@/www.unix-systems@/.org/@/version2/@/whatsnew/@/lfs20mar.html,
|
| 8607 | |
large-file support}. On some hosts, one must use special compiler
|
| 8608 | |
options to build programs that can access large files. Append any such
|
| 8609 | |
options to the output variable @code{CC}. Define
|
| 8610 | |
@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
|
| 8611 | |
|
| 8612 | |
Large-file support can be disabled by configuring with the
|
| 8613 | |
@option{--disable-largefile} option.
|
| 8614 | |
|
| 8615 | |
If you use this macro, check that your program works even when
|
| 8616 | |
@code{off_t} is wider than @code{long int}, since this is common when
|
| 8617 | |
large-file support is enabled. For example, it is not correct to print
|
| 8618 | |
an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
|
| 8619 | |
(long int) X)}.
|
| 8620 | |
|
| 8621 | |
The LFS introduced the @code{fseeko} and @code{ftello} functions to
|
| 8622 | |
replace their C counterparts @code{fseek} and @code{ftell} that do not
|
| 8623 | |
use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
|
| 8624 | |
prototypes available when using them and large-file support is
|
| 8625 | |
enabled.
|
| 8626 | |
@end defmac
|
| 8627 | |
|
| 8628 | |
@anchor{AC_SYS_LONG_FILE_NAMES}
|
| 8629 | |
@defmac AC_SYS_LONG_FILE_NAMES
|
| 8630 | |
@acindex{SYS_LONG_FILE_NAMES}
|
| 8631 | |
@cvindex HAVE_LONG_FILE_NAMES
|
| 8632 | |
If the system supports file names longer than 14 characters, define
|
| 8633 | |
@code{HAVE_LONG_FILE_NAMES}.
|
| 8634 | |
@end defmac
|
| 8635 | |
|
| 8636 | |
@defmac AC_SYS_POSIX_TERMIOS
|
| 8637 | |
@acindex{SYS_POSIX_TERMIOS}
|
| 8638 | |
@cindex Posix termios headers
|
| 8639 | |
@cindex termios Posix headers
|
| 8640 | |
@caindex sys_posix_termios
|
| 8641 | |
Check to see if the Posix termios headers and functions are available on the
|
| 8642 | |
system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
|
| 8643 | |
@samp{yes}. If not, set the variable to @samp{no}.
|
| 8644 | |
@end defmac
|
| 8645 | |
|
| 8646 | |
@node Posix Variants
|
| 8647 | |
@section Posix Variants
|
| 8648 | |
|
| 8649 | |
The following macro makes it possible to use features of Posix that are
|
| 8650 | |
extensions to C, as well as platform extensions not defined by Posix.
|
| 8651 | |
|
| 8652 | |
@anchor{AC_USE_SYSTEM_EXTENSIONS}
|
| 8653 | |
@defmac AC_USE_SYSTEM_EXTENSIONS
|
| 8654 | |
@acindex{USE_SYSTEM_EXTENSIONS}
|
| 8655 | |
@cvindex _ALL_SOURCE
|
| 8656 | |
@cvindex _GNU_SOURCE
|
| 8657 | |
@cvindex _MINIX
|
| 8658 | |
@cvindex _POSIX_1_SOURCE
|
| 8659 | |
@cvindex _POSIX_PTHREAD_SEMANTICS
|
| 8660 | |
@cvindex _POSIX_SOURCE
|
| 8661 | |
@cvindex _TANDEM_SOURCE
|
| 8662 | |
@cvindex __EXTENSIONS__
|
| 8663 | |
This macro was introduced in Autoconf 2.60. If possible, enable
|
| 8664 | |
extensions to C or Posix on hosts that normally disable the extensions,
|
| 8665 | |
typically due to standards-conformance namespace issues. This should be
|
| 8666 | |
called before any macros that run the C compiler. The following
|
| 8667 | |
preprocessor macros are defined where appropriate:
|
| 8668 | |
|
| 8669 | |
@table @code
|
| 8670 | |
@item _GNU_SOURCE
|
| 8671 | |
Enable extensions on GNU/Linux.
|
| 8672 | |
@item __EXTENSIONS__
|
| 8673 | |
Enable general extensions on Solaris.
|
| 8674 | |
@item _POSIX_PTHREAD_SEMANTICS
|
| 8675 | |
Enable threading extensions on Solaris.
|
| 8676 | |
@item _TANDEM_SOURCE
|
| 8677 | |
Enable extensions for the HP NonStop platform.
|
| 8678 | |
@item _ALL_SOURCE
|
| 8679 | |
Enable extensions for AIX 3, and for Interix.
|
| 8680 | |
@item _POSIX_SOURCE
|
| 8681 | |
Enable Posix functions for Minix.
|
| 8682 | |
@item _POSIX_1_SOURCE
|
| 8683 | |
Enable additional Posix functions for Minix.
|
| 8684 | |
@item _MINIX
|
| 8685 | |
Identify Minix platform. This particular preprocessor macro is
|
| 8686 | |
obsolescent, and may be removed in a future release of Autoconf.
|
| 8687 | |
@end table
|
| 8688 | |
@end defmac
|
| 8689 | |
|
| 8690 | |
|
| 8691 | |
@node Erlang Libraries
|
| 8692 | |
@section Erlang Libraries
|
| 8693 | |
@cindex Erlang, Library, checking
|
| 8694 | |
|
| 8695 | |
The following macros check for an installation of Erlang/OTP, and for the
|
| 8696 | |
presence of certain Erlang libraries. All those macros require the
|
| 8697 | |
configuration of an Erlang interpreter and an Erlang compiler
|
| 8698 | |
(@pxref{Erlang Compiler and Interpreter}).
|
| 8699 | |
|
| 8700 | |
@defmac AC_ERLANG_SUBST_ERTS_VER
|
| 8701 | |
@acindex{ERLANG_SUBST_ERTS_VER}
|
| 8702 | |
@ovindex ERLANG_ERTS_VER
|
| 8703 | |
Set the output variable @code{ERLANG_ERTS_VER} to the version of the
|
| 8704 | |
Erlang runtime system (as returned by Erlang's
|
| 8705 | |
@code{erlang:system_info(version)} function). The result of this test
|
| 8706 | |
is cached if caching is enabled when running @command{configure}. The
|
| 8707 | |
@code{ERLANG_ERTS_VER} variable is not intended to be used for testing
|
| 8708 | |
for features of specific ERTS versions, but to be used for substituting
|
| 8709 | |
the ERTS version in Erlang/OTP release resource files (@code{.rel}
|
| 8710 | |
files), as shown below.
|
| 8711 | |
@end defmac
|
| 8712 | |
|
| 8713 | |
@defmac AC_ERLANG_SUBST_ROOT_DIR
|
| 8714 | |
@acindex{ERLANG_SUBST_ROOT_DIR}
|
| 8715 | |
@ovindex ERLANG_ROOT_DIR
|
| 8716 | |
Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base
|
| 8717 | |
directory in which Erlang/OTP is installed (as returned by Erlang's
|
| 8718 | |
@code{code:root_dir/0} function). The result of this test is cached if
|
| 8719 | |
caching is enabled when running @command{configure}.
|
| 8720 | |
@end defmac
|
| 8721 | |
|
| 8722 | |
@defmac AC_ERLANG_SUBST_LIB_DIR
|
| 8723 | |
@acindex{ERLANG_SUBST_LIB_DIR}
|
| 8724 | |
@ovindex ERLANG_LIB_DIR
|
| 8725 | |
Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
|
| 8726 | |
directory of Erlang/OTP (as returned by Erlang's
|
| 8727 | |
@code{code:lib_dir/0} function), which subdirectories each contain an installed
|
| 8728 | |
Erlang/OTP library. The result of this test is cached if caching is enabled
|
| 8729 | |
when running @command{configure}.
|
| 8730 | |
@end defmac
|
| 8731 | |
|
| 8732 | |
@defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @
|
| 8733 | |
@ovar{action-if-not-found})
|
| 8734 | |
@acindex{ERLANG_CHECK_LIB}
|
| 8735 | |
@ovindex ERLANG_LIB_DIR_@var{library}
|
| 8736 | |
@ovindex ERLANG_LIB_VER_@var{library}
|
| 8737 | |
Test whether the Erlang/OTP library @var{library} is installed by
|
| 8738 | |
calling Erlang's @code{code:lib_dir/1} function. The result of this
|
| 8739 | |
test is cached if caching is enabled when running @command{configure}.
|
| 8740 | |
@var{action-if-found} is a list of shell commands to run if the library
|
| 8741 | |
is installed; @var{action-if-not-found} is a list of shell commands to
|
| 8742 | |
run if it is not. Additionally, if the library is installed, the output
|
| 8743 | |
variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
|
| 8744 | |
library installation directory, and the output variable
|
| 8745 | |
@samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
|
| 8746 | |
part of the subdirectory name, if it is in the standard form
|
| 8747 | |
(@code{@var{library}-@var{version}}). If the directory name does not
|
| 8748 | |
have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
|
| 8749 | |
empty string. If the library is not installed,
|
| 8750 | |
@samp{ERLANG_LIB_DIR_@var{library}} and
|
| 8751 | |
@samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
|
| 8752 | |
example, to check if library @code{stdlib} is installed:
|
| 8753 | |
|
| 8754 | |
@example
|
| 8755 | |
AC_ERLANG_CHECK_LIB([stdlib],
|
| 8756 | |
[echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
|
| 8757 | |
echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
|
| 8758 | |
[AC_MSG_ERROR([stdlib was not found!])])
|
| 8759 | |
@end example
|
| 8760 | |
|
| 8761 | |
The @samp{ERLANG_LIB_VER_@var{library}} variables (set by
|
| 8762 | |
@code{AC_ERLANG_CHECK_LIB}) and the @code{ERLANG_ERTS_VER} variable (set
|
| 8763 | |
by @code{AC_ERLANG_SUBST_ERTS_VER}) are not intended to be used for
|
| 8764 | |
testing for features of specific versions of libraries or of the Erlang
|
| 8765 | |
runtime system. Those variables are intended to be substituted in
|
| 8766 | |
Erlang release resource files (@code{.rel} files). For instance, to
|
| 8767 | |
generate a @file{example.rel} file for an application depending on the
|
| 8768 | |
@code{stdlib} library, @file{configure.ac} could contain:
|
| 8769 | |
|
| 8770 | |
@example
|
| 8771 | |
AC_ERLANG_SUBST_ERTS_VER
|
| 8772 | |
AC_ERLANG_CHECK_LIB([stdlib],
|
| 8773 | |
[],
|
| 8774 | |
[AC_MSG_ERROR([stdlib was not found!])])
|
| 8775 | |
AC_CONFIG_FILES([example.rel])
|
| 8776 | |
@end example
|
| 8777 | |
|
| 8778 | |
@noindent
|
| 8779 | |
The @file{example.rel.in} file used to generate @file{example.rel}
|
| 8780 | |
should contain:
|
| 8781 | |
|
| 8782 | |
@example
|
| 8783 | |
@{release,
|
| 8784 | |
@{"@@PACKAGE@@", "@@VERSION@@"@},
|
| 8785 | |
@{erts, "@@ERLANG_ERTS_VER@@"@},
|
| 8786 | |
[@{stdlib, "@@ERLANG_LIB_VER_stdlib@@"@},
|
| 8787 | |
@{@@PACKAGE@@, "@@VERSION@@"@}]@}.
|
| 8788 | |
@end example
|
| 8789 | |
@end defmac
|
| 8790 | |
|
| 8791 | |
In addition to the above macros, which test installed Erlang libraries, the
|
| 8792 | |
following macros determine the paths to the directories into which newly built
|
| 8793 | |
Erlang libraries are to be installed:
|
| 8794 | |
|
| 8795 | |
@defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
|
| 8796 | |
@acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
|
| 8797 | |
@ovindex ERLANG_INSTALL_LIB_DIR
|
| 8798 | |
|
| 8799 | |
Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
|
| 8800 | |
which every built Erlang library should be installed in a separate
|
| 8801 | |
subdirectory.
|
| 8802 | |
If this variable is not set in the environment when @command{configure} runs,
|
| 8803 | |
its default value is @code{$@{libdir@}/erlang/lib}.
|
| 8804 | |
@end defmac
|
| 8805 | |
|
| 8806 | |
@defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
|
| 8807 | |
@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
|
| 8808 | |
@ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
|
| 8809 | |
|
| 8810 | |
Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
|
| 8811 | |
directory into which the built Erlang library @var{library} version
|
| 8812 | |
@var{version} should be installed. If this variable is not set in the
|
| 8813 | |
environment when @command{configure} runs, its default value is
|
| 8814 | |
@samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
|
| 8815 | |
@code{ERLANG_INSTALL_LIB_DIR} variable being set by the
|
| 8816 | |
@code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
|
| 8817 | |
@end defmac
|
| 8818 | |
|
| 8819 | |
|
| 8820 | |
|
| 8821 | |
|
| 8822 | |
|
| 8823 | |
@c ========================================================= Writing Tests
|
| 8824 | |
|
| 8825 | |
@node Writing Tests
|
| 8826 | |
@chapter Writing Tests
|
| 8827 | |
|
| 8828 | |
If the existing feature tests don't do something you need, you have to
|
| 8829 | |
write new ones. These macros are the building blocks. They provide
|
| 8830 | |
ways for other macros to check whether various kinds of features are
|
| 8831 | |
available and report the results.
|
| 8832 | |
|
| 8833 | |
This chapter contains some suggestions and some of the reasons why the
|
| 8834 | |
existing tests are written the way they are. You can also learn a lot
|
| 8835 | |
about how to write Autoconf tests by looking at the existing ones. If
|
| 8836 | |
something goes wrong in one or more of the Autoconf tests, this
|
| 8837 | |
information can help you understand the assumptions behind them, which
|
| 8838 | |
might help you figure out how to best solve the problem.
|
| 8839 | |
|
| 8840 | |
These macros check the output of the compiler system of the current
|
| 8841 | |
language (@pxref{Language Choice}). They do not cache the results of
|
| 8842 | |
their tests for future use (@pxref{Caching Results}), because they don't
|
| 8843 | |
know enough about the information they are checking for to generate a
|
| 8844 | |
cache variable name. They also do not print any messages, for the same
|
| 8845 | |
reason. The checks for particular kinds of features call these macros
|
| 8846 | |
and do cache their results and print messages about what they're
|
| 8847 | |
checking for.
|
| 8848 | |
|
| 8849 | |
When you write a feature test that could be applicable to more than one
|
| 8850 | |
software package, the best thing to do is encapsulate it in a new macro.
|
| 8851 | |
@xref{Writing Autoconf Macros}, for how to do that.
|
| 8852 | |
|
| 8853 | |
@menu
|
| 8854 | |
* Language Choice:: Selecting which language to use for testing
|
| 8855 | |
* Writing Test Programs:: Forging source files for compilers
|
| 8856 | |
* Running the Preprocessor:: Detecting preprocessor symbols
|
| 8857 | |
* Running the Compiler:: Detecting language or header features
|
| 8858 | |
* Running the Linker:: Detecting library features
|
| 8859 | |
* Runtime:: Testing for runtime features
|
| 8860 | |
* Systemology:: A zoology of operating systems
|
| 8861 | |
* Multiple Cases:: Tests for several possible values
|
| 8862 | |
@end menu
|
| 8863 | |
|
| 8864 | |
@node Language Choice
|
| 8865 | |
@section Language Choice
|
| 8866 | |
@cindex Language
|
| 8867 | |
|
| 8868 | |
Autoconf-generated @command{configure} scripts check for the C compiler and
|
| 8869 | |
its features by default. Packages that use other programming languages
|
| 8870 | |
(maybe more than one, e.g., C and C++) need to test features of the
|
| 8871 | |
compilers for the respective languages. The following macros determine
|
| 8872 | |
which programming language is used in the subsequent tests in
|
| 8873 | |
@file{configure.ac}.
|
| 8874 | |
|
| 8875 | |
@anchor{AC_LANG}
|
| 8876 | |
@defmac AC_LANG (@var{language})
|
| 8877 | |
@acindex{LANG}
|
| 8878 | |
Do compilation tests using the compiler, preprocessor, and file
|
| 8879 | |
extensions for the specified @var{language}.
|
| 8880 | |
|
| 8881 | |
Supported languages are:
|
| 8882 | |
|
| 8883 | |
@table @samp
|
| 8884 | |
@item C
|
| 8885 | |
Do compilation tests using @code{CC} and @code{CPP} and use extension
|
| 8886 | |
@file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
|
| 8887 | |
@code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
|
| 8888 | |
|
| 8889 | |
@item C++
|
| 8890 | |
Do compilation tests using @code{CXX} and @code{CXXCPP} and use
|
| 8891 | |
extension @file{.C} for test programs. Use compilation flags:
|
| 8892 | |
@code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
|
| 8893 | |
@code{CXXFLAGS} with @code{CXX}.
|
| 8894 | |
|
| 8895 | |
@item Fortran 77
|
| 8896 | |
Do compilation tests using @code{F77} and use extension @file{.f} for
|
| 8897 | |
test programs. Use compilation flags: @code{FFLAGS}.
|
| 8898 | |
|
| 8899 | |
@item Fortran
|
| 8900 | |
Do compilation tests using @code{FC} and use extension @file{.f} (or
|
| 8901 | |
whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
|
| 8902 | |
compilation flags: @code{FCFLAGS}.
|
| 8903 | |
|
| 8904 | |
@item Erlang
|
| 8905 | |
@ovindex ERLC
|
| 8906 | |
@ovindex ERL
|
| 8907 | |
@ovindex ERLCFLAGS
|
| 8908 | |
Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
|
| 8909 | |
@file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
|
| 8910 | |
|
| 8911 | |
@item Objective C
|
| 8912 | |
Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
|
| 8913 | |
extension @file{.m} for test programs. Use compilation flags:
|
| 8914 | |
@code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
|
| 8915 | |
@code{OBJCFLAGS} with @code{OBJC}.
|
| 8916 | |
|
| 8917 | |
@item Objective C++
|
| 8918 | |
Do compilation tests using @code{OBJCXX} and @code{OBJCXXCPP} and use
|
| 8919 | |
extension @file{.mm} for test programs. Use compilation flags:
|
| 8920 | |
@code{CPPFLAGS} with @code{OBJCXXCPP}, and both @code{CPPFLAGS} and
|
| 8921 | |
@code{OBJCXXFLAGS} with @code{OBJCXX}.
|
| 8922 | |
|
| 8923 | |
@item Go
|
| 8924 | |
Do compilation tests using @code{GOC} and use extension @file{.go} for
|
| 8925 | |
test programs. Use compilation flags @code{GOFLAGS}.
|
| 8926 | |
@end table
|
| 8927 | |
@end defmac
|
| 8928 | |
|
| 8929 | |
@anchor{AC_LANG_PUSH}
|
| 8930 | |
@defmac AC_LANG_PUSH (@var{language})
|
| 8931 | |
@acindex{LANG_PUSH}
|
| 8932 | |
Remember the current language (as set by @code{AC_LANG}) on a stack, and
|
| 8933 | |
then select the @var{language}. Use this macro and @code{AC_LANG_POP}
|
| 8934 | |
in macros that need to temporarily switch to a particular language.
|
| 8935 | |
@end defmac
|
| 8936 | |
|
| 8937 | |
@defmac AC_LANG_POP (@ovar{language})
|
| 8938 | |
@acindex{LANG_POP}
|
| 8939 | |
Select the language that is saved on the top of the stack, as set by
|
| 8940 | |
@code{AC_LANG_PUSH}, and remove it from the stack.
|
| 8941 | |
|
| 8942 | |
If given, @var{language} specifies the language we just @emph{quit}. It
|
| 8943 | |
is a good idea to specify it when it's known (which should be the
|
| 8944 | |
case@dots{}), since Autoconf detects inconsistencies.
|
| 8945 | |
|
| 8946 | |
@example
|
| 8947 | |
AC_LANG_PUSH([Fortran 77])
|
| 8948 | |
# Perform some tests on Fortran 77.
|
| 8949 | |
# @dots{}
|
| 8950 | |
AC_LANG_POP([Fortran 77])
|
| 8951 | |
@end example
|
| 8952 | |
@end defmac
|
| 8953 | |
|
| 8954 | |
@defmac AC_LANG_ASSERT (@var{language})
|
| 8955 | |
@acindex{LANG_ASSERT}
|
| 8956 | |
Check statically that the current language is @var{language}.
|
| 8957 | |
You should use this in your language specific macros
|
| 8958 | |
to avoid that they be called with an inappropriate language.
|
| 8959 | |
|
| 8960 | |
This macro runs only at @command{autoconf} time, and incurs no cost at
|
| 8961 | |
@command{configure} time. Sadly enough and because Autoconf is a two
|
| 8962 | |
layer language @footnote{Because M4 is not aware of Sh code,
|
| 8963 | |
especially conditionals, some optimizations that look nice statically
|
| 8964 | |
may produce incorrect results at runtime.}, the macros
|
| 8965 | |
@code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
|
| 8966 | |
therefore as much as possible you ought to avoid using them to wrap
|
| 8967 | |
your code, rather, require from the user to run the macro with a
|
| 8968 | |
correct current language, and check it with @code{AC_LANG_ASSERT}.
|
| 8969 | |
And anyway, that may help the user understand she is running a Fortran
|
| 8970 | |
macro while expecting a result about her Fortran 77 compiler@enddots{}
|
| 8971 | |
@end defmac
|
| 8972 | |
|
| 8973 | |
|
| 8974 | |
@defmac AC_REQUIRE_CPP
|
| 8975 | |
@acindex{REQUIRE_CPP}
|
| 8976 | |
Ensure that whichever preprocessor would currently be used for tests has
|
| 8977 | |
been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
|
| 8978 | |
argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
|
| 8979 | |
depending on which language is current.
|
| 8980 | |
@end defmac
|
| 8981 | |
|
| 8982 | |
|
| 8983 | |
@node Writing Test Programs
|
| 8984 | |
@section Writing Test Programs
|
| 8985 | |
|
| 8986 | |
Autoconf tests follow a common scheme: feed some program with some
|
| 8987 | |
input, and most of the time, feed a compiler with some source file.
|
| 8988 | |
This section is dedicated to these source samples.
|
| 8989 | |
|
| 8990 | |
@menu
|
| 8991 | |
* Guidelines:: General rules for writing test programs
|
| 8992 | |
* Test Functions:: Avoiding pitfalls in test programs
|
| 8993 | |
* Generating Sources:: Source program boilerplate
|
| 8994 | |
@end menu
|
| 8995 | |
|
| 8996 | |
@node Guidelines
|
| 8997 | |
@subsection Guidelines for Test Programs
|
| 8998 | |
|
| 8999 | |
The most important rule to follow when writing testing samples is:
|
| 9000 | |
|
| 9001 | |
@center @emph{Look for realism.}
|
| 9002 | |
|
| 9003 | |
This motto means that testing samples must be written with the same
|
| 9004 | |
strictness as real programs are written. In particular, you should
|
| 9005 | |
avoid ``shortcuts'' and simplifications.
|
| 9006 | |
|
| 9007 | |
Don't just play with the preprocessor if you want to prepare a
|
| 9008 | |
compilation. For instance, using @command{cpp} to check whether a header is
|
| 9009 | |
functional might let your @command{configure} accept a header which
|
| 9010 | |
causes some @emph{compiler} error. Do not hesitate to check a header with
|
| 9011 | |
other headers included before, especially required headers.
|
| 9012 | |
|
| 9013 | |
Make sure the symbols you use are properly defined, i.e., refrain from
|
| 9014 | |
simply declaring a function yourself instead of including the proper
|
| 9015 | |
header.
|
| 9016 | |
|
| 9017 | |
Test programs should not write to standard output. They
|
| 9018 | |
should exit with status 0 if the test succeeds, and with status 1
|
| 9019 | |
otherwise, so that success
|
| 9020 | |
can be distinguished easily from a core dump or other failure;
|
| 9021 | |
segmentation violations and other failures produce a nonzero exit
|
| 9022 | |
status. Unless you arrange for @code{exit} to be declared, test
|
| 9023 | |
programs should @code{return}, not @code{exit}, from @code{main},
|
| 9024 | |
because on many systems @code{exit} is not declared by default.
|
| 9025 | |
|
| 9026 | |
Test programs can use @code{#if} or @code{#ifdef} to check the values of
|
| 9027 | |
preprocessor macros defined by tests that have already run. For
|
| 9028 | |
example, if you call @code{AC_HEADER_STDBOOL}, then later on in
|
| 9029 | |
@file{configure.ac} you can have a test program that includes
|
| 9030 | |
@file{stdbool.h} conditionally:
|
| 9031 | |
|
| 9032 | |
@example
|
| 9033 | |
@group
|
| 9034 | |
#ifdef HAVE_STDBOOL_H
|
| 9035 | |
# include <stdbool.h>
|
| 9036 | |
#endif
|
| 9037 | |
@end group
|
| 9038 | |
@end example
|
| 9039 | |
|
| 9040 | |
Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
|
| 9041 | |
work with any standard C compiler. Some developers prefer @code{#if}
|
| 9042 | |
because it is easier to read, while others prefer @code{#ifdef} because
|
| 9043 | |
it avoids diagnostics with picky compilers like GCC with the
|
| 9044 | |
@option{-Wundef} option.
|
| 9045 | |
|
| 9046 | |
If a test program needs to use or create a data file, give it a name
|
| 9047 | |
that starts with @file{conftest}, such as @file{conftest.data}. The
|
| 9048 | |
@command{configure} script cleans up by running @samp{rm -f -r conftest*}
|
| 9049 | |
after running test programs and if the script is interrupted.
|
| 9050 | |
|
| 9051 | |
@node Test Functions
|
| 9052 | |
@subsection Test Functions
|
| 9053 | |
|
| 9054 | |
These days it's safe to assume support for function prototypes
|
| 9055 | |
(introduced in C89).
|
| 9056 | |
|
| 9057 | |
Functions that test programs declare should also be conditionalized for
|
| 9058 | |
C++, which requires @samp{extern "C"} prototypes. Make sure to not
|
| 9059 | |
include any header files containing clashing prototypes.
|
| 9060 | |
|
| 9061 | |
@example
|
| 9062 | |
#ifdef __cplusplus
|
| 9063 | |
extern "C"
|
| 9064 | |
#endif
|
| 9065 | |
void *valloc (size_t);
|
| 9066 | |
@end example
|
| 9067 | |
|
| 9068 | |
If a test program calls a function with invalid parameters (just to see
|
| 9069 | |
whether it exists), organize the program to ensure that it never invokes
|
| 9070 | |
that function. You can do this by calling it in another function that is
|
| 9071 | |
never invoked. You can't do it by putting it after a call to
|
| 9072 | |
@code{exit}, because GCC version 2 knows that @code{exit}
|
| 9073 | |
never returns
|
| 9074 | |
and optimizes out any code that follows it in the same block.
|
| 9075 | |
|
| 9076 | |
If you include any header files, be sure to call the functions
|
| 9077 | |
relevant to them with the correct number of arguments, even if they are
|
| 9078 | |
just 0, to avoid compilation errors due to prototypes. GCC
|
| 9079 | |
version 2
|
| 9080 | |
has internal prototypes for several functions that it automatically
|
| 9081 | |
inlines; for example, @code{memcpy}. To avoid errors when checking for
|
| 9082 | |
them, either pass them the correct number of arguments or redeclare them
|
| 9083 | |
with a different return type (such as @code{char}).
|
| 9084 | |
|
| 9085 | |
|
| 9086 | |
@node Generating Sources
|
| 9087 | |
@subsection Generating Sources
|
| 9088 | |
|
| 9089 | |
Autoconf provides a set of macros that can be used to generate test
|
| 9090 | |
source files. They are written to be language generic, i.e., they
|
| 9091 | |
actually depend on the current language (@pxref{Language Choice}) to
|
| 9092 | |
``format'' the output properly.
|
| 9093 | |
|
| 9094 | |
|
| 9095 | |
@defmac AC_LANG_CONFTEST (@var{source})
|
| 9096 | |
@acindex{LANG_CONFTEST}
|
| 9097 | |
Save the @var{source} text in the current test source file:
|
| 9098 | |
@file{conftest.@var{extension}} where the @var{extension} depends on the
|
| 9099 | |
current language. As of Autoconf 2.63b, the source file also contains
|
| 9100 | |
the results of all of the @code{AC_DEFINE} performed so far.
|
| 9101 | |
|
| 9102 | |
Note that the @var{source} is evaluated exactly once, like regular
|
| 9103 | |
Autoconf macro arguments, and therefore (i) you may pass a macro
|
| 9104 | |
invocation, (ii) if not, be sure to double quote if needed.
|
| 9105 | |
|
| 9106 | |
This macro issues a warning during @command{autoconf} processing if
|
| 9107 | |
@var{source} does not include an expansion of the macro
|
| 9108 | |
@code{AC_LANG_DEFINES_PROVIDED} (note that both @code{AC_LANG_SOURCE} and
|
| 9109 | |
@code{AC_LANG_PROGRAM} call this macro, and thus avoid the warning).
|
| 9110 | |
|
| 9111 | |
This macro is seldom called directly, but is used under the hood by more
|
| 9112 | |
common macros such as @code{AC_COMPILE_IFELSE} and @code{AC_RUN_IFELSE}.
|
| 9113 | |
@end defmac
|
| 9114 | |
|
| 9115 | |
@defmac AC_LANG_DEFINES_PROVIDED
|
| 9116 | |
@acindex{LANG_DEFINES_PROVIDED}
|
| 9117 | |
This macro is called as a witness that the file
|
| 9118 | |
@file{conftest.@var{extension}} appropriate for the current language is
|
| 9119 | |
complete, including all previously determined results from
|
| 9120 | |
@code{AC_DEFINE}. This macro is seldom called directly, but exists if
|
| 9121 | |
you have a compelling reason to write a conftest file without using
|
| 9122 | |
@code{AC_LANG_SOURCE}, yet still want to avoid a syntax warning from
|
| 9123 | |
@code{AC_LANG_CONFTEST}.
|
| 9124 | |
@end defmac
|
| 9125 | |
|
| 9126 | |
@defmac AC_LANG_SOURCE (@var{source})
|
| 9127 | |
@acindex{LANG_SOURCE}
|
| 9128 | |
Expands into the @var{source}, with the definition of
|
| 9129 | |
all the @code{AC_DEFINE} performed so far. This macro includes an
|
| 9130 | |
expansion of @code{AC_LANG_DEFINES_PROVIDED}.
|
| 9131 | |
|
| 9132 | |
In many cases, you may find it more convenient to use the wrapper
|
| 9133 | |
@code{AC_LANG_PROGRAM}.
|
| 9134 | |
@end defmac
|
| 9135 | |
|
| 9136 | |
For instance, executing (observe the double quotation!):
|
| 9137 | |
|
| 9138 | |
@example
|
| 9139 | |
@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
|
| 9140 | |
AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
|
| 9141 | |
[http://www.example.org/])
|
| 9142 | |
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
|
| 9143 | |
[Greetings string.])
|
| 9144 | |
AC_LANG([C])
|
| 9145 | |
AC_LANG_CONFTEST(
|
| 9146 | |
[AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
|
| 9147 | |
gcc -E -dD conftest.c
|
| 9148 | |
@end example
|
| 9149 | |
|
| 9150 | |
@noindent
|
| 9151 | |
on a system with @command{gcc} installed, results in:
|
| 9152 | |
|
| 9153 | |
@example
|
| 9154 | |
@c If you change this example, adjust tests/compile.at:AC_LANG_SOURCE example.
|
| 9155 | |
@dots{}
|
| 9156 | |
# 1 "conftest.c"
|
| 9157 | |
|
| 9158 | |
#define PACKAGE_NAME "Hello"
|
| 9159 | |
#define PACKAGE_TARNAME "hello"
|
| 9160 | |
#define PACKAGE_VERSION "1.0"
|
| 9161 | |
#define PACKAGE_STRING "Hello 1.0"
|
| 9162 | |
#define PACKAGE_BUGREPORT "bug-hello@@example.org"
|
| 9163 | |
#define PACKAGE_URL "http://www.example.org/"
|
| 9164 | |
#define HELLO_WORLD "Hello, World\n"
|
| 9165 | |
|
| 9166 | |
const char hw[] = "Hello, World\n";
|
| 9167 | |
@end example
|
| 9168 | |
|
| 9169 | |
When the test language is Fortran, Erlang, or Go, the @code{AC_DEFINE}
|
| 9170 | |
definitions are not automatically translated into constants in the
|
| 9171 | |
source code by this macro.
|
| 9172 | |
|
| 9173 | |
@defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
|
| 9174 | |
@acindex{LANG_PROGRAM}
|
| 9175 | |
Expands into a source file which consists of the @var{prologue}, and
|
| 9176 | |
then @var{body} as body of the main function (e.g., @code{main} in
|
| 9177 | |
C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
|
| 9178 | |
available.
|
| 9179 | |
@end defmac
|
| 9180 | |
|
| 9181 | |
For instance:
|
| 9182 | |
|
| 9183 | |
@example
|
| 9184 | |
@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
|
| 9185 | |
AC_INIT([Hello], [1.0], [bug-hello@@example.org], [],
|
| 9186 | |
[http://www.example.org/])
|
| 9187 | |
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
|
| 9188 | |
[Greetings string.])
|
| 9189 | |
AC_LANG_CONFTEST(
|
| 9190 | |
[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
|
| 9191 | |
[[fputs (hw, stdout);]])])
|
| 9192 | |
gcc -E -dD conftest.c
|
| 9193 | |
@end example
|
| 9194 | |
|
| 9195 | |
@noindent
|
| 9196 | |
on a system with @command{gcc} installed, results in:
|
| 9197 | |
|
| 9198 | |
@example
|
| 9199 | |
@c If you change this example, adjust tests/compile.at:AC_LANG_PROGRAM example.
|
| 9200 | |
@dots{}
|
| 9201 | |
# 1 "conftest.c"
|
| 9202 | |
|
| 9203 | |
#define PACKAGE_NAME "Hello"
|
| 9204 | |
#define PACKAGE_TARNAME "hello"
|
| 9205 | |
#define PACKAGE_VERSION "1.0"
|
| 9206 | |
#define PACKAGE_STRING "Hello 1.0"
|
| 9207 | |
#define PACKAGE_BUGREPORT "bug-hello@@example.org"
|
| 9208 | |
#define PACKAGE_URL "http://www.example.org/"
|
| 9209 | |
#define HELLO_WORLD "Hello, World\n"
|
| 9210 | |
|
| 9211 | |
const char hw[] = "Hello, World\n";
|
| 9212 | |
int
|
| 9213 | |
main ()
|
| 9214 | |
@{
|
| 9215 | |
fputs (hw, stdout);
|
| 9216 | |
;
|
| 9217 | |
return 0;
|
| 9218 | |
@}
|
| 9219 | |
@end example
|
| 9220 | |
|
| 9221 | |
In Erlang tests, the created source file is that of an Erlang module called
|
| 9222 | |
@code{conftest} (@file{conftest.erl}). This module defines and exports
|
| 9223 | |
at least
|
| 9224 | |
one @code{start/0} function, which is called to perform the test. The
|
| 9225 | |
@var{prologue} is optional code that is inserted between the module header and
|
| 9226 | |
the @code{start/0} function definition. @var{body} is the body of the
|
| 9227 | |
@code{start/0} function without the final period (@pxref{Runtime}, about
|
| 9228 | |
constraints on this function's behavior).
|
| 9229 | |
|
| 9230 | |
For instance:
|
| 9231 | |
|
| 9232 | |
@example
|
| 9233 | |
AC_INIT([Hello], [1.0], [bug-hello@@example.org])
|
| 9234 | |
AC_LANG(Erlang)
|
| 9235 | |
AC_LANG_CONFTEST(
|
| 9236 | |
[AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
|
| 9237 | |
[[io:format("~s~n", [?HELLO_WORLD])]])])
|
| 9238 | |
cat conftest.erl
|
| 9239 | |
@end example
|
| 9240 | |
|
| 9241 | |
@noindent
|
| 9242 | |
results in:
|
| 9243 | |
|
| 9244 | |
@example
|
| 9245 | |
-module(conftest).
|
| 9246 | |
-export([start/0]).
|
| 9247 | |
-define(HELLO_WORLD, "Hello, world!").
|
| 9248 | |
start() ->
|
| 9249 | |
io:format("~s~n", [?HELLO_WORLD])
|
| 9250 | |
.
|
| 9251 | |
@end example
|
| 9252 | |
|
| 9253 | |
@defmac AC_LANG_CALL (@var{prologue}, @var{function})
|
| 9254 | |
@acindex{LANG_CALL}
|
| 9255 | |
Expands into a source file which consists of the @var{prologue}, and
|
| 9256 | |
then a call to the @var{function} as body of the main function (e.g.,
|
| 9257 | |
@code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
|
| 9258 | |
of the latter are available.
|
| 9259 | |
|
| 9260 | |
This function will probably be replaced in the future by a version
|
| 9261 | |
which would enable specifying the arguments. The use of this macro is
|
| 9262 | |
not encouraged, as it violates strongly the typing system.
|
| 9263 | |
|
| 9264 | |
This macro cannot be used for Erlang tests.
|
| 9265 | |
@end defmac
|
| 9266 | |
|
| 9267 | |
@defmac AC_LANG_FUNC_LINK_TRY (@var{function})
|
| 9268 | |
@acindex{LANG_FUNC_LINK_TRY}
|
| 9269 | |
Expands into a source file which uses the @var{function} in the body of
|
| 9270 | |
the main function (e.g., @code{main} in C). Since it uses
|
| 9271 | |
@code{AC_LANG_PROGRAM}, the features of the latter are available.
|
| 9272 | |
|
| 9273 | |
As @code{AC_LANG_CALL}, this macro is documented only for completeness.
|
| 9274 | |
It is considered to be severely broken, and in the future will be
|
| 9275 | |
removed in favor of actual function calls (with properly typed
|
| 9276 | |
arguments).
|
| 9277 | |
|
| 9278 | |
This macro cannot be used for Erlang tests.
|
| 9279 | |
@end defmac
|
| 9280 | |
|
| 9281 | |
@node Running the Preprocessor
|
| 9282 | |
@section Running the Preprocessor
|
| 9283 | |
|
| 9284 | |
Sometimes one might need to run the preprocessor on some source file.
|
| 9285 | |
@emph{Usually it is a bad idea}, as you typically need to @emph{compile}
|
| 9286 | |
your project, not merely run the preprocessor on it; therefore you
|
| 9287 | |
certainly want to run the compiler, not the preprocessor. Resist the
|
| 9288 | |
temptation of following the easiest path.
|
| 9289 | |
|
| 9290 | |
Nevertheless, if you need to run the preprocessor, then use
|
| 9291 | |
@code{AC_PREPROC_IFELSE}.
|
| 9292 | |
|
| 9293 | |
The macros described in this section cannot be used for tests in Erlang,
|
| 9294 | |
Fortran, or Go, since those languages require no preprocessor.
|
| 9295 | |
|
| 9296 | |
@anchor{AC_PREPROC_IFELSE}
|
| 9297 | |
@defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @
|
| 9298 | |
@ovar{action-if-false})
|
| 9299 | |
@acindex{PREPROC_IFELSE}
|
| 9300 | |
Run the preprocessor of the current language (@pxref{Language Choice})
|
| 9301 | |
on the @var{input}, run the shell commands @var{action-if-true} on
|
| 9302 | |
success, @var{action-if-false} otherwise. The @var{input} can be made
|
| 9303 | |
by @code{AC_LANG_PROGRAM} and friends.
|
| 9304 | |
|
| 9305 | |
This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
|
| 9306 | |
@option{-g}, @option{-O}, etc.@: are not valid options to many C
|
| 9307 | |
preprocessors.
|
| 9308 | |
|
| 9309 | |
It is customary to report unexpected failures with
|
| 9310 | |
@code{AC_MSG_FAILURE}. If needed, @var{action-if-true} can further access
|
| 9311 | |
the preprocessed output in the file @file{conftest.i}.
|
| 9312 | |
@end defmac
|
| 9313 | |
|
| 9314 | |
For instance:
|
| 9315 | |
|
| 9316 | |
@example
|
| 9317 | |
AC_INIT([Hello], [1.0], [bug-hello@@example.org])
|
| 9318 | |
AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
|
| 9319 | |
[Greetings string.])
|
| 9320 | |
AC_PREPROC_IFELSE(
|
| 9321 | |
[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
|
| 9322 | |
[[fputs (hw, stdout);]])],
|
| 9323 | |
[AC_MSG_RESULT([OK])],
|
| 9324 | |
[AC_MSG_FAILURE([unexpected preprocessor failure])])
|
| 9325 | |
@end example
|
| 9326 | |
|
| 9327 | |
@noindent
|
| 9328 | |
results in:
|
| 9329 | |
|
| 9330 | |
@example
|
| 9331 | |
checking for gcc... gcc
|
| 9332 | |
checking for C compiler default output file name... a.out
|
| 9333 | |
checking whether the C compiler works... yes
|
| 9334 | |
checking whether we are cross compiling... no
|
| 9335 | |
checking for suffix of executables...
|
| 9336 | |
checking for suffix of object files... o
|
| 9337 | |
checking whether we are using the GNU C compiler... yes
|
| 9338 | |
checking whether gcc accepts -g... yes
|
| 9339 | |
checking for gcc option to accept ISO C89... none needed
|
| 9340 | |
checking how to run the C preprocessor... gcc -E
|
| 9341 | |
OK
|
| 9342 | |
@end example
|
| 9343 | |
|
| 9344 | |
@sp 1
|
| 9345 | |
|
| 9346 | |
The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
|
| 9347 | |
role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
|
| 9348 | |
it impossible to use it to elaborate sources. You are encouraged to
|
| 9349 | |
get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
|
| 9350 | |
@code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
|
| 9351 | |
to run the @emph{preprocessor} and not the compiler?
|
| 9352 | |
|
| 9353 | |
@anchor{AC_EGREP_HEADER}
|
| 9354 | |
@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @
|
| 9355 | |
@var{action-if-found}, @ovar{action-if-not-found})
|
| 9356 | |
@acindex{EGREP_HEADER}
|
| 9357 | |
If the output of running the preprocessor on the system header file
|
| 9358 | |
@var{header-file} matches the extended regular expression
|
| 9359 | |
@var{pattern}, execute shell commands @var{action-if-found}, otherwise
|
| 9360 | |
execute @var{action-if-not-found}.
|
| 9361 | |
@end defmac
|
| 9362 | |
|
| 9363 | |
@anchor{AC_EGREP_CPP}
|
| 9364 | |
@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @
|
| 9365 | |
@ovar{action-if-found}, @ovar{action-if-not-found})
|
| 9366 | |
@acindex{EGREP_CPP}
|
| 9367 | |
@var{program} is the text of a C or C++ program, on which shell
|
| 9368 | |
variable, back quote, and backslash substitutions are performed. If the
|
| 9369 | |
output of running the preprocessor on @var{program} matches the
|
| 9370 | |
extended regular expression @var{pattern}, execute shell commands
|
| 9371 | |
@var{action-if-found}, otherwise execute @var{action-if-not-found}.
|
| 9372 | |
@end defmac
|
| 9373 | |
|
| 9374 | |
|
| 9375 | |
|
| 9376 | |
@node Running the Compiler
|
| 9377 | |
@section Running the Compiler
|
| 9378 | |
|
| 9379 | |
To check for a syntax feature of the current language's (@pxref{Language
|
| 9380 | |
Choice}) compiler, such as whether it recognizes a certain keyword, or
|
| 9381 | |
simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
|
| 9382 | |
to compile a small program that uses that feature.
|
| 9383 | |
|
| 9384 | |
@defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @
|
| 9385 | |
@ovar{action-if-false})
|
| 9386 | |
@acindex{COMPILE_IFELSE}
|
| 9387 | |
Run the compiler and compilation flags of the current language
|
| 9388 | |
(@pxref{Language Choice}) on the @var{input}, run the shell commands
|
| 9389 | |
@var{action-if-true} on success, @var{action-if-false} otherwise. The
|
| 9390 | |
@var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
|
| 9391 | |
|
| 9392 | |
It is customary to report unexpected failures with
|
| 9393 | |
@code{AC_MSG_FAILURE}. This macro does not try to link; use
|
| 9394 | |
@code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
|
| 9395 | |
Linker}). If needed, @var{action-if-true} can further access the
|
| 9396 | |
just-compiled object file @file{conftest.$OBJEXT}.
|
| 9397 | |
|
| 9398 | |
This macro uses @code{AC_REQUIRE} for the compiler associated with the
|
| 9399 | |
current language, which means that if the compiler has not yet been
|
| 9400 | |
determined, the compiler determination will be made prior to the body of
|
| 9401 | |
the outermost @code{AC_DEFUN} macro that triggered this macro to
|
| 9402 | |
expand (@pxref{Expanded Before Required}).
|
| 9403 | |
@end defmac
|
| 9404 | |
|
| 9405 | |
@ovindex ERL
|
| 9406 | |
For tests in Erlang, the @var{input} must be the source code of a module named
|
| 9407 | |
@code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
|
| 9408 | |
file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
|
| 9409 | |
recommended to use @code{AC_LANG_PROGRAM} to specify the test program,
|
| 9410 | |
to ensure that the Erlang module has the right name.
|
| 9411 | |
|
| 9412 | |
@node Running the Linker
|
| 9413 | |
@section Running the Linker
|
| 9414 | |
|
| 9415 | |
To check for a library, a function, or a global variable, Autoconf
|
| 9416 | |
@command{configure} scripts try to compile and link a small program that
|
| 9417 | |
uses it. This is unlike Metaconfig, which by default uses @code{nm} or
|
| 9418 | |
@code{ar} on the C library to try to figure out which functions are
|
| 9419 | |
available. Trying to link with the function is usually a more reliable
|
| 9420 | |
approach because it avoids dealing with the variations in the options
|
| 9421 | |
and output formats of @code{nm} and @code{ar} and in the location of the
|
| 9422 | |
standard libraries. It also allows configuring for cross-compilation or
|
| 9423 | |
checking a function's runtime behavior if needed. On the other hand,
|
| 9424 | |
it can be slower than scanning the libraries once, but accuracy is more
|
| 9425 | |
important than speed.
|
| 9426 | |
|
| 9427 | |
@code{AC_LINK_IFELSE} is used to compile test programs to test for
|
| 9428 | |
functions and global variables. It is also used by @code{AC_CHECK_LIB}
|
| 9429 | |
to check for libraries (@pxref{Libraries}), by adding the library being
|
| 9430 | |
checked for to @code{LIBS} temporarily and trying to link a small
|
| 9431 | |
program.
|
| 9432 | |
|
| 9433 | |
@anchor{AC_LINK_IFELSE}
|
| 9434 | |
@defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @
|
| 9435 | |
@ovar{action-if-false})
|
| 9436 | |
@acindex{LINK_IFELSE}
|
| 9437 | |
Run the compiler (and compilation flags) and the linker of the current
|
| 9438 | |
language (@pxref{Language Choice}) on the @var{input}, run the shell
|
| 9439 | |
commands @var{action-if-true} on success, @var{action-if-false}
|
| 9440 | |
otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
|
| 9441 | |
friends. If needed, @var{action-if-true} can further access the
|
| 9442 | |
just-linked program file @file{conftest$EXEEXT}.
|
| 9443 | |
|
| 9444 | |
@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
|
| 9445 | |
current compilation flags.
|
| 9446 | |
|
| 9447 | |
It is customary to report unexpected failures with
|
| 9448 | |
@code{AC_MSG_FAILURE}. This macro does not try to execute the program;
|
| 9449 | |
use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
|
| 9450 | |
@end defmac
|
| 9451 | |
|
| 9452 | |
The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
|
| 9453 | |
programs are interpreted and do not require linking.
|
| 9454 | |
|
| 9455 | |
|
| 9456 | |
|
| 9457 | |
@node Runtime
|
| 9458 | |
@section Checking Runtime Behavior
|
| 9459 | |
|
| 9460 | |
Sometimes you need to find out how a system performs at runtime, such
|
| 9461 | |
as whether a given function has a certain capability or bug. If you
|
| 9462 | |
can, make such checks when your program runs instead of when it is
|
| 9463 | |
configured. You can check for things like the machine's endianness when
|
| 9464 | |
your program initializes itself.
|
| 9465 | |
|
| 9466 | |
If you really need to test for a runtime behavior while configuring,
|
| 9467 | |
you can write a test program to determine the result, and compile and
|
| 9468 | |
run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
|
| 9469 | |
possible, because this prevents people from configuring your package for
|
| 9470 | |
cross-compiling.
|
| 9471 | |
|
| 9472 | |
@anchor{AC_RUN_IFELSE}
|
| 9473 | |
@defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @
|
| 9474 | |
@ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE})
|
| 9475 | |
@acindex{RUN_IFELSE}
|
| 9476 | |
Run the compiler (and compilation flags) and the linker of the current
|
| 9477 | |
language (@pxref{Language Choice}) on the @var{input}, then execute the
|
| 9478 | |
resulting program. If the program returns an exit
|
| 9479 | |
status of 0 when executed, run shell commands @var{action-if-true}.
|
| 9480 | |
Otherwise, run shell commands @var{action-if-false}.
|
| 9481 | |
|
| 9482 | |
The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
|
| 9483 | |
@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
|
| 9484 | |
compilation flags of the current language (@pxref{Language Choice}).
|
| 9485 | |
Additionally, @var{action-if-true} can run @command{./conftest$EXEEXT}
|
| 9486 | |
for further testing.
|
| 9487 | |
|
| 9488 | |
In the @var{action-if-false} section, the failing exit status is
|
| 9489 | |
available in the shell variable @samp{$?}. This exit status might be
|
| 9490 | |
that of a failed compilation, or it might be that of a failed program
|
| 9491 | |
execution.
|
| 9492 | |
|
| 9493 | |
If cross-compilation mode is enabled (this is the case if either the
|
| 9494 | |
compiler being used does not produce executables that run on the system
|
| 9495 | |
where @command{configure} is being run, or if the options @code{--build}
|
| 9496 | |
and @code{--host} were both specified and their values are different),
|
| 9497 | |
then the test program is
|
| 9498 | |
not run. If the optional shell commands @var{action-if-cross-compiling}
|
| 9499 | |
are given, those commands are run instead; typically these commands
|
| 9500 | |
provide pessimistic defaults that allow cross-compilation to work even
|
| 9501 | |
if the guess was wrong. If the fourth argument is empty or omitted, but
|
| 9502 | |
cross-compilation is detected, then @command{configure} prints an error
|
| 9503 | |
message and exits. If you want your package to be useful in a
|
| 9504 | |
cross-compilation scenario, you @emph{should} provide a non-empty
|
| 9505 | |
@var{action-if-cross-compiling} clause, as well as wrap the
|
| 9506 | |
@code{AC_RUN_IFELSE} compilation inside an @code{AC_CACHE_CHECK}
|
| 9507 | |
(@pxref{Caching Results}) which allows the user to override the
|
| 9508 | |
pessimistic default if needed.
|
| 9509 | |
|
| 9510 | |
It is customary to report unexpected failures with
|
| 9511 | |
@code{AC_MSG_FAILURE}.
|
| 9512 | |
@end defmac
|
| 9513 | |
|
| 9514 | |
@command{autoconf} prints a warning message when creating
|
| 9515 | |
@command{configure} each time it encounters a call to
|
| 9516 | |
@code{AC_RUN_IFELSE} with no @var{action-if-cross-compiling} argument
|
| 9517 | |
given. If you are not concerned about users configuring your package
|
| 9518 | |
for cross-compilation, you may ignore the warning. A few of the macros
|
| 9519 | |
distributed with Autoconf produce this warning message; but if this is a
|
| 9520 | |
problem for you, please report it as a bug, along with an appropriate
|
| 9521 | |
pessimistic guess to use instead.
|
| 9522 | |
|
| 9523 | |
To configure for cross-compiling you can also choose a value for those
|
| 9524 | |
parameters based on the canonical system name (@pxref{Manual
|
| 9525 | |
Configuration}). Alternatively, set up a test results cache file with
|
| 9526 | |
the correct values for the host system (@pxref{Caching Results}).
|
| 9527 | |
|
| 9528 | |
@ovindex cross_compiling
|
| 9529 | |
To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
|
| 9530 | |
in other macros, including a few of the ones that come with Autoconf,
|
| 9531 | |
you can test whether the shell variable @code{cross_compiling} is set to
|
| 9532 | |
@samp{yes}, and then use an alternate method to get the results instead
|
| 9533 | |
of calling the macros.
|
| 9534 | |
|
| 9535 | |
It is also permissible to temporarily assign to @code{cross_compiling}
|
| 9536 | |
in order to force tests to behave as though they are in a
|
| 9537 | |
cross-compilation environment, particularly since this provides a way to
|
| 9538 | |
test your @var{action-if-cross-compiling} even when you are not using a
|
| 9539 | |
cross-compiler.
|
| 9540 | |
|
| 9541 | |
@example
|
| 9542 | |
# We temporarily set cross-compile mode to force AC_COMPUTE_INT
|
| 9543 | |
# to use the slow link-only method
|
| 9544 | |
save_cross_compiling=$cross_compiling
|
| 9545 | |
cross_compiling=yes
|
| 9546 | |
AC_COMPUTE_INT([@dots{}])
|
| 9547 | |
cross_compiling=$save_cross_compiling
|
| 9548 | |
@end example
|
| 9549 | |
|
| 9550 | |
A C or C++ runtime test should be portable.
|
| 9551 | |
@xref{Portable C and C++}.
|
| 9552 | |
|
| 9553 | |
Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
|
| 9554 | |
function: the given status code is used to determine the success of the test
|
| 9555 | |
(status is @code{0}) or its failure (status is different than @code{0}), as
|
| 9556 | |
explained above. It must be noted that data output through the standard output
|
| 9557 | |
(e.g., using @code{io:format/2}) may be truncated when halting the VM.
|
| 9558 | |
Therefore, if a test must output configuration information, it is recommended
|
| 9559 | |
to create and to output data into the temporary file named @file{conftest.out},
|
| 9560 | |
using the functions of module @code{file}. The @code{conftest.out} file is
|
| 9561 | |
automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
|
| 9562 | |
simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR}
|
| 9563 | |
macro is:
|
| 9564 | |
|
| 9565 | |
@example
|
| 9566 | |
AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
|
| 9567 | |
AC_ERLANG_NEED_ERL
|
| 9568 | |
AC_LANG(Erlang)
|
| 9569 | |
AC_RUN_IFELSE(
|
| 9570 | |
[AC_LANG_PROGRAM([], [dnl
|
| 9571 | |
file:write_file("conftest.out", code:lib_dir()),
|
| 9572 | |
halt(0)])],
|
| 9573 | |
[echo "code:lib_dir() returned: `cat conftest.out`"],
|
| 9574 | |
[AC_MSG_FAILURE([test Erlang program execution failed])])
|
| 9575 | |
@end example
|
| 9576 | |
|
| 9577 | |
|
| 9578 | |
@node Systemology
|
| 9579 | |
@section Systemology
|
| 9580 | |
@cindex Systemology
|
| 9581 | |
|
| 9582 | |
This section aims at presenting some systems and pointers to
|
| 9583 | |
documentation. It may help you addressing particular problems reported
|
| 9584 | |
by users.
|
| 9585 | |
|
| 9586 | |
@uref{http://@/www.opengroup.org/@/susv3, Posix-conforming systems} are
|
| 9587 | |
derived from the @uref{http://@/www.bell-labs.com/@/history/@/unix/, Unix
|
| 9588 | |
operating system}.
|
| 9589 | |
|
| 9590 | |
The @uref{http://@/bhami.com/@/rosetta.html, Rosetta Stone for Unix}
|
| 9591 | |
contains a table correlating the features of various Posix-conforming
|
| 9592 | |
systems. @uref{http://@/www.levenez.com/@/unix/, Unix History} is a
|
| 9593 | |
simplified diagram of how many Unix systems were derived from each
|
| 9594 | |
other.
|
| 9595 | |
|
| 9596 | |
@uref{http://@/heirloom.sourceforge.net/, The Heirloom Project}
|
| 9597 | |
provides some variants of traditional implementations of Unix utilities.
|
| 9598 | |
|
| 9599 | |
@table @asis
|
| 9600 | |
@item Darwin
|
| 9601 | |
@cindex Darwin
|
| 9602 | |
Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
|
| 9603 | |
case-preserving, but case insensitive. This can cause nasty problems,
|
| 9604 | |
since for instance the installation attempt for a package having an
|
| 9605 | |
@file{INSTALL} file can result in @samp{make install} report that
|
| 9606 | |
nothing was to be done!
|
| 9607 | |
|
| 9608 | |
That's all dependent on whether the file system is a UFS (case
|
| 9609 | |
sensitive) or HFS+ (case preserving). By default Apple wants you to
|
| 9610 | |
install the OS on HFS+. Unfortunately, there are some pieces of
|
| 9611 | |
software which really need to be built on UFS@. We may want to rebuild
|
| 9612 | |
Darwin to have both UFS and HFS+ available (and put the /local/build
|
| 9613 | |
tree on the UFS).
|
| 9614 | |
|
| 9615 | |
@item QNX 4.25
|
| 9616 | |
@cindex QNX 4.25
|
| 9617 | |
@c FIXME: Please, if you feel like writing something more precise,
|
| 9618 | |
@c it'd be great. In particular, I can't understand the difference with
|
| 9619 | |
@c QNX Neutrino.
|
| 9620 | |
QNX is a realtime operating system running on Intel architecture
|
| 9621 | |
meant to be scalable from the small embedded systems to the hundred
|
| 9622 | |
processor super-computer. It claims to be Posix certified. More
|
| 9623 | |
information is available on the
|
| 9624 | |
@uref{http://@/www.qnx.com/, QNX home page}.
|
| 9625 | |
|
| 9626 | |
@item Tru64
|
| 9627 | |
@cindex Tru64
|
| 9628 | |
@uref{http://@/h30097.www3.hp.com/@/docs/,
|
| 9629 | |
Documentation of several versions of Tru64} is available in different
|
| 9630 | |
formats.
|
| 9631 | |
|
| 9632 | |
@item Unix version 7
|
| 9633 | |
@cindex Unix version 7
|
| 9634 | |
@cindex V7
|
| 9635 | |
Officially this was called the ``Seventh Edition'' of ``the UNIX
|
| 9636 | |
time-sharing system'' but we use the more-common name ``Unix version 7''.
|
| 9637 | |
Documentation is available in the
|
| 9638 | |
@uref{http://@/plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
|
| 9639 | |
Previous versions of Unix are called ``Unix version 6'', etc., but
|
| 9640 | |
they were not as widely used.
|
| 9641 | |
@end table
|
| 9642 | |
|
| 9643 | |
|
| 9644 | |
@node Multiple Cases
|
| 9645 | |
@section Multiple Cases
|
| 9646 | |
|
| 9647 | |
Some operations are accomplished in several possible ways, depending on
|
| 9648 | |
the OS variant. Checking for them essentially requires a ``case
|
| 9649 | |
statement''. Autoconf does not directly provide one; however, it is
|
| 9650 | |
easy to simulate by using a shell variable to keep track of whether a
|
| 9651 | |
way to perform the operation has been found yet.
|
| 9652 | |
|
| 9653 | |
Here is an example that uses the shell variable @code{fstype} to keep
|
| 9654 | |
track of whether the remaining cases need to be checked. Note that
|
| 9655 | |
since the value of @code{fstype} is under our control, we don't have to
|
| 9656 | |
use the longer @samp{test "x$fstype" = xno}.
|
| 9657 | |
|
| 9658 | |
@example
|
| 9659 | |
@group
|
| 9660 | |
AC_MSG_CHECKING([how to get file system type])
|
| 9661 | |
fstype=no
|
| 9662 | |
# The order of these tests is important.
|
| 9663 | |
AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
|
| 9664 | |
#include <sys/fstyp.h>]])],
|
| 9665 | |
[AC_DEFINE([FSTYPE_STATVFS], [1],
|
| 9666 | |
[Define if statvfs exists.])
|
| 9667 | |
fstype=SVR4])
|
| 9668 | |
if test $fstype = no; then
|
| 9669 | |
AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
|
| 9670 | |
#include <sys/fstyp.h>]])],
|
| 9671 | |
[AC_DEFINE([FSTYPE_USG_STATFS], [1],
|
| 9672 | |
[Define if USG statfs.])
|
| 9673 | |
fstype=SVR3])
|
| 9674 | |
fi
|
| 9675 | |
if test $fstype = no; then
|
| 9676 | |
AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
|
| 9677 | |
#include <sys/vmount.h>]])]),
|
| 9678 | |
[AC_DEFINE([FSTYPE_AIX_STATFS], [1],
|
| 9679 | |
[Define if AIX statfs.])
|
| 9680 | |
fstype=AIX])
|
| 9681 | |
fi
|
| 9682 | |
# (more cases omitted here)
|
| 9683 | |
AC_MSG_RESULT([$fstype])
|
| 9684 | |
@end group
|
| 9685 | |
@end example
|
| 9686 | |
|
| 9687 | |
@c ====================================================== Results of Tests.
|
| 9688 | |
|
| 9689 | |
@node Results
|
| 9690 | |
@chapter Results of Tests
|
| 9691 | |
|
| 9692 | |
Once @command{configure} has determined whether a feature exists, what can
|
| 9693 | |
it do to record that information? There are four sorts of things it can
|
| 9694 | |
do: define a C preprocessor symbol, set a variable in the output files,
|
| 9695 | |
save the result in a cache file for future @command{configure} runs, and
|
| 9696 | |
print a message letting the user know the result of the test.
|
| 9697 | |
|
| 9698 | |
@menu
|
| 9699 | |
* Defining Symbols:: Defining C preprocessor symbols
|
| 9700 | |
* Setting Output Variables:: Replacing variables in output files
|
| 9701 | |
* Special Chars in Variables:: Characters to beware of in variables
|
| 9702 | |
* Caching Results:: Speeding up subsequent @command{configure} runs
|
| 9703 | |
* Printing Messages:: Notifying @command{configure} users
|
| 9704 | |
@end menu
|
| 9705 | |
|
| 9706 | |
@node Defining Symbols
|
| 9707 | |
@section Defining C Preprocessor Symbols
|
| 9708 | |
|
| 9709 | |
A common action to take in response to a feature test is to define a C
|
| 9710 | |
preprocessor symbol indicating the results of the test. That is done by
|
| 9711 | |
calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
|
| 9712 | |
|
| 9713 | |
By default, @code{AC_OUTPUT} places the symbols defined by these macros
|
| 9714 | |
into the output variable @code{DEFS}, which contains an option
|
| 9715 | |
@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
|
| 9716 | |
Autoconf version 1, there is no variable @code{DEFS} defined while
|
| 9717 | |
@command{configure} is running. To check whether Autoconf macros have
|
| 9718 | |
already defined a certain C preprocessor symbol, test the value of the
|
| 9719 | |
appropriate cache variable, as in this example:
|
| 9720 | |
|
| 9721 | |
@example
|
| 9722 | |
AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
|
| 9723 | |
[Define if vprintf exists.])])
|
| 9724 | |
if test "x$ac_cv_func_vprintf" != xyes; then
|
| 9725 | |
AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
|
| 9726 | |
[Define if _doprnt exists.])])
|
| 9727 | |
fi
|
| 9728 | |
@end example
|
| 9729 | |
|
| 9730 | |
If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
|
| 9731 | |
@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
|
| 9732 | |
correct values into @code{#define} statements in a template file.
|
| 9733 | |
@xref{Configuration Headers}, for more information about this kind of
|
| 9734 | |
output.
|
| 9735 | |
|
| 9736 | |
@defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
|
| 9737 | |
@defmacx AC_DEFINE (@var{variable})
|
| 9738 | |
@cvindex @var{variable}
|
| 9739 | |
@acindex{DEFINE}
|
| 9740 | |
Define @var{variable} to @var{value} (verbatim), by defining a C
|
| 9741 | |
preprocessor macro for @var{variable}. @var{variable} should be a C
|
| 9742 | |
identifier, optionally suffixed by a parenthesized argument list to
|
| 9743 | |
define a C preprocessor macro with arguments. The macro argument list,
|
| 9744 | |
if present, should be a comma-separated list of C identifiers, possibly
|
| 9745 | |
terminated by an ellipsis @samp{...} if C99 syntax is employed.
|
| 9746 | |
@var{variable} should not contain comments, white space, trigraphs,
|
| 9747 | |
backslash-newlines, universal character names, or non-ASCII
|
| 9748 | |
characters.
|
| 9749 | |
|
| 9750 | |
@var{value} may contain backslash-escaped newlines, which will be
|
| 9751 | |
preserved if you use @code{AC_CONFIG_HEADERS} but flattened if passed
|
| 9752 | |
via @code{@@DEFS@@} (with no effect on the compilation, since the
|
| 9753 | |
preprocessor sees only one line in the first place). @var{value} should
|
| 9754 | |
not contain raw newlines. If you are not using
|
| 9755 | |
@code{AC_CONFIG_HEADERS}, @var{value} should not contain any @samp{#}
|
| 9756 | |
characters, as @command{make} tends to eat them. To use a shell
|
| 9757 | |
variable, use @code{AC_DEFINE_UNQUOTED} instead.
|
| 9758 | |
|
| 9759 | |
@var{description} is only useful if you are using
|
| 9760 | |
@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
|
| 9761 | |
the generated @file{config.h.in} as the comment before the macro define.
|
| 9762 | |
The following example defines the C preprocessor variable
|
| 9763 | |
@code{EQUATION} to be the string constant @samp{"$a > $b"}:
|
| 9764 | |
|
| 9765 | |
@example
|
| 9766 | |
AC_DEFINE([EQUATION], ["$a > $b"],
|
| 9767 | |
[Equation string.])
|
| 9768 | |
@end example
|
| 9769 | |
|
| 9770 | |
If neither @var{value} nor @var{description} are given, then
|
| 9771 | |
@var{value} defaults to 1 instead of to the empty string. This is for
|
| 9772 | |
backwards compatibility with older versions of Autoconf, but this usage
|
| 9773 | |
is obsolescent and may be withdrawn in future versions of Autoconf.
|
| 9774 | |
|
| 9775 | |
If the @var{variable} is a literal string, it is passed to
|
| 9776 | |
@code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
|
| 9777 | |
|
| 9778 | |
If multiple @code{AC_DEFINE} statements are executed for the same
|
| 9779 | |
@var{variable} name (not counting any parenthesized argument list),
|
| 9780 | |
the last one wins.
|
| 9781 | |
@end defmac
|
| 9782 | |
|
| 9783 | |
@defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
|
| 9784 | |
@defmacx AC_DEFINE_UNQUOTED (@var{variable})
|
| 9785 | |
@acindex{DEFINE_UNQUOTED}
|
| 9786 | |
@cvindex @var{variable}
|
| 9787 | |
Like @code{AC_DEFINE}, but three shell expansions are
|
| 9788 | |
performed---once---on @var{variable} and @var{value}: variable expansion
|
| 9789 | |
(@samp{$}), command substitution (@samp{`}), and backslash escaping
|
| 9790 | |
(@samp{\}), as if in an unquoted here-document. Single and double quote
|
| 9791 | |
characters in the value have no
|
| 9792 | |
special meaning. Use this macro instead of @code{AC_DEFINE} when
|
| 9793 | |
@var{variable} or @var{value} is a shell variable. Examples:
|
| 9794 | |
|
| 9795 | |
@example
|
| 9796 | |
AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
|
| 9797 | |
[Configuration machine file.])
|
| 9798 | |
AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
|
| 9799 | |
[getgroups return type.])
|
| 9800 | |
AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
|
| 9801 | |
[Translated header name.])
|
| 9802 | |
@end example
|
| 9803 | |
@end defmac
|
| 9804 | |
|
| 9805 | |
Due to a syntactical bizarreness of the Bourne shell, do not use
|
| 9806 | |
semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
|
| 9807 | |
calls from other macro calls or shell code; that can cause syntax errors
|
| 9808 | |
in the resulting @command{configure} script. Use either blanks or
|
| 9809 | |
newlines. That is, do this:
|
| 9810 | |
|
| 9811 | |
@example
|
| 9812 | |
AC_CHECK_HEADER([elf.h],
|
| 9813 | |
[AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
|
| 9814 | |
@end example
|
| 9815 | |
|
| 9816 | |
@noindent
|
| 9817 | |
or this:
|
| 9818 | |
|
| 9819 | |
@example
|
| 9820 | |
AC_CHECK_HEADER([elf.h],
|
| 9821 | |
[AC_DEFINE([SVR4], [1], [System V Release 4])
|
| 9822 | |
LIBS="-lelf $LIBS"])
|
| 9823 | |
@end example
|
| 9824 | |
|
| 9825 | |
@noindent
|
| 9826 | |
instead of this:
|
| 9827 | |
|
| 9828 | |
@example
|
| 9829 | |
AC_CHECK_HEADER([elf.h],
|
| 9830 | |
[AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
|
| 9831 | |
@end example
|
| 9832 | |
|
| 9833 | |
@node Setting Output Variables
|
| 9834 | |
@section Setting Output Variables
|
| 9835 | |
@cindex Output variables
|
| 9836 | |
|
| 9837 | |
Another way to record the results of tests is to set @dfn{output
|
| 9838 | |
variables}, which are shell variables whose values are substituted into
|
| 9839 | |
files that @command{configure} outputs. The two macros below create new
|
| 9840 | |
output variables. @xref{Preset Output Variables}, for a list of output
|
| 9841 | |
variables that are always available.
|
| 9842 | |
|
| 9843 | |
@defmac AC_SUBST (@var{variable}, @ovar{value})
|
| 9844 | |
@acindex{SUBST}
|
| 9845 | |
Create an output variable from a shell variable. Make @code{AC_OUTPUT}
|
| 9846 | |
substitute the variable @var{variable} into output files (typically one
|
| 9847 | |
or more makefiles). This means that @code{AC_OUTPUT}
|
| 9848 | |
replaces instances of @samp{@@@var{variable}@@} in input files with the
|
| 9849 | |
value that the shell variable @var{variable} has when @code{AC_OUTPUT}
|
| 9850 | |
is called. The value can contain any non-@code{NUL} character, including
|
| 9851 | |
newline. If you are using Automake 1.11 or newer, for newlines in values
|
| 9852 | |
you might want to consider using @code{AM_SUBST_NOTMAKE} to prevent
|
| 9853 | |
@command{automake} from adding a line @code{@var{variable} =
|
| 9854 | |
@@@var{variable}@@} to the @file{Makefile.in} files (@pxref{Optional, ,
|
| 9855 | |
Automake, automake, Other things Automake recognizes}).
|
| 9856 | |
|
| 9857 | |
Variable occurrences should not overlap: e.g., an input file should
|
| 9858 | |
not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
|
| 9859 | |
are variable names.
|
| 9860 | |
The substituted value is not rescanned for more output variables;
|
| 9861 | |
occurrences of @samp{@@@var{variable}@@} in the value are inserted
|
| 9862 | |
literally into the output file. (The algorithm uses the special marker
|
| 9863 | |
@code{|#_!!_#|} internally, so neither the substituted value nor the
|
| 9864 | |
output file may contain @code{|#_!!_#|}.)
|
| 9865 | |
|
| 9866 | |
If @var{value} is given, in addition assign it to @var{variable}.
|
| 9867 | |
|
| 9868 | |
The string @var{variable} is passed to @code{m4_pattern_allow}
|
| 9869 | |
(@pxref{Forbidden Patterns}).
|
| 9870 | |
@end defmac
|
| 9871 | |
|
| 9872 | |
@defmac AC_SUBST_FILE (@var{variable})
|
| 9873 | |
@acindex{SUBST_FILE}
|
| 9874 | |
Another way to create an output variable from a shell variable. Make
|
| 9875 | |
@code{AC_OUTPUT} insert (without substitutions) the contents of the file
|
| 9876 | |
named by shell variable @var{variable} into output files. This means
|
| 9877 | |
that @code{AC_OUTPUT} replaces instances of
|
| 9878 | |
@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
|
| 9879 | |
with the contents of the file that the shell variable @var{variable}
|
| 9880 | |
names when @code{AC_OUTPUT} is called. Set the variable to
|
| 9881 | |
@file{/dev/null} for cases that do not have a file to insert.
|
| 9882 | |
This substitution occurs only when the @samp{@@@var{variable}@@} is on a
|
| 9883 | |
line by itself, optionally surrounded by spaces and tabs. The
|
| 9884 | |
substitution replaces the whole line, including the spaces, tabs, and
|
| 9885 | |
the terminating newline.
|
| 9886 | |
|
| 9887 | |
This macro is useful for inserting makefile fragments containing
|
| 9888 | |
special dependencies or other @command{make} directives for particular host
|
| 9889 | |
or target types into makefiles. For example, @file{configure.ac}
|
| 9890 | |
could contain:
|
| 9891 | |
|
| 9892 | |
@example
|
| 9893 | |
AC_SUBST_FILE([host_frag])
|
| 9894 | |
host_frag=$srcdir/conf/sun4.mh
|
| 9895 | |
@end example
|
| 9896 | |
|
| 9897 | |
@noindent
|
| 9898 | |
and then a @file{Makefile.in} could contain:
|
| 9899 | |
|
| 9900 | |
@example
|
| 9901 | |
@@host_frag@@
|
| 9902 | |
@end example
|
| 9903 | |
|
| 9904 | |
The string @var{variable} is passed to @code{m4_pattern_allow}
|
| 9905 | |
(@pxref{Forbidden Patterns}).
|
| 9906 | |
@end defmac
|
| 9907 | |
|
| 9908 | |
@cindex Precious Variable
|
| 9909 | |
@cindex Variable, Precious
|
| 9910 | |
Running @command{configure} in varying environments can be extremely
|
| 9911 | |
dangerous. If for instance the user runs @samp{CC=bizarre-cc
|
| 9912 | |
./configure}, then the cache, @file{config.h}, and many other output
|
| 9913 | |
files depend upon @command{bizarre-cc} being the C compiler. If
|
| 9914 | |
for some reason the user runs @command{./configure} again, or if it is
|
| 9915 | |
run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
|
| 9916 | |
and @pxref{config.status Invocation}), then the configuration can be
|
| 9917 | |
inconsistent, composed of results depending upon two different
|
| 9918 | |
compilers.
|
| 9919 | |
|
| 9920 | |
Environment variables that affect this situation, such as @samp{CC}
|
| 9921 | |
above, are called @dfn{precious variables}, and can be declared as such
|
| 9922 | |
by @code{AC_ARG_VAR}.
|
| 9923 | |
|
| 9924 | |
@defmac AC_ARG_VAR (@var{variable}, @var{description})
|
| 9925 | |
@acindex{ARG_VAR}
|
| 9926 | |
Declare @var{variable} is a precious variable, and include its
|
| 9927 | |
@var{description} in the variable section of @samp{./configure --help}.
|
| 9928 | |
|
| 9929 | |
Being precious means that
|
| 9930 | |
@itemize @minus
|
| 9931 | |
@item
|
| 9932 | |
@var{variable} is substituted via @code{AC_SUBST}.
|
| 9933 | |
|
| 9934 | |
@item
|
| 9935 | |
The value of @var{variable} when @command{configure} was launched is
|
| 9936 | |
saved in the cache, including if it was not specified on the command
|
| 9937 | |
line but via the environment. Indeed, while @command{configure} can
|
| 9938 | |
notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
|
| 9939 | |
it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
|
| 9940 | |
which, unfortunately, is what most users do.
|
| 9941 | |
|
| 9942 | |
We emphasize that it is the @emph{initial} value of @var{variable} which
|
| 9943 | |
is saved, not that found during the execution of @command{configure}.
|
| 9944 | |
Indeed, specifying @samp{./configure FOO=foo} and letting
|
| 9945 | |
@samp{./configure} guess that @code{FOO} is @code{foo} can be two
|
| 9946 | |
different things.
|
| 9947 | |
|
| 9948 | |
@item
|
| 9949 | |
@var{variable} is checked for consistency between two
|
| 9950 | |
@command{configure} runs. For instance:
|
| 9951 | |
|
| 9952 | |
@example
|
| 9953 | |
$ @kbd{./configure --silent --config-cache}
|
| 9954 | |
$ @kbd{CC=cc ./configure --silent --config-cache}
|
| 9955 | |
configure: error: `CC' was not set in the previous run
|
| 9956 | |
configure: error: changes in the environment can compromise \
|
| 9957 | |
the build
|
| 9958 | |
configure: error: run `make distclean' and/or \
|
| 9959 | |
`rm config.cache' and start over
|
| 9960 | |
@end example
|
| 9961 | |
|
| 9962 | |
@noindent
|
| 9963 | |
and similarly if the variable is unset, or if its content is changed.
|
| 9964 | |
If the content has white space changes only, then the error is degraded
|
| 9965 | |
to a warning only, but the old value is reused.
|
| 9966 | |
|
| 9967 | |
@item
|
| 9968 | |
@var{variable} is kept during automatic reconfiguration
|
| 9969 | |
(@pxref{config.status Invocation}) as if it had been passed as a command
|
| 9970 | |
line argument, including when no cache is used:
|
| 9971 | |
|
| 9972 | |
@example
|
| 9973 | |
$ @kbd{CC=/usr/bin/cc ./configure var=raboof --silent}
|
| 9974 | |
$ @kbd{./config.status --recheck}
|
| 9975 | |
running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \
|
| 9976 | |
CC=/usr/bin/cc --no-create --no-recursion
|
| 9977 | |
@end example
|
| 9978 | |
@end itemize
|
| 9979 | |
@end defmac
|
| 9980 | |
|
| 9981 | |
@node Special Chars in Variables
|
| 9982 | |
@section Special Characters in Output Variables
|
| 9983 | |
@cindex Output variables, special characters in
|
| 9984 | |
|
| 9985 | |
Many output variables are intended to be evaluated both by
|
| 9986 | |
@command{make} and by the shell. Some characters are expanded
|
| 9987 | |
differently in these two contexts, so to avoid confusion these
|
| 9988 | |
variables' values should not contain any of the following characters:
|
| 9989 | |
|
| 9990 | |
@example
|
| 9991 | |
" # $ & ' ( ) * ; < > ? [ \ ^ ` |
|
| 9992 | |
@end example
|
| 9993 | |
|
| 9994 | |
Also, these variables' values should neither contain newlines, nor start
|
| 9995 | |
with @samp{~}, nor contain white space or @samp{:} immediately followed
|
| 9996 | |
by @samp{~}. The values can contain nonempty sequences of white space
|
| 9997 | |
characters like tabs and spaces, but each such sequence might
|
| 9998 | |
arbitrarily be replaced by a single space during substitution.
|
| 9999 | |
|
| 10000 | |
These restrictions apply both to the values that @command{configure}
|
| 10001 | |
computes, and to the values set directly by the user. For example, the
|
| 10002 | |
following invocations of @command{configure} are problematic, since they
|
| 10003 | |
attempt to use special characters within @code{CPPFLAGS} and white space
|
| 10004 | |
within @code{$(srcdir)}:
|
| 10005 | |
|
| 10006 | |
@example
|
| 10007 | |
CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
|
| 10008 | |
|
| 10009 | |
'../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
|
| 10010 | |
@end example
|
| 10011 | |
|
| 10012 | |
@node Caching Results
|
| 10013 | |
@section Caching Results
|
| 10014 | |
@cindex Cache
|
| 10015 | |
|
| 10016 | |
To avoid checking for the same features repeatedly in various
|
| 10017 | |
@command{configure} scripts (or in repeated runs of one script),
|
| 10018 | |
@command{configure} can optionally save the results of many checks in a
|
| 10019 | |
@dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
|
| 10020 | |
runs with caching enabled and finds a cache file, it reads the results
|
| 10021 | |
of previous runs from the cache and avoids rerunning those checks. As a
|
| 10022 | |
result, @command{configure} can then run much faster than if it had to
|
| 10023 | |
perform all of the checks every time.
|
| 10024 | |
|
| 10025 | |
@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
|
| 10026 | |
@acindex{CACHE_VAL}
|
| 10027 | |
Ensure that the results of the check identified by @var{cache-id} are
|
| 10028 | |
available. If the results of the check were in the cache file that was
|
| 10029 | |
read, and @command{configure} was not given the @option{--quiet} or
|
| 10030 | |
@option{--silent} option, print a message saying that the result was
|
| 10031 | |
cached; otherwise, run the shell commands @var{commands-to-set-it}. If
|
| 10032 | |
the shell commands are run to determine the value, the value is
|
| 10033 | |
saved in the cache file just before @command{configure} creates its output
|
| 10034 | |
files. @xref{Cache Variable Names}, for how to choose the name of the
|
| 10035 | |
@var{cache-id} variable.
|
| 10036 | |
|
| 10037 | |
The @var{commands-to-set-it} @emph{must have no side effects} except for
|
| 10038 | |
setting the variable @var{cache-id}, see below.
|
| 10039 | |
@end defmac
|
| 10040 | |
|
| 10041 | |
@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @
|
| 10042 | |
@var{commands-to-set-it})
|
| 10043 | |
@acindex{CACHE_CHECK}
|
| 10044 | |
A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
|
| 10045 | |
messages. This macro provides a convenient shorthand for the most
|
| 10046 | |
common way to use these macros. It calls @code{AC_MSG_CHECKING} for
|
| 10047 | |
@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
|
| 10048 | |
@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
|
| 10049 | |
|
| 10050 | |
The @var{commands-to-set-it} @emph{must have no side effects} except for
|
| 10051 | |
setting the variable @var{cache-id}, see below.
|
| 10052 | |
@end defmac
|
| 10053 | |
|
| 10054 | |
It is common to find buggy macros using @code{AC_CACHE_VAL} or
|
| 10055 | |
@code{AC_CACHE_CHECK}, because people are tempted to call
|
| 10056 | |
@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
|
| 10057 | |
@emph{follows} the call to @code{AC_CACHE_VAL} should call
|
| 10058 | |
@code{AC_DEFINE}, by examining the value of the cache variable. For
|
| 10059 | |
instance, the following macro is broken:
|
| 10060 | |
|
| 10061 | |
@example
|
| 10062 | |
@c If you change this example, adjust tests/base.at:AC_CACHE_CHECK.
|
| 10063 | |
@group
|
| 10064 | |
AC_DEFUN([AC_SHELL_TRUE],
|
| 10065 | |
[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
|
| 10066 | |
[my_cv_shell_true_works=no
|
| 10067 | |
(true) 2>/dev/null && my_cv_shell_true_works=yes
|
| 10068 | |
if test "x$my_cv_shell_true_works" = xyes; then
|
| 10069 | |
AC_DEFINE([TRUE_WORKS], [1],
|
| 10070 | |
[Define if `true(1)' works properly.])
|
| 10071 | |
fi])
|
| 10072 | |
])
|
| 10073 | |
@end group
|
| 10074 | |
@end example
|
| 10075 | |
|
| 10076 | |
@noindent
|
| 10077 | |
This fails if the cache is enabled: the second time this macro is run,
|
| 10078 | |
@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
|
| 10079 | |
is:
|
| 10080 | |
|
| 10081 | |
@example
|
| 10082 | |
@c If you change this example, adjust tests/base.at:AC_CACHE_CHECK.
|
| 10083 | |
@group
|
| 10084 | |
AC_DEFUN([AC_SHELL_TRUE],
|
| 10085 | |
[AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
|
| 10086 | |
[my_cv_shell_true_works=no
|
| 10087 | |
(true) 2>/dev/null && my_cv_shell_true_works=yes])
|
| 10088 | |
if test "x$my_cv_shell_true_works" = xyes; then
|
| 10089 | |
AC_DEFINE([TRUE_WORKS], [1],
|
| 10090 | |
[Define if `true(1)' works properly.])
|
| 10091 | |
fi
|
| 10092 | |
])
|
| 10093 | |
@end group
|
| 10094 | |
@end example
|
| 10095 | |
|
| 10096 | |
Also, @var{commands-to-set-it} should not print any messages, for
|
| 10097 | |
example with @code{AC_MSG_CHECKING}; do that before calling
|
| 10098 | |
@code{AC_CACHE_VAL}, so the messages are printed regardless of whether
|
| 10099 | |
the results of the check are retrieved from the cache or determined by
|
| 10100 | |
running the shell commands.
|
| 10101 | |
|
| 10102 | |
@menu
|
| 10103 | |
* Cache Variable Names:: Shell variables used in caches
|
| 10104 | |
* Cache Files:: Files @command{configure} uses for caching
|
| 10105 | |
* Cache Checkpointing:: Loading and saving the cache file
|
| 10106 | |
@end menu
|
| 10107 | |
|
| 10108 | |
@node Cache Variable Names
|
| 10109 | |
@subsection Cache Variable Names
|
| 10110 | |
@cindex Cache variable
|
| 10111 | |
|
| 10112 | |
The names of cache variables should have the following format:
|
| 10113 | |
|
| 10114 | |
@example
|
| 10115 | |
@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
|
| 10116 | |
@end example
|
| 10117 | |
|
| 10118 | |
@noindent
|
| 10119 | |
for example, @samp{ac_cv_header_stat_broken} or
|
| 10120 | |
@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
|
| 10121 | |
|
| 10122 | |
@table @asis
|
| 10123 | |
@item @var{package-prefix}
|
| 10124 | |
An abbreviation for your package or organization; the same prefix you
|
| 10125 | |
begin local Autoconf macros with, except lowercase by convention.
|
| 10126 | |
For cache values used by the distributed Autoconf macros, this value is
|
| 10127 | |
@samp{ac}.
|
| 10128 | |
|
| 10129 | |
@item @code{_cv_}
|
| 10130 | |
Indicates that this shell variable is a cache value. This string
|
| 10131 | |
@emph{must} be present in the variable name, including the leading
|
| 10132 | |
underscore.
|
| 10133 | |
|
| 10134 | |
@item @var{value-type}
|
| 10135 | |
A convention for classifying cache values, to produce a rational naming
|
| 10136 | |
system. The values used in Autoconf are listed in @ref{Macro Names}.
|
| 10137 | |
|
| 10138 | |
@item @var{specific-value}
|
| 10139 | |
Which member of the class of cache values this test applies to.
|
| 10140 | |
For example, which function (@samp{alloca}), program (@samp{gcc}), or
|
| 10141 | |
output variable (@samp{INSTALL}).
|
| 10142 | |
|
| 10143 | |
@item @var{additional-options}
|
| 10144 | |
Any particular behavior of the specific member that this test applies to.
|
| 10145 | |
For example, @samp{broken} or @samp{set}. This part of the name may
|
| 10146 | |
be omitted if it does not apply.
|
| 10147 | |
@end table
|
| 10148 | |
|
| 10149 | |
The values assigned to cache variables may not contain newlines.
|
| 10150 | |
Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
|
| 10151 | |
names of files or functions; so this is not an important restriction.
|
| 10152 | |
@ref{Cache Variable Index} for an index of cache variables with
|
| 10153 | |
documented semantics.
|
| 10154 | |
|
| 10155 | |
|
| 10156 | |
@node Cache Files
|
| 10157 | |
@subsection Cache Files
|
| 10158 | |
|
| 10159 | |
A cache file is a shell script that caches the results of configure
|
| 10160 | |
tests run on one system so they can be shared between configure scripts
|
| 10161 | |
and configure runs. It is not useful on other systems. If its contents
|
| 10162 | |
are invalid for some reason, the user may delete or edit it, or override
|
| 10163 | |
documented cache variables on the @command{configure} command line.
|
| 10164 | |
|
| 10165 | |
By default, @command{configure} uses no cache file,
|
| 10166 | |
to avoid problems caused by accidental
|
| 10167 | |
use of stale cache files.
|
| 10168 | |
|
| 10169 | |
To enable caching, @command{configure} accepts @option{--config-cache} (or
|
| 10170 | |
@option{-C}) to cache results in the file @file{config.cache}.
|
| 10171 | |
Alternatively, @option{--cache-file=@var{file}} specifies that
|
| 10172 | |
@var{file} be the cache file. The cache file is created if it does not
|
| 10173 | |
exist already. When @command{configure} calls @command{configure} scripts in
|
| 10174 | |
subdirectories, it uses the @option{--cache-file} argument so that they
|
| 10175 | |
share the same cache. @xref{Subdirectories}, for information on
|
| 10176 | |
configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
|
| 10177 | |
|
| 10178 | |
@file{config.status} only pays attention to the cache file if it is
|
| 10179 | |
given the @option{--recheck} option, which makes it rerun
|
| 10180 | |
@command{configure}.
|
| 10181 | |
|
| 10182 | |
It is wrong to try to distribute cache files for particular system types.
|
| 10183 | |
There is too much room for error in doing that, and too much
|
| 10184 | |
administrative overhead in maintaining them. For any features that
|
| 10185 | |
can't be guessed automatically, use the standard method of the canonical
|
| 10186 | |
system type and linking files (@pxref{Manual Configuration}).
|
| 10187 | |
|
| 10188 | |
The site initialization script can specify a site-wide cache file to
|
| 10189 | |
use, instead of the usual per-program cache. In this case, the cache
|
| 10190 | |
file gradually accumulates information whenever someone runs a new
|
| 10191 | |
@command{configure} script. (Running @command{configure} merges the new cache
|
| 10192 | |
results with the existing cache file.) This may cause problems,
|
| 10193 | |
however, if the system configuration (e.g., the installed libraries or
|
| 10194 | |
compilers) changes and the stale cache file is not deleted.
|
| 10195 | |
|
| 10196 | |
If @command{configure} is interrupted at the right time when it updates
|
| 10197 | |
a cache file outside of the build directory where the @command{configure}
|
| 10198 | |
script is run, it may leave behind a temporary file named after the
|
| 10199 | |
cache file with digits following it. You may safely delete such a file.
|
| 10200 | |
|
| 10201 | |
|
| 10202 | |
@node Cache Checkpointing
|
| 10203 | |
@subsection Cache Checkpointing
|
| 10204 | |
|
| 10205 | |
If your configure script, or a macro called from @file{configure.ac}, happens
|
| 10206 | |
to abort the configure process, it may be useful to checkpoint the cache
|
| 10207 | |
a few times at key points using @code{AC_CACHE_SAVE}. Doing so
|
| 10208 | |
reduces the amount of time it takes to rerun the configure script with
|
| 10209 | |
(hopefully) the error that caused the previous abort corrected.
|
| 10210 | |
|
| 10211 | |
@c FIXME: Do we really want to document this guy?
|
| 10212 | |
@defmac AC_CACHE_LOAD
|
| 10213 | |
@acindex{CACHE_LOAD}
|
| 10214 | |
Loads values from existing cache file, or creates a new cache file if a
|
| 10215 | |
cache file is not found. Called automatically from @code{AC_INIT}.
|
| 10216 | |
@end defmac
|
| 10217 | |
|
| 10218 | |
@defmac AC_CACHE_SAVE
|
| 10219 | |
@acindex{CACHE_SAVE}
|
| 10220 | |
Flushes all cached values to the cache file. Called automatically from
|
| 10221 | |
@code{AC_OUTPUT}, but it can be quite useful to call
|
| 10222 | |
@code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
|
| 10223 | |
@end defmac
|
| 10224 | |
|
| 10225 | |
For instance:
|
| 10226 | |
|
| 10227 | |
@example
|
| 10228 | |
@r{ @dots{} AC_INIT, etc. @dots{}}
|
| 10229 | |
@group
|
| 10230 | |
# Checks for programs.
|
| 10231 | |
AC_PROG_CC
|
| 10232 | |
AC_PROG_AWK
|
| 10233 | |
@r{ @dots{} more program checks @dots{}}
|
| 10234 | |
AC_CACHE_SAVE
|
| 10235 | |
@end group
|
| 10236 | |
|
| 10237 | |
@group
|
| 10238 | |
# Checks for libraries.
|
| 10239 | |
AC_CHECK_LIB([nsl], [gethostbyname])
|
| 10240 | |
AC_CHECK_LIB([socket], [connect])
|
| 10241 | |
@r{ @dots{} more lib checks @dots{}}
|
| 10242 | |
AC_CACHE_SAVE
|
| 10243 | |
@end group
|
| 10244 | |
|
| 10245 | |
@group
|
| 10246 | |
# Might abort@dots{}
|
| 10247 | |
AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
|
| 10248 | |
AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
|
| 10249 | |
@end group
|
| 10250 | |
@r{ @dots{} AC_OUTPUT, etc. @dots{}}
|
| 10251 | |
@end example
|
| 10252 | |
|
| 10253 | |
@node Printing Messages
|
| 10254 | |
@section Printing Messages
|
| 10255 | |
@cindex Messages, from @command{configure}
|
| 10256 | |
|
| 10257 | |
@command{configure} scripts need to give users running them several kinds
|
| 10258 | |
of information. The following macros print messages in ways appropriate
|
| 10259 | |
for each kind. The arguments to all of them get enclosed in shell
|
| 10260 | |
double quotes, so the shell performs variable and back-quote
|
| 10261 | |
substitution on them.
|
| 10262 | |
|
| 10263 | |
These macros are all wrappers around the @command{echo} shell command.
|
| 10264 | |
They direct output to the appropriate file descriptor (@pxref{File
|
| 10265 | |
Descriptor Macros}).
|
| 10266 | |
@command{configure} scripts should rarely need to run @command{echo} directly
|
| 10267 | |
to print messages for the user. Using these macros makes it easy to
|
| 10268 | |
change how and when each kind of message is printed; such changes need
|
| 10269 | |
only be made to the macro definitions and all the callers change
|
| 10270 | |
automatically.
|
| 10271 | |
|
| 10272 | |
To diagnose static issues, i.e., when @command{autoconf} is run, see
|
| 10273 | |
@ref{Diagnostic Macros}.
|
| 10274 | |
|
| 10275 | |
@defmac AC_MSG_CHECKING (@var{feature-description})
|
| 10276 | |
@acindex{MSG_CHECKING}
|
| 10277 | |
Notify the user that @command{configure} is checking for a particular
|
| 10278 | |
feature. This macro prints a message that starts with @samp{checking }
|
| 10279 | |
and ends with @samp{...} and no newline. It must be followed by a call
|
| 10280 | |
to @code{AC_MSG_RESULT} to print the result of the check and the
|
| 10281 | |
newline. The @var{feature-description} should be something like
|
| 10282 | |
@samp{whether the Fortran compiler accepts C++ comments} or @samp{for
|
| 10283 | |
c89}.
|
| 10284 | |
|
| 10285 | |
This macro prints nothing if @command{configure} is run with the
|
| 10286 | |
@option{--quiet} or @option{--silent} option.
|
| 10287 | |
@end defmac
|
| 10288 | |
|
| 10289 | |
@anchor{AC_MSG_RESULT}
|
| 10290 | |
@defmac AC_MSG_RESULT (@var{result-description})
|
| 10291 | |
@acindex{MSG_RESULT}
|
| 10292 | |
Notify the user of the results of a check. @var{result-description} is
|
| 10293 | |
almost always the value of the cache variable for the check, typically
|
| 10294 | |
@samp{yes}, @samp{no}, or a file name. This macro should follow a call
|
| 10295 | |
to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
|
| 10296 | |
the completion of the message printed by the call to
|
| 10297 | |
@code{AC_MSG_CHECKING}.
|
| 10298 | |
|
| 10299 | |
This macro prints nothing if @command{configure} is run with the
|
| 10300 | |
@option{--quiet} or @option{--silent} option.
|
| 10301 | |
@end defmac
|
| 10302 | |
|
| 10303 | |
@anchor{AC_MSG_NOTICE}
|
| 10304 | |
@defmac AC_MSG_NOTICE (@var{message})
|
| 10305 | |
@acindex{MSG_NOTICE}
|
| 10306 | |
Deliver the @var{message} to the user. It is useful mainly to print a
|
| 10307 | |
general description of the overall purpose of a group of feature checks,
|
| 10308 | |
e.g.,
|
| 10309 | |
|
| 10310 | |
@example
|
| 10311 | |
AC_MSG_NOTICE([checking if stack overflow is detectable])
|
| 10312 | |
@end example
|
| 10313 | |
|
| 10314 | |
This macro prints nothing if @command{configure} is run with the
|
| 10315 | |
@option{--quiet} or @option{--silent} option.
|
| 10316 | |
@end defmac
|
| 10317 | |
|
| 10318 | |
@anchor{AC_MSG_ERROR}
|
| 10319 | |
@defmac AC_MSG_ERROR (@var{error-description}, @dvar{exit-status, $?/1})
|
| 10320 | |
@acindex{MSG_ERROR}
|
| 10321 | |
Notify the user of an error that prevents @command{configure} from
|
| 10322 | |
completing. This macro prints an error message to the standard error
|
| 10323 | |
output and exits @command{configure} with @var{exit-status} (@samp{$?}
|
| 10324 | |
by default, except that @samp{0} is converted to @samp{1}).
|
| 10325 | |
@var{error-description} should be something like @samp{invalid value
|
| 10326 | |
$HOME for \$HOME}.
|
| 10327 | |
|
| 10328 | |
The @var{error-description} should start with a lower-case letter, and
|
| 10329 | |
``cannot'' is preferred to ``can't''.
|
| 10330 | |
@end defmac
|
| 10331 | |
|
| 10332 | |
@defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
|
| 10333 | |
@acindex{MSG_FAILURE}
|
| 10334 | |
This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
|
| 10335 | |
prevents @command{configure} from completing @emph{and} that additional
|
| 10336 | |
details are provided in @file{config.log}. This is typically used when
|
| 10337 | |
abnormal results are found during a compilation.
|
| 10338 | |
@end defmac
|
| 10339 | |
|
| 10340 | |
@anchor{AC_MSG_WARN}
|
| 10341 | |
@defmac AC_MSG_WARN (@var{problem-description})
|
| 10342 | |
@acindex{MSG_WARN}
|
| 10343 | |
Notify the @command{configure} user of a possible problem. This macro
|
| 10344 | |
prints the message to the standard error output; @command{configure}
|
| 10345 | |
continues running afterward, so macros that call @code{AC_MSG_WARN} should
|
| 10346 | |
provide a default (back-up) behavior for the situations they warn about.
|
| 10347 | |
@var{problem-description} should be something like @samp{ln -s seems to
|
| 10348 | |
make hard links}.
|
| 10349 | |
@end defmac
|
| 10350 | |
|
| 10351 | |
|
| 10352 | |
|
| 10353 | |
@c ====================================================== Programming in M4.
|
| 10354 | |
|
| 10355 | |
@node Programming in M4
|
| 10356 | |
@chapter Programming in M4
|
| 10357 | |
@cindex M4
|
| 10358 | |
|
| 10359 | |
Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
|
| 10360 | |
convenient macros for pure M4 programming, and @dfn{M4sh}, which
|
| 10361 | |
provides macros dedicated to shell script generation.
|
| 10362 | |
|
| 10363 | |
As of this version of Autoconf, these two layers still contain
|
| 10364 | |
experimental macros, whose interface might change in the future. As a
|
| 10365 | |
matter of fact, @emph{anything that is not documented must not be used}.
|
| 10366 | |
|
| 10367 | |
@menu
|
| 10368 | |
* M4 Quotation:: Protecting macros from unwanted expansion
|
| 10369 | |
* Using autom4te:: The Autoconf executables backbone
|
| 10370 | |
* Programming in M4sugar:: Convenient pure M4 macros
|
| 10371 | |
* Debugging via autom4te:: Figuring out what M4 was doing
|
| 10372 | |
@end menu
|
| 10373 | |
|
| 10374 | |
@node M4 Quotation
|
| 10375 | |
@section M4 Quotation
|
| 10376 | |
@cindex M4 quotation
|
| 10377 | |
@cindex quotation
|
| 10378 | |
|
| 10379 | |
The most common problem with existing macros is an improper quotation.
|
| 10380 | |
This section, which users of Autoconf can skip, but which macro writers
|
| 10381 | |
@emph{must} read, first justifies the quotation scheme that was chosen
|
| 10382 | |
for Autoconf and then ends with a rule of thumb. Understanding the
|
| 10383 | |
former helps one to follow the latter.
|
| 10384 | |
|
| 10385 | |
@menu
|
| 10386 | |
* Active Characters:: Characters that change the behavior of M4
|
| 10387 | |
* One Macro Call:: Quotation and one macro call
|
| 10388 | |
* Quoting and Parameters:: M4 vs. shell parameters
|
| 10389 | |
* Quotation and Nested Macros:: Macros calling macros
|
| 10390 | |
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
|
| 10391 | |
* Quadrigraphs:: Another way to escape special characters
|
| 10392 | |
* Balancing Parentheses:: Dealing with unbalanced parentheses
|
| 10393 | |
* Quotation Rule Of Thumb:: One parenthesis, one quote
|
| 10394 | |
@end menu
|
| 10395 | |
|
| 10396 | |
@node Active Characters
|
| 10397 | |
@subsection Active Characters
|
| 10398 | |
|
| 10399 | |
To fully understand where proper quotation is important, you first need
|
| 10400 | |
to know what the special characters are in Autoconf: @samp{#} introduces
|
| 10401 | |
a comment inside which no macro expansion is performed, @samp{,}
|
| 10402 | |
separates arguments, @samp{[} and @samp{]} are the quotes
|
| 10403 | |
themselves@footnote{By itself, M4 uses @samp{`} and @samp{'}; it is the
|
| 10404 | |
M4sugar layer that sets up the preferred quotes of @samp{[} and @samp{]}.},
|
| 10405 | |
@samp{(} and @samp{)} (which M4 tries to match by pairs), and finally
|
| 10406 | |
@samp{$} inside a macro definition.
|
| 10407 | |
|
| 10408 | |
In order to understand the delicate case of macro calls, we first have
|
| 10409 | |
to present some obvious failures. Below they are ``obvious-ified'',
|
| 10410 | |
but when you find them in real life, they are usually in disguise.
|
| 10411 | |
|
| 10412 | |
Comments, introduced by a hash and running up to the newline, are opaque
|
| 10413 | |
tokens to the top level: active characters are turned off, and there is
|
| 10414 | |
no macro expansion:
|
| 10415 | |
|
| 10416 | |
@example
|
| 10417 | |
# define([def], ine)
|
| 10418 | |
@result{}# define([def], ine)
|
| 10419 | |
@end example
|
| 10420 | |
|
| 10421 | |
Each time there can be a macro expansion, there is a quotation
|
| 10422 | |
expansion, i.e., one level of quotes is stripped:
|
| 10423 | |
|
| 10424 | |
@example
|
| 10425 | |
int tab[10];
|
| 10426 | |
@result{}int tab10;
|
| 10427 | |
[int tab[10];]
|
| 10428 | |
@result{}int tab[10];
|
| 10429 | |
@end example
|
| 10430 | |
|
| 10431 | |
Without this in mind, the reader might try hopelessly to use her macro
|
| 10432 | |
@code{array}:
|
| 10433 | |
|
| 10434 | |
@example
|
| 10435 | |
define([array], [int tab[10];])
|
| 10436 | |
array
|
| 10437 | |
@result{}int tab10;
|
| 10438 | |
[array]
|
| 10439 | |
@result{}array
|
| 10440 | |
@end example
|
| 10441 | |
|
| 10442 | |
@noindent
|
| 10443 | |
How can you correctly output the intended results@footnote{Using
|
| 10444 | |
@code{defn}.}?
|
| 10445 | |
|
| 10446 | |
|
| 10447 | |
@node One Macro Call
|
| 10448 | |
@subsection One Macro Call
|
| 10449 | |
|
| 10450 | |
Let's proceed on the interaction between active characters and macros
|
| 10451 | |
with this small macro, which just returns its first argument:
|
| 10452 | |
|
| 10453 | |
@example
|
| 10454 | |
define([car], [$1])
|
| 10455 | |
@end example
|
| 10456 | |
|
| 10457 | |
@noindent
|
| 10458 | |
The two pairs of quotes above are not part of the arguments of
|
| 10459 | |
@code{define}; rather, they are understood by the top level when it
|
| 10460 | |
tries to find the arguments of @code{define}. Therefore, assuming
|
| 10461 | |
@code{car} is not already defined, it is equivalent to write:
|
| 10462 | |
|
| 10463 | |
@example
|
| 10464 | |
define(car, $1)
|
| 10465 | |
@end example
|
| 10466 | |
|
| 10467 | |
@noindent
|
| 10468 | |
But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
|
| 10469 | |
quotes, it is bad practice for Autoconf macros which must both be more
|
| 10470 | |
robust and also advocate perfect style.
|
| 10471 | |
|
| 10472 | |
At the top level, there are only two possibilities: either you
|
| 10473 | |
quote or you don't:
|
| 10474 | |
|
| 10475 | |
@example
|
| 10476 | |
car(foo, bar, baz)
|
| 10477 | |
@result{}foo
|
| 10478 | |
[car(foo, bar, baz)]
|
| 10479 | |
@result{}car(foo, bar, baz)
|
| 10480 | |
@end example
|
| 10481 | |
|
| 10482 | |
Let's pay attention to the special characters:
|
| 10483 | |
|
| 10484 | |
@example
|
| 10485 | |
car(#)
|
| 10486 | |
@error{}EOF in argument list
|
| 10487 | |
@end example
|
| 10488 | |
|
| 10489 | |
The closing parenthesis is hidden in the comment; with a hypothetical
|
| 10490 | |
quoting, the top level understood it this way:
|
| 10491 | |
|
| 10492 | |
@example
|
| 10493 | |
car([#)]
|
| 10494 | |
@end example
|
| 10495 | |
|
| 10496 | |
@noindent
|
| 10497 | |
Proper quotation, of course, fixes the problem:
|
| 10498 | |
|
| 10499 | |
@example
|
| 10500 | |
car([#])
|
| 10501 | |
@result{}#
|
| 10502 | |
@end example
|
| 10503 | |
|
| 10504 | |
Here are more examples:
|
| 10505 | |
|
| 10506 | |
@example
|
| 10507 | |
car(foo, bar)
|
| 10508 | |
@result{}foo
|
| 10509 | |
car([foo, bar])
|
| 10510 | |
@result{}foo, bar
|
| 10511 | |
car((foo, bar))
|
| 10512 | |
@result{}(foo, bar)
|
| 10513 | |
car([(foo], [bar)])
|
| 10514 | |
@result{}(foo
|
| 10515 | |
define([a], [b])
|
| 10516 | |
@result{}
|
| 10517 | |
car(a)
|
| 10518 | |
@result{}b
|
| 10519 | |
car([a])
|
| 10520 | |
@result{}b
|
| 10521 | |
car([[a]])
|
| 10522 | |
@result{}a
|
| 10523 | |
car([[[a]]])
|
| 10524 | |
@result{}[a]
|
| 10525 | |
@end example
|
| 10526 | |
|
| 10527 | |
@node Quoting and Parameters
|
| 10528 | |
@subsection Quoting and Parameters
|
| 10529 | |
|
| 10530 | |
When M4 encounters @samp{$} within a macro definition, followed
|
| 10531 | |
immediately by a character it recognizes (@samp{0}@dots{}@samp{9},
|
| 10532 | |
@samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter
|
| 10533 | |
expansion. This happens regardless of how many layers of quotes the
|
| 10534 | |
parameter expansion is nested within, or even if it occurs in text that
|
| 10535 | |
will be rescanned as a comment.
|
| 10536 | |
|
| 10537 | |
@example
|
| 10538 | |
define([none], [$1])
|
| 10539 | |
@result{}
|
| 10540 | |
define([one], [[$1]])
|
| 10541 | |
@result{}
|
| 10542 | |
define([two], [[[$1]]])
|
| 10543 | |
@result{}
|
| 10544 | |
define([comment], [# $1])
|
| 10545 | |
@result{}
|
| 10546 | |
define([active], [ACTIVE])
|
| 10547 | |
@result{}
|
| 10548 | |
none([active])
|
| 10549 | |
@result{}ACTIVE
|
| 10550 | |
one([active])
|
| 10551 | |
@result{}active
|
| 10552 | |
two([active])
|
| 10553 | |
@result{}[active]
|
| 10554 | |
comment([active])
|
| 10555 | |
@result{}# active
|
| 10556 | |
@end example
|
| 10557 | |
|
| 10558 | |
On the other hand, since autoconf generates shell code, you often want
|
| 10559 | |
to output shell variable expansion, rather than performing M4 parameter
|
| 10560 | |
expansion. To do this, you must use M4 quoting to separate the @samp{$}
|
| 10561 | |
from the next character in the definition of your macro. If the macro
|
| 10562 | |
definition occurs in single-quoted text, then insert another level of
|
| 10563 | |
quoting; if the usage is already inside a double-quoted string, then
|
| 10564 | |
split it into concatenated strings.
|
| 10565 | |
|
| 10566 | |
@example
|
| 10567 | |
define([single], [a single-quoted $[]1 definition])
|
| 10568 | |
@result{}
|
| 10569 | |
define([double], [[a double-quoted $][1 definition]])
|
| 10570 | |
@result{}
|
| 10571 | |
single
|
| 10572 | |
@result{}a single-quoted $1 definition
|
| 10573 | |
double
|
| 10574 | |
@result{}a double-quoted $1 definition
|
| 10575 | |
@end example
|
| 10576 | |
|
| 10577 | |
Posix states that M4 implementations are free to provide implementation
|
| 10578 | |
extensions when @samp{$@{} is encountered in a macro definition.
|
| 10579 | |
Autoconf reserves the longer sequence @samp{$@{@{} for use with planned
|
| 10580 | |
extensions that will be available in the future GNU M4 2.0,
|
| 10581 | |
but guarantees that all other instances of @samp{$@{} will be output
|
| 10582 | |
literally. Therefore, this idiom can also be used to output shell code
|
| 10583 | |
parameter references:
|
| 10584 | |
|
| 10585 | |
@example
|
| 10586 | |
define([first], [$@{1@}])first
|
| 10587 | |
@result{}$@{1@}
|
| 10588 | |
@end example
|
| 10589 | |
|
| 10590 | |
Posix also states that @samp{$11} should expand to the first parameter
|
| 10591 | |
concatenated with a literal @samp{1}, although some versions of
|
| 10592 | |
GNU M4 expand the eleventh parameter instead. For
|
| 10593 | |
portability, you should only use single-digit M4 parameter expansion.
|
| 10594 | |
|
| 10595 | |
With this in mind, we can explore the cases where macros invoke
|
| 10596 | |
macros@enddots{}
|
| 10597 | |
|
| 10598 | |
@node Quotation and Nested Macros
|
| 10599 | |
@subsection Quotation and Nested Macros
|
| 10600 | |
|
| 10601 | |
The examples below use the following macros:
|
| 10602 | |
|
| 10603 | |
@example
|
| 10604 | |
define([car], [$1])
|
| 10605 | |
define([active], [ACT, IVE])
|
| 10606 | |
define([array], [int tab[10]])
|
| 10607 | |
@end example
|
| 10608 | |
|
| 10609 | |
Each additional embedded macro call introduces other possible
|
| 10610 | |
interesting quotations:
|
| 10611 | |
|
| 10612 | |
@example
|
| 10613 | |
car(active)
|
| 10614 | |
@result{}ACT
|
| 10615 | |
car([active])
|
| 10616 | |
@result{}ACT, IVE
|
| 10617 | |
car([[active]])
|
| 10618 | |
@result{}active
|
| 10619 | |
@end example
|
| 10620 | |
|
| 10621 | |
In the first case, the top level looks for the arguments of @code{car},
|
| 10622 | |
and finds @samp{active}. Because M4 evaluates its arguments
|
| 10623 | |
before applying the macro, @samp{active} is expanded, which results in:
|
| 10624 | |
|
| 10625 | |
@example
|
| 10626 | |
car(ACT, IVE)
|
| 10627 | |
@result{}ACT
|
| 10628 | |
@end example
|
| 10629 | |
|
| 10630 | |
@noindent
|
| 10631 | |
In the second case, the top level gives @samp{active} as first and only
|
| 10632 | |
argument of @code{car}, which results in:
|
| 10633 | |
|
| 10634 | |
@example
|
| 10635 | |
active
|
| 10636 | |
@result{}ACT, IVE
|
| 10637 | |
@end example
|
| 10638 | |
|
| 10639 | |
@noindent
|
| 10640 | |
i.e., the argument is evaluated @emph{after} the macro that invokes it.
|
| 10641 | |
In the third case, @code{car} receives @samp{[active]}, which results in:
|
| 10642 | |
|
| 10643 | |
@example
|
| 10644 | |
[active]
|
| 10645 | |
@result{}active
|
| 10646 | |
@end example
|
| 10647 | |
|
| 10648 | |
@noindent
|
| 10649 | |
exactly as we already saw above.
|
| 10650 | |
|
| 10651 | |
The example above, applied to a more realistic example, gives:
|
| 10652 | |
|
| 10653 | |
@example
|
| 10654 | |
car(int tab[10];)
|
| 10655 | |
@result{}int tab10;
|
| 10656 | |
car([int tab[10];])
|
| 10657 | |
@result{}int tab10;
|
| 10658 | |
car([[int tab[10];]])
|
| 10659 | |
@result{}int tab[10];
|
| 10660 | |
@end example
|
| 10661 | |
|
| 10662 | |
@noindent
|
| 10663 | |
Huh? The first case is easily understood, but why is the second wrong,
|
| 10664 | |
and the third right? To understand that, you must know that after
|
| 10665 | |
M4 expands a macro, the resulting text is immediately subjected
|
| 10666 | |
to macro expansion and quote removal. This means that the quote removal
|
| 10667 | |
occurs twice---first before the argument is passed to the @code{car}
|
| 10668 | |
macro, and second after the @code{car} macro expands to the first
|
| 10669 | |
argument.
|
| 10670 | |
|
| 10671 | |
As the author of the Autoconf macro @code{car}, you then consider it to
|
| 10672 | |
be incorrect that your users have to double-quote the arguments of
|
| 10673 | |
@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
|
| 10674 | |
quoted car:
|
| 10675 | |
|
| 10676 | |
@example
|
| 10677 | |
define([qar], [[$1]])
|
| 10678 | |
@end example
|
| 10679 | |
|
| 10680 | |
@noindent
|
| 10681 | |
and check that @code{qar} is properly fixed:
|
| 10682 | |
|
| 10683 | |
@example
|
| 10684 | |
qar([int tab[10];])
|
| 10685 | |
@result{}int tab[10];
|
| 10686 | |
@end example
|
| 10687 | |
|
| 10688 | |
@noindent
|
| 10689 | |
Ahhh! That's much better.
|
| 10690 | |
|
| 10691 | |
But note what you've done: now that the result of @code{qar} is always
|
| 10692 | |
a literal string, the only time a user can use nested macros is if she
|
| 10693 | |
relies on an @emph{unquoted} macro call:
|
| 10694 | |
|
| 10695 | |
@example
|
| 10696 | |
qar(active)
|
| 10697 | |
@result{}ACT
|
| 10698 | |
qar([active])
|
| 10699 | |
@result{}active
|
| 10700 | |
@end example
|
| 10701 | |
|
| 10702 | |
@noindent
|
| 10703 | |
leaving no way for her to reproduce what she used to do with @code{car}:
|
| 10704 | |
|
| 10705 | |
@example
|
| 10706 | |
car([active])
|
| 10707 | |
@result{}ACT, IVE
|
| 10708 | |
@end example
|
| 10709 | |
|
| 10710 | |
@noindent
|
| 10711 | |
Worse yet: she wants to use a macro that produces a set of @code{cpp}
|
| 10712 | |
macros:
|
| 10713 | |
|
| 10714 | |
@example
|
| 10715 | |
define([my_includes], [#include <stdio.h>])
|
| 10716 | |
car([my_includes])
|
| 10717 | |
@result{}#include <stdio.h>
|
| 10718 | |
qar(my_includes)
|
| 10719 | |
@error{}EOF in argument list
|
| 10720 | |
@end example
|
| 10721 | |
|
| 10722 | |
This macro, @code{qar}, because it double quotes its arguments, forces
|
| 10723 | |
its users to leave their macro calls unquoted, which is dangerous.
|
| 10724 | |
Commas and other active symbols are interpreted by M4 before
|
| 10725 | |
they are given to the macro, often not in the way the users expect.
|
| 10726 | |
Also, because @code{qar} behaves differently from the other macros,
|
| 10727 | |
it's an exception that should be avoided in Autoconf.
|
| 10728 | |
|
| 10729 | |
@node Changequote is Evil
|
| 10730 | |
@subsection @code{changequote} is Evil
|
| 10731 | |
@cindex @code{changequote}
|
| 10732 | |
|
| 10733 | |
The temptation is often high to bypass proper quotation, in particular
|
| 10734 | |
when it's late at night. Then, many experienced Autoconf hackers
|
| 10735 | |
finally surrender to the dark side of the force and use the ultimate
|
| 10736 | |
weapon: @code{changequote}.
|
| 10737 | |
|
| 10738 | |
The M4 builtin @code{changequote} belongs to a set of primitives that
|
| 10739 | |
allow one to adjust the syntax of the language to adjust it to one's
|
| 10740 | |
needs. For instance, by default M4 uses @samp{`} and @samp{'} as
|
| 10741 | |
quotes, but in the context of shell programming (and actually of most
|
| 10742 | |
programming languages), that's about the worst choice one can make:
|
| 10743 | |
because of strings and back-quoted expressions in shell code (such as
|
| 10744 | |
@samp{'this'} and @samp{`that`}), and because of literal characters in usual
|
| 10745 | |
programming languages (as in @samp{'0'}), there are many unbalanced
|
| 10746 | |
@samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
|
| 10747 | |
not impossible. In order to make M4 useful in such a context, its
|
| 10748 | |
designers have equipped it with @code{changequote}, which makes it
|
| 10749 | |
possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
|
| 10750 | |
Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
|
| 10751 | |
because they are unlikely characters, but @emph{because they are
|
| 10752 | |
characters unlikely to be unbalanced}.
|
| 10753 | |
|
| 10754 | |
There are other magic primitives, such as @code{changecom} to specify
|
| 10755 | |
what syntactic forms are comments (it is common to see
|
| 10756 | |
@samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
|
| 10757 | |
@code{changeword} and @code{changesyntax} to change other syntactic
|
| 10758 | |
details (such as the character to denote the @var{n}th argument, @samp{$} by
|
| 10759 | |
default, the parentheses around arguments, etc.).
|
| 10760 | |
|
| 10761 | |
These primitives are really meant to make M4 more useful for specific
|
| 10762 | |
domains: they should be considered like command line options:
|
| 10763 | |
@option{--quotes}, @option{--comments}, @option{--words}, and
|
| 10764 | |
@option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
|
| 10765 | |
it makes M4 libraries self contained (no need for additional options).
|
| 10766 | |
|
| 10767 | |
There lies the problem@enddots{}
|
| 10768 | |
|
| 10769 | |
@sp 1
|
| 10770 | |
|
| 10771 | |
The problem is that it is then tempting to use them in the middle of an
|
| 10772 | |
M4 script, as opposed to its initialization. This, if not carefully
|
| 10773 | |
thought out, can lead to disastrous effects: @emph{you are changing the
|
| 10774 | |
language in the middle of the execution}. Changing and restoring the
|
| 10775 | |
syntax is often not enough: if you happened to invoke macros in between,
|
| 10776 | |
these macros are lost, as the current syntax is probably not
|
| 10777 | |
the one they were implemented with.
|
| 10778 | |
|
| 10779 | |
@c FIXME: I've been looking for a short, real case example, but I
|
| 10780 | |
@c lost them all :(
|
| 10781 | |
|
| 10782 | |
|
| 10783 | |
@node Quadrigraphs
|
| 10784 | |
@subsection Quadrigraphs
|
| 10785 | |
@cindex quadrigraphs
|
| 10786 | |
@cindex @samp{@@S|@@}
|
| 10787 | |
@cindex @samp{@@&t@@}
|
| 10788 | |
@c Info cannot handle `:' in index entries.
|
| 10789 | |
@ifnotinfo
|
| 10790 | |
@cindex @samp{@@<:@@}
|
| 10791 | |
@cindex @samp{@@:>@@}
|
| 10792 | |
@cindex @samp{@@%:@@}
|
| 10793 | |
@cindex @samp{@@@{:@@}
|
| 10794 | |
@cindex @samp{@@:@}@@}
|
| 10795 | |
@end ifnotinfo
|
| 10796 | |
|
| 10797 | |
When writing an Autoconf macro you may occasionally need to generate
|
| 10798 | |
special characters that are difficult to express with the standard
|
| 10799 | |
Autoconf quoting rules. For example, you may need to output the regular
|
| 10800 | |
expression @samp{[^[]}, which matches any character other than @samp{[}.
|
| 10801 | |
This expression contains unbalanced brackets so it cannot be put easily
|
| 10802 | |
into an M4 macro.
|
| 10803 | |
|
| 10804 | |
Additionally, there are a few m4sugar macros (such as @code{m4_split}
|
| 10805 | |
and @code{m4_expand}) which internally use special markers in addition
|
| 10806 | |
to the regular quoting characters. If the arguments to these macros
|
| 10807 | |
contain the literal strings @samp{-=<@{(} or @samp{)@}>=-}, the macros
|
| 10808 | |
might behave incorrectly.
|
| 10809 | |
|
| 10810 | |
You can work around these problems by using one of the following
|
| 10811 | |
@dfn{quadrigraphs}:
|
| 10812 | |
|
| 10813 | |
@table @samp
|
| 10814 | |
@item @@<:@@
|
| 10815 | |
@samp{[}
|
| 10816 | |
@item @@:>@@
|
| 10817 | |
@samp{]}
|
| 10818 | |
@item @@S|@@
|
| 10819 | |
@samp{$}
|
| 10820 | |
@item @@%:@@
|
| 10821 | |
@samp{#}
|
| 10822 | |
@item @@@{:@@
|
| 10823 | |
@samp{(}
|
| 10824 | |
@item @@:@}@@
|
| 10825 | |
@samp{)}
|
| 10826 | |
@item @@&t@@
|
| 10827 | |
Expands to nothing.
|
| 10828 | |
@end table
|
| 10829 | |
|
| 10830 | |
Quadrigraphs are replaced at a late stage of the translation process,
|
| 10831 | |
after @command{m4} is run, so they do not get in the way of M4 quoting.
|
| 10832 | |
For example, the string @samp{^@@<:@@}, independently of its quotation,
|
| 10833 | |
appears as @samp{^[} in the output.
|
| 10834 | |
|
| 10835 | |
The empty quadrigraph can be used:
|
| 10836 | |
|
| 10837 | |
@itemize @minus
|
| 10838 | |
@item to mark trailing spaces explicitly
|
| 10839 | |
|
| 10840 | |
Trailing spaces are smashed by @command{autom4te}. This is a feature.
|
| 10841 | |
|
| 10842 | |
@item to produce quadrigraphs and other strings reserved by m4sugar
|
| 10843 | |
|
| 10844 | |
For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}. For a more
|
| 10845 | |
contrived example:
|
| 10846 | |
|
| 10847 | |
@example
|
| 10848 | |
m4_define([a], [A])m4_define([b], [B])m4_define([c], [C])dnl
|
| 10849 | |
m4_split([a )@}>=- b -=<@{( c])
|
| 10850 | |
@result{}[a], [], [B], [], [c]
|
| 10851 | |
m4_split([a )@}@@&t@@>=- b -=<@@&t@@@{( c])
|
| 10852 | |
@result{}[a], [)@}>=-], [b], [-=<@{(], [c]
|
| 10853 | |
@end example
|
| 10854 | |
|
| 10855 | |
@item to escape @emph{occurrences} of forbidden patterns
|
| 10856 | |
|
| 10857 | |
For instance you might want to mention @code{AC_FOO} in a comment, while
|
| 10858 | |
still being sure that @command{autom4te} still catches unexpanded
|
| 10859 | |
@samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
|
| 10860 | |
@end itemize
|
| 10861 | |
|
| 10862 | |
The name @samp{@@&t@@} was suggested by Paul Eggert:
|
| 10863 | |
|
| 10864 | |
@quotation
|
| 10865 | |
I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
|
| 10866 | |
own invention, but the @samp{t} came from the source code of the
|
| 10867 | |
ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame),
|
| 10868 | |
and which used @samp{mt} to denote the empty string. In C, it would
|
| 10869 | |
have looked like something like:
|
| 10870 | |
|
| 10871 | |
@example
|
| 10872 | |
char const mt[] = "";
|
| 10873 | |
@end example
|
| 10874 | |
|
| 10875 | |
@noindent
|
| 10876 | |
but of course the source code was written in Algol 68.
|
| 10877 | |
|
| 10878 | |
I don't know where he got @samp{mt} from: it could have been his own
|
| 10879 | |
invention, and I suppose it could have been a common pun around the
|
| 10880 | |
Cambridge University computer lab at the time.
|
| 10881 | |
@end quotation
|
| 10882 | |
|
| 10883 | |
|
| 10884 | |
@node Balancing Parentheses
|
| 10885 | |
@subsection Dealing with unbalanced parentheses
|
| 10886 | |
@cindex balancing parentheses
|
| 10887 | |
@cindex parentheses, balancing
|
| 10888 | |
@cindex unbalanced parentheses, managing
|
| 10889 | |
|
| 10890 | |
One of the pitfalls of portable shell programming is that @command{case}
|
| 10891 | |
statements require unbalanced parentheses (@pxref{case, , Limitations of
|
| 10892 | |
Shell Builtins}). With syntax highlighting
|
| 10893 | |
editors, the presence of unbalanced @samp{)} can interfere with editors
|
| 10894 | |
that perform syntax highlighting of macro contents based on finding the
|
| 10895 | |
matching @samp{(}. Another concern is how much editing must be done
|
| 10896 | |
when transferring code snippets between shell scripts and macro
|
| 10897 | |
definitions. But most importantly, the presence of unbalanced
|
| 10898 | |
parentheses can introduce expansion bugs.
|
| 10899 | |
|
| 10900 | |
For an example, here is an underquoted attempt to use the macro
|
| 10901 | |
@code{my_case}, which happens to expand to a portable @command{case}
|
| 10902 | |
statement:
|
| 10903 | |
|
| 10904 | |
@example
|
| 10905 | |
AC_DEFUN([my_case],
|
| 10906 | |
[case $file_name in
|
| 10907 | |
*.c) echo "C source code";;
|
| 10908 | |
esac])
|
| 10909 | |
AS_IF(:, my_case)
|
| 10910 | |
@end example
|
| 10911 | |
|
| 10912 | |
@noindent
|
| 10913 | |
In the above example, the @code{AS_IF} call underquotes its arguments.
|
| 10914 | |
As a result, the unbalanced @samp{)} generated by the premature
|
| 10915 | |
expansion of @code{my_case} results in expanding @code{AS_IF} with a
|
| 10916 | |
truncated parameter, and the expansion is syntactically invalid:
|
| 10917 | |
|
| 10918 | |
@example
|
| 10919 | |
if :; then
|
| 10920 | |
case $file_name in
|
| 10921 | |
*.c
|
| 10922 | |
fi echo "C source code";;
|
| 10923 | |
esac)
|
| 10924 | |
@end example
|
| 10925 | |
|
| 10926 | |
If nothing else, this should emphasize the importance of the quoting
|
| 10927 | |
arguments to macro calls. On the other hand, there are several
|
| 10928 | |
variations for defining @code{my_case} to be more robust, even when used
|
| 10929 | |
without proper quoting, each with some benefits and some drawbacks.
|
| 10930 | |
|
| 10931 | |
@itemize @w{}
|
| 10932 | |
@item Creative literal shell comment
|
| 10933 | |
@example
|
| 10934 | |
AC_DEFUN([my_case],
|
| 10935 | |
[case $file_name in #(
|
| 10936 | |
*.c) echo "C source code";;
|
| 10937 | |
esac])
|
| 10938 | |
@end example
|
| 10939 | |
@noindent
|
| 10940 | |
This version provides balanced parentheses to several editors, and can
|
| 10941 | |
be copied and pasted into a terminal as is. Unfortunately, it is still
|
| 10942 | |
unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
|
| 10943 | |
that masks the normal properties of @samp{(}.
|
| 10944 | |
|
| 10945 | |
@item Quadrigraph shell comment
|
| 10946 | |
@example
|
| 10947 | |
AC_DEFUN([my_case],
|
| 10948 | |
[case $file_name in @@%:@@(
|
| 10949 | |
*.c) echo "C source code";;
|
| 10950 | |
esac])
|
| 10951 | |
@end example
|
| 10952 | |
@noindent
|
| 10953 | |
This version provides balanced parentheses to even more editors, and can
|
| 10954 | |
be used as a balanced Autoconf argument. Unfortunately, it requires
|
| 10955 | |
some editing before it can be copied and pasted into a terminal, and the
|
| 10956 | |
use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
|
| 10957 | |
|
| 10958 | |
@item Quoting just the parenthesis
|
| 10959 | |
@example
|
| 10960 | |
AC_DEFUN([my_case],
|
| 10961 | |
[case $file_name in
|
| 10962 | |
*.c[)] echo "C source code";;
|
| 10963 | |
esac])
|
| 10964 | |
@end example
|
| 10965 | |
@noindent
|
| 10966 | |
This version quotes the @samp{)}, so that it can be used as a balanced
|
| 10967 | |
Autoconf argument. As written, this is not balanced to an editor, but
|
| 10968 | |
it can be coupled with @samp{[#(]} to meet that need, too. However, it
|
| 10969 | |
still requires some edits before it can be copied and pasted into a
|
| 10970 | |
terminal.
|
| 10971 | |
|
| 10972 | |
@item Double-quoting the entire statement
|
| 10973 | |
@example
|
| 10974 | |
AC_DEFUN([my_case],
|
| 10975 | |
[[case $file_name in #(
|
| 10976 | |
*.c) echo "C source code";;
|
| 10977 | |
esac]])
|
| 10978 | |
@end example
|
| 10979 | |
@noindent
|
| 10980 | |
Since the entire macro is double-quoted, there is no problem with using
|
| 10981 | |
this as an Autoconf argument; and since the double-quoting is over the
|
| 10982 | |
entire statement, this code can be easily copied and pasted into a
|
| 10983 | |
terminal. However, the double quoting prevents the expansion of any
|
| 10984 | |
macros inside the case statement, which may cause its own set of
|
| 10985 | |
problems.
|
| 10986 | |
|
| 10987 | |
@item Using @code{AS_CASE}
|
| 10988 | |
@example
|
| 10989 | |
AC_DEFUN([my_case],
|
| 10990 | |
[AS_CASE([$file_name],
|
| 10991 | |
[*.c], [echo "C source code"])])
|
| 10992 | |
@end example
|
| 10993 | |
@noindent
|
| 10994 | |
This version avoids the balancing issue altogether, by relying on
|
| 10995 | |
@code{AS_CASE} (@pxref{Common Shell Constructs}); it also allows for the
|
| 10996 | |
expansion of @code{AC_REQUIRE} to occur prior to the entire case
|
| 10997 | |
statement, rather than within a branch of the case statement that might
|
| 10998 | |
not be taken. However, the abstraction comes with a penalty that it is
|
| 10999 | |
no longer a quick copy, paste, and edit to get back to shell code.
|
| 11000 | |
@end itemize
|
| 11001 | |
|
| 11002 | |
|
| 11003 | |
@node Quotation Rule Of Thumb
|
| 11004 | |
@subsection Quotation Rule Of Thumb
|
| 11005 | |
|
| 11006 | |
To conclude, the quotation rule of thumb is:
|
| 11007 | |
|
| 11008 | |
@center @emph{One pair of quotes per pair of parentheses.}
|
| 11009 | |
|
| 11010 | |
Never over-quote, never under-quote, in particular in the definition of
|
| 11011 | |
macros. In the few places where the macros need to use brackets
|
| 11012 | |
(usually in C program text or regular expressions), properly quote
|
| 11013 | |
@emph{the arguments}!
|
| 11014 | |
|
| 11015 | |
It is common to read Autoconf programs with snippets like:
|
| 11016 | |
|
| 11017 | |
@example
|
| 11018 | |
AC_TRY_LINK(
|
| 11019 | |
changequote(<<, >>)dnl
|
| 11020 | |
<<#include <time.h>
|
| 11021 | |
#ifndef tzname /* For SGI. */
|
| 11022 | |
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
|
| 11023 | |
#endif>>,
|
| 11024 | |
changequote([, ])dnl
|
| 11025 | |
[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
|
| 11026 | |
@end example
|
| 11027 | |
|
| 11028 | |
@noindent
|
| 11029 | |
which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
|
| 11030 | |
double quoting, so you just need:
|
| 11031 | |
|
| 11032 | |
@example
|
| 11033 | |
AC_TRY_LINK(
|
| 11034 | |
[#include <time.h>
|
| 11035 | |
#ifndef tzname /* For SGI. */
|
| 11036 | |
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
|
| 11037 | |
#endif],
|
| 11038 | |
[atoi (*tzname);],
|
| 11039 | |
[ac_cv_var_tzname=yes],
|
| 11040 | |
[ac_cv_var_tzname=no])
|
| 11041 | |
@end example
|
| 11042 | |
|
| 11043 | |
@noindent
|
| 11044 | |
The M4-fluent reader might note that these two examples are rigorously
|
| 11045 | |
equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
|
| 11046 | |
and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
|
| 11047 | |
quotes are not part of the arguments!
|
| 11048 | |
|
| 11049 | |
Simplified, the example above is just doing this:
|
| 11050 | |
|
| 11051 | |
@example
|
| 11052 | |
changequote(<<, >>)dnl
|
| 11053 | |
<<[]>>
|
| 11054 | |
changequote([, ])dnl
|
| 11055 | |
@end example
|
| 11056 | |
|
| 11057 | |
@noindent
|
| 11058 | |
instead of simply:
|
| 11059 | |
|
| 11060 | |
@example
|
| 11061 | |
[[]]
|
| 11062 | |
@end example
|
| 11063 | |
|
| 11064 | |
With macros that do not double quote their arguments (which is the
|
| 11065 | |
rule), double-quote the (risky) literals:
|
| 11066 | |
|
| 11067 | |
@example
|
| 11068 | |
AC_LINK_IFELSE([AC_LANG_PROGRAM(
|
| 11069 | |
[[#include <time.h>
|
| 11070 | |
#ifndef tzname /* For SGI. */
|
| 11071 | |
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
|
| 11072 | |
#endif]],
|
| 11073 | |
[atoi (*tzname);])],
|
| 11074 | |
[ac_cv_var_tzname=yes],
|
| 11075 | |
[ac_cv_var_tzname=no])
|
| 11076 | |
@end example
|
| 11077 | |
|
| 11078 | |
Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
|
| 11079 | |
should be using @code{AC_LINK_IFELSE} instead.
|
| 11080 | |
|
| 11081 | |
@xref{Quadrigraphs}, for what to do if you run into a hopeless case
|
| 11082 | |
where quoting does not suffice.
|
| 11083 | |
|
| 11084 | |
When you create a @command{configure} script using newly written macros,
|
| 11085 | |
examine it carefully to check whether you need to add more quotes in
|
| 11086 | |
your macros. If one or more words have disappeared in the M4
|
| 11087 | |
output, you need more quotes. When in doubt, quote.
|
| 11088 | |
|
| 11089 | |
However, it's also possible to put on too many layers of quotes. If
|
| 11090 | |
this happens, the resulting @command{configure} script may contain
|
| 11091 | |
unexpanded macros. The @command{autoconf} program checks for this problem
|
| 11092 | |
by looking for the string @samp{AC_} in @file{configure}. However, this
|
| 11093 | |
heuristic does not work in general: for example, it does not catch
|
| 11094 | |
overquoting in @code{AC_DEFINE} descriptions.
|
| 11095 | |
|
| 11096 | |
|
| 11097 | |
@c ---------------------------------------- Using autom4te
|
| 11098 | |
|
| 11099 | |
@node Using autom4te
|
| 11100 | |
@section Using @command{autom4te}
|
| 11101 | |
|
| 11102 | |
The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
|
| 11103 | |
to Autoconf per se, heavily rely on M4. All these different uses
|
| 11104 | |
revealed common needs factored into a layer over M4:
|
| 11105 | |
@command{autom4te}@footnote{
|
| 11106 | |
@c
|
| 11107 | |
Yet another great name from Lars J. Aas.
|
| 11108 | |
@c
|
| 11109 | |
}.
|
| 11110 | |
|
| 11111 | |
@command{autom4te} is a preprocessor that is like @command{m4}.
|
| 11112 | |
It supports M4 extensions designed for use in tools like Autoconf.
|
| 11113 | |
|
| 11114 | |
@menu
|
| 11115 | |
* autom4te Invocation:: A GNU M4 wrapper
|
| 11116 | |
* Customizing autom4te:: Customizing the Autoconf package
|
| 11117 | |
@end menu
|
| 11118 | |
|
| 11119 | |
@node autom4te Invocation
|
| 11120 | |
@subsection Invoking @command{autom4te}
|
| 11121 | |
|
| 11122 | |
The command line arguments are modeled after M4's:
|
| 11123 | |
|
| 11124 | |
@example
|
| 11125 | |
autom4te @var{options} @var{files}
|
| 11126 | |
@end example
|
| 11127 | |
|
| 11128 | |
@noindent
|
| 11129 | |
@evindex M4
|
| 11130 | |
where the @var{files} are directly passed to @command{m4}. By default,
|
| 11131 | |
GNU M4 is found during configuration, but the environment
|
| 11132 | |
variable
|
| 11133 | |
@env{M4} can be set to tell @command{autom4te} where to look. In addition
|
| 11134 | |
to the regular expansion, it handles the replacement of the quadrigraphs
|
| 11135 | |
(@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
|
| 11136 | |
output. It supports an extended syntax for the @var{files}:
|
| 11137 | |
|
| 11138 | |
@table @file
|
| 11139 | |
@item @var{file}.m4f
|
| 11140 | |
This file is an M4 frozen file. Note that @emph{all the previous files
|
| 11141 | |
are ignored}. See the option @option{--melt} for the rationale.
|
| 11142 | |
|
| 11143 | |
@item @var{file}?
|
| 11144 | |
If found in the library path, the @var{file} is included for expansion,
|
| 11145 | |
otherwise it is ignored instead of triggering a failure.
|
| 11146 | |
@end table
|
| 11147 | |
|
| 11148 | |
@sp 1
|
| 11149 | |
|
| 11150 | |
Of course, it supports the Autoconf common subset of options:
|
| 11151 | |
|
| 11152 | |
@table @option
|
| 11153 | |
@item --help
|
| 11154 | |
@itemx -h
|
| 11155 | |
Print a summary of the command line options and exit.
|
| 11156 | |
|
| 11157 | |
@item --version
|
| 11158 | |
@itemx -V
|
| 11159 | |
Print the version number of Autoconf and exit.
|
| 11160 | |
|
| 11161 | |
@item --verbose
|
| 11162 | |
@itemx -v
|
| 11163 | |
Report processing steps.
|
| 11164 | |
|
| 11165 | |
@item --debug
|
| 11166 | |
@itemx -d
|
| 11167 | |
Don't remove the temporary files and be even more verbose.
|
| 11168 | |
|
| 11169 | |
@item --include=@var{dir}
|
| 11170 | |
@itemx -I @var{dir}
|
| 11171 | |
Also look for input files in @var{dir}. Multiple invocations
|
| 11172 | |
accumulate.
|
| 11173 | |
|
| 11174 | |
@item --output=@var{file}
|
| 11175 | |
@itemx -o @var{file}
|
| 11176 | |
Save output (script or trace) to @var{file}. The file @option{-} stands
|
| 11177 | |
for the standard output.
|
| 11178 | |
@end table
|
| 11179 | |
|
| 11180 | |
@sp 1
|
| 11181 | |
|
| 11182 | |
As an extension of @command{m4}, it includes the following options:
|
| 11183 | |
|
| 11184 | |
@table @option
|
| 11185 | |
@item --warnings=@var{category}
|
| 11186 | |
@itemx -W @var{category}
|
| 11187 | |
@evindex WARNINGS
|
| 11188 | |
@c FIXME: Point to the M4sugar macros, not Autoconf's.
|
| 11189 | |
Report the warnings related to @var{category} (which can actually be a
|
| 11190 | |
comma separated list). @xref{Reporting Messages}, macro
|
| 11191 | |
@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
|
| 11192 | |
values include:
|
| 11193 | |
|
| 11194 | |
@table @samp
|
| 11195 | |
@item all
|
| 11196 | |
report all the warnings
|
| 11197 | |
|
| 11198 | |
@item none
|
| 11199 | |
report none
|
| 11200 | |
|
| 11201 | |
@item error
|
| 11202 | |
treats warnings as errors
|
| 11203 | |
|
| 11204 | |
@item no-@var{category}
|
| 11205 | |
disable warnings falling into @var{category}
|
| 11206 | |
@end table
|
| 11207 | |
|
| 11208 | |
Warnings about @samp{syntax} are enabled by default, and the environment
|
| 11209 | |
variable @env{WARNINGS}, a comma separated list of categories, is
|
| 11210 | |
honored. @samp{autom4te -W @var{category}} actually
|
| 11211 | |
behaves as if you had run:
|
| 11212 | |
|
| 11213 | |
@example
|
| 11214 | |
autom4te --warnings=syntax,$WARNINGS,@var{category}
|
| 11215 | |
@end example
|
| 11216 | |
|
| 11217 | |
@noindent
|
| 11218 | |
For example, if you want to disable defaults and @env{WARNINGS}
|
| 11219 | |
of @command{autom4te}, but enable the warnings about obsolete
|
| 11220 | |
constructs, you would use @option{-W none,obsolete}.
|
| 11221 | |
|
| 11222 | |
@cindex Back trace
|
| 11223 | |
@cindex Macro invocation stack
|
| 11224 | |
@command{autom4te} displays a back trace for errors, but not for
|
| 11225 | |
warnings; if you want them, just pass @option{-W error}.
|
| 11226 | |
|
| 11227 | |
@item --melt
|
| 11228 | |
@itemx -M
|
| 11229 | |
Do not use frozen files. Any argument @code{@var{file}.m4f} is
|
| 11230 | |
replaced by @code{@var{file}.m4}. This helps tracing the macros which
|
| 11231 | |
are executed only when the files are frozen, typically
|
| 11232 | |
@code{m4_define}. For instance, running:
|
| 11233 | |
|
| 11234 | |
@example
|
| 11235 | |
autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
|
| 11236 | |
@end example
|
| 11237 | |
|
| 11238 | |
@noindent
|
| 11239 | |
is roughly equivalent to running:
|
| 11240 | |
|
| 11241 | |
@example
|
| 11242 | |
m4 1.m4 2.m4 3.m4 4.m4 input.m4
|
| 11243 | |
@end example
|
| 11244 | |
|
| 11245 | |
@noindent
|
| 11246 | |
while
|
| 11247 | |
|
| 11248 | |
@example
|
| 11249 | |
autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
|
| 11250 | |
@end example
|
| 11251 | |
|
| 11252 | |
@noindent
|
| 11253 | |
is equivalent to:
|
| 11254 | |
|
| 11255 | |
@example
|
| 11256 | |
m4 --reload-state=4.m4f input.m4
|
| 11257 | |
@end example
|
| 11258 | |
|
| 11259 | |
@item --freeze
|
| 11260 | |
@itemx -F
|
| 11261 | |
Produce a frozen state file. @command{autom4te} freezing is stricter
|
| 11262 | |
than M4's: it must produce no warnings, and no output other than empty
|
| 11263 | |
lines (a line with white space is @emph{not} empty) and comments
|
| 11264 | |
(starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
|
| 11265 | |
this option takes no argument:
|
| 11266 | |
|
| 11267 | |
@example
|
| 11268 | |
autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
|
| 11269 | |
@end example
|
| 11270 | |
|
| 11271 | |
@noindent
|
| 11272 | |
corresponds to
|
| 11273 | |
|
| 11274 | |
@example
|
| 11275 | |
m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
|
| 11276 | |
@end example
|
| 11277 | |
|
| 11278 | |
@item --mode=@var{octal-mode}
|
| 11279 | |
@itemx -m @var{octal-mode}
|
| 11280 | |
Set the mode of the non-traces output to @var{octal-mode}; by default
|
| 11281 | |
@samp{0666}.
|
| 11282 | |
@end table
|
| 11283 | |
|
| 11284 | |
@sp 1
|
| 11285 | |
|
| 11286 | |
@cindex @file{autom4te.cache}
|
| 11287 | |
As another additional feature over @command{m4}, @command{autom4te}
|
| 11288 | |
caches its results. GNU M4 is able to produce a regular
|
| 11289 | |
output and traces at the same time. Traces are heavily used in the
|
| 11290 | |
GNU Build System: @command{autoheader} uses them to build
|
| 11291 | |
@file{config.h.in}, @command{autoreconf} to determine what
|
| 11292 | |
GNU Build System components are used, @command{automake} to
|
| 11293 | |
``parse'' @file{configure.ac} etc. To avoid recomputation,
|
| 11294 | |
traces are cached while performing regular expansion,
|
| 11295 | |
and conversely. This cache is (actually, the caches are) stored in
|
| 11296 | |
the directory @file{autom4te.cache}. @emph{It can safely be removed}
|
| 11297 | |
at any moment (especially if for some reason @command{autom4te}
|
| 11298 | |
considers it trashed).
|
| 11299 | |
|
| 11300 | |
@table @option
|
| 11301 | |
@item --cache=@var{directory}
|
| 11302 | |
@itemx -C @var{directory}
|
| 11303 | |
Specify the name of the directory where the result should be cached.
|
| 11304 | |
Passing an empty value disables caching. Be sure to pass a relative
|
| 11305 | |
file name, as for the time being, global caches are not supported.
|
| 11306 | |
|
| 11307 | |
@item --no-cache
|
| 11308 | |
Don't cache the results.
|
| 11309 | |
|
| 11310 | |
@item --force
|
| 11311 | |
@itemx -f
|
| 11312 | |
If a cache is used, consider it obsolete (but update it anyway).
|
| 11313 | |
@end table
|
| 11314 | |
|
| 11315 | |
@sp 1
|
| 11316 | |
|
| 11317 | |
Because traces are so important to the GNU Build System,
|
| 11318 | |
@command{autom4te} provides high level tracing features as compared to
|
| 11319 | |
M4, and helps exploiting the cache:
|
| 11320 | |
|
| 11321 | |
@table @option
|
| 11322 | |
@item --trace=@var{macro}[:@var{format}]
|
| 11323 | |
@itemx -t @var{macro}[:@var{format}]
|
| 11324 | |
Trace the invocations of @var{macro} according to the @var{format}.
|
| 11325 | |
Multiple @option{--trace} arguments can be used to list several macros.
|
| 11326 | |
Multiple @option{--trace} arguments for a single macro are not
|
| 11327 | |
cumulative; instead, you should just make @var{format} as long as
|
| 11328 | |
needed.
|
| 11329 | |
|
| 11330 | |
The @var{format} is a regular string, with newlines if desired, and
|
| 11331 | |
several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
|
| 11332 | |
use the following special escapes:
|
| 11333 | |
|
| 11334 | |
@table @samp
|
| 11335 | |
@item $$
|
| 11336 | |
@c $$ restore font-lock
|
| 11337 | |
The character @samp{$}.
|
| 11338 | |
|
| 11339 | |
@item $f
|
| 11340 | |
The file name from which @var{macro} is called.
|
| 11341 | |
|
| 11342 | |
@item $l
|
| 11343 | |
The line number from which @var{macro} is called.
|
| 11344 | |
|
| 11345 | |
@item $d
|
| 11346 | |
The depth of the @var{macro} call. This is an M4 technical detail that
|
| 11347 | |
you probably don't want to know about.
|
| 11348 | |
|
| 11349 | |
@item $n
|
| 11350 | |
The name of the @var{macro}.
|
| 11351 | |
|
| 11352 | |
@item $@var{num}
|
| 11353 | |
The @var{num}th argument of the call to @var{macro}.
|
| 11354 | |
|
| 11355 | |
@item $@@
|
| 11356 | |
@itemx $@var{sep}@@
|
| 11357 | |
@itemx $@{@var{separator}@}@@
|
| 11358 | |
All the arguments passed to @var{macro}, separated by the character
|
| 11359 | |
@var{sep} or the string @var{separator} (@samp{,} by default). Each
|
| 11360 | |
argument is quoted, i.e., enclosed in a pair of square brackets.
|
| 11361 | |
|
| 11362 | |
@item $*
|
| 11363 | |
@itemx $@var{sep}*
|
| 11364 | |
@itemx $@{@var{separator}@}*
|
| 11365 | |
As above, but the arguments are not quoted.
|
| 11366 | |
|
| 11367 | |
@item $%
|
| 11368 | |
@itemx $@var{sep}%
|
| 11369 | |
@itemx $@{@var{separator}@}%
|
| 11370 | |
As above, but the arguments are not quoted, all new line characters in
|
| 11371 | |
the arguments are smashed, and the default separator is @samp{:}.
|
| 11372 | |
|
| 11373 | |
The escape @samp{$%} produces single-line trace outputs (unless you put
|
| 11374 | |
newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
|
| 11375 | |
not.
|
| 11376 | |
@end table
|
| 11377 | |
|
| 11378 | |
@xref{autoconf Invocation}, for examples of trace uses.
|
| 11379 | |
|
| 11380 | |
@item --preselect=@var{macro}
|
| 11381 | |
@itemx -p @var{macro}
|
| 11382 | |
Cache the traces of @var{macro}, but do not enable traces. This is
|
| 11383 | |
especially important to save CPU cycles in the future. For instance,
|
| 11384 | |
when invoked, @command{autoconf} preselects all the macros that
|
| 11385 | |
@command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
|
| 11386 | |
trace, so that running @command{m4} is not needed to trace them: the
|
| 11387 | |
cache suffices. This results in a huge speed-up.
|
| 11388 | |
@end table
|
| 11389 | |
|
| 11390 | |
@sp 1
|
| 11391 | |
|
| 11392 | |
@cindex Autom4te Library
|
| 11393 | |
Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
|
| 11394 | |
libraries}. They consists in a powerful yet extremely simple feature:
|
| 11395 | |
sets of combined command line arguments:
|
| 11396 | |
|
| 11397 | |
@table @option
|
| 11398 | |
@item --language=@var{language}
|
| 11399 | |
@itemx -l @var{language}
|
| 11400 | |
Use the @var{language} Autom4te library. Current languages include:
|
| 11401 | |
|
| 11402 | |
@table @code
|
| 11403 | |
@item M4sugar
|
| 11404 | |
create M4sugar output.
|
| 11405 | |
|
| 11406 | |
@item M4sh
|
| 11407 | |
create M4sh executable shell scripts.
|
| 11408 | |
|
| 11409 | |
@item Autotest
|
| 11410 | |
create Autotest executable test suites.
|
| 11411 | |
|
| 11412 | |
@item Autoconf-without-aclocal-m4
|
| 11413 | |
create Autoconf executable configure scripts without
|
| 11414 | |
reading @file{aclocal.m4}.
|
| 11415 | |
|
| 11416 | |
@item Autoconf
|
| 11417 | |
create Autoconf executable configure scripts. This language inherits
|
| 11418 | |
all the characteristics of @code{Autoconf-without-aclocal-m4} and
|
| 11419 | |
additionally reads @file{aclocal.m4}.
|
| 11420 | |
@end table
|
| 11421 | |
|
| 11422 | |
@item --prepend-include=@var{dir}
|
| 11423 | |
@itemx -B @var{dir}
|
| 11424 | |
Prepend directory @var{dir} to the search path. This is used to include
|
| 11425 | |
the language-specific files before any third-party macros.
|
| 11426 | |
|
| 11427 | |
@end table
|
| 11428 | |
|
| 11429 | |
@cindex @file{autom4te.cfg}
|
| 11430 | |
As an example, if Autoconf is installed in its default location,
|
| 11431 | |
@file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
|
| 11432 | |
strictly equivalent to the command:
|
| 11433 | |
|
| 11434 | |
@example
|
| 11435 | |
autom4te --prepend-include /usr/local/share/autoconf \
|
| 11436 | |
m4sugar/m4sugar.m4f --warnings syntax foo.m4
|
| 11437 | |
@end example
|
| 11438 | |
|
| 11439 | |
@noindent
|
| 11440 | |
Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
|
| 11441 | |
is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
|
| 11442 | |
foo.m4}, i.e.:
|
| 11443 | |
|
| 11444 | |
@example
|
| 11445 | |
autom4te --prepend-include /usr/local/share/autoconf \
|
| 11446 | |
m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
|
| 11447 | |
@end example
|
| 11448 | |
|
| 11449 | |
@noindent
|
| 11450 | |
The definition of the languages is stored in @file{autom4te.cfg}.
|
| 11451 | |
|
| 11452 | |
@node Customizing autom4te
|
| 11453 | |
@subsection Customizing @command{autom4te}
|
| 11454 | |
|
| 11455 | |
One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
|
| 11456 | |
as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
|
| 11457 | |
as found in the directory from which @command{autom4te} is run). The
|
| 11458 | |
order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
|
| 11459 | |
then @file{./.autom4te.cfg}, and finally the command line arguments.
|
| 11460 | |
|
| 11461 | |
In these text files, comments are introduced with @code{#}, and empty
|
| 11462 | |
lines are ignored. Customization is performed on a per-language basis,
|
| 11463 | |
wrapped in between a @samp{begin-language: "@var{language}"},
|
| 11464 | |
@samp{end-language: "@var{language}"} pair.
|
| 11465 | |
|
| 11466 | |
Customizing a language stands for appending options (@pxref{autom4te
|
| 11467 | |
Invocation}) to the current definition of the language. Options, and
|
| 11468 | |
more generally arguments, are introduced by @samp{args:
|
| 11469 | |
@var{arguments}}. You may use the traditional shell syntax to quote the
|
| 11470 | |
@var{arguments}.
|
| 11471 | |
|
| 11472 | |
As an example, to disable Autoconf caches (@file{autom4te.cache})
|
| 11473 | |
globally, include the following lines in @file{~/.autom4te.cfg}:
|
| 11474 | |
|
| 11475 | |
@verbatim
|
| 11476 | |
## ------------------ ##
|
| 11477 | |
## User Preferences. ##
|
| 11478 | |
## ------------------ ##
|
| 11479 | |
|
| 11480 | |
begin-language: "Autoconf-without-aclocal-m4"
|
| 11481 | |
args: --no-cache
|
| 11482 | |
end-language: "Autoconf-without-aclocal-m4"
|
| 11483 | |
@end verbatim
|
| 11484 | |
|
| 11485 | |
|
| 11486 | |
@node Programming in M4sugar
|
| 11487 | |
@section Programming in M4sugar
|
| 11488 | |
|
| 11489 | |
@cindex M4sugar
|
| 11490 | |
M4 by itself provides only a small, but sufficient, set of all-purpose
|
| 11491 | |
macros. M4sugar introduces additional generic macros. Its name was
|
| 11492 | |
coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
|
| 11493 | |
M4sugar''.
|
| 11494 | |
|
| 11495 | |
M4sugar reserves the macro namespace @samp{^_m4_} for internal use, and
|
| 11496 | |
the macro namespace @samp{^m4_} for M4sugar macros. You should not
|
| 11497 | |
define your own macros into these namespaces.
|
| 11498 | |
|
| 11499 | |
@menu
|
| 11500 | |
* Redefined M4 Macros:: M4 builtins changed in M4sugar
|
| 11501 | |
* Diagnostic Macros:: Diagnostic messages from M4sugar
|
| 11502 | |
* Diversion support:: Diversions in M4sugar
|
| 11503 | |
* Conditional constructs:: Conditions in M4
|
| 11504 | |
* Looping constructs:: Iteration in M4
|
| 11505 | |
* Evaluation Macros:: More quotation and evaluation control
|
| 11506 | |
* Text processing Macros:: String manipulation in M4
|
| 11507 | |
* Number processing Macros:: Arithmetic computation in M4
|
| 11508 | |
* Set manipulation Macros:: Set manipulation in M4
|
| 11509 | |
* Forbidden Patterns:: Catching unexpanded macros
|
| 11510 | |
@end menu
|
| 11511 | |
|
| 11512 | |
@node Redefined M4 Macros
|
| 11513 | |
@subsection Redefined M4 Macros
|
| 11514 | |
|
| 11515 | |
@msindex{builtin}
|
| 11516 | |
@msindex{changecom}
|
| 11517 | |
@msindex{changequote}
|
| 11518 | |
@msindex{debugfile}
|
| 11519 | |
@msindex{debugmode}
|
| 11520 | |
@msindex{decr}
|
| 11521 | |
@msindex{define}
|
| 11522 | |
@msindex{divnum}
|
| 11523 | |
@msindex{errprint}
|
| 11524 | |
@msindex{esyscmd}
|
| 11525 | |
@msindex{eval}
|
| 11526 | |
@msindex{format}
|
| 11527 | |
@msindex{ifdef}
|
| 11528 | |
@msindex{incr}
|
| 11529 | |
@msindex{index}
|
| 11530 | |
@msindex{indir}
|
| 11531 | |
@msindex{len}
|
| 11532 | |
@msindex{pushdef}
|
| 11533 | |
@msindex{shift}
|
| 11534 | |
@msindex{substr}
|
| 11535 | |
@msindex{syscmd}
|
| 11536 | |
@msindex{sysval}
|
| 11537 | |
@msindex{traceoff}
|
| 11538 | |
@msindex{traceon}
|
| 11539 | |
@msindex{translit}
|
| 11540 | |
With a few exceptions, all the M4 native macros are moved in the
|
| 11541 | |
@samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
|
| 11542 | |
@code{m4_define} etc.
|
| 11543 | |
|
| 11544 | |
The list of macros unchanged from M4, except for their name, is:
|
| 11545 | |
@itemize @minus
|
| 11546 | |
@item m4_builtin
|
| 11547 | |
@item m4_changecom
|
| 11548 | |
@item m4_changequote
|
| 11549 | |
@item m4_debugfile
|
| 11550 | |
@item m4_debugmode
|
| 11551 | |
@item m4_decr
|
| 11552 | |
@item m4_define
|
| 11553 | |
@item m4_divnum
|
| 11554 | |
@item m4_errprint
|
| 11555 | |
@item m4_esyscmd
|
| 11556 | |
@item m4_eval
|
| 11557 | |
@item m4_format
|
| 11558 | |
@item m4_ifdef
|
| 11559 | |
@item m4_incr
|
| 11560 | |
@item m4_index
|
| 11561 | |
@item m4_indir
|
| 11562 | |
@item m4_len
|
| 11563 | |
@item m4_pushdef
|
| 11564 | |
@item m4_shift
|
| 11565 | |
@item m4_substr
|
| 11566 | |
@item m4_syscmd
|
| 11567 | |
@item m4_sysval
|
| 11568 | |
@item m4_traceoff
|
| 11569 | |
@item m4_traceon
|
| 11570 | |
@item m4_translit
|
| 11571 | |
@end itemize
|
| 11572 | |
|
| 11573 | |
Some M4 macros are redefined, and are slightly incompatible with their
|
| 11574 | |
native equivalent.
|
| 11575 | |
|
| 11576 | |
@defmac __file__
|
| 11577 | |
@defmacx __line__
|
| 11578 | |
@MSindex __file__
|
| 11579 | |
@MSindex __line__
|
| 11580 | |
All M4 macros starting with @samp{__} retain their original name: for
|
| 11581 | |
example, no @code{m4__file__} is defined.
|
| 11582 | |
@end defmac
|
| 11583 | |
|
| 11584 | |
@defmac __oline__
|
| 11585 | |
@MSindex __oline__
|
| 11586 | |
This is not technically a macro, but a feature of Autom4te. The
|
| 11587 | |
sequence @code{__oline__} can be used similarly to the other m4sugar
|
| 11588 | |
location macros, but rather than expanding to the location of the input
|
| 11589 | |
file, it is translated to the line number where it appears in the output
|
| 11590 | |
file after all other M4 expansions.
|
| 11591 | |
@end defmac
|
| 11592 | |
|
| 11593 | |
@defmac dnl
|
| 11594 | |
@MSindex dnl
|
| 11595 | |
This macro kept its original name: no @code{m4_dnl} is defined.
|
| 11596 | |
@end defmac
|
| 11597 | |
|
| 11598 | |
@defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
|
| 11599 | |
@msindex{bpatsubst}
|
| 11600 | |
This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
|
| 11601 | |
is kept for future versions of M4sugar, once GNU M4 2.0 is
|
| 11602 | |
released and supports extended regular expression syntax.
|
| 11603 | |
@end defmac
|
| 11604 | |
|
| 11605 | |
@defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
|
| 11606 | |
@msindex{bregexp}
|
| 11607 | |
This macro corresponds to @code{regexp}. The name @code{m4_regexp}
|
| 11608 | |
is kept for future versions of M4sugar, once GNU M4 2.0 is
|
| 11609 | |
released and supports extended regular expression syntax.
|
| 11610 | |
@end defmac
|
| 11611 | |
|
| 11612 | |
@defmac m4_copy (@var{source}, @var{dest})
|
| 11613 | |
@defmacx m4_copy_force (@var{source}, @var{dest})
|
| 11614 | |
@defmacx m4_rename (@var{source}, @var{dest})
|
| 11615 | |
@defmacx m4_rename_force (@var{source}, @var{dest})
|
| 11616 | |
@msindex{copy}
|
| 11617 | |
@msindex{copy_force}
|
| 11618 | |
@msindex{rename}
|
| 11619 | |
@msindex{rename_force}
|
| 11620 | |
These macros aren't directly builtins, but are closely related to
|
| 11621 | |
@code{m4_pushdef} and @code{m4_defn}. @code{m4_copy} and
|
| 11622 | |
@code{m4_rename} ensure that @var{dest} is undefined, while
|
| 11623 | |
@code{m4_copy_force} and @code{m4_rename_force} overwrite any existing
|
| 11624 | |
definition. All four macros then proceed to copy the entire pushdef
|
| 11625 | |
stack of definitions of @var{source} over to @var{dest}. @code{m4_copy}
|
| 11626 | |
and @code{m4_copy_force} preserve the source (including in the special
|
| 11627 | |
case where @var{source} is undefined), while @code{m4_rename} and
|
| 11628 | |
@code{m4_rename_force} undefine the original macro name (making it an
|
| 11629 | |
error to rename an undefined @var{source}).
|
| 11630 | |
|
| 11631 | |
Note that attempting to invoke a renamed macro might not work, since the
|
| 11632 | |
macro may have a dependence on helper macros accessed via composition of
|
| 11633 | |
@samp{$0} but that were not also renamed; likewise, other macros may
|
| 11634 | |
have a hard-coded dependence on @var{source} and could break if
|
| 11635 | |
@var{source} has been deleted. On the other hand, it is always safe to
|
| 11636 | |
rename a macro to temporarily move it out of the way, then rename it
|
| 11637 | |
back later to restore original semantics.
|
| 11638 | |
@end defmac
|
| 11639 | |
|
| 11640 | |
@defmac m4_defn (@var{macro}@dots{})
|
| 11641 | |
@msindex{defn}
|
| 11642 | |
This macro fails if @var{macro} is not defined, even when using older
|
| 11643 | |
versions of M4 that did not warn. See @code{m4_undefine}.
|
| 11644 | |
Unfortunately, in order to support these older versions of M4, there are
|
| 11645 | |
some situations involving unbalanced quotes where concatenating multiple
|
| 11646 | |
macros together will work in newer M4 but not in m4sugar; use
|
| 11647 | |
quadrigraphs to work around this.
|
| 11648 | |
@end defmac
|
| 11649 | |
|
| 11650 | |
@defmac m4_divert (@var{diversion})
|
| 11651 | |
@msindex{divert}
|
| 11652 | |
M4sugar relies heavily on diversions, so rather than behaving as a
|
| 11653 | |
primitive, @code{m4_divert} behaves like:
|
| 11654 | |
@example
|
| 11655 | |
m4_divert_pop()m4_divert_push([@var{diversion}])
|
| 11656 | |
@end example
|
| 11657 | |
@noindent
|
| 11658 | |
@xref{Diversion support}, for more details about the use of the
|
| 11659 | |
diversion stack. In particular, this implies that @var{diversion}
|
| 11660 | |
should be a named diversion rather than a raw number. But be aware that
|
| 11661 | |
it is seldom necessary to explicitly change the diversion stack, and
|
| 11662 | |
that when done incorrectly, it can lead to syntactically invalid
|
| 11663 | |
scripts.
|
| 11664 | |
@end defmac
|
| 11665 | |
|
| 11666 | |
@defmac m4_dumpdef (@var{name}@dots{})
|
| 11667 | |
@defmacx m4_dumpdefs (@var{name}@dots{})
|
| 11668 | |
@msindex{dumpdef}
|
| 11669 | |
@msindex{dumpdefs}
|
| 11670 | |
@code{m4_dumpdef} is like the M4 builtin, except that this version
|
| 11671 | |
requires at least one argument, output always goes to standard error
|
| 11672 | |
rather than the current debug file, no sorting is done on multiple
|
| 11673 | |
arguments, and an error is issued if any
|
| 11674 | |
@var{name} is undefined. @code{m4_dumpdefs} is a convenience macro that
|
| 11675 | |
calls @code{m4_dumpdef} for all of the
|
| 11676 | |
@code{m4_pushdef} stack of definitions, starting with the current, and
|
| 11677 | |
silently does nothing if @var{name} is undefined.
|
| 11678 | |
|
| 11679 | |
Unfortunately, due to a limitation in M4 1.4.x, any macro defined as a
|
| 11680 | |
builtin is output as the empty string. This behavior is rectified by
|
| 11681 | |
using M4 1.6 or newer. However, this behavior difference means that
|
| 11682 | |
@code{m4_dumpdef} should only be used while developing m4sugar macros,
|
| 11683 | |
and never in the final published form of a macro.
|
| 11684 | |
@end defmac
|
| 11685 | |
|
| 11686 | |
@defmac m4_esyscmd_s (@var{command})
|
| 11687 | |
@msindex{esyscmd_s}
|
| 11688 | |
Like @code{m4_esyscmd}, this macro expands to the result of running
|
| 11689 | |
@var{command} in a shell. The difference is that any trailing newlines
|
| 11690 | |
are removed, so that the output behaves more like shell command
|
| 11691 | |
substitution.
|
| 11692 | |
@end defmac
|
| 11693 | |
|
| 11694 | |
@defmac m4_exit (@var{exit-status})
|
| 11695 | |
@msindex{exit}
|
| 11696 | |
This macro corresponds to @code{m4exit}.
|
| 11697 | |
@end defmac
|
| 11698 | |
|
| 11699 | |
@defmac m4_if (@var{comment})
|
| 11700 | |
@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
|
| 11701 | |
@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal-1}, @
|
| 11702 | |
@var{string-3}, @var{string-4}, @var{equal-2}, @dots{}, @ovar{not-equal})
|
| 11703 | |
@msindex{if}
|
| 11704 | |
This macro corresponds to @code{ifelse}. @var{string-1} and
|
| 11705 | |
@var{string-2} are compared literally, so usually one of the two
|
| 11706 | |
arguments is passed unquoted. @xref{Conditional constructs}, for more
|
| 11707 | |
conditional idioms.
|
| 11708 | |
@end defmac
|
| 11709 | |
|
| 11710 | |
@defmac m4_include (@var{file})
|
| 11711 | |
@defmacx m4_sinclude (@var{file})
|
| 11712 | |
@msindex{include}
|
| 11713 | |
@msindex{sinclude}
|
| 11714 | |
Like the M4 builtins, but warn against multiple inclusions of @var{file}.
|
| 11715 | |
@end defmac
|
| 11716 | |
|
| 11717 | |
@defmac m4_mkstemp (@var{template})
|
| 11718 | |
@defmacx m4_maketemp (@var{template})
|
| 11719 | |
@msindex{maketemp}
|
| 11720 | |
@msindex{mkstemp}
|
| 11721 | |
Posix requires @code{maketemp} to replace the trailing @samp{X}
|
| 11722 | |
characters in @var{template} with the process id, without regards to the
|
| 11723 | |
existence of a file by that name, but this a security hole. When this
|
| 11724 | |
was pointed out to the Posix folks, they agreed to invent a new macro
|
| 11725 | |
@code{mkstemp} that always creates a uniquely named file, but not all
|
| 11726 | |
versions of GNU M4 support the new macro. In M4sugar,
|
| 11727 | |
@code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
|
| 11728 | |
and both have the secure semantics regardless of which macro the
|
| 11729 | |
underlying M4 provides.
|
| 11730 | |
@end defmac
|
| 11731 | |
|
| 11732 | |
@defmac m4_popdef (@var{macro}@dots{})
|
| 11733 | |
@msindex{popdef}
|
| 11734 | |
This macro fails if @var{macro} is not defined, even when using older
|
| 11735 | |
versions of M4 that did not warn. See @code{m4_undefine}.
|
| 11736 | |
@end defmac
|
| 11737 | |
|
| 11738 | |
@defmac m4_undefine (@var{macro}@dots{})
|
| 11739 | |
@msindex{undefine}
|
| 11740 | |
This macro fails if @var{macro} is not defined, even when using older
|
| 11741 | |
versions of M4 that did not warn. Use
|
| 11742 | |
|
| 11743 | |
@example
|
| 11744 | |
m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
|
| 11745 | |
@end example
|
| 11746 | |
|
| 11747 | |
@noindent
|
| 11748 | |
if you are not sure whether @var{macro} is defined.
|
| 11749 | |
@end defmac
|
| 11750 | |
|
| 11751 | |
@defmac m4_undivert (@var{diversion}@dots{})
|
| 11752 | |
@msindex{undivert}
|
| 11753 | |
Unlike the M4 builtin, at least one @var{diversion} must be specified.
|
| 11754 | |
Also, since the M4sugar diversion stack prefers named
|
| 11755 | |
diversions, the use of @code{m4_undivert} to include files is risky.
|
| 11756 | |
@xref{Diversion support}, for more details about the use of the
|
| 11757 | |
diversion stack. But be aware that it is seldom necessary to explicitly
|
| 11758 | |
change the diversion stack, and that when done incorrectly, it can lead
|
| 11759 | |
to syntactically invalid scripts.
|
| 11760 | |
@end defmac
|
| 11761 | |
|
| 11762 | |
@defmac m4_wrap (@var{text})
|
| 11763 | |
@defmacx m4_wrap_lifo (@var{text})
|
| 11764 | |
@msindex{wrap}
|
| 11765 | |
@msindex{wrap_lifo}
|
| 11766 | |
These macros correspond to @code{m4wrap}. Posix requires arguments of
|
| 11767 | |
multiple wrap calls to be reprocessed at EOF in the same order
|
| 11768 | |
as the original calls (first-in, first-out). GNU M4 versions
|
| 11769 | |
through 1.4.10, however, reprocess them in reverse order (last-in,
|
| 11770 | |
first-out). Both orders are useful, therefore, you can rely on
|
| 11771 | |
@code{m4_wrap} to provide FIFO semantics and @code{m4_wrap_lifo} for
|
| 11772 | |
LIFO semantics, regardless of the underlying GNU M4 version.
|
| 11773 | |
|
| 11774 | |
Unlike the GNU M4 builtin, these macros only recognize one
|
| 11775 | |
argument, and avoid token pasting between consecutive invocations. On
|
| 11776 | |
the other hand, nested calls to @code{m4_wrap} from within wrapped text
|
| 11777 | |
work just as in the builtin.
|
| 11778 | |
@end defmac
|
| 11779 | |
|
| 11780 | |
|
| 11781 | |
@node Diagnostic Macros
|
| 11782 | |
@subsection Diagnostic messages from M4sugar
|
| 11783 | |
@cindex Messages, from @command{M4sugar}
|
| 11784 | |
|
| 11785 | |
When macros statically diagnose abnormal situations, benign or fatal,
|
| 11786 | |
they should report them using these macros. For issuing dynamic issues,
|
| 11787 | |
i.e., when @command{configure} is run, see @ref{Printing Messages}.
|
| 11788 | |
|
| 11789 | |
@defmac m4_assert (@var{expression}, @dvar{exit-status, 1})
|
| 11790 | |
@msindex{assert}
|
| 11791 | |
Assert that the arithmetic @var{expression} evaluates to non-zero.
|
| 11792 | |
Otherwise, issue a fatal error, and exit @command{autom4te} with
|
| 11793 | |
@var{exit-status}.
|
| 11794 | |
@end defmac
|
| 11795 | |
|
| 11796 | |
@defmac m4_errprintn (@var{message})
|
| 11797 | |
@msindex{errprintn}
|
| 11798 | |
Similar to the builtin @code{m4_errprint}, except that a newline is
|
| 11799 | |
guaranteed after @var{message}.
|
| 11800 | |
@end defmac
|
| 11801 | |
|
| 11802 | |
@anchor{m4_fatal}
|
| 11803 | |
@defmac m4_fatal (@var{message})
|
| 11804 | |
@msindex{fatal}
|
| 11805 | |
Report a severe error @var{message} prefixed with the current location,
|
| 11806 | |
and have @command{autom4te} die.
|
| 11807 | |
@end defmac
|
| 11808 | |
|
| 11809 | |
@defmac m4_location
|
| 11810 | |
@msindex{location}
|
| 11811 | |
Useful as a prefix in a message line. Short for:
|
| 11812 | |
@example
|
| 11813 | |
__file__:__line__
|
| 11814 | |
@end example
|
| 11815 | |
@end defmac
|
| 11816 | |
|
| 11817 | |
@anchor{m4_warn}
|
| 11818 | |
@defmac m4_warn (@var{category}, @var{message})
|
| 11819 | |
@msindex{warn}
|
| 11820 | |
Report @var{message} as a warning (or as an error if requested by the
|
| 11821 | |
user) if warnings of the @var{category} are turned on. If the message
|
| 11822 | |
is emitted, it is prefixed with the current location, and followed by a
|
| 11823 | |
call trace of all macros defined via @code{AC_DEFUN} used to get to the
|
| 11824 | |
current expansion. You are encouraged to use standard categories, which
|
| 11825 | |
currently include:
|
| 11826 | |
|
| 11827 | |
@table @samp
|
| 11828 | |
@item all
|
| 11829 | |
messages that don't fall into one of the following categories. Use of an
|
| 11830 | |
empty @var{category} is equivalent.
|
| 11831 | |
|
| 11832 | |
@item cross
|
| 11833 | |
related to cross compilation issues.
|
| 11834 | |
|
| 11835 | |
@item obsolete
|
| 11836 | |
use of an obsolete construct.
|
| 11837 | |
|
| 11838 | |
@item syntax
|
| 11839 | |
dubious syntactic constructs, incorrectly ordered macro calls.
|
| 11840 | |
@end table
|
| 11841 | |
@end defmac
|
| 11842 | |
|
| 11843 | |
|
| 11844 | |
@node Diversion support
|
| 11845 | |
@subsection Diversion support
|
| 11846 | |
|
| 11847 | |
M4sugar makes heavy use of diversions under the hood, because it is
|
| 11848 | |
often the case that
|
| 11849 | |
text that must appear early in the output is not discovered until late
|
| 11850 | |
in the input. Additionally, some of the topological sorting algorithms
|
| 11851 | |
used in resolving macro dependencies use diversions. However, most
|
| 11852 | |
macros should not need to change diversions directly, but rather rely on
|
| 11853 | |
higher-level M4sugar macros to manage diversions transparently. If you
|
| 11854 | |
change diversions improperly, you risk generating a syntactically
|
| 11855 | |
invalid script, because an incorrect diversion will violate assumptions
|
| 11856 | |
made by many macros about whether prerequisite text has been previously
|
| 11857 | |
output. In short, if you manually change the diversion, you should not
|
| 11858 | |
expect any macros provided by the Autoconf package to work until you
|
| 11859 | |
have restored the diversion stack back to its original state.
|
| 11860 | |
|
| 11861 | |
In the rare case that it is necessary to write a macro that explicitly
|
| 11862 | |
outputs text to a different diversion, it is important to be aware of an
|
| 11863 | |
M4 limitation regarding diversions: text only goes to a diversion if it
|
| 11864 | |
is not part of argument collection. Therefore, any macro that changes
|
| 11865 | |
the current diversion cannot be used as an unquoted argument to another
|
| 11866 | |
macro, but must be expanded at the top level. The macro
|
| 11867 | |
@code{m4_expand} will diagnose any attempt to change diversions, since
|
| 11868 | |
it is generally useful only as an argument to another macro. The
|
| 11869 | |
following example shows what happens when diversion manipulation is
|
| 11870 | |
attempted within macro arguments:
|
| 11871 | |
|
| 11872 | |
@example
|
| 11873 | |
m4_do([normal text]
|
| 11874 | |
m4_divert_push([KILL])unwanted[]m4_divert_pop([KILL])
|
| 11875 | |
[m4_divert_push([KILL])discarded[]m4_divert_pop([KILL])])dnl
|
| 11876 | |
@result{}normal text
|
| 11877 | |
@result{}unwanted
|
| 11878 | |
@end example
|
| 11879 | |
|
| 11880 | |
@noindent
|
| 11881 | |
Notice that the unquoted text @code{unwanted} is output, even though it
|
| 11882 | |
was processed while the current diversion was @code{KILL}, because it
|
| 11883 | |
was collected as part of the argument to @code{m4_do}. However, the
|
| 11884 | |
text @code{discarded} disappeared as desired, because the diversion
|
| 11885 | |
changes were single-quoted, and were not expanded until the top-level
|
| 11886 | |
rescan of the output of @code{m4_do}.
|
| 11887 | |
|
| 11888 | |
To make diversion management easier, M4sugar uses the concept of named
|
| 11889 | |
diversions. Rather than using diversion numbers directly, it is nicer
|
| 11890 | |
to associate a name with each diversion. The diversion number associated
|
| 11891 | |
with a particular diversion name is an implementation detail, and a
|
| 11892 | |
syntax warning is issued if a diversion number is used instead of a
|
| 11893 | |
name. In general, you should not output text
|
| 11894 | |
to a named diversion until after calling the appropriate initialization
|
| 11895 | |
routine for your language (@code{m4_init}, @code{AS_INIT},
|
| 11896 | |
@code{AT_INIT}, @dots{}), although there are some exceptions documented
|
| 11897 | |
below.
|
| 11898 | |
|
| 11899 | |
M4sugar defines two named diversions.
|
| 11900 | |
@table @code
|
| 11901 | |
@item KILL
|
| 11902 | |
Text written to this diversion is discarded. This is the default
|
| 11903 | |
diversion once M4sugar is initialized.
|
| 11904 | |
@item GROW
|
| 11905 | |
This diversion is used behind the scenes by topological sorting macros,
|
| 11906 | |
such as @code{AC_REQUIRE}.
|
| 11907 | |
@end table
|
| 11908 | |
|
| 11909 | |
M4sh adds several more named diversions.
|
| 11910 | |
@table @code
|
| 11911 | |
@item BINSH
|
| 11912 | |
This diversion is reserved for the @samp{#!} interpreter line.
|
| 11913 | |
@item HEADER-REVISION
|
| 11914 | |
This diversion holds text from @code{AC_REVISION}.
|
| 11915 | |
@item HEADER-COMMENT
|
| 11916 | |
This diversion holds comments about the purpose of a file.
|
| 11917 | |
@item HEADER-COPYRIGHT
|
| 11918 | |
This diversion is managed by @code{AC_COPYRIGHT}.
|
| 11919 | |
@item M4SH-SANITIZE
|
| 11920 | |
This diversion contains M4sh sanitization code, used to ensure M4sh is
|
| 11921 | |
executing in a reasonable shell environment.
|
| 11922 | |
@item M4SH-INIT
|
| 11923 | |
This diversion contains M4sh initialization code, initializing variables
|
| 11924 | |
that are required by other M4sh macros.
|
| 11925 | |
@item BODY
|
| 11926 | |
This diversion contains the body of the shell code, and is the default
|
| 11927 | |
diversion once M4sh is initialized.
|
| 11928 | |
@end table
|
| 11929 | |
|
| 11930 | |
Autotest inherits diversions from M4sh, and changes the default
|
| 11931 | |
diversion from @code{BODY} back to @code{KILL}. It also adds several
|
| 11932 | |
more named diversions, with the following subset designed for developer
|
| 11933 | |
use.
|
| 11934 | |
@table @code
|
| 11935 | |
@item PREPARE_TESTS
|
| 11936 | |
This diversion contains initialization sequences which are executed
|
| 11937 | |
after @file{atconfig} and @file{atlocal}, and after all command line
|
| 11938 | |
arguments have been parsed, but prior to running any tests. It can be
|
| 11939 | |
used to set up state that is required across all tests. This diversion
|
| 11940 | |
will work even before @code{AT_INIT}.
|
| 11941 | |
@end table
|
| 11942 | |
|
| 11943 | |
Autoconf inherits diversions from M4sh, and adds the following named
|
| 11944 | |
diversions which developers can utilize.
|
| 11945 | |
@table @code
|
| 11946 | |
@item DEFAULTS
|
| 11947 | |
This diversion contains shell variable assignments to set defaults that
|
| 11948 | |
must be in place before arguments are parsed. This diversion is placed
|
| 11949 | |
early enough in @file{configure} that it is unsafe to expand any
|
| 11950 | |
autoconf macros into this diversion.
|
| 11951 | |
@item HELP_ENABLE
|
| 11952 | |
If @code{AC_PRESERVE_HELP_ORDER} was used, then text placed in this
|
| 11953 | |
diversion will be included as part of a quoted here-doc providing all of
|
| 11954 | |
the @option{--help} output of @file{configure} related to options
|
| 11955 | |
created by @code{AC_ARG_WITH} and @code{AC_ARG_ENABLE}.
|
| 11956 | |
@item INIT_PREPARE
|
| 11957 | |
This diversion occurs after all command line options have been parsed,
|
| 11958 | |
but prior to the main body of the @file{configure} script. This
|
| 11959 | |
diversion is the last chance to insert shell code such as variable
|
| 11960 | |
assignments or shell function declarations that will used by the
|
| 11961 | |
expansion of other macros.
|
| 11962 | |
@end table
|
| 11963 | |
|
| 11964 | |
For now, the remaining named diversions of Autoconf, Autoheader, and
|
| 11965 | |
Autotest are not documented. In other words,
|
| 11966 | |
intentionally outputting text into an undocumented diversion is subject
|
| 11967 | |
to breakage in a future release of Autoconf.
|
| 11968 | |
|
| 11969 | |
@defmac m4_cleardivert (@var{diversion}@dots{})
|
| 11970 | |
@msindex{cleardivert}
|
| 11971 | |
Permanently discard any text that has been diverted into
|
| 11972 | |
@var{diversion}.
|
| 11973 | |
@end defmac
|
| 11974 | |
|
| 11975 | |
@defmac m4_divert_once (@var{diversion}, @ovar{content})
|
| 11976 | |
@msindex{divert_once}
|
| 11977 | |
Similar to @code{m4_divert_text}, except that @var{content} is only
|
| 11978 | |
output to @var{diversion} if this is the first time that
|
| 11979 | |
@code{m4_divert_once} has been called with its particular arguments.
|
| 11980 | |
@end defmac
|
| 11981 | |
|
| 11982 | |
@defmac m4_divert_pop (@ovar{diversion})
|
| 11983 | |
@msindex{divert_pop}
|
| 11984 | |
If provided, check that the current diversion is indeed @var{diversion}.
|
| 11985 | |
Then change to the diversion located earlier on the stack, giving an
|
| 11986 | |
error if an attempt is made to pop beyond the initial m4sugar diversion
|
| 11987 | |
of @code{KILL}.
|
| 11988 | |
@end defmac
|
| 11989 | |
|
| 11990 | |
@defmac m4_divert_push (@var{diversion})
|
| 11991 | |
@msindex{divert_push}
|
| 11992 | |
Remember the former diversion on the diversion stack, and output
|
| 11993 | |
subsequent text into @var{diversion}. M4sugar maintains a diversion
|
| 11994 | |
stack, and issues an error if there is not a matching pop for every
|
| 11995 | |
push.
|
| 11996 | |
@end defmac
|
| 11997 | |
|
| 11998 | |
@defmac m4_divert_text (@var{diversion}, @ovar{content})
|
| 11999 | |
@msindex{divert_text}
|
| 12000 | |
Output @var{content} and a newline into @var{diversion}, without
|
| 12001 | |
affecting the current diversion. Shorthand for:
|
| 12002 | |
@example
|
| 12003 | |
m4_divert_push([@var{diversion}])@var{content}
|
| 12004 | |
m4_divert_pop([@var{diversion}])dnl
|
| 12005 | |
@end example
|
| 12006 | |
|
| 12007 | |
One use of @code{m4_divert_text} is to develop two related macros, where
|
| 12008 | |
macro @samp{MY_A} does the work, but adjusts what work is performed
|
| 12009 | |
based on whether the optional macro @samp{MY_B} has also been expanded.
|
| 12010 | |
Of course, it is possible to use @code{AC_BEFORE} within @code{MY_A} to
|
| 12011 | |
require that @samp{MY_B} occurs first, if it occurs at all. But this
|
| 12012 | |
imposes an ordering restriction on the user; it would be nicer if macros
|
| 12013 | |
@samp{MY_A} and @samp{MY_B} can be invoked in either order. The trick
|
| 12014 | |
is to let @samp{MY_B} leave a breadcrumb in an early diversion, which
|
| 12015 | |
@samp{MY_A} can then use to determine whether @samp{MY_B} has been
|
| 12016 | |
expanded.
|
| 12017 | |
|
| 12018 | |
@example
|
| 12019 | |
AC_DEFUN([MY_A],
|
| 12020 | |
[# various actions
|
| 12021 | |
if test -n "$b_was_used"; then
|
| 12022 | |
# extra action
|
| 12023 | |
fi])
|
| 12024 | |
AC_DEFUN([MY_B],
|
| 12025 | |
[AC_REQUIRE([MY_A])dnl
|
| 12026 | |
m4_divert_text([INIT_PREPARE], [b_was_used=true])])
|
| 12027 | |
@end example
|
| 12028 | |
|
| 12029 | |
@end defmac
|
| 12030 | |
|
| 12031 | |
@defmac m4_init
|
| 12032 | |
@msindex{init}
|
| 12033 | |
Initialize the M4sugar environment, setting up the default named
|
| 12034 | |
diversion to be @code{KILL}.
|
| 12035 | |
@end defmac
|
| 12036 | |
|
| 12037 | |
@node Conditional constructs
|
| 12038 | |
@subsection Conditional constructs
|
| 12039 | |
|
| 12040 | |
The following macros provide additional conditional constructs as
|
| 12041 | |
convenience wrappers around @code{m4_if}.
|
| 12042 | |
|
| 12043 | |
@defmac m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @
|
| 12044 | |
@ovar{regex-2}, @ovar{value-2}, @dots{}, @ovar{default})
|
| 12045 | |
@msindex{bmatch}
|
| 12046 | |
The string @var{string} is repeatedly compared against a series of
|
| 12047 | |
@var{regex} arguments; if a match is found, the expansion is the
|
| 12048 | |
corresponding @var{value}, otherwise, the macro moves on to the next
|
| 12049 | |
@var{regex}. If no @var{regex} match, then the result is the optional
|
| 12050 | |
@var{default}, or nothing.
|
| 12051 | |
@end defmac
|
| 12052 | |
|
| 12053 | |
@defmac m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @
|
| 12054 | |
@ovar{regex-2}, @ovar{subst-2}, @dots{})
|
| 12055 | |
@msindex{bpatsubsts}
|
| 12056 | |
The string @var{string} is altered by @var{regex-1} and @var{subst-1},
|
| 12057 | |
as if by:
|
| 12058 | |
@example
|
| 12059 | |
m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}])
|
| 12060 | |
@end example
|
| 12061 | |
|
| 12062 | |
@noindent
|
| 12063 | |
The result of the substitution is then passed through the next set of
|
| 12064 | |
@var{regex} and @var{subst}, and so forth. An empty @var{subst} implies
|
| 12065 | |
deletion of any matched portions in the current string. Note that this
|
| 12066 | |
macro over-quotes @var{string}; this behavior is intentional, so that
|
| 12067 | |
the result of each step of the recursion remains as a quoted string.
|
| 12068 | |
However, it means that anchors (@samp{^} and @samp{$} in the @var{regex}
|
| 12069 | |
will line up with the extra quotations, and not the characters of the
|
| 12070 | |
original string. The overquoting is removed after the final
|
| 12071 | |
substitution.
|
| 12072 | |
@end defmac
|
| 12073 | |
|
| 12074 | |
@defmac m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @
|
| 12075 | |
@ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
|
| 12076 | |
@msindex{case}
|
| 12077 | |
Test @var{string} against multiple @var{value} possibilities, resulting
|
| 12078 | |
in the first @var{if-value} for a match, or in the optional
|
| 12079 | |
@var{default}. This is shorthand for:
|
| 12080 | |
@example
|
| 12081 | |
m4_if([@var{string}], [@var{value-1}], [@var{if-value-1}],
|
| 12082 | |
[@var{string}], [@var{value-2}], [@var{if-value-2}], @dots{},
|
| 12083 | |
[@var{default}])
|
| 12084 | |
@end example
|
| 12085 | |
@end defmac
|
| 12086 | |
|
| 12087 | |
@defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @
|
| 12088 | |
@ovar{test-2}, @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
|
| 12089 | |
@msindex{cond}
|
| 12090 | |
This macro was introduced in Autoconf 2.62. Similar to @code{m4_if},
|
| 12091 | |
except that each @var{test} is expanded only when it is encountered.
|
| 12092 | |
This is useful for short-circuiting expensive tests; while @code{m4_if}
|
| 12093 | |
requires all its strings to be expanded up front before doing
|
| 12094 | |
comparisons, @code{m4_cond} only expands a @var{test} when all earlier
|
| 12095 | |
tests have failed.
|
| 12096 | |
|
| 12097 | |
For an example, these two sequences give the same result, but in the
|
| 12098 | |
case where @samp{$1} does not contain a backslash, the @code{m4_cond}
|
| 12099 | |
version only expands @code{m4_index} once, instead of five times, for
|
| 12100 | |
faster computation if this is a common case for @samp{$1}. Notice that
|
| 12101 | |
every third argument is unquoted for @code{m4_if}, and quoted for
|
| 12102 | |
@code{m4_cond}:
|
| 12103 | |
|
| 12104 | |
@example
|
| 12105 | |
m4_if(m4_index([$1], [\]), [-1], [$2],
|
| 12106 | |
m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
|
| 12107 | |
m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
|
| 12108 | |
m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
|
| 12109 | |
m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
|
| 12110 | |
[$2])
|
| 12111 | |
m4_cond([m4_index([$1], [\])], [-1], [$2],
|
| 12112 | |
[m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
|
| 12113 | |
[m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
|
| 12114 | |
[m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
|
| 12115 | |
[m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
|
| 12116 | |
[$2])
|
| 12117 | |
@end example
|
| 12118 | |
@end defmac
|
| 12119 | |
|
| 12120 | |
@defmac m4_default (@var{expr-1}, @var{expr-2})
|
| 12121 | |
@defmacx m4_default_quoted (@var{expr-1}, @var{expr-2})
|
| 12122 | |
@defmacx m4_default_nblank (@var{expr-1}, @ovar{expr-2})
|
| 12123 | |
@defmacx m4_default_nblank_quoted (@var{expr-1}, @ovar{expr-2})
|
| 12124 | |
@msindex{default}
|
| 12125 | |
@msindex{default_quoted}
|
| 12126 | |
@msindex{default_nblank}
|
| 12127 | |
@msindex{default_nblank_quoted}
|
| 12128 | |
If @var{expr-1} contains text, use it. Otherwise, select @var{expr-2}.
|
| 12129 | |
@code{m4_default} expands the result, while @code{m4_default_quoted}
|
| 12130 | |
does not. Useful for providing a fixed default if the expression that
|
| 12131 | |
results in @var{expr-1} would otherwise be empty. The difference
|
| 12132 | |
between @code{m4_default} and @code{m4_default_nblank} is whether an
|
| 12133 | |
argument consisting of just blanks (space, tab, newline) is
|
| 12134 | |
significant. When using the expanding versions, note that an argument
|
| 12135 | |
may contain text but still expand to an empty string.
|
| 12136 | |
|
| 12137 | |
@example
|
| 12138 | |
m4_define([active], [ACTIVE])dnl
|
| 12139 | |
m4_define([empty], [])dnl
|
| 12140 | |
m4_define([demo1], [m4_default([$1], [$2])])dnl
|
| 12141 | |
m4_define([demo2], [m4_default_quoted([$1], [$2])])dnl
|
| 12142 | |
m4_define([demo3], [m4_default_nblank([$1], [$2])])dnl
|
| 12143 | |
m4_define([demo4], [m4_default_nblank_quoted([$1], [$2])])dnl
|
| 12144 | |
demo1([active], [default])
|
| 12145 | |
@result{}ACTIVE
|
| 12146 | |
demo1([], [active])
|
| 12147 | |
@result{}ACTIVE
|
| 12148 | |
demo1([empty], [text])
|
| 12149 | |
@result{}
|
| 12150 | |
-demo1([ ], [active])-
|
| 12151 | |
@result{}- -
|
| 12152 | |
demo2([active], [default])
|
| 12153 | |
@result{}active
|
| 12154 | |
demo2([], [active])
|
| 12155 | |
@result{}active
|
| 12156 | |
demo2([empty], [text])
|
| 12157 | |
@result{}empty
|
| 12158 | |
-demo2([ ], [active])-
|
| 12159 | |
@result{}- -
|
| 12160 | |
demo3([active], [default])
|
| 12161 | |
@result{}ACTIVE
|
| 12162 | |
demo3([], [active])
|
| 12163 | |
@result{}ACTIVE
|
| 12164 | |
demo3([empty], [text])
|
| 12165 | |
@result{}
|
| 12166 | |
-demo3([ ], [active])-
|
| 12167 | |
@result{}-ACTIVE-
|
| 12168 | |
demo4([active], [default])
|
| 12169 | |
@result{}active
|
| 12170 | |
demo4([], [active])
|
| 12171 | |
@result{}active
|
| 12172 | |
demo4([empty], [text])
|
| 12173 | |
@result{}empty
|
| 12174 | |
-demo4([ ], [active])-
|
| 12175 | |
@result{}-active-
|
| 12176 | |
@end example
|
| 12177 | |
@end defmac
|
| 12178 | |
|
| 12179 | |
@defmac m4_define_default (@var{macro}, @ovar{default-definition})
|
| 12180 | |
@msindex{define_default}
|
| 12181 | |
If @var{macro} does not already have a definition, then define it to
|
| 12182 | |
@var{default-definition}.
|
| 12183 | |
@end defmac
|
| 12184 | |
|
| 12185 | |
@defmac m4_ifblank (@var{cond}, @ovar{if-blank}, @ovar{if-text})
|
| 12186 | |
@defmacx m4_ifnblank (@var{cond}, @ovar{if-text}, @ovar{if-blank})
|
| 12187 | |
@msindex{ifblank}
|
| 12188 | |
@msindex{ifnblank}
|
| 12189 | |
If @var{cond} is empty or consists only of blanks (space, tab, newline),
|
| 12190 | |
then expand @var{if-blank}; otherwise, expand @var{if-text}. Two
|
| 12191 | |
variants exist, in order to make it easier to select the correct logical
|
| 12192 | |
sense when using only two parameters. Note that this is more efficient
|
| 12193 | |
than the equivalent behavior of:
|
| 12194 | |
@example
|
| 12195 | |
m4_ifval(m4_normalize([@var{cond}]), @var{if-text}, @var{if-blank})
|
| 12196 | |
@end example
|
| 12197 | |
@end defmac
|
| 12198 | |
|
| 12199 | |
@defmac m4_ifndef (@var{macro}, @var{if-not-defined}, @ovar{if-defined})
|
| 12200 | |
@msindex{ifndef}
|
| 12201 | |
This is shorthand for:
|
| 12202 | |
@example
|
| 12203 | |
m4_ifdef([@var{macro}], [@var{if-defined}], [@var{if-not-defined}])
|
| 12204 | |
@end example
|
| 12205 | |
@end defmac
|
| 12206 | |
|
| 12207 | |
@defmac m4_ifset (@var{macro}, @ovar{if-true}, @ovar{if-false})
|
| 12208 | |
@msindex{ifset}
|
| 12209 | |
If @var{macro} is undefined, or is defined as the empty string, expand
|
| 12210 | |
to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to:
|
| 12211 | |
@example
|
| 12212 | |
m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}])
|
| 12213 | |
@end example
|
| 12214 | |
@noindent
|
| 12215 | |
except that it is not an error if @var{macro} is undefined.
|
| 12216 | |
@end defmac
|
| 12217 | |
|
| 12218 | |
@defmac m4_ifval (@var{cond}, @ovar{if-true}, @ovar{if-false})
|
| 12219 | |
@msindex{ifval}
|
| 12220 | |
Expands to @var{if-true} if @var{cond} is not empty, otherwise to
|
| 12221 | |
@var{if-false}. This is shorthand for:
|
| 12222 | |
@example
|
| 12223 | |
m4_if([@var{cond}], [], [@var{if-false}], [@var{if-true}])
|
| 12224 | |
@end example
|
| 12225 | |
@end defmac
|
| 12226 | |
|
| 12227 | |
@defmac m4_ifvaln (@var{cond}, @ovar{if-true}, @ovar{if-false})
|
| 12228 | |
@msindex{ifvaln}
|
| 12229 | |
Similar to @code{m4_ifval}, except guarantee that a newline is present
|
| 12230 | |
after any non-empty expansion. Often followed by @code{dnl}.
|
| 12231 | |
@end defmac
|
| 12232 | |
|
| 12233 | |
@defmac m4_n (@var{text})
|
| 12234 | |
@msindex{n}
|
| 12235 | |
Expand to @var{text}, and add a newline if @var{text} is not empty.
|
| 12236 | |
Often followed by @code{dnl}.
|
| 12237 | |
@end defmac
|
| 12238 | |
|
| 12239 | |
|
| 12240 | |
@node Looping constructs
|
| 12241 | |
@subsection Looping constructs
|
| 12242 | |
|
| 12243 | |
The following macros are useful in implementing recursive algorithms in
|
| 12244 | |
M4, including loop operations. An M4 list is formed by quoting a list
|
| 12245 | |
of quoted elements; generally the lists are comma-separated, although
|
| 12246 | |
@code{m4_foreach_w} is whitespace-separated. For example, the list
|
| 12247 | |
@samp{[[a], [b,c]]} contains two elements: @samp{[a]} and @samp{[b,c]}.
|
| 12248 | |
It is common to see lists with unquoted elements when those elements are
|
| 12249 | |
not likely to be macro names, as in @samp{[fputc_unlocked,
|
| 12250 | |
fgetc_unlocked]}.
|
| 12251 | |
|
| 12252 | |
Although not generally recommended, it is possible for quoted lists to
|
| 12253 | |
have side effects; all side effects are expanded only once, and prior to
|
| 12254 | |
visiting any list element. On the other hand, the fact that unquoted
|
| 12255 | |
macros are expanded exactly once means that macros without side effects
|
| 12256 | |
can be used to generate lists. For example,
|
| 12257 | |
|
| 12258 | |
@example
|
| 12259 | |
m4_foreach([i], [[1], [2], [3]m4_errprintn([hi])], [i])
|
| 12260 | |
@error{}hi
|
| 12261 | |
@result{}123
|
| 12262 | |
m4_define([list], [[1], [2], [3]])
|
| 12263 | |
@result{}
|
| 12264 | |
m4_foreach([i], [list], [i])
|
| 12265 | |
@result{}123
|
| 12266 | |
@end example
|
| 12267 | |
|
| 12268 | |
@defmac m4_argn (@var{n}, @ovar{arg}@dots{})
|
| 12269 | |
@msindex{argn}
|
| 12270 | |
Extracts argument @var{n} (larger than 0) from the remaining arguments.
|
| 12271 | |
If there are too few arguments, the empty string is used. For any
|
| 12272 | |
@var{n} besides 1, this is more efficient than the similar
|
| 12273 | |
@samp{m4_car(m4_shiftn([@var{n}], [], [@var{arg}@dots{}]))}.
|
| 12274 | |
@end defmac
|
| 12275 | |
|
| 12276 | |
@defmac m4_car (@var{arg}@dots{})
|
| 12277 | |
@msindex{car}
|
| 12278 | |
Expands to the quoted first @var{arg}. Can be used with @code{m4_cdr}
|
| 12279 | |
to recursively iterate
|
| 12280 | |
through a list. Generally, when using quoted lists of quoted elements,
|
| 12281 | |
@code{m4_car} should be called without any extra quotes.
|
| 12282 | |
@end defmac
|
| 12283 | |
|
| 12284 | |
@defmac m4_cdr (@var{arg}@dots{})
|
| 12285 | |
@msindex{cdr}
|
| 12286 | |
Expands to a quoted list of all but the first @var{arg}, or the empty
|
| 12287 | |
string if there was only one argument. Generally, when using quoted
|
| 12288 | |
lists of quoted elements, @code{m4_cdr} should be called without any
|
| 12289 | |
extra quotes.
|
| 12290 | |
|
| 12291 | |
For example, this is a simple implementation of @code{m4_map}; note how
|
| 12292 | |
each iteration checks for the end of recursion, then merely applies the
|
| 12293 | |
first argument to the first element of the list, then repeats with the
|
| 12294 | |
rest of the list. (The actual implementation in M4sugar is a bit more
|
| 12295 | |
involved, to gain some speed and share code with @code{m4_map_sep}, and
|
| 12296 | |
also to avoid expanding side effects in @samp{$2} twice).
|
| 12297 | |
@example
|
| 12298 | |
m4_define([m4_map], [m4_ifval([$2],
|
| 12299 | |
[m4_apply([$1], m4_car($2))[]$0([$1], m4_cdr($2))])])dnl
|
| 12300 | |
m4_map([ m4_eval], [[[1]], [[1+1]], [[10],[16]]])
|
| 12301 | |
@result{} 1 2 a
|
| 12302 | |
@end example
|
| 12303 | |
@end defmac
|
| 12304 | |
|
| 12305 | |
@defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @
|
| 12306 | |
@var{expression})
|
| 12307 | |
@msindex{for}
|
| 12308 | |
Loop over the numeric values between @var{first} and @var{last}
|
| 12309 | |
including bounds by increments of @var{step}. For each iteration,
|
| 12310 | |
expand @var{expression} with the numeric value assigned to @var{var}.
|
| 12311 | |
If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
|
| 12312 | |
on the order of the limits. If given, @var{step} has to match this
|
| 12313 | |
order. The number of iterations is determined independently from
|
| 12314 | |
definition of @var{var}; iteration cannot be short-circuited or
|
| 12315 | |
lengthened by modifying @var{var} from within @var{expression}.
|
| 12316 | |
@end defmac
|
| 12317 | |
|
| 12318 | |
@defmac m4_foreach (@var{var}, @var{list}, @var{expression})
|
| 12319 | |
@msindex{foreach}
|
| 12320 | |
Loop over the comma-separated M4 list @var{list}, assigning each value
|
| 12321 | |
to @var{var}, and expand @var{expression}. The following example
|
| 12322 | |
outputs two lines:
|
| 12323 | |
|
| 12324 | |
@example
|
| 12325 | |
m4_foreach([myvar], [[foo], [bar, baz]],
|
| 12326 | |
[echo myvar
|
| 12327 | |
])dnl
|
| 12328 | |
@result{}echo foo
|
| 12329 | |
@result{}echo bar, baz
|
| 12330 | |
@end example
|
| 12331 | |
|
| 12332 | |
Note that for some forms of @var{expression}, it may be faster to use
|
| 12333 | |
@code{m4_map_args}.
|
| 12334 | |
@end defmac
|
| 12335 | |
|
| 12336 | |
@anchor{m4_foreach_w}
|
| 12337 | |
@defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
|
| 12338 | |
@msindex{foreach_w}
|
| 12339 | |
Loop over the white-space-separated list @var{list}, assigning each value
|
| 12340 | |
to @var{var}, and expand @var{expression}. If @var{var} is only
|
| 12341 | |
referenced once in @var{expression}, it is more efficient to use
|
| 12342 | |
@code{m4_map_args_w}.
|
| 12343 | |
|
| 12344 | |
The deprecated macro @code{AC_FOREACH} is an alias of
|
| 12345 | |
@code{m4_foreach_w}.
|
| 12346 | |
@end defmac
|
| 12347 | |
|
| 12348 | |
@defmac m4_map (@var{macro}, @var{list})
|
| 12349 | |
@defmacx m4_mapall (@var{macro}, @var{list})
|
| 12350 | |
@defmacx m4_map_sep (@var{macro}, @var{separator}, @var{list})
|
| 12351 | |
@defmacx m4_mapall_sep (@var{macro}, @var{separator}, @var{list})
|
| 12352 | |
@msindex{map}
|
| 12353 | |
@msindex{mapall}
|
| 12354 | |
@msindex{map_sep}
|
| 12355 | |
@msindex{mapall_sep}
|
| 12356 | |
Loop over the comma separated quoted list of argument descriptions in
|
| 12357 | |
@var{list}, and invoke @var{macro} with the arguments. An argument
|
| 12358 | |
description is in turn a comma-separated quoted list of quoted elements,
|
| 12359 | |
suitable for @code{m4_apply}. The macros @code{m4_map} and
|
| 12360 | |
@code{m4_map_sep} ignore empty argument descriptions, while
|
| 12361 | |
@code{m4_mapall} and @code{m4_mapall_sep} invoke @var{macro} with no
|
| 12362 | |
arguments. The macros @code{m4_map_sep} and @code{m4_mapall_sep}
|
| 12363 | |
additionally expand @var{separator} between invocations of @var{macro}.
|
| 12364 | |
|
| 12365 | |
Note that @var{separator} is expanded, unlike in @code{m4_join}. When
|
| 12366 | |
separating output with commas, this means that the map result can be
|
| 12367 | |
used as a series of arguments, by using a single-quoted comma as
|
| 12368 | |
@var{separator}, or as a single string, by using a double-quoted comma.
|
| 12369 | |
|
| 12370 | |
@example
|
| 12371 | |
m4_map([m4_count], [])
|
| 12372 | |
@result{}
|
| 12373 | |
m4_map([ m4_count], [[],
|
| 12374 | |
[[1]],
|
| 12375 | |
[[1], [2]]])
|
| 12376 | |
@result{} 1 2
|
| 12377 | |
m4_mapall([ m4_count], [[],
|
| 12378 | |
[[1]],
|
| 12379 | |
[[1], [2]]])
|
| 12380 | |
@result{} 0 1 2
|
| 12381 | |
m4_map_sep([m4_eval], [,], [[[1+2]],
|
| 12382 | |
[[10], [16]]])
|
| 12383 | |
@result{}3,a
|
| 12384 | |
m4_map_sep([m4_echo], [,], [[[a]], [[b]]])
|
| 12385 | |
@result{}a,b
|
| 12386 | |
m4_count(m4_map_sep([m4_echo], [,], [[[a]], [[b]]]))
|
| 12387 | |
@result{}2
|
| 12388 | |
m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]])
|
| 12389 | |
@result{}a,b
|
| 12390 | |
m4_count(m4_map_sep([m4_echo], [[,]], [[[a]], [[b]]]))
|
| 12391 | |
@result{}1
|
| 12392 | |
@end example
|
| 12393 | |
@end defmac
|
| 12394 | |
|
| 12395 | |
@defmac m4_map_args (@var{macro}, @var{arg}@dots{})
|
| 12396 | |
@msindex{map_args}
|
| 12397 | |
Repeatedly invoke @var{macro} with each successive @var{arg} as its only
|
| 12398 | |
argument. In the following example, three solutions are presented with
|
| 12399 | |
the same expansion; the solution using @code{m4_map_args} is the most
|
| 12400 | |
efficient.
|
| 12401 | |
@example
|
| 12402 | |
m4_define([active], [ACTIVE])dnl
|
| 12403 | |
m4_foreach([var], [[plain], [active]], [ m4_echo(m4_defn([var]))])
|
| 12404 | |
@result{} plain active
|
| 12405 | |
m4_map([ m4_echo], [[[plain]], [[active]]])
|
| 12406 | |
@result{} plain active
|
| 12407 | |
m4_map_args([ m4_echo], [plain], [active])
|
| 12408 | |
@result{} plain active
|
| 12409 | |
@end example
|
| 12410 | |
|
| 12411 | |
In cases where it is useful to operate on additional parameters besides
|
| 12412 | |
the list elements, the macro @code{m4_curry} can be used in @var{macro}
|
| 12413 | |
to supply the argument currying necessary to generate the desired
|
| 12414 | |
argument list. In the following example, @code{list_add_n} is more
|
| 12415 | |
efficient than @code{list_add_x}. On the other hand, using
|
| 12416 | |
@code{m4_map_args_sep} can be even more efficient.
|
| 12417 | |
|
| 12418 | |
@example
|
| 12419 | |
m4_define([list], [[1], [2], [3]])dnl
|
| 12420 | |
m4_define([add], [m4_eval(([$1]) + ([$2]))])dnl
|
| 12421 | |
dnl list_add_n(N, ARG...)
|
| 12422 | |
dnl Output a list consisting of each ARG added to N
|
| 12423 | |
m4_define([list_add_n],
|
| 12424 | |
[m4_shift(m4_map_args([,m4_curry([add], [$1])], m4_shift($@@)))])dnl
|
| 12425 | |
list_add_n([1], list)
|
| 12426 | |
@result{}2,3,4
|
| 12427 | |
list_add_n([2], list)
|
| 12428 | |
@result{}3,4,5
|
| 12429 | |
m4_define([list_add_x],
|
| 12430 | |
[m4_shift(m4_foreach([var], m4_dquote(m4_shift($@@)),
|
| 12431 | |
[,add([$1],m4_defn([var]))]))])dnl
|
| 12432 | |
list_add_x([1], list)
|
| 12433 | |
@result{}2,3,4
|
| 12434 | |
@end example
|
| 12435 | |
@end defmac
|
| 12436 | |
|
| 12437 | |
@defmac m4_map_args_pair (@var{macro}, @dvar{macro-end, macro}, @
|
| 12438 | |
@var{arg}@dots{})
|
| 12439 | |
@msindex{map_args_pair}
|
| 12440 | |
For every pair of arguments @var{arg}, invoke @var{macro} with two
|
| 12441 | |
arguments. If there is an odd number of arguments, invoke
|
| 12442 | |
@var{macro-end}, which defaults to @var{macro}, with the remaining
|
| 12443 | |
argument.
|
| 12444 | |
|
| 12445 | |
@example
|
| 12446 | |
m4_map_args_pair([, m4_reverse], [], [1], [2], [3])
|
| 12447 | |
@result{}, 2, 1, 3
|
| 12448 | |
m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3])
|
| 12449 | |
@result{}, 2, 1, [3]
|
| 12450 | |
m4_map_args_pair([, m4_reverse], [, m4_dquote], [1], [2], [3], [4])
|
| 12451 | |
@result{}, 2, 1, 4, 3
|
| 12452 | |
@end example
|
| 12453 | |
@end defmac
|
| 12454 | |
|
| 12455 | |
@defmac m4_map_args_sep (@ovar{pre}, @ovar{post}, @ovar{sep}, @var{arg}@dots{})
|
| 12456 | |
@msindex{map_args_sep}
|
| 12457 | |
Expand the sequence @code{@var{pre}[@var{arg}]@var{post}} for each
|
| 12458 | |
argument, additionally expanding @var{sep} between arguments. One
|
| 12459 | |
common use of this macro is constructing a macro call, where the opening
|
| 12460 | |
and closing parentheses are split between @var{pre} and @var{post}; in
|
| 12461 | |
particular, @code{m4_map_args([@var{macro}], [@var{arg}])} is equivalent
|
| 12462 | |
to @code{m4_map_args_sep([@var{macro}(], [)], [], [@var{arg}])}. This
|
| 12463 | |
macro provides the most efficient means for iterating over an arbitrary
|
| 12464 | |
list of arguments, particularly when repeatedly constructing a macro
|
| 12465 | |
call with more arguments than @var{arg}.
|
| 12466 | |
@end defmac
|
| 12467 | |
|
| 12468 | |
@defmac m4_map_args_w (@var{string}, @ovar{pre}, @ovar{post}, @ovar{sep})
|
| 12469 | |
@msindex{map_args_w}
|
| 12470 | |
Expand the sequence @code{@var{pre}[word]@var{post}} for each word in
|
| 12471 | |
the whitespace-separated @var{string}, additionally expanding @var{sep}
|
| 12472 | |
between words. This macro provides the most efficient means for
|
| 12473 | |
iterating over a whitespace-separated string. In particular,
|
| 12474 | |
@code{m4_map_args_w([@var{string}], [@var{action}(], [)])} is more
|
| 12475 | |
efficient than @code{m4_foreach_w([var], [@var{string}],
|
| 12476 | |
[@var{action}(m4_defn([var]))])}.
|
| 12477 | |
@end defmac
|
| 12478 | |
|
| 12479 | |
@defmac m4_shiftn (@var{count}, @dots{})
|
| 12480 | |
@defmacx m4_shift2 (@dots{})
|
| 12481 | |
@defmacx m4_shift3 (@dots{})
|
| 12482 | |
@msindex{shift2}
|
| 12483 | |
@msindex{shift3}
|
| 12484 | |
@msindex{shiftn}
|
| 12485 | |
@code{m4_shiftn} performs @var{count} iterations of @code{m4_shift},
|
| 12486 | |
along with validation that enough arguments were passed in to match the
|
| 12487 | |
shift count, and that the count is positive. @code{m4_shift2} and
|
| 12488 | |
@code{m4_shift3} are specializations
|
| 12489 | |
of @code{m4_shiftn}, introduced in Autoconf 2.62, and are more efficient
|
| 12490 | |
for two and three shifts, respectively.
|
| 12491 | |
@end defmac
|
| 12492 | |
|
| 12493 | |
@defmac m4_stack_foreach (@var{macro}, @var{action})
|
| 12494 | |
@defmacx m4_stack_foreach_lifo (@var{macro}, @var{action})
|
| 12495 | |
@msindex{stack_foreach}
|
| 12496 | |
@msindex{stack_foreach_lifo}
|
| 12497 | |
For each of the @code{m4_pushdef} definitions of @var{macro}, expand
|
| 12498 | |
@var{action} with the single argument of a definition of @var{macro}.
|
| 12499 | |
@code{m4_stack_foreach} starts with the oldest definition, while
|
| 12500 | |
@code{m4_stack_foreach_lifo} starts with the current definition.
|
| 12501 | |
@var{action} should not push or pop definitions of @var{macro}, nor is
|
| 12502 | |
there any guarantee that the current definition of @var{macro} matches
|
| 12503 | |
the argument that was passed to @var{action}. The macro @code{m4_curry}
|
| 12504 | |
can be used if @var{action} needs more than one argument, although in
|
| 12505 | |
that case it is more efficient to use @var{m4_stack_foreach_sep}.
|
| 12506 | |
|
| 12507 | |
Due to technical limitations, there are a few low-level m4sugar
|
| 12508 | |
functions, such as @code{m4_pushdef}, that cannot be used as the
|
| 12509 | |
@var{macro} argument.
|
| 12510 | |
|
| 12511 | |
@example
|
| 12512 | |
m4_pushdef([a], [1])m4_pushdef([a], [2])dnl
|
| 12513 | |
m4_stack_foreach([a], [ m4_incr])
|
| 12514 | |
@result{} 2 3
|
| 12515 | |
m4_stack_foreach_lifo([a], [ m4_curry([m4_substr], [abcd])])
|
| 12516 | |
@result{} cd bcd
|
| 12517 | |
@end example
|
| 12518 | |
@end defmac
|
| 12519 | |
|
| 12520 | |
@defmac m4_stack_foreach_sep (@var{macro}, @ovar{pre}, @ovar{post}, @ovar{sep})
|
| 12521 | |
@defmacx m4_stack_foreach_sep_lifo (@var{macro}, @ovar{pre}, @ovar{post}, @
|
| 12522 | |
@ovar{sep})
|
| 12523 | |
@msindex{stack_foreach_sep}
|
| 12524 | |
@msindex{stack_foreach_sep_lifo}
|
| 12525 | |
Expand the sequence @code{@var{pre}[definition]@var{post}} for each
|
| 12526 | |
@code{m4_pushdef} definition of @var{macro}, additionally expanding
|
| 12527 | |
@var{sep} between definitions. @code{m4_stack_foreach_sep} visits the
|
| 12528 | |
oldest definition first, while @code{m4_stack_foreach_sep_lifo} visits
|
| 12529 | |
the current definition first. This macro provides the most efficient
|
| 12530 | |
means for iterating over a pushdef stack. In particular,
|
| 12531 | |
@code{m4_stack_foreach([@var{macro}], [@var{action}])} is short for
|
| 12532 | |
@code{m4_stack_foreach_sep([@var{macro}], [@var{action}(], [)])}.
|
| 12533 | |
@end defmac
|
| 12534 | |
|
| 12535 | |
@node Evaluation Macros
|
| 12536 | |
@subsection Evaluation Macros
|
| 12537 | |
|
| 12538 | |
The following macros give some control over the order of the evaluation
|
| 12539 | |
by adding or removing levels of quotes.
|
| 12540 | |
|
| 12541 | |
@defmac m4_apply (@var{macro}, @var{list})
|
| 12542 | |
@msindex{apply}
|
| 12543 | |
Apply the elements of the quoted, comma-separated @var{list} as the
|
| 12544 | |
arguments to @var{macro}. If @var{list} is empty, invoke @var{macro}
|
| 12545 | |
without arguments. Note the difference between @code{m4_indir}, which
|
| 12546 | |
expects its first argument to be a macro name but can use names that are
|
| 12547 | |
otherwise invalid, and @code{m4_apply}, where @var{macro} can contain
|
| 12548 | |
other text, but must end in a valid macro name.
|
| 12549 | |
@example
|
| 12550 | |
m4_apply([m4_count], [])
|
| 12551 | |
@result{}0
|
| 12552 | |
m4_apply([m4_count], [[]])
|
| 12553 | |
@result{}1
|
| 12554 | |
m4_apply([m4_count], [[1], [2]])
|
| 12555 | |
@result{}2
|
| 12556 | |
m4_apply([m4_join], [[|], [1], [2]])
|
| 12557 | |
@result{}1|2
|
| 12558 | |
@end example
|
| 12559 | |
@end defmac
|
| 12560 | |
|
| 12561 | |
@defmac m4_count (@var{arg}, @dots{})
|
| 12562 | |
@msindex{count}
|
| 12563 | |
This macro returns the decimal count of the number of arguments it was
|
| 12564 | |
passed.
|
| 12565 | |
@end defmac
|
| 12566 | |
|
| 12567 | |
@defmac m4_curry (@var{macro}, @var{arg}@dots{})
|
| 12568 | |
@msindex{curry}
|
| 12569 | |
This macro performs argument currying. The expansion of this macro is
|
| 12570 | |
another macro name that expects exactly one argument; that argument is
|
| 12571 | |
then appended to the @var{arg} list, and then @var{macro} is expanded
|
| 12572 | |
with the resulting argument list.
|
| 12573 | |
|
| 12574 | |
@example
|
| 12575 | |
m4_curry([m4_curry], [m4_reverse], [1])([2])([3])
|
| 12576 | |
@result{}3, 2, 1
|
| 12577 | |
@end example
|
| 12578 | |
|
| 12579 | |
Unfortunately, due to a limitation in M4 1.4.x, it is not possible to
|
| 12580 | |
pass the definition of a builtin macro as the argument to the output of
|
| 12581 | |
@code{m4_curry}; the empty string is used instead of the builtin token.
|
| 12582 | |
This behavior is rectified by using M4 1.6 or newer.
|
| 12583 | |
@end defmac
|
| 12584 | |
|
| 12585 | |
@defmac m4_do (@var{arg}, @dots{})
|
| 12586 | |
@msindex{do}
|
| 12587 | |
This macro loops over its arguments and expands each @var{arg} in
|
| 12588 | |
sequence. Its main use is for readability; it allows the use of
|
| 12589 | |
indentation and fewer @code{dnl} to result in the same expansion. This
|
| 12590 | |
macro guarantees that no expansion will be concatenated with subsequent
|
| 12591 | |
text; to achieve full concatenation, use @code{m4_unquote(m4_join([],
|
| 12592 | |
@var{arg@dots{}}))}.
|
| 12593 | |
|
| 12594 | |
@example
|
| 12595 | |
m4_define([ab],[1])m4_define([bc],[2])m4_define([abc],[3])dnl
|
| 12596 | |
m4_do([a],[b])c
|
| 12597 | |
@result{}abc
|
| 12598 | |
m4_unquote(m4_join([],[a],[b]))c
|
| 12599 | |
@result{}3
|
| 12600 | |
m4_define([a],[A])m4_define([b],[B])m4_define([c],[C])dnl
|
| 12601 | |
m4_define([AB],[4])m4_define([BC],[5])m4_define([ABC],[6])dnl
|
| 12602 | |
m4_do([a],[b])c
|
| 12603 | |
@result{}ABC
|
| 12604 | |
m4_unquote(m4_join([],[a],[b]))c
|
| 12605 | |
@result{}3
|
| 12606 | |
@end example
|
| 12607 | |
@end defmac
|
| 12608 | |
|
| 12609 | |
@defmac m4_dquote (@var{arg}, @dots{})
|
| 12610 | |
@msindex{dquote}
|
| 12611 | |
Return the arguments as a quoted list of quoted arguments.
|
| 12612 | |
Conveniently, if there is just one @var{arg}, this effectively adds a
|
| 12613 | |
level of quoting.
|
| 12614 | |
@end defmac
|
| 12615 | |
|
| 12616 | |
@defmac m4_dquote_elt (@var{arg}, @dots{})
|
| 12617 | |
@msindex{dquote_elt}
|
| 12618 | |
Return the arguments as a series of double-quoted arguments. Whereas
|
| 12619 | |
@code{m4_dquote} returns a single argument, @code{m4_dquote_elt} returns
|
| 12620 | |
as many arguments as it was passed.
|
| 12621 | |
@end defmac
|
| 12622 | |
|
| 12623 | |
@defmac m4_echo (@var{arg}, @dots{})
|
| 12624 | |
@msindex{echo}
|
| 12625 | |
Return the arguments, with the same level of quoting. Other than
|
| 12626 | |
discarding whitespace after unquoted commas, this macro is a no-op.
|
| 12627 | |
@end defmac
|
| 12628 | |
|
| 12629 | |
@defmac m4_expand (@var{arg})
|
| 12630 | |
@msindex{expand}
|
| 12631 | |
Return the expansion of @var{arg} as a quoted string. Whereas
|
| 12632 | |
@code{m4_quote} is designed to collect expanded text into a single
|
| 12633 | |
argument, @code{m4_expand} is designed to perform one level of expansion
|
| 12634 | |
on quoted text. One distinction is in the treatment of whitespace
|
| 12635 | |
following a comma in the original @var{arg}. Any time multiple
|
| 12636 | |
arguments are collected into one with @code{m4_quote}, the M4 argument
|
| 12637 | |
collection rules discard the whitespace. However, with @code{m4_expand},
|
| 12638 | |
whitespace is preserved, even after the expansion of macros contained in
|
| 12639 | |
@var{arg}. Additionally, @code{m4_expand} is able to expand text that
|
| 12640 | |
would involve an unterminated comment, whereas expanding that same text
|
| 12641 | |
as the argument to @code{m4_quote} runs into difficulty in finding the
|
| 12642 | |
end of the argument. Since manipulating diversions during argument
|
| 12643 | |
collection is inherently unsafe, @code{m4_expand} issues an error if
|
| 12644 | |
@var{arg} attempts to change the current diversion (@pxref{Diversion
|
| 12645 | |
support}).
|
| 12646 | |
|
| 12647 | |
@example
|
| 12648 | |
m4_define([active], [ACT, IVE])dnl
|
| 12649 | |
m4_define([active2], [[ACT, IVE]])dnl
|
| 12650 | |
m4_quote(active, active)
|
| 12651 | |
@result{}ACT,IVE,ACT,IVE
|
| 12652 | |
m4_expand([active, active])
|
| 12653 | |
@result{}ACT, IVE, ACT, IVE
|
| 12654 | |
m4_quote(active2, active2)
|
| 12655 | |
@result{}ACT, IVE,ACT, IVE
|
| 12656 | |
m4_expand([active2, active2])
|
| 12657 | |
@result{}ACT, IVE, ACT, IVE
|
| 12658 | |
m4_expand([# m4_echo])
|
| 12659 | |
@result{}# m4_echo
|
| 12660 | |
m4_quote(# m4_echo)
|
| 12661 | |
)
|
| 12662 | |
@result{}# m4_echo)
|
| 12663 | |
@result{}
|
| 12664 | |
@end example
|
| 12665 | |
|
| 12666 | |
Note that @code{m4_expand} cannot handle an @var{arg} that expands to
|
| 12667 | |
literal unbalanced quotes, but that quadrigraphs can be used when
|
| 12668 | |
unbalanced output is necessary. Likewise, unbalanced parentheses should
|
| 12669 | |
be supplied with double quoting or a quadrigraph.
|
| 12670 | |
|
| 12671 | |
@example
|
| 12672 | |
m4_define([pattern], [[!@@<:@@]])dnl
|
| 12673 | |
m4_define([bar], [BAR])dnl
|
| 12674 | |
m4_expand([case $foo in
|
| 12675 | |
m4_defn([pattern])@@:@}@@ bar ;;
|
| 12676 | |
*[)] blah ;;
|
| 12677 | |
esac])
|
| 12678 | |
@result{}case $foo in
|
| 12679 | |
@result{} [![]) BAR ;;
|
| 12680 | |
@result{} *) blah ;;
|
| 12681 | |
@result{}esac
|
| 12682 | |
@end example
|
| 12683 | |
@end defmac
|
| 12684 | |
|
| 12685 | |
@defmac m4_ignore (@dots{})
|
| 12686 | |
@msindex{ignore}
|
| 12687 | |
This macro was introduced in Autoconf 2.62. Expands to nothing,
|
| 12688 | |
ignoring all of its arguments. By itself, this isn't very useful.
|
| 12689 | |
However, it can be used to conditionally ignore an arbitrary number of
|
| 12690 | |
arguments, by deciding which macro name to apply to a list of arguments.
|
| 12691 | |
@example
|
| 12692 | |
dnl foo outputs a message only if [debug] is defined.
|
| 12693 | |
m4_define([foo],
|
| 12694 | |
[m4_ifdef([debug],[AC_MSG_NOTICE],[m4_ignore])([debug message])])
|
| 12695 | |
@end example
|
| 12696 | |
|
| 12697 | |
Note that for earlier versions of Autoconf, the macro @code{__gnu__} can
|
| 12698 | |
serve the same purpose, although it is less readable.
|
| 12699 | |
@end defmac
|
| 12700 | |
|
| 12701 | |
@defmac m4_make_list (@var{arg}, @dots{})
|
| 12702 | |
@msindex{make_list}
|
| 12703 | |
This macro exists to aid debugging of M4sugar algorithms. Its net
|
| 12704 | |
effect is similar to @code{m4_dquote}---it produces a quoted list of
|
| 12705 | |
quoted arguments, for each @var{arg}. The difference is that this
|
| 12706 | |
version uses a comma-newline separator instead of just comma, to improve
|
| 12707 | |
readability of the list; with the result that it is less efficient than
|
| 12708 | |
@code{m4_dquote}.
|
| 12709 | |
@example
|
| 12710 | |
m4_define([zero],[0])m4_define([one],[1])m4_define([two],[2])dnl
|
| 12711 | |
m4_dquote(zero, [one], [[two]])
|
| 12712 | |
@result{}[0],[one],[[two]]
|
| 12713 | |
m4_make_list(zero, [one], [[two]])
|
| 12714 | |
@result{}[0],
|
| 12715 | |
@result{}[one],
|
| 12716 | |
@result{}[[two]]
|
| 12717 | |
m4_foreach([number], m4_dquote(zero, [one], [[two]]), [ number])
|
| 12718 | |
@result{} 0 1 two
|
| 12719 | |
m4_foreach([number], m4_make_list(zero, [one], [[two]]), [ number])
|
| 12720 | |
@result{} 0 1 two
|
| 12721 | |
@end example
|
| 12722 | |
@end defmac
|
| 12723 | |
|
| 12724 | |
@c m4_noquote is too dangerous to document - it invokes macros that
|
| 12725 | |
@c probably rely on @samp{[]} nested quoting for proper operation. The
|
| 12726 | |
@c user should generally prefer m4_unquote instead.
|
| 12727 | |
|
| 12728 | |
@defmac m4_quote (@var{arg}, @dots{})
|
| 12729 | |
@msindex{quote}
|
| 12730 | |
Return the arguments as a single entity, i.e., wrap them into a pair of
|
| 12731 | |
quotes. This effectively collapses multiple arguments into one,
|
| 12732 | |
although it loses whitespace after unquoted commas in the process.
|
| 12733 | |
@end defmac
|
| 12734 | |
|
| 12735 | |
@defmac m4_reverse (@var{arg}, @dots{})
|
| 12736 | |
@msindex{reverse}
|
| 12737 | |
Outputs each argument with the same level of quoting, but in reverse
|
| 12738 | |
order, and with space following each comma for readability.
|
| 12739 | |
|
| 12740 | |
@example
|
| 12741 | |
m4_define([active], [ACT,IVE])
|
| 12742 | |
@result{}
|
| 12743 | |
m4_reverse(active, [active])
|
| 12744 | |
@result{}active, IVE, ACT
|
| 12745 | |
@end example
|
| 12746 | |
@end defmac
|
| 12747 | |
|
| 12748 | |
@defmac m4_unquote (@var{arg}, @dots{})
|
| 12749 | |
@msindex{unquote}
|
| 12750 | |
This macro was introduced in Autoconf 2.62. Expand each argument,
|
| 12751 | |
separated by commas. For a single @var{arg}, this effectively removes a
|
| 12752 | |
layer of quoting, and @code{m4_unquote([@var{arg}])} is more efficient
|
| 12753 | |
than the equivalent @code{m4_do([@var{arg}])}. For multiple arguments,
|
| 12754 | |
this results in an unquoted list of expansions. This is commonly used
|
| 12755 | |
with @code{m4_split}, in order to convert a single quoted list into a
|
| 12756 | |
series of quoted elements.
|
| 12757 | |
@end defmac
|
| 12758 | |
|
| 12759 | |
The following example aims at emphasizing the difference between several
|
| 12760 | |
scenarios: not using these macros, using @code{m4_defn}, using
|
| 12761 | |
@code{m4_quote}, using @code{m4_dquote}, and using @code{m4_expand}.
|
| 12762 | |
|
| 12763 | |
@example
|
| 12764 | |
$ @kbd{cat example.m4}
|
| 12765 | |
dnl Overquote, so that quotes are visible.
|
| 12766 | |
m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
|
| 12767 | |
m4_define([a], [A])
|
| 12768 | |
m4_define([mkargs], [1, 2[,] 3])
|
| 12769 | |
m4_define([arg1], [[$1]])
|
| 12770 | |
m4_divert([0])dnl
|
| 12771 | |
show(a, b)
|
| 12772 | |
show([a, b])
|
| 12773 | |
show(m4_quote(a, b))
|
| 12774 | |
show(m4_dquote(a, b))
|
| 12775 | |
show(m4_expand([a, b]))
|
| 12776 | |
|
| 12777 | |
arg1(mkargs)
|
| 12778 | |
arg1([mkargs])
|
| 12779 | |
arg1(m4_defn([mkargs]))
|
| 12780 | |
arg1(m4_quote(mkargs))
|
| 12781 | |
arg1(m4_dquote(mkargs))
|
| 12782 | |
arg1(m4_expand([mkargs]))
|
| 12783 | |
$ @kbd{autom4te -l m4sugar example.m4}
|
| 12784 | |
$1 = A, $@@ = [A],[b]
|
| 12785 | |
$1 = a, b, $@@ = [a, b]
|
| 12786 | |
$1 = A,b, $@@ = [A,b]
|
| 12787 | |
$1 = [A],[b], $@@ = [[A],[b]]
|
| 12788 | |
$1 = A, b, $@@ = [A, b]
|
| 12789 | |
|
| 12790 | |
1
|
| 12791 | |
mkargs
|
| 12792 | |
1, 2[,] 3
|
| 12793 | |
1,2, 3
|
| 12794 | |
[1],[2, 3]
|
| 12795 | |
1, 2, 3
|
| 12796 | |
@end example
|
| 12797 | |
|
| 12798 | |
|
| 12799 | |
@node Text processing Macros
|
| 12800 | |
@subsection String manipulation in M4
|
| 12801 | |
|
| 12802 | |
The following macros may be used to manipulate strings in M4. Many of
|
| 12803 | |
the macros in this section intentionally result in quoted strings as
|
| 12804 | |
output, rather than subjecting the arguments to further expansions. As
|
| 12805 | |
a result, if you are manipulating text that contains active M4
|
| 12806 | |
characters, the arguments are passed with single quoting rather than
|
| 12807 | |
double.
|
| 12808 | |
|
| 12809 | |
@defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
|
| 12810 | |
@defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator} @
|
| 12811 | |
@ovar{if-uniq}, @ovar{if-duplicate})
|
| 12812 | |
@msindex{append}
|
| 12813 | |
@msindex{append_uniq}
|
| 12814 | |
Redefine @var{macro-name} to its former contents with @var{separator}
|
| 12815 | |
and @var{string} added at the end. If @var{macro-name} was undefined
|
| 12816 | |
before (but not if it was defined but empty), then no @var{separator} is
|
| 12817 | |
added. As of Autoconf 2.62, neither @var{string} nor @var{separator}
|
| 12818 | |
are expanded during this macro; instead, they are expanded when
|
| 12819 | |
@var{macro-name} is invoked.
|
| 12820 | |
|
| 12821 | |
@code{m4_append} can be used to grow strings, and @code{m4_append_uniq}
|
| 12822 | |
to grow strings without duplicating substrings. Additionally,
|
| 12823 | |
@code{m4_append_uniq} takes two optional parameters as of Autoconf 2.62;
|
| 12824 | |
@var{if-uniq} is expanded if @var{string} was appended, and
|
| 12825 | |
@var{if-duplicate} is expanded if @var{string} was already present.
|
| 12826 | |
Also, @code{m4_append_uniq} warns if @var{separator} is not empty, but
|
| 12827 | |
occurs within @var{string}, since that can lead to duplicates.
|
| 12828 | |
|
| 12829 | |
Note that @code{m4_append} can scale linearly in the length of the final
|
| 12830 | |
string, depending on the quality of the underlying M4 implementation,
|
| 12831 | |
while @code{m4_append_uniq} has an inherent quadratic scaling factor.
|
| 12832 | |
If an algorithm can tolerate duplicates in the final string, use the
|
| 12833 | |
former for speed. If duplicates must be avoided, consider using
|
| 12834 | |
@code{m4_set_add} instead (@pxref{Set manipulation Macros}).
|
| 12835 | |
|
| 12836 | |
@example
|
| 12837 | |
m4_define([active], [ACTIVE])dnl
|
| 12838 | |
m4_append([sentence], [This is an])dnl
|
| 12839 | |
m4_append([sentence], [ active ])dnl
|
| 12840 | |
m4_append([sentence], [symbol.])dnl
|
| 12841 | |
sentence
|
| 12842 | |
@result{}This is an ACTIVE symbol.
|
| 12843 | |
m4_undefine([active])dnl
|
| 12844 | |
@result{}This is an active symbol.
|
| 12845 | |
m4_append_uniq([list], [one], [, ], [new], [existing])
|
| 12846 | |
@result{}new
|
| 12847 | |
m4_append_uniq([list], [one], [, ], [new], [existing])
|
| 12848 | |
@result{}existing
|
| 12849 | |
m4_append_uniq([list], [two], [, ], [new], [existing])
|
| 12850 | |
@result{}new
|
| 12851 | |
m4_append_uniq([list], [three], [, ], [new], [existing])
|
| 12852 | |
@result{}new
|
| 12853 | |
m4_append_uniq([list], [two], [, ], [new], [existing])
|
| 12854 | |
@result{}existing
|
| 12855 | |
list
|
| 12856 | |
@result{}one, two, three
|
| 12857 | |
m4_dquote(list)
|
| 12858 | |
@result{}[one],[two],[three]
|
| 12859 | |
m4_append([list2], [one], [[, ]])dnl
|
| 12860 | |
m4_append_uniq([list2], [two], [[, ]])dnl
|
| 12861 | |
m4_append([list2], [three], [[, ]])dnl
|
| 12862 | |
list2
|
| 12863 | |
@result{}one, two, three
|
| 12864 | |
m4_dquote(list2)
|
| 12865 | |
@result{}[one, two, three]
|
| 12866 | |
@end example
|
| 12867 | |
@end defmac
|
| 12868 | |
|
| 12869 | |
@defmac m4_append_uniq_w (@var{macro-name}, @var{strings})
|
| 12870 | |
@msindex{append_uniq_w}
|
| 12871 | |
This macro was introduced in Autoconf 2.62. It is similar to
|
| 12872 | |
@code{m4_append_uniq}, but treats @var{strings} as a whitespace
|
| 12873 | |
separated list of words to append, and only appends unique words.
|
| 12874 | |
@var{macro-name} is updated with a single space between new words.
|
| 12875 | |
@example
|
| 12876 | |
m4_append_uniq_w([numbers], [1 1 2])dnl
|
| 12877 | |
m4_append_uniq_w([numbers], [ 2 3 ])dnl
|
| 12878 | |
numbers
|
| 12879 | |
@result{}1 2 3
|
| 12880 | |
@end example
|
| 12881 | |
@end defmac
|
| 12882 | |
|
| 12883 | |
@defmac m4_chomp (@var{string})
|
| 12884 | |
@defmacx m4_chomp_all (@var{string})
|
| 12885 | |
@msindex{chomp}
|
| 12886 | |
@msindex{chomp_all}
|
| 12887 | |
Output @var{string} in quotes, but without a trailing newline. The
|
| 12888 | |
macro @code{m4_chomp} is slightly faster, and removes at most one
|
| 12889 | |
newline; the macro @code{m4_chomp_all} removes all consecutive trailing
|
| 12890 | |
newlines. Unlike @code{m4_flatten}, embedded newlines are left intact,
|
| 12891 | |
and backslash does not influence the result.
|
| 12892 | |
@end defmac
|
| 12893 | |
|
| 12894 | |
@defmac m4_combine (@ovar{separator}, @var{prefix-list}, @ovar{infix}, @
|
| 12895 | |
@var{suffix-1}, @ovar{suffix-2}, @dots{})
|
| 12896 | |
@msindex{combine}
|
| 12897 | |
This macro produces a quoted string containing the pairwise combination
|
| 12898 | |
of every element of the quoted, comma-separated @var{prefix-list}, and
|
| 12899 | |
every element from the @var{suffix} arguments. Each pairwise
|
| 12900 | |
combination is joined with @var{infix} in the middle, and successive
|
| 12901 | |
pairs are joined by @var{separator}. No expansion occurs on any of the
|
| 12902 | |
arguments. No output occurs if either the @var{prefix} or @var{suffix}
|
| 12903 | |
list is empty, but the lists can contain empty elements.
|
| 12904 | |
@example
|
| 12905 | |
m4_define([a], [oops])dnl
|
| 12906 | |
m4_combine([, ], [[a], [b], [c]], [-], [1], [2], [3])
|
| 12907 | |
@result{}a-1, a-2, a-3, b-1, b-2, b-3, c-1, c-2, c-3
|
| 12908 | |
m4_combine([, ], [[a], [b]], [-])
|
| 12909 | |
@result{}
|
| 12910 | |
m4_combine([, ], [[a], [b]], [-], [])
|
| 12911 | |
@result{}a-, b-
|
| 12912 | |
m4_combine([, ], [], [-], [1], [2])
|
| 12913 | |
@result{}
|
| 12914 | |
m4_combine([, ], [[]], [-], [1], [2])
|
| 12915 | |
@result{}-1, -2
|
| 12916 | |
@end example
|
| 12917 | |
@end defmac
|
| 12918 | |
|
| 12919 | |
@defmac m4_escape (@var{string})
|
| 12920 | |
@msindex{escape}
|
| 12921 | |
Convert all instances of @samp{[}, @samp{]}, @samp{#}, and @samp{$}
|
| 12922 | |
within @var{string} into their respective quadrigraphs. The result is
|
| 12923 | |
still a quoted string.
|
| 12924 | |
@end defmac
|
| 12925 | |
|
| 12926 | |
@defmac m4_flatten (@var{string})
|
| 12927 | |
@msindex{flatten}
|
| 12928 | |
Flatten @var{string} into a single line. Delete all backslash-newline
|
| 12929 | |
pairs, and replace all remaining newlines with a space. The result is
|
| 12930 | |
still a quoted string.
|
| 12931 | |
@end defmac
|
| 12932 | |
|
| 12933 | |
@defmac m4_join (@ovar{separator}, @var{args}@dots{})
|
| 12934 | |
@defmacx m4_joinall (@ovar{separator}, @var{args}@dots{})
|
| 12935 | |
@msindex{join}
|
| 12936 | |
@msindex{joinall}
|
| 12937 | |
Concatenate each @var{arg}, separated by @var{separator}.
|
| 12938 | |
@code{joinall} uses every argument, while @code{join} omits empty
|
| 12939 | |
arguments so that there are no back-to-back separators in the output.
|
| 12940 | |
The result is a quoted string.
|
| 12941 | |
@example
|
| 12942 | |
m4_define([active], [ACTIVE])dnl
|
| 12943 | |
m4_join([|], [one], [], [active], [two])
|
| 12944 | |
@result{}one|active|two
|
| 12945 | |
m4_joinall([|], [one], [], [active], [two])
|
| 12946 | |
@result{}one||active|two
|
| 12947 | |
@end example
|
| 12948 | |
|
| 12949 | |
Note that if all you intend to do is join @var{args} with commas between
|
| 12950 | |
them, to form a quoted list suitable for @code{m4_foreach}, it is more
|
| 12951 | |
efficient to use @code{m4_dquote}.
|
| 12952 | |
@end defmac
|
| 12953 | |
|
| 12954 | |
@defmac m4_newline (@ovar{text})
|
| 12955 | |
@msindex{newline}
|
| 12956 | |
This macro was introduced in Autoconf 2.62, and expands to a newline,
|
| 12957 | |
followed by any @var{text}.
|
| 12958 | |
It is primarily useful for maintaining macro formatting, and ensuring
|
| 12959 | |
that M4 does not discard leading whitespace during argument collection.
|
| 12960 | |
@end defmac
|
| 12961 | |
|
| 12962 | |
@defmac m4_normalize (@var{string})
|
| 12963 | |
@msindex{normalize}
|
| 12964 | |
Remove leading and trailing spaces and tabs, sequences of
|
| 12965 | |
backslash-then-newline, and replace multiple spaces, tabs, and newlines
|
| 12966 | |
with a single space. This is a combination of @code{m4_flatten} and
|
| 12967 | |
@code{m4_strip}. To determine if @var{string} consists only of bytes
|
| 12968 | |
that would be removed by @code{m4_normalize}, you can use
|
| 12969 | |
@code{m4_ifblank}.
|
| 12970 | |
@end defmac
|
| 12971 | |
|
| 12972 | |
@defmac m4_re_escape (@var{string})
|
| 12973 | |
@msindex{re_escape}
|
| 12974 | |
Backslash-escape all characters in @var{string} that are active in
|
| 12975 | |
regexps.
|
| 12976 | |
@end defmac
|
| 12977 | |
|
| 12978 | |
@c We cannot use @dvar because the macro expansion mistreats backslashes.
|
| 12979 | |
@defmac m4_split (@var{string}, @r{[}@var{regexp} = @samp{[\t ]+}@r{]})
|
| 12980 | |
@msindex{split}
|
| 12981 | |
Split @var{string} into an M4 list of elements quoted by @samp{[} and
|
| 12982 | |
@samp{]}, while keeping white space at the beginning and at the end.
|
| 12983 | |
If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
|
| 12984 | |
If @var{string} is empty, the result is an empty list.
|
| 12985 | |
@end defmac
|
| 12986 | |
|
| 12987 | |
@defmac m4_strip (@var{string})
|
| 12988 | |
@msindex{strip}
|
| 12989 | |
Strip whitespace from @var{string}. Sequences of spaces and tabs are
|
| 12990 | |
reduced to a single space, then leading and trailing spaces are removed.
|
| 12991 | |
The result is still a quoted string. Note that this does not interfere
|
| 12992 | |
with newlines; if you want newlines stripped as well, consider
|
| 12993 | |
@code{m4_flatten}, or do it all at once with @code{m4_normalize}. To
|
| 12994 | |
quickly test if @var{string} has only whitespace, use @code{m4_ifblank}.
|
| 12995 | |
@end defmac
|
| 12996 | |
|
| 12997 | |
@defmac m4_text_box (@var{message}, @dvar{frame, -})
|
| 12998 | |
@msindex{text_box}
|
| 12999 | |
Add a text box around @var{message}, using @var{frame} as the border
|
| 13000 | |
character above and below the message. The @var{frame} argument must be
|
| 13001 | |
a single byte, and does not support quadrigraphs.
|
| 13002 | |
The frame correctly accounts for
|
| 13003 | |
the subsequent expansion of @var{message}. For example:
|
| 13004 | |
@example
|
| 13005 | |
m4_define([macro], [abc])dnl
|
| 13006 | |
m4_text_box([macro])
|
| 13007 | |
@result{}## --- ##
|
| 13008 | |
@result{}## abc ##
|
| 13009 | |
@result{}## --- ##
|
| 13010 | |
@end example
|
| 13011 | |
|
| 13012 | |
The @var{message} must contain balanced quotes and parentheses, although
|
| 13013 | |
quadrigraphs can be used to work around this.
|
| 13014 | |
@end defmac
|
| 13015 | |
|
| 13016 | |
@defmac m4_text_wrap (@var{string}, @ovar{prefix}, @
|
| 13017 | |
@dvar{prefix1, @var{prefix}}, @dvar{width, 79})
|
| 13018 | |
@msindex{text_wrap}
|
| 13019 | |
Break @var{string} into a series of whitespace-separated words, then
|
| 13020 | |
output those words separated by spaces, and wrapping lines any time the
|
| 13021 | |
output would exceed @var{width} columns. If given, @var{prefix1} begins
|
| 13022 | |
the first line, and @var{prefix} begins all wrapped lines. If
|
| 13023 | |
@var{prefix1} is longer than @var{prefix}, then the first line consists
|
| 13024 | |
of just @var{prefix1}. If @var{prefix} is longer than @var{prefix1},
|
| 13025 | |
padding is inserted so that the first word of @var{string} begins at the
|
| 13026 | |
same indentation as all wrapped lines. Note that using literal tab
|
| 13027 | |
characters in any of the arguments will interfere with the calculation
|
| 13028 | |
of width. No expansions occur on @var{prefix}, @var{prefix1}, or the
|
| 13029 | |
words of @var{string}, although quadrigraphs are recognized.
|
| 13030 | |
|
| 13031 | |
For some examples:
|
| 13032 | |
@example
|
| 13033 | |
m4_text_wrap([Short string */], [ ], [/* ], [20])
|
| 13034 | |
@result{}/* Short string */
|
| 13035 | |
m4_text_wrap([Much longer string */], [ ], [/* ], [20])
|
| 13036 | |
@result{}/* Much longer
|
| 13037 | |
@result{} string */
|
| 13038 | |
m4_text_wrap([Short doc.], [ ], [ --short ], [30])
|
| 13039 | |
@result{} --short Short doc.
|
| 13040 | |
m4_text_wrap([Short doc.], [ ], [ --too-wide ], [30])
|
| 13041 | |
@result{} --too-wide
|
| 13042 | |
@result{} Short doc.
|
| 13043 | |
m4_text_wrap([Super long documentation.], [ ],
|
| 13044 | |
[ --too-wide ], 30)
|
| 13045 | |
@result{} --too-wide
|
| 13046 | |
@result{} Super long
|
| 13047 | |
@result{} documentation.
|
| 13048 | |
@end example
|
| 13049 | |
@end defmac
|
| 13050 | |
|
| 13051 | |
@defmac m4_tolower (@var{string})
|
| 13052 | |
@defmacx m4_toupper (@var{string})
|
| 13053 | |
@msindex{tolower}
|
| 13054 | |
@msindex{toupper}
|
| 13055 | |
Return @var{string} with letters converted to upper or lower case,
|
| 13056 | |
respectively.
|
| 13057 | |
@end defmac
|
| 13058 | |
|
| 13059 | |
@node Number processing Macros
|
| 13060 | |
@subsection Arithmetic computation in M4
|
| 13061 | |
|
| 13062 | |
The following macros facilitate integer arithmetic operations.
|
| 13063 | |
Where a parameter is documented as taking an arithmetic expression, you
|
| 13064 | |
can use anything that can be parsed by @code{m4_eval}.
|
| 13065 | |
|
| 13066 | |
@defmac m4_cmp (@var{expr-1}, @var{expr-2})
|
| 13067 | |
@msindex{cmp}
|
| 13068 | |
Compare the arithmetic expressions @var{expr-1} and @var{expr-2}, and
|
| 13069 | |
expand to @samp{-1} if @var{expr-1} is smaller, @samp{0} if they are
|
| 13070 | |
equal, and @samp{1} if @var{expr-1} is larger.
|
| 13071 | |
@end defmac
|
| 13072 | |
|
| 13073 | |
@defmac m4_list_cmp (@var{list-1}, @var{list-2})
|
| 13074 | |
@msindex{list_cmp}
|
| 13075 | |
Compare the two M4 lists consisting of comma-separated arithmetic
|
| 13076 | |
expressions, left to right. Expand to @samp{-1} for the first element
|
| 13077 | |
pairing where the value from @var{list-1} is smaller, @samp{1} where the
|
| 13078 | |
value from @var{list-2} is smaller, or @samp{0} if both lists have the
|
| 13079 | |
same values. If one list is shorter than the other, the remaining
|
| 13080 | |
elements of the longer list are compared against zero.
|
| 13081 | |
@example
|
| 13082 | |
m4_list_cmp([1, 0], [1])
|
| 13083 | |
@result{}0
|
| 13084 | |
m4_list_cmp([1, [1 * 0]], [1, 0])
|
| 13085 | |
@result{}0
|
| 13086 | |
m4_list_cmp([1, 2], [1, 0])
|
| 13087 | |
@result{}1
|
| 13088 | |
m4_list_cmp([1, [1+1], 3],[1, 2])
|
| 13089 | |
@result{}1
|
| 13090 | |
m4_list_cmp([1, 2, -3], [1, 2])
|
| 13091 | |
@result{}-1
|
| 13092 | |
m4_list_cmp([1, 0], [1, 2])
|
| 13093 | |
@result{}-1
|
| 13094 | |
m4_list_cmp([1], [1, 2])
|
| 13095 | |
@result{}-1
|
| 13096 | |
@end example
|
| 13097 | |
@end defmac
|
| 13098 | |
|
| 13099 | |
@defmac m4_max (@var{arg}, @dots{})
|
| 13100 | |
@msindex{max}
|
| 13101 | |
This macro was introduced in Autoconf 2.62. Expand to the decimal value
|
| 13102 | |
of the maximum arithmetic expression among all the arguments.
|
| 13103 | |
@end defmac
|
| 13104 | |
|
| 13105 | |
@defmac m4_min (@var{arg}, @dots{})
|
| 13106 | |
@msindex{min}
|
| 13107 | |
This macro was introduced in Autoconf 2.62. Expand to the decimal value
|
| 13108 | |
of the minimum arithmetic expression among all the arguments.
|
| 13109 | |
@end defmac
|
| 13110 | |
|
| 13111 | |
@defmac m4_sign (@var{expr})
|
| 13112 | |
@msindex{sign}
|
| 13113 | |
Expand to @samp{-1} if the arithmetic expression @var{expr} is negative,
|
| 13114 | |
@samp{1} if it is positive, and @samp{0} if it is zero.
|
| 13115 | |
@end defmac
|
| 13116 | |
|
| 13117 | |
@anchor{m4_version_compare}
|
| 13118 | |
@defmac m4_version_compare (@var{version-1}, @var{version-2})
|
| 13119 | |
@msindex{version_compare}
|
| 13120 | |
This macro was introduced in Autoconf 2.53, but had a number of
|
| 13121 | |
usability limitations that were not lifted until Autoconf 2.62. Compare
|
| 13122 | |
the version strings @var{version-1} and @var{version-2}, and expand to
|
| 13123 | |
@samp{-1} if @var{version-1} is smaller, @samp{0} if they are the same,
|
| 13124 | |
or @samp{1} @var{version-2} is smaller. Version strings must be a list
|
| 13125 | |
of elements separated by @samp{.}, @samp{,} or @samp{-}, where each
|
| 13126 | |
element is a number along with optional case-insensitive letters
|
| 13127 | |
designating beta releases. The comparison stops at the leftmost element
|
| 13128 | |
that contains a difference, although a 0 element compares equal to a
|
| 13129 | |
missing element.
|
| 13130 | |
|
| 13131 | |
It is permissible to include commit identifiers in @var{version}, such
|
| 13132 | |
as an abbreviated SHA1 of the commit, provided there is still a
|
| 13133 | |
monotonically increasing prefix to allow for accurate version-based
|
| 13134 | |
comparisons. For example, this paragraph was written when the
|
| 13135 | |
development snapshot of autoconf claimed to be at version
|
| 13136 | |
@samp{2.61a-248-dc51}, or 248 commits after the 2.61a release, with an
|
| 13137 | |
abbreviated commit identification of @samp{dc51}.
|
| 13138 | |
|
| 13139 | |
@example
|
| 13140 | |
m4_version_compare([1.1], [2.0])
|
| 13141 | |
@result{}-1
|
| 13142 | |
m4_version_compare([2.0b], [2.0a])
|
| 13143 | |
@result{}1
|
| 13144 | |
m4_version_compare([1.1.1], [1.1.1a])
|
| 13145 | |
@result{}-1
|
| 13146 | |
m4_version_compare([1.2], [1.1.1a])
|
| 13147 | |
@result{}1
|
| 13148 | |
m4_version_compare([1.0], [1])
|
| 13149 | |
@result{}0
|
| 13150 | |
m4_version_compare([1.1pre], [1.1PRE])
|
| 13151 | |
@result{}0
|
| 13152 | |
m4_version_compare([1.1a], [1,10])
|
| 13153 | |
@result{}-1
|
| 13154 | |
m4_version_compare([2.61a], [2.61a-248-dc51])
|
| 13155 | |
@result{}-1
|
| 13156 | |
m4_version_compare([2.61b], [2.61a-248-dc51])
|
| 13157 | |
@result{}1
|
| 13158 | |
@end example
|
| 13159 | |
@end defmac
|
| 13160 | |
|
| 13161 | |
@defmac m4_version_prereq (@var{version}, @ovar{if-new-enough}, @
|
| 13162 | |
@dvar{if-old, m4_fatal})
|
| 13163 | |
@msindex{version_prereq}
|
| 13164 | |
Compares @var{version} against the version of Autoconf currently
|
| 13165 | |
running. If the running version is at @var{version} or newer, expand
|
| 13166 | |
@var{if-new-enough}, but if @var{version} is larger than the version
|
| 13167 | |
currently executing, expand @var{if-old}, which defaults to printing an
|
| 13168 | |
error message and exiting m4sugar with status 63. When given only one
|
| 13169 | |
argument, this behaves like @code{AC_PREREQ} (@pxref{Versioning}).
|
| 13170 | |
Remember that the autoconf philosophy favors feature checks over version
|
| 13171 | |
checks.
|
| 13172 | |
@end defmac
|
| 13173 | |
|
| 13174 | |
@node Set manipulation Macros
|
| 13175 | |
@subsection Set manipulation in M4
|
| 13176 | |
@cindex Set manipulation
|
| 13177 | |
@cindex Data structure, set
|
| 13178 | |
@cindex Unordered set manipulation
|
| 13179 | |
|
| 13180 | |
Sometimes, it is necessary to track a set of data, where the order does
|
| 13181 | |
not matter and where there are no duplicates in the set. The following
|
| 13182 | |
macros facilitate set manipulations. Each set is an opaque object,
|
| 13183 | |
which can only be accessed via these basic operations. The underlying
|
| 13184 | |
implementation guarantees linear scaling for set creation, which is more
|
| 13185 | |
efficient than using the quadratic @code{m4_append_uniq}. Both set
|
| 13186 | |
names and values can be arbitrary strings, except for unbalanced quotes.
|
| 13187 | |
This implementation ties up memory for removed elements until the next
|
| 13188 | |
operation that must traverse all the elements of a set; and although
|
| 13189 | |
that may slow down some operations until the memory for removed elements
|
| 13190 | |
is pruned, it still guarantees linear performance.
|
| 13191 | |
|
| 13192 | |
@defmac m4_set_add (@var{set}, @var{value}, @ovar{if-uniq}, @ovar{if-dup})
|
| 13193 | |
@msindex{set_add}
|
| 13194 | |
Adds the string @var{value} as a member of set @var{set}. Expand
|
| 13195 | |
@var{if-uniq} if the element was added, or @var{if-dup} if it was
|
| 13196 | |
previously in the set. Operates in amortized constant time, so that set
|
| 13197 | |
creation scales linearly.
|
| 13198 | |
@end defmac
|
| 13199 | |
|
| 13200 | |
@defmac m4_set_add_all (@var{set}, @var{value}@dots{})
|
| 13201 | |
@msindex{set_add_all}
|
| 13202 | |
Adds each @var{value} to the set @var{set}. This is slightly more
|
| 13203 | |
efficient than repeatedly invoking @code{m4_set_add}.
|
| 13204 | |
@end defmac
|
| 13205 | |
|
| 13206 | |
@defmac m4_set_contains (@var{set}, @var{value}, @ovar{if-present}, @
|
| 13207 | |
@ovar{if-absent})
|
| 13208 | |
@msindex{set_contains}
|
| 13209 | |
Expands @var{if-present} if the string @var{value} is a member of
|
| 13210 | |
@var{set}, otherwise @var{if-absent}.
|
| 13211 | |
|
| 13212 | |
@example
|
| 13213 | |
m4_set_contains([a], [1], [yes], [no])
|
| 13214 | |
@result{}no
|
| 13215 | |
m4_set_add([a], [1], [added], [dup])
|
| 13216 | |
@result{}added
|
| 13217 | |
m4_set_add([a], [1], [added], [dup])
|
| 13218 | |
@result{}dup
|
| 13219 | |
m4_set_contains([a], [1], [yes], [no])
|
| 13220 | |
@result{}yes
|
| 13221 | |
m4_set_remove([a], [1], [removed], [missing])
|
| 13222 | |
@result{}removed
|
| 13223 | |
m4_set_contains([a], [1], [yes], [no])
|
| 13224 | |
@result{}no
|
| 13225 | |
m4_set_remove([a], [1], [removed], [missing])
|
| 13226 | |
@result{}missing
|
| 13227 | |
@end example
|
| 13228 | |
@end defmac
|
| 13229 | |
|
| 13230 | |
@defmac m4_set_contents (@var{set}, @ovar{sep})
|
| 13231 | |
@defmacx m4_set_dump (@var{set}, @ovar{sep})
|
| 13232 | |
@msindex{set_contents}
|
| 13233 | |
@msindex{set_dump}
|
| 13234 | |
Expands to a single string consisting of all the members of the set
|
| 13235 | |
@var{set}, each separated by @var{sep}, which is not expanded.
|
| 13236 | |
@code{m4_set_contents} leaves the elements in @var{set} but reclaims any
|
| 13237 | |
memory occupied by removed elements, while @code{m4_set_dump} is a
|
| 13238 | |
faster one-shot action that also deletes the set. No provision is made
|
| 13239 | |
for disambiguating members that contain a non-empty @var{sep} as a
|
| 13240 | |
substring; use @code{m4_set_empty} to distinguish between an empty set
|
| 13241 | |
and the set containing only the empty string. The order of the output
|
| 13242 | |
is unspecified; in the current implementation, part of the speed of
|
| 13243 | |
@code{m4_set_dump} results from using a different output order than
|
| 13244 | |
@code{m4_set_contents}. These macros scale linearly in the size of the
|
| 13245 | |
set before memory pruning, and @code{m4_set_contents([@var{set}],
|
| 13246 | |
[@var{sep}])} is faster than
|
| 13247 | |
@code{m4_joinall([@var{sep}]m4_set_listc([@var{set}]))}.
|
| 13248 | |
|
| 13249 | |
@example
|
| 13250 | |
m4_set_add_all([a], [1], [2], [3])
|
| 13251 | |
@result{}
|
| 13252 | |
m4_set_contents([a], [-])
|
| 13253 | |
@result{}1-2-3
|
| 13254 | |
m4_joinall([-]m4_set_listc([a]))
|
| 13255 | |
@result{}1-2-3
|
| 13256 | |
m4_set_dump([a], [-])
|
| 13257 | |
@result{}3-2-1
|
| 13258 | |
m4_set_contents([a])
|
| 13259 | |
@result{}
|
| 13260 | |
m4_set_add([a], [])
|
| 13261 | |
@result{}
|
| 13262 | |
m4_set_contents([a], [-])
|
| 13263 | |
@result{}
|
| 13264 | |
@end example
|
| 13265 | |
@end defmac
|
| 13266 | |
|
| 13267 | |
@defmac m4_set_delete (@var{set})
|
| 13268 | |
@msindex{set_delete}
|
| 13269 | |
Delete all elements and memory associated with @var{set}. This is
|
| 13270 | |
linear in the set size, and faster than removing one element at a time.
|
| 13271 | |
@end defmac
|
| 13272 | |
|
| 13273 | |
@defmac m4_set_difference (@var{seta}, @var{setb})
|
| 13274 | |
@defmacx m4_set_intersection (@var{seta}, @var{setb})
|
| 13275 | |
@defmacx m4_set_union (@var{seta}, @var{setb})
|
| 13276 | |
@msindex{set_difference}
|
| 13277 | |
@msindex{set_intersection}
|
| 13278 | |
@msindex{set_union}
|
| 13279 | |
Compute the relation between @var{seta} and @var{setb}, and output the
|
| 13280 | |
result as a list of quoted arguments without duplicates and with a
|
| 13281 | |
leading comma. Set difference selects the elements in @var{seta} but
|
| 13282 | |
not @var{setb}, intersection selects only elements in both sets, and
|
| 13283 | |
union selects elements in either set. These actions are linear in the
|
| 13284 | |
sum of the set sizes. The leading comma is necessary to distinguish
|
| 13285 | |
between no elements and the empty string as the only element.
|
| 13286 | |
|
| 13287 | |
@example
|
| 13288 | |
m4_set_add_all([a], [1], [2], [3])
|
| 13289 | |
@result{}
|
| 13290 | |
m4_set_add_all([b], [3], [], [4])
|
| 13291 | |
@result{}
|
| 13292 | |
m4_set_difference([a], [b])
|
| 13293 | |
@result{},1,2
|
| 13294 | |
m4_set_difference([b], [a])
|
| 13295 | |
@result{},,4
|
| 13296 | |
m4_set_intersection([a], [b])
|
| 13297 | |
@result{},3
|
| 13298 | |
m4_set_union([a], [b])
|
| 13299 | |
@result{},1,2,3,,4
|
| 13300 | |
@end example
|
| 13301 | |
@end defmac
|
| 13302 | |
|
| 13303 | |
@defmac m4_set_empty (@var{set}, @ovar{if-empty}, @ovar{if-elements})
|
| 13304 | |
@msindex{set_empty}
|
| 13305 | |
Expand @var{if-empty} if the set @var{set} has no elements, otherwise
|
| 13306 | |
expand @var{if-elements}. This macro operates in constant time. Using
|
| 13307 | |
this macro can help disambiguate output from @code{m4_set_contents} or
|
| 13308 | |
@code{m4_set_list}.
|
| 13309 | |
@end defmac
|
| 13310 | |
|
| 13311 | |
@defmac m4_set_foreach (@var{set}, @var{variable}, @var{action})
|
| 13312 | |
@msindex{set_foreach}
|
| 13313 | |
For each element in the set @var{set}, expand @var{action} with the
|
| 13314 | |
macro @var{variable} defined as the set element. Behavior is
|
| 13315 | |
unspecified if @var{action} recursively lists the contents of @var{set}
|
| 13316 | |
(although listing other sets is acceptable), or if it modifies the set
|
| 13317 | |
in any way other than removing the element currently contained in
|
| 13318 | |
@var{variable}. This macro is faster than the corresponding
|
| 13319 | |
@code{m4_foreach([@var{variable}],
|
| 13320 | |
m4_indir([m4_dquote]m4_set_listc([@var{set}])), [@var{action}])},
|
| 13321 | |
although @code{m4_set_map} might be faster still.
|
| 13322 | |
|
| 13323 | |
@example
|
| 13324 | |
m4_set_add_all([a]m4_for([i], [1], [5], [], [,i]))
|
| 13325 | |
@result{}
|
| 13326 | |
m4_set_contents([a])
|
| 13327 | |
@result{}12345
|
| 13328 | |
m4_set_foreach([a], [i],
|
| 13329 | |
[m4_if(m4_eval(i&1), [0], [m4_set_remove([a], i, [i])])])
|
| 13330 | |
@result{}24
|
| 13331 | |
m4_set_contents([a])
|
| 13332 | |
@result{}135
|
| 13333 | |
@end example
|
| 13334 | |
@end defmac
|
| 13335 | |
|
| 13336 | |
@defmac m4_set_list (@var{set})
|
| 13337 | |
@defmacx m4_set_listc (@var{set})
|
| 13338 | |
@msindex{set_list}
|
| 13339 | |
@msindex{set_listc}
|
| 13340 | |
Produce a list of arguments, where each argument is a quoted element
|
| 13341 | |
from the set @var{set}. The variant @code{m4_set_listc} is unambiguous,
|
| 13342 | |
by adding a leading comma if there are any set elements, whereas the
|
| 13343 | |
variant @code{m4_set_list} cannot distinguish between an empty set and a
|
| 13344 | |
set containing only the empty string. These can be directly used in
|
| 13345 | |
macros that take multiple arguments, such as @code{m4_join} or
|
| 13346 | |
@code{m4_set_add_all}, or wrapped by @code{m4_dquote} for macros that
|
| 13347 | |
take a quoted list, such as @code{m4_map} or @code{m4_foreach}. Any
|
| 13348 | |
memory occupied by removed elements is reclaimed during these macros.
|
| 13349 | |
|
| 13350 | |
@example
|
| 13351 | |
m4_set_add_all([a], [1], [2], [3])
|
| 13352 | |
@result{}
|
| 13353 | |
m4_set_list([a])
|
| 13354 | |
@result{}1,2,3
|
| 13355 | |
m4_set_list([b])
|
| 13356 | |
@result{}
|
| 13357 | |
m4_set_listc([b])
|
| 13358 | |
@result{}
|
| 13359 | |
m4_count(m4_set_list([b]))
|
| 13360 | |
@result{}1
|
| 13361 | |
m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
|
| 13362 | |
@result{}0
|
| 13363 | |
m4_set_add([b], [])
|
| 13364 | |
@result{}
|
| 13365 | |
m4_set_list([b])
|
| 13366 | |
@result{}
|
| 13367 | |
m4_set_listc([b])
|
| 13368 | |
@result{},
|
| 13369 | |
m4_count(m4_set_list([b]))
|
| 13370 | |
@result{}1
|
| 13371 | |
m4_set_empty([b], [0], [m4_count(m4_set_list([b]))])
|
| 13372 | |
@result{}1
|
| 13373 | |
@end example
|
| 13374 | |
@end defmac
|
| 13375 | |
|
| 13376 | |
@defmac m4_set_map (@var{set}, @var{action})
|
| 13377 | |
@msindex{set_map}
|
| 13378 | |
For each element in the set @var{set}, expand @var{action} with a single
|
| 13379 | |
argument of the set element. Behavior is unspecified if @var{action}
|
| 13380 | |
recursively lists the contents of @var{set} (although listing other sets
|
| 13381 | |
is acceptable), or if it modifies the set in any way other than removing
|
| 13382 | |
the element passed as an argument. This macro is faster than either
|
| 13383 | |
corresponding counterpart of
|
| 13384 | |
@code{m4_map_args([@var{action}]m4_set_listc([@var{set}]))} or
|
| 13385 | |
@code{m4_set_foreach([@var{set}], [var],
|
| 13386 | |
[@var{action}(m4_defn([var]))])}. It is possible to use @code{m4_curry}
|
| 13387 | |
if more than one argument is needed for @var{action}, although it is
|
| 13388 | |
more efficient to use @code{m4_set_map_sep} in that case.
|
| 13389 | |
@end defmac
|
| 13390 | |
|
| 13391 | |
@defmac m4_set_map_sep (@var{set}, @ovar{pre}, @ovar{post}, @ovar{sep})
|
| 13392 | |
@msindex{set_map_sep}
|
| 13393 | |
For each element in the set @var{set}, expand
|
| 13394 | |
@code{@var{pre}[element]@var{post}}, additionally expanding @var{sep}
|
| 13395 | |
between elements. Behavior is unspecified if the expansion recursively
|
| 13396 | |
lists the contents of @var{set} (although listing other sets
|
| 13397 | |
is acceptable), or if it modifies the set in any way other than removing
|
| 13398 | |
the element visited by the expansion. This macro provides the most
|
| 13399 | |
efficient means for non-destructively visiting the elements of a set; in
|
| 13400 | |
particular, @code{m4_set_map([@var{set}], [@var{action}])} is equivalent
|
| 13401 | |
to @code{m4_set_map_sep([@var{set}], [@var{action}(], [)])}.
|
| 13402 | |
@end defmac
|
| 13403 | |
|
| 13404 | |
@defmac m4_set_remove (@var{set}, @var{value}, @ovar{if-present}, @
|
| 13405 | |
@ovar{if-absent})
|
| 13406 | |
@msindex{set_remove}
|
| 13407 | |
If @var{value} is an element in the set @var{set}, then remove it and
|
| 13408 | |
expand @var{if-present}. Otherwise expand @var{if-absent}. This macro
|
| 13409 | |
operates in constant time so that multiple removals will scale linearly
|
| 13410 | |
rather than quadratically; but when used outside of
|
| 13411 | |
@code{m4_set_foreach} or @code{m4_set_map}, it leaves memory occupied
|
| 13412 | |
until the set is later
|
| 13413 | |
compacted by @code{m4_set_contents} or @code{m4_set_list}. Several
|
| 13414 | |
other set operations are then less efficient between the time of element
|
| 13415 | |
removal and subsequent memory compaction, but still maintain their
|
| 13416 | |
guaranteed scaling performance.
|
| 13417 | |
@end defmac
|
| 13418 | |
|
| 13419 | |
@defmac m4_set_size (@var{set})
|
| 13420 | |
@msindex{set_size}
|
| 13421 | |
Expand to the size of the set @var{set}. This implementation operates
|
| 13422 | |
in constant time, and is thus more efficient than
|
| 13423 | |
@code{m4_eval(m4_count(m4_set_listc([set])) - 1)}.
|
| 13424 | |
@end defmac
|
| 13425 | |
|
| 13426 | |
|
| 13427 | |
@node Forbidden Patterns
|
| 13428 | |
@subsection Forbidden Patterns
|
| 13429 | |
@cindex Forbidden patterns
|
| 13430 | |
@cindex Patterns, forbidden
|
| 13431 | |
|
| 13432 | |
M4sugar provides a means to define suspicious patterns, patterns
|
| 13433 | |
describing tokens which should not be found in the output. For
|
| 13434 | |
instance, if an Autoconf @file{configure} script includes tokens such as
|
| 13435 | |
@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
|
| 13436 | |
wrong (typically a macro was not evaluated because of overquotation).
|
| 13437 | |
|
| 13438 | |
M4sugar forbids all the tokens matching @samp{^_?m4_} and @samp{^dnl$}.
|
| 13439 | |
Additional layers, such as M4sh and Autoconf, add additional forbidden
|
| 13440 | |
patterns to the list.
|
| 13441 | |
|
| 13442 | |
@defmac m4_pattern_forbid (@var{pattern})
|
| 13443 | |
@msindex{pattern_forbid}
|
| 13444 | |
Declare that no token matching @var{pattern} must be found in the output.
|
| 13445 | |
Comments are not checked; this can be a problem if, for instance, you
|
| 13446 | |
have some macro left unexpanded after an @samp{#include}. No consensus
|
| 13447 | |
is currently found in the Autoconf community, as some people consider it
|
| 13448 | |
should be valid to name macros in comments (which doesn't make sense to
|
| 13449 | |
the authors of this documentation: input, such as macros, should be
|
| 13450 | |
documented by @samp{dnl} comments; reserving @samp{#}-comments to
|
| 13451 | |
document the output).
|
| 13452 | |
@end defmac
|
| 13453 | |
|
| 13454 | |
Of course, you might encounter exceptions to these generic rules, for
|
| 13455 | |
instance you might have to refer to @samp{$m4_flags}.
|
| 13456 | |
|
| 13457 | |
@defmac m4_pattern_allow (@var{pattern})
|
| 13458 | |
@msindex{pattern_allow}
|
| 13459 | |
Any token matching @var{pattern} is allowed, including if it matches an
|
| 13460 | |
@code{m4_pattern_forbid} pattern.
|
| 13461 | |
@end defmac
|
| 13462 | |
|
| 13463 | |
@node Debugging via autom4te
|
| 13464 | |
@section Debugging via autom4te
|
| 13465 | |
@cindex debugging tips
|
| 13466 | |
@cindex autom4te debugging tips
|
| 13467 | |
@cindex m4sugar debugging tips
|
| 13468 | |
At times, it is desirable to see what was happening inside m4, to see
|
| 13469 | |
why output was not matching expectations. However, post-processing done
|
| 13470 | |
by @command{autom4te} means that directly using the m4 builtin
|
| 13471 | |
@code{m4_traceon} is likely to interfere with operation. Also, frequent
|
| 13472 | |
diversion changes and the concept of forbidden tokens make it difficult
|
| 13473 | |
to use @code{m4_defn} to generate inline comments in the final output.
|
| 13474 | |
|
| 13475 | |
There are a couple of tools to help with this. One is the use of the
|
| 13476 | |
@option{--trace} option provided by @command{autom4te} (as well as each
|
| 13477 | |
of the programs that wrap @command{autom4te}, such as
|
| 13478 | |
@command{autoconf}), in order to inspect when a macro is called and with
|
| 13479 | |
which arguments. For example, when this paragraph was written, the
|
| 13480 | |
autoconf version could be found by:
|
| 13481 | |
|
| 13482 | |
@example
|
| 13483 | |
$ @kbd{autoconf --trace=AC_INIT}
|
| 13484 | |
configure.ac:23:AC_INIT:GNU Autoconf:2.63b.95-3963:bug-autoconf@@gnu.org
|
| 13485 | |
$ @kbd{autoconf --trace='AC_INIT:version is $2'}
|
| 13486 | |
version is 2.63b.95-3963
|
| 13487 | |
@end example
|
| 13488 | |
|
| 13489 | |
Another trick is to print out the expansion of various m4 expressions to
|
| 13490 | |
standard error or to an independent file, with no further m4 expansion,
|
| 13491 | |
and without interfering with diversion changes or the post-processing
|
| 13492 | |
done to standard output. @code{m4_errprintn} shows a given expression
|
| 13493 | |
on standard error. For example, if you want to see the expansion of an
|
| 13494 | |
autoconf primitive or of one of your autoconf macros, you can do it like
|
| 13495 | |
this:
|
| 13496 | |
|
| 13497 | |
@example
|
| 13498 | |
$ @kbd{cat <<\EOF > configure.ac}
|
| 13499 | |
AC_INIT
|
| 13500 | |
m4_errprintn([The definition of AC_DEFINE_UNQUOTED:])
|
| 13501 | |
m4_errprintn(m4_defn([AC_DEFINE_UNQUOTED]))
|
| 13502 | |
AC_OUTPUT
|
| 13503 | |
EOF
|
| 13504 | |
$ @kbd{autoconf}
|
| 13505 | |
@error{}The definition of AC_DEFINE_UNQUOTED:
|
| 13506 | |
@error{}_AC_DEFINE_Q([], $@@)
|
| 13507 | |
@end example
|
| 13508 | |
|
| 13509 | |
@node Programming in M4sh
|
| 13510 | |
@chapter Programming in M4sh
|
| 13511 | |
|
| 13512 | |
M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
|
| 13513 | |
scripts. This name was coined by Lars J. Aas, who notes that,
|
| 13514 | |
according to the Webster's Revised Unabridged Dictionary (1913):
|
| 13515 | |
|
| 13516 | |
@quotation
|
| 13517 | |
Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
|
| 13518 | |
wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
|
| 13519 | |
|
| 13520 | |
@enumerate 1
|
| 13521 | |
@item
|
| 13522 | |
A mass of mixed ingredients reduced to a soft pulpy state by beating or
|
| 13523 | |
pressure@enddots{}
|
| 13524 | |
|
| 13525 | |
@item
|
| 13526 | |
A mixture of meal or bran and water fed to animals.
|
| 13527 | |
|
| 13528 | |
@item
|
| 13529 | |
A mess; trouble. [Obs.] --Beau.@: & Fl.
|
| 13530 | |
@end enumerate
|
| 13531 | |
@end quotation
|
| 13532 | |
|
| 13533 | |
M4sh reserves the M4 macro namespace @samp{^_AS_} for internal use, and
|
| 13534 | |
the namespace @samp{^AS_} for M4sh macros. It also reserves the shell
|
| 13535 | |
and environment variable namespace @samp{^as_}, and the here-document
|
| 13536 | |
delimiter namespace @samp{^_AS[A-Z]} in the output file. You should not
|
| 13537 | |
define your own macros or output shell code that conflicts with these
|
| 13538 | |
namespaces.
|
| 13539 | |
|
| 13540 | |
@menu
|
| 13541 | |
* Common Shell Constructs:: Portability layer for common shell constructs
|
| 13542 | |
* Polymorphic Variables:: Support for indirect variable names
|
| 13543 | |
* Initialization Macros:: Macros to establish a sane shell environment
|
| 13544 | |
* File Descriptor Macros:: File descriptor macros for input and output
|
| 13545 | |
@end menu
|
| 13546 | |
|
| 13547 | |
@node Common Shell Constructs
|
| 13548 | |
@section Common Shell Constructs
|
| 13549 | |
|
| 13550 | |
M4sh provides portable alternatives for some common shell constructs
|
| 13551 | |
that unfortunately are not portable in practice.
|
| 13552 | |
|
| 13553 | |
@c Deprecated, to be replaced by a better API
|
| 13554 | |
@ignore
|
| 13555 | |
@defmac AS_BASENAME (@var{file-name})
|
| 13556 | |
@asindex{BASENAME}
|
| 13557 | |
Output the non-directory portion of @var{file-name}. For example,
|
| 13558 | |
if @code{$file} is @samp{/one/two/three}, the command
|
| 13559 | |
@code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
|
| 13560 | |
@end defmac
|
| 13561 | |
@end ignore
|
| 13562 | |
|
| 13563 | |
@defmac AS_BOX (@var{text}, @dvar{char, -})
|
| 13564 | |
@asindex{BOX}
|
| 13565 | |
Expand into shell code that will output @var{text} surrounded by a box
|
| 13566 | |
with @var{char} in the top and bottom border. @var{text} should not
|
| 13567 | |
contain a newline, but may contain shell expansions valid for unquoted
|
| 13568 | |
here-documents. @var{char} defaults to @samp{-}, but can be any
|
| 13569 | |
character except @samp{/}, @samp{'}, @samp{"}, @samp{\},
|
| 13570 | |
@samp{&}, or @samp{`}. This is useful for outputting a comment box into
|
| 13571 | |
log files to separate distinct phases of script operation.
|
| 13572 | |
@end defmac
|
| 13573 | |
|
| 13574 | |
@defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @
|
| 13575 | |
@dots{}, @ovar{default})
|
| 13576 | |
@asindex{CASE}
|
| 13577 | |
Expand into a shell @samp{case} statement, where @var{word} is matched
|
| 13578 | |
against one or more patterns. @var{if-matched} is run if the
|
| 13579 | |
corresponding pattern matched @var{word}, else @var{default} is run.
|
| 13580 | |
Avoids several portability issues (@pxref{case, , Limitations of Shell
|
| 13581 | |
Builtins}).
|
| 13582 | |
@end defmac
|
| 13583 | |
|
| 13584 | |
@c Deprecated, to be replaced by a better API
|
| 13585 | |
@defmac AS_DIRNAME (@var{file-name})
|
| 13586 | |
@asindex{DIRNAME}
|
| 13587 | |
Output the directory portion of @var{file-name}. For example,
|
| 13588 | |
if @code{$file} is @samp{/one/two/three}, the command
|
| 13589 | |
@code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
|
| 13590 | |
|
| 13591 | |
This interface may be improved in the future to avoid forks and losing
|
| 13592 | |
trailing newlines.
|
| 13593 | |
@end defmac
|
| 13594 | |
|
| 13595 | |
@defmac AS_ECHO (@var{word})
|
| 13596 | |
@asindex{ECHO}
|
| 13597 | |
Emits @var{word} to the standard output, followed by a newline. @var{word}
|
| 13598 | |
must be a single shell word (typically a quoted string). The bytes of
|
| 13599 | |
@var{word} are output as-is, even if it starts with "-" or contains "\".
|
| 13600 | |
Redirections can be placed outside the macro invocation. This is much
|
| 13601 | |
more portable than using @command{echo} (@pxref{echo, , Limitations of
|
| 13602 | |
Shell Builtins}).
|
| 13603 | |
@end defmac
|
| 13604 | |
|
| 13605 | |
@defmac AS_ECHO_N (@var{word})
|
| 13606 | |
@asindex{ECHO_N}
|
| 13607 | |
Emits @var{word} to the standard output, without a following newline.
|
| 13608 | |
@var{word} must be a single shell word (typically a quoted string) and,
|
| 13609 | |
for portability, should not include more than one newline. The bytes of
|
| 13610 | |
@var{word} are output as-is, even if it starts with "-" or contains "\".
|
| 13611 | |
Redirections can be placed outside the macro invocation.
|
| 13612 | |
@end defmac
|
| 13613 | |
|
| 13614 | |
@c We cannot use @dvar because the macro expansion mistreats backslashes.
|
| 13615 | |
@defmac AS_ESCAPE (@var{string}, @r{[}@var{chars} = @samp{`\"$}@r{]})
|
| 13616 | |
@asindex{ESCAPE}
|
| 13617 | |
Expands to @var{string}, with any characters in @var{chars} escaped with
|
| 13618 | |
a backslash (@samp{\}). @var{chars} should be at most four bytes long,
|
| 13619 | |
and only contain characters from the set @samp{`\"$}; however,
|
| 13620 | |
characters may be safely listed more than once in @var{chars} for the
|
| 13621 | |
sake of syntax highlighting editors. The current implementation expands
|
| 13622 | |
@var{string} after adding escapes; if @var{string} contains macro calls
|
| 13623 | |
that in turn expand to text needing shell quoting, you can use
|
| 13624 | |
@code{AS_ESCAPE(m4_dquote(m4_expand([string])))}.
|
| 13625 | |
|
| 13626 | |
The default for @var{chars} (@samp{\"$`}) is the set of characters
|
| 13627 | |
needing escapes when @var{string} will be used literally within double
|
| 13628 | |
quotes. One common variant is the set of characters to protect when
|
| 13629 | |
@var{string} will be used literally within back-ticks or an unquoted
|
| 13630 | |
here-document (@samp{\$`}). Another common variant is @samp{""}, which can
|
| 13631 | |
be used to form a double-quoted string containing the same expansions
|
| 13632 | |
that would have occurred if @var{string} were expanded in an unquoted
|
| 13633 | |
here-document; however, when using this variant, care must be taken that
|
| 13634 | |
@var{string} does not use double quotes within complex variable
|
| 13635 | |
expansions (such as @samp{$@{foo-`echo "hi"`@}}) that would be broken
|
| 13636 | |
with improper escapes.
|
| 13637 | |
|
| 13638 | |
This macro is often used with @code{AS_ECHO}. For an example, observe
|
| 13639 | |
the output generated by the shell code generated from this snippet:
|
| 13640 | |
|
| 13641 | |
@example
|
| 13642 | |
foo=bar
|
| 13643 | |
AS_ECHO(["AS_ESCAPE(["$foo" = ])AS_ESCAPE(["$foo"], [""])"])
|
| 13644 | |
@result{}"$foo" = "bar"
|
| 13645 | |
m4_define([macro], [a, [\b]])
|
| 13646 | |
AS_ECHO(["AS_ESCAPE([[macro]])"])
|
| 13647 | |
@result{}macro
|
| 13648 | |
AS_ECHO(["AS_ESCAPE([macro])"])
|
| 13649 | |
@result{}a, b
|
| 13650 | |
AS_ECHO(["AS_ESCAPE(m4_dquote(m4_expand([macro])))"])
|
| 13651 | |
@result{}a, \b
|
| 13652 | |
@end example
|
| 13653 | |
|
| 13654 | |
@comment Should we add AS_ESCAPE_SINGLE? If we do, we can optimize in
|
| 13655 | |
@comment the case of @var{string} that does not contain '.
|
| 13656 | |
To escape a string that will be placed within single quotes, use:
|
| 13657 | |
|
| 13658 | |
@example
|
| 13659 | |
m4_bpatsubst([[@var{string}]], ['], ['\\''])
|
| 13660 | |
@end example
|
| 13661 | |
@end defmac
|
| 13662 | |
|
| 13663 | |
@defmac AS_EXECUTABLE_P (@var{file})
|
| 13664 | |
@asindex{EXECUTABLE_P}
|
| 13665 | |
Emit code to probe whether @var{file} is a regular file with executable
|
| 13666 | |
permissions (and not a directory with search permissions). The caller
|
| 13667 | |
is responsible for quoting @var{file}.
|
| 13668 | |
@end defmac
|
| 13669 | |
|
| 13670 | |
@defmac AS_EXIT (@dvar{status, $?})
|
| 13671 | |
@asindex{EXIT}
|
| 13672 | |
Emit code to exit the shell with @var{status}, defaulting to @samp{$?}.
|
| 13673 | |
This macro
|
| 13674 | |
works around shells that see the exit status of the command prior to
|
| 13675 | |
@code{exit} inside a @samp{trap 0} handler (@pxref{trap, , Limitations
|
| 13676 | |
of Shell Builtins}).
|
| 13677 | |
@end defmac
|
| 13678 | |
|
| 13679 | |
@defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
|
| 13680 | |
@asindex{IF}
|
| 13681 | |
Run shell code @var{test1}. If @var{test1} exits with a zero status then
|
| 13682 | |
run shell code @var{run-if-true1}, else examine further tests. If no test
|
| 13683 | |
exits with a zero status, run shell code @var{run-if-false}, with
|
| 13684 | |
simplifications if either @var{run-if-true1} or @var{run-if-false}
|
| 13685 | |
is empty. For example,
|
| 13686 | |
|
| 13687 | |
@example
|
| 13688 | |
AS_IF([test "x$foo" = xyes], [HANDLE_FOO([yes])],
|
| 13689 | |
[test "x$foo" != xno], [HANDLE_FOO([maybe])],
|
| 13690 | |
[echo foo not specified])
|
| 13691 | |
@end example
|
| 13692 | |
|
| 13693 | |
@noindent
|
| 13694 | |
ensures any required macros of @code{HANDLE_FOO}
|
| 13695 | |
are expanded before the first test.
|
| 13696 | |
@end defmac
|
| 13697 | |
|
| 13698 | |
@defmac AS_MKDIR_P (@var{file-name})
|
| 13699 | |
@asindex{MKDIR_P}
|
| 13700 | |
Make the directory @var{file-name}, including intervening directories
|
| 13701 | |
as necessary. This is equivalent to @samp{mkdir -p -- @var{file-name}},
|
| 13702 | |
except that it is portable to older versions of @command{mkdir} that
|
| 13703 | |
lack support for the @option{-p} option or for the @option{--}
|
| 13704 | |
delimiter (@pxref{mkdir, , Limitations of Usual Tools}). Also,
|
| 13705 | |
@code{AS_MKDIR_P}
|
| 13706 | |
succeeds if @var{file-name} is a symbolic link to an existing directory,
|
| 13707 | |
even though Posix is unclear whether @samp{mkdir -p} should
|
| 13708 | |
succeed in that case. If creation of @var{file-name} fails, exit the
|
| 13709 | |
script.
|
| 13710 | |
|
| 13711 | |
Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
|
| 13712 | |
@end defmac
|
| 13713 | |
|
| 13714 | |
@defmac AS_SET_STATUS (@var{status})
|
| 13715 | |
@asindex{SET_STATUS}
|
| 13716 | |
Emit shell code to set the value of @samp{$?} to @var{status}, as
|
| 13717 | |
efficiently as possible. However, this is not guaranteed to abort a
|
| 13718 | |
shell running with @code{set -e} (@pxref{set, , Limitations of Shell
|
| 13719 | |
Builtins}). This should also be used at the end of a complex shell
|
| 13720 | |
function instead of @samp{return} (@pxref{Shell Functions}) to avoid
|
| 13721 | |
a DJGPP shell bug.
|
| 13722 | |
@end defmac
|
| 13723 | |
|
| 13724 | |
@defmac AS_TR_CPP (@var{expression})
|
| 13725 | |
@asindex{TR_CPP}
|
| 13726 | |
Transform @var{expression} into a valid right-hand side for a C @code{#define}.
|
| 13727 | |
For example:
|
| 13728 | |
|
| 13729 | |
@example
|
| 13730 | |
# This outputs "#define HAVE_CHAR_P 1".
|
| 13731 | |
# Notice the m4 quoting around #, to prevent an m4 comment
|
| 13732 | |
type="char *"
|
| 13733 | |
echo "[#]define AS_TR_CPP([HAVE_$type]) 1"
|
| 13734 | |
@end example
|
| 13735 | |
@end defmac
|
| 13736 | |
|
| 13737 | |
@defmac AS_TR_SH (@var{expression})
|
| 13738 | |
@asindex{TR_SH}
|
| 13739 | |
Transform @var{expression} into shell code that generates a valid shell
|
| 13740 | |
variable name. The result is literal when possible at m4 time, but must
|
| 13741 | |
be used with @code{eval} if @var{expression} causes shell indirections.
|
| 13742 | |
For example:
|
| 13743 | |
|
| 13744 | |
@example
|
| 13745 | |
# This outputs "Have it!".
|
| 13746 | |
header="sys/some file.h"
|
| 13747 | |
eval AS_TR_SH([HAVE_$header])=yes
|
| 13748 | |
if test "x$HAVE_sys_some_file_h" = xyes; then echo "Have it!"; fi
|
| 13749 | |
@end example
|
| 13750 | |
@end defmac
|
| 13751 | |
|
| 13752 | |
@defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
|
| 13753 | |
@asindex{SET_CATFILE}
|
| 13754 | |
Set the polymorphic shell variable @var{var} to @var{dir}/@var{file},
|
| 13755 | |
but optimizing the common cases (@var{dir} or @var{file} is @samp{.},
|
| 13756 | |
@var{file} is absolute, etc.).
|
| 13757 | |
@end defmac
|
| 13758 | |
|
| 13759 | |
@defmac AS_UNSET (@var{var})
|
| 13760 | |
@asindex{UNSET}
|
| 13761 | |
Unsets the shell variable @var{var}, working around bugs in older
|
| 13762 | |
shells (@pxref{unset, , Limitations of Shell
|
| 13763 | |
Builtins}). @var{var} can be a literal or indirect variable name.
|
| 13764 | |
@end defmac
|
| 13765 | |
|
| 13766 | |
@defmac AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, @
|
| 13767 | |
@ovar{action-if-less}, @ovar{action-if-equal}, @ovar{action-if-greater})
|
| 13768 | |
@asindex{VERSION_COMPARE}
|
| 13769 | |
Compare two strings @var{version-1} and @var{version-2}, possibly
|
| 13770 | |
containing shell variables, as version strings, and expand
|
| 13771 | |
@var{action-if-less}, @var{action-if-equal}, or @var{action-if-greater}
|
| 13772 | |
depending upon the result.
|
| 13773 | |
The algorithm to compare is similar to the one used by strverscmp in
|
| 13774 | |
glibc (@pxref{String/Array Comparison, , String/Array Comparison, libc,
|
| 13775 | |
The GNU C Library}).
|
| 13776 | |
@end defmac
|
| 13777 | |
|
| 13778 | |
@node Polymorphic Variables
|
| 13779 | |
@section Support for indirect variable names
|
| 13780 | |
@cindex variable name indirection
|
| 13781 | |
@cindex polymorphic variable name
|
| 13782 | |
@cindex indirection, variable name
|
| 13783 | |
|
| 13784 | |
Often, it is convenient to write a macro that will emit shell code
|
| 13785 | |
operating on a shell variable. The simplest case is when the variable
|
| 13786 | |
name is known. But a more powerful idiom is writing shell code that can
|
| 13787 | |
work through an indirection, where another variable or command
|
| 13788 | |
substitution produces the name of the variable to actually manipulate.
|
| 13789 | |
M4sh supports the notion of polymorphic shell variables, making it easy
|
| 13790 | |
to write a macro that can deal with either literal or indirect variable
|
| 13791 | |
names and output shell code appropriate for both use cases. Behavior is
|
| 13792 | |
undefined if expansion of an indirect variable does not result in a
|
| 13793 | |
literal variable name.
|
| 13794 | |
|
| 13795 | |
@defmac AS_LITERAL_IF (@var{expression}, @ovar{if-literal}, @ovar{if-not}, @
|
| 13796 | |
@dvar{if-simple-ref, @var{if-not}})
|
| 13797 | |
@defmacx AS_LITERAL_WORD_IF (@var{expression}, @ovar{if-literal}, @
|
| 13798 | |
@ovar{if-not}, @dvar{if-simple-ref, @var{if-not}})
|
| 13799 | |
@asindex{LITERAL_IF}
|
| 13800 | |
@asindex{LITERAL_WORD_IF}
|
| 13801 | |
If the expansion of @var{expression} is definitely a shell literal,
|
| 13802 | |
expand @var{if-literal}. If the expansion of @var{expression} looks
|
| 13803 | |
like it might contain shell indirections (such as @code{$var} or
|
| 13804 | |
@code{`expr`}), then @var{if-not} is expanded. Sometimes, it is
|
| 13805 | |
possible to output optimized code if @var{expression} consists only of
|
| 13806 | |
shell variable expansions (such as @code{$@{var@}}), in which case
|
| 13807 | |
@var{if-simple-ref} can be provided; but defaulting to @var{if-not}
|
| 13808 | |
should always be safe. @code{AS_LITERAL_WORD_IF} only expands
|
| 13809 | |
@var{if-literal} if @var{expression} looks like a single shell word,
|
| 13810 | |
containing no whitespace; while @code{AS_LITERAL_IF} allows whitespace
|
| 13811 | |
in @var{expression}.
|
| 13812 | |
|
| 13813 | |
In order to reduce the time spent recognizing whether an
|
| 13814 | |
@var{expression} qualifies as a literal or a simple indirection, the
|
| 13815 | |
implementation is somewhat conservative: @var{expression} must be a
|
| 13816 | |
single shell word (possibly after stripping whitespace), consisting only
|
| 13817 | |
of bytes that would have the same meaning whether unquoted or enclosed
|
| 13818 | |
in double quotes (for example, @samp{a.b} results in @var{if-literal},
|
| 13819 | |
even though it is not a valid shell variable name; while both @samp{'a'}
|
| 13820 | |
and @samp{[$]} result in @var{if-not}, because they behave differently
|
| 13821 | |
than @samp{"'a'"} and @samp{"[$]"}). This macro can be used in contexts
|
| 13822 | |
for recognizing portable file names (such as in the implementation of
|
| 13823 | |
@code{AC_LIBSOURCE}), or coupled with some transliterations for forming
|
| 13824 | |
valid variable names (such as in the implementation of @code{AS_TR_SH},
|
| 13825 | |
which uses an additional @code{m4_translit} to convert @samp{.} to
|
| 13826 | |
@samp{_}).
|
| 13827 | |
|
| 13828 | |
This example shows how to read the contents of the shell variable
|
| 13829 | |
@code{bar}, exercising all three arguments to @code{AS_LITERAL_IF}. It
|
| 13830 | |
results in a script that will output the line @samp{hello} three times.
|
| 13831 | |
|
| 13832 | |
@example
|
| 13833 | |
AC_DEFUN([MY_ACTION],
|
| 13834 | |
[AS_LITERAL_IF([$1],
|
| 13835 | |
[echo "$$1"],
|
| 13836 | |
@c $$
|
| 13837 | |
[AS_VAR_COPY([var], [$1])
|
| 13838 | |
echo "$var"],
|
| 13839 | |
[eval 'echo "$'"$1"\"])])
|
| 13840 | |
foo=bar bar=hello
|
| 13841 | |
MY_ACTION([bar])
|
| 13842 | |
MY_ACTION([`echo bar`])
|
| 13843 | |
MY_ACTION([$foo])
|
| 13844 | |
@end example
|
| 13845 | |
@end defmac
|
| 13846 | |
|
| 13847 | |
@defmac AS_VAR_APPEND (@var{var}, @var{text})
|
| 13848 | |
@asindex{VAR_APPEND}
|
| 13849 | |
Emit shell code to append the shell expansion of @var{text} to the end
|
| 13850 | |
of the current contents of the polymorphic shell variable @var{var},
|
| 13851 | |
taking advantage of shells that provide the @samp{+=} extension for more
|
| 13852 | |
efficient scaling.
|
| 13853 | |
|
| 13854 | |
For situations where the final contents of @var{var} are relatively
|
| 13855 | |
short (less than 256 bytes), it is more efficient to use the simpler
|
| 13856 | |
code sequence of @code{@var{var}=$@{@var{var}@}@var{text}} (or its
|
| 13857 | |
polymorphic equivalent of @code{AS_VAR_COPY([t], [@var{var}])} and
|
| 13858 | |
@code{AS_VAR_SET([@var{var}], ["$t"@var{text}])}). But in the case
|
| 13859 | |
when the script will be repeatedly appending text into @code{var},
|
| 13860 | |
issues of scaling start to become apparent. A naive implementation
|
| 13861 | |
requires execution time linear to the length of the current contents of
|
| 13862 | |
@var{var} as well as the length of @var{text} for a single append, for
|
| 13863 | |
an overall quadratic scaling with multiple appends. This macro takes
|
| 13864 | |
advantage of shells which provide the extension
|
| 13865 | |
@code{@var{var}+=@var{text}}, which can provide amortized constant time
|
| 13866 | |
for a single append, for an overall linear scaling with multiple
|
| 13867 | |
appends. Note that unlike @code{AS_VAR_SET}, this macro requires that
|
| 13868 | |
@var{text} be quoted properly to avoid field splitting and file name
|
| 13869 | |
expansion.
|
| 13870 | |
@end defmac
|
| 13871 | |
|
| 13872 | |
@defmac AS_VAR_ARITH (@var{var}, @var{expression})
|
| 13873 | |
@asindex{VAR_ARITH}
|
| 13874 | |
Emit shell code to compute the arithmetic expansion of @var{expression},
|
| 13875 | |
assigning the result as the contents of the polymorphic shell variable
|
| 13876 | |
@var{var}. The code takes advantage of shells that provide @samp{$(())}
|
| 13877 | |
for fewer forks, but uses @command{expr} as a fallback. Therefore, the
|
| 13878 | |
syntax for a valid @var{expression} is rather limited: all operators
|
| 13879 | |
must occur as separate shell arguments and with proper quoting, there is
|
| 13880 | |
no portable equality operator, all variables containing numeric values
|
| 13881 | |
must be expanded prior to the computation, all numeric values must be
|
| 13882 | |
provided in decimal without leading zeroes, and the first shell argument
|
| 13883 | |
should not be a negative number. In the following example, this snippet
|
| 13884 | |
will print @samp{(2+3)*4 == 20}.
|
| 13885 | |
|
| 13886 | |
@example
|
| 13887 | |
bar=3
|
| 13888 | |
AS_VAR_ARITH([foo], [\( 2 + $bar \) \* 4])
|
| 13889 | |
echo "(2+$bar)*4 == $foo"
|
| 13890 | |
@end example
|
| 13891 | |
@end defmac
|
| 13892 | |
|
| 13893 | |
@defmac AS_VAR_COPY (@var{dest}, @var{source})
|
| 13894 | |
@asindex{VAR_COPY}
|
| 13895 | |
Emit shell code to assign the contents of the polymorphic shell variable
|
| 13896 | |
@var{source} to the polymorphic shell variable @var{dest}. For example,
|
| 13897 | |
executing this M4sh snippet will output @samp{bar hi}:
|
| 13898 | |
|
| 13899 | |
@example
|
| 13900 | |
foo=bar bar=hi
|
| 13901 | |
AS_VAR_COPY([a], [foo])
|
| 13902 | |
AS_VAR_COPY([b], [$foo])
|
| 13903 | |
echo "$a $b"
|
| 13904 | |
@end example
|
| 13905 | |
|
| 13906 | |
When it is necessary to access the contents of an indirect variable
|
| 13907 | |
inside a shell double-quoted context, the recommended idiom is to first
|
| 13908 | |
copy the contents into a temporary literal shell variable.
|
| 13909 | |
|
| 13910 | |
@smallexample
|
| 13911 | |
for header in stdint_h inttypes_h ; do
|
| 13912 | |
AS_VAR_COPY([var], [ac_cv_header_$header])
|
| 13913 | |
echo "$header detected: $var"
|
| 13914 | |
done
|
| 13915 | |
@end smallexample
|
| 13916 | |
@end defmac
|
| 13917 | |
|
| 13918 | |
@comment AS_VAR_GET is intentionally undocumented; it can't handle
|
| 13919 | |
@comment trailing newlines uniformly, and forks too much.
|
| 13920 | |
|
| 13921 | |
@defmac AS_VAR_IF (@var{var}, @ovar{word}, @ovar{if-equal}, @
|
| 13922 | |
@ovar{if-not-equal})
|
| 13923 | |
@asindex{VAR_IF}
|
| 13924 | |
Output a shell conditional statement. If the contents of the
|
| 13925 | |
polymorphic shell variable @var{var} match the string @var{word},
|
| 13926 | |
execute @var{if-equal}; otherwise execute @var{if-not-equal}. @var{word}
|
| 13927 | |
must be a single shell word (typically a quoted string). Avoids
|
| 13928 | |
shell bugs if an interrupt signal arrives while a command substitution
|
| 13929 | |
in @var{var} is being expanded.
|
| 13930 | |
@end defmac
|
| 13931 | |
|
| 13932 | |
@defmac AS_VAR_PUSHDEF (@var{m4-name}, @var{value})
|
| 13933 | |
@defmacx AS_VAR_POPDEF (@var{m4-name})
|
| 13934 | |
@asindex{VAR_PUSHDEF}
|
| 13935 | |
@asindex{VAR_POPDEF}
|
| 13936 | |
@cindex composing variable names
|
| 13937 | |
@cindex variable names, composing
|
| 13938 | |
A common M4sh idiom involves composing shell variable names from an m4
|
| 13939 | |
argument (for example, writing a macro that uses a cache variable).
|
| 13940 | |
@var{value} can be an arbitrary string, which will be transliterated
|
| 13941 | |
into a valid shell name by @code{AS_TR_SH}. In order to access the
|
| 13942 | |
composed variable name based on @var{value}, it is easier to declare a
|
| 13943 | |
temporary m4 macro @var{m4-name} with @code{AS_VAR_PUSHDEF}, then use
|
| 13944 | |
that macro as the argument to subsequent @code{AS_VAR} macros as a
|
| 13945 | |
polymorphic variable name, and finally free the temporary macro with
|
| 13946 | |
@code{AS_VAR_POPDEF}. These macros are often followed with @code{dnl},
|
| 13947 | |
to avoid excess newlines in the output.
|
| 13948 | |
|
| 13949 | |
Here is an involved example, that shows the power of writing macros that
|
| 13950 | |
can handle composed shell variable names:
|
| 13951 | |
|
| 13952 | |
@example
|
| 13953 | |
m4_define([MY_CHECK_HEADER],
|
| 13954 | |
[AS_VAR_PUSHDEF([my_Header], [ac_cv_header_$1])dnl
|
| 13955 | |
AS_VAR_IF([my_Header], [yes], [echo "header $1 detected"])dnl
|
| 13956 | |
AS_VAR_POPDEF([my_Header])dnl
|
| 13957 | |
])
|
| 13958 | |
MY_CHECK_HEADER([stdint.h])
|
| 13959 | |
for header in inttypes.h stdlib.h ; do
|
| 13960 | |
MY_CHECK_HEADER([$header])
|
| 13961 | |
done
|
| 13962 | |
@end example
|
| 13963 | |
|
| 13964 | |
@noindent
|
| 13965 | |
In the above example, @code{MY_CHECK_HEADER} can operate on polymorphic
|
| 13966 | |
variable names. In the first invocation, the m4 argument is
|
| 13967 | |
@code{stdint.h}, which transliterates into a literal @code{stdint_h}.
|
| 13968 | |
As a result, the temporary macro @code{my_Header} expands to the literal
|
| 13969 | |
shell name @samp{ac_cv_header_stdint_h}. In the second invocation, the
|
| 13970 | |
m4 argument to @code{MY_CHECK_HEADER} is @code{$header}, and the
|
| 13971 | |
temporary macro @code{my_Header} expands to the indirect shell name
|
| 13972 | |
@samp{$as_my_Header}. During the shell execution of the for loop, when
|
| 13973 | |
@samp{$header} contains @samp{inttypes.h}, then @samp{$as_my_Header}
|
| 13974 | |
contains @samp{ac_cv_header_inttypes_h}. If this script is then run on a
|
| 13975 | |
platform where all three headers have been previously detected, the
|
| 13976 | |
output of the script will include:
|
| 13977 | |
|
| 13978 | |
@smallexample
|
| 13979 | |
header stdint.h detected
|
| 13980 | |
header inttypes.h detected
|
| 13981 | |
header stdlib.h detected
|
| 13982 | |
@end smallexample
|
| 13983 | |
@end defmac
|
| 13984 | |
|
| 13985 | |
@defmac AS_VAR_SET (@var{var}, @ovar{value})
|
| 13986 | |
@asindex{VAR_SET}
|
| 13987 | |
Emit shell code to assign the contents of the polymorphic shell variable
|
| 13988 | |
@var{var} to the shell expansion of @var{value}. @var{value} is not
|
| 13989 | |
subject to field splitting or file name expansion, so if command
|
| 13990 | |
substitution is used, it may be done with @samp{`""`} rather than using
|
| 13991 | |
an intermediate variable (@pxref{Shell Substitutions}). However,
|
| 13992 | |
@var{value} does undergo rescanning for additional macro names; behavior
|
| 13993 | |
is unspecified if late expansion results in any shell meta-characters.
|
| 13994 | |
@end defmac
|
| 13995 | |
|
| 13996 | |
@defmac AS_VAR_SET_IF (@var{var}, @ovar{if-set}, @ovar{if-undef})
|
| 13997 | |
@asindex{VAR_SET_IF}
|
| 13998 | |
Emit a shell conditional statement, which executes @var{if-set} if the
|
| 13999 | |
polymorphic shell variable @code{var} is set to any value, and
|
| 14000 | |
@var{if-undef} otherwise.
|
| 14001 | |
@end defmac
|
| 14002 | |
|
| 14003 | |
@defmac AS_VAR_TEST_SET (@var{var})
|
| 14004 | |
@asindex{VAR_TEST_SET}
|
| 14005 | |
Emit a shell statement that results in a successful exit status only if
|
| 14006 | |
the polymorphic shell variable @code{var} is set.
|
| 14007 | |
@end defmac
|
| 14008 | |
|
| 14009 | |
@node Initialization Macros
|
| 14010 | |
@section Initialization Macros
|
| 14011 | |
|
| 14012 | |
@defmac AS_BOURNE_COMPATIBLE
|
| 14013 | |
@asindex{BOURNE_COMPATIBLE}
|
| 14014 | |
Set up the shell to be more compatible with the Bourne shell as
|
| 14015 | |
standardized by Posix, if possible. This may involve setting
|
| 14016 | |
environment variables, or setting options, or similar
|
| 14017 | |
implementation-specific actions. This macro is deprecated, since
|
| 14018 | |
@code{AS_INIT} already invokes it.
|
| 14019 | |
@end defmac
|
| 14020 | |
|
| 14021 | |
@defmac AS_INIT
|
| 14022 | |
@asindex{INIT}
|
| 14023 | |
@evindex LC_ALL
|
| 14024 | |
@evindex SHELL
|
| 14025 | |
Initialize the M4sh environment. This macro calls @code{m4_init}, then
|
| 14026 | |
outputs the @code{#! /bin/sh} line, a notice about where the output was
|
| 14027 | |
generated from, and code to sanitize the environment for the rest of the
|
| 14028 | |
script. Among other initializations, this sets @env{SHELL} to the shell
|
| 14029 | |
chosen to run the script (@pxref{CONFIG_SHELL}), and @env{LC_ALL} to
|
| 14030 | |
ensure the C locale. Finally, it changes the current diversion to
|
| 14031 | |
@code{BODY}. @code{AS_INIT} is called automatically by @code{AC_INIT}
|
| 14032 | |
and @code{AT_INIT}, so shell code in @file{configure},
|
| 14033 | |
@file{config.status}, and @file{testsuite} all benefit from a sanitized
|
| 14034 | |
shell environment.
|
| 14035 | |
@end defmac
|
| 14036 | |
|
| 14037 | |
@defmac AS_INIT_GENERATED (@var{file}, @ovar{comment})
|
| 14038 | |
@asindex{INIT_GENERATED}
|
| 14039 | |
Emit shell code to start the creation of a subsidiary shell script in
|
| 14040 | |
@var{file}, including changing @var{file} to be executable. This macro
|
| 14041 | |
populates the child script with information learned from the parent
|
| 14042 | |
(thus, the emitted code is equivalent in effect, but more efficient,
|
| 14043 | |
than the code output by @code{AS_INIT}, @code{AS_BOURNE_COMPATIBLE}, and
|
| 14044 | |
@code{AS_SHELL_SANITIZE}). If present, @var{comment} is output near the
|
| 14045 | |
beginning of the child, prior to the shell initialization code, and is
|
| 14046 | |
subject to parameter expansion, command substitution, and backslash
|
| 14047 | |
quote removal. The
|
| 14048 | |
parent script should check the exit status after this macro, in case
|
| 14049 | |
@var{file} could not be properly created (for example, if the disk was
|
| 14050 | |
full). If successfully created, the parent script can then proceed to
|
| 14051 | |
append additional M4sh constructs into the child script.
|
| 14052 | |
|
| 14053 | |
Note that the child script starts life without a log file open, so if
|
| 14054 | |
the parent script uses logging (@pxref{AS_MESSAGE_LOG_FD}), you
|
| 14055 | |
must temporarily disable any attempts to use the log file until after
|
| 14056 | |
emitting code to open a log within the child. On the other hand, if the
|
| 14057 | |
parent script has @code{AS_MESSAGE_FD} redirected somewhere besides
|
| 14058 | |
@samp{1}, then the child script already has code that copies stdout to
|
| 14059 | |
that descriptor. Currently, the suggested
|
| 14060 | |
idiom for writing a M4sh shell script from within another script is:
|
| 14061 | |
|
| 14062 | |
@example
|
| 14063 | |
AS_INIT_GENERATED([@var{file}], [[# My child script.
|
| 14064 | |
]]) || @{ AS_ECHO(["Failed to create child script"]); AS_EXIT; @}
|
| 14065 | |
m4_pushdef([AS_MESSAGE_LOG_FD])dnl
|
| 14066 | |
cat >> "@var{file}" <<\__EOF__
|
| 14067 | |
# Code to initialize AS_MESSAGE_LOG_FD
|
| 14068 | |
m4_popdef([AS_MESSAGE_LOG_FD])dnl
|
| 14069 | |
# Additional code
|
| 14070 | |
__EOF__
|
| 14071 | |
@end example
|
| 14072 | |
|
| 14073 | |
This, however, may change in the future as the M4sh interface is
|
| 14074 | |
stabilized further.
|
| 14075 | |
|
| 14076 | |
Also, be aware that use of @env{LINENO} within the child script may
|
| 14077 | |
report line numbers relative to their location in the parent script,
|
| 14078 | |
even when using @code{AS_LINENO_PREPARE}, if the parent script was
|
| 14079 | |
unable to locate a shell with working @env{LINENO} support.
|
| 14080 | |
@end defmac
|
| 14081 | |
|
| 14082 | |
@defmac AS_LINENO_PREPARE
|
| 14083 | |
@asindex{LINENO_PREPARE}
|
| 14084 | |
@evindex LINENO
|
| 14085 | |
Find a shell that supports the special variable @env{LINENO}, which
|
| 14086 | |
contains the number of the currently executing line. This macro is
|
| 14087 | |
automatically invoked by @code{AC_INIT} in configure scripts.
|
| 14088 | |
@end defmac
|
| 14089 | |
|
| 14090 | |
@defmac AS_ME_PREPARE
|
| 14091 | |
@asindex{ME_PREPARE}
|
| 14092 | |
Set up variable @env{as_me} to be the basename of the currently executing
|
| 14093 | |
script. This macro is automatically invoked by @code{AC_INIT} in
|
| 14094 | |
configure scripts.
|
| 14095 | |
@end defmac
|
| 14096 | |
|
| 14097 | |
@defmac AS_TMPDIR (@var{prefix}, @dvar{dir, $@{TMPDIR:=/tmp@}})
|
| 14098 | |
@asindex{TMPDIR}
|
| 14099 | |
@evindex TMPDIR
|
| 14100 | |
@ovindex tmp
|
| 14101 | |
Create, as safely as possible, a temporary sub-directory within
|
| 14102 | |
@var{dir} with a name starting with @var{prefix}. @var{prefix} should
|
| 14103 | |
be 2-4 characters, to make it slightly easier to identify the owner of
|
| 14104 | |
the directory. If @var{dir} is omitted, then the value of @env{TMPDIR}
|
| 14105 | |
will be used (defaulting to @samp{/tmp}). On success, the name of the
|
| 14106 | |
newly created directory is stored in the shell variable @code{tmp}. On
|
| 14107 | |
error, the script is aborted.
|
| 14108 | |
|
| 14109 | |
Typically, this macro is coupled with some exit traps to delete the created
|
| 14110 | |
directory and its contents on exit or interrupt. However, there is a
|
| 14111 | |
slight window between when the directory is created and when the name is
|
| 14112 | |
actually known to the shell, so an interrupt at the right moment might
|
| 14113 | |
leave the temporary directory behind. Hence it is important to use a
|
| 14114 | |
@var{prefix} that makes it easier to determine if a leftover temporary
|
| 14115 | |
directory from an interrupted script is safe to delete.
|
| 14116 | |
|
| 14117 | |
The use of the output variable @samp{$tmp} rather than something in the
|
| 14118 | |
@samp{as_} namespace is historical; it has the unfortunate consequence
|
| 14119 | |
that reusing this otherwise common name for any other purpose inside
|
| 14120 | |
your script has the potential to break any cleanup traps designed to
|
| 14121 | |
remove the temporary directory.
|
| 14122 | |
@end defmac
|
| 14123 | |
|
| 14124 | |
@defmac AS_SHELL_SANITIZE
|
| 14125 | |
@asindex{SHELL_SANITIZE}
|
| 14126 | |
Initialize the shell suitably for @command{configure} scripts. This has
|
| 14127 | |
the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
|
| 14128 | |
environment variables for predictable results from configuration tests.
|
| 14129 | |
For example, it sets @env{LC_ALL} to change to the default C locale.
|
| 14130 | |
@xref{Special Shell Variables}. This macro is deprecated, since
|
| 14131 | |
@code{AS_INIT} already invokes it.
|
| 14132 | |
@end defmac
|
| 14133 | |
|
| 14134 | |
|
| 14135 | |
@node File Descriptor Macros
|
| 14136 | |
@section File Descriptor Macros
|
| 14137 | |
@cindex input
|
| 14138 | |
@cindex standard input
|
| 14139 | |
@cindex file descriptors
|
| 14140 | |
@cindex descriptors
|
| 14141 | |
@cindex low-level output
|
| 14142 | |
@cindex output, low-level
|
| 14143 | |
|
| 14144 | |
The following macros define file descriptors used to output messages
|
| 14145 | |
(or input values) from @file{configure} scripts.
|
| 14146 | |
For example:
|
| 14147 | |
|
| 14148 | |
@example
|
| 14149 | |
echo "$wombats found" >&AS_MESSAGE_LOG_FD
|
| 14150 | |
echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
|
| 14151 | |
read kangaroos <&AS_ORIGINAL_STDIN_FD`
|
| 14152 | |
@end example
|
| 14153 | |
|
| 14154 | |
@noindent
|
| 14155 | |
However doing so is seldom needed, because Autoconf provides higher
|
| 14156 | |
level macros as described below.
|
| 14157 | |
|
| 14158 | |
@defmac AS_MESSAGE_FD
|
| 14159 | |
@asindex{MESSAGE_FD}
|
| 14160 | |
The file descriptor for @samp{checking for...} messages and results.
|
| 14161 | |
By default, @code{AS_INIT} sets this to @samp{1} for standalone M4sh
|
| 14162 | |
clients. However, @code{AC_INIT} shuffles things around to another file
|
| 14163 | |
descriptor, in order to allow the @option{-q} option of
|
| 14164 | |
@command{configure} to choose whether messages should go to the script's
|
| 14165 | |
standard output or be discarded.
|
| 14166 | |
|
| 14167 | |
If you want to display some messages, consider using one of the printing
|
| 14168 | |
macros (@pxref{Printing Messages}) instead. Copies of messages output
|
| 14169 | |
via these macros are also recorded in @file{config.log}.
|
| 14170 | |
@end defmac
|
| 14171 | |
|
| 14172 | |
@anchor{AS_MESSAGE_LOG_FD}
|
| 14173 | |
@defmac AS_MESSAGE_LOG_FD
|
| 14174 | |
@asindex{MESSAGE_LOG_FD}
|
| 14175 | |
This must either be empty, or expand to a file descriptor for log
|
| 14176 | |
messages. By default, @code{AS_INIT} sets this macro to the empty
|
| 14177 | |
string for standalone M4sh clients, thus disabling logging. However,
|
| 14178 | |
@code{AC_INIT} shuffles things around so that both @command{configure}
|
| 14179 | |
and @command{config.status} use @file{config.log} for log messages.
|
| 14180 | |
Macros that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
|
| 14181 | |
Compiler}), redirect all output to this descriptor. You may want to do
|
| 14182 | |
so if you develop such a low-level macro.
|
| 14183 | |
@end defmac
|
| 14184 | |
|
| 14185 | |
@defmac AS_ORIGINAL_STDIN_FD
|
| 14186 | |
@asindex{ORIGINAL_STDIN_FD}
|
| 14187 | |
This must expand to a file descriptor for the original standard input.
|
| 14188 | |
By default, @code{AS_INIT} sets this macro to @samp{0} for standalone
|
| 14189 | |
M4sh clients. However, @code{AC_INIT} shuffles things around for
|
| 14190 | |
safety.
|
| 14191 | |
|
| 14192 | |
When @command{configure} runs, it may accidentally execute an
|
| 14193 | |
interactive command that has the same name as the non-interactive meant
|
| 14194 | |
to be used or checked. If the standard input was the terminal, such
|
| 14195 | |
interactive programs would cause @command{configure} to stop, pending
|
| 14196 | |
some user input. Therefore @command{configure} redirects its standard
|
| 14197 | |
input from @file{/dev/null} during its initialization. This is not
|
| 14198 | |
normally a problem, since @command{configure} normally does not need
|
| 14199 | |
user input.
|
| 14200 | |
|
| 14201 | |
In the extreme case where your @file{configure} script really needs to
|
| 14202 | |
obtain some values from the original standard input, you can read them
|
| 14203 | |
explicitly from @code{AS_ORIGINAL_STDIN_FD}.
|
| 14204 | |
@end defmac
|
| 14205 | |
|
| 14206 | |
|
| 14207 | |
@c =================================================== Writing Autoconf Macros.
|
| 14208 | |
|
| 14209 | |
@node Writing Autoconf Macros
|
| 14210 | |
@chapter Writing Autoconf Macros
|
| 14211 | |
|
| 14212 | |
When you write a feature test that could be applicable to more than one
|
| 14213 | |
software package, the best thing to do is encapsulate it in a new macro.
|
| 14214 | |
Here are some instructions and guidelines for writing Autoconf macros.
|
| 14215 | |
|
| 14216 | |
@menu
|
| 14217 | |
* Macro Definitions:: Basic format of an Autoconf macro
|
| 14218 | |
* Macro Names:: What to call your new macros
|
| 14219 | |
* Reporting Messages:: Notifying @command{autoconf} users
|
| 14220 | |
* Dependencies Between Macros:: What to do when macros depend on other macros
|
| 14221 | |
* Obsoleting Macros:: Warning about old ways of doing things
|
| 14222 | |
* Coding Style:: Writing Autoconf macros @`a la Autoconf
|
| 14223 | |
@end menu
|
| 14224 | |
|
| 14225 | |
@node Macro Definitions
|
| 14226 | |
@section Macro Definitions
|
| 14227 | |
|
| 14228 | |
@defmac AC_DEFUN (@var{name}, @ovar{body})
|
| 14229 | |
@acindex{DEFUN}
|
| 14230 | |
Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
|
| 14231 | |
similar to the M4 builtin @code{m4_define} macro; this creates a macro
|
| 14232 | |
named @var{name} and with @var{body} as its expansion. In addition to
|
| 14233 | |
defining a macro, @code{AC_DEFUN} adds to it some code that is used to
|
| 14234 | |
constrain the order in which macros are called, while avoiding redundant
|
| 14235 | |
output (@pxref{Prerequisite Macros}).
|
| 14236 | |
@end defmac
|
| 14237 | |
|
| 14238 | |
An Autoconf macro definition looks like this:
|
| 14239 | |
|
| 14240 | |
@example
|
| 14241 | |
AC_DEFUN(@var{macro-name}, @var{macro-body})
|
| 14242 | |
@end example
|
| 14243 | |
|
| 14244 | |
You can refer to any arguments passed to the macro as @samp{$1},
|
| 14245 | |
@samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
|
| 14246 | |
GNU M4}, for more complete information on writing M4 macros.
|
| 14247 | |
|
| 14248 | |
Most macros fall in one of two general categories. The first category
|
| 14249 | |
includes macros which take arguments, in order to generate output
|
| 14250 | |
parameterized by those arguments. Macros in this category are designed
|
| 14251 | |
to be directly expanded, often multiple times, and should not be used as
|
| 14252 | |
the argument to @code{AC_REQUIRE}. The other category includes macros
|
| 14253 | |
which are shorthand for a fixed block of text, and therefore do not take
|
| 14254 | |
arguments. For this category of macros, directly expanding the macro
|
| 14255 | |
multiple times results in redundant output, so it is more common to use
|
| 14256 | |
the macro as the argument to @code{AC_REQUIRE}, or to declare the macro
|
| 14257 | |
with @code{AC_DEFUN_ONCE} (@pxref{One-Shot Macros}).
|
| 14258 | |
|
| 14259 | |
Be sure to properly quote both the @var{macro-body} @emph{and} the
|
| 14260 | |
@var{macro-name} to avoid any problems if the macro happens to have
|
| 14261 | |
been previously defined.
|
| 14262 | |
|
| 14263 | |
Each macro should have a header comment that gives its prototype, and a
|
| 14264 | |
brief description. When arguments have default values, display them in
|
| 14265 | |
the prototype. For example:
|
| 14266 | |
|
| 14267 | |
@example
|
| 14268 | |
# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
|
| 14269 | |
# --------------------------------------
|
| 14270 | |
m4_define([AC_MSG_ERROR],
|
| 14271 | |
[@{ AS_MESSAGE([error: $1], [2])
|
| 14272 | |
exit m4_default([$2], [1]); @}])
|
| 14273 | |
@end example
|
| 14274 | |
|
| 14275 | |
Comments about the macro should be left in the header comment. Most
|
| 14276 | |
other comments make their way into @file{configure}, so just keep
|
| 14277 | |
using @samp{#} to introduce comments.
|
| 14278 | |
|
| 14279 | |
@cindex @code{dnl}
|
| 14280 | |
If you have some special comments about pure M4 code, comments
|
| 14281 | |
that make no sense in @file{configure} and in the header comment, then
|
| 14282 | |
use the builtin @code{dnl}: it causes M4 to discard the text
|
| 14283 | |
through the next newline.
|
| 14284 | |
|
| 14285 | |
Keep in mind that @code{dnl} is rarely needed to introduce comments;
|
| 14286 | |
@code{dnl} is more useful to get rid of the newlines following macros
|
| 14287 | |
that produce no output, such as @code{AC_REQUIRE}.
|
| 14288 | |
|
| 14289 | |
Public third-party macros need to use @code{AC_DEFUN}, and not
|
| 14290 | |
@code{m4_define}, in order to be found by @command{aclocal}
|
| 14291 | |
(@pxref{Extending aclocal,,, automake, GNU Automake}).
|
| 14292 | |
Additionally, if it is ever determined that a macro should be made
|
| 14293 | |
obsolete, it is easy to convert from @code{AC_DEFUN} to @code{AU_DEFUN}
|
| 14294 | |
in order to have @command{autoupdate} assist the user in choosing a
|
| 14295 | |
better alternative, but there is no corresponding way to make
|
| 14296 | |
@code{m4_define} issue an upgrade notice (@pxref{AU_DEFUN}).
|
| 14297 | |
|
| 14298 | |
There is another subtle, but important, difference between using
|
| 14299 | |
@code{m4_define} and @code{AC_DEFUN}: only the former is unaffected by
|
| 14300 | |
@code{AC_REQUIRE}. When writing a file, it is always safe to replace a
|
| 14301 | |
block of text with a @code{m4_define} macro that will expand to the same
|
| 14302 | |
text. But replacing a block of text with an @code{AC_DEFUN} macro with
|
| 14303 | |
the same content does not necessarily give the same results, because it
|
| 14304 | |
changes the location where any embedded but unsatisfied
|
| 14305 | |
@code{AC_REQUIRE} invocations within the block will be expanded. For an
|
| 14306 | |
example of this, see @ref{Expanded Before Required}.
|
| 14307 | |
|
| 14308 | |
@node Macro Names
|
| 14309 | |
@section Macro Names
|
| 14310 | |
|
| 14311 | |
All of the public Autoconf macros have all-uppercase names in the
|
| 14312 | |
namespace @samp{^AC_} to prevent them from accidentally conflicting with
|
| 14313 | |
other text; Autoconf also reserves the namespace @samp{^_AC_} for
|
| 14314 | |
internal macros. All shell variables that they use for internal
|
| 14315 | |
purposes have mostly-lowercase names starting with @samp{ac_}. Autoconf
|
| 14316 | |
also uses here-document delimiters in the namespace @samp{^_AC[A-Z]}. During
|
| 14317 | |
@command{configure}, files produced by Autoconf make heavy use of the
|
| 14318 | |
file system namespace @samp{^conf}.
|
| 14319 | |
|
| 14320 | |
Since Autoconf is built on top of M4sugar (@pxref{Programming in
|
| 14321 | |
M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
|
| 14322 | |
of those namespaces (@samp{^_?\(m4\|AS\)_}). And since
|
| 14323 | |
@file{configure.ac} is also designed to be scanned by Autoheader,
|
| 14324 | |
Autoscan, Autoupdate, and Automake, you should be aware of the
|
| 14325 | |
@samp{^_?A[HNUM]_} namespaces. In general, you @emph{should not use}
|
| 14326 | |
the namespace of a package that does not own the macro or shell code you
|
| 14327 | |
are writing.
|
| 14328 | |
|
| 14329 | |
To ensure that your macros don't conflict with present or future
|
| 14330 | |
Autoconf macros, you should prefix your own macro names and any shell
|
| 14331 | |
variables they use with some other sequence. Possibilities include your
|
| 14332 | |
initials, or an abbreviation for the name of your organization or
|
| 14333 | |
software package. Historically, people have not always followed the
|
| 14334 | |
rule of using a namespace appropriate for their package, and this has
|
| 14335 | |
made it difficult for determining the origin of a macro (and where to
|
| 14336 | |
report bugs about that macro), as well as difficult for the true
|
| 14337 | |
namespace owner to add new macros without interference from pre-existing
|
| 14338 | |
uses of third-party macros. Perhaps the best example of this confusion
|
| 14339 | |
is the @code{AM_GNU_GETTEXT} macro, which belongs, not to Automake, but
|
| 14340 | |
to Gettext.
|
| 14341 | |
|
| 14342 | |
Most of the Autoconf macros' names follow a structured naming convention
|
| 14343 | |
that indicates the kind of feature check by the name. The macro names
|
| 14344 | |
consist of several words, separated by underscores, going from most
|
| 14345 | |
general to most specific. The names of their cache variables use the
|
| 14346 | |
same convention (@pxref{Cache Variable Names}, for more information on
|
| 14347 | |
them).
|
| 14348 | |
|
| 14349 | |
The first word of the name after the namespace initials (such as
|
| 14350 | |
@samp{AC_}) usually tells the category
|
| 14351 | |
of the feature being tested. Here are the categories used in Autoconf for
|
| 14352 | |
specific test macros, the kind of macro that you are more likely to
|
| 14353 | |
write. They are also used for cache variables, in all-lowercase. Use
|
| 14354 | |
them where applicable; where they're not, invent your own categories.
|
| 14355 | |
|
| 14356 | |
@table @code
|
| 14357 | |
@item C
|
| 14358 | |
C language builtin features.
|
| 14359 | |
@item DECL
|
| 14360 | |
Declarations of C variables in header files.
|
| 14361 | |
@item FUNC
|
| 14362 | |
Functions in libraries.
|
| 14363 | |
@item GROUP
|
| 14364 | |
Posix group owners of files.
|
| 14365 | |
@item HEADER
|
| 14366 | |
Header files.
|
| 14367 | |
@item LIB
|
| 14368 | |
C libraries.
|
| 14369 | |
@item PROG
|
| 14370 | |
The base names of programs.
|
| 14371 | |
@item MEMBER
|
| 14372 | |
Members of aggregates.
|
| 14373 | |
@item SYS
|
| 14374 | |
Operating system features.
|
| 14375 | |
@item TYPE
|
| 14376 | |
C builtin or declared types.
|
| 14377 | |
@item VAR
|
| 14378 | |
C variables in libraries.
|
| 14379 | |
@end table
|
| 14380 | |
|
| 14381 | |
After the category comes the name of the particular feature being
|
| 14382 | |
tested. Any further words in the macro name indicate particular aspects
|
| 14383 | |
of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
|
| 14384 | |
C compiler supports ISO Standard C.
|
| 14385 | |
|
| 14386 | |
An internal macro should have a name that starts with an underscore;
|
| 14387 | |
Autoconf internals should therefore start with @samp{_AC_}.
|
| 14388 | |
Additionally, a macro that is an internal subroutine of another macro
|
| 14389 | |
should have a name that starts with an underscore and the name of that
|
| 14390 | |
other macro, followed by one or more words saying what the internal
|
| 14391 | |
macro does. For example, @code{AC_PATH_X} has internal macros
|
| 14392 | |
@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
|
| 14393 | |
|
| 14394 | |
@node Reporting Messages
|
| 14395 | |
@section Reporting Messages
|
| 14396 | |
@cindex Messages, from @command{autoconf}
|
| 14397 | |
|
| 14398 | |
When macros statically diagnose abnormal situations, benign or fatal, it
|
| 14399 | |
is possible to make @command{autoconf} detect the problem, and refuse to
|
| 14400 | |
create @file{configure} in the case of an error. The macros in this
|
| 14401 | |
section are considered obsolescent, and new code should use M4sugar
|
| 14402 | |
macros for this purpose, see @ref{Diagnostic Macros}.
|
| 14403 | |
|
| 14404 | |
On the other hand, it is possible to want to detect errors when
|
| 14405 | |
@command{configure} is run, which are dependent on the environment of
|
| 14406 | |
the user rather than the maintainer. For dynamic diagnostics, see
|
| 14407 | |
@ref{Printing Messages}.
|
| 14408 | |
|
| 14409 | |
@defmac AC_DIAGNOSE (@var{category}, @var{message})
|
| 14410 | |
@acindex{DIAGNOSE}
|
| 14411 | |
Report @var{message} as a warning (or as an error if requested by the
|
| 14412 | |
user) if warnings of the @var{category} are turned on. This macro is
|
| 14413 | |
obsolescent; you are encouraged to use:
|
| 14414 | |
@example
|
| 14415 | |
m4_warn([@var{category}], [@var{message}])
|
| 14416 | |
@end example
|
| 14417 | |
@noindent
|
| 14418 | |
instead. @xref{m4_warn}, for more details, including valid
|
| 14419 | |
@var{category} names.
|
| 14420 | |
@end defmac
|
| 14421 | |
|
| 14422 | |
@defmac AC_WARNING (@var{message})
|
| 14423 | |
@acindex{WARNING}
|
| 14424 | |
Report @var{message} as a syntax warning. This macro is obsolescent;
|
| 14425 | |
you are encouraged to use:
|
| 14426 | |
@example
|
| 14427 | |
m4_warn([syntax], [@var{message}])
|
| 14428 | |
@end example
|
| 14429 | |
@noindent
|
| 14430 | |
instead. @xref{m4_warn}, for more details, as well as better
|
| 14431 | |
finer-grained categories of warnings (not all problems have to do with
|
| 14432 | |
syntax).
|
| 14433 | |
@end defmac
|
| 14434 | |
|
| 14435 | |
@defmac AC_FATAL (@var{message})
|
| 14436 | |
@acindex{FATAL}
|
| 14437 | |
Report a severe error @var{message}, and have @command{autoconf} die.
|
| 14438 | |
This macro is obsolescent; you are encouraged to use:
|
| 14439 | |
@example
|
| 14440 | |
m4_fatal([@var{message}])
|
| 14441 | |
@end example
|
| 14442 | |
@noindent
|
| 14443 | |
instead. @xref{m4_fatal}, for more details.
|
| 14444 | |
@end defmac
|
| 14445 | |
|
| 14446 | |
When the user runs @samp{autoconf -W error}, warnings from
|
| 14447 | |
@code{m4_warn} (including those issued through @code{AC_DIAGNOSE} and
|
| 14448 | |
@code{AC_WARNING}) are reported as errors, see @ref{autoconf Invocation}.
|
| 14449 | |
|
| 14450 | |
@node Dependencies Between Macros
|
| 14451 | |
@section Dependencies Between Macros
|
| 14452 | |
@cindex Dependencies between macros
|
| 14453 | |
|
| 14454 | |
Some Autoconf macros depend on other macros having been called first in
|
| 14455 | |
order to work correctly. Autoconf provides a way to ensure that certain
|
| 14456 | |
macros are called if needed and a way to warn the user if macros are
|
| 14457 | |
called in an order that might cause incorrect operation.
|
| 14458 | |
|
| 14459 | |
@menu
|
| 14460 | |
* Prerequisite Macros:: Ensuring required information
|
| 14461 | |
* Suggested Ordering:: Warning about possible ordering problems
|
| 14462 | |
* One-Shot Macros:: Ensuring a macro is called only once
|
| 14463 | |
@end menu
|
| 14464 | |
|
| 14465 | |
@node Prerequisite Macros
|
| 14466 | |
@subsection Prerequisite Macros
|
| 14467 | |
@cindex Prerequisite macros
|
| 14468 | |
@cindex Macros, prerequisites
|
| 14469 | |
|
| 14470 | |
A macro that you write might need to use values that have previously
|
| 14471 | |
been computed by other macros. For example, @code{AC_DECL_YYTEXT}
|
| 14472 | |
examines the output of @code{flex} or @code{lex}, so it depends on
|
| 14473 | |
@code{AC_PROG_LEX} having been called first to set the shell variable
|
| 14474 | |
@code{LEX}.
|
| 14475 | |
|
| 14476 | |
Rather than forcing the user of the macros to keep track of the
|
| 14477 | |
dependencies between them, you can use the @code{AC_REQUIRE} macro to do
|
| 14478 | |
it automatically. @code{AC_REQUIRE} can ensure that a macro is only
|
| 14479 | |
called if it is needed, and only called once.
|
| 14480 | |
|
| 14481 | |
@defmac AC_REQUIRE (@var{macro-name})
|
| 14482 | |
@acindex{REQUIRE}
|
| 14483 | |
If the M4 macro @var{macro-name} has not already been called, call it
|
| 14484 | |
(without any arguments). Make sure to quote @var{macro-name} with
|
| 14485 | |
square brackets. @var{macro-name} must have been defined using
|
| 14486 | |
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
|
| 14487 | |
that it has been called.
|
| 14488 | |
|
| 14489 | |
@code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
|
| 14490 | |
must not be called from the top level. Also, it does not make sense to
|
| 14491 | |
require a macro that takes parameters.
|
| 14492 | |
@end defmac
|
| 14493 | |
|
| 14494 | |
@code{AC_REQUIRE} is often misunderstood. It really implements
|
| 14495 | |
dependencies between macros in the sense that if one macro depends upon
|
| 14496 | |
another, the latter is expanded @emph{before} the body of the
|
| 14497 | |
former. To be more precise, the required macro is expanded before
|
| 14498 | |
the outermost defined macro in the current expansion stack.
|
| 14499 | |
In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
|
| 14500 | |
@code{FOO}. For instance, this definition of macros:
|
| 14501 | |
|
| 14502 | |
@example
|
| 14503 | |
@group
|
| 14504 | |
AC_DEFUN([TRAVOLTA],
|
| 14505 | |
[test "$body_temperature_in_celsius" -gt "38" &&
|
| 14506 | |
dance_floor=occupied])
|
| 14507 | |
AC_DEFUN([NEWTON_JOHN],
|
| 14508 | |
[test "x$hair_style" = xcurly &&
|
| 14509 | |
dance_floor=occupied])
|
| 14510 | |
@end group
|
| 14511 | |
|
| 14512 | |
@group
|
| 14513 | |
AC_DEFUN([RESERVE_DANCE_FLOOR],
|
| 14514 | |
[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
|
| 14515 | |
AC_REQUIRE([TRAVOLTA])
|
| 14516 | |
AC_REQUIRE([NEWTON_JOHN])
|
| 14517 | |
fi])
|
| 14518 | |
@end group
|
| 14519 | |
@end example
|
| 14520 | |
|
| 14521 | |
@noindent
|
| 14522 | |
with this @file{configure.ac}
|
| 14523 | |
|
| 14524 | |
@example
|
| 14525 | |
AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
|
| 14526 | |
RESERVE_DANCE_FLOOR
|
| 14527 | |
if test "x$dance_floor" = xoccupied; then
|
| 14528 | |
AC_MSG_ERROR([cannot pick up here, let's move])
|
| 14529 | |
fi
|
| 14530 | |
@end example
|
| 14531 | |
|
| 14532 | |
@noindent
|
| 14533 | |
does not leave you with a better chance to meet a kindred soul at
|
| 14534 | |
other times than Saturday night since it expands into:
|
| 14535 | |
|
| 14536 | |
@example
|
| 14537 | |
@group
|
| 14538 | |
test "$body_temperature_in_Celsius" -gt "38" &&
|
| 14539 | |
dance_floor=occupied
|
| 14540 | |
test "x$hair_style" = xcurly &&
|
| 14541 | |
dance_floor=occupied
|
| 14542 | |
fi
|
| 14543 | |
if date | grep '^Sat.*pm' >/dev/null 2>&1; then
|
| 14544 | |
|
| 14545 | |
|
| 14546 | |
fi
|
| 14547 | |
@end group
|
| 14548 | |
@end example
|
| 14549 | |
|
| 14550 | |
This behavior was chosen on purpose: (i) it prevents messages in
|
| 14551 | |
required macros from interrupting the messages in the requiring macros;
|
| 14552 | |
(ii) it avoids bad surprises when shell conditionals are used, as in:
|
| 14553 | |
|
| 14554 | |
@example
|
| 14555 | |
@group
|
| 14556 | |
if @dots{}; then
|
| 14557 | |
AC_REQUIRE([SOME_CHECK])
|
| 14558 | |
fi
|
| 14559 | |
@dots{}
|
| 14560 | |
SOME_CHECK
|
| 14561 | |
@end group
|
| 14562 | |
@end example
|
| 14563 | |
|
| 14564 | |
However, this implementation can lead to another class of problems.
|
| 14565 | |
Consider the case where an outer macro first expands, then indirectly
|
| 14566 | |
requires, an inner macro:
|
| 14567 | |
|
| 14568 | |
@example
|
| 14569 | |
AC_DEFUN([TESTA], [[echo in A
|
| 14570 | |
if test -n "$SEEN_A" ; then echo duplicate ; fi
|
| 14571 | |
SEEN_A=:]])
|
| 14572 | |
AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B
|
| 14573 | |
if test -z "$SEEN_A" ; then echo bug ; fi]])
|
| 14574 | |
AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
|
| 14575 | |
AC_DEFUN([OUTER], [[echo in OUTER]
|
| 14576 | |
TESTA
|
| 14577 | |
TESTC])
|
| 14578 | |
OUTER
|
| 14579 | |
@end example
|
| 14580 | |
|
| 14581 | |
@noindent
|
| 14582 | |
Prior to Autoconf 2.64, the implementation of @code{AC_REQUIRE}
|
| 14583 | |
recognized that @code{TESTB} needed to be hoisted prior to the expansion
|
| 14584 | |
of @code{OUTER}, but because @code{TESTA} had already been directly
|
| 14585 | |
expanded, it failed to hoist @code{TESTA}. Therefore, the expansion of
|
| 14586 | |
@code{TESTB} occurs prior to its prerequisites, leading to the following
|
| 14587 | |
output:
|
| 14588 | |
|
| 14589 | |
@example
|
| 14590 | |
in B
|
| 14591 | |
bug
|
| 14592 | |
in OUTER
|
| 14593 | |
in A
|
| 14594 | |
in C
|
| 14595 | |
@end example
|
| 14596 | |
|
| 14597 | |
@noindent
|
| 14598 | |
Newer Autoconf is smart enough to recognize this situation, and hoists
|
| 14599 | |
@code{TESTA} even though it has already been expanded, but issues a
|
| 14600 | |
syntax warning in the process. This is because the hoisted expansion of
|
| 14601 | |
@code{TESTA} defeats the purpose of using @code{AC_REQUIRE} to avoid
|
| 14602 | |
redundant code, and causes its own set of problems if the hoisted macro
|
| 14603 | |
is not idempotent:
|
| 14604 | |
|
| 14605 | |
@example
|
| 14606 | |
in A
|
| 14607 | |
in B
|
| 14608 | |
in OUTER
|
| 14609 | |
in A
|
| 14610 | |
duplicate
|
| 14611 | |
in C
|
| 14612 | |
@end example
|
| 14613 | |
|
| 14614 | |
The bug is not in Autoconf, but in the macro definitions. If you ever
|
| 14615 | |
pass a particular macro name to @code{AC_REQUIRE}, then you are implying
|
| 14616 | |
that the macro only needs to be expanded once. But to enforce this,
|
| 14617 | |
either the macro must be declared with @code{AC_DEFUN_ONCE} (although
|
| 14618 | |
this only helps in Autoconf 2.64 or newer), or all
|
| 14619 | |
uses of that macro should be through @code{AC_REQUIRE}; directly
|
| 14620 | |
expanding the macro defeats the point of using @code{AC_REQUIRE} to
|
| 14621 | |
eliminate redundant expansion. In the example, this rule of thumb was
|
| 14622 | |
violated because @code{TESTB} requires @code{TESTA} while @code{OUTER}
|
| 14623 | |
directly expands it. One way of fixing the bug is to factor
|
| 14624 | |
@code{TESTA} into two macros, the portion designed for direct and
|
| 14625 | |
repeated use (here, named @code{TESTA}), and the portion designed for
|
| 14626 | |
one-shot output and used only inside @code{AC_REQUIRE} (here, named
|
| 14627 | |
@code{TESTA_PREREQ}). Then, by fixing all clients to use the correct
|
| 14628 | |
calling convention according to their needs:
|
| 14629 | |
|
| 14630 | |
@example
|
| 14631 | |
AC_DEFUN([TESTA], [AC_REQUIRE([TESTA_PREREQ])[echo in A]])
|
| 14632 | |
AC_DEFUN([TESTA_PREREQ], [[echo in A_PREREQ
|
| 14633 | |
if test -n "$SEEN_A" ; then echo duplicate ; fi
|
| 14634 | |
SEEN_A=:]])
|
| 14635 | |
AC_DEFUN([TESTB], [AC_REQUIRE([TESTA_PREREQ])[echo in B
|
| 14636 | |
if test -z "$SEEN_A" ; then echo bug ; fi]])
|
| 14637 | |
AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
|
| 14638 | |
AC_DEFUN([OUTER], [[echo in OUTER]
|
| 14639 | |
TESTA
|
| 14640 | |
TESTC])
|
| 14641 | |
OUTER
|
| 14642 | |
@end example
|
| 14643 | |
|
| 14644 | |
@noindent
|
| 14645 | |
the resulting output will then obey all dependency rules and avoid any
|
| 14646 | |
syntax warnings, whether the script is built with old or new Autoconf
|
| 14647 | |
versions:
|
| 14648 | |
|
| 14649 | |
@example
|
| 14650 | |
in A_PREREQ
|
| 14651 | |
in B
|
| 14652 | |
in OUTER
|
| 14653 | |
in A
|
| 14654 | |
in C
|
| 14655 | |
@end example
|
| 14656 | |
|
| 14657 | |
The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
|
| 14658 | |
enforce expansion of required macros outside of shell conditional
|
| 14659 | |
constructs. You are furthermore encouraged, although not required, to
|
| 14660 | |
put all @code{AC_REQUIRE} calls
|
| 14661 | |
at the beginning of a macro. You can use @code{dnl} to avoid the empty
|
| 14662 | |
lines they leave.
|
| 14663 | |
|
| 14664 | |
@node Suggested Ordering
|
| 14665 | |
@subsection Suggested Ordering
|
| 14666 | |
@cindex Macros, ordering
|
| 14667 | |
@cindex Ordering macros
|
| 14668 | |
|
| 14669 | |
Some macros should be run before another macro if both are called, but
|
| 14670 | |
neither @emph{requires} that the other be called. For example, a macro
|
| 14671 | |
that changes the behavior of the C compiler should be called before any
|
| 14672 | |
macros that run the C compiler. Many of these dependencies are noted in
|
| 14673 | |
the documentation.
|
| 14674 | |
|
| 14675 | |
Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
|
| 14676 | |
with this kind of dependency appear out of order in a
|
| 14677 | |
@file{configure.ac} file. The warning occurs when creating
|
| 14678 | |
@command{configure} from @file{configure.ac}, not when running
|
| 14679 | |
@command{configure}.
|
| 14680 | |
|
| 14681 | |
For example, @code{AC_PROG_CPP} checks whether the C compiler
|
| 14682 | |
can run the C preprocessor when given the @option{-E} option. It should
|
| 14683 | |
therefore be called after any macros that change which C compiler is
|
| 14684 | |
being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
|
| 14685 | |
|
| 14686 | |
@example
|
| 14687 | |
AC_BEFORE([$0], [AC_PROG_CPP])dnl
|
| 14688 | |
@end example
|
| 14689 | |
|
| 14690 | |
@noindent
|
| 14691 | |
This warns the user if a call to @code{AC_PROG_CPP} has already occurred
|
| 14692 | |
when @code{AC_PROG_CC} is called.
|
| 14693 | |
|
| 14694 | |
@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
|
| 14695 | |
@acindex{BEFORE}
|
| 14696 | |
Make M4 print a warning message to the standard error output if
|
| 14697 | |
@var{called-macro-name} has already been called. @var{this-macro-name}
|
| 14698 | |
should be the name of the macro that is calling @code{AC_BEFORE}. The
|
| 14699 | |
macro @var{called-macro-name} must have been defined using
|
| 14700 | |
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
|
| 14701 | |
that it has been called.
|
| 14702 | |
@end defmac
|
| 14703 | |
|
| 14704 | |
@node One-Shot Macros
|
| 14705 | |
@subsection One-Shot Macros
|
| 14706 | |
@cindex One-shot macros
|
| 14707 | |
@cindex Macros, called once
|
| 14708 | |
|
| 14709 | |
Some macros should be called only once, either because calling them
|
| 14710 | |
multiple time is unsafe, or because it is bad style. For instance
|
| 14711 | |
Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
|
| 14712 | |
(@pxref{Canonicalizing}) are evaluated only once, because it makes no
|
| 14713 | |
sense to run these expensive checks more than once. Such one-shot
|
| 14714 | |
macros can be defined using @code{AC_DEFUN_ONCE}.
|
| 14715 | |
|
| 14716 | |
@defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
|
| 14717 | |
@acindex{DEFUN_ONCE}
|
| 14718 | |
Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
|
| 14719 | |
Definitions}), but add additional logic that guarantees that only the
|
| 14720 | |
first use of the macro (whether by direct expansion or
|
| 14721 | |
@code{AC_REQUIRE}) causes an expansion of @var{macro-body}; the
|
| 14722 | |
expansion will occur before the start of any enclosing macro defined by
|
| 14723 | |
@code{AC_DEFUN}. Subsequent expansions are silently ignored.
|
| 14724 | |
Generally, it does not make sense for @var{macro-body} to use parameters
|
| 14725 | |
such as @code{$1}.
|
| 14726 | |
@end defmac
|
| 14727 | |
|
| 14728 | |
Prior to Autoconf 2.64, a macro defined by @code{AC_DEFUN_ONCE} would
|
| 14729 | |
emit a warning if it was directly expanded a second time, so for
|
| 14730 | |
portability, it is better to use @code{AC_REQUIRE} than direct
|
| 14731 | |
invocation of @var{macro-name} inside a macro defined by @code{AC_DEFUN}
|
| 14732 | |
(@pxref{Prerequisite Macros}).
|
| 14733 | |
|
| 14734 | |
@node Obsoleting Macros
|
| 14735 | |
@section Obsoleting Macros
|
| 14736 | |
@cindex Obsoleting macros
|
| 14737 | |
@cindex Macros, obsoleting
|
| 14738 | |
|
| 14739 | |
Configuration and portability technology has evolved over the years.
|
| 14740 | |
Often better ways of solving a particular problem are developed, or
|
| 14741 | |
ad-hoc approaches are systematized. This process has occurred in many
|
| 14742 | |
parts of Autoconf. One result is that some of the macros are now
|
| 14743 | |
considered @dfn{obsolete}; they still work, but are no longer considered
|
| 14744 | |
the best thing to do, hence they should be replaced with more modern
|
| 14745 | |
macros. Ideally, @command{autoupdate} should replace the old macro calls
|
| 14746 | |
with their modern implementation.
|
| 14747 | |
|
| 14748 | |
Autoconf provides a simple means to obsolete a macro.
|
| 14749 | |
|
| 14750 | |
@anchor{AU_DEFUN}
|
| 14751 | |
@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
|
| 14752 | |
@auindex{DEFUN}
|
| 14753 | |
Define @var{old-macro} as @var{implementation}. The only difference
|
| 14754 | |
with @code{AC_DEFUN} is that the user is warned that
|
| 14755 | |
@var{old-macro} is now obsolete.
|
| 14756 | |
|
| 14757 | |
If she then uses @command{autoupdate}, the call to @var{old-macro} is
|
| 14758 | |
replaced by the modern @var{implementation}. @var{message} should
|
| 14759 | |
include information on what to do after running @command{autoupdate};
|
| 14760 | |
@command{autoupdate} prints it as a warning, and includes it
|
| 14761 | |
in the updated @file{configure.ac} file.
|
| 14762 | |
|
| 14763 | |
The details of this macro are hairy: if @command{autoconf} encounters an
|
| 14764 | |
@code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
|
| 14765 | |
as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
|
| 14766 | |
macros are expanded here, while all other macros are disabled and
|
| 14767 | |
appear literally in the updated @file{configure.ac}.
|
| 14768 | |
@end defmac
|
| 14769 | |
|
| 14770 | |
@defmac AU_ALIAS (@var{old-name}, @var{new-name})
|
| 14771 | |
@auindex{ALIAS}
|
| 14772 | |
Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
|
| 14773 | |
with the same parameters. This happens for example if the macro was renamed.
|
| 14774 | |
@end defmac
|
| 14775 | |
|
| 14776 | |
@node Coding Style
|
| 14777 | |
@section Coding Style
|
| 14778 | |
@cindex Coding style
|
| 14779 | |
|
| 14780 | |
The Autoconf macros follow a strict coding style. You are encouraged to
|
| 14781 | |
follow this style, especially if you intend to distribute your macro,
|
| 14782 | |
either by contributing it to Autoconf itself or the
|
| 14783 | |
@uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
|
| 14784 | |
Archive}, or by other means.
|
| 14785 | |
|
| 14786 | |
The first requirement is to pay great attention to the quotation. For
|
| 14787 | |
more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
|
| 14788 | |
|
| 14789 | |
Do not try to invent new interfaces. It is likely that there is a macro
|
| 14790 | |
in Autoconf that resembles the macro you are defining: try to stick to
|
| 14791 | |
this existing interface (order of arguments, default values, etc.). We
|
| 14792 | |
@emph{are} conscious that some of these interfaces are not perfect;
|
| 14793 | |
nevertheless, when harmless, homogeneity should be preferred over
|
| 14794 | |
creativity.
|
| 14795 | |
|
| 14796 | |
Be careful about clashes both between M4 symbols and between shell
|
| 14797 | |
variables.
|
| 14798 | |
|
| 14799 | |
If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
|
| 14800 | |
you are unlikely to generate conflicts. Nevertheless, when you need to
|
| 14801 | |
set a special value, @emph{avoid using a regular macro name}; rather,
|
| 14802 | |
use an ``impossible'' name. For instance, up to version 2.13, the macro
|
| 14803 | |
@code{AC_SUBST} used to remember what @var{symbol} macros were already defined
|
| 14804 | |
by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
|
| 14805 | |
But since there is a macro named @code{AC_SUBST_FILE}, it was just
|
| 14806 | |
impossible to @samp{AC_SUBST(FILE)}! In this case,
|
| 14807 | |
@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
|
| 14808 | |
have been used (yes, with the parentheses).
|
| 14809 | |
@c or better yet, high-level macros such as @code{m4_expand_once}
|
| 14810 | |
|
| 14811 | |
No Autoconf macro should ever enter the user-variable name space; i.e.,
|
| 14812 | |
except for the variables that are the actual result of running the
|
| 14813 | |
macro, all shell variables should start with @code{ac_}. In
|
| 14814 | |
addition, small macros or any macro that is likely to be embedded in
|
| 14815 | |
other macros should be careful not to use obvious names.
|
| 14816 | |
|
| 14817 | |
@cindex @code{dnl}
|
| 14818 | |
Do not use @code{dnl} to introduce comments: most of the comments you
|
| 14819 | |
are likely to write are either header comments which are not output
|
| 14820 | |
anyway, or comments that should make their way into @file{configure}.
|
| 14821 | |
There are exceptional cases where you do want to comment special M4
|
| 14822 | |
constructs, in which case @code{dnl} is right, but keep in mind that it
|
| 14823 | |
is unlikely.
|
| 14824 | |
|
| 14825 | |
M4 ignores the leading blanks and newlines before each argument.
|
| 14826 | |
Use this feature to
|
| 14827 | |
indent in such a way that arguments are (more or less) aligned with the
|
| 14828 | |
opening parenthesis of the macro being called. For instance, instead of
|
| 14829 | |
|
| 14830 | |
@example
|
| 14831 | |
AC_CACHE_CHECK(for EMX OS/2 environment,
|
| 14832 | |
ac_cv_emxos2,
|
| 14833 | |
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
|
| 14834 | |
[ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
|
| 14835 | |
@end example
|
| 14836 | |
|
| 14837 | |
@noindent
|
| 14838 | |
write
|
| 14839 | |
|
| 14840 | |
@example
|
| 14841 | |
AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
|
| 14842 | |
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
|
| 14843 | |
[ac_cv_emxos2=yes],
|
| 14844 | |
[ac_cv_emxos2=no])])
|
| 14845 | |
@end example
|
| 14846 | |
|
| 14847 | |
@noindent
|
| 14848 | |
or even
|
| 14849 | |
|
| 14850 | |
@example
|
| 14851 | |
AC_CACHE_CHECK([for EMX OS/2 environment],
|
| 14852 | |
[ac_cv_emxos2],
|
| 14853 | |
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
|
| 14854 | |
[return __EMX__;])],
|
| 14855 | |
[ac_cv_emxos2=yes],
|
| 14856 | |
[ac_cv_emxos2=no])])
|
| 14857 | |
@end example
|
| 14858 | |
|
| 14859 | |
When using @code{AC_RUN_IFELSE} or any macro that cannot work when
|
| 14860 | |
cross-compiling, provide a pessimistic value (typically @samp{no}).
|
| 14861 | |
|
| 14862 | |
Feel free to use various tricks to prevent auxiliary tools, such as
|
| 14863 | |
syntax-highlighting editors, from behaving improperly. For instance,
|
| 14864 | |
instead of:
|
| 14865 | |
|
| 14866 | |
@example
|
| 14867 | |
m4_bpatsubst([$1], [$"])
|
| 14868 | |
@end example
|
| 14869 | |
|
| 14870 | |
@noindent
|
| 14871 | |
use
|
| 14872 | |
|
| 14873 | |
@example
|
| 14874 | |
m4_bpatsubst([$1], [$""])
|
| 14875 | |
@end example
|
| 14876 | |
|
| 14877 | |
@noindent
|
| 14878 | |
so that Emacsen do not open an endless ``string'' at the first quote.
|
| 14879 | |
For the same reasons, avoid:
|
| 14880 | |
|
| 14881 | |
@example
|
| 14882 | |
test $[#] != 0
|
| 14883 | |
@end example
|
| 14884 | |
|
| 14885 | |
@noindent
|
| 14886 | |
and use:
|
| 14887 | |
|
| 14888 | |
@example
|
| 14889 | |
test $[@@%:@@] != 0
|
| 14890 | |
@end example
|
| 14891 | |
|
| 14892 | |
@noindent
|
| 14893 | |
Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
|
| 14894 | |
breaking the bracket-matching highlighting from Emacsen. Note the
|
| 14895 | |
preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
|
| 14896 | |
not escape when it is unnecessary. Common examples of useless quotation
|
| 14897 | |
are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
|
| 14898 | |
etc. If you add portability issues to the picture, you'll prefer
|
| 14899 | |
@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
|
| 14900 | |
better than hacking Autoconf @code{:-)}.
|
| 14901 | |
|
| 14902 | |
When using @command{sed}, don't use @option{-e} except for indenting
|
| 14903 | |
purposes. With the @code{s} and @code{y} commands, the preferred
|
| 14904 | |
separator is @samp{/} unless @samp{/} itself might appear in the pattern
|
| 14905 | |
or replacement, in which case you should use @samp{|}, or optionally
|
| 14906 | |
@samp{,} if you know the pattern and replacement cannot contain a file
|
| 14907 | |
name. If none of these characters will do, choose a printable character
|
| 14908 | |
that cannot appear in the pattern or replacement. Characters from the
|
| 14909 | |
set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
|
| 14910 | |
replacement might contain a file name, since they have special meaning
|
| 14911 | |
to the shell and are less likely to occur in file names.
|
| 14912 | |
|
| 14913 | |
@xref{Macro Definitions}, for details on how to define a macro. If a
|
| 14914 | |
macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
|
| 14915 | |
of an @code{AC_REQUIRE} directive, and macros required by other macros
|
| 14916 | |
inside arguments do not need to be expanded before this macro, then
|
| 14917 | |
use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
|
| 14918 | |
Also take into account that public third-party macros need to use
|
| 14919 | |
@code{AC_DEFUN} in order to be found by @command{aclocal}
|
| 14920 | |
(@pxref{Extending aclocal,,, automake, GNU Automake}).
|
| 14921 | |
All the @code{AC_REQUIRE} statements should be at the beginning of the
|
| 14922 | |
macro, and each statement should be followed by @code{dnl}.
|
| 14923 | |
|
| 14924 | |
You should not rely on the number of arguments: instead of checking
|
| 14925 | |
whether an argument is missing, test that it is not empty. It provides
|
| 14926 | |
both a simpler and a more predictable interface to the user, and saves
|
| 14927 | |
room for further arguments.
|
| 14928 | |
|
| 14929 | |
Unless the macro is short, try to leave the closing @samp{])} at the
|
| 14930 | |
beginning of a line, followed by a comment that repeats the name of the
|
| 14931 | |
macro being defined. This introduces an additional newline in
|
| 14932 | |
@command{configure}; normally, that is not a problem, but if you want to
|
| 14933 | |
remove it you can use @samp{[]dnl} on the last line. You can similarly
|
| 14934 | |
use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
|
| 14935 | |
is recommended instead of @samp{dnl} to ensure that M4 does not
|
| 14936 | |
interpret the @samp{dnl} as being attached to the preceding text or
|
| 14937 | |
macro output. For example, instead of:
|
| 14938 | |
|
| 14939 | |
@example
|
| 14940 | |
AC_DEFUN([AC_PATH_X],
|
| 14941 | |
[AC_MSG_CHECKING([for X])
|
| 14942 | |
AC_REQUIRE_CPP()
|
| 14943 | |
@r{# @dots{}omitted@dots{}}
|
| 14944 | |
AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
|
| 14945 | |
fi])
|
| 14946 | |
@end example
|
| 14947 | |
|
| 14948 | |
@noindent
|
| 14949 | |
you would write:
|
| 14950 | |
|
| 14951 | |
@example
|
| 14952 | |
AC_DEFUN([AC_PATH_X],
|
| 14953 | |
[AC_REQUIRE_CPP()[]dnl
|
| 14954 | |
AC_MSG_CHECKING([for X])
|
| 14955 | |
@r{# @dots{}omitted@dots{}}
|
| 14956 | |
AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
|
| 14957 | |
fi[]dnl
|
| 14958 | |
])# AC_PATH_X
|
| 14959 | |
@end example
|
| 14960 | |
|
| 14961 | |
If the macro is long, try to split it into logical chunks. Typically,
|
| 14962 | |
macros that check for a bug in a function and prepare its
|
| 14963 | |
@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
|
| 14964 | |
this setup. Do not hesitate to introduce auxiliary macros to factor
|
| 14965 | |
your code.
|
| 14966 | |
|
| 14967 | |
In order to highlight the recommended coding style, here is a macro
|
| 14968 | |
written the old way:
|
| 14969 | |
|
| 14970 | |
@example
|
| 14971 | |
dnl Check for EMX on OS/2.
|
| 14972 | |
dnl _AC_EMXOS2
|
| 14973 | |
AC_DEFUN(_AC_EMXOS2,
|
| 14974 | |
[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
|
| 14975 | |
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
|
| 14976 | |
ac_cv_emxos2=yes, ac_cv_emxos2=no)])
|
| 14977 | |
test "x$ac_cv_emxos2" = xyes && EMXOS2=yes])
|
| 14978 | |
@end example
|
| 14979 | |
|
| 14980 | |
@noindent
|
| 14981 | |
and the new way:
|
| 14982 | |
|
| 14983 | |
@example
|
| 14984 | |
# _AC_EMXOS2
|
| 14985 | |
# ----------
|
| 14986 | |
# Check for EMX on OS/2.
|
| 14987 | |
m4_define([_AC_EMXOS2],
|
| 14988 | |
[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
|
| 14989 | |
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
|
| 14990 | |
[ac_cv_emxos2=yes],
|
| 14991 | |
[ac_cv_emxos2=no])])
|
| 14992 | |
test "x$ac_cv_emxos2" = xyes && EMXOS2=yes[]dnl
|
| 14993 | |
])# _AC_EMXOS2
|
| 14994 | |
@end example
|
| 14995 | |
|
| 14996 | |
|
| 14997 | |
|
| 14998 | |
|
| 14999 | |
@c ============================================= Portable Shell Programming
|
| 15000 | |
|
| 15001 | |
@node Portable Shell
|
| 15002 | |
@chapter Portable Shell Programming
|
| 15003 | |
@cindex Portable shell programming
|
| 15004 | |
|
| 15005 | |
When writing your own checks, there are some shell-script programming
|
| 15006 | |
techniques you should avoid in order to make your code portable. The
|
| 15007 | |
Bourne shell and upward-compatible shells like the Korn shell and Bash
|
| 15008 | |
have evolved over the years, and many features added to the original
|
| 15009 | |
System7 shell are now supported on all interesting porting targets.
|
| 15010 | |
However, the following discussion between Russ Allbery and Robert Lipe
|
| 15011 | |
is worth reading:
|
| 15012 | |
|
| 15013 | |
@noindent
|
| 15014 | |
Russ Allbery:
|
| 15015 | |
|
| 15016 | |
@quotation
|
| 15017 | |
The GNU assumption that @command{/bin/sh} is the one and only shell
|
| 15018 | |
leads to a permanent deadlock. Vendors don't want to break users'
|
| 15019 | |
existing shell scripts, and there are some corner cases in the Bourne
|
| 15020 | |
shell that are not completely compatible with a Posix shell. Thus,
|
| 15021 | |
vendors who have taken this route will @emph{never} (OK@dots{}``never say
|
| 15022 | |
never'') replace the Bourne shell (as @command{/bin/sh}) with a
|
| 15023 | |
Posix shell.
|
| 15024 | |
@end quotation
|
| 15025 | |
|
| 15026 | |
@noindent
|
| 15027 | |
Robert Lipe:
|
| 15028 | |
|
| 15029 | |
@quotation
|
| 15030 | |
This is exactly the problem. While most (at least most System V's) do
|
| 15031 | |
have a Bourne shell that accepts shell functions most vendor
|
| 15032 | |
@command{/bin/sh} programs are not the Posix shell.
|
| 15033 | |
|
| 15034 | |
So while most modern systems do have a shell @emph{somewhere} that meets the
|
| 15035 | |
Posix standard, the challenge is to find it.
|
| 15036 | |
@end quotation
|
| 15037 | |
|
| 15038 | |
For this reason, part of the job of M4sh (@pxref{Programming in M4sh})
|
| 15039 | |
is to find such a shell. But to prevent trouble, if you're not using
|
| 15040 | |
M4sh you should not take advantage of features that were added after Unix
|
| 15041 | |
version 7, circa 1977 (@pxref{Systemology}); you should not use aliases,
|
| 15042 | |
negated character classes, or even @command{unset}. @code{#} comments,
|
| 15043 | |
while not in Unix version 7, were retrofitted in the original Bourne
|
| 15044 | |
shell and can be assumed to be part of the least common denominator.
|
| 15045 | |
|
| 15046 | |
On the other hand, if you're using M4sh you can assume that the shell
|
| 15047 | |
has the features that were added in SVR2 (circa 1984), including shell
|
| 15048 | |
functions,
|
| 15049 | |
@command{return}, @command{unset}, and I/O redirection for builtins. For
|
| 15050 | |
more information, refer to @uref{http://@/www.in-ulm.de/@/~mascheck/@/bourne/}.
|
| 15051 | |
However, some pitfalls have to be avoided for portable use of these
|
| 15052 | |
constructs; these will be documented in the rest of this chapter.
|
| 15053 | |
See in particular @ref{Shell Functions} and @ref{Limitations of
|
| 15054 | |
Builtins, , Limitations of Shell Builtins}.
|
| 15055 | |
|
| 15056 | |
Some ancient systems have quite
|
| 15057 | |
small limits on the length of the @samp{#!} line; for instance, 32
|
| 15058 | |
bytes (not including the newline) on SunOS 4.
|
| 15059 | |
However, these ancient systems are no longer of practical concern.
|
| 15060 | |
|
| 15061 | |
The set of external programs you should run in a @command{configure} script
|
| 15062 | |
is fairly small. @xref{Utilities in Makefiles, , Utilities in
|
| 15063 | |
Makefiles, standards, The GNU Coding Standards}, for the list. This
|
| 15064 | |
restriction allows users to start out with a fairly small set of
|
| 15065 | |
programs and build the rest, avoiding too many interdependencies between
|
| 15066 | |
packages.
|
| 15067 | |
|
| 15068 | |
Some of these external utilities have a portable subset of features; see
|
| 15069 | |
@ref{Limitations of Usual Tools}.
|
| 15070 | |
|
| 15071 | |
There are other sources of documentation about shells. The
|
| 15072 | |
specification for the Posix
|
| 15073 | |
@uref{http://@/www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02@/.html, Shell
|
| 15074 | |
Command Language}, though more generous than the restrictive shell
|
| 15075 | |
subset described above, is fairly portable nowadays. Also please see
|
| 15076 | |
@uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
|
| 15077 | |
|
| 15078 | |
@menu
|
| 15079 | |
* Shellology:: A zoology of shells
|
| 15080 | |
* Invoking the Shell:: Invoking the shell as a command
|
| 15081 | |
* Here-Documents:: Quirks and tricks
|
| 15082 | |
* File Descriptors:: FDs and redirections
|
| 15083 | |
* Signal Handling:: Shells, signals, and headaches
|
| 15084 | |
* File System Conventions:: File names
|
| 15085 | |
* Shell Pattern Matching:: Pattern matching
|
| 15086 | |
* Shell Substitutions:: Variable and command expansions
|
| 15087 | |
* Assignments:: Varying side effects of assignments
|
| 15088 | |
* Parentheses:: Parentheses in shell scripts
|
| 15089 | |
* Slashes:: Slashes in shell scripts
|
| 15090 | |
* Special Shell Variables:: Variables you should not change
|
| 15091 | |
* Shell Functions:: What to look out for if you use them
|
| 15092 | |
* Limitations of Builtins:: Portable use of not so portable /bin/sh
|
| 15093 | |
* Limitations of Usual Tools:: Portable use of portable tools
|
| 15094 | |
@end menu
|
| 15095 | |
|
| 15096 | |
@node Shellology
|
| 15097 | |
@section Shellology
|
| 15098 | |
@cindex Shellology
|
| 15099 | |
|
| 15100 | |
There are several families of shells, most prominently the Bourne family
|
| 15101 | |
and the C shell family which are deeply incompatible. If you want to
|
| 15102 | |
write portable shell scripts, avoid members of the C shell family. The
|
| 15103 | |
@uref{http://@/www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
|
| 15104 | |
Shell difference FAQ} includes a small history of Posix shells, and a
|
| 15105 | |
comparison between several of them.
|
| 15106 | |
|
| 15107 | |
Below we describe some of the members of the Bourne shell family.
|
| 15108 | |
|
| 15109 | |
@table @asis
|
| 15110 | |
@item Ash
|
| 15111 | |
@cindex Ash
|
| 15112 | |
Ash is often used on GNU/Linux and BSD
|
| 15113 | |
systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
|
| 15114 | |
bugs that are fixed in the 0.3.x series, but portable shell scripts
|
| 15115 | |
should work around them, since version 0.2 is still shipped with many
|
| 15116 | |
GNU/Linux distributions.
|
| 15117 | |
|
| 15118 | |
To be compatible with Ash 0.2:
|
| 15119 | |
|
| 15120 | |
@itemize @minus
|
| 15121 | |
@item
|
| 15122 | |
don't use @samp{$?} after expanding empty or unset variables,
|
| 15123 | |
or at the start of an @command{eval}:
|
| 15124 | |
|
| 15125 | |
@example
|
| 15126 | |
foo=
|
| 15127 | |
false
|
| 15128 | |
$foo
|
| 15129 | |
echo "Do not use it: $?"
|
| 15130 | |
false
|
| 15131 | |
eval 'echo "Do not use it: $?"'
|
| 15132 | |
@end example
|
| 15133 | |
|
| 15134 | |
@item
|
| 15135 | |
don't use command substitution within variable expansion:
|
| 15136 | |
|
| 15137 | |
@example
|
| 15138 | |
cat $@{FOO=`bar`@}
|
| 15139 | |
@end example
|
| 15140 | |
|
| 15141 | |
@item
|
| 15142 | |
beware that single builtin substitutions are not performed by a
|
| 15143 | |
subshell, hence their effect applies to the current shell! @xref{Shell
|
| 15144 | |
Substitutions}, item ``Command Substitution''.
|
| 15145 | |
@end itemize
|
| 15146 | |
|
| 15147 | |
@item Bash
|
| 15148 | |
@cindex Bash
|
| 15149 | |
To detect whether you are running Bash, test whether
|
| 15150 | |
@code{BASH_VERSION} is set. To require
|
| 15151 | |
Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
|
| 15152 | |
Mode, , Bash Posix Mode, bash, The GNU Bash Reference
|
| 15153 | |
Manual}, for details.
|
| 15154 | |
|
| 15155 | |
@item Bash 2.05 and later
|
| 15156 | |
@cindex Bash 2.05 and later
|
| 15157 | |
Versions 2.05 and later of Bash use a different format for the
|
| 15158 | |
output of the @command{set} builtin, designed to make evaluating its
|
| 15159 | |
output easier. However, this output is not compatible with earlier
|
| 15160 | |
versions of Bash (or with many other shells, probably). So if
|
| 15161 | |
you use Bash 2.05 or higher to execute @command{configure},
|
| 15162 | |
you'll need to use Bash 2.05 for all other build tasks as well.
|
| 15163 | |
|
| 15164 | |
@item Ksh
|
| 15165 | |
@cindex Ksh
|
| 15166 | |
@cindex Korn shell
|
| 15167 | |
@prindex @samp{ksh}
|
| 15168 | |
@prindex @samp{ksh88}
|
| 15169 | |
@prindex @samp{ksh93}
|
| 15170 | |
The Korn shell is compatible with the Bourne family and it mostly
|
| 15171 | |
conforms to Posix. It has two major variants commonly
|
| 15172 | |
called @samp{ksh88} and @samp{ksh93}, named after the years of initial
|
| 15173 | |
release. It is usually called @command{ksh}, but is called @command{sh}
|
| 15174 | |
on some hosts if you set your path appropriately.
|
| 15175 | |
|
| 15176 | |
Solaris systems have three variants:
|
| 15177 | |
@prindex @command{/usr/bin/ksh} on Solaris
|
| 15178 | |
@command{/usr/bin/ksh} is @samp{ksh88}; it is
|
| 15179 | |
standard on Solaris 2.0 and later.
|
| 15180 | |
@prindex @command{/usr/xpg4/bin/sh} on Solaris
|
| 15181 | |
@command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
|
| 15182 | |
@samp{ksh88}; it is standard on Solaris 9 and later.
|
| 15183 | |
@prindex @command{/usr/dt/bin/dtksh} on Solaris
|
| 15184 | |
@command{/usr/dt/bin/dtksh} is @samp{ksh93}.
|
| 15185 | |
Variants that are not standard may be parts of optional
|
| 15186 | |
packages. There is no extra charge for these packages, but they are
|
| 15187 | |
not part of a minimal OS install and therefore some installations may
|
| 15188 | |
not have it.
|
| 15189 | |
|
| 15190 | |
Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
|
| 15191 | |
is also available as @command{/usr/bin/posix/sh}. If the environment
|
| 15192 | |
variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
|
| 15193 | |
the standard shell conform to Posix.
|
| 15194 | |
|
| 15195 | |
@item Pdksh
|
| 15196 | |
@prindex @samp{pdksh}
|
| 15197 | |
A public-domain clone of the Korn shell called @command{pdksh} is widely
|
| 15198 | |
available: it has most of the @samp{ksh88} features along with a few of
|
| 15199 | |
its own. It usually sets @code{KSH_VERSION}, except if invoked as
|
| 15200 | |
@command{/bin/sh} on OpenBSD, and similarly to Bash you can require
|
| 15201 | |
Posix compatibility by running @samp{set -o posix}. Unfortunately, with
|
| 15202 | |
@command{pdksh} 5.2.14 (the latest stable version as of January 2007)
|
| 15203 | |
Posix mode is buggy and causes @command{pdksh} to depart from Posix in
|
| 15204 | |
at least one respect, see @ref{Shell Substitutions}.
|
| 15205 | |
|
| 15206 | |
@item Zsh
|
| 15207 | |
@cindex Zsh
|
| 15208 | |
To detect whether you are running @command{zsh}, test whether
|
| 15209 | |
@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
|
| 15210 | |
compatible with the Bourne shell: you must execute @samp{emulate sh},
|
| 15211 | |
and for @command{zsh} versions before 3.1.6-dev-18 you must also
|
| 15212 | |
set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
|
| 15213 | |
zsh, The Z Shell Manual}, for details.
|
| 15214 | |
|
| 15215 | |
The default Mac OS X @command{sh} was originally Zsh; it was changed to
|
| 15216 | |
Bash in Mac OS X 10.2.
|
| 15217 | |
@end table
|
| 15218 | |
|
| 15219 | |
@node Invoking the Shell
|
| 15220 | |
@section Invoking the Shell
|
| 15221 | |
@cindex invoking the shell
|
| 15222 | |
@cindex shell invocation
|
| 15223 | |
|
| 15224 | |
The Korn shell (up to at least version M-12/28/93d) has a bug when
|
| 15225 | |
invoked on a file whose name does not contain a slash. It first
|
| 15226 | |
searches for the file's name in @env{PATH}, and if found it executes
|
| 15227 | |
that rather than the original file. For example, assuming there is a
|
| 15228 | |
binary executable @file{/usr/bin/script} in your @env{PATH}, the last
|
| 15229 | |
command in the following example fails because the Korn shell finds
|
| 15230 | |
@file{/usr/bin/script} and refuses to execute it as a shell script:
|
| 15231 | |
|
| 15232 | |
@example
|
| 15233 | |
$ @kbd{touch xxyzzyz script}
|
| 15234 | |
$ @kbd{ksh xxyzzyz}
|
| 15235 | |
$ @kbd{ksh ./script}
|
| 15236 | |
$ @kbd{ksh script}
|
| 15237 | |
ksh: script: cannot execute
|
| 15238 | |
@end example
|
| 15239 | |
|
| 15240 | |
Bash 2.03 has a bug when invoked with the @option{-c} option: if the
|
| 15241 | |
option-argument ends in backslash-newline, Bash incorrectly reports a
|
| 15242 | |
syntax error. The problem does not occur if a character follows the
|
| 15243 | |
backslash:
|
| 15244 | |
|
| 15245 | |
@example
|
| 15246 | |
$ @kbd{$ bash -c 'echo foo \}
|
| 15247 | |
> @kbd{'}
|
| 15248 | |
bash: -c: line 2: syntax error: unexpected end of file
|
| 15249 | |
$ @kbd{bash -c 'echo foo \}
|
| 15250 | |
> @kbd{ '}
|
| 15251 | |
foo
|
| 15252 | |
@end example
|
| 15253 | |
|
| 15254 | |
@noindent
|
| 15255 | |
@xref{Backslash-Newline-Empty}, for how this can cause problems in makefiles.
|
| 15256 | |
|
| 15257 | |
@node Here-Documents
|
| 15258 | |
@section Here-Documents
|
| 15259 | |
@cindex Here-documents
|
| 15260 | |
@cindex Shell here-documents
|
| 15261 | |
|
| 15262 | |
Don't rely on @samp{\} being preserved just because it has no special
|
| 15263 | |
meaning together with the next symbol. In the native @command{sh}
|
| 15264 | |
on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
|
| 15265 | |
unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
|
| 15266 | |
use @samp{\\} to get @samp{\}.
|
| 15267 | |
|
| 15268 | |
With OpenBSD 2.7's @command{sh}
|
| 15269 | |
|
| 15270 | |
@example
|
| 15271 | |
@group
|
| 15272 | |
$ @kbd{cat <<EOF
|
| 15273 | |
> \" \\
|
| 15274 | |
> EOF}
|
| 15275 | |
" \
|
| 15276 | |
@end group
|
| 15277 | |
@end example
|
| 15278 | |
|
| 15279 | |
@noindent
|
| 15280 | |
and with Bash:
|
| 15281 | |
|
| 15282 | |
@example
|
| 15283 | |
@group
|
| 15284 | |
bash-2.04$ @kbd{cat <<EOF
|
| 15285 | |
> \" \\
|
| 15286 | |
> EOF}
|
| 15287 | |
\" \
|
| 15288 | |
@end group
|
| 15289 | |
@end example
|
| 15290 | |
|
| 15291 | |
Using command substitutions in a here-document that is fed to a shell
|
| 15292 | |
function is not portable. For example, with Solaris 10 @command{/bin/sh}:
|
| 15293 | |
|
| 15294 | |
@example
|
| 15295 | |
$ @kbd{kitty () @{ cat; @}}
|
| 15296 | |
$ @kbd{kitty <<EOF
|
| 15297 | |
> `echo ok`
|
| 15298 | |
> EOF}
|
| 15299 | |
/tmp/sh199886: cannot open
|
| 15300 | |
$ @kbd{echo $?}
|
| 15301 | |
1
|
| 15302 | |
@end example
|
| 15303 | |
|
| 15304 | |
Some shells mishandle large here-documents: for example,
|
| 15305 | |
Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
|
| 15306 | |
derived from Korn shell version M-12/28/93d, mishandle braced variable
|
| 15307 | |
expansion that crosses a 1024- or 4096-byte buffer boundary
|
| 15308 | |
within a here-document. Only the part of the variable name after the boundary
|
| 15309 | |
is used. For example, @code{$@{variable@}} could be replaced by the expansion
|
| 15310 | |
of @code{$@{ble@}}. If the end of the variable name is aligned with the block
|
| 15311 | |
boundary, the shell reports an error, as if you used @code{$@{@}}.
|
| 15312 | |
Instead of @code{$@{variable-default@}}, the shell may expand
|
| 15313 | |
@code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
|
| 15314 | |
be worked around by omitting the braces: @code{$variable}. The bug was
|
| 15315 | |
fixed in
|
| 15316 | |
@samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
|
| 15317 | |
still shipping older versions with the bug.
|
| 15318 | |
|
| 15319 | |
Empty here-documents are not portable either; with the following code,
|
| 15320 | |
@command{zsh} up to at least version 4.3.10 creates a file with a single
|
| 15321 | |
newline, whereas other shells create an empty file:
|
| 15322 | |
|
| 15323 | |
@example
|
| 15324 | |
cat >file <<EOF
|
| 15325 | |
EOF
|
| 15326 | |
@end example
|
| 15327 | |
|
| 15328 | |
Many shells (including the Bourne shell) implement here-documents
|
| 15329 | |
inefficiently. In particular, some shells can be extremely inefficient when
|
| 15330 | |
a single statement contains many here-documents. For instance if your
|
| 15331 | |
@file{configure.ac} includes something like:
|
| 15332 | |
|
| 15333 | |
@example
|
| 15334 | |
@group
|
| 15335 | |
if <cross_compiling>; then
|
| 15336 | |
assume this and that
|
| 15337 | |
else
|
| 15338 | |
check this
|
| 15339 | |
check that
|
| 15340 | |
check something else
|
| 15341 | |
@dots{}
|
| 15342 | |
on and on forever
|
| 15343 | |
@dots{}
|
| 15344 | |
fi
|
| 15345 | |
@end group
|
| 15346 | |
@end example
|
| 15347 | |
|
| 15348 | |
A shell parses the whole @code{if}/@code{fi} construct, creating
|
| 15349 | |
temporary files for each here-document in it. Some shells create links
|
| 15350 | |
for such here-documents on every @code{fork}, so that the clean-up code
|
| 15351 | |
they had installed correctly removes them. It is creating the links
|
| 15352 | |
that can take the shell forever.
|
| 15353 | |
|
| 15354 | |
Moving the tests out of the @code{if}/@code{fi}, or creating multiple
|
| 15355 | |
@code{if}/@code{fi} constructs, would improve the performance
|
| 15356 | |
significantly. Anyway, this kind of construct is not exactly the
|
| 15357 | |
typical use of Autoconf. In fact, it's even not recommended, because M4
|
| 15358 | |
macros can't look into shell conditionals, so we may fail to expand a
|
| 15359 | |
macro when it was expanded before in a conditional path, and the
|
| 15360 | |
condition turned out to be false at runtime, and we end up not
|
| 15361 | |
executing the macro at all.
|
| 15362 | |
|
| 15363 | |
Be careful with the use of @samp{<<-} to unindent here-documents. The
|
| 15364 | |
behavior is only portable for stripping leading @key{TAB}s, and things
|
| 15365 | |
can silently break if an overzealous editor converts to using leading
|
| 15366 | |
spaces (not all shells are nice enough to warn about unterminated
|
| 15367 | |
here-documents).
|
| 15368 | |
|
| 15369 | |
@example
|
| 15370 | |
$ @kbd{printf 'cat <<-x\n\t1\n\t 2\n\tx\n' | bash && echo done}
|
| 15371 | |
1
|
| 15372 | |
2
|
| 15373 | |
done
|
| 15374 | |
$ @kbd{printf 'cat <<-x\n 1\n 2\n x\n' | bash-3.2 && echo done}
|
| 15375 | |
1
|
| 15376 | |
2
|
| 15377 | |
x
|
| 15378 | |
done
|
| 15379 | |
@end example
|
| 15380 | |
|
| 15381 | |
@node File Descriptors
|
| 15382 | |
@section File Descriptors
|
| 15383 | |
@cindex Descriptors
|
| 15384 | |
@cindex File descriptors
|
| 15385 | |
@cindex Shell file descriptors
|
| 15386 | |
|
| 15387 | |
Most shells, if not all (including Bash, Zsh, Ash), output traces on
|
| 15388 | |
stderr, even for subshells. This might result in undesirable content
|
| 15389 | |
if you meant to capture the standard-error output of the inner command:
|
| 15390 | |
|
| 15391 | |
@example
|
| 15392 | |
$ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
|
| 15393 | |
$ @kbd{cat stderr}
|
| 15394 | |
+ eval echo foo >&2
|
| 15395 | |
+ echo foo
|
| 15396 | |
foo
|
| 15397 | |
$ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
|
| 15398 | |
$ @kbd{cat stderr}
|
| 15399 | |
+ eval 'echo foo >&2'
|
| 15400 | |
++ echo foo
|
| 15401 | |
foo
|
| 15402 | |
$ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
|
| 15403 | |
@i{# Traces on startup files deleted here.}
|
| 15404 | |
$ @kbd{cat stderr}
|
| 15405 | |
+zsh:1> eval echo foo >&2
|
| 15406 | |
+zsh:1> echo foo
|
| 15407 | |
foo
|
| 15408 | |
@end example
|
| 15409 | |
|
| 15410 | |
@noindent
|
| 15411 | |
One workaround is to grep out uninteresting lines, hoping not to remove
|
| 15412 | |
good ones.
|
| 15413 | |
|
| 15414 | |
If you intend to redirect both standard error and standard output,
|
| 15415 | |
redirect standard output first. This works better with HP-UX,
|
| 15416 | |
since its shell mishandles tracing if standard error is redirected
|
| 15417 | |
first:
|
| 15418 | |
|
| 15419 | |
@example
|
| 15420 | |
$ @kbd{sh -x -c ': 2>err >out'}
|
| 15421 | |
+ :
|
| 15422 | |
+ 2> err $ @kbd{cat err}
|
| 15423 | |
1> out
|
| 15424 | |
@end example
|
| 15425 | |
|
| 15426 | |
Don't try to redirect the standard error of a command substitution. It
|
| 15427 | |
must be done @emph{inside} the command substitution. When running
|
| 15428 | |
@samp{: `cd /zorglub` 2>/dev/null} expect the error message to
|
| 15429 | |
escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
|
| 15430 | |
|
| 15431 | |
On the other hand, some shells, such as Solaris or FreeBSD
|
| 15432 | |
@command{/bin/sh}, warn about missing programs before performing
|
| 15433 | |
redirections. Therefore, to silently check whether a program exists, it
|
| 15434 | |
is necessary to perform redirections on a subshell or brace group:
|
| 15435 | |
@example
|
| 15436 | |
$ @kbd{/bin/sh -c 'nosuch 2>/dev/null'}
|
| 15437 | |
nosuch: not found
|
| 15438 | |
$ @kbd{/bin/sh -c '(nosuch) 2>/dev/null'}
|
| 15439 | |
$ @kbd{/bin/sh -c '@{ nosuch; @} 2>/dev/null'}
|
| 15440 | |
$ @kbd{bash -c 'nosuch 2>/dev/null'}
|
| 15441 | |
@end example
|
| 15442 | |
|
| 15443 | |
FreeBSD 6.2 sh may mix the trace output lines from the statements in a
|
| 15444 | |
shell pipeline.
|
| 15445 | |
|
| 15446 | |
It is worth noting that Zsh (but not Ash nor Bash) makes it possible
|
| 15447 | |
in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
|
| 15448 | |
|
| 15449 | |
Some shells, like @command{ash}, don't recognize bi-directional
|
| 15450 | |
redirection (@samp{<>}). And even on shells that recognize it, it is
|
| 15451 | |
not portable to use on fifos: Posix does not require read-write support
|
| 15452 | |
for named pipes, and Cygwin does not support it:
|
| 15453 | |
|
| 15454 | |
@example
|
| 15455 | |
$ @kbd{mkfifo fifo}
|
| 15456 | |
$ @kbd{exec 5<>fifo}
|
| 15457 | |
$ @kbd{echo hi >&5}
|
| 15458 | |
bash: echo: write error: Communication error on send
|
| 15459 | |
@end example
|
| 15460 | |
|
| 15461 | |
@noindent
|
| 15462 | |
Furthermore, versions of @command{dash} before 0.5.6 mistakenly truncate
|
| 15463 | |
regular files when using @samp{<>}:
|
| 15464 | |
|
| 15465 | |
@example
|
| 15466 | |
$ @kbd{echo a > file}
|
| 15467 | |
$ @kbd{bash -c ': 1<>file'; cat file}
|
| 15468 | |
a
|
| 15469 | |
$ @kbd{dash -c ': 1<>file'; cat file}
|
| 15470 | |
$ rm a
|
| 15471 | |
@end example
|
| 15472 | |
|
| 15473 | |
When catering to old systems, don't redirect the same file descriptor
|
| 15474 | |
several times, as you are doomed to failure under Ultrix.
|
| 15475 | |
|
| 15476 | |
@example
|
| 15477 | |
ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
|
| 15478 | |
UWS V4.4 (Rev. 11)
|
| 15479 | |
$ @kbd{eval 'echo matter >fullness' >void}
|
| 15480 | |
illegal io
|
| 15481 | |
$ @kbd{eval '(echo matter >fullness)' >void}
|
| 15482 | |
illegal io
|
| 15483 | |
$ @kbd{(eval '(echo matter >fullness)') >void}
|
| 15484 | |
Ambiguous output redirect.
|
| 15485 | |
@end example
|
| 15486 | |
|
| 15487 | |
@noindent
|
| 15488 | |
In each case the expected result is of course @file{fullness} containing
|
| 15489 | |
@samp{matter} and @file{void} being empty. However, this bug is
|
| 15490 | |
probably not of practical concern to modern platforms.
|
| 15491 | |
|
| 15492 | |
Solaris 10 @command{sh} will try to optimize away a @command{:} command
|
| 15493 | |
(even if it is redirected) in a loop after the first iteration, or in a
|
| 15494 | |
shell function after the first call:
|
| 15495 | |
|
| 15496 | |
@example
|
| 15497 | |
$ @kbd{for i in 1 2 3 ; do : >x$i; done}
|
| 15498 | |
$ @kbd{ls x*}
|
| 15499 | |
x1
|
| 15500 | |
$ @kbd{f () @{ : >$1; @}; f y1; f y2; f y3;}
|
| 15501 | |
$ @kbd{ls y*}
|
| 15502 | |
y1
|
| 15503 | |
@end example
|
| 15504 | |
|
| 15505 | |
@noindent
|
| 15506 | |
As a workaround, @command{echo} or @command{eval} can be used.
|
| 15507 | |
|
| 15508 | |
Don't rely on file descriptors 0, 1, and 2 remaining closed in a
|
| 15509 | |
subsidiary program. If any of these descriptors is closed, the
|
| 15510 | |
operating system may open an unspecified file for the descriptor in the
|
| 15511 | |
new process image. Posix 2008 says this may be done only if the
|
| 15512 | |
subsidiary program is set-user-ID or set-group-ID, but HP-UX 11.23 does
|
| 15513 | |
it even for ordinary programs, and the next version of Posix will allow
|
| 15514 | |
HP-UX behavior.
|
| 15515 | |
|
| 15516 | |
If you want a file descriptor above 2 to be inherited into a child
|
| 15517 | |
process, then you must use redirections specific to that command or a
|
| 15518 | |
containing subshell or command group, rather than relying on
|
| 15519 | |
@command{exec} in the shell. In @command{ksh} as well as HP-UX
|
| 15520 | |
@command{sh}, file descriptors above 2 which are opened using
|
| 15521 | |
@samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
|
| 15522 | |
that involved in the fork-and-exec which runs a program or script):
|
| 15523 | |
|
| 15524 | |
@example
|
| 15525 | |
$ @kbd{echo 'echo hello >&5' >k}
|
| 15526 | |
$ @kbd{/bin/sh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t}
|
| 15527 | |
hello
|
| 15528 | |
$ @kbd{bash -c 'exec 5>t; ksh ./k; exec 5>&-; cat t}
|
| 15529 | |
hello
|
| 15530 | |
$ @kbd{ksh -c 'exec 5>t; ksh ./k; exec 5>&-; cat t}
|
| 15531 | |
./k[1]: 5: cannot open [Bad file number]
|
| 15532 | |
$ @kbd{ksh -c '(ksh ./k) 5>t; cat t'}
|
| 15533 | |
hello
|
| 15534 | |
$ @kbd{ksh -c '@{ ksh ./k; @} 5>t; cat t'}
|
| 15535 | |
hello
|
| 15536 | |
$ @kbd{ksh -c '5>t ksh ./k; cat t}
|
| 15537 | |
hello
|
| 15538 | |
@end example
|
| 15539 | |
|
| 15540 | |
Don't rely on duplicating a closed file descriptor to cause an
|
| 15541 | |
error. With Solaris @command{/bin/sh}, failed duplication is silently
|
| 15542 | |
ignored, which can cause unintended leaks to the original file
|
| 15543 | |
descriptor. In this example, observe the leak to standard output:
|
| 15544 | |
|
| 15545 | |
@example
|
| 15546 | |
$ @kbd{bash -c 'echo hi >&3' 3>&-; echo $?}
|
| 15547 | |
bash: 3: Bad file descriptor
|
| 15548 | |
1
|
| 15549 | |
$ @kbd{/bin/sh -c 'echo hi >&3' 3>&-; echo $?}
|
| 15550 | |
hi
|
| 15551 | |
0
|
| 15552 | |
@end example
|
| 15553 | |
|
| 15554 | |
Fortunately, an attempt to close an already closed file descriptor will
|
| 15555 | |
portably succeed. Likewise, it is safe to use either style of
|
| 15556 | |
@samp{@var{n}<&-} or @samp{@var{n}>&-} for closing a file descriptor,
|
| 15557 | |
even if it doesn't match the read/write mode that the file descriptor
|
| 15558 | |
was opened with.
|
| 15559 | |
|
| 15560 | |
DOS variants cannot rename or remove open files, such as in
|
| 15561 | |
@samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
|
| 15562 | |
perfectly portable among Posix hosts.
|
| 15563 | |
|
| 15564 | |
A few ancient systems reserved some file descriptors. By convention,
|
| 15565 | |
file descriptor 3 was opened to @file{/dev/tty} when you logged into
|
| 15566 | |
Eighth Edition (1985) through Tenth Edition Unix (1989). File
|
| 15567 | |
descriptor 4 had a special use on the Stardent/Kubota Titan (circa
|
| 15568 | |
1990), though we don't now remember what it was. Both these systems are
|
| 15569 | |
obsolete, so it's now safe to treat file descriptors 3 and 4 like any
|
| 15570 | |
other file descriptors.
|
| 15571 | |
|
| 15572 | |
On the other hand, you can't portably use multi-digit file descriptors.
|
| 15573 | |
Solaris @command{ksh} doesn't understand any file descriptor larger than
|
| 15574 | |
@samp{9}:
|
| 15575 | |
|
| 15576 | |
@example
|
| 15577 | |
$ @kbd{bash -c 'exec 10>&-'; echo $?}
|
| 15578 | |
0
|
| 15579 | |
$ @kbd{ksh -c 'exec 9>&-'; echo $?}
|
| 15580 | |
0
|
| 15581 | |
$ @kbd{ksh -c 'exec 10>&-'; echo $?}
|
| 15582 | |
ksh[1]: exec: 10: not found
|
| 15583 | |
127
|
| 15584 | |
@end example
|
| 15585 | |
|
| 15586 | |
@c <http://lists.gnu.org/archive/html/bug-autoconf/2011-09/msg00004.html>
|
| 15587 | |
@node Signal Handling
|
| 15588 | |
@section Signal Handling
|
| 15589 | |
@cindex Signal handling in the shell
|
| 15590 | |
@cindex Signals, shells and
|
| 15591 | |
|
| 15592 | |
Portable handling of signals within the shell is another major source of
|
| 15593 | |
headaches. This is worsened by the fact that various different, mutually
|
| 15594 | |
incompatible approaches are possible in this area, each with its
|
| 15595 | |
distinctive merits and demerits. A detailed description of these possible
|
| 15596 | |
approaches, as well as of their pros and cons, can be found in
|
| 15597 | |
@uref{http://www.cons.org/cracauer/sigint.html, this article}.
|
| 15598 | |
|
| 15599 | |
Solaris 10 @command{/bin/sh} automatically traps most signals by default;
|
| 15600 | |
@c See: <http://dbaspot.com/shell/396118-bourne-shell-exit-code-term.html>
|
| 15601 | |
the shell still exits with error upon termination by one of those signals,
|
| 15602 | |
but in such a case the exit status might be somewhat unexpected (even if
|
| 15603 | |
allowed by POSIX, strictly speaking):
|
| 15604 | |
|
| 15605 | |
@example
|
| 15606 | |
$ @kbd{bash -c 'kill -1 $$'; echo $?} # Will exit 128 + (signal number).
|
| 15607 | |
Hangup
|
| 15608 | |
129
|
| 15609 | |
$ @kbd{/bin/ksh -c 'kill -15 $$'; echo $?} # Likewise.
|
| 15610 | |
Terminated
|
| 15611 | |
143
|
| 15612 | |
$ @kbd{for sig in 1 2 3 15; do}
|
| 15613 | |
> @kbd{ echo $sig:}
|
| 15614 | |
> @kbd{ /bin/sh -c "kill -$s \$\$"; echo $?}
|
| 15615 | |
> @kbd{done}
|
| 15616 | |
signal 1:
|
| 15617 | |
Hangup
|
| 15618 | |
129
|
| 15619 | |
signal 2:
|
| 15620 | |
208
|
| 15621 | |
signal 3:
|
| 15622 | |
208
|
| 15623 | |
signal 15:
|
| 15624 | |
208
|
| 15625 | |
@end example
|
| 15626 | |
|
| 15627 | |
This gets even worse if one is using the POSIX `wait' interface to get
|
| 15628 | |
details about the shell process terminations: it will result in the shell
|
| 15629 | |
having exited normally, rather than by receiving a signal.
|
| 15630 | |
|
| 15631 | |
@example
|
| 15632 | |
$ @kbd{cat > foo.c <<'END'}
|
| 15633 | |
#include <stdio.h> /* for printf */
|
| 15634 | |
#include <stdlib.h> /* for system */
|
| 15635 | |
#include <sys/wait.h> /* for WIF* macros */
|
| 15636 | |
int main(void)
|
| 15637 | |
@{
|
| 15638 | |
int status = system ("kill -15 $$");
|
| 15639 | |
printf ("Terminated by signal: %s\n",
|
| 15640 | |
WIFSIGNALED (status) ? "yes" : "no");
|
| 15641 | |
printf ("Exited normally: %s\n",
|
| 15642 | |
WIFEXITED (status) ? "yes" : "no");
|
| 15643 | |
return 0;
|
| 15644 | |
@}
|
| 15645 | |
END
|
| 15646 | |
@c $$ font-lock
|
| 15647 | |
$ @kbd{cc -o foo foo.c}
|
| 15648 | |
$ @kbd{./a.out} # On GNU/Linux
|
| 15649 | |
Terminated by signal: no
|
| 15650 | |
Exited normally: yes
|
| 15651 | |
$ @kbd{./a.out} # On Solaris 10
|
| 15652 | |
Terminated by signal: yes
|
| 15653 | |
Exited normally: no
|
| 15654 | |
@end example
|
| 15655 | |
|
| 15656 | |
Various shells seem to handle @code{SIGQUIT} specially: they ignore it even
|
| 15657 | |
if it is not blocked, and even if the shell is not running interactively
|
| 15658 | |
(in fact, even if the shell has no attached tty); among these shells
|
| 15659 | |
are at least Bash (from version 2 onwards), Zsh 4.3.12, Solaris 10
|
| 15660 | |
@code{/bin/ksh} and @code{/usr/xpg4/bin/sh}, and AT&T @code{ksh93} (2011).
|
| 15661 | |
Still, @code{SIGQUIT} seems to be trappable quite portably within all
|
| 15662 | |
these shells. OTOH, some other shells doesn't special-case the handling
|
| 15663 | |
of @code{SIGQUIT}; among these shells are at least @code{pdksh} 5.2.14,
|
| 15664 | |
Solaris 10 and NetBSD 5.1 @code{/bin/sh}, and the Almquist Shell 0.5.5.1.
|
| 15665 | |
|
| 15666 | |
@c See: <http://mail.opensolaris.org/pipermail/ksh93-integration-discuss/2009-February/004121.html>
|
| 15667 | |
Some shells (especially Korn shells and derivatives) might try to
|
| 15668 | |
propagate to themselves a signal that has killed a child process; this is
|
| 15669 | |
not a bug, but a conscious design choice (although its overall value might
|
| 15670 | |
be debatable). The exact details of how this is attained vary from shell
|
| 15671 | |
to shell. For example, upon running @code{perl -e 'kill 2, $$'}, after
|
| 15672 | |
the perl process has been interrupted AT&T @code{ksh93} (2011) will
|
| 15673 | |
proceed to send itself a @code{SIGINT}, while Solaris 10 @code{/bin/ksh}
|
| 15674 | |
and @code{/usr/xpg4/bin/sh} will proceed to exit with status 130 (i.e.,
|
| 15675 | |
128 + 2). In any case, if there is an active trap associated with
|
| 15676 | |
@code{SIGINT}, those shells will correctly execute it.
|
| 15677 | |
|
| 15678 | |
@c See: <http://www.austingroupbugs.net/view.php?id=51>
|
| 15679 | |
Some Korn shells, when a child process die due receiving a signal with
|
| 15680 | |
signal number @var{n}, can leave in @samp{$?} an exit status of
|
| 15681 | |
256+@var{n} instead of the more common 128+@var{n}. Observe the
|
| 15682 | |
difference between AT&T @code{ksh93} (2011) and @code{bash} 4.1.5 on
|
| 15683 | |
Debian:
|
| 15684 | |
|
| 15685 | |
@example
|
| 15686 | |
$ @kbd{/bin/ksh -c 'sh -c "kill -1 \$\$"; echo $?'}
|
| 15687 | |
/bin/ksh: line 1: 7837: Hangup
|
| 15688 | |
257
|
| 15689 | |
$ @kbd{/bin/bash -c 'sh -c "kill -1 \$\$"; echo $?'}
|
| 15690 | |
/bin/bash: line 1: 7861 Hangup (sh -c "kill -1 \$\$")
|
| 15691 | |
129
|
| 15692 | |
@end example
|
| 15693 | |
|
| 15694 | |
@noindent
|
| 15695 | |
This @command{ksh} behavior is allowed by POSIX, if implemented with
|
| 15696 | |
due care; see this @uref{http://www.austingroupbugs.net/view.php?id=51,
|
| 15697 | |
Austin Group discussion} for more background. However, if it is not
|
| 15698 | |
implemented with proper care, such a behavior might cause problems
|
| 15699 | |
in some corner cases. To see why, assume we have a ``wrapper'' script
|
| 15700 | |
like this:
|
| 15701 | |
|
| 15702 | |
@example
|
| 15703 | |
#!/bin/sh
|
| 15704 | |
# Ignore some signals in the shell only, not in its child processes.
|
| 15705 | |
trap : 1 2 13 15
|
| 15706 | |
wrapped_command "$@@"
|
| 15707 | |
ret=$?
|
| 15708 | |
other_command
|
| 15709 | |
exit $ret
|
| 15710 | |
@end example
|
| 15711 | |
|
| 15712 | |
@noindent
|
| 15713 | |
If @command{wrapped_command} is interrupted by a @code{SIGHUP} (which
|
| 15714 | |
has signal number 1), @code{ret} will be set to 257. Unless the
|
| 15715 | |
@command{exit} shell builtin is smart enough to understand that such
|
| 15716 | |
a value can only have originated from a signal, and adjust the final
|
| 15717 | |
wait status of the shell appropriately, the value 257 will just get
|
| 15718 | |
truncated to 1 by the closing @code{exit} call, so that a caller of
|
| 15719 | |
the script will have no way to determine that termination by a signal
|
| 15720 | |
was involved. Observe the different behavior of AT&T @code{ksh93}
|
| 15721 | |
(2011) and @code{bash} 4.1.5 on Debian:
|
| 15722 | |
|
| 15723 | |
@example
|
| 15724 | |
$ @kbd{cat foo.sh}
|
| 15725 | |
#!/bin/sh
|
| 15726 | |
sh -c 'kill -1 $$'
|
| 15727 | |
ret=$?
|
| 15728 | |
echo $ret
|
| 15729 | |
exit $ret
|
| 15730 | |
$ @kbd{/bin/ksh foo.sh; echo $?}
|
| 15731 | |
foo.sh: line 2: 12479: Hangup
|
| 15732 | |
257
|
| 15733 | |
1
|
| 15734 | |
$ @kbd{/bin/bash foo.sh; echo $?}
|
| 15735 | |
foo.sh: line 2: 12487 Hangup (sh -c 'kill -1 $$')
|
| 15736 | |
129
|
| 15737 | |
129
|
| 15738 | |
@end example
|
| 15739 | |
|
| 15740 | |
@node File System Conventions
|
| 15741 | |
@section File System Conventions
|
| 15742 | |
@cindex File system conventions
|
| 15743 | |
|
| 15744 | |
Autoconf uses shell-script processing extensively, so the file names
|
| 15745 | |
that it processes should not contain characters that are special to the
|
| 15746 | |
shell. Special characters include space, tab, newline, NUL, and
|
| 15747 | |
the following:
|
| 15748 | |
|
| 15749 | |
@example
|
| 15750 | |
" # $ & ' ( ) * ; < = > ? [ \ ` |
|
| 15751 | |
@end example
|
| 15752 | |
|
| 15753 | |
Also, file names should not begin with @samp{~} or @samp{-}, and should
|
| 15754 | |
contain neither @samp{-} immediately after @samp{/} nor @samp{~}
|
| 15755 | |
immediately after @samp{:}. On Posix-like platforms, directory names
|
| 15756 | |
should not contain @samp{:}, as this runs afoul of @samp{:} used as the
|
| 15757 | |
path separator.
|
| 15758 | |
|
| 15759 | |
These restrictions apply not only to the files that you distribute, but
|
| 15760 | |
also to the absolute file names of your source, build, and destination
|
| 15761 | |
directories.
|
| 15762 | |
|
| 15763 | |
On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
|
| 15764 | |
they should be avoided.
|
| 15765 | |
|
| 15766 | |
Posix lets implementations treat leading @file{//} specially, but
|
| 15767 | |
requires leading @file{///} and beyond to be equivalent to @file{/}.
|
| 15768 | |
Most Unix variants treat @file{//} like @file{/}. However, some treat
|
| 15769 | |
@file{//} as a ``super-root'' that can provide access to files that are
|
| 15770 | |
not otherwise reachable from @file{/}. The super-root tradition began
|
| 15771 | |
with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
|
| 15772 | |
has revived it.
|
| 15773 | |
|
| 15774 | |
While @command{autoconf} and friends are usually run on some Posix
|
| 15775 | |
variety, they can be used on other systems, most notably DOS
|
| 15776 | |
variants. This impacts several assumptions regarding file names.
|
| 15777 | |
|
| 15778 | |
@noindent
|
| 15779 | |
For example, the following code:
|
| 15780 | |
|
| 15781 | |
@example
|
| 15782 | |
case $foo_dir in
|
| 15783 | |
/*) # Absolute
|
| 15784 | |
;;
|
| 15785 | |
*)
|
| 15786 | |
foo_dir=$dots$foo_dir ;;
|
| 15787 | |
esac
|
| 15788 | |
@end example
|
| 15789 | |
|
| 15790 | |
@noindent
|
| 15791 | |
fails to properly detect absolute file names on those systems, because
|
| 15792 | |
they can use a drivespec, and usually use a backslash as directory
|
| 15793 | |
separator. If you want to be portable to DOS variants (at the
|
| 15794 | |
price of rejecting valid but oddball Posix file names like @file{a:\b}),
|
| 15795 | |
you can check for absolute file names like this:
|
| 15796 | |
|
| 15797 | |
@cindex absolute file names, detect
|
| 15798 | |
@example
|
| 15799 | |
case $foo_dir in
|
| 15800 | |
[\\/]* | ?:[\\/]* ) # Absolute
|
| 15801 | |
;;
|
| 15802 | |
*)
|
| 15803 | |
foo_dir=$dots$foo_dir ;;
|
| 15804 | |
esac
|
| 15805 | |
@end example
|
| 15806 | |
|
| 15807 | |
@noindent
|
| 15808 | |
Make sure you quote the brackets if appropriate and keep the backslash as
|
| 15809 | |
first character (@pxref{case, , Limitations of Shell Builtins}).
|
| 15810 | |
|
| 15811 | |
Also, because the colon is used as part of a drivespec, these systems don't
|
| 15812 | |
use it as path separator. When creating or accessing paths, you can use the
|
| 15813 | |
@code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
|
| 15814 | |
to the appropriate value for the build system (@samp{:} or @samp{;}) when it
|
| 15815 | |
starts up.
|
| 15816 | |
|
| 15817 | |
File names need extra care as well. While DOS variants
|
| 15818 | |
that are Posixy enough to run @command{autoconf} (such as DJGPP)
|
| 15819 | |
are usually able to handle long file names properly, there are still
|
| 15820 | |
limitations that can seriously break packages. Several of these issues
|
| 15821 | |
can be easily detected by the
|
| 15822 | |
@uref{ftp://@/ftp.gnu.org/@/gnu/@/non-gnu/@/doschk/@/doschk-1.1.tar.gz, doschk}
|
| 15823 | |
package.
|
| 15824 | |
|
| 15825 | |
A short overview follows; problems are marked with SFN/LFN to
|
| 15826 | |
indicate where they apply: SFN means the issues are only relevant to
|
| 15827 | |
plain DOS, not to DOS under Microsoft Windows
|
| 15828 | |
variants, while LFN identifies problems that exist even under
|
| 15829 | |
Microsoft Windows variants.
|
| 15830 | |
|
| 15831 | |
@table @asis
|
| 15832 | |
@item No multiple dots (SFN)
|
| 15833 | |
DOS cannot handle multiple dots in file names. This is an especially
|
| 15834 | |
important thing to remember when building a portable configure script,
|
| 15835 | |
as @command{autoconf} uses a .in suffix for template files.
|
| 15836 | |
|
| 15837 | |
This is perfectly OK on Posix variants:
|
| 15838 | |
|
| 15839 | |
@example
|
| 15840 | |
AC_CONFIG_HEADERS([config.h])
|
| 15841 | |
AC_CONFIG_FILES([source.c foo.bar])
|
| 15842 | |
AC_OUTPUT
|
| 15843 | |
@end example
|
| 15844 | |
|
| 15845 | |
@noindent
|
| 15846 | |
but it causes problems on DOS, as it requires @samp{config.h.in},
|
| 15847 | |
@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
|
| 15848 | |
to DOS-based environments, you should use this instead:
|
| 15849 | |
|
| 15850 | |
@example
|
| 15851 | |
AC_CONFIG_HEADERS([config.h:config.hin])
|
| 15852 | |
AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
|
| 15853 | |
AC_OUTPUT
|
| 15854 | |
@end example
|
| 15855 | |
|
| 15856 | |
@item No leading dot (SFN)
|
| 15857 | |
DOS cannot handle file names that start with a dot. This is usually
|
| 15858 | |
not important for @command{autoconf}.
|
| 15859 | |
|
| 15860 | |
@item Case insensitivity (LFN)
|
| 15861 | |
DOS is case insensitive, so you cannot, for example, have both a
|
| 15862 | |
file called @samp{INSTALL} and a directory called @samp{install}. This
|
| 15863 | |
also affects @command{make}; if there's a file called @samp{INSTALL} in
|
| 15864 | |
the directory, @samp{make install} does nothing (unless the
|
| 15865 | |
@samp{install} target is marked as PHONY).
|
| 15866 | |
|
| 15867 | |
@item The 8+3 limit (SFN)
|
| 15868 | |
Because the DOS file system only stores the first 8 characters of
|
| 15869 | |
the file name and the first 3 of the extension, those must be unique.
|
| 15870 | |
That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
|
| 15871 | |
@file{foobar-prettybird.c} all resolve to the same file name
|
| 15872 | |
(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
|
| 15873 | |
@file{foo.bartender}.
|
| 15874 | |
|
| 15875 | |
The 8+3 limit is not usually a problem under Microsoft Windows, as it
|
| 15876 | |
uses numeric
|
| 15877 | |
tails in the short version of file names to make them unique. However, a
|
| 15878 | |
registry setting can turn this behavior off. While this makes it
|
| 15879 | |
possible to share file trees containing long file names between SFN
|
| 15880 | |
and LFN environments, it also means the above problem applies there
|
| 15881 | |
as well.
|
| 15882 | |
|
| 15883 | |
@item Invalid characters (LFN)
|
| 15884 | |
Some characters are invalid in DOS file names, and should therefore
|
| 15885 | |
be avoided. In a LFN environment, these are @samp{/}, @samp{\},
|
| 15886 | |
@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
|
| 15887 | |
In a SFN environment, other characters are also invalid. These
|
| 15888 | |
include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
|
| 15889 | |
|
| 15890 | |
@item Invalid names (LFN)
|
| 15891 | |
Some DOS file names are reserved, and cause problems if you
|
| 15892 | |
try to use files with those names. These names include @file{CON},
|
| 15893 | |
@file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
|
| 15894 | |
@file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
|
| 15895 | |
File names are case insensitive, so even names like
|
| 15896 | |
@file{aux/config.guess} are disallowed.
|
| 15897 | |
|
| 15898 | |
@end table
|
| 15899 | |
|
| 15900 | |
@node Shell Pattern Matching
|
| 15901 | |
@section Shell Pattern Matching
|
| 15902 | |
@cindex Shell pattern matching
|
| 15903 | |
|
| 15904 | |
Nowadays portable patterns can use negated character classes like
|
| 15905 | |
@samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by
|
| 15906 | |
some shells but not others; hence portable scripts should never use
|
| 15907 | |
@samp{^} as the first character of a bracket pattern.
|
| 15908 | |
|
| 15909 | |
Outside the C locale, patterns like @samp{[a-z]} are problematic since
|
| 15910 | |
they may match characters that are not lower-case letters.
|
| 15911 | |
|
| 15912 | |
@node Shell Substitutions
|
| 15913 | |
@section Shell Substitutions
|
| 15914 | |
@cindex Shell substitutions
|
| 15915 | |
|
| 15916 | |
Contrary to a persistent urban legend, the Bourne shell does not
|
| 15917 | |
systematically split variables and back-quoted expressions, in particular
|
| 15918 | |
on the right-hand side of assignments and in the argument of @code{case}.
|
| 15919 | |
For instance, the following code:
|
| 15920 | |
|
| 15921 | |
@example
|
| 15922 | |
case "$given_srcdir" in
|
| 15923 | |
.) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;;
|
| 15924 | |
*) top_srcdir="$dots$given_srcdir" ;;
|
| 15925 | |
esac
|
| 15926 | |
@end example
|
| 15927 | |
|
| 15928 | |
@noindent
|
| 15929 | |
is more readable when written as:
|
| 15930 | |
|
| 15931 | |
@example
|
| 15932 | |
case $given_srcdir in
|
| 15933 | |
.) top_srcdir=`echo "$dots" | sed 's|/$||'` ;;
|
| 15934 | |
*) top_srcdir=$dots$given_srcdir ;;
|
| 15935 | |
esac
|
| 15936 | |
@end example
|
| 15937 | |
|
| 15938 | |
@noindent
|
| 15939 | |
and in fact it is even @emph{more} portable: in the first case of the
|
| 15940 | |
first attempt, the computation of @code{top_srcdir} is not portable,
|
| 15941 | |
since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"},
|
| 15942 | |
for example Solaris 10 ksh:
|
| 15943 | |
|
| 15944 | |
@example
|
| 15945 | |
$ @kbd{foo="`echo " bar" | sed 's, ,,'`"}
|
| 15946 | |
ksh: : cannot execute
|
| 15947 | |
ksh: bar | sed 's, ,,': cannot execute
|
| 15948 | |
@end example
|
| 15949 | |
|
| 15950 | |
@noindent
|
| 15951 | |
Posix does not specify behavior for this sequence. On the other hand,
|
| 15952 | |
behavior for @code{"`@dots{}\"@dots{}\"@dots{}`"} is specified by Posix,
|
| 15953 | |
but in practice, not all shells understand it the same way: pdksh 5.2.14
|
| 15954 | |
prints spurious quotes when in Posix mode:
|
| 15955 | |
|
| 15956 | |
@example
|
| 15957 | |
$ @kbd{echo "`echo \"hello\"`"}
|
| 15958 | |
hello
|
| 15959 | |
$ @kbd{set -o posix}
|
| 15960 | |
$ @kbd{echo "`echo \"hello\"`"}
|
| 15961 | |
"hello"
|
| 15962 | |
@end example
|
| 15963 | |
|
| 15964 | |
@noindent
|
| 15965 | |
There is just no portable way to use double-quoted strings inside
|
| 15966 | |
double-quoted back-quoted expressions (pfew!).
|
| 15967 | |
|
| 15968 | |
Bash 4.1 has a bug where quoted empty strings adjacent to unquoted
|
| 15969 | |
parameter expansions are elided during word splitting. Meanwhile, zsh
|
| 15970 | |
does not perform word splitting except when in Bourne compatibility
|
| 15971 | |
mode. In the example below, the correct behavior is to have five
|
| 15972 | |
arguments to the function, and exactly two spaces on either side of the
|
| 15973 | |
middle @samp{-}, since word splitting collapses multiple spaces in
|
| 15974 | |
@samp{$f} but leaves empty arguments intact.
|
| 15975 | |
|
| 15976 | |
@example
|
| 15977 | |
$ @kbd{bash -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
|
| 15978 | |
3- - -
|
| 15979 | |
$ @kbd{ksh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
|
| 15980 | |
5- - -
|
| 15981 | |
$ @kbd{zsh -c 'n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
|
| 15982 | |
3- - -
|
| 15983 | |
$ @kbd{zsh -c 'emulate sh;}
|
| 15984 | |
> @kbd{n() @{ echo "$#$@@"; @}; f=" - "; n - ""$f"" -'}
|
| 15985 | |
5- - -
|
| 15986 | |
@end example
|
| 15987 | |
|
| 15988 | |
@noindent
|
| 15989 | |
You can work around this by doing manual word splitting, such as using
|
| 15990 | |
@samp{"$str" $list} rather than @samp{"$str"$list}.
|
| 15991 | |
|
| 15992 | |
There are also portability pitfalls with particular expansions:
|
| 15993 | |
|
| 15994 | |
@table @code
|
| 15995 | |
@item $@@
|
| 15996 | |
@cindex @code{"$@@"}
|
| 15997 | |
One of the most famous shell-portability issues is related to
|
| 15998 | |
@samp{"$@@"}. When there are no positional arguments, Posix says
|
| 15999 | |
that @samp{"$@@"} is supposed to be equivalent to nothing, but the
|
| 16000 | |
original Unix version 7 Bourne shell treated it as equivalent to
|
| 16001 | |
@samp{""} instead, and this behavior survives in later implementations
|
| 16002 | |
like Digital Unix 5.0.
|
| 16003 | |
|
| 16004 | |
The traditional way to work around this portability problem is to use
|
| 16005 | |
@samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
|
| 16006 | |
Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
|
| 16007 | |
the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
|
| 16008 | |
|
| 16009 | |
@example
|
| 16010 | |
zsh $ @kbd{emulate sh}
|
| 16011 | |
zsh $ @kbd{for i in "$@@"; do echo $i; done}
|
| 16012 | |
Hello World
|
| 16013 | |
!
|
| 16014 | |
zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
|
| 16015 | |
Hello
|
| 16016 | |
World
|
| 16017 | |
!
|
| 16018 | |
@end example
|
| 16019 | |
|
| 16020 | |
@noindent
|
| 16021 | |
Zsh handles plain @samp{"$@@"} properly, but we can't use plain
|
| 16022 | |
@samp{"$@@"} because of the portability problems mentioned above.
|
| 16023 | |
One workaround relies on Zsh's ``global aliases'' to convert
|
| 16024 | |
@samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
|
| 16025 | |
|
| 16026 | |
@example
|
| 16027 | |
test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
|
| 16028 | |
@end example
|
| 16029 | |
|
| 16030 | |
Zsh only recognizes this alias when a shell word matches it exactly;
|
| 16031 | |
@samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this
|
| 16032 | |
case always yields at least one shell word, use plain @samp{"$@@"}.
|
| 16033 | |
|
| 16034 | |
A more conservative workaround is to avoid @samp{"$@@"} if it is
|
| 16035 | |
possible that there may be no positional arguments. For example,
|
| 16036 | |
instead of:
|
| 16037 | |
|
| 16038 | |
@example
|
| 16039 | |
cat conftest.c "$@@"
|
| 16040 | |
@end example
|
| 16041 | |
|
| 16042 | |
you can use this instead:
|
| 16043 | |
|
| 16044 | |
@example
|
| 16045 | |
case $# in
|
| 16046 | |
0) cat conftest.c;;
|
| 16047 | |
*) cat conftest.c "$@@";;
|
| 16048 | |
esac
|
| 16049 | |
@end example
|
| 16050 | |
|
| 16051 | |
Autoconf macros often use the @command{set} command to update
|
| 16052 | |
@samp{$@@}, so if you are writing shell code intended for
|
| 16053 | |
@command{configure} you should not assume that the value of @samp{$@@}
|
| 16054 | |
persists for any length of time.
|
| 16055 | |
|
| 16056 | |
|
| 16057 | |
@item $@{10@}
|
| 16058 | |
@cindex positional parameters
|
| 16059 | |
The 10th, 11th, @dots{} positional parameters can be accessed only after
|
| 16060 | |
a @code{shift}. The 7th Edition shell reported an error if given
|
| 16061 | |
@code{$@{10@}}, and
|
| 16062 | |
Solaris 10 @command{/bin/sh} still acts that way:
|
| 16063 | |
|
| 16064 | |
@example
|
| 16065 | |
$ @kbd{set 1 2 3 4 5 6 7 8 9 10}
|
| 16066 | |
$ @kbd{echo $@{10@}}
|
| 16067 | |
bad substitution
|
| 16068 | |
@end example
|
| 16069 | |
|
| 16070 | |
Conversely, not all shells obey the Posix rule that when braces are
|
| 16071 | |
omitted, multiple digits beyond a @samp{$} imply the single-digit
|
| 16072 | |
positional parameter expansion concatenated with the remaining literal
|
| 16073 | |
digits. To work around the issue, you must use braces.
|
| 16074 | |
|
| 16075 | |
@example
|
| 16076 | |
$ @kbd{bash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'}
|
| 16077 | |
a0 a0
|
| 16078 | |
$ @kbd{dash -c 'set a b c d e f g h i j; echo $10 $@{1@}0'}
|
| 16079 | |
j a0
|
| 16080 | |
@end example
|
| 16081 | |
|
| 16082 | |
@item $@{@var{var}:-@var{value}@}
|
| 16083 | |
@c Info cannot handle `:' in index entries.
|
| 16084 | |
@ifnotinfo
|
| 16085 | |
@cindex @code{$@{@var{var}:-@var{value}@}}
|
| 16086 | |
@end ifnotinfo
|
| 16087 | |
@cindex @code{$@{@var{var}-@var{value}@}}
|
| 16088 | |
Old BSD shells, including the Ultrix @code{sh}, don't accept the
|
| 16089 | |
colon for any shell substitution, and complain and die.
|
| 16090 | |
Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
|
| 16091 | |
However, all shells that support functions allow the use of colon in
|
| 16092 | |
shell substitution, and since m4sh requires functions, you can portably
|
| 16093 | |
use null variable substitution patterns in configure scripts.
|
| 16094 | |
|
| 16095 | |
@item $@{@var{var}+@var{value}@}
|
| 16096 | |
@cindex @code{$@{@var{var}+@var{value}@}}
|
| 16097 | |
When using @samp{$@{@var{var}-@var{value}@}} or
|
| 16098 | |
@samp{$@{@var{var}-@var{value}@}} for providing alternate substitutions,
|
| 16099 | |
@var{value} must either be a single shell word, quoted, or in the
|
| 16100 | |
context of an unquoted here-document. Solaris
|
| 16101 | |
@command{/bin/sh} complains otherwise.
|
| 16102 | |
|
| 16103 | |
@example
|
| 16104 | |
$ @kbd{/bin/sh -c 'echo $@{a-b c@}'}
|
| 16105 | |
/bin/sh: bad substitution
|
| 16106 | |
$ @kbd{/bin/sh -c 'echo $@{a-'\''b c'\''@}'}
|
| 16107 | |
b c
|
| 16108 | |
$ @kbd{/bin/sh -c 'echo "$@{a-b c@}"'}
|
| 16109 | |
b c
|
| 16110 | |
$ @kbd{/bin/sh -c 'cat <<EOF
|
| 16111 | |
$@{a-b c@}
|
| 16112 | |
EOF}
|
| 16113 | |
b c
|
| 16114 | |
@end example
|
| 16115 | |
|
| 16116 | |
According to Posix, if an expansion occurs inside double quotes, then
|
| 16117 | |
the use of unquoted double quotes within @var{value} is unspecified, and
|
| 16118 | |
any single quotes become literal characters; in that case, escaping must
|
| 16119 | |
be done with backslash. Likewise, the use of unquoted here-documents is
|
| 16120 | |
a case where double quotes have unspecified results:
|
| 16121 | |
|
| 16122 | |
@example
|
| 16123 | |
$ @kbd{/bin/sh -c 'echo "$@{a-"b c"@}"'}
|
| 16124 | |
/bin/sh: bad substitution
|
| 16125 | |
$ @kbd{ksh -c 'echo "$@{a-"b c"@}"'}
|
| 16126 | |
b c
|
| 16127 | |
$ @kbd{bash -c 'echo "$@{a-"b c"@}"'}
|
| 16128 | |
b c
|
| 16129 | |
$ @kbd{/bin/sh -c 'a=; echo $@{a+'\''b c'\''@}'}
|
| 16130 | |
b c
|
| 16131 | |
$ @kbd{/bin/sh -c 'a=; echo "$@{a+'\''b c'\''@}"'}
|
| 16132 | |
'b c'
|
| 16133 | |
$ @kbd{/bin/sh -c 'a=; echo "$@{a+\"b c\"@}"'}
|
| 16134 | |
"b c"
|
| 16135 | |
$ @kbd{/bin/sh -c 'a=; echo "$@{a+b c@}"'}
|
| 16136 | |
b c
|
| 16137 | |
$ @kbd{/bin/sh -c 'cat <<EOF
|
| 16138 | |
$@{a-"b c"@}
|
| 16139 | |
EOF'}
|
| 16140 | |
"b c"
|
| 16141 | |
$ @kbd{/bin/sh -c 'cat <<EOF
|
| 16142 | |
$@{a-'b c'@}
|
| 16143 | |
EOF'}
|
| 16144 | |
'b c'
|
| 16145 | |
$ @kbd{bash -c 'cat <<EOF
|
| 16146 | |
$@{a-"b c"@}
|
| 16147 | |
EOF'}
|
| 16148 | |
b c
|
| 16149 | |
$ @kbd{bash -c 'cat <<EOF
|
| 16150 | |
$@{a-'b c'@}
|
| 16151 | |
EOF'}
|
| 16152 | |
'b c'
|
| 16153 | |
@end example
|
| 16154 | |
|
| 16155 | |
Perhaps the easiest way to work around quoting issues in a manner
|
| 16156 | |
portable to all shells is to place the results in a temporary variable,
|
| 16157 | |
then use @samp{$t} as the @var{value}, rather than trying to inline
|
| 16158 | |
the expression needing quoting.
|
| 16159 | |
|
| 16160 | |
@example
|
| 16161 | |
$ @kbd{/bin/sh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'}
|
| 16162 | |
b c"'@}\
|
| 16163 | |
$ @kbd{ksh -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'}
|
| 16164 | |
b c"'@}\
|
| 16165 | |
$ @kbd{bash -c 't="b c\"'\''@}\\"; echo "$@{a-$t@}"'}
|
| 16166 | |
b c"'@}\
|
| 16167 | |
@end example
|
| 16168 | |
|
| 16169 | |
@item $@{@var{var}=@var{value}@}
|
| 16170 | |
@cindex @code{$@{@var{var}=@var{value}@}}
|
| 16171 | |
When using @samp{$@{@var{var}=@var{value}@}} to assign a default value
|
| 16172 | |
to @var{var}, remember that even though the assignment to @var{var} does
|
| 16173 | |
not undergo file name expansion, the result of the variable expansion
|
| 16174 | |
does unless the expansion occurred within double quotes. In particular,
|
| 16175 | |
when using @command{:} followed by unquoted variable expansion for the
|
| 16176 | |
side effect of setting a default value, if the final value of
|
| 16177 | |
@samp{$var} contains any globbing characters (either from @var{value} or
|
| 16178 | |
from prior contents), the shell has to spend time performing file name
|
| 16179 | |
expansion and field splitting even though those results will not be
|
| 16180 | |
used. Therefore, it is a good idea to consider double quotes when performing
|
| 16181 | |
default initialization; while remembering how this impacts any quoting
|
| 16182 | |
characters appearing in @var{value}.
|
| 16183 | |
|
| 16184 | |
@example
|
| 16185 | |
$ @kbd{time bash -c ': "$@{a=/usr/bin/*@}"; echo "$a"'}
|
| 16186 | |
/usr/bin/*
|
| 16187 | |
|
| 16188 | |
real 0m0.005s
|
| 16189 | |
user 0m0.002s
|
| 16190 | |
sys 0m0.003s
|
| 16191 | |
$ @kbd{time bash -c ': $@{a=/usr/bin/*@}; echo "$a"'}
|
| 16192 | |
/usr/bin/*
|
| 16193 | |
|
| 16194 | |
real 0m0.039s
|
| 16195 | |
user 0m0.026s
|
| 16196 | |
sys 0m0.009s
|
| 16197 | |
$ @kbd{time bash -c 'a=/usr/bin/*; : $@{a=noglob@}; echo "$a"'}
|
| 16198 | |
/usr/bin/*
|
| 16199 | |
|
| 16200 | |
real 0m0.031s
|
| 16201 | |
user 0m0.020s
|
| 16202 | |
sys 0m0.010s
|
| 16203 | |
|
| 16204 | |
$ @kbd{time bash -c 'a=/usr/bin/*; : "$@{a=noglob@}"; echo "$a"'}
|
| 16205 | |
/usr/bin/*
|
| 16206 | |
|
| 16207 | |
real 0m0.006s
|
| 16208 | |
user 0m0.002s
|
| 16209 | |
sys 0m0.003s
|
| 16210 | |
@end example
|
| 16211 | |
|
| 16212 | |
As with @samp{+} and @samp{-}, you must use quotes when using @samp{=}
|
| 16213 | |
if the @var{value} contains more than one shell word; either single
|
| 16214 | |
quotes for just the @var{value}, or double quotes around the entire
|
| 16215 | |
expansion:
|
| 16216 | |
|
| 16217 | |
@example
|
| 16218 | |
$ @kbd{: $@{var1='Some words'@}}
|
| 16219 | |
$ @kbd{: "$@{var2=like this@}"}
|
| 16220 | |
$ @kbd{echo $var1 $var2}
|
| 16221 | |
Some words like this
|
| 16222 | |
@end example
|
| 16223 | |
|
| 16224 | |
@noindent
|
| 16225 | |
otherwise some shells, such as Solaris @command{/bin/sh} or on Digital
|
| 16226 | |
Unix V 5.0, die because of a ``bad substitution''. Meanwhile, Posix
|
| 16227 | |
requires that with @samp{=}, quote removal happens prior to the
|
| 16228 | |
assignment, and the expansion be the final contents of @var{var} without
|
| 16229 | |
quoting (and thus subject to field splitting), in contrast to the
|
| 16230 | |
behavior with @samp{-} passing the quoting through to the final
|
| 16231 | |
expansion. However, @command{bash} 4.1 does not obey this rule.
|
| 16232 | |
|
| 16233 | |
@example
|
| 16234 | |
$ @kbd{ksh -c 'echo $@{var-a\ \ b@}'}
|
| 16235 | |
a b
|
| 16236 | |
$ @kbd{ksh -c 'echo $@{var=a\ \ b@}'}
|
| 16237 | |
a b
|
| 16238 | |
$ @kbd{bash -c 'echo $@{var=a\ \ b@}'}
|
| 16239 | |
a b
|
| 16240 | |
@end example
|
| 16241 | |
|
| 16242 | |
Finally, Posix states that when mixing @samp{$@{a=b@}} with regular
|
| 16243 | |
commands, it is unspecified whether the assignments affect the parent
|
| 16244 | |
shell environment. It is best to perform assignments independently from
|
| 16245 | |
commands, to avoid the problems demonstrated in this example:
|
| 16246 | |
|
| 16247 | |
@example
|
| 16248 | |
$ @kbd{bash -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'}
|
| 16249 | |
+b+b+
|
| 16250 | |
-b-
|
| 16251 | |
$ @kbd{/bin/sh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'}
|
| 16252 | |
++b+
|
| 16253 | |
--
|
| 16254 | |
$ @kbd{ksh -c 'x= y=$@{x:=b@} sh -c "echo +\$x+\$y+";echo -$x-'}
|
| 16255 | |
+b+b+
|
| 16256 | |
--
|
| 16257 | |
@end example
|
| 16258 | |
|
| 16259 | |
@item $@{@var{var}=@var{value}@}
|
| 16260 | |
@cindex @code{$@{@var{var}=@var{literal}@}}
|
| 16261 | |
Solaris @command{/bin/sh} has a frightening bug in its handling of
|
| 16262 | |
literal assignments. Imagine you need set a variable to a string containing
|
| 16263 | |
@samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
|
| 16264 | |
when the affected variable was already set. This bug can be exercised
|
| 16265 | |
by running:
|
| 16266 | |
|
| 16267 | |
@example
|
| 16268 | |
$ @kbd{unset foo}
|
| 16269 | |
$ @kbd{foo=$@{foo='@}'@}}
|
| 16270 | |
$ @kbd{echo $foo}
|
| 16271 | |
@}
|
| 16272 | |
$ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
|
| 16273 | |
$ @kbd{echo $foo}
|
| 16274 | |
@}
|
| 16275 | |
$ @kbd{foo=$@{foo='@}'@}}
|
| 16276 | |
$ @kbd{echo $foo}
|
| 16277 | |
@}@}
|
| 16278 | |
^ ugh!
|
| 16279 | |
@end example
|
| 16280 | |
|
| 16281 | |
It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
|
| 16282 | |
though it is enclosed in single quotes. The problem doesn't happen
|
| 16283 | |
using double quotes, or when using a temporary variable holding the
|
| 16284 | |
problematic string.
|
| 16285 | |
|
| 16286 | |
@item $@{@var{var}=@var{expanded-value}@}
|
| 16287 | |
@cindex @code{$@{@var{var}=@var{expanded-value}@}}
|
| 16288 | |
On Ultrix,
|
| 16289 | |
running
|
| 16290 | |
|
| 16291 | |
@example
|
| 16292 | |
default="yu,yaa"
|
| 16293 | |
: $@{var="$default"@}
|
| 16294 | |
@end example
|
| 16295 | |
|
| 16296 | |
@noindent
|
| 16297 | |
sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
|
| 16298 | |
each char is set. You don't observe the phenomenon using a simple
|
| 16299 | |
@samp{echo $var} since apparently the shell resets the 8th bit when it
|
| 16300 | |
expands $var. Here are two means to make this shell confess its sins:
|
| 16301 | |
|
| 16302 | |
@example
|
| 16303 | |
$ @kbd{cat -v <<EOF
|
| 16304 | |
$var
|
| 16305 | |
EOF}
|
| 16306 | |
@end example
|
| 16307 | |
|
| 16308 | |
@noindent
|
| 16309 | |
and
|
| 16310 | |
|
| 16311 | |
@example
|
| 16312 | |
$ @kbd{set | grep '^var=' | cat -v}
|
| 16313 | |
@end example
|
| 16314 | |
|
| 16315 | |
One classic incarnation of this bug is:
|
| 16316 | |
|
| 16317 | |
@example
|
| 16318 | |
default="a b c"
|
| 16319 | |
: $@{list="$default"@}
|
| 16320 | |
for c in $list; do
|
| 16321 | |
echo $c
|
| 16322 | |
done
|
| 16323 | |
@end example
|
| 16324 | |
|
| 16325 | |
@noindent
|
| 16326 | |
You'll get @samp{a b c} on a single line. Why? Because there are no
|
| 16327 | |
spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
|
| 16328 | |
bit set, hence no IFS splitting is performed!!!
|
| 16329 | |
|
| 16330 | |
One piece of good news is that Ultrix works fine with @samp{:
|
| 16331 | |
$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
|
| 16332 | |
then that QNX 4.25 then sets @var{list} to the @emph{last} item of
|
| 16333 | |
@var{default}!
|
| 16334 | |
|
| 16335 | |
The portable way out consists in using a double assignment, to switch
|
| 16336 | |
the 8th bit twice on Ultrix:
|
| 16337 | |
|
| 16338 | |
@example
|
| 16339 | |
list=$@{list="$default"@}
|
| 16340 | |
@end example
|
| 16341 | |
|
| 16342 | |
@noindent
|
| 16343 | |
@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
|
| 16344 | |
use:
|
| 16345 | |
|
| 16346 | |
@example
|
| 16347 | |
test "$@{var+set@}" = set || var=@var{@{value@}}
|
| 16348 | |
@end example
|
| 16349 | |
|
| 16350 | |
@item $@{#@var{var}@}
|
| 16351 | |
@itemx $@{@var{var}%@var{word}@}
|
| 16352 | |
@itemx $@{@var{var}%%@var{word}@}
|
| 16353 | |
@itemx $@{@var{var}#@var{word}@}
|
| 16354 | |
@itemx $@{@var{var}##@var{word}@}
|
| 16355 | |
@cindex @code{$@{#@var{var}@}}
|
| 16356 | |
@cindex @code{$@{@var{var}%@var{word}@}}
|
| 16357 | |
@cindex @code{$@{@var{var}%%@var{word}@}}
|
| 16358 | |
@cindex @code{$@{@var{var}#@var{word}@}}
|
| 16359 | |
@cindex @code{$@{@var{var}##@var{word}@}}
|
| 16360 | |
Posix requires support for these usages, but they do not work with many
|
| 16361 | |
traditional shells, e.g., Solaris 10 @command{/bin/sh}.
|
| 16362 | |
|
| 16363 | |
Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For
|
| 16364 | |
example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
|
| 16365 | |
@samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
|
| 16366 | |
yields the empty string.
|
| 16367 | |
|
| 16368 | |
|
| 16369 | |
@item `@var{commands}`
|
| 16370 | |
@cindex @code{`@var{commands}`}
|
| 16371 | |
@cindex Command Substitution
|
| 16372 | |
Posix requires shells to trim all trailing newlines from command
|
| 16373 | |
output before substituting it, so assignments like
|
| 16374 | |
@samp{dir=`echo "$file" | tr a A`} do not work as expected if
|
| 16375 | |
@samp{$file} ends in a newline.
|
| 16376 | |
|
| 16377 | |
While in general it makes no sense, do not substitute a single builtin
|
| 16378 | |
with side effects, because Ash 0.2, trying to optimize, does not fork a
|
| 16379 | |
subshell to perform the command.
|
| 16380 | |
|
| 16381 | |
For instance, if you wanted to check that @command{cd} is silent, do not
|
| 16382 | |
use @samp{test -z "`cd /`"} because the following can happen:
|
| 16383 | |
|
| 16384 | |
@example
|
| 16385 | |
$ @kbd{pwd}
|
| 16386 | |
/tmp
|
| 16387 | |
$ @kbd{test -z "`cd /`" && pwd}
|
| 16388 | |
/
|
| 16389 | |
@end example
|
| 16390 | |
|
| 16391 | |
@noindent
|
| 16392 | |
The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
|
| 16393 | |
|
| 16394 | |
The MSYS shell leaves a stray byte in the expansion of a double-quoted
|
| 16395 | |
command substitution of a native program, if the end of the substitution
|
| 16396 | |
is not aligned with the end of the double quote. This may be worked
|
| 16397 | |
around by inserting another pair of quotes:
|
| 16398 | |
|
| 16399 | |
@example
|
| 16400 | |
$ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
|
| 16401 | |
$ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
|
| 16402 | |
- broken differ: char 4, line 1
|
| 16403 | |
@end example
|
| 16404 | |
|
| 16405 | |
Upon interrupt or SIGTERM, some shells may abort a command substitution,
|
| 16406 | |
replace it with a null string, and wrongly evaluate the enclosing
|
| 16407 | |
command before entering the trap or ending the script. This can lead to
|
| 16408 | |
spurious errors:
|
| 16409 | |
|
| 16410 | |
@example
|
| 16411 | |
$ @kbd{sh -c 'if test `sleep 5; echo hi` = hi; then echo yes; fi'}
|
| 16412 | |
$ @kbd{^C}
|
| 16413 | |
sh: test: hi: unexpected operator/operand
|
| 16414 | |
@end example
|
| 16415 | |
|
| 16416 | |
@noindent
|
| 16417 | |
You can avoid this by assigning the command substitution to a temporary
|
| 16418 | |
variable:
|
| 16419 | |
|
| 16420 | |
@example
|
| 16421 | |
$ @kbd{sh -c 'res=`sleep 5; echo hi`
|
| 16422 | |
if test "x$res" = xhi; then echo yes; fi'}
|
| 16423 | |
$ @kbd{^C}
|
| 16424 | |
@end example
|
| 16425 | |
|
| 16426 | |
@item $(@var{commands})
|
| 16427 | |
@cindex @code{$(@var{commands})}
|
| 16428 | |
This construct is meant to replace @samp{`@var{commands}`},
|
| 16429 | |
and it has most of the problems listed under @code{`@var{commands}`}.
|
| 16430 | |
|
| 16431 | |
This construct can be
|
| 16432 | |
nested while this is impossible to do portably with back quotes.
|
| 16433 | |
Unfortunately it is not yet universally supported. Most notably, even recent
|
| 16434 | |
releases of Solaris don't support it:
|
| 16435 | |
|
| 16436 | |
@example
|
| 16437 | |
$ @kbd{showrev -c /bin/sh | grep version}
|
| 16438 | |
Command version: SunOS 5.10 Generic 121005-03 Oct 2006
|
| 16439 | |
$ @kbd{echo $(echo blah)}
|
| 16440 | |
syntax error: `(' unexpected
|
| 16441 | |
@end example
|
| 16442 | |
|
| 16443 | |
@noindent
|
| 16444 | |
nor does IRIX 6.5's Bourne shell:
|
| 16445 | |
@example
|
| 16446 | |
$ @kbd{uname -a}
|
| 16447 | |
IRIX firebird-image 6.5 07151432 IP22
|
| 16448 | |
$ @kbd{echo $(echo blah)}
|
| 16449 | |
$(echo blah)
|
| 16450 | |
@end example
|
| 16451 | |
|
| 16452 | |
If you do use @samp{$(@var{commands})}, make sure that the commands
|
| 16453 | |
do not start with a parenthesis, as that would cause confusion with
|
| 16454 | |
a different notation @samp{$((@var{expression}))} that in modern
|
| 16455 | |
shells is an arithmetic expression not a command. To avoid the
|
| 16456 | |
confusion, insert a space between the two opening parentheses.
|
| 16457 | |
|
| 16458 | |
Avoid @var{commands} that contain unbalanced parentheses in
|
| 16459 | |
here-documents, comments, or case statement patterns, as many shells
|
| 16460 | |
mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
|
| 16461 | |
5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
|
| 16462 | |
|
| 16463 | |
@example
|
| 16464 | |
echo $(case x in x) echo hello;; esac)
|
| 16465 | |
@end example
|
| 16466 | |
|
| 16467 | |
|
| 16468 | |
@item $((@var{expression}))
|
| 16469 | |
@cindex @code{$((@var{expression}))}
|
| 16470 | |
Arithmetic expansion is not portable as some shells (most
|
| 16471 | |
notably Solaris 10 @command{/bin/sh}) don't support it.
|
| 16472 | |
|
| 16473 | |
Among shells that do support @samp{$(( ))}, not all of them obey the
|
| 16474 | |
Posix rule that octal and hexadecimal constants must be recognized:
|
| 16475 | |
|
| 16476 | |
@example
|
| 16477 | |
$ @kbd{bash -c 'echo $(( 010 + 0x10 ))'}
|
| 16478 | |
24
|
| 16479 | |
$ @kbd{zsh -c 'echo $(( 010 + 0x10 ))'}
|
| 16480 | |
26
|
| 16481 | |
$ @kbd{zsh -c 'emulate sh; echo $(( 010 + 0x10 ))'}
|
| 16482 | |
24
|
| 16483 | |
$ @kbd{pdksh -c 'echo $(( 010 + 0x10 ))'}
|
| 16484 | |
pdksh: 010 + 0x10 : bad number `0x10'
|
| 16485 | |
$ @kbd{pdksh -c 'echo $(( 010 ))'}
|
| 16486 | |
10
|
| 16487 | |
@end example
|
| 16488 | |
|
| 16489 | |
When it is available, using arithmetic expansion provides a noticeable
|
| 16490 | |
speedup in script execution; but testing for support requires
|
| 16491 | |
@command{eval} to avoid syntax errors. The following construct is used
|
| 16492 | |
by @code{AS_VAR_ARITH} to provide arithmetic computation when all
|
| 16493 | |
arguments are provided in decimal and without a leading zero, and all
|
| 16494 | |
operators are properly quoted and appear as distinct arguments:
|
| 16495 | |
|
| 16496 | |
@example
|
| 16497 | |
if ( eval 'test $(( 1 + 1 )) = 2' ) 2>/dev/null; then
|
| 16498 | |
eval 'func_arith ()
|
| 16499 | |
@{
|
| 16500 | |
func_arith_result=$(( $* ))
|
| 16501 | |
@}'
|
| 16502 | |
else
|
| 16503 | |
func_arith ()
|
| 16504 | |
@{
|
| 16505 | |
func_arith_result=`expr "$@@"`
|
| 16506 | |
@}
|
| 16507 | |
fi
|
| 16508 | |
func_arith 1 + 1
|
| 16509 | |
foo=$func_arith_result
|
| 16510 | |
@end example
|
| 16511 | |
|
| 16512 | |
|
| 16513 | |
@item ^
|
| 16514 | |
@cindex @code{^} quoting
|
| 16515 | |
Always quote @samp{^}, otherwise traditional shells such as
|
| 16516 | |
@command{/bin/sh} on Solaris 10 treat this like @samp{|}.
|
| 16517 | |
|
| 16518 | |
@end table
|
| 16519 | |
|
| 16520 | |
|
| 16521 | |
@node Assignments
|
| 16522 | |
@section Assignments
|
| 16523 | |
@cindex Shell assignments
|
| 16524 | |
|
| 16525 | |
When setting several variables in a row, be aware that the order of the
|
| 16526 | |
evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
|
| 16527 | |
gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
|
| 16528 | |
You must use
|
| 16529 | |
@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
|
| 16530 | |
|
| 16531 | |
Don't rely on the following to find @file{subdir/program}:
|
| 16532 | |
|
| 16533 | |
@example
|
| 16534 | |
PATH=subdir$PATH_SEPARATOR$PATH program
|
| 16535 | |
@end example
|
| 16536 | |
|
| 16537 | |
@noindent
|
| 16538 | |
as this does not work with Zsh 3.0.6. Use something like this
|
| 16539 | |
instead:
|
| 16540 | |
|
| 16541 | |
@example
|
| 16542 | |
(PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
|
| 16543 | |
@end example
|
| 16544 | |
|
| 16545 | |
Don't rely on the exit status of an assignment: Ash 0.2 does not change
|
| 16546 | |
the status and propagates that of the last statement:
|
| 16547 | |
|
| 16548 | |
@example
|
| 16549 | |
$ @kbd{false || foo=bar; echo $?}
|
| 16550 | |
1
|
| 16551 | |
$ @kbd{false || foo=`:`; echo $?}
|
| 16552 | |
0
|
| 16553 | |
@end example
|
| 16554 | |
|
| 16555 | |
@noindent
|
| 16556 | |
and to make things even worse, QNX 4.25 just sets the exit status
|
| 16557 | |
to 0 in any case:
|
| 16558 | |
|
| 16559 | |
@example
|
| 16560 | |
$ @kbd{foo=`exit 1`; echo $?}
|
| 16561 | |
0
|
| 16562 | |
@end example
|
| 16563 | |
|
| 16564 | |
To assign default values, follow this algorithm:
|
| 16565 | |
|
| 16566 | |
@enumerate
|
| 16567 | |
@item
|
| 16568 | |
If the default value is a literal and does not contain any closing
|
| 16569 | |
brace, use:
|
| 16570 | |
|
| 16571 | |
@example
|
| 16572 | |
: "$@{var='my literal'@}"
|
| 16573 | |
@end example
|
| 16574 | |
|
| 16575 | |
@item
|
| 16576 | |
If the default value contains no closing brace, has to be expanded, and
|
| 16577 | |
the variable being initialized is not intended to be IFS-split
|
| 16578 | |
(i.e., it's not a list), then use:
|
| 16579 | |
|
| 16580 | |
@example
|
| 16581 | |
: $@{var="$default"@}
|
| 16582 | |
@end example
|
| 16583 | |
|
| 16584 | |
@item
|
| 16585 | |
If the default value contains no closing brace, has to be expanded, and
|
| 16586 | |
the variable being initialized is intended to be IFS-split (i.e., it's a list),
|
| 16587 | |
then use:
|
| 16588 | |
|
| 16589 | |
@example
|
| 16590 | |
var=$@{var="$default"@}
|
| 16591 | |
@end example
|
| 16592 | |
|
| 16593 | |
@item
|
| 16594 | |
If the default value contains a closing brace, then use:
|
| 16595 | |
|
| 16596 | |
@example
|
| 16597 | |
test "$@{var+set@}" = set || var="has a '@}'"
|
| 16598 | |
@end example
|
| 16599 | |
@end enumerate
|
| 16600 | |
|
| 16601 | |
In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
|
| 16602 | |
doubt, just use the last form. @xref{Shell Substitutions}, items
|
| 16603 | |
@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
|
| 16604 | |
for the rationale.
|
| 16605 | |
|
| 16606 | |
@node Parentheses
|
| 16607 | |
@section Parentheses in Shell Scripts
|
| 16608 | |
@cindex Shell parentheses
|
| 16609 | |
|
| 16610 | |
Beware of two opening parentheses in a row, as many shell
|
| 16611 | |
implementations treat them specially, and Posix says that a portable
|
| 16612 | |
script cannot use @samp{((} outside the @samp{$((} form used for shell
|
| 16613 | |
arithmetic. In traditional shells, @samp{((cat))} behaves like
|
| 16614 | |
@samp{(cat)}; but many shells, including
|
| 16615 | |
Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
|
| 16616 | |
expression equivalent to @samp{let "cat"}, and may or may not report an
|
| 16617 | |
error when they detect that @samp{cat} is not a number. As another
|
| 16618 | |
example, @samp{pdksh} 5.2.14 does not treat the following code
|
| 16619 | |
as a traditional shell would:
|
| 16620 | |
|
| 16621 | |
@example
|
| 16622 | |
if ((true) || false); then
|
| 16623 | |
echo ok
|
| 16624 | |
fi
|
| 16625 | |
@end example
|
| 16626 | |
|
| 16627 | |
@noindent
|
| 16628 | |
To work around this problem, insert a space between the two opening
|
| 16629 | |
parentheses. There is a similar problem and workaround with
|
| 16630 | |
@samp{$((}; see @ref{Shell Substitutions}.
|
| 16631 | |
|
| 16632 | |
@node Slashes
|
| 16633 | |
@section Slashes in Shell Scripts
|
| 16634 | |
@cindex Shell slashes
|
| 16635 | |
|
| 16636 | |
Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
|
| 16637 | |
arguments that contain two trailing slashes:
|
| 16638 | |
|
| 16639 | |
@example
|
| 16640 | |
$ @kbd{echo / // /// //// .// //.}
|
| 16641 | |
/ / // /// ./ //.
|
| 16642 | |
$ @kbd{x=//}
|
| 16643 | |
$ @kbd{eval "echo \$x"}
|
| 16644 | |
/
|
| 16645 | |
$ @kbd{set -x}
|
| 16646 | |
$ @kbd{echo abc | tr -t ab //}
|
| 16647 | |
+ echo abc
|
| 16648 | |
+ tr -t ab /
|
| 16649 | |
/bc
|
| 16650 | |
@end example
|
| 16651 | |
|
| 16652 | |
Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
|
| 16653 | |
variable is empty and the second double-quote is followed by a word that
|
| 16654 | |
begins and ends with slash:
|
| 16655 | |
|
| 16656 | |
@example
|
| 16657 | |
$ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
|
| 16658 | |
p=
|
| 16659 | |
+ echo //ouch/
|
| 16660 | |
//ouch/
|
| 16661 | |
@end example
|
| 16662 | |
|
| 16663 | |
However, our understanding is that patches are available, so perhaps
|
| 16664 | |
it's not worth worrying about working around these horrendous bugs.
|
| 16665 | |
|
| 16666 | |
@node Special Shell Variables
|
| 16667 | |
@section Special Shell Variables
|
| 16668 | |
@cindex Shell variables
|
| 16669 | |
@cindex Special shell variables
|
| 16670 | |
|
| 16671 | |
Some shell variables should not be used, since they can have a deep
|
| 16672 | |
influence on the behavior of the shell. In order to recover a sane
|
| 16673 | |
behavior from the shell, some variables should be unset; M4sh takes
|
| 16674 | |
care of this and provides fallback values, whenever needed, to cater
|
| 16675 | |
for a very old @file{/bin/sh} that does not support @command{unset}.
|
| 16676 | |
(@pxref{Portable Shell, , Portable Shell Programming}).
|
| 16677 | |
|
| 16678 | |
As a general rule, shell variable names containing a lower-case letter
|
| 16679 | |
are safe; you can define and use these variables without worrying about
|
| 16680 | |
their effect on the underlying system, and without worrying about
|
| 16681 | |
whether the shell changes them unexpectedly. (The exception is the
|
| 16682 | |
shell variable @code{status}, as described below.)
|
| 16683 | |
|
| 16684 | |
Here is a list of names that are known to cause trouble. This list is
|
| 16685 | |
not exhaustive, but you should be safe if you avoid the name
|
| 16686 | |
@code{status} and names containing only upper-case letters and
|
| 16687 | |
underscores.
|
| 16688 | |
|
| 16689 | |
@c Alphabetical order, case insensitive, `A' before `a'.
|
| 16690 | |
@table @code
|
| 16691 | |
@item ?
|
| 16692 | |
Not all shells correctly reset @samp{$?} after conditionals (@pxref{if,
|
| 16693 | |
, Limitations of Shell Builtins}). Not all shells manage @samp{$?}
|
| 16694 | |
correctly in shell functions (@pxref{Shell Functions}) or in traps
|
| 16695 | |
(@pxref{trap, , Limitations of Shell Builtins}). Not all shells reset
|
| 16696 | |
@samp{$?} to zero after an empty command.
|
| 16697 | |
|
| 16698 | |
@example
|
| 16699 | |
$ @kbd{bash -c 'false; $empty; echo $?'}
|
| 16700 | |
0
|
| 16701 | |
$ @kbd{zsh -c 'false; $empty; echo $?'}
|
| 16702 | |
1
|
| 16703 | |
@end example
|
| 16704 | |
|
| 16705 | |
@item _
|
| 16706 | |
@evindex _
|
| 16707 | |
Many shells reserve @samp{$_} for various purposes, e.g., the name of
|
| 16708 | |
the last command executed.
|
| 16709 | |
|
| 16710 | |
@item BIN_SH
|
| 16711 | |
@evindex BIN_SH
|
| 16712 | |
In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
|
| 16713 | |
the standard shell conform to Posix.
|
| 16714 | |
|
| 16715 | |
@item CDPATH
|
| 16716 | |
@evindex CDPATH
|
| 16717 | |
When this variable is set it specifies a list of directories to search
|
| 16718 | |
when invoking @code{cd} with a relative file name that did not start
|
| 16719 | |
with @samp{./} or @samp{../}. Posix
|
| 16720 | |
1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
|
| 16721 | |
is used successfully, @code{cd} prints the resulting absolute
|
| 16722 | |
file name. Unfortunately this output can break idioms like
|
| 16723 | |
@samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
|
| 16724 | |
Also, many shells do not conform to this part of Posix; for
|
| 16725 | |
example, @command{zsh} prints the result only if a directory name
|
| 16726 | |
other than @file{.} was chosen from @env{CDPATH}.
|
| 16727 | |
|
| 16728 | |
In practice the shells that have this problem also support
|
| 16729 | |
@command{unset}, so you can work around the problem as follows:
|
| 16730 | |
|
| 16731 | |
@example
|
| 16732 | |
(unset CDPATH) >/dev/null 2>&1 && unset CDPATH
|
| 16733 | |
@end example
|
| 16734 | |
|
| 16735 | |
You can also avoid output by ensuring that your directory name is
|
| 16736 | |
absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
|
| 16737 | |
|
| 16738 | |
Configure scripts use M4sh, which automatically unsets @env{CDPATH} if
|
| 16739 | |
possible, so you need not worry about this problem in those scripts.
|
| 16740 | |
|
| 16741 | |
@item CLICOLOR_FORCE
|
| 16742 | |
@evindex CLICOLOR_FORCE
|
| 16743 | |
When this variable is set, some implementations of tools like
|
| 16744 | |
@command{ls} attempt to add color to their output via terminal escape
|
| 16745 | |
sequences, even when the output is not directed to a terminal, and can
|
| 16746 | |
thus cause spurious failures in scripts. Configure scripts use M4sh,
|
| 16747 | |
which automatically unsets this variable.
|
| 16748 | |
|
| 16749 | |
@item DUALCASE
|
| 16750 | |
@evindex DUALCASE
|
| 16751 | |
In the MKS shell, case statements and file name generation are
|
| 16752 | |
case-insensitive unless @env{DUALCASE} is nonzero.
|
| 16753 | |
Autoconf-generated scripts export this variable when they start up.
|
| 16754 | |
|
| 16755 | |
@item ENV
|
| 16756 | |
@itemx MAIL
|
| 16757 | |
@itemx MAILPATH
|
| 16758 | |
@itemx PS1
|
| 16759 | |
@itemx PS2
|
| 16760 | |
@itemx PS4
|
| 16761 | |
@evindex ENV
|
| 16762 | |
@evindex MAIL
|
| 16763 | |
@evindex MAILPATH
|
| 16764 | |
@evindex PS1
|
| 16765 | |
@evindex PS2
|
| 16766 | |
@evindex PS4
|
| 16767 | |
These variables should not matter for shell scripts, since they are
|
| 16768 | |
supposed to affect only interactive shells. However, at least one
|
| 16769 | |
shell (the pre-3.0 UWIN Korn shell) gets confused about
|
| 16770 | |
whether it is interactive, which means that (for example) a @env{PS1}
|
| 16771 | |
with a side effect can unexpectedly modify @samp{$?}. To work around
|
| 16772 | |
this bug, M4sh scripts (including @file{configure} scripts) do something
|
| 16773 | |
like this:
|
| 16774 | |
|
| 16775 | |
@example
|
| 16776 | |
(unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
|
| 16777 | |
PS1='$ '
|
| 16778 | |
PS2='> '
|
| 16779 | |
PS4='+ '
|
| 16780 | |
@end example
|
| 16781 | |
|
| 16782 | |
@noindent
|
| 16783 | |
(actually, there is some complication due to bugs in @command{unset};
|
| 16784 | |
@pxref{unset, , Limitations of Shell Builtins}).
|
| 16785 | |
|
| 16786 | |
@item FPATH
|
| 16787 | |
@evindex FPATH
|
| 16788 | |
The Korn shell uses @env{FPATH} to find shell functions, so avoid
|
| 16789 | |
@env{FPATH} in portable scripts. @env{FPATH} is consulted after
|
| 16790 | |
@env{PATH}, but you still need to be wary of tests that use @env{PATH}
|
| 16791 | |
to find whether a command exists, since they might report the wrong
|
| 16792 | |
result if @env{FPATH} is also set.
|
| 16793 | |
|
| 16794 | |
@item GREP_OPTIONS
|
| 16795 | |
@evindex GREP_OPTIONS
|
| 16796 | |
When this variable is set, some implementations of @command{grep} honor
|
| 16797 | |
these options, even if the options include direction to enable colored
|
| 16798 | |
output via terminal escape sequences, and the result can cause spurious
|
| 16799 | |
failures when the output is not directed to a terminal. Configure
|
| 16800 | |
scripts use M4sh, which automatically unsets this variable.
|
| 16801 | |
|
| 16802 | |
@item IFS
|
| 16803 | |
@evindex IFS
|
| 16804 | |
Long ago, shell scripts inherited @env{IFS} from the environment,
|
| 16805 | |
but this caused many problems so modern shells ignore any environment
|
| 16806 | |
settings for @env{IFS}.
|
| 16807 | |
|
| 16808 | |
Don't set the first character of @env{IFS} to backslash. Indeed,
|
| 16809 | |
Bourne shells use the first character (backslash) when joining the
|
| 16810 | |
components in @samp{"$@@"} and some shells then reinterpret (!)@: the
|
| 16811 | |
backslash escapes, so you can end up with backspace and other strange
|
| 16812 | |
characters.
|
| 16813 | |
|
| 16814 | |
The proper value for @env{IFS} (in regular code, not when performing
|
| 16815 | |
splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
|
| 16816 | |
especially important, as it is used to join the arguments in @samp{$*};
|
| 16817 | |
however, note that traditional shells, but also bash-2.04, fail to adhere
|
| 16818 | |
to this and join with a space anyway.
|
| 16819 | |
|
| 16820 | |
M4sh guarantees that @env{IFS} will have the default value at the
|
| 16821 | |
beginning of a script, and many macros within autoconf rely on this
|
| 16822 | |
setting. It is okay to use blocks of shell code that temporarily change
|
| 16823 | |
the value of @env{IFS} in order to split on another character, but
|
| 16824 | |
remember to restore it before expanding further macros.
|
| 16825 | |
|
| 16826 | |
Unsetting @code{IFS} instead of resetting it to the default sequence
|
| 16827 | |
is not suggested, since code that tries to save and restore the
|
| 16828 | |
variable's value will incorrectly reset it to an empty value, thus
|
| 16829 | |
disabling field splitting:
|
| 16830 | |
|
| 16831 | |
@example
|
| 16832 | |
unset IFS
|
| 16833 | |
# default separators used for field splitting
|
| 16834 | |
|
| 16835 | |
save_IFS=$IFS
|
| 16836 | |
IFS=:
|
| 16837 | |
# ...
|
| 16838 | |
IFS=$save_IFS
|
| 16839 | |
# no field splitting performed
|
| 16840 | |
@end example
|
| 16841 | |
|
| 16842 | |
@item LANG
|
| 16843 | |
@itemx LC_ALL
|
| 16844 | |
@itemx LC_COLLATE
|
| 16845 | |
@itemx LC_CTYPE
|
| 16846 | |
@itemx LC_MESSAGES
|
| 16847 | |
@itemx LC_MONETARY
|
| 16848 | |
@itemx LC_NUMERIC
|
| 16849 | |
@itemx LC_TIME
|
| 16850 | |
@evindex LANG
|
| 16851 | |
@evindex LC_ALL
|
| 16852 | |
@evindex LC_COLLATE
|
| 16853 | |
@evindex LC_CTYPE
|
| 16854 | |
@evindex LC_MESSAGES
|
| 16855 | |
@evindex LC_MONETARY
|
| 16856 | |
@evindex LC_NUMERIC
|
| 16857 | |
@evindex LC_TIME
|
| 16858 | |
|
| 16859 | |
You should set all these variables to @samp{C} because so much
|
| 16860 | |
configuration code assumes the C locale and Posix requires that locale
|
| 16861 | |
environment variables be set to @samp{C} if the C locale is desired;
|
| 16862 | |
@file{configure} scripts and M4sh do that for you.
|
| 16863 | |
Export these variables after setting them.
|
| 16864 | |
|
| 16865 | |
@c However, some older, nonstandard
|
| 16866 | |
@c systems (notably SCO) break if locale environment variables
|
| 16867 | |
@c are set to @samp{C}, so when running on these systems
|
| 16868 | |
@c Autoconf-generated scripts unset the variables instead.
|
| 16869 | |
|
| 16870 | |
@item LANGUAGE
|
| 16871 | |
@evindex LANGUAGE
|
| 16872 | |
|
| 16873 | |
@env{LANGUAGE} is not specified by Posix, but it is a GNU
|
| 16874 | |
extension that overrides @env{LC_ALL} in some cases, so you (or M4sh)
|
| 16875 | |
should set it too.
|
| 16876 | |
|
| 16877 | |
@item LC_ADDRESS
|
| 16878 | |
@itemx LC_IDENTIFICATION
|
| 16879 | |
@itemx LC_MEASUREMENT
|
| 16880 | |
@itemx LC_NAME
|
| 16881 | |
@itemx LC_PAPER
|
| 16882 | |
@itemx LC_TELEPHONE
|
| 16883 | |
@evindex LC_ADDRESS
|
| 16884 | |
@evindex LC_IDENTIFICATION
|
| 16885 | |
@evindex LC_MEASUREMENT
|
| 16886 | |
@evindex LC_NAME
|
| 16887 | |
@evindex LC_PAPER
|
| 16888 | |
@evindex LC_TELEPHONE
|
| 16889 | |
|
| 16890 | |
These locale environment variables are GNU extensions. They
|
| 16891 | |
are treated like their Posix brethren (@env{LC_COLLATE},
|
| 16892 | |
etc.)@: as described above.
|
| 16893 | |
|
| 16894 | |
@item LINENO
|
| 16895 | |
@evindex LINENO
|
| 16896 | |
Most modern shells provide the current line number in @code{LINENO}.
|
| 16897 | |
Its value is the line number of the beginning of the current command.
|
| 16898 | |
M4sh, and hence Autoconf, attempts to execute @command{configure} with
|
| 16899 | |
a shell that supports @code{LINENO}. If no such shell is available, it
|
| 16900 | |
attempts to implement @code{LINENO} with a Sed prepass that replaces each
|
| 16901 | |
instance of the string @code{$LINENO} (not followed by an alphanumeric
|
| 16902 | |
character) with the line's number. In M4sh scripts you should execute
|
| 16903 | |
@code{AS_LINENO_PREPARE} so that these workarounds are included in
|
| 16904 | |
your script; configure scripts do this automatically in @code{AC_INIT}.
|
| 16905 | |
|
| 16906 | |
You should not rely on @code{LINENO} within @command{eval} or shell
|
| 16907 | |
functions, as the behavior differs in practice. The presence of a
|
| 16908 | |
quoted newline within simple commands can alter which line number is
|
| 16909 | |
used as the starting point for @code{$LINENO} substitutions within that
|
| 16910 | |
command. Also, the possibility of the Sed prepass means that you should
|
| 16911 | |
not rely on @code{$LINENO} when quoted, when in here-documents, or when
|
| 16912 | |
line continuations are used. Subshells should be OK, though. In the
|
| 16913 | |
following example, lines 1, 9, and 14 are portable, but the other
|
| 16914 | |
instances of @code{$LINENO} do not have deterministic values:
|
| 16915 | |
|
| 16916 | |
@example
|
| 16917 | |
@group
|
| 16918 | |
$ @kbd{cat lineno}
|
| 16919 | |
echo 1. $LINENO
|
| 16920 | |
echo "2. $LINENO
|
| 16921 | |
3. $LINENO"
|
| 16922 | |
cat <<EOF
|
| 16923 | |
5. $LINENO
|
| 16924 | |
6. $LINENO
|
| 16925 | |
7. \$LINENO
|
| 16926 | |
EOF
|
| 16927 | |
( echo 9. $LINENO )
|
| 16928 | |
eval 'echo 10. $LINENO'
|
| 16929 | |
eval 'echo 11. $LINENO
|
| 16930 | |
echo 12. $LINENO'
|
| 16931 | |
echo 13. '$LINENO'
|
| 16932 | |
echo 14. $LINENO '
|
| 16933 | |
15.' $LINENO
|
| 16934 | |
f () @{ echo $1 $LINENO;
|
| 16935 | |
echo $1 $LINENO @}
|
| 16936 | |
f 18.
|
| 16937 | |
echo 19. \
|
| 16938 | |
$LINENO
|
| 16939 | |
@end group
|
| 16940 | |
@group
|
| 16941 | |
$ @kbd{bash-3.2 ./lineno}
|
| 16942 | |
1. 1
|
| 16943 | |
2. 3
|
| 16944 | |
3. 3
|
| 16945 | |
5. 4
|
| 16946 | |
6. 4
|
| 16947 | |
7. $LINENO
|
| 16948 | |
9. 9
|
| 16949 | |
10. 10
|
| 16950 | |
11. 12
|
| 16951 | |
12. 13
|
| 16952 | |
13. $LINENO
|
| 16953 | |
14. 14
|
| 16954 | |
15. 14
|
| 16955 | |
18. 16
|
| 16956 | |
18. 17
|
| 16957 | |
19. 19
|
| 16958 | |
@end group
|
| 16959 | |
@group
|
| 16960 | |
$ @kbd{zsh-4.3.4 ./lineno}
|
| 16961 | |
1. 1
|
| 16962 | |
2. 2
|
| 16963 | |
3. 2
|
| 16964 | |
5. 4
|
| 16965 | |
6. 4
|
| 16966 | |
7. $LINENO
|
| 16967 | |
9. 9
|
| 16968 | |
10. 1
|
| 16969 | |
11. 1
|
| 16970 | |
12. 2
|
| 16971 | |
13. $LINENO
|
| 16972 | |
14. 14
|
| 16973 | |
15. 14
|
| 16974 | |
18. 0
|
| 16975 | |
18. 1
|
| 16976 | |
19. 19
|
| 16977 | |
@end group
|
| 16978 | |
@group
|
| 16979 | |
$ @kbd{pdksh-5.2.14 ./lineno}
|
| 16980 | |
1. 1
|
| 16981 | |
2. 2
|
| 16982 | |
3. 2
|
| 16983 | |
5. 4
|
| 16984 | |
6. 4
|
| 16985 | |
7. $LINENO
|
| 16986 | |
9. 9
|
| 16987 | |
10. 0
|
| 16988 | |
11. 0
|
| 16989 | |
12. 0
|
| 16990 | |
13. $LINENO
|
| 16991 | |
14. 14
|
| 16992 | |
15. 14
|
| 16993 | |
18. 16
|
| 16994 | |
18. 17
|
| 16995 | |
19. 19
|
| 16996 | |
@end group
|
| 16997 | |
@group
|
| 16998 | |
$ @kbd{sed '=' <lineno |}
|
| 16999 | |
> @kbd{ sed '}
|
| 17000 | |
> @kbd{ N}
|
| 17001 | |
> @kbd{ s,$,-,}
|
| 17002 | |
> @kbd{ t loop}
|
| 17003 | |
> @kbd{ :loop}
|
| 17004 | |
> @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
|
| 17005 | |
> @kbd{ t loop}
|
| 17006 | |
> @kbd{ s,-$,,}
|
| 17007 | |
> @kbd{ s,^[0-9]*\n,,}
|
| 17008 | |
> @kbd{ ' |}
|
| 17009 | |
> @kbd{ sh}
|
| 17010 | |
1. 1
|
| 17011 | |
2. 2
|
| 17012 | |
3. 3
|
| 17013 | |
5. 5
|
| 17014 | |
6. 6
|
| 17015 | |
7. \7
|
| 17016 | |
9. 9
|
| 17017 | |
10. 10
|
| 17018 | |
11. 11
|
| 17019 | |
12. 12
|
| 17020 | |
13. 13
|
| 17021 | |
14. 14
|
| 17022 | |
15. 15
|
| 17023 | |
18. 16
|
| 17024 | |
18. 17
|
| 17025 | |
19. 20
|
| 17026 | |
@end group
|
| 17027 | |
@end example
|
| 17028 | |
|
| 17029 | |
In particular, note that @file{config.status} (and any other subsidiary
|
| 17030 | |
script created by @code{AS_INIT_GENERATED}) might report line numbers
|
| 17031 | |
relative to the parent script as a result of the potential Sed pass.
|
| 17032 | |
|
| 17033 | |
@item NULLCMD
|
| 17034 | |
@evindex NULLCMD
|
| 17035 | |
When executing the command @samp{>foo}, @command{zsh} executes
|
| 17036 | |
@samp{$NULLCMD >foo} unless it is operating in Bourne shell
|
| 17037 | |
compatibility mode and the @command{zsh} version is newer
|
| 17038 | |
than 3.1.6-dev-18. If you are using an older @command{zsh}
|
| 17039 | |
and forget to set @env{NULLCMD},
|
| 17040 | |
your script might be suspended waiting for data on its standard input.
|
| 17041 | |
|
| 17042 | |
@item options
|
| 17043 | |
@evindex options
|
| 17044 | |
For @command{zsh} 4.3.10, @env{options} is treated as an associative
|
| 17045 | |
array even after @code{emulate sh}, so it should not be used.
|
| 17046 | |
|
| 17047 | |
@item PATH_SEPARATOR
|
| 17048 | |
@evindex PATH_SEPARATOR
|
| 17049 | |
On DJGPP systems, the @env{PATH_SEPARATOR} environment
|
| 17050 | |
variable can be set to either @samp{:} or @samp{;} to control the path
|
| 17051 | |
separator Bash uses to set up certain environment variables (such as
|
| 17052 | |
@env{PATH}). You can set this variable to @samp{;} if you want
|
| 17053 | |
@command{configure} to use @samp{;} as a separator; this might be useful
|
| 17054 | |
if you plan to use non-Posix shells to execute files. @xref{File System
|
| 17055 | |
Conventions}, for more information about @code{PATH_SEPARATOR}.
|
| 17056 | |
|
| 17057 | |
@item POSIXLY_CORRECT
|
| 17058 | |
@evindex POSIXLY_CORRECT
|
| 17059 | |
In the GNU environment, exporting @env{POSIXLY_CORRECT} with any value
|
| 17060 | |
(even empty) causes programs to try harder to conform to Posix.
|
| 17061 | |
Autoconf does not directly manipulate this variable, but @command{bash}
|
| 17062 | |
ties the shell variable @env{POSIXLY_CORRECT} to whether the script is
|
| 17063 | |
running in Posix mode. Therefore, take care when exporting or unsetting
|
| 17064 | |
this variable, so as not to change whether @command{bash} is in Posix
|
| 17065 | |
mode.
|
| 17066 | |
|
| 17067 | |
@example
|
| 17068 | |
$ @kbd{bash --posix -c 'set -o | grep posix}
|
| 17069 | |
> @kbd{unset POSIXLY_CORRECT}
|
| 17070 | |
> @kbd{set -o | grep posix'}
|
| 17071 | |
posix on
|
| 17072 | |
posix off
|
| 17073 | |
@end example
|
| 17074 | |
|
| 17075 | |
@item PWD
|
| 17076 | |
@evindex PWD
|
| 17077 | |
Posix 1003.1-2001 requires that @command{cd} and
|
| 17078 | |
@command{pwd} must update the @env{PWD} environment variable to point
|
| 17079 | |
to the logical name of the current directory, but traditional shells
|
| 17080 | |
do not support this. This can cause confusion if one shell instance
|
| 17081 | |
maintains @env{PWD} but a subsidiary and different shell does not know
|
| 17082 | |
about @env{PWD} and executes @command{cd}; in this case @env{PWD}
|
| 17083 | |
points to the wrong directory. Use @samp{`pwd`} rather than
|
| 17084 | |
@samp{$PWD}.
|
| 17085 | |
|
| 17086 | |
@item RANDOM
|
| 17087 | |
@evindex RANDOM
|
| 17088 | |
Many shells provide @code{RANDOM}, a variable that returns a different
|
| 17089 | |
integer each time it is used. Most of the time, its value does not
|
| 17090 | |
change when it is not used, but on IRIX 6.5 the value changes all
|
| 17091 | |
the time. This can be observed by using @command{set}. It is common
|
| 17092 | |
practice to use @code{$RANDOM} as part of a file name, but code
|
| 17093 | |
shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
|
| 17094 | |
|
| 17095 | |
@item status
|
| 17096 | |
@evindex status
|
| 17097 | |
This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
|
| 17098 | |
hence read-only. Do not use it.
|
| 17099 | |
@end table
|
| 17100 | |
|
| 17101 | |
@node Shell Functions
|
| 17102 | |
@section Shell Functions
|
| 17103 | |
@cindex Shell Functions
|
| 17104 | |
|
| 17105 | |
Nowadays, it is difficult to find a shell that does not support
|
| 17106 | |
shell functions at all. However, some differences should be expected.
|
| 17107 | |
|
| 17108 | |
When declaring a shell function, you must include whitespace between the
|
| 17109 | |
@samp{)} after the function name and the start of the compound
|
| 17110 | |
expression, to avoid upsetting @command{ksh}. While it is possible to
|
| 17111 | |
use any compound command, most scripts use @samp{@{@dots{}@}}.
|
| 17112 | |
|
| 17113 | |
@example
|
| 17114 | |
$ @kbd{/bin/sh -c 'a()@{ echo hi;@}; a'}
|
| 17115 | |
hi
|
| 17116 | |
$ @kbd{ksh -c 'a()@{ echo hi;@}; a'}
|
| 17117 | |
ksh: syntax error at line 1: `@}' unexpected
|
| 17118 | |
$ @kbd{ksh -c 'a() @{ echo hi;@}; a'}
|
| 17119 | |
hi
|
| 17120 | |
@end example
|
| 17121 | |
|
| 17122 | |
Inside a shell function, you should not rely on the error status of a
|
| 17123 | |
subshell if the last command of that subshell was @code{exit} or
|
| 17124 | |
@code{trap}, as this triggers bugs in zsh 4.x; while Autoconf tries to
|
| 17125 | |
find a shell that does not exhibit the bug, zsh might be the only shell
|
| 17126 | |
present on the user's machine.
|
| 17127 | |
|
| 17128 | |
Likewise, the state of @samp{$?} is not reliable when entering a shell
|
| 17129 | |
function. This has the effect that using a function as the first
|
| 17130 | |
command in a @command{trap} handler can cause problems.
|
| 17131 | |
|
| 17132 | |
@example
|
| 17133 | |
$ @kbd{bash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?}
|
| 17134 | |
2
|
| 17135 | |
2
|
| 17136 | |
$ @kbd{ash -c 'foo() @{ echo $?; @}; trap foo 0; (exit 2); exit 2'; echo $?}
|
| 17137 | |
0
|
| 17138 | |
2
|
| 17139 | |
@end example
|
| 17140 | |
|
| 17141 | |
DJGPP bash 2.04 has a bug in that @command{return} from a
|
| 17142 | |
shell function which also used a command substitution causes a
|
| 17143 | |
segmentation fault. To work around the issue, you can use
|
| 17144 | |
@command{return} from a subshell, or @samp{AS_SET_STATUS} as last command
|
| 17145 | |
in the execution flow of the function (@pxref{Common Shell Constructs}).
|
| 17146 | |
|
| 17147 | |
Not all shells treat shell functions as simple commands impacted by
|
| 17148 | |
@samp{set -e}, for example with Solaris 10 @command{/bin/sh}:
|
| 17149 | |
|
| 17150 | |
@example
|
| 17151 | |
$ @kbd{bash -c 'f() @{ return 1; @}; set -e; f; echo oops'}
|
| 17152 | |
$ @kbd{/bin/sh -c 'f() @{ return 1; @}; set -e; f; echo oops'}
|
| 17153 | |
oops
|
| 17154 | |
@end example
|
| 17155 | |
|
| 17156 | |
Shell variables and functions may share the same namespace, for example
|
| 17157 | |
with Solaris 10 @command{/bin/sh}:
|
| 17158 | |
|
| 17159 | |
@example
|
| 17160 | |
$ @kbd{f () @{ :; @}; f=; f}
|
| 17161 | |
f: not found
|
| 17162 | |
@end example
|
| 17163 | |
|
| 17164 | |
@noindent
|
| 17165 | |
For this reason, Autoconf (actually M4sh, @pxref{Programming in M4sh})
|
| 17166 | |
uses the prefix @samp{as_fn_} for its functions.
|
| 17167 | |
|
| 17168 | |
Handling of positional parameters and shell options varies among shells.
|
| 17169 | |
For example, Korn shells reset and restore trace output (@samp{set -x})
|
| 17170 | |
and other options upon function entry and exit. Inside a function,
|
| 17171 | |
IRIX sh sets @samp{$0} to the function name.
|
| 17172 | |
|
| 17173 | |
It is not portable to pass temporary environment variables to shell
|
| 17174 | |
functions. Solaris @command{/bin/sh} does not see the variable.
|
| 17175 | |
Meanwhile, not all shells follow the Posix rule that the assignment must
|
| 17176 | |
affect the current environment in the same manner as special built-ins.
|
| 17177 | |
|
| 17178 | |
@example
|
| 17179 | |
$ @kbd{/bin/sh -c 'func() @{ echo $a;@}; a=1 func; echo $a'}
|
| 17180 | |
@result{}
|
| 17181 | |
@result{}
|
| 17182 | |
$ @kbd{ash -c 'func() @{ echo $a;@}; a=1 func; echo $a'}
|
| 17183 | |
@result{}1
|
| 17184 | |
@result{}
|
| 17185 | |
$ @kbd{bash -c 'set -o posix; func() @{ echo $a;@}; a=1 func; echo $a'}
|
| 17186 | |
@result{}1
|
| 17187 | |
@result{}1
|
| 17188 | |
@end example
|
| 17189 | |
|
| 17190 | |
Some ancient Bourne shell variants with function support did not reset
|
| 17191 | |
@samp{$@var{i}, @var{i} >= 0}, upon function exit, so effectively the
|
| 17192 | |
arguments of the script were lost after the first function invocation.
|
| 17193 | |
It is probably not worth worrying about these shells any more.
|
| 17194 | |
|
| 17195 | |
With AIX sh, a @command{trap} on 0 installed in a shell function
|
| 17196 | |
triggers at function exit rather than at script exit. @xref{trap, ,
|
| 17197 | |
Limitations of Shell Builtins}.
|
| 17198 | |
|
| 17199 | |
@node Limitations of Builtins
|
| 17200 | |
@section Limitations of Shell Builtins
|
| 17201 | |
@cindex Shell builtins
|
| 17202 | |
@cindex Limitations of shell builtins
|
| 17203 | |
|
| 17204 | |
No, no, we are serious: some shells do have limitations! :)
|
| 17205 | |
|
| 17206 | |
You should always keep in mind that any builtin or command may support
|
| 17207 | |
options, and therefore differ in behavior with arguments
|
| 17208 | |
starting with a dash. For instance, even the innocent @samp{echo "$word"}
|
| 17209 | |
can give unexpected results when @code{word} starts with a dash. It is
|
| 17210 | |
often possible to avoid this problem using @samp{echo "x$word"}, taking
|
| 17211 | |
the @samp{x} into account later in the pipe. Many of these limitations
|
| 17212 | |
can be worked around using M4sh (@pxref{Programming in M4sh}).
|
| 17213 | |
|
| 17214 | |
@c This table includes things like `@command{test} (files)', so we can't
|
| 17215 | |
@c use @table @command.
|
| 17216 | |
@table @asis
|
| 17217 | |
@item @command{.}
|
| 17218 | |
@c --------------
|
| 17219 | |
@prindex @command{.}
|
| 17220 | |
Use @command{.} only with regular files (use @samp{test -f}). Bash
|
| 17221 | |
2.03, for instance, chokes on @samp{. /dev/null}. Remember that
|
| 17222 | |
@command{.} uses @env{PATH} if its argument contains no slashes. Also,
|
| 17223 | |
some shells, including bash 3.2, implicitly append the current directory
|
| 17224 | |
to this @env{PATH} search, even though Posix forbids it. So if you want
|
| 17225 | |
to use @command{.} on a file @file{foo} in the current directory, you
|
| 17226 | |
must use @samp{. ./foo}.
|
| 17227 | |
|
| 17228 | |
Not all shells gracefully handle syntax errors within a sourced file.
|
| 17229 | |
On one extreme, some non-interactive shells abort the entire script. On
|
| 17230 | |
the other, @command{zsh} 4.3.10 has a bug where it fails to react to the
|
| 17231 | |
syntax error.
|
| 17232 | |
|
| 17233 | |
@example
|
| 17234 | |
$ @kbd{echo 'fi' > syntax}
|
| 17235 | |
$ @kbd{bash -c '. ./syntax; echo $?'}
|
| 17236 | |
./syntax: line 1: syntax error near unexpected token `fi'
|
| 17237 | |
./syntax: line 1: `fi'
|
| 17238 | |
1
|
| 17239 | |
$ @kbd{ash -c '. ./syntax; echo $?'}
|
| 17240 | |
./syntax: 1: Syntax error: "fi" unexpected
|
| 17241 | |
$ @kbd{zsh -c '. ./syntax; echo $?'}
|
| 17242 | |
./syntax:1: parse error near `fi'
|
| 17243 | |
0
|
| 17244 | |
@end example
|
| 17245 | |
|
| 17246 | |
@item @command{!}
|
| 17247 | |
@c --------------
|
| 17248 | |
@prindex @command{!}
|
| 17249 | |
The Unix version 7 shell did not support
|
| 17250 | |
negating the exit status of commands with @command{!}, and this feature
|
| 17251 | |
is still absent from some shells (e.g., Solaris @command{/bin/sh}).
|
| 17252 | |
Other shells, such as FreeBSD @command{/bin/sh} or @command{ash}, have
|
| 17253 | |
bugs when using @command{!}:
|
| 17254 | |
|
| 17255 | |
@example
|
| 17256 | |
$ @kbd{sh -c '! : | :'; echo $?}
|
| 17257 | |
1
|
| 17258 | |
$ @kbd{ash -c '! : | :'; echo $?}
|
| 17259 | |
0
|
| 17260 | |
$ @kbd{sh -c '! @{ :; @}'; echo $?}
|
| 17261 | |
1
|
| 17262 | |
$ @kbd{ash -c '! @{ :; @}'; echo $?}
|
| 17263 | |
@{: not found
|
| 17264 | |
Syntax error: "@}" unexpected
|
| 17265 | |
2
|
| 17266 | |
@end example
|
| 17267 | |
|
| 17268 | |
Shell code like this:
|
| 17269 | |
|
| 17270 | |
@example
|
| 17271 | |
if ! cmp file1 file2 >/dev/null 2>&1; then
|
| 17272 | |
echo files differ or trouble
|
| 17273 | |
fi
|
| 17274 | |
@end example
|
| 17275 | |
|
| 17276 | |
is therefore not portable in practice. Typically it is easy to rewrite
|
| 17277 | |
such code, e.g.:
|
| 17278 | |
|
| 17279 | |
@example
|
| 17280 | |
cmp file1 file2 >/dev/null 2>&1 ||
|
| 17281 | |
echo files differ or trouble
|
| 17282 | |
@end example
|
| 17283 | |
|
| 17284 | |
More generally, one can always rewrite @samp{! @var{command}} as:
|
| 17285 | |
|
| 17286 | |
@example
|
| 17287 | |
if @var{command}; then (exit 1); else :; fi
|
| 17288 | |
@end example
|
| 17289 | |
|
| 17290 | |
|
| 17291 | |
@item @command{@{...@}}
|
| 17292 | |
@c --------------------
|
| 17293 | |
@prindex @command{@{...@}}
|
| 17294 | |
Bash 3.2 (and earlier versions) sometimes does not properly set
|
| 17295 | |
@samp{$?} when failing to write redirected output of a compound command.
|
| 17296 | |
This problem is most commonly observed with @samp{@{@dots{}@}}; it does
|
| 17297 | |
not occur with @samp{(@dots{})}. For example:
|
| 17298 | |
|
| 17299 | |
@example
|
| 17300 | |
$ @kbd{bash -c '@{ echo foo; @} >/bad; echo $?'}
|
| 17301 | |
bash: line 1: /bad: Permission denied
|
| 17302 | |
0
|
| 17303 | |
$ @kbd{bash -c 'while :; do echo; done >/bad; echo $?'}
|
| 17304 | |
bash: line 1: /bad: Permission denied
|
| 17305 | |
0
|
| 17306 | |
@end example
|
| 17307 | |
|
| 17308 | |
To work around the bug, prepend @samp{:;}:
|
| 17309 | |
|
| 17310 | |
@example
|
| 17311 | |
$ @kbd{bash -c ':;@{ echo foo; @} >/bad; echo $?'}
|
| 17312 | |
bash: line 1: /bad: Permission denied
|
| 17313 | |
1
|
| 17314 | |
@end example
|
| 17315 | |
|
| 17316 | |
Posix requires a syntax error if a brace list has no contents. However,
|
| 17317 | |
not all shells obey this rule; and on shells where empty lists are
|
| 17318 | |
permitted, the effect on @samp{$?} is inconsistent. To avoid problems,
|
| 17319 | |
ensure that a brace list is never empty.
|
| 17320 | |
|
| 17321 | |
@example
|
| 17322 | |
$ @kbd{bash -c 'false; @{ @}; echo $?' || echo $?}
|
| 17323 | |
bash: line 1: syntax error near unexpected token `@}'
|
| 17324 | |
bash: line 1: `false; @{ @}; echo $?'
|
| 17325 | |
2
|
| 17326 | |
$ @kbd{zsh -c 'false; @{ @}; echo $?' || echo $?}
|
| 17327 | |
1
|
| 17328 | |
$ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?}
|
| 17329 | |
0
|
| 17330 | |
@end example
|
| 17331 | |
|
| 17332 | |
|
| 17333 | |
@item @command{break}
|
| 17334 | |
@c ------------------
|
| 17335 | |
@prindex @command{break}
|
| 17336 | |
The use of @samp{break 2} etc.@: is safe.
|
| 17337 | |
|
| 17338 | |
|
| 17339 | |
@anchor{case}
|
| 17340 | |
@item @command{case}
|
| 17341 | |
@c -----------------
|
| 17342 | |
@prindex @command{case}
|
| 17343 | |
You don't need to quote the argument; no splitting is performed.
|
| 17344 | |
|
| 17345 | |
You don't need the final @samp{;;}, but you should use it.
|
| 17346 | |
|
| 17347 | |
Posix requires support for @code{case} patterns with opening
|
| 17348 | |
parentheses like this:
|
| 17349 | |
|
| 17350 | |
@example
|
| 17351 | |
case $file_name in
|
| 17352 | |
(*.c) echo "C source code";;
|
| 17353 | |
esac
|
| 17354 | |
@end example
|
| 17355 | |
|
| 17356 | |
@noindent
|
| 17357 | |
but the @code{(} in this example is not portable to many Bourne
|
| 17358 | |
shell implementations, which is a pity for those of us using tools that
|
| 17359 | |
rely on balanced parentheses. For instance, with Solaris
|
| 17360 | |
@command{/bin/sh}:
|
| 17361 | |
|
| 17362 | |
@example
|
| 17363 | |
$ @kbd{case foo in (foo) echo foo;; esac}
|
| 17364 | |
@error{}syntax error: `(' unexpected
|
| 17365 | |
@end example
|
| 17366 | |
|
| 17367 | |
@noindent
|
| 17368 | |
The leading @samp{(} can be omitted safely. Unfortunately, there are
|
| 17369 | |
contexts where unbalanced parentheses cause other problems, such as when
|
| 17370 | |
using a syntax-highlighting editor that searches for the balancing
|
| 17371 | |
counterpart, or more importantly, when using a case statement as an
|
| 17372 | |
underquoted argument to an Autoconf macro. @xref{Balancing
|
| 17373 | |
Parentheses}, for tradeoffs involved in various styles of dealing with
|
| 17374 | |
unbalanced @samp{)}.
|
| 17375 | |
|
| 17376 | |
Zsh handles pattern fragments derived from parameter expansions or
|
| 17377 | |
command substitutions as though quoted:
|
| 17378 | |
|
| 17379 | |
@example
|
| 17380 | |
$ pat=\?; case aa in ?$pat) echo match;; esac
|
| 17381 | |
$ pat=\?; case a? in ?$pat) echo match;; esac
|
| 17382 | |
match
|
| 17383 | |
@end example
|
| 17384 | |
|
| 17385 | |
@noindent
|
| 17386 | |
Because of a bug in its @code{fnmatch}, Bash fails to properly
|
| 17387 | |
handle backslashes in character classes:
|
| 17388 | |
|
| 17389 | |
@example
|
| 17390 | |
bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
|
| 17391 | |
bash-2.02$
|
| 17392 | |
@end example
|
| 17393 | |
|
| 17394 | |
@noindent
|
| 17395 | |
This is extremely unfortunate, since you are likely to use this code to
|
| 17396 | |
handle Posix or MS-DOS absolute file names. To work around this
|
| 17397 | |
bug, always put the backslash first:
|
| 17398 | |
|
| 17399 | |
@example
|
| 17400 | |
bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
|
| 17401 | |
OK
|
| 17402 | |
bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
|
| 17403 | |
OK
|
| 17404 | |
@end example
|
| 17405 | |
|
| 17406 | |
Many Bourne shells cannot handle closing brackets in character classes
|
| 17407 | |
correctly.
|
| 17408 | |
|
| 17409 | |
Some shells also have problems with backslash escaping in case you do not want
|
| 17410 | |
to match the backslash: both a backslash and the escaped character match this
|
| 17411 | |
pattern. To work around this, specify the character class in a variable, so
|
| 17412 | |
that quote removal does not apply afterwards, and the special characters don't
|
| 17413 | |
have to be backslash-escaped:
|
| 17414 | |
|
| 17415 | |
@example
|
| 17416 | |
$ @kbd{case '\' in [\<]) echo OK;; esac}
|
| 17417 | |
OK
|
| 17418 | |
$ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
|
| 17419 | |
$
|
| 17420 | |
@end example
|
| 17421 | |
|
| 17422 | |
Even with this, Solaris @command{ksh} matches a backslash if the set
|
| 17423 | |
contains any
|
| 17424 | |
of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
|
| 17425 | |
|
| 17426 | |
Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
|
| 17427 | |
a closing parenthesis if not specified in a character class:
|
| 17428 | |
|
| 17429 | |
@example
|
| 17430 | |
$ @kbd{case foo in *\)*) echo fail ;; esac}
|
| 17431 | |
fail
|
| 17432 | |
$ @kbd{case foo in *')'*) echo fail ;; esac}
|
| 17433 | |
fail
|
| 17434 | |
@end example
|
| 17435 | |
|
| 17436 | |
Some shells, such as Ash 0.3.8, are confused by an empty
|
| 17437 | |
@code{case}/@code{esac}:
|
| 17438 | |
|
| 17439 | |
@example
|
| 17440 | |
ash-0.3.8 $ @kbd{case foo in esac;}
|
| 17441 | |
@error{}Syntax error: ";" unexpected (expecting ")")
|
| 17442 | |
@end example
|
| 17443 | |
|
| 17444 | |
Posix requires @command{case} to give an exit status of 0 if no cases
|
| 17445 | |
match. However, @command{/bin/sh} in Solaris 10 does not obey this
|
| 17446 | |
rule. Meanwhile, it is unclear whether a case that matches, but
|
| 17447 | |
contains no statements, must also change the exit status to 0. The M4sh
|
| 17448 | |
macro @code{AS_CASE} works around these inconsistencies.
|
| 17449 | |
|
| 17450 | |
@example
|
| 17451 | |
$ @kbd{bash -c 'case `false` in ?) ;; esac; echo $?'}
|
| 17452 | |
0
|
| 17453 | |
$ @kbd{/bin/sh -c 'case `false` in ?) ;; esac; echo $?'}
|
| 17454 | |
255
|
| 17455 | |
@end example
|
| 17456 | |
|
| 17457 | |
|
| 17458 | |
@item @command{cd}
|
| 17459 | |
@c ---------------
|
| 17460 | |
@prindex @command{cd}
|
| 17461 | |
Posix 1003.1-2001 requires that @command{cd} must support
|
| 17462 | |
the @option{-L} (``logical'') and @option{-P} (``physical'') options,
|
| 17463 | |
with @option{-L} being the default. However, traditional shells do
|
| 17464 | |
not support these options, and their @command{cd} command has the
|
| 17465 | |
@option{-P} behavior.
|
| 17466 | |
|
| 17467 | |
Portable scripts should assume neither option is supported, and should
|
| 17468 | |
assume neither behavior is the default. This can be a bit tricky,
|
| 17469 | |
since the Posix default behavior means that, for example,
|
| 17470 | |
@samp{ls ..} and @samp{cd ..} may refer to different directories if
|
| 17471 | |
the current logical directory is a symbolic link. It is safe to use
|
| 17472 | |
@code{cd @var{dir}} if @var{dir} contains no @file{..} components.
|
| 17473 | |
Also, Autoconf-generated scripts check for this problem when computing
|
| 17474 | |
variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
|
| 17475 | |
so it is safe to @command{cd} to these variables.
|
| 17476 | |
|
| 17477 | |
Posix states that behavior is undefined if @command{cd} is given an
|
| 17478 | |
explicit empty argument. Some shells do nothing, some change to the
|
| 17479 | |
first entry in @env{CDPATH}, some change to @env{HOME}, and some exit
|
| 17480 | |
the shell rather than returning an error. Unfortunately, this means
|
| 17481 | |
that if @samp{$var} is empty, then @samp{cd "$var"} is less predictable
|
| 17482 | |
than @samp{cd $var} (at least the latter is well-behaved in all shells
|
| 17483 | |
at changing to @env{HOME}, although this is probably not what you wanted
|
| 17484 | |
in a script). You should check that a directory name was supplied
|
| 17485 | |
before trying to change locations.
|
| 17486 | |
|
| 17487 | |
@xref{Special Shell Variables}, for portability problems involving
|
| 17488 | |
@command{cd} and the @env{CDPATH} environment variable.
|
| 17489 | |
Also please see the discussion of the @command{pwd} command.
|
| 17490 | |
|
| 17491 | |
|
| 17492 | |
@anchor{echo}
|
| 17493 | |
@item @command{echo}
|
| 17494 | |
@c -----------------
|
| 17495 | |
@prindex @command{echo}
|
| 17496 | |
The simple @command{echo} is probably the most surprising source of
|
| 17497 | |
portability troubles. It is not possible to use @samp{echo} portably
|
| 17498 | |
unless both options and escape sequences are omitted. Don't expect any
|
| 17499 | |
option.
|
| 17500 | |
|
| 17501 | |
Do not use backslashes in the arguments, as there is no consensus on
|
| 17502 | |
their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
|
| 17503 | |
Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
|
| 17504 | |
The problem is truly @command{echo}: all the shells
|
| 17505 | |
understand @samp{'\n'} as the string composed of a backslash and an
|
| 17506 | |
@samp{n}. Within a command substitution, @samp{echo 'string\c'} will
|
| 17507 | |
mess up the internal state of ksh88 on AIX 6.1 so that it will print
|
| 17508 | |
the first character @samp{s} only, followed by a newline, and then
|
| 17509 | |
entirely drop the output of the next echo in a command substitution.
|
| 17510 | |
|
| 17511 | |
Because of these problems, do not pass a string containing arbitrary
|
| 17512 | |
characters to @command{echo}. For example, @samp{echo "$foo"} is safe
|
| 17513 | |
only if you know that @var{foo}'s value cannot contain backslashes and
|
| 17514 | |
cannot start with @samp{-}.
|
| 17515 | |
|
| 17516 | |
If this may not be true, @command{printf} is in general safer and
|
| 17517 | |
easier to use than @command{echo} and @command{echo -n}. Thus, scripts
|
| 17518 | |
where portability is not a major concern should use @command{printf
|
| 17519 | |
'%s\n'} whenever @command{echo} could fail, and similarly use
|
| 17520 | |
@command{printf %s} instead of @command{echo -n}. For portable shell
|
| 17521 | |
scripts, instead, it is suggested to use a here-document like this:
|
| 17522 | |
|
| 17523 | |
@example
|
| 17524 | |
cat <<EOF
|
| 17525 | |
$foo
|
| 17526 | |
EOF
|
| 17527 | |
@end example
|
| 17528 | |
|
| 17529 | |
Alternatively, M4sh provides @code{AS_ECHO} and @code{AS_ECHO_N} macros
|
| 17530 | |
which choose between various portable implementations: @samp{echo}
|
| 17531 | |
or @samp{print} where they work, @command{printf} if it is available,
|
| 17532 | |
or else other creative tricks in order to work around the above problems.
|
| 17533 | |
|
| 17534 | |
|
| 17535 | |
@item @command{eval}
|
| 17536 | |
@c -----------------
|
| 17537 | |
@prindex @command{eval}
|
| 17538 | |
The @command{eval} command is useful in limited circumstances, e.g.,
|
| 17539 | |
using commands like @samp{eval table_$key=\$value} and @samp{eval
|
| 17540 | |
value=table_$key} to simulate a hash table when the key is known to be
|
| 17541 | |
alphanumeric.
|
| 17542 | |
|
| 17543 | |
You should also be wary of common bugs in @command{eval} implementations.
|
| 17544 | |
In some shell implementations (e.g., older @command{ash}, OpenBSD 3.8
|
| 17545 | |
@command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
|
| 17546 | |
4.2.5), the arguments of @samp{eval} are evaluated in a context where
|
| 17547 | |
@samp{$?} is 0, so they exhibit behavior like this:
|
| 17548 | |
|
| 17549 | |
@example
|
| 17550 | |
$ @kbd{false; eval 'echo $?'}
|
| 17551 | |
0
|
| 17552 | |
@end example
|
| 17553 | |
|
| 17554 | |
The correct behavior here is to output a nonzero value,
|
| 17555 | |
but portable scripts should not rely on this.
|
| 17556 | |
|
| 17557 | |
You should not rely on @code{LINENO} within @command{eval}.
|
| 17558 | |
@xref{Special Shell Variables}.
|
| 17559 | |
|
| 17560 | |
Note that, even though these bugs are easily avoided,
|
| 17561 | |
@command{eval} is tricky to use on arbitrary arguments.
|
| 17562 | |
It is obviously unwise to use @samp{eval $cmd} if the string value of
|
| 17563 | |
@samp{cmd} was derived from an untrustworthy source. But even if the
|
| 17564 | |
string value is valid, @samp{eval $cmd} might not work as intended,
|
| 17565 | |
since it causes field splitting and file name expansion to occur twice,
|
| 17566 | |
once for the @command{eval} and once for the command itself. It is
|
| 17567 | |
therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
|
| 17568 | |
has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
|
| 17569 | |
equivalent of @samp{cat test;.c} if there happens to be a file named
|
| 17570 | |
@file{test;.c} in the current directory; and this in turn
|
| 17571 | |
mistakenly attempts to invoke @command{cat} on the file @file{test} and
|
| 17572 | |
then execute the command @command{.c}. To avoid this problem, use
|
| 17573 | |
@samp{eval "$cmd"} rather than @samp{eval $cmd}.
|
| 17574 | |
|
| 17575 | |
However, suppose that you want to output the text of the evaluated
|
| 17576 | |
command just before executing it. Assuming the previous example,
|
| 17577 | |
@samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
|
| 17578 | |
this output doesn't show the user that @samp{test;.c} is the actual name
|
| 17579 | |
of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
|
| 17580 | |
works on this example, but it fails with @samp{cmd='cat foo >bar'},
|
| 17581 | |
since it mistakenly replaces the contents of @file{bar} by the
|
| 17582 | |
string @samp{cat foo}. No simple, general, and portable solution to
|
| 17583 | |
this problem is known.
|
| 17584 | |
|
| 17585 | |
@item @command{exec}
|
| 17586 | |
@c -----------------
|
| 17587 | |
@prindex @command{exec}
|
| 17588 | |
Posix describes several categories of shell built-ins. Special
|
| 17589 | |
built-ins (such as @command{exit}) must impact the environment of the
|
| 17590 | |
current shell, and need not be available through @command{exec}. All
|
| 17591 | |
other built-ins are regular, and must not propagate variable assignments
|
| 17592 | |
to the environment of the current shell. However, the group of regular
|
| 17593 | |
built-ins is further distinguished by commands that do not require a
|
| 17594 | |
@env{PATH} search (such as @command{cd}), in contrast to built-ins that
|
| 17595 | |
are offered as a more efficient version of something that must still be
|
| 17596 | |
found in a @env{PATH} search (such as @command{echo}). Posix is not
|
| 17597 | |
clear on whether @command{exec} must work with the list of 17 utilities
|
| 17598 | |
that are invoked without a @env{PATH} search, and many platforms lack an
|
| 17599 | |
executable for some of those built-ins:
|
| 17600 | |
|
| 17601 | |
@example
|
| 17602 | |
$ @kbd{sh -c 'exec cd /tmp'}
|
| 17603 | |
sh: line 0: exec: cd: not found
|
| 17604 | |
@end example
|
| 17605 | |
|
| 17606 | |
All other built-ins that provide utilities specified by Posix must have
|
| 17607 | |
a counterpart executable that exists on @env{PATH}, although Posix
|
| 17608 | |
allows @command{exec} to use the built-in instead of the executable.
|
| 17609 | |
For example, contrast @command{bash} 3.2 and @command{pdksh} 5.2.14:
|
| 17610 | |
|
| 17611 | |
@example
|
| 17612 | |
$ @kbd{bash -c 'pwd --version' | head -n1}
|
| 17613 | |
bash: line 0: pwd: --: invalid option
|
| 17614 | |
pwd: usage: pwd [-LP]
|
| 17615 | |
$ @kbd{bash -c 'exec pwd --version' | head -n1}
|
| 17616 | |
pwd (GNU coreutils) 6.10
|
| 17617 | |
$ @kbd{pdksh -c 'exec pwd --version' | head -n1}
|
| 17618 | |
pdksh: pwd: --: unknown option
|
| 17619 | |
@end example
|
| 17620 | |
|
| 17621 | |
When it is desired to avoid a regular shell built-in, the workaround is
|
| 17622 | |
to use some other forwarding command, such as @command{env} or
|
| 17623 | |
@command{nice}, that will ensure a path search:
|
| 17624 | |
|
| 17625 | |
@example
|
| 17626 | |
$ @kbd{pdksh -c 'exec true --version' | head -n1}
|
| 17627 | |
$ @kbd{pdksh -c 'nice true --version' | head -n1}
|
| 17628 | |
true (GNU coreutils) 6.10
|
| 17629 | |
$ @kbd{pdksh -c 'env true --version' | head -n1}
|
| 17630 | |
true (GNU coreutils) 6.10
|
| 17631 | |
@end example
|
| 17632 | |
|
| 17633 | |
@item @command{exit}
|
| 17634 | |
@c -----------------
|
| 17635 | |
@prindex @command{exit}
|
| 17636 | |
The default value of @command{exit} is supposed to be @code{$?};
|
| 17637 | |
unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
|
| 17638 | |
perform @samp{exit 0}.
|
| 17639 | |
|
| 17640 | |
@example
|
| 17641 | |
bash-2.04$ @kbd{foo=`exit 1` || echo fail}
|
| 17642 | |
fail
|
| 17643 | |
bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
|
| 17644 | |
fail
|
| 17645 | |
bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
|
| 17646 | |
bash-2.04$
|
| 17647 | |
@end example
|
| 17648 | |
|
| 17649 | |
Using @samp{exit $?} restores the expected behavior.
|
| 17650 | |
|
| 17651 | |
Some shell scripts, such as those generated by @command{autoconf}, use a
|
| 17652 | |
trap to clean up before exiting. If the last shell command exited with
|
| 17653 | |
nonzero status, the trap also exits with nonzero status so that the
|
| 17654 | |
invoker can tell that an error occurred.
|
| 17655 | |
|
| 17656 | |
Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
|
| 17657 | |
trap ignores the @code{exit} command's argument. In these shells, a trap
|
| 17658 | |
cannot determine whether it was invoked by plain @code{exit} or by
|
| 17659 | |
@code{exit 1}. Instead of calling @code{exit} directly, use the
|
| 17660 | |
@code{AC_MSG_ERROR} macro that has a workaround for this problem.
|
| 17661 | |
|
| 17662 | |
|
| 17663 | |
@anchor{export}
|
| 17664 | |
@item @command{export}
|
| 17665 | |
@c -------------------
|
| 17666 | |
@prindex @command{export}
|
| 17667 | |
The builtin @command{export} dubs a shell variable @dfn{environment
|
| 17668 | |
variable}. Each update of exported variables corresponds to an update
|
| 17669 | |
of the environment variables. Conversely, each environment variable
|
| 17670 | |
received by the shell when it is launched should be imported as a shell
|
| 17671 | |
variable marked as exported.
|
| 17672 | |
|
| 17673 | |
Alas, many shells, such as Solaris @command{/bin/sh},
|
| 17674 | |
IRIX 6.3, IRIX 5.2,
|
| 17675 | |
AIX 4.1.5, and Digital Unix 4.0, forget to
|
| 17676 | |
@command{export} the environment variables they receive. As a result,
|
| 17677 | |
two variables coexist: the environment variable and the shell
|
| 17678 | |
variable. The following code demonstrates this failure:
|
| 17679 | |
|
| 17680 | |
@example
|
| 17681 | |
#!/bin/sh
|
| 17682 | |
echo $FOO
|
| 17683 | |
FOO=bar
|
| 17684 | |
echo $FOO
|
| 17685 | |
exec /bin/sh $0
|
| 17686 | |
@end example
|
| 17687 | |
|
| 17688 | |
@noindent
|
| 17689 | |
when run with @samp{FOO=foo} in the environment, these shells print
|
| 17690 | |
alternately @samp{foo} and @samp{bar}, although they should print only
|
| 17691 | |
@samp{foo} and then a sequence of @samp{bar}s.
|
| 17692 | |
|
| 17693 | |
Therefore you should @command{export} again each environment variable
|
| 17694 | |
that you update; the export can occur before or after the assignment.
|
| 17695 | |
|
| 17696 | |
Posix is not clear on whether the @command{export} of an undefined
|
| 17697 | |
variable causes the variable to be defined with the value of an empty
|
| 17698 | |
string, or merely marks any future definition of a variable by that name
|
| 17699 | |
for export. Various shells behave differently in this regard:
|
| 17700 | |
|
| 17701 | |
@example
|
| 17702 | |
$ @kbd{sh -c 'export foo; env | grep foo'}
|
| 17703 | |
$ @kbd{ash -c 'export foo; env | grep foo'}
|
| 17704 | |
foo=
|
| 17705 | |
@end example
|
| 17706 | |
|
| 17707 | |
Posix requires @command{export} to honor assignments made as arguments,
|
| 17708 | |
but older shells do not support this, including @command{/bin/sh} in
|
| 17709 | |
Solaris 10. Portable scripts should separate assignments and exports
|
| 17710 | |
into different statements.
|
| 17711 | |
|
| 17712 | |
@example
|
| 17713 | |
$ @kbd{bash -c 'export foo=bar; echo $foo'}
|
| 17714 | |
bar
|
| 17715 | |
$ @kbd{/bin/sh -c 'export foo=bar; echo $foo'}
|
| 17716 | |
/bin/sh: foo=bar: is not an identifier
|
| 17717 | |
$ @kbd{/bin/sh -c 'export foo; foo=bar; echo $foo'}
|
| 17718 | |
bar
|
| 17719 | |
@end example
|
| 17720 | |
|
| 17721 | |
@item @command{false}
|
| 17722 | |
@c ------------------
|
| 17723 | |
@prindex @command{false}
|
| 17724 | |
Don't expect @command{false} to exit with status 1: in native
|
| 17725 | |
Solaris @file{/bin/false} exits with status 255.
|
| 17726 | |
|
| 17727 | |
|
| 17728 | |
@item @command{for}
|
| 17729 | |
@c ----------------
|
| 17730 | |
@prindex @command{for}
|
| 17731 | |
To loop over positional arguments, use:
|
| 17732 | |
|
| 17733 | |
@example
|
| 17734 | |
for arg
|
| 17735 | |
do
|
| 17736 | |
echo "$arg"
|
| 17737 | |
done
|
| 17738 | |
@end example
|
| 17739 | |
|
| 17740 | |
@noindent
|
| 17741 | |
You may @emph{not} leave the @code{do} on the same line as @code{for},
|
| 17742 | |
since some shells improperly grok:
|
| 17743 | |
|
| 17744 | |
@example
|
| 17745 | |
for arg; do
|
| 17746 | |
echo "$arg"
|
| 17747 | |
done
|
| 17748 | |
@end example
|
| 17749 | |
|
| 17750 | |
If you want to explicitly refer to the positional arguments, given the
|
| 17751 | |
@samp{$@@} bug (@pxref{Shell Substitutions}), use:
|
| 17752 | |
|
| 17753 | |
@example
|
| 17754 | |
for arg in $@{1+"$@@"@}; do
|
| 17755 | |
echo "$arg"
|
| 17756 | |
done
|
| 17757 | |
@end example
|
| 17758 | |
|
| 17759 | |
@noindent
|
| 17760 | |
But keep in mind that Zsh, even in Bourne shell emulation mode, performs
|
| 17761 | |
word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
|
| 17762 | |
item @samp{$@@}, for more.
|
| 17763 | |
|
| 17764 | |
In Solaris @command{/bin/sh}, when the list of arguments of a
|
| 17765 | |
@command{for} loop starts with @emph{unquoted} tokens looking like
|
| 17766 | |
variable assignments, the loop is not executed on those tokens:
|
| 17767 | |
|
| 17768 | |
@example
|
| 17769 | |
$ @kbd{/bin/sh -c 'for v in a=b c=d x e=f; do echo $v; done'}
|
| 17770 | |
x
|
| 17771 | |
e=f
|
| 17772 | |
@end example
|
| 17773 | |
|
| 17774 | |
@noindent
|
| 17775 | |
Thankfully, quoting the assignment-like tokens, or starting the list
|
| 17776 | |
with other tokens (including unquoted variable expansion that results in
|
| 17777 | |
an assignment-like result), avoids the problem, so it is easy to work
|
| 17778 | |
around:
|
| 17779 | |
|
| 17780 | |
@example
|
| 17781 | |
$ @kbd{/bin/sh -c 'for v in "a=b"; do echo $v; done'}
|
| 17782 | |
a=b
|
| 17783 | |
$ @kbd{/bin/sh -c 'x=a=b; for v in $x c=d; do echo $v; done'}
|
| 17784 | |
a=b
|
| 17785 | |
c=d
|
| 17786 | |
@end example
|
| 17787 | |
|
| 17788 | |
@anchor{if}
|
| 17789 | |
@item @command{if}
|
| 17790 | |
@c ---------------
|
| 17791 | |
@prindex @command{if}
|
| 17792 | |
Using @samp{!} is not portable. Instead of:
|
| 17793 | |
|
| 17794 | |
@example
|
| 17795 | |
if ! cmp -s file file.new; then
|
| 17796 | |
mv file.new file
|
| 17797 | |
fi
|
| 17798 | |
@end example
|
| 17799 | |
|
| 17800 | |
@noindent
|
| 17801 | |
use:
|
| 17802 | |
|
| 17803 | |
@example
|
| 17804 | |
if cmp -s file file.new; then :; else
|
| 17805 | |
mv file.new file
|
| 17806 | |
fi
|
| 17807 | |
@end example
|
| 17808 | |
|
| 17809 | |
@noindent
|
| 17810 | |
Or, especially if the @dfn{else} branch is short, you can use @code{||}.
|
| 17811 | |
In M4sh, the @code{AS_IF} macro provides an easy way to write these kinds
|
| 17812 | |
of conditionals:
|
| 17813 | |
|
| 17814 | |
@example
|
| 17815 | |
AS_IF([cmp -s file file.new], [], [mv file.new file])
|
| 17816 | |
@end example
|
| 17817 | |
|
| 17818 | |
This is especially useful in other M4 macros, where the @dfn{then} and
|
| 17819 | |
@dfn{else} branches might be macro arguments.
|
| 17820 | |
|
| 17821 | |
Some very old shells did not reset the exit status from an @command{if}
|
| 17822 | |
with no @command{else}:
|
| 17823 | |
|
| 17824 | |
@example
|
| 17825 | |
$ @kbd{if (exit 42); then true; fi; echo $?}
|
| 17826 | |
42
|
| 17827 | |
@end example
|
| 17828 | |
|
| 17829 | |
@noindent
|
| 17830 | |
whereas a proper shell should have printed @samp{0}. But this is no
|
| 17831 | |
longer a portability problem; any shell that supports functions gets it
|
| 17832 | |
correct. However, it explains why some makefiles have lengthy
|
| 17833 | |
constructs:
|
| 17834 | |
|
| 17835 | |
@example
|
| 17836 | |
if test -f "$file"; then
|
| 17837 | |
install "$file" "$dest"
|
| 17838 | |
else
|
| 17839 | |
:
|
| 17840 | |
fi
|
| 17841 | |
@end example
|
| 17842 | |
|
| 17843 | |
|
| 17844 | |
@item @command{printf}
|
| 17845 | |
@c ------------------
|
| 17846 | |
@prindex @command{printf}
|
| 17847 | |
A format string starting with a @samp{-} can cause problems.
|
| 17848 | |
Bash interprets it as an option and
|
| 17849 | |
gives an error. And @samp{--} to mark the end of options is not good
|
| 17850 | |
in the NetBSD Almquist shell (e.g., 0.4.6) which takes that
|
| 17851 | |
literally as the format string. Putting the @samp{-} in a @samp{%c}
|
| 17852 | |
or @samp{%s} is probably easiest:
|
| 17853 | |
|
| 17854 | |
@example
|
| 17855 | |
printf %s -foo
|
| 17856 | |
@end example
|
| 17857 | |
|
| 17858 | |
Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
|
| 17859 | |
|
| 17860 | |
@example
|
| 17861 | |
$ @kbd{printf '\045'}
|
| 17862 | |
bash: printf: `%': missing format character
|
| 17863 | |
@end example
|
| 17864 | |
|
| 17865 | |
Large outputs may cause trouble. On Solaris 2.5.1 through 10, for
|
| 17866 | |
example, @file{/usr/bin/printf} is buggy, so when using
|
| 17867 | |
@command{/bin/sh} the command @samp{printf %010000x 123} normally dumps
|
| 17868 | |
core.
|
| 17869 | |
|
| 17870 | |
Since @command{printf} is not always a shell builtin, there is a
|
| 17871 | |
potential speed penalty for using @code{printf '%s\n'} as a replacement
|
| 17872 | |
for an @command{echo} that does not interpret @samp{\} or leading
|
| 17873 | |
@samp{-}. With Solaris @command{ksh}, it is possible to use @code{print
|
| 17874 | |
-r --} for this role instead.
|
| 17875 | |
|
| 17876 | |
@xref{echo, , Limitations of Shell Builtins} for a discussion of
|
| 17877 | |
portable alternatives to both @command{printf} and @command{echo}.
|
| 17878 | |
|
| 17879 | |
|
| 17880 | |
@item @command{pwd}
|
| 17881 | |
@c ----------------
|
| 17882 | |
@prindex @command{pwd}
|
| 17883 | |
With modern shells, plain @command{pwd} outputs a ``logical''
|
| 17884 | |
directory name, some of whose components may be symbolic links. These
|
| 17885 | |
directory names are in contrast to ``physical'' directory names, whose
|
| 17886 | |
components are all directories.
|
| 17887 | |
|
| 17888 | |
Posix 1003.1-2001 requires that @command{pwd} must support
|
| 17889 | |
the @option{-L} (``logical'') and @option{-P} (``physical'') options,
|
| 17890 | |
with @option{-L} being the default. However, traditional shells do
|
| 17891 | |
not support these options, and their @command{pwd} command has the
|
| 17892 | |
@option{-P} behavior.
|
| 17893 | |
|
| 17894 | |
Portable scripts should assume neither option is supported, and should
|
| 17895 | |
assume neither behavior is the default. Also, on many hosts
|
| 17896 | |
@samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
|
| 17897 | |
does not require this behavior and portable scripts should not rely on
|
| 17898 | |
it.
|
| 17899 | |
|
| 17900 | |
Typically it's best to use plain @command{pwd}. On modern hosts this
|
| 17901 | |
outputs logical directory names, which have the following advantages:
|
| 17902 | |
|
| 17903 | |
@itemize @bullet
|
| 17904 | |
@item
|
| 17905 | |
Logical names are what the user specified.
|
| 17906 | |
@item
|
| 17907 | |
Physical names may not be portable from one installation
|
| 17908 | |
host to another due to network file system gymnastics.
|
| 17909 | |
@item
|
| 17910 | |
On modern hosts @samp{pwd -P} may fail due to lack of permissions to
|
| 17911 | |
some parent directory, but plain @command{pwd} cannot fail for this
|
| 17912 | |
reason.
|
| 17913 | |
@end itemize
|
| 17914 | |
|
| 17915 | |
Also please see the discussion of the @command{cd} command.
|
| 17916 | |
|
| 17917 | |
|
| 17918 | |
@item @command{read}
|
| 17919 | |
@c -----------------
|
| 17920 | |
@prindex @command{read}
|
| 17921 | |
No options are portable, not even support @option{-r} (Solaris
|
| 17922 | |
@command{/bin/sh} for example). Tru64/OSF 5.1 @command{sh} treats
|
| 17923 | |
@command{read} as a special built-in, so it may exit if input is
|
| 17924 | |
redirected from a non-existent or unreadable file.
|
| 17925 | |
|
| 17926 | |
|
| 17927 | |
@anchor{set}
|
| 17928 | |
@item @command{set}
|
| 17929 | |
@c ----------------
|
| 17930 | |
@prindex @command{set}
|
| 17931 | |
With the FreeBSD 6.0 shell, the @command{set} command (without
|
| 17932 | |
any options) does not sort its output.
|
| 17933 | |
|
| 17934 | |
The @command{set} builtin faces the usual problem with arguments
|
| 17935 | |
starting with a
|
| 17936 | |
dash. Modern shells such as Bash or Zsh understand @option{--} to specify
|
| 17937 | |
the end of the options (any argument after @option{--} is a parameter,
|
| 17938 | |
even @samp{-x} for instance), but many traditional shells (e.g., Solaris
|
| 17939 | |
10 @command{/bin/sh}) simply stop option
|
| 17940 | |
processing as soon as a non-option argument is found. Therefore, use
|
| 17941 | |
@samp{dummy} or simply @samp{x} to end the option processing, and use
|
| 17942 | |
@command{shift} to pop it out:
|
| 17943 | |
|
| 17944 | |
@example
|
| 17945 | |
set x $my_list; shift
|
| 17946 | |
@end example
|
| 17947 | |
|
| 17948 | |
Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
|
| 17949 | |
longer requires support for this command, and in traditional shells
|
| 17950 | |
@samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
|
| 17951 | |
makes scripts harder to debug.
|
| 17952 | |
|
| 17953 | |
Some nonstandard shells do not recognize more than one option
|
| 17954 | |
(e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
|
| 17955 | |
better to combine them:
|
| 17956 | |
|
| 17957 | |
@example
|
| 17958 | |
set -ex
|
| 17959 | |
@end example
|
| 17960 | |
|
| 17961 | |
@cindex @command{set -e}
|
| 17962 | |
The option @option{-e} has historically been underspecified, with enough
|
| 17963 | |
ambiguities to cause numerous differences across various shell
|
| 17964 | |
implementations; see for example
|
| 17965 | |
@uref{http://www.in-ulm.de/@/~mascheck/@/various/@/set-e/, this overview},
|
| 17966 | |
or @uref{http://www.austingroupbugs.net/@/view.php?id=52, this link},
|
| 17967 | |
documenting a change to Posix 2008 to match @command{ksh88} behavior.
|
| 17968 | |
Note that mixing @code{set -e} and shell functions is asking for surprises:
|
| 17969 | |
|
| 17970 | |
@example
|
| 17971 | |
set -e
|
| 17972 | |
doit()
|
| 17973 | |
@{
|
| 17974 | |
rm file
|
| 17975 | |
echo one
|
| 17976 | |
@}
|
| 17977 | |
doit || echo two
|
| 17978 | |
@end example
|
| 17979 | |
|
| 17980 | |
@noindent
|
| 17981 | |
According to the recommendation, @samp{one} should always be output
|
| 17982 | |
regardless of whether the @command{rm} failed, because it occurs within
|
| 17983 | |
the body of the shell function @samp{doit} invoked on the left side of
|
| 17984 | |
@samp{||}, where the effects of @samp{set -e} are not enforced.
|
| 17985 | |
Likewise, @samp{two} should never be printed, since the failure of
|
| 17986 | |
@command{rm} does not abort the function, such that the status of
|
| 17987 | |
@samp{doit} is 0.
|
| 17988 | |
|
| 17989 | |
The BSD shell has had several problems with the @option{-e}
|
| 17990 | |
option. Older versions of the BSD
|
| 17991 | |
shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
|
| 17992 | |
@samp{case} when @option{-e} was in effect, causing the shell to exit
|
| 17993 | |
unexpectedly in some cases. This was particularly a problem with
|
| 17994 | |
makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
|
| 17995 | |
touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
|
| 17996 | |
wrapper works around the bug (@pxref{Failure in Make Rules}).
|
| 17997 | |
|
| 17998 | |
Even relatively-recent versions of the BSD shell (e.g., OpenBSD 3.4)
|
| 17999 | |
wrongly exit with @option{-e} if the last command within a compound
|
| 18000 | |
statement fails and is guarded by an @samp{&&} only. For example:
|
| 18001 | |
|
| 18002 | |
@example
|
| 18003 | |
#! /bin/sh
|
| 18004 | |
set -e
|
| 18005 | |
foo=''
|
| 18006 | |
test -n "$foo" && exit 1
|
| 18007 | |
echo one
|
| 18008 | |
if :; then
|
| 18009 | |
test -n "$foo" && exit 1
|
| 18010 | |
echo two
|
| 18011 | |
test -n "$foo" && exit 1
|
| 18012 | |
fi
|
| 18013 | |
echo three
|
| 18014 | |
@end example
|
| 18015 | |
|
| 18016 | |
@noindent
|
| 18017 | |
does not print @samp{three}. One workaround is to change the last
|
| 18018 | |
instance of @samp{test -n "$foo" && exit 1} to be @samp{if test -n
|
| 18019 | |
"$foo"; then exit 1; fi} instead. Another possibility is to warn BSD
|
| 18020 | |
users not to use @samp{sh -e}.
|
| 18021 | |
|
| 18022 | |
When @samp{set -e} is in effect, a failed command substitution in
|
| 18023 | |
Solaris @command{/bin/sh} cannot be ignored, even with @samp{||}.
|
| 18024 | |
|
| 18025 | |
@example
|
| 18026 | |
$ @kbd{/bin/sh -c 'set -e; foo=`false` || echo foo; echo bar'}
|
| 18027 | |
$ @kbd{bash -c 'set -e; foo=`false` || echo foo; echo bar'}
|
| 18028 | |
foo
|
| 18029 | |
bar
|
| 18030 | |
@end example
|
| 18031 | |
|
| 18032 | |
@noindent
|
| 18033 | |
Moreover, a command substitution, successful or not, causes this shell to
|
| 18034 | |
exit from a failing outer command even in presence of an @samp{&&} list:
|
| 18035 | |
|
| 18036 | |
@example
|
| 18037 | |
$ @kbd{bash -c 'set -e; false `true` && echo notreached; echo ok'}
|
| 18038 | |
ok
|
| 18039 | |
$ @kbd{sh -c 'set -e; false `true` && echo notreached; echo ok'}
|
| 18040 | |
$
|
| 18041 | |
@end example
|
| 18042 | |
|
| 18043 | |
Portable scripts should not use @samp{set -e} if @command{trap} is used
|
| 18044 | |
to install an exit handler. This is because Tru64/OSF 5.1 @command{sh}
|
| 18045 | |
sometimes enters the trap handler with the exit status of the command
|
| 18046 | |
prior to the one that triggered the errexit handler:
|
| 18047 | |
|
| 18048 | |
@example
|
| 18049 | |
$ @kbd{sh -ec 'trap '\''echo $?'\'' 0; false'}
|
| 18050 | |
0
|
| 18051 | |
$ @kbd{sh -c 'set -e; trap '\''echo $?'\'' 0; false'}
|
| 18052 | |
1
|
| 18053 | |
@end example
|
| 18054 | |
|
| 18055 | |
@noindent
|
| 18056 | |
Thus, when writing a script in M4sh, rather than trying to rely on
|
| 18057 | |
@samp{set -e}, it is better to append @samp{|| AS_EXIT} to any
|
| 18058 | |
statement where it is desirable to abort on failure.
|
| 18059 | |
|
| 18060 | |
@cindex @command{set -b}
|
| 18061 | |
@cindex @command{set -m}
|
| 18062 | |
Job control is not provided by all shells, so the use of @samp{set -m}
|
| 18063 | |
or @samp{set -b} must be done with care. When using @command{zsh} in
|
| 18064 | |
native mode, asynchronous notification (@samp{set -b}) is enabled by
|
| 18065 | |
default, and using @samp{emulate sh} to switch to Posix mode does not
|
| 18066 | |
clear this setting (although asynchronous notification has no impact
|
| 18067 | |
unless job monitoring is also enabled). Also, @command{zsh} 4.3.10 and
|
| 18068 | |
earlier have a bug where job control can be manipulated in interactive
|
| 18069 | |
shells, but not in subshells or scripts. Furthermore, some shells, like
|
| 18070 | |
@command{pdksh}, fail to treat subshells as interactive, even though the
|
| 18071 | |
parent shell was.
|
| 18072 | |
|
| 18073 | |
@example
|
| 18074 | |
$ @kbd{echo $ZSH_VERSION}
|
| 18075 | |
4.3.10
|
| 18076 | |
$ @kbd{set -m; echo $?}
|
| 18077 | |
0
|
| 18078 | |
$ @kbd{zsh -c 'set -m; echo $?'}
|
| 18079 | |
set: can't change option: -m
|
| 18080 | |
$ @kbd{(set -m); echo $?}
|
| 18081 | |
set: can't change option: -m
|
| 18082 | |
1
|
| 18083 | |
$ @kbd{pdksh -ci 'echo $-; (echo $-)'}
|
| 18084 | |
cim
|
| 18085 | |
c
|
| 18086 | |
@end example
|
| 18087 | |
|
| 18088 | |
@cindex @command{set -n}
|
| 18089 | |
Use of @command{set -n} (typically via @command{sh -n script}) to
|
| 18090 | |
validate a script is not foolproof. Modern @command{ksh93} tries to be
|
| 18091 | |
helpful by informing you about better syntax, but switching the script
|
| 18092 | |
to use the suggested syntax in order to silence the warnings would
|
| 18093 | |
render the script no longer portable to older shells:
|
| 18094 | |
|
| 18095 | |
@example
|
| 18096 | |
$ @kbd{ksh -nc '``'}
|
| 18097 | |
ksh: warning: line 1: `...` obsolete, use $(...)
|
| 18098 | |
0
|
| 18099 | |
@end example
|
| 18100 | |
|
| 18101 | |
Furthermore, on ancient hosts, such as SunOS 4, @command{sh -n} could go
|
| 18102 | |
into an infinite loop; even with that bug fixed, Solaris 8
|
| 18103 | |
@command{/bin/sh} takes extremely long to parse large scripts. Autoconf
|
| 18104 | |
itself uses @command{sh -n} within its testsuite to check that correct
|
| 18105 | |
scripts were generated, but only after first probing for other shell
|
| 18106 | |
features (such as @code{test -n "$@{BASH_VERSION+set@}"}) that indicate
|
| 18107 | |
a reasonably fast and working implementation.
|
| 18108 | |
|
| 18109 | |
@item @command{shift}
|
| 18110 | |
@c ------------------
|
| 18111 | |
@prindex @command{shift}
|
| 18112 | |
Not only is @command{shift}ing a bad idea when there is nothing left to
|
| 18113 | |
shift, but in addition it is not portable: the shell of MIPS
|
| 18114 | |
RISC/OS 4.52 refuses to do it.
|
| 18115 | |
|
| 18116 | |
Don't use @samp{shift 2} etc.; while it in the SVR1 shell (1983),
|
| 18117 | |
it is also absent in many pre-Posix shells.
|
| 18118 | |
|
| 18119 | |
|
| 18120 | |
@item @command{source}
|
| 18121 | |
@c -------------------
|
| 18122 | |
@prindex @command{source}
|
| 18123 | |
This command is not portable, as Posix does not require it; use
|
| 18124 | |
@command{.} instead.
|
| 18125 | |
|
| 18126 | |
|
| 18127 | |
@item @command{test}
|
| 18128 | |
@c -----------------
|
| 18129 | |
@prindex @command{test}
|
| 18130 | |
The @code{test} program is the way to perform many file and string
|
| 18131 | |
tests. It is often invoked by the alternate name @samp{[}, but using
|
| 18132 | |
that name in Autoconf code is asking for trouble since it is an M4 quote
|
| 18133 | |
character.
|
| 18134 | |
|
| 18135 | |
The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not
|
| 18136 | |
present in all implementations, and have been marked obsolete by Posix
|
| 18137 | |
2008. This is because there are inherent ambiguities in using them.
|
| 18138 | |
For example, @samp{test "$1" -a "$2"} looks like a binary operator to
|
| 18139 | |
check whether two strings are both non-empty, but if @samp{$1} is the
|
| 18140 | |
literal @samp{!}, then some implementations of @command{test} treat it
|
| 18141 | |
as a negation of the unary operator @option{-a}.
|
| 18142 | |
|
| 18143 | |
Thus, portable uses of @command{test} should never have more than four
|
| 18144 | |
arguments, and scripts should use shell constructs like @samp{&&} and
|
| 18145 | |
@samp{||} instead. If you combine @samp{&&} and @samp{||} in the same
|
| 18146 | |
statement, keep in mind that they have equal precedence, so it is often
|
| 18147 | |
better to parenthesize even when this is redundant. For example:
|
| 18148 | |
|
| 18149 | |
@smallexample
|
| 18150 | |
# Not portable:
|
| 18151 | |
test "X$a" = "X$b" -a \
|
| 18152 | |
'(' "X$c" != "X$d" -o "X$e" = "X$f" ')'
|
| 18153 | |
|
| 18154 | |
# Portable:
|
| 18155 | |
test "X$a" = "X$b" &&
|
| 18156 | |
@{ test "X$c" != "X$d" || test "X$e" = "X$f"; @}
|
| 18157 | |
@end smallexample
|
| 18158 | |
|
| 18159 | |
@command{test} does not process options like most other commands do; for
|
| 18160 | |
example, it does not recognize the @option{--} argument as marking the
|
| 18161 | |
end of options.
|
| 18162 | |
|
| 18163 | |
It is safe to use @samp{!} as a @command{test} operator. For example,
|
| 18164 | |
@samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
|
| 18165 | |
-d foo; @dots{}} is not.
|
| 18166 | |
|
| 18167 | |
|
| 18168 | |
@item @command{test} (files)
|
| 18169 | |
@c -------------------------
|
| 18170 | |
To enable @command{configure} scripts to support cross-compilation, they
|
| 18171 | |
shouldn't do anything that tests features of the build system instead of
|
| 18172 | |
the host system. But occasionally you may find it necessary to check
|
| 18173 | |
whether some arbitrary file exists. To do so, use @samp{test -f},
|
| 18174 | |
@samp{test -r}, or @samp{test -x}. Do not use @samp{test -e}, because
|
| 18175 | |
Solaris 10 @command{/bin/sh}
|
| 18176 | |
lacks it. To test for symbolic links on systems that have them, use
|
| 18177 | |
@samp{test -h} rather than @samp{test -L}; either form conforms to
|
| 18178 | |
Posix 1003.1-2001, but older shells like Solaris 8
|
| 18179 | |
@code{/bin/sh} support only @option{-h}.
|
| 18180 | |
|
| 18181 | |
For historical reasons, Posix reluctantly allows implementations of
|
| 18182 | |
@samp{test -x} that will succeed for the root user, even if no execute
|
| 18183 | |
permissions are present. Furthermore, shells do not all agree on
|
| 18184 | |
whether Access Control Lists should affect @samp{test -r}, @samp{test
|
| 18185 | |
-w}, and @samp{test -x}; some shells base test results strictly on the
|
| 18186 | |
current user id compared to file owner and mode, as if by
|
| 18187 | |
@code{stat(2)}; while other shells base test results on whether the
|
| 18188 | |
current user has the given right, even if that right is only granted by
|
| 18189 | |
an ACL, as if by @code{faccessat(2)}. Furthermore, there is a classic
|
| 18190 | |
time of check to time of use race between any use of @command{test}
|
| 18191 | |
followed by operating on the just-checked file. Therefore, it is a good
|
| 18192 | |
idea to write scripts that actually attempt an operation, and are
|
| 18193 | |
prepared for the resulting failure if permission is denied, rather than
|
| 18194 | |
trying to avoid an operation based solely on whether @command{test}
|
| 18195 | |
guessed that it might not be permitted.
|
| 18196 | |
|
| 18197 | |
@item @command{test} (strings)
|
| 18198 | |
@c ---------------------------
|
| 18199 | |
Posix says that @samp{test "@var{string}"} succeeds if @var{string} is
|
| 18200 | |
not null, but this usage is not portable to traditional platforms like
|
| 18201 | |
Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and
|
| 18202 | |
@samp{-n}.
|
| 18203 | |
|
| 18204 | |
Posix also says that @samp{test ! "@var{string}"},
|
| 18205 | |
@samp{test -n "@var{string}"} and
|
| 18206 | |
@samp{test -z "@var{string}"} work with any string, but many
|
| 18207 | |
shells (such as Solaris, AIX 3.2, UNICOS 10.0.0.6,
|
| 18208 | |
Digital Unix 4, etc.)@: get confused if
|
| 18209 | |
@var{string} looks like an operator:
|
| 18210 | |
|
| 18211 | |
@example
|
| 18212 | |
$ @kbd{test -n =}
|
| 18213 | |
test: argument expected
|
| 18214 | |
$ @kbd{test ! -n}
|
| 18215 | |
test: argument expected
|
| 18216 | |
$ @kbd{test -z ")"; echo $?}
|
| 18217 | |
0
|
| 18218 | |
@end example
|
| 18219 | |
|
| 18220 | |
Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}}
|
| 18221 | |
and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of
|
| 18222 | |
strings, but in practice this is not true for troublesome strings that
|
| 18223 | |
look like operators or parentheses, or that begin with @samp{-}.
|
| 18224 | |
|
| 18225 | |
It is best to protect such strings with a leading @samp{X}, e.g.,
|
| 18226 | |
@samp{test "X@var{string}" != X} rather than @samp{test -n
|
| 18227 | |
"@var{string}"} or @samp{test ! "@var{string}"}.
|
| 18228 | |
|
| 18229 | |
It is common to find variations of the following idiom:
|
| 18230 | |
|
| 18231 | |
@example
|
| 18232 | |
test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
|
| 18233 | |
@var{action}
|
| 18234 | |
@end example
|
| 18235 | |
|
| 18236 | |
@noindent
|
| 18237 | |
to take an action when a token matches a given pattern. Such constructs
|
| 18238 | |
should be avoided by using:
|
| 18239 | |
|
| 18240 | |
@example
|
| 18241 | |
case $ac_feature in
|
| 18242 | |
*[!-a-zA-Z0-9_]*) @var{action};;
|
| 18243 | |
esac
|
| 18244 | |
@end example
|
| 18245 | |
|
| 18246 | |
If the pattern is a complicated regular expression that cannot be
|
| 18247 | |
expressed as a shell pattern, use something like this instead:
|
| 18248 | |
|
| 18249 | |
@example
|
| 18250 | |
expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
|
| 18251 | |
@var{action}
|
| 18252 | |
@end example
|
| 18253 | |
|
| 18254 | |
@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
|
| 18255 | |
"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
|
| 18256 | |
@samp{@var{foo}} contains backslashes.
|
| 18257 | |
|
| 18258 | |
|
| 18259 | |
@anchor{trap}
|
| 18260 | |
@item @command{trap}
|
| 18261 | |
@c -----------------
|
| 18262 | |
@prindex @command{trap}
|
| 18263 | |
It is safe to trap at least the signals 1, 2, 13, and 15. You can also
|
| 18264 | |
trap 0, i.e., have the @command{trap} run when the script ends (either via an
|
| 18265 | |
explicit @command{exit}, or the end of the script). The trap for 0 should be
|
| 18266 | |
installed outside of a shell function, or AIX 5.3 @command{/bin/sh}
|
| 18267 | |
will invoke the trap at the end of this function.
|
| 18268 | |
|
| 18269 | |
Posix says that @samp{trap - 1 2 13 15} resets the traps for the
|
| 18270 | |
specified signals to their default values, but many common shells (e.g.,
|
| 18271 | |
Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
|
| 18272 | |
``command'' named @command{-} when the specified conditions arise.
|
| 18273 | |
Posix 2008 also added a requirement to support @samp{trap 1 2 13 15} to
|
| 18274 | |
reset traps, as this is supported by a larger set of shells, but there
|
| 18275 | |
are still shells like @command{dash} that mistakenly try to execute
|
| 18276 | |
@command{1} instead of resetting the traps. Therefore, there is no
|
| 18277 | |
portable workaround, except for @samp{trap - 0}, for which
|
| 18278 | |
@samp{trap '' 0} is a portable substitute.
|
| 18279 | |
|
| 18280 | |
Although Posix is not absolutely clear on this point, it is widely
|
| 18281 | |
admitted that when entering the trap @samp{$?} should be set to the exit
|
| 18282 | |
status of the last command run before the trap. The ambiguity can be
|
| 18283 | |
summarized as: ``when the trap is launched by an @command{exit}, what is
|
| 18284 | |
the @emph{last} command run: that before @command{exit}, or
|
| 18285 | |
@command{exit} itself?''
|
| 18286 | |
|
| 18287 | |
Bash considers @command{exit} to be the last command, while Zsh and
|
| 18288 | |
Solaris @command{/bin/sh} consider that when the trap is run it is
|
| 18289 | |
@emph{still} in the @command{exit}, hence it is the previous exit status
|
| 18290 | |
that the trap receives:
|
| 18291 | |
|
| 18292 | |
@example
|
| 18293 | |
$ @kbd{cat trap.sh}
|
| 18294 | |
trap 'echo $?' 0
|
| 18295 | |
(exit 42); exit 0
|
| 18296 | |
$ @kbd{zsh trap.sh}
|
| 18297 | |
42
|
| 18298 | |
$ @kbd{bash trap.sh}
|
| 18299 | |
0
|
| 18300 | |
@end example
|
| 18301 | |
|
| 18302 | |
The portable solution is then simple: when you want to @samp{exit 42},
|
| 18303 | |
run @samp{(exit 42); exit 42}, the first @command{exit} being used to
|
| 18304 | |
set the exit status to 42 for Zsh, and the second to trigger the trap
|
| 18305 | |
and pass 42 as exit status for Bash. In M4sh, this is covered by using
|
| 18306 | |
@code{AS_EXIT}.
|
| 18307 | |
|
| 18308 | |
The shell in FreeBSD 4.0 has the following bug: @samp{$?} is
|
| 18309 | |
reset to 0 by empty lines if the code is inside @command{trap}.
|
| 18310 | |
|
| 18311 | |
@example
|
| 18312 | |
$ @kbd{trap 'false}
|
| 18313 | |
|
| 18314 | |
echo $?' 0
|
| 18315 | |
$ @kbd{exit}
|
| 18316 | |
0
|
| 18317 | |
@end example
|
| 18318 | |
|
| 18319 | |
@noindent
|
| 18320 | |
Fortunately, this bug only affects @command{trap}.
|
| 18321 | |
|
| 18322 | |
Several shells fail to execute an exit trap that is defined inside a
|
| 18323 | |
subshell, when the last command of that subshell is not a builtin. A
|
| 18324 | |
workaround is to use @samp{exit $?} as the shell builtin.
|
| 18325 | |
|
| 18326 | |
@example
|
| 18327 | |
$ @kbd{bash -c '(trap "echo hi" 0; /bin/true)'}
|
| 18328 | |
hi
|
| 18329 | |
$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true)'}
|
| 18330 | |
$ @kbd{/bin/sh -c '(trap "echo hi" 0; /bin/true; exit $?)'}
|
| 18331 | |
hi
|
| 18332 | |
@end example
|
| 18333 | |
|
| 18334 | |
@noindent
|
| 18335 | |
Likewise, older implementations of @command{bash} failed to preserve
|
| 18336 | |
@samp{$?} across an exit trap consisting of a single cleanup command.
|
| 18337 | |
|
| 18338 | |
@example
|
| 18339 | |
$ @kbd{bash -c 'trap "/bin/true" 0; exit 2'; echo $?}
|
| 18340 | |
2
|
| 18341 | |
$ @kbd{bash-2.05b -c 'trap "/bin/true" 0; exit 2'; echo $?}
|
| 18342 | |
0
|
| 18343 | |
$ @kbd{bash-2.05b -c 'trap ":; /bin/true" 0; exit 2'; echo $?}
|
| 18344 | |
2
|
| 18345 | |
@end example
|
| 18346 | |
|
| 18347 | |
@item @command{true}
|
| 18348 | |
@c -----------------
|
| 18349 | |
@prindex @command{true}
|
| 18350 | |
@c Info cannot handle `:' in index entries.
|
| 18351 | |
@c @prindex @command{:}
|
| 18352 | |
Don't worry: as far as we know @command{true} is portable.
|
| 18353 | |
Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
|
| 18354 | |
portable shell community tends to prefer using @command{:}. This has a
|
| 18355 | |
funny side effect: when asked whether @command{false} is more portable
|
| 18356 | |
than @command{true} Alexandre Oliva answered:
|
| 18357 | |
|
| 18358 | |
@quotation
|
| 18359 | |
In a sense, yes, because if it doesn't exist, the shell will produce an
|
| 18360 | |
exit status of failure, which is correct for @command{false}, but not
|
| 18361 | |
for @command{true}.
|
| 18362 | |
@end quotation
|
| 18363 | |
|
| 18364 | |
Remember that even though @samp{:} ignores its arguments, it still takes
|
| 18365 | |
time to compute those arguments. It is a good idea to use double quotes
|
| 18366 | |
around any arguments to @samp{:} to avoid time spent in field splitting
|
| 18367 | |
and file name expansion.
|
| 18368 | |
|
| 18369 | |
|
| 18370 | |
@anchor{unset}
|
| 18371 | |
@item @command{unset}
|
| 18372 | |
@c ------------------
|
| 18373 | |
@prindex @command{unset}
|
| 18374 | |
In some nonconforming shells (e.g., Solaris 10 @command{/bin/ksh} and
|
| 18375 | |
@command{/usr/xpg4/bin/sh}, NetBSD 5.99.43 sh, or Bash 2.05a),
|
| 18376 | |
@code{unset FOO} fails when @code{FOO} is not set. This can interfere
|
| 18377 | |
with @code{set -e} operation. You can use
|
| 18378 | |
|
| 18379 | |
@smallexample
|
| 18380 | |
FOO=; unset FOO
|
| 18381 | |
@end smallexample
|
| 18382 | |
|
| 18383 | |
@noindent
|
| 18384 | |
if you are not sure that @code{FOO} is set.
|
| 18385 | |
|
| 18386 | |
A few ancient shells lack @command{unset} entirely. For some variables
|
| 18387 | |
such as @code{PS1}, you can use a neutralizing value instead:
|
| 18388 | |
|
| 18389 | |
@smallexample
|
| 18390 | |
PS1='$ '
|
| 18391 | |
@end smallexample
|
| 18392 | |
|
| 18393 | |
Usually, shells that do not support @command{unset} need less effort to
|
| 18394 | |
make the environment sane, so for example is not a problem if you cannot
|
| 18395 | |
unset @command{CDPATH} on those shells. However, Bash 2.01 mishandles
|
| 18396 | |
@code{unset MAIL} and @code{unset MAILPATH} in some cases and dumps core.
|
| 18397 | |
So, you should do something like
|
| 18398 | |
|
| 18399 | |
@smallexample
|
| 18400 | |
( (unset MAIL) || exit 1) >/dev/null 2>&1 && unset MAIL || :
|
| 18401 | |
@end smallexample
|
| 18402 | |
|
| 18403 | |
@noindent
|
| 18404 | |
@xref{Special Shell Variables}, for some neutralizing values. Also, see
|
| 18405 | |
@ref{export, , Limitations of Builtins}, for
|
| 18406 | |
the case of environment variables.
|
| 18407 | |
|
| 18408 | |
@item @command{wait}
|
| 18409 | |
@c -----------------
|
| 18410 | |
@prindex @command{wait}
|
| 18411 | |
The exit status of @command{wait} is not always reliable.
|
| 18412 | |
@end table
|
| 18413 | |
|
| 18414 | |
@node Limitations of Usual Tools
|
| 18415 | |
@section Limitations of Usual Tools
|
| 18416 | |
@cindex Limitations of usual tools
|
| 18417 | |
|
| 18418 | |
The small set of tools you can expect to find on any machine can still
|
| 18419 | |
include some limitations you should be aware of.
|
| 18420 | |
|
| 18421 | |
@comment Between this list and the list of builtins above, we should
|
| 18422 | |
@comment mention all the tools in GNU Coding Standards ``Utilities in
|
| 18423 | |
@comment Makefiles''.
|
| 18424 | |
|
| 18425 | |
@c This table includes things like `@command{expr} (|)', so we can't
|
| 18426 | |
@c use @table @command.
|
| 18427 | |
@table @asis
|
| 18428 | |
@anchor{awk}
|
| 18429 | |
@item @command{awk}
|
| 18430 | |
@c ----------------
|
| 18431 | |
@prindex @command{awk}
|
| 18432 | |
Don't leave white space before the opening parenthesis in a user function call.
|
| 18433 | |
Posix does not allow this and GNU Awk rejects it:
|
| 18434 | |
|
| 18435 | |
@example
|
| 18436 | |
$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
|
| 18437 | |
BEGIN @{ die () @}'}
|
| 18438 | |
gawk: cmd. line:2: BEGIN @{ die () @}
|
| 18439 | |
gawk: cmd. line:2: ^ parse error
|
| 18440 | |
$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
|
| 18441 | |
BEGIN @{ die() @}'}
|
| 18442 | |
Aaaaarg!
|
| 18443 | |
@end example
|
| 18444 | |
|
| 18445 | |
Posix says that if a program contains only @samp{BEGIN} actions, and
|
| 18446 | |
contains no instances of @code{getline}, then the program merely
|
| 18447 | |
executes the actions without reading input. However, traditional Awk
|
| 18448 | |
implementations (such as Solaris 10 @command{awk}) read and discard
|
| 18449 | |
input in this case. Portable scripts can redirect input from
|
| 18450 | |
@file{/dev/null} to work around the problem. For example:
|
| 18451 | |
|
| 18452 | |
@example
|
| 18453 | |
awk 'BEGIN @{print "hello world"@}' </dev/null
|
| 18454 | |
@end example
|
| 18455 | |
|
| 18456 | |
Posix says that in an @samp{END} action, @samp{$NF} (and presumably,
|
| 18457 | |
@samp{$1}) retain their value from the last record read, if no
|
| 18458 | |
intervening @samp{getline} occurred. However, some implementations
|
| 18459 | |
(such as Solaris 10 @samp{/usr/bin/awk}, @samp{nawk}, or Darwin
|
| 18460 | |
@samp{awk}) reset these variables. A workaround is to use an
|
| 18461 | |
intermediate variable prior to the @samp{END} block. For example:
|
| 18462 | |
|
| 18463 | |
@example
|
| 18464 | |
$ @kbd{cat end.awk}
|
| 18465 | |
@{ tmp = $1 @}
|
| 18466 | |
END @{ print "a", $1, $NF, "b", tmp @}
|
| 18467 | |
$ @kbd{echo 1 | awk -f end.awk}
|
| 18468 | |
a b 1
|
| 18469 | |
$ @kbd{echo 1 | gawk -f end.awk}
|
| 18470 | |
a 1 1 b 1
|
| 18471 | |
@end example
|
| 18472 | |
|
| 18473 | |
If you want your program to be deterministic, don't depend on @code{for}
|
| 18474 | |
on arrays:
|
| 18475 | |
|
| 18476 | |
@example
|
| 18477 | |
$ @kbd{cat for.awk}
|
| 18478 | |
END @{
|
| 18479 | |
arr["foo"] = 1
|
| 18480 | |
arr["bar"] = 1
|
| 18481 | |
for (i in arr)
|
| 18482 | |
print i
|
| 18483 | |
@}
|
| 18484 | |
$ @kbd{gawk -f for.awk </dev/null}
|
| 18485 | |
foo
|
| 18486 | |
bar
|
| 18487 | |
$ @kbd{nawk -f for.awk </dev/null}
|
| 18488 | |
bar
|
| 18489 | |
foo
|
| 18490 | |
@end example
|
| 18491 | |
|
| 18492 | |
Some Awk implementations, such as HP-UX 11.0's native one,
|
| 18493 | |
mishandle anchors:
|
| 18494 | |
|
| 18495 | |
@example
|
| 18496 | |
$ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
|
| 18497 | |
$ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
|
| 18498 | |
bar
|
| 18499 | |
$ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
|
| 18500 | |
xfoo
|
| 18501 | |
$ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
|
| 18502 | |
bar
|
| 18503 | |
@end example
|
| 18504 | |
|
| 18505 | |
@noindent
|
| 18506 | |
Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
|
| 18507 | |
or use a simple test to reject such implementations.
|
| 18508 | |
|
| 18509 | |
On @samp{ia64-hp-hpux11.23}, Awk mishandles @code{printf} conversions
|
| 18510 | |
after @code{%u}:
|
| 18511 | |
|
| 18512 | |
@example
|
| 18513 | |
$ @kbd{awk 'BEGIN @{ printf "%u %d\n", 0, -1 @}'}
|
| 18514 | |
0 0
|
| 18515 | |
@end example
|
| 18516 | |
|
| 18517 | |
AIX version 5.2 has an arbitrary limit of 399 on the
|
| 18518 | |
length of regular expressions and literal strings in an Awk program.
|
| 18519 | |
|
| 18520 | |
Traditional Awk implementations derived from Unix version 7, such as
|
| 18521 | |
Solaris @command{/bin/awk}, have many limitations and do not
|
| 18522 | |
conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
|
| 18523 | |
Programs}) finds you an Awk that doesn't have these problems, but if
|
| 18524 | |
for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
|
| 18525 | |
address them. For more detailed descriptions, see @ref{Language
|
| 18526 | |
History, , @command{awk} language history, gawk, GNU Awk User's Guide}.
|
| 18527 | |
|
| 18528 | |
Traditional Awk does not support multidimensional arrays or user-defined
|
| 18529 | |
functions.
|
| 18530 | |
|
| 18531 | |
Traditional Awk does not support the @option{-v} option. You can use
|
| 18532 | |
assignments after the program instead, e.g., @code{$AWK '@{print v
|
| 18533 | |
$1@}' v=x}; however, don't forget that such assignments are not
|
| 18534 | |
evaluated until they are encountered (e.g., after any @code{BEGIN}
|
| 18535 | |
action).
|
| 18536 | |
|
| 18537 | |
Traditional Awk does not support the keywords @code{delete} or @code{do}.
|
| 18538 | |
|
| 18539 | |
Traditional Awk does not support the expressions
|
| 18540 | |
@code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
|
| 18541 | |
or @code{@var{a}^=@var{b}}.
|
| 18542 | |
|
| 18543 | |
Traditional Awk does not support the predefined @code{CONVFMT} or
|
| 18544 | |
@code{ENVIRON} variables.
|
| 18545 | |
|
| 18546 | |
Traditional Awk supports only the predefined functions @code{exp}, @code{index},
|
| 18547 | |
@code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
|
| 18548 | |
@code{sqrt}, and @code{substr}.
|
| 18549 | |
|
| 18550 | |
Traditional Awk @code{getline} is not at all compatible with Posix;
|
| 18551 | |
avoid it.
|
| 18552 | |
|
| 18553 | |
Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
|
| 18554 | |
@code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
|
| 18555 | |
|
| 18556 | |
In code portable to both traditional and modern Awk, @code{FS} must be a
|
| 18557 | |
string containing just one ordinary character, and similarly for the
|
| 18558 | |
field-separator argument to @code{split}.
|
| 18559 | |
|
| 18560 | |
Traditional Awk has a limit of 99 fields in a record. Since some Awk
|
| 18561 | |
implementations, like Tru64's, split the input even if you don't refer
|
| 18562 | |
to any field in the script, to circumvent this problem, set @samp{FS}
|
| 18563 | |
to an unusual character and use @code{split}.
|
| 18564 | |
|
| 18565 | |
Traditional Awk has a limit of at most 99 bytes in a number formatted by
|
| 18566 | |
@code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
|
| 18567 | |
dumps core.
|
| 18568 | |
|
| 18569 | |
The original version of Awk had a limit of at most 99 bytes per
|
| 18570 | |
@code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
|
| 18571 | |
per run of non-special characters in a @code{printf} format, but these
|
| 18572 | |
bugs have been fixed on all practical hosts that we know of.
|
| 18573 | |
|
| 18574 | |
HP-UX 11.00 and IRIX 6.5 Awk require that input files have a line length
|
| 18575 | |
of at most 3070 bytes.
|
| 18576 | |
|
| 18577 | |
@item @command{basename}
|
| 18578 | |
@c ---------------------
|
| 18579 | |
@prindex @command{basename}
|
| 18580 | |
Not all hosts have a working @command{basename}.
|
| 18581 | |
You can use @command{expr} instead.
|
| 18582 | |
|
| 18583 | |
@c AS_BASENAME is to be replaced by a better API.
|
| 18584 | |
@ignore
|
| 18585 | |
Not all hosts have a working @command{basename}, and you should instead
|
| 18586 | |
use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
|
| 18587 | |
@command{expr} if you need to strip a suffix. For example:
|
| 18588 | |
|
| 18589 | |
@example
|
| 18590 | |
a=`basename "$aname"` # This is not portable.
|
| 18591 | |
a=`AS_BASENAME(["$aname"])` # This is more portable.
|
| 18592 | |
|
| 18593 | |
# This is not portable.
|
| 18594 | |
c=`basename "$cname" .c`
|
| 18595 | |
|
| 18596 | |
# This is more portable.
|
| 18597 | |
c=`AS_BASENAME(["$cname"])`
|
| 18598 | |
case $c in
|
| 18599 | |
?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
|
| 18600 | |
esac
|
| 18601 | |
@end example
|
| 18602 | |
@end ignore
|
| 18603 | |
|
| 18604 | |
|
| 18605 | |
@item @command{cat}
|
| 18606 | |
@c ----------------
|
| 18607 | |
@prindex @command{cat}
|
| 18608 | |
Don't rely on any option.
|
| 18609 | |
|
| 18610 | |
|
| 18611 | |
@item @command{cc}
|
| 18612 | |
@c ---------------
|
| 18613 | |
@prindex @command{cc}
|
| 18614 | |
The command @samp{cc -c foo.c} traditionally produces an object file
|
| 18615 | |
named @file{foo.o}. Most compilers allow @option{-c} to be combined
|
| 18616 | |
with @option{-o} to specify a different object file name, but
|
| 18617 | |
Posix does not require this combination and a few compilers
|
| 18618 | |
lack support for it. @xref{C Compiler}, for how GNU Make
|
| 18619 | |
tests for this feature with @code{AC_PROG_CC_C_O}.
|
| 18620 | |
|
| 18621 | |
When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
|
| 18622 | |
(such as CDS on Reliant Unix) leave a @file{foo.o}.
|
| 18623 | |
|
| 18624 | |
HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
|
| 18625 | |
assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
|
| 18626 | |
nothing.
|
| 18627 | |
|
| 18628 | |
The default executable, produced by @samp{cc foo.c}, can be
|
| 18629 | |
|
| 18630 | |
@itemize
|
| 18631 | |
@item @file{a.out} --- usual Posix convention.
|
| 18632 | |
@item @file{b.out} --- i960 compilers (including @command{gcc}).
|
| 18633 | |
@item @file{a.exe} --- DJGPP port of @command{gcc}.
|
| 18634 | |
@item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
|
| 18635 | |
@item @file{foo.exe} --- various MS-DOS compilers.
|
| 18636 | |
@end itemize
|
| 18637 | |
|
| 18638 | |
The C compiler's traditional name is @command{cc}, but other names like
|
| 18639 | |
@command{gcc} are common. Posix 1003.1-2001 specifies the
|
| 18640 | |
name @command{c99}, but older Posix editions specified
|
| 18641 | |
@command{c89} and anyway these standard names are rarely used in
|
| 18642 | |
practice. Typically the C compiler is invoked from makefiles that use
|
| 18643 | |
@samp{$(CC)}, so the value of the @samp{CC} make variable selects the
|
| 18644 | |
compiler name.
|
| 18645 | |
|
| 18646 | |
@item @command{chgrp}
|
| 18647 | |
@itemx @command{chown}
|
| 18648 | |
@c -------------------
|
| 18649 | |
@prindex @command{chgrp}
|
| 18650 | |
@prindex @command{chown}
|
| 18651 | |
It is not portable to change a file's group to a group that the owner
|
| 18652 | |
does not belong to.
|
| 18653 | |
|
| 18654 | |
@item @command{chmod}
|
| 18655 | |
@c ------------------
|
| 18656 | |
@prindex @command{chmod}
|
| 18657 | |
Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
|
| 18658 | |
instead, for two reasons. First, plain @option{-w} does not necessarily
|
| 18659 | |
make the file unwritable, since it does not affect mode bits that
|
| 18660 | |
correspond to bits in the file mode creation mask. Second,
|
| 18661 | |
Posix says that the @option{-w} might be interpreted as an
|
| 18662 | |
implementation-specific option, not as a mode; Posix suggests
|
| 18663 | |
using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
|
| 18664 | |
@samp{--} does not work on some older hosts.
|
| 18665 | |
|
| 18666 | |
|
| 18667 | |
@item @command{cmp}
|
| 18668 | |
@c ----------------
|
| 18669 | |
@prindex @command{cmp}
|
| 18670 | |
@command{cmp} performs a raw data comparison of two files, while
|
| 18671 | |
@command{diff} compares two text files. Therefore, if you might compare
|
| 18672 | |
DOS files, even if only checking whether two files are different, use
|
| 18673 | |
@command{diff} to avoid spurious differences due to differences of
|
| 18674 | |
newline encoding.
|
| 18675 | |
|
| 18676 | |
|
| 18677 | |
@item @command{cp}
|
| 18678 | |
@c ---------------
|
| 18679 | |
@prindex @command{cp}
|
| 18680 | |
Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
|
| 18681 | |
obsolescent and its behavior on special files is implementation-defined.
|
| 18682 | |
Use @option{-R} instead. On GNU hosts the two options
|
| 18683 | |
are equivalent, but on Solaris hosts (for example) @code{cp -r}
|
| 18684 | |
reads from pipes instead of replicating them. AIX 5.3 @code{cp -R} may
|
| 18685 | |
corrupt its own memory with some directory hierarchies and error out or
|
| 18686 | |
dump core:
|
| 18687 | |
|
| 18688 | |
@example
|
| 18689 | |
@kbd{mkdir -p 12345678/12345678/12345678/12345678}
|
| 18690 | |
@kbd{touch 12345678/12345678/x}
|
| 18691 | |
@kbd{cp -R 12345678 t}
|
| 18692 | |
cp: 0653-440 12345678/12345678/: name too long.
|
| 18693 | |
@end example
|
| 18694 | |
|
| 18695 | |
Some @command{cp} implementations (e.g., BSD/OS 4.2) do not allow
|
| 18696 | |
trailing slashes at the end of nonexistent destination directories. To
|
| 18697 | |
avoid this problem, omit the trailing slashes. For example, use
|
| 18698 | |
@samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
|
| 18699 | |
/tmp/newdir/} if @file{/tmp/newdir} does not exist.
|
| 18700 | |
|
| 18701 | |
@c This is thanks to Ian.
|
| 18702 | |
The ancient SunOS 4 @command{cp} does not support @option{-f}, although
|
| 18703 | |
its @command{mv} does.
|
| 18704 | |
|
| 18705 | |
@cindex timestamp resolution
|
| 18706 | |
Traditionally, file timestamps had 1-second resolution, and @samp{cp
|
| 18707 | |
-p} copied the timestamps exactly. However, many modern file systems
|
| 18708 | |
have timestamps with 1-nanosecond resolution. Unfortunately, some older
|
| 18709 | |
@samp{cp -p} implementations truncate timestamps when copying files,
|
| 18710 | |
which can cause the destination file to appear to be older than the
|
| 18711 | |
source. The exact amount of truncation depends on the resolution of
|
| 18712 | |
the system calls that @command{cp} uses. Traditionally this was
|
| 18713 | |
@code{utime}, which has 1-second resolution. Less-ancient @command{cp}
|
| 18714 | |
implementations such as GNU Core Utilities 5.0.91 (2003) use
|
| 18715 | |
@code{utimes}, which has 1-microsecond resolution. Modern
|
| 18716 | |
implementations such as GNU Core Utilities 6.12 (2008) can set timestamps to
|
| 18717 | |
the full nanosecond resolution, using the modern system calls
|
| 18718 | |
@code{futimens} and @code{utimensat} when they are available. As of
|
| 18719 | |
2011, though, many platforms do not yet fully support these new system
|
| 18720 | |
calls.
|
| 18721 | |
|
| 18722 | |
Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
|
| 18723 | |
ownerships. But whether it actually does copy ownerships or not is a
|
| 18724 | |
system dependent policy decision implemented by the kernel. If the
|
| 18725 | |
kernel allows it then it happens. If the kernel does not allow it then
|
| 18726 | |
it does not happen. It is not something @command{cp} itself has control
|
| 18727 | |
over.
|
| 18728 | |
|
| 18729 | |
In Unix System V any user can chown files to any other user, and System
|
| 18730 | |
V also has a non-sticky @file{/tmp}. That probably derives from the
|
| 18731 | |
heritage of System V in a business environment without hostile users.
|
| 18732 | |
BSD changed this
|
| 18733 | |
to be a more secure model where only root can @command{chown} files and
|
| 18734 | |
a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
|
| 18735 | |
of BSD in a campus environment.
|
| 18736 | |
|
| 18737 | |
GNU/Linux and Solaris by default follow BSD, but
|
| 18738 | |
can be configured to allow a System V style @command{chown}. On the
|
| 18739 | |
other hand, HP-UX follows System V, but can
|
| 18740 | |
be configured to use the modern security model and disallow
|
| 18741 | |
@command{chown}. Since it is an administrator-configurable parameter
|
| 18742 | |
you can't use the name of the kernel as an indicator of the behavior.
|
| 18743 | |
|
| 18744 | |
|
| 18745 | |
|
| 18746 | |
@item @command{date}
|
| 18747 | |
@c -----------------
|
| 18748 | |
@prindex @command{date}
|
| 18749 | |
Some versions of @command{date} do not recognize special @samp{%} directives,
|
| 18750 | |
and unfortunately, instead of complaining, they just pass them through,
|
| 18751 | |
and exit with success:
|
| 18752 | |
|
| 18753 | |
@example
|
| 18754 | |
$ @kbd{uname -a}
|
| 18755 | |
OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
|
| 18756 | |
$ @kbd{date "+%s"}
|
| 18757 | |
%s
|
| 18758 | |
@end example
|
| 18759 | |
|
| 18760 | |
|
| 18761 | |
@item @command{diff}
|
| 18762 | |
@c -----------------
|
| 18763 | |
@prindex @command{diff}
|
| 18764 | |
Option @option{-u} is nonportable.
|
| 18765 | |
|
| 18766 | |
Some implementations, such as Tru64's, fail when comparing to
|
| 18767 | |
@file{/dev/null}. Use an empty file instead.
|
| 18768 | |
|
| 18769 | |
|
| 18770 | |
@item @command{dirname}
|
| 18771 | |
@c --------------------
|
| 18772 | |
@prindex @command{dirname}
|
| 18773 | |
Not all hosts have a working @command{dirname}, and you should instead
|
| 18774 | |
use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
|
| 18775 | |
|
| 18776 | |
@example
|
| 18777 | |
dir=`dirname "$file"` # This is not portable.
|
| 18778 | |
dir=`AS_DIRNAME(["$file"])` # This is more portable.
|
| 18779 | |
@end example
|
| 18780 | |
|
| 18781 | |
|
| 18782 | |
@item @command{egrep}
|
| 18783 | |
@c ------------------
|
| 18784 | |
@prindex @command{egrep}
|
| 18785 | |
Posix 1003.1-2001 no longer requires @command{egrep},
|
| 18786 | |
but many hosts do not yet support the Posix
|
| 18787 | |
replacement @code{grep -E}. Also, some traditional implementations do
|
| 18788 | |
not work on long input lines. To work around these problems, invoke
|
| 18789 | |
@code{AC_PROG_EGREP} and then use @code{$EGREP}.
|
| 18790 | |
|
| 18791 | |
Portable extended regular expressions should use @samp{\} only to escape
|
| 18792 | |
characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
|
| 18793 | |
is not portable, even though it typically matches @samp{@}}.
|
| 18794 | |
|
| 18795 | |
The empty alternative is not portable. Use @samp{?} instead. For
|
| 18796 | |
instance with Digital Unix v5.0:
|
| 18797 | |
|
| 18798 | |
@example
|
| 18799 | |
> printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
|
| 18800 | |
|foo
|
| 18801 | |
> printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
|
| 18802 | |
bar|
|
| 18803 | |
> printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
|
| 18804 | |
foo
|
| 18805 | |
|bar
|
| 18806 | |
@end example
|
| 18807 | |
|
| 18808 | |
@command{$EGREP} also suffers the limitations of @command{grep}
|
| 18809 | |
(@pxref{grep, , Limitations of Usual Tools}).
|
| 18810 | |
|
| 18811 | |
@item @command{expr}
|
| 18812 | |
@c -----------------
|
| 18813 | |
@prindex @command{expr}
|
| 18814 | |
Not all implementations obey the Posix rule that @samp{--} separates
|
| 18815 | |
options from arguments; likewise, not all implementations provide the
|
| 18816 | |
extension to Posix that the first argument can be treated as part of a
|
| 18817 | |
valid expression rather than an invalid option if it begins with
|
| 18818 | |
@samp{-}. When performing arithmetic, use @samp{expr 0 + $var} if
|
| 18819 | |
@samp{$var} might be a negative number, to keep @command{expr} from
|
| 18820 | |
interpreting it as an option.
|
| 18821 | |
|
| 18822 | |
No @command{expr} keyword starts with @samp{X}, so use @samp{expr
|
| 18823 | |
X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
|
| 18824 | |
misinterpreting @var{word}.
|
| 18825 | |
|
| 18826 | |
Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
|
| 18827 | |
|
| 18828 | |
@item @command{expr} (@samp{|})
|
| 18829 | |
@prindex @command{expr} (@samp{|})
|
| 18830 | |
You can use @samp{|}. Although Posix does require that @samp{expr
|
| 18831 | |
''} return the empty string, it does not specify the result when you
|
| 18832 | |
@samp{|} together the empty string (or zero) with the empty string. For
|
| 18833 | |
example:
|
| 18834 | |
|
| 18835 | |
@example
|
| 18836 | |
expr '' \| ''
|
| 18837 | |
@end example
|
| 18838 | |
|
| 18839 | |
Posix 1003.2-1992 returns the empty string
|
| 18840 | |
for this case, but traditional Unix returns @samp{0} (Solaris is
|
| 18841 | |
one such example). In Posix 1003.1-2001, the specification was
|
| 18842 | |
changed to match traditional Unix's behavior (which is
|
| 18843 | |
bizarre, but it's too late to fix this). Please note that the same
|
| 18844 | |
problem does arise when the empty string results from a computation,
|
| 18845 | |
as in:
|
| 18846 | |
|
| 18847 | |
@example
|
| 18848 | |
expr bar : foo \| foo : bar
|
| 18849 | |
@end example
|
| 18850 | |
|
| 18851 | |
@noindent
|
| 18852 | |
Avoid this portability problem by avoiding the empty string.
|
| 18853 | |
|
| 18854 | |
|
| 18855 | |
@item @command{expr} (@samp{:})
|
| 18856 | |
@c ----------------------------
|
| 18857 | |
@prindex @command{expr}
|
| 18858 | |
Portable @command{expr} regular expressions should use @samp{\} to
|
| 18859 | |
escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
|
| 18860 | |
For example, alternation, @samp{\|}, is common but Posix does not
|
| 18861 | |
require its support, so it should be avoided in portable scripts.
|
| 18862 | |
Similarly, @samp{\+} and @samp{\?} should be avoided.
|
| 18863 | |
|
| 18864 | |
Portable @command{expr} regular expressions should not begin with
|
| 18865 | |
@samp{^}. Patterns are automatically anchored so leading @samp{^} is
|
| 18866 | |
not needed anyway.
|
| 18867 | |
|
| 18868 | |
On the other hand, the behavior of the @samp{$} anchor is not portable
|
| 18869 | |
on multi-line strings. Posix is ambiguous whether the anchor applies to
|
| 18870 | |
each line, as was done in older versions of the GNU Core Utilities, or
|
| 18871 | |
whether it applies only to the end of the overall string, as in
|
| 18872 | |
Coreutils 6.0 and most other implementations.
|
| 18873 | |
|
| 18874 | |
@example
|
| 18875 | |
$ @kbd{baz='foo}
|
| 18876 | |
> @kbd{bar'}
|
| 18877 | |
$ @kbd{expr "X$baz" : 'X\(foo\)$'}
|
| 18878 | |
|
| 18879 | |
$ @kbd{expr-5.97 "X$baz" : 'X\(foo\)$'}
|
| 18880 | |
foo
|
| 18881 | |
@end example
|
| 18882 | |
|
| 18883 | |
The Posix standard is ambiguous as to whether
|
| 18884 | |
@samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
|
| 18885 | |
In practice, it outputs the empty string on most platforms, but portable
|
| 18886 | |
scripts should not assume this. For instance, the QNX 4.25 native
|
| 18887 | |
@command{expr} returns @samp{0}.
|
| 18888 | |
|
| 18889 | |
One might think that a way to get a uniform behavior would be to use
|
| 18890 | |
the empty string as a default value:
|
| 18891 | |
|
| 18892 | |
@example
|
| 18893 | |
expr a : '\(b\)' \| ''
|
| 18894 | |
@end example
|
| 18895 | |
|
| 18896 | |
@noindent
|
| 18897 | |
Unfortunately this behaves exactly as the original expression; see the
|
| 18898 | |
@command{expr} (@samp{|}) entry for more information.
|
| 18899 | |
|
| 18900 | |
Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
|
| 18901 | |
Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
|
| 18902 | |
@command{expr} to fail if the matched substring is longer than 120
|
| 18903 | |
bytes. In this case, you might want to fall back on @samp{echo|sed} if
|
| 18904 | |
@command{expr} fails. Nowadays this is of practical importance only for
|
| 18905 | |
the rare installer who mistakenly puts @file{/usr/ucb} before
|
| 18906 | |
@file{/usr/bin} in @env{PATH}.
|
| 18907 | |
|
| 18908 | |
On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
|
| 18909 | |
some cases. For example, the command
|
| 18910 | |
@example
|
| 18911 | |
expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
|
| 18912 | |
@end example
|
| 18913 | |
|
| 18914 | |
@noindent
|
| 18915 | |
outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
|
| 18916 | |
This particular case can be worked around by substituting @samp{[^--]}
|
| 18917 | |
for @samp{[^-]}.
|
| 18918 | |
|
| 18919 | |
Don't leave, there is some more!
|
| 18920 | |
|
| 18921 | |
The QNX 4.25 @command{expr}, in addition of preferring @samp{0} to
|
| 18922 | |
the empty string, has a funny behavior in its exit status: it's always 1
|
| 18923 | |
when parentheses are used!
|
| 18924 | |
|
| 18925 | |
@example
|
| 18926 | |
$ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
|
| 18927 | |
0: 1
|
| 18928 | |
$ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
|
| 18929 | |
1: 0
|
| 18930 | |
|
| 18931 | |
$ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
|
| 18932 | |
1: a
|
| 18933 | |
$ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
|
| 18934 | |
1: 0
|
| 18935 | |
@end example
|
| 18936 | |
|
| 18937 | |
@noindent
|
| 18938 | |
In practice this can be a big problem if you are ready to catch failures
|
| 18939 | |
of @command{expr} programs with some other method (such as using
|
| 18940 | |
@command{sed}), since you may get twice the result. For instance
|
| 18941 | |
|
| 18942 | |
@example
|
| 18943 | |
$ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
|
| 18944 | |
@end example
|
| 18945 | |
|
| 18946 | |
@noindent
|
| 18947 | |
outputs @samp{a} on most hosts, but @samp{aa} on QNX 4.25. A
|
| 18948 | |
simple workaround consists of testing @command{expr} and using a variable
|
| 18949 | |
set to @command{expr} or to @command{false} according to the result.
|
| 18950 | |
|
| 18951 | |
Tru64 @command{expr} incorrectly treats the result as a number, if it
|
| 18952 | |
can be interpreted that way:
|
| 18953 | |
|
| 18954 | |
@example
|
| 18955 | |
$ @kbd{expr 00001 : '.*\(...\)'}
|
| 18956 | |
1
|
| 18957 | |
@end example
|
| 18958 | |
|
| 18959 | |
On HP-UX 11, @command{expr} only supports a single
|
| 18960 | |
sub-expression.
|
| 18961 | |
|
| 18962 | |
@example
|
| 18963 | |
$ @kbd{expr 'Xfoo' : 'X\(f\(oo\)*\)$'}
|
| 18964 | |
expr: More than one '\(' was used.
|
| 18965 | |
@end example
|
| 18966 | |
|
| 18967 | |
|
| 18968 | |
@item @command{fgrep}
|
| 18969 | |
@c ------------------
|
| 18970 | |
@prindex @command{fgrep}
|
| 18971 | |
Posix 1003.1-2001 no longer requires @command{fgrep},
|
| 18972 | |
but many hosts do not yet support the Posix
|
| 18973 | |
replacement @code{grep -F}. Also, some traditional implementations do
|
| 18974 | |
not work on long input lines. To work around these problems, invoke
|
| 18975 | |
@code{AC_PROG_FGREP} and then use @code{$FGREP}.
|
| 18976 | |
|
| 18977 | |
Tru64/OSF 5.1 @command{fgrep} does not match an empty pattern.
|
| 18978 | |
|
| 18979 | |
|
| 18980 | |
@item @command{find}
|
| 18981 | |
@c -----------------
|
| 18982 | |
@prindex @command{find}
|
| 18983 | |
The option @option{-maxdepth} seems to be GNU specific.
|
| 18984 | |
Tru64 v5.1, NetBSD 1.5 and Solaris @command{find}
|
| 18985 | |
commands do not understand it.
|
| 18986 | |
|
| 18987 | |
The replacement of @samp{@{@}} is guaranteed only if the argument is
|
| 18988 | |
exactly @emph{@{@}}, not if it's only a part of an argument. For
|
| 18989 | |
instance on DU, and HP-UX 10.20 and HP-UX 11:
|
| 18990 | |
|
| 18991 | |
@example
|
| 18992 | |
$ @kbd{touch foo}
|
| 18993 | |
$ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
|
| 18994 | |
@{@}-@{@}
|
| 18995 | |
@end example
|
| 18996 | |
|
| 18997 | |
@noindent
|
| 18998 | |
while GNU @command{find} reports @samp{./foo-./foo}.
|
| 18999 | |
|
| 19000 | |
|
| 19001 | |
@anchor{grep}
|
| 19002 | |
@item @command{grep}
|
| 19003 | |
@c -----------------
|
| 19004 | |
@prindex @command{grep}
|
| 19005 | |
Portable scripts can rely on the @command{grep} options @option{-c},
|
| 19006 | |
@option{-l}, @option{-n}, and @option{-v}, but should avoid other
|
| 19007 | |
options. For example, don't use @option{-w}, as Posix does not require
|
| 19008 | |
it and Irix 6.5.16m's @command{grep} does not support it. Also,
|
| 19009 | |
portable scripts should not combine @option{-c} with @option{-l},
|
| 19010 | |
as Posix does not allow this.
|
| 19011 | |
|
| 19012 | |
Some of the options required by Posix are not portable in practice.
|
| 19013 | |
Don't use @samp{grep -q} to suppress output, because many @command{grep}
|
| 19014 | |
implementations (e.g., Solaris) do not support @option{-q}.
|
| 19015 | |
Don't use @samp{grep -s} to suppress output either, because Posix
|
| 19016 | |
says @option{-s} does not suppress output, only some error messages;
|
| 19017 | |
also, the @option{-s} option of traditional @command{grep} behaved
|
| 19018 | |
like @option{-q} does in most modern implementations. Instead,
|
| 19019 | |
redirect the standard output and standard error (in case the file
|
| 19020 | |
doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
|
| 19021 | |
status of @code{grep} to determine whether it found a match.
|
| 19022 | |
|
| 19023 | |
The QNX4 implementation fails to count lines with @code{grep -c '$'},
|
| 19024 | |
but works with @code{grep -c '^'}. Other alternatives for counting
|
| 19025 | |
lines are to use @code{sed -n '$='} or @code{wc -l}.
|
| 19026 | |
|
| 19027 | |
Some traditional @command{grep} implementations do not work on long
|
| 19028 | |
input lines. On AIX the default @code{grep} silently truncates long
|
| 19029 | |
lines on the input before matching.
|
| 19030 | |
|
| 19031 | |
Also, many implementations do not support multiple regexps
|
| 19032 | |
with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
|
| 19033 | |
or honor only the last pattern (e.g., IRIX 6.5 and NeXT). To
|
| 19034 | |
work around these problems, invoke @code{AC_PROG_GREP} and then use
|
| 19035 | |
@code{$GREP}.
|
| 19036 | |
|
| 19037 | |
Another possible workaround for the multiple @option{-e} problem is to
|
| 19038 | |
separate the patterns by newlines, for example:
|
| 19039 | |
|
| 19040 | |
@example
|
| 19041 | |
grep 'foo
|
| 19042 | |
bar' in.txt
|
| 19043 | |
@end example
|
| 19044 | |
|
| 19045 | |
@noindent
|
| 19046 | |
except that this fails with traditional @command{grep}
|
| 19047 | |
implementations and with OpenBSD 3.8 @command{grep}.
|
| 19048 | |
|
| 19049 | |
Traditional @command{grep} implementations (e.g., Solaris) do not
|
| 19050 | |
support the @option{-E} or @option{-F} options. To work around these
|
| 19051 | |
problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
|
| 19052 | |
similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
|
| 19053 | |
willing to require support for Posix @command{grep}, your script should
|
| 19054 | |
not use both @option{-E} and @option{-F}, since Posix does not allow
|
| 19055 | |
this combination.
|
| 19056 | |
|
| 19057 | |
Portable @command{grep} regular expressions should use @samp{\} only to
|
| 19058 | |
escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
|
| 19059 | |
alternation, @samp{\|}, is common but Posix does not require its
|
| 19060 | |
support in basic regular expressions, so it should be avoided in
|
| 19061 | |
portable scripts. Solaris and HP-UX @command{grep} do not support it.
|
| 19062 | |
Similarly, the following escape sequences should also be avoided:
|
| 19063 | |
@samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
|
| 19064 | |
@samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
|
| 19065 | |
|
| 19066 | |
Posix does not specify the behavior of @command{grep} on binary files.
|
| 19067 | |
An example where this matters is using BSD @command{grep} to
|
| 19068 | |
search text that includes embedded ANSI escape sequences for
|
| 19069 | |
colored output to terminals (@samp{\033[m} is the sequence to restore
|
| 19070 | |
normal output); the behavior depends on whether input is seekable:
|
| 19071 | |
|
| 19072 | |
@example
|
| 19073 | |
$ @kbd{printf 'esc\033[mape\n' > sample}
|
| 19074 | |
$ @kbd{grep . sample}
|
| 19075 | |
Binary file sample matches
|
| 19076 | |
$ @kbd{cat sample | grep .}
|
| 19077 | |
escape
|
| 19078 | |
@end example
|
| 19079 | |
|
| 19080 | |
|
| 19081 | |
@item @command{join}
|
| 19082 | |
@c -----------------
|
| 19083 | |
@prindex @command{join}
|
| 19084 | |
Solaris 8 @command{join} has bugs when the second operand is standard
|
| 19085 | |
input, and when standard input is a pipe. For example, the following
|
| 19086 | |
shell script causes Solaris 8 @command{join} to loop forever:
|
| 19087 | |
|
| 19088 | |
@example
|
| 19089 | |
cat >file <<'EOF'
|
| 19090 | |
1 x
|
| 19091 | |
2 y
|
| 19092 | |
EOF
|
| 19093 | |
cat file | join file -
|
| 19094 | |
@end example
|
| 19095 | |
|
| 19096 | |
Use @samp{join - file} instead.
|
| 19097 | |
|
| 19098 | |
On NetBSD, @command{join -a 1 file1 file2} mistakenly behaves like
|
| 19099 | |
@command{join -a 1 -a 2 1 file1 file2}, resulting in a usage warning;
|
| 19100 | |
the workaround is to use @command{join -a1 file1 file2} instead.
|
| 19101 | |
|
| 19102 | |
@item @command{ln}
|
| 19103 | |
@c ---------------
|
| 19104 | |
@prindex @command{ln}
|
| 19105 | |
@cindex Symbolic links
|
| 19106 | |
Don't rely on @command{ln} having a @option{-f} option. Symbolic links
|
| 19107 | |
are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
|
| 19108 | |
|
| 19109 | |
For versions of the DJGPP before 2.04,
|
| 19110 | |
@command{ln} emulates symbolic links
|
| 19111 | |
to executables by generating a stub that in turn calls the real
|
| 19112 | |
program. This feature also works with nonexistent files like in the
|
| 19113 | |
Posix spec. So @samp{ln -s file link} generates @file{link.exe},
|
| 19114 | |
which attempts to call @file{file.exe} if run. But this feature only
|
| 19115 | |
works for executables, so @samp{cp -p} is used instead for these
|
| 19116 | |
systems. DJGPP versions 2.04 and later have full support
|
| 19117 | |
for symbolic links.
|
| 19118 | |
|
| 19119 | |
|
| 19120 | |
@item @command{ls}
|
| 19121 | |
@c ---------------
|
| 19122 | |
@prindex @command{ls}
|
| 19123 | |
@cindex Listing directories
|
| 19124 | |
The portable options are @option{-acdilrtu}. Current practice is for
|
| 19125 | |
@option{-l} to output both owner and group, even though ancient versions
|
| 19126 | |
of @command{ls} omitted the group.
|
| 19127 | |
|
| 19128 | |
On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
|
| 19129 | |
to standard output if @file{foo} did not exist. Hence a shell command
|
| 19130 | |
like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
|
| 19131 | |
was equivalent to @samp{sources='*.c not found'} in the absence of
|
| 19132 | |
@samp{.c} files. This is no longer a practical problem, since current
|
| 19133 | |
@command{ls} implementations send diagnostics to standard error.
|
| 19134 | |
|
| 19135 | |
The behavior of @command{ls} on a directory that is being concurrently
|
| 19136 | |
modified is not always predictable, because of a data race where cached
|
| 19137 | |
information returned by @code{readdir} does not match the current
|
| 19138 | |
directory state. In fact, MacOS 10.5 has an intermittent bug where
|
| 19139 | |
@code{readdir}, and thus @command{ls}, sometimes lists a file more than
|
| 19140 | |
once if other files were added or removed from the directory immediately
|
| 19141 | |
prior to the @command{ls} call. Since @command{ls} already sorts its
|
| 19142 | |
output, the duplicate entries can be avoided by piping the results
|
| 19143 | |
through @code{uniq}.
|
| 19144 | |
|
| 19145 | |
@anchor{mkdir}
|
| 19146 | |
@item @command{mkdir}
|
| 19147 | |
@c ------------------
|
| 19148 | |
@prindex @command{mkdir}
|
| 19149 | |
@cindex Making directories
|
| 19150 | |
No @command{mkdir} option is portable to older systems. Instead of
|
| 19151 | |
@samp{mkdir -p @var{file-name}}, you should use
|
| 19152 | |
@code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
|
| 19153 | |
or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
|
| 19154 | |
|
| 19155 | |
Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
|
| 19156 | |
go-w -p @var{dir}}, often leads to trouble. FreeBSD
|
| 19157 | |
@command{mkdir} incorrectly attempts to change the permissions of
|
| 19158 | |
@var{dir} even if it already exists. HP-UX 11.23 and
|
| 19159 | |
IRIX 6.5 @command{mkdir} often assign the wrong permissions to
|
| 19160 | |
any newly-created parents of @var{dir}.
|
| 19161 | |
|
| 19162 | |
Posix does not clearly specify whether @samp{mkdir -p foo}
|
| 19163 | |
should succeed when @file{foo} is a symbolic link to an already-existing
|
| 19164 | |
directory. The GNU Core Utilities 5.1.0 @command{mkdir}
|
| 19165 | |
succeeds, but Solaris @command{mkdir} fails.
|
| 19166 | |
|
| 19167 | |
Traditional @code{mkdir -p} implementations suffer from race conditions.
|
| 19168 | |
For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
|
| 19169 | |
at the same time, both processes might detect that @file{a} is missing,
|
| 19170 | |
one might create @file{a}, then the other might try to create @file{a}
|
| 19171 | |
and fail with a @code{File exists} diagnostic. The GNU Core
|
| 19172 | |
Utilities (@samp{fileutils} version 4.1), FreeBSD 5.0,
|
| 19173 | |
NetBSD 2.0.2, and OpenBSD 2.4 are known to be
|
| 19174 | |
race-free when two processes invoke @code{mkdir -p} simultaneously, but
|
| 19175 | |
earlier versions are vulnerable. Solaris @command{mkdir} is still
|
| 19176 | |
vulnerable as of Solaris 10, and other traditional Unix systems are
|
| 19177 | |
probably vulnerable too. This possible race is harmful in parallel
|
| 19178 | |
builds when several Make rules call @code{mkdir -p} to
|
| 19179 | |
construct directories. You may use
|
| 19180 | |
@code{install-sh -d} as a safe replacement, provided this script is
|
| 19181 | |
recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
|
| 19182 | |
OK, but copies from older versions are vulnerable.
|
| 19183 | |
|
| 19184 | |
|
| 19185 | |
@item @command{mkfifo}
|
| 19186 | |
@itemx @command{mknod}
|
| 19187 | |
@c -------------------
|
| 19188 | |
@prindex @command{mkfifo}
|
| 19189 | |
@prindex @command{mknod}
|
| 19190 | |
The GNU Coding Standards state that @command{mknod} is safe to use on
|
| 19191 | |
platforms where it has been tested to exist; but it is generally portable
|
| 19192 | |
only for creating named FIFOs, since device numbers are
|
| 19193 | |
platform-specific. Autotest uses @command{mkfifo} to implement parallel
|
| 19194 | |
testsuites. Posix states that behavior is unspecified when opening a
|
| 19195 | |
named FIFO for both reading and writing; on at least Cygwin, this
|
| 19196 | |
results in failure on any attempt to read or write to that file
|
| 19197 | |
descriptor.
|
| 19198 | |
|
| 19199 | |
@item @command{mktemp}
|
| 19200 | |
@c -------------------
|
| 19201 | |
@prindex @command{mktemp}
|
| 19202 | |
@cindex Creating temporary files
|
| 19203 | |
Shell scripts can use temporary files safely with @command{mktemp}, but
|
| 19204 | |
it does not exist on all systems. A portable way to create a safe
|
| 19205 | |
temporary file name is to create a temporary directory with mode 700 and
|
| 19206 | |
use a file inside this directory. Both methods prevent attackers from
|
| 19207 | |
gaining control, though @command{mktemp} is far less likely to fail
|
| 19208 | |
gratuitously under attack.
|
| 19209 | |
|
| 19210 | |
Here is sample code to create a new temporary directory @samp{$dir} safely:
|
| 19211 | |
|
| 19212 | |
@example
|
| 19213 | |
# Create a temporary directory $dir in $TMPDIR (default /tmp).
|
| 19214 | |
# Use mktemp if possible; otherwise fall back on mkdir,
|
| 19215 | |
# with $RANDOM to make collisions less likely.
|
| 19216 | |
: "$@{TMPDIR:=/tmp@}"
|
| 19217 | |
@{
|
| 19218 | |
dir=`
|
| 19219 | |
(umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
|
| 19220 | |
` &&
|
| 19221 | |
test -d "$dir"
|
| 19222 | |
@} || @{
|
| 19223 | |
dir=$TMPDIR/foo$$-$RANDOM
|
| 19224 | |
@c $$ restore font-lock
|
| 19225 | |
(umask 077 && mkdir "$dir")
|
| 19226 | |
@} || exit $?
|
| 19227 | |
@end example
|
| 19228 | |
|
| 19229 | |
|
| 19230 | |
@item @command{mv}
|
| 19231 | |
@c ---------------
|
| 19232 | |
@prindex @command{mv}
|
| 19233 | |
@cindex Moving open files
|
| 19234 | |
The only portable options are @option{-f} and @option{-i}.
|
| 19235 | |
|
| 19236 | |
Moving individual files between file systems is portable (it was in Unix
|
| 19237 | |
version 6),
|
| 19238 | |
but it is not always atomic: when doing @samp{mv new existing}, there's
|
| 19239 | |
a critical section where neither the old nor the new version of
|
| 19240 | |
@file{existing} actually exists.
|
| 19241 | |
|
| 19242 | |
On some systems moving files from @file{/tmp} can sometimes cause
|
| 19243 | |
undesirable (but perfectly valid) warnings, even if you created these
|
| 19244 | |
files. This is because @file{/tmp} belongs to a group that ordinary
|
| 19245 | |
users are not members of, and files created in @file{/tmp} inherit
|
| 19246 | |
the group of @file{/tmp}. When the file is copied, @command{mv} issues
|
| 19247 | |
a diagnostic without failing:
|
| 19248 | |
|
| 19249 | |
@smallexample
|
| 19250 | |
$ @kbd{touch /tmp/foo}
|
| 19251 | |
$ @kbd{mv /tmp/foo .}
|
| 19252 | |
@error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
|
| 19253 | |
$ @kbd{echo $?}
|
| 19254 | |
0
|
| 19255 | |
$ @kbd{ls foo}
|
| 19256 | |
foo
|
| 19257 | |
@end smallexample
|
| 19258 | |
|
| 19259 | |
@noindent
|
| 19260 | |
This annoying behavior conforms to Posix, unfortunately.
|
| 19261 | |
|
| 19262 | |
Moving directories across mount points is not portable, use @command{cp}
|
| 19263 | |
and @command{rm}.
|
| 19264 | |
|
| 19265 | |
DOS variants cannot rename or remove open files, and do not
|
| 19266 | |
support commands like @samp{mv foo bar >foo}, even though this is
|
| 19267 | |
perfectly portable among Posix hosts.
|
| 19268 | |
|
| 19269 | |
|
| 19270 | |
@item @command{od}
|
| 19271 | |
@c ---------------
|
| 19272 | |
@prindex @command{od}
|
| 19273 | |
|
| 19274 | |
In Mac OS X 10.3, @command{od} does not support the
|
| 19275 | |
standard Posix options @option{-A}, @option{-j}, @option{-N}, or
|
| 19276 | |
@option{-t}, or the XSI option @option{-s}. The only
|
| 19277 | |
supported Posix option is @option{-v}, and the only supported
|
| 19278 | |
XSI options are those in @option{-bcdox}. The BSD
|
| 19279 | |
@command{hexdump} program can be used instead.
|
| 19280 | |
|
| 19281 | |
This problem no longer exists in Mac OS X 10.4.3.
|
| 19282 | |
|
| 19283 | |
|
| 19284 | |
@item @command{rm}
|
| 19285 | |
@c ---------------
|
| 19286 | |
@prindex @command{rm}
|
| 19287 | |
The @option{-f} and @option{-r} options are portable.
|
| 19288 | |
|
| 19289 | |
It is not portable to invoke @command{rm} without options or operands.
|
| 19290 | |
On the other hand, Posix now requires @command{rm -f} to silently
|
| 19291 | |
succeed when there are no operands (useful for constructs like
|
| 19292 | |
@command{rm -rf $filelist} without first checking if @samp{$filelist}
|
| 19293 | |
was empty). But this was not always portable; at least NetBSD
|
| 19294 | |
@command{rm} built before 2008 would fail with a diagnostic.
|
| 19295 | |
|
| 19296 | |
A file might not be removed even if its parent directory is writable
|
| 19297 | |
and searchable. Many Posix hosts cannot remove a mount point, a named
|
| 19298 | |
stream, a working directory, or a last link to a file that is being
|
| 19299 | |
executed.
|
| 19300 | |
|
| 19301 | |
DOS variants cannot rename or remove open files, and do not
|
| 19302 | |
support commands like @samp{rm foo >foo}, even though this is
|
| 19303 | |
perfectly portable among Posix hosts.
|
| 19304 | |
|
| 19305 | |
@item @command{rmdir}
|
| 19306 | |
@c ------------------
|
| 19307 | |
@prindex @command{rmdir}
|
| 19308 | |
Just as with @command{rm}, some platforms refuse to remove a working
|
| 19309 | |
directory.
|
| 19310 | |
|
| 19311 | |
@anchor{sed}
|
| 19312 | |
@item @command{sed}
|
| 19313 | |
@c ----------------
|
| 19314 | |
@prindex @command{sed}
|
| 19315 | |
Patterns should not include the separator (unless escaped), even as part
|
| 19316 | |
of a character class. In conformance with Posix, the Cray
|
| 19317 | |
@command{sed} rejects @samp{s/[^/]*$//}: use @samp{s%[^/]*$%%}.
|
| 19318 | |
Even when escaped, patterns should not include separators that are also
|
| 19319 | |
used as @command{sed} metacharacters. For example, GNU sed 4.0.9 rejects
|
| 19320 | |
@samp{s,x\@{1\,\@},,}, while sed 4.1 strips the backslash before the comma
|
| 19321 | |
before evaluating the basic regular expression.
|
| 19322 | |
|
| 19323 | |
Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
|
| 19324 | |
not require support for empty patterns, and Unicos 9 @command{sed} rejects
|
| 19325 | |
them.
|
| 19326 | |
|
| 19327 | |
Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
|
| 19328 | |
|
| 19329 | |
Sed scripts should not use branch labels longer than 7 characters and
|
| 19330 | |
should not contain comments; AIX 5.3 @command{sed} rejects indented comments.
|
| 19331 | |
HP-UX sed has a limit of 99 commands (not counting @samp{:} commands) and
|
| 19332 | |
48 labels, which cannot be circumvented by using more than one script
|
| 19333 | |
file. It can execute up to 19 reads with the @samp{r} command per cycle.
|
| 19334 | |
Solaris @command{/usr/ucb/sed} rejects usages that exceed a limit of
|
| 19335 | |
about 6000 bytes for the internal representation of commands.
|
| 19336 | |
|
| 19337 | |
Avoid redundant @samp{;}, as some @command{sed} implementations, such as
|
| 19338 | |
NetBSD 1.4.2's, incorrectly try to interpret the second
|
| 19339 | |
@samp{;} as a command:
|
| 19340 | |
|
| 19341 | |
@example
|
| 19342 | |
$ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
|
| 19343 | |
sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
|
| 19344 | |
@end example
|
| 19345 | |
|
| 19346 | |
Some @command{sed} implementations have a buffer limited to 4000 bytes,
|
| 19347 | |
and this limits the size of input lines, output lines, and internal
|
| 19348 | |
buffers that can be processed portably. Likewise,
|
| 19349 | |
not all @command{sed} implementations can handle embedded @code{NUL} or
|
| 19350 | |
a missing trailing newline.
|
| 19351 | |
|
| 19352 | |
Remember that ranges within a bracket expression of a regular expression
|
| 19353 | |
are only well-defined in the @samp{C} (or @samp{POSIX}) locale.
|
| 19354 | |
Meanwhile, support for character classes like @samp{[[:upper:]]} is not
|
| 19355 | |
yet universal, so if you cannot guarantee the setting of @env{LC_ALL},
|
| 19356 | |
it is better to spell out a range @samp{[ABCDEFGHIJKLMNOPQRSTUVWXYZ]}
|
| 19357 | |
than to rely on @samp{[A-Z]}.
|
| 19358 | |
|
| 19359 | |
Additionally, Posix states that regular expressions are only
|
| 19360 | |
well-defined on characters. Unfortunately, there exist platforms such
|
| 19361 | |
as MacOS X 10.5 where not all 8-bit byte values are valid characters,
|
| 19362 | |
even though that platform has a single-byte @samp{C} locale. And Posix
|
| 19363 | |
allows the existence of a multi-byte @samp{C} locale, although that does
|
| 19364 | |
not yet appear to be a common implementation. At any rate, it means
|
| 19365 | |
that not all bytes will be matched by the regular expression @samp{.}:
|
| 19366 | |
|
| 19367 | |
@example
|
| 19368 | |
$ @kbd{printf '\200\n' | LC_ALL=C sed -n /./p | wc -l}
|
| 19369 | |
0
|
| 19370 | |
$ @kbd{printf '\200\n' | LC_ALL=en_US.ISO8859-1 sed -n /./p | wc -l}
|
| 19371 | |
1
|
| 19372 | |
@end example
|
| 19373 | |
|
| 19374 | |
Portable @command{sed} regular expressions should use @samp{\} only to escape
|
| 19375 | |
characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
|
| 19376 | |
alternation, @samp{\|}, is common but Posix does not require its
|
| 19377 | |
support, so it should be avoided in portable scripts. Solaris
|
| 19378 | |
@command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
|
| 19379 | |
deletes only lines that contain the literal string @samp{a|b}.
|
| 19380 | |
Similarly, @samp{\+} and @samp{\?} should be avoided.
|
| 19381 | |
|
| 19382 | |
Anchors (@samp{^} and @samp{$}) inside groups are not portable.
|
| 19383 | |
|
| 19384 | |
Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
|
| 19385 | |
quite portable to current hosts, but was not supported by some ancient
|
| 19386 | |
@command{sed} implementations like SVR3.
|
| 19387 | |
|
| 19388 | |
Some @command{sed} implementations, e.g., Solaris, restrict the special
|
| 19389 | |
role of the asterisk @samp{*} to one-character regular expressions and
|
| 19390 | |
back-references, and the special role of interval expressions
|
| 19391 | |
@samp{\@{@var{m}\@}}, @samp{\@{@var{m},\@}}, or @samp{\@{@var{m},@var{n}\@}}
|
| 19392 | |
to one-character regular expressions. This may lead to unexpected behavior:
|
| 19393 | |
|
| 19394 | |
@example
|
| 19395 | |
$ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
|
| 19396 | |
x2x4
|
| 19397 | |
$ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
|
| 19398 | |
x
|
| 19399 | |
@end example
|
| 19400 | |
|
| 19401 | |
The @option{-e} option is mostly portable.
|
| 19402 | |
However, its argument
|
| 19403 | |
cannot start with @samp{a}, @samp{c}, or @samp{i},
|
| 19404 | |
as this runs afoul of a Tru64 5.1 bug.
|
| 19405 | |
Also, its argument cannot be empty, as this fails on AIX 5.3.
|
| 19406 | |
Some people prefer to use @samp{-e}:
|
| 19407 | |
|
| 19408 | |
@example
|
| 19409 | |
sed -e '@var{command-1}' \
|
| 19410 | |
-e '@var{command-2}'
|
| 19411 | |
@end example
|
| 19412 | |
|
| 19413 | |
@noindent
|
| 19414 | |
as opposed to the equivalent:
|
| 19415 | |
|
| 19416 | |
@example
|
| 19417 | |
sed '
|
| 19418 | |
@var{command-1}
|
| 19419 | |
@var{command-2}
|
| 19420 | |
'
|
| 19421 | |
@end example
|
| 19422 | |
|
| 19423 | |
@noindent
|
| 19424 | |
The following usage is sometimes equivalent:
|
| 19425 | |
|
| 19426 | |
@example
|
| 19427 | |
sed '@var{command-1};@var{command-2}'
|
| 19428 | |
@end example
|
| 19429 | |
|
| 19430 | |
but Posix says that this use of a semicolon has undefined effect if
|
| 19431 | |
@var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
|
| 19432 | |
@samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
|
| 19433 | |
should use semicolon only with simple scripts that do not use these
|
| 19434 | |
verbs.
|
| 19435 | |
|
| 19436 | |
Posix up to the 2008 revision requires the argument of the @option{-e}
|
| 19437 | |
option to be a syntactically complete script. GNU @command{sed} allows
|
| 19438 | |
to pass multiple script fragments, each as argument of a separate
|
| 19439 | |
@option{-e} option, that are then combined, with newlines between the
|
| 19440 | |
fragments, and a future Posix revision may allow this as well. This
|
| 19441 | |
approach is not portable with script fragments ending in backslash; for
|
| 19442 | |
example, the @command{sed} programs on Solaris 10, HP-UX 11, and AIX
|
| 19443 | |
don't allow splitting in this case:
|
| 19444 | |
|
| 19445 | |
@example
|
| 19446 | |
$ @kbd{echo a | sed -n -e 'i\}
|
| 19447 | |
@kbd{0'}
|
| 19448 | |
0
|
| 19449 | |
$ @kbd{echo a | sed -n -e 'i\' -e 0}
|
| 19450 | |
Unrecognized command: 0
|
| 19451 | |
@end example
|
| 19452 | |
|
| 19453 | |
@noindent
|
| 19454 | |
In practice, however, this technique of joining fragments
|
| 19455 | |
through @option{-e} works for multiple @command{sed} functions within
|
| 19456 | |
@samp{@{} and @samp{@}}, even if that is not specified by Posix:
|
| 19457 | |
|
| 19458 | |
@example
|
| 19459 | |
@c The quote around the closing brace silences interactive zsh.
|
| 19460 | |
$ @kbd{echo a | sed -n -e '/a/@{' -e s/a/b/ -e p -e '@}'}
|
| 19461 | |
b
|
| 19462 | |
@end example
|
| 19463 | |
|
| 19464 | |
Commands inside @{ @} brackets are further restricted. Posix 2008 says that
|
| 19465 | |
they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
|
| 19466 | |
each command must be followed immediately by a newline, without any
|
| 19467 | |
intervening blanks or semicolons. The closing bracket must be alone on
|
| 19468 | |
a line, other than white space preceding or following it. However, a
|
| 19469 | |
future version of Posix may standardize the use of addresses within brackets.
|
| 19470 | |
|
| 19471 | |
Contrary to yet another urban legend, you may portably use @samp{&} in
|
| 19472 | |
the replacement part of the @code{s} command to mean ``what was
|
| 19473 | |
matched''. All descendants of Unix version 7 @command{sed}
|
| 19474 | |
(at least; we
|
| 19475 | |
don't have first hand experience with older @command{sed} implementations) have
|
| 19476 | |
supported it.
|
| 19477 | |
|
| 19478 | |
Posix requires that you must not have any white space between
|
| 19479 | |
@samp{!} and the following command. It is OK to have blanks between
|
| 19480 | |
the address and the @samp{!}. For instance, on Solaris:
|
| 19481 | |
|
| 19482 | |
@example
|
| 19483 | |
$ @kbd{echo "foo" | sed -n '/bar/ ! p'}
|
| 19484 | |
@error{}Unrecognized command: /bar/ ! p
|
| 19485 | |
$ @kbd{echo "foo" | sed -n '/bar/! p'}
|
| 19486 | |
@error{}Unrecognized command: /bar/! p
|
| 19487 | |
$ @kbd{echo "foo" | sed -n '/bar/ !p'}
|
| 19488 | |
foo
|
| 19489 | |
@end example
|
| 19490 | |
|
| 19491 | |
Posix also says that you should not combine @samp{!} and @samp{;}. If
|
| 19492 | |
you use @samp{!}, it is best to put it on a command that is delimited by
|
| 19493 | |
newlines rather than @samp{;}.
|
| 19494 | |
|
| 19495 | |
Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
|
| 19496 | |
@samp{w} commands be followed by exactly one space before their argument.
|
| 19497 | |
On the other hand, no white space is allowed between @samp{:} and the
|
| 19498 | |
subsequent label name.
|
| 19499 | |
|
| 19500 | |
If a sed script is specified on the command line and ends in an
|
| 19501 | |
@samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
|
| 19502 | |
should be followed by a newline. Otherwise some @command{sed}
|
| 19503 | |
implementations (e.g., OpenBSD 3.9) do not append a newline to the
|
| 19504 | |
inserted text.
|
| 19505 | |
|
| 19506 | |
Many @command{sed} implementations (e.g., MacOS X 10.4,
|
| 19507 | |
OpenBSD 3.9, Solaris 10
|
| 19508 | |
@command{/usr/ucb/sed}) strip leading white space from the text of
|
| 19509 | |
@samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
|
| 19510 | |
work around this incompatibility with Posix:
|
| 19511 | |
|
| 19512 | |
@example
|
| 19513 | |
$ @kbd{echo flushleft | sed 'a\}
|
| 19514 | |
> @kbd{ indented}
|
| 19515 | |
> @kbd{'}
|
| 19516 | |
flushleft
|
| 19517 | |
indented
|
| 19518 | |
$ @kbd{echo foo | sed 'a\}
|
| 19519 | |
> @kbd{\ indented}
|
| 19520 | |
> @kbd{'}
|
| 19521 | |
flushleft
|
| 19522 | |
indented
|
| 19523 | |
@end example
|
| 19524 | |
|
| 19525 | |
Posix requires that with an empty regular expression, the last non-empty
|
| 19526 | |
regular expression from either an address specification or substitution
|
| 19527 | |
command is applied. However, busybox 1.6.1 complains when using a
|
| 19528 | |
substitution command with a replacement containing a back-reference to
|
| 19529 | |
an empty regular expression; the workaround is repeating the regular
|
| 19530 | |
expression.
|
| 19531 | |
|
| 19532 | |
@example
|
| 19533 | |
$ @kbd{echo abc | busybox sed '/a\(b\)c/ s//\1/'}
|
| 19534 | |
sed: No previous regexp.
|
| 19535 | |
$ @kbd{echo abc | busybox sed '/a\(b\)c/ s/a\(b\)c/\1/'}
|
| 19536 | |
b
|
| 19537 | |
@end example
|
| 19538 | |
|
| 19539 | |
|
| 19540 | |
@item @command{sed} (@samp{t})
|
| 19541 | |
@c ---------------------------
|
| 19542 | |
@prindex @command{sed} (@samp{t})
|
| 19543 | |
Some old systems have @command{sed} that ``forget'' to reset their
|
| 19544 | |
@samp{t} flag when starting a new cycle. For instance on MIPS
|
| 19545 | |
RISC/OS, and on IRIX 5.3, if you run the following @command{sed}
|
| 19546 | |
script (the line numbers are not actual part of the texts):
|
| 19547 | |
|
| 19548 | |
@example
|
| 19549 | |
s/keep me/kept/g # a
|
| 19550 | |
t end # b
|
| 19551 | |
s/.*/deleted/g # c
|
| 19552 | |
:end # d
|
| 19553 | |
@end example
|
| 19554 | |
|
| 19555 | |
@noindent
|
| 19556 | |
on
|
| 19557 | |
|
| 19558 | |
@example
|
| 19559 | |
delete me # 1
|
| 19560 | |
delete me # 2
|
| 19561 | |
keep me # 3
|
| 19562 | |
delete me # 4
|
| 19563 | |
@end example
|
| 19564 | |
|
| 19565 | |
@noindent
|
| 19566 | |
you get
|
| 19567 | |
|
| 19568 | |
@example
|
| 19569 | |
deleted
|
| 19570 | |
delete me
|
| 19571 | |
kept
|
| 19572 | |
deleted
|
| 19573 | |
@end example
|
| 19574 | |
|
| 19575 | |
@noindent
|
| 19576 | |
instead of
|
| 19577 | |
|
| 19578 | |
@example
|
| 19579 | |
deleted
|
| 19580 | |
deleted
|
| 19581 | |
kept
|
| 19582 | |
deleted
|
| 19583 | |
@end example
|
| 19584 | |
|
| 19585 | |
Why? When processing line 1, (c) matches, therefore sets the @samp{t}
|
| 19586 | |
flag, and the output is produced. When processing
|
| 19587 | |
line 2, the @samp{t} flag is still set (this is the bug). Command (a)
|
| 19588 | |
fails to match, but @command{sed} is not supposed to clear the @samp{t}
|
| 19589 | |
flag when a substitution fails. Command (b) sees that the flag is set,
|
| 19590 | |
therefore it clears it, and jumps to (d), hence you get @samp{delete me}
|
| 19591 | |
instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
|
| 19592 | |
(a) matches, so the flag is set, hence (b) clears the flags and jumps.
|
| 19593 | |
Finally, since the flag is clear, line 4 is processed properly.
|
| 19594 | |
|
| 19595 | |
There are two things one should remember about @samp{t} in @command{sed}.
|
| 19596 | |
Firstly, always remember that @samp{t} jumps if @emph{some} substitution
|
| 19597 | |
succeeded, not only the immediately preceding substitution. Therefore,
|
| 19598 | |
always use a fake @samp{t clear} followed by a @samp{:clear} on the next
|
| 19599 | |
line, to reset the @samp{t} flag where needed.
|
| 19600 | |
|
| 19601 | |
Secondly, you cannot rely on @command{sed} to clear the flag at each new
|
| 19602 | |
cycle.
|
| 19603 | |
|
| 19604 | |
One portable implementation of the script above is:
|
| 19605 | |
|
| 19606 | |
@example
|
| 19607 | |
t clear
|
| 19608 | |
:clear
|
| 19609 | |
s/keep me/kept/g
|
| 19610 | |
t end
|
| 19611 | |
s/.*/deleted/g
|
| 19612 | |
:end
|
| 19613 | |
@end example
|
| 19614 | |
|
| 19615 | |
@item @command{sleep}
|
| 19616 | |
@c ------------------
|
| 19617 | |
@prindex @command{sleep}
|
| 19618 | |
Using @command{sleep} is generally portable. However, remember that
|
| 19619 | |
adding a @command{sleep} to work around timestamp issues, with a minimum
|
| 19620 | |
granularity of one second, doesn't scale well for parallel builds on
|
| 19621 | |
modern machines with sub-second process completion.
|
| 19622 | |
|
| 19623 | |
@item @command{sort}
|
| 19624 | |
@c -----------------
|
| 19625 | |
@prindex @command{sort}
|
| 19626 | |
Remember that sort order is influenced by the current locale. Inside
|
| 19627 | |
@file{configure}, the C locale is in effect, but in Makefile snippets,
|
| 19628 | |
you may need to specify @code{LC_ALL=C sort}.
|
| 19629 | |
|
| 19630 | |
@item @command{tar}
|
| 19631 | |
@c ----------------
|
| 19632 | |
@prindex @command{tar}
|
| 19633 | |
There are multiple file formats for @command{tar}; if you use Automake,
|
| 19634 | |
the macro @code{AM_INIT_AUTOMAKE} has some options controlling which
|
| 19635 | |
level of portability to use.
|
| 19636 | |
|
| 19637 | |
@anchor{touch}
|
| 19638 | |
@item @command{touch}
|
| 19639 | |
@c ------------------
|
| 19640 | |
@prindex @command{touch}
|
| 19641 | |
@cindex timestamp resolution
|
| 19642 | |
If you specify the desired timestamp (e.g., with the @option{-r}
|
| 19643 | |
option), older @command{touch} implementations use the @code{utime} or
|
| 19644 | |
@code{utimes} system call, which can result in the same kind of
|
| 19645 | |
timestamp truncation problems that @samp{cp -p} has.
|
| 19646 | |
|
| 19647 | |
On ancient BSD systems, @command{touch} or any command that
|
| 19648 | |
results in an empty file does not update the timestamps, so use a
|
| 19649 | |
command like @command{echo} as a workaround.
|
| 19650 | |
Also,
|
| 19651 | |
GNU @command{touch} 3.16r (and presumably all before that)
|
| 19652 | |
fails to work on SunOS 4.1.3 when the empty file is on an
|
| 19653 | |
NFS-mounted 4.2 volume.
|
| 19654 | |
However, these problems are no longer of practical concern.
|
| 19655 | |
|
| 19656 | |
@item @command{tr}
|
| 19657 | |
@c ---------------
|
| 19658 | |
@prindex @command{tr}
|
| 19659 | |
@cindex carriage return, deleting
|
| 19660 | |
@cindex newline, deleting
|
| 19661 | |
@cindex deleting carriage return
|
| 19662 | |
Not all versions of @command{tr} handle all backslash character escapes.
|
| 19663 | |
For example, Solaris 10 @command{/usr/ucb/tr} falls over, even though
|
| 19664 | |
Solaris contains more modern @command{tr} in other locations.
|
| 19665 | |
Using octal escapes is more portable for carriage returns, since
|
| 19666 | |
@samp{\015} is the same for both ASCII and EBCDIC, and since use of
|
| 19667 | |
literal carriage returns in scripts causes a number of other problems.
|
| 19668 | |
But for other characters, like newline, using octal escapes ties the
|
| 19669 | |
operation to ASCII, so it is better to use literal characters.
|
| 19670 | |
|
| 19671 | |
@example
|
| 19672 | |
$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\n' ; echo}
|
| 19673 | |
moo
|
| 19674 | |
light
|
| 19675 | |
$ @kbd{@{ echo moon; echo light; @} | /usr/bin/tr -d '\n' ; echo}
|
| 19676 | |
moonlight
|
| 19677 | |
$ @kbd{@{ echo moon; echo light; @} | /usr/ucb/tr -d '\012' ; echo}
|
| 19678 | |
moonlight
|
| 19679 | |
$ @kbd{nl='}
|
| 19680 | |
@kbd{'; @{ echo moon; echo light; @} | /usr/ucb/tr -d "$nl" ; echo}
|
| 19681 | |
moonlight
|
| 19682 | |
@end example
|
| 19683 | |
|
| 19684 | |
Not all versions of @command{tr} recognize direct ranges of characters: at
|
| 19685 | |
least Solaris @command{/usr/bin/tr} still fails to do so. But you can
|
| 19686 | |
use @command{/usr/xpg4/bin/tr} instead, or add brackets (which in Posix
|
| 19687 | |
transliterate to themselves).
|
| 19688 | |
|
| 19689 | |
@example
|
| 19690 | |
$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr a-z A-Z}
|
| 19691 | |
HAZy FAntAZy
|
| 19692 | |
$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/bin/tr '[a-z]' '[A-Z]'}
|
| 19693 | |
HAZY FANTAZY
|
| 19694 | |
$ @kbd{echo "Hazy Fantazy" | LC_ALL=C /usr/xpg4/bin/tr a-z A-Z}
|
| 19695 | |
HAZY FANTAZY
|
| 19696 | |
@end example
|
| 19697 | |
|
| 19698 | |
When providing two arguments, be sure the second string is at least as
|
| 19699 | |
long as the first.
|
| 19700 | |
|
| 19701 | |
@example
|
| 19702 | |
$ @kbd{echo abc | /usr/xpg4/bin/tr bc d}
|
| 19703 | |
adc
|
| 19704 | |
$ @kbd{echo abc | coreutils/tr bc d}
|
| 19705 | |
add
|
| 19706 | |
@end example
|
| 19707 | |
|
| 19708 | |
Posix requires @command{tr} to operate on binary files. But at least
|
| 19709 | |
Solaris @command{/usr/ucb/tr} and @command{/usr/bin/tr} silently discard
|
| 19710 | |
@code{NUL} in the input prior to doing any translation. When using
|
| 19711 | |
@command{tr} to process a binary file that may contain @code{NUL} bytes,
|
| 19712 | |
it is necessary to use @command{/usr/xpg4/bin/tr} instead, or
|
| 19713 | |
@command{/usr/xpg6/bin/tr} if that is available.
|
| 19714 | |
|
| 19715 | |
@example
|
| 19716 | |
$ @kbd{printf 'a\0b' | /usr/ucb/tr x x | od -An -tx1}
|
| 19717 | |
61 62
|
| 19718 | |
$ @kbd{printf 'a\0b' | /usr/bin/tr x x | od -An -tx1}
|
| 19719 | |
61 62
|
| 19720 | |
$ @kbd{printf 'a\0b' | /usr/xpg4/bin/tr x x | od -An -tx1}
|
| 19721 | |
61 00 62
|
| 19722 | |
@end example
|
| 19723 | |
|
| 19724 | |
Solaris @command{/usr/ucb/tr} additionally fails to handle @samp{\0} as the
|
| 19725 | |
octal escape for @code{NUL}.
|
| 19726 | |
|
| 19727 | |
@example
|
| 19728 | |
$ @kbd{printf 'abc' | /usr/ucb/tr 'bc' '\0d' | od -An -tx1}
|
| 19729 | |
61 62 63
|
| 19730 | |
$ @kbd{printf 'abc' | /usr/bin/tr 'bc' '\0d' | od -An -tx1}
|
| 19731 | |
61 00 64
|
| 19732 | |
$ @kbd{printf 'abc' | /usr/xpg4/bin/tr 'bc' '\0d' | od -An -tx1}
|
| 19733 | |
61 00 64
|
| 19734 | |
@end example
|
| 19735 | |
|
| 19736 | |
@end table
|
| 19737 | |
|
| 19738 | |
|
| 19739 | |
@node Portable Make
|
| 19740 | |
@chapter Portable Make Programming
|
| 19741 | |
@prindex @command{make}
|
| 19742 | |
@cindex Limitations of @command{make}
|
| 19743 | |
|
| 19744 | |
Writing portable makefiles is an art. Since a makefile's commands are
|
| 19745 | |
executed by the shell, you must consider the shell portability issues
|
| 19746 | |
already mentioned. However, other issues are specific to @command{make}
|
| 19747 | |
itself.
|
| 19748 | |
|
| 19749 | |
@menu
|
| 19750 | |
* $< in Ordinary Make Rules:: $< in ordinary rules
|
| 19751 | |
* Failure in Make Rules:: Failing portably in rules
|
| 19752 | |
* Special Chars in Names:: Special Characters in Macro Names
|
| 19753 | |
* Backslash-Newline-Empty:: Empty lines after backslash-newline
|
| 19754 | |
* Backslash-Newline Comments:: Spanning comments across line boundaries
|
| 19755 | |
* Long Lines in Makefiles:: Line length limitations
|
| 19756 | |
* Macros and Submakes:: @code{make macro=value} and submakes
|
| 19757 | |
* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
|
| 19758 | |
* The Make Macro SHELL:: @code{$(SHELL)} portability issues
|
| 19759 | |
* Parallel Make:: Parallel @command{make} quirks
|
| 19760 | |
* Comments in Make Rules:: Other problems with Make comments
|
| 19761 | |
* Newlines in Make Rules:: Using literal newlines in rules
|
| 19762 | |
* Comments in Make Macros:: Other problems with Make comments in macros
|
| 19763 | |
* Trailing whitespace in Make Macros:: Macro substitution problems
|
| 19764 | |
* Command-line Macros and whitespace:: Whitespace trimming of values
|
| 19765 | |
* obj/ and Make:: Don't name a subdirectory @file{obj}
|
| 19766 | |
* make -k Status:: Exit status of @samp{make -k}
|
| 19767 | |
* VPATH and Make:: @code{VPATH} woes
|
| 19768 | |
* Single Suffix Rules:: Single suffix rules and separated dependencies
|
| 19769 | |
* Timestamps and Make:: Subsecond timestamp resolution
|
| 19770 | |
@end menu
|
| 19771 | |
|
| 19772 | |
@node $< in Ordinary Make Rules
|
| 19773 | |
@section @code{$<} in Ordinary Make Rules
|
| 19774 | |
|
| 19775 | |
Posix says that the @samp{$<} construct in makefiles can be
|
| 19776 | |
used only in inference rules and in the @samp{.DEFAULT} rule; its
|
| 19777 | |
meaning in ordinary rules is unspecified. Solaris @command{make}
|
| 19778 | |
for instance replaces it with the empty string. OpenBSD (3.0 and
|
| 19779 | |
later) @command{make} diagnoses these uses and errors out.
|
| 19780 | |
|
| 19781 | |
@node Failure in Make Rules
|
| 19782 | |
@section Failure in Make Rules
|
| 19783 | |
|
| 19784 | |
Posix 2008 requires that @command{make} must invoke each command with
|
| 19785 | |
the equivalent of a @samp{sh -e -c} subshell, which causes the
|
| 19786 | |
subshell to exit immediately if a subsidiary simple-command fails,
|
| 19787 | |
although not all @command{make} implementations have historically
|
| 19788 | |
followed this rule. For
|
| 19789 | |
example, the command @samp{touch T; rm -f U} may attempt to
|
| 19790 | |
remove @file{U} even if the @command{touch} fails, although this is not
|
| 19791 | |
permitted with Posix make. One way to work around failures in simple
|
| 19792 | |
commands is to reword them so that they always succeed, e.g., @samp{touch
|
| 19793 | |
T || :; rm -f U}.
|
| 19794 | |
However, even this approach can run into common bugs in BSD
|
| 19795 | |
implementations of the @option{-e} option of @command{sh} and
|
| 19796 | |
@command{set} (@pxref{set, , Limitations of Shell Builtins}), so if you
|
| 19797 | |
are worried
|
| 19798 | |
about porting to buggy BSD shells it may be simpler to migrate
|
| 19799 | |
complicated @command{make} actions into separate scripts.
|
| 19800 | |
|
| 19801 | |
@node Special Chars in Names
|
| 19802 | |
@section Special Characters in Make Macro Names
|
| 19803 | |
|
| 19804 | |
Posix limits macro names to nonempty strings containing only
|
| 19805 | |
ASCII letters and digits, @samp{.}, and @samp{_}. Many
|
| 19806 | |
@command{make} implementations allow a wider variety of characters, but
|
| 19807 | |
portable makefiles should avoid them. It is portable to start a name
|
| 19808 | |
with a special character, e.g., @samp{$(.FOO)}.
|
| 19809 | |
|
| 19810 | |
Some ancient @command{make} implementations don't support leading
|
| 19811 | |
underscores in macro names. An example is NEWS-OS 4.2R.
|
| 19812 | |
|
| 19813 | |
@example
|
| 19814 | |
$ @kbd{cat Makefile}
|
| 19815 | |
_am_include = #
|
| 19816 | |
_am_quote =
|
| 19817 | |
all:; @@echo this is test
|
| 19818 | |
$ @kbd{make}
|
| 19819 | |
Make: Must be a separator on rules line 2. Stop.
|
| 19820 | |
$ @kbd{cat Makefile2}
|
| 19821 | |
am_include = #
|
| 19822 | |
am_quote =
|
| 19823 | |
all:; @@echo this is test
|
| 19824 | |
$ @kbd{make -f Makefile2}
|
| 19825 | |
this is test
|
| 19826 | |
@end example
|
| 19827 | |
|
| 19828 | |
@noindent
|
| 19829 | |
However, this problem is no longer of practical concern.
|
| 19830 | |
|
| 19831 | |
@node Backslash-Newline-Empty
|
| 19832 | |
@section Backslash-Newline Before Empty Lines
|
| 19833 | |
|
| 19834 | |
A bug in Bash 2.03 can cause problems if a Make rule contains a
|
| 19835 | |
backslash-newline followed by line that expands to nothing.
|
| 19836 | |
For example, on Solaris 8:
|
| 19837 | |
|
| 19838 | |
@example
|
| 19839 | |
SHELL = /bin/bash
|
| 19840 | |
EMPTY =
|
| 19841 | |
foo:
|
| 19842 | |
touch foo \
|
| 19843 | |
$(EMPTY)
|
| 19844 | |
@end example
|
| 19845 | |
|
| 19846 | |
@noindent
|
| 19847 | |
executes
|
| 19848 | |
|
| 19849 | |
@example
|
| 19850 | |
/bin/bash -c 'touch foo \
|
| 19851 | |
'
|
| 19852 | |
@end example
|
| 19853 | |
|
| 19854 | |
@noindent
|
| 19855 | |
which fails with a syntax error, due to the Bash bug. To avoid this
|
| 19856 | |
problem, avoid nullable macros in the last line of a multiline command.
|
| 19857 | |
|
| 19858 | |
@c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
|
| 19859 | |
@c but another hppa hpux 10.20 didn't have it. Bob Proulx
|
| 19860 | |
@c <bob@proulx.com> thinks it was in hpux 8.0 too.
|
| 19861 | |
On some versions of HP-UX, @command{make} reads multiple newlines
|
| 19862 | |
following a backslash, continuing to the next non-empty line. For
|
| 19863 | |
example,
|
| 19864 | |
|
| 19865 | |
@example
|
| 19866 | |
FOO = one \
|
| 19867 | |
|
| 19868 | |
BAR = two
|
| 19869 | |
|
| 19870 | |
test:
|
| 19871 | |
: FOO is "$(FOO)"
|
| 19872 | |
: BAR is "$(BAR)"
|
| 19873 | |
@end example
|
| 19874 | |
|
| 19875 | |
@noindent
|
| 19876 | |
shows @code{FOO} equal to @code{one BAR = two}. Other implementations
|
| 19877 | |
sensibly let a backslash continue only to the immediately following
|
| 19878 | |
line.
|
| 19879 | |
|
| 19880 | |
@node Backslash-Newline Comments
|
| 19881 | |
@section Backslash-Newline in Make Comments
|
| 19882 | |
|
| 19883 | |
According to Posix, Make comments start with @code{#}
|
| 19884 | |
and continue until an unescaped newline is reached.
|
| 19885 | |
|
| 19886 | |
@example
|
| 19887 | |
$ @kbd{cat Makefile}
|
| 19888 | |
# A = foo \
|
| 19889 | |
bar \
|
| 19890 | |
baz
|
| 19891 | |
|
| 19892 | |
all:
|
| 19893 | |
@@echo ok
|
| 19894 | |
$ @kbd{make} # GNU make
|
| 19895 | |
ok
|
| 19896 | |
@end example
|
| 19897 | |
|
| 19898 | |
@noindent
|
| 19899 | |
However this is not always the case. Some implementations
|
| 19900 | |
discard everything from @code{#} through the end of the line, ignoring any
|
| 19901 | |
trailing backslash.
|
| 19902 | |
|
| 19903 | |
@example
|
| 19904 | |
$ @kbd{pmake} # BSD make
|
| 19905 | |
"Makefile", line 3: Need an operator
|
| 19906 | |
Fatal errors encountered -- cannot continue
|
| 19907 | |
@end example
|
| 19908 | |
|
| 19909 | |
@noindent
|
| 19910 | |
Therefore, if you want to comment out a multi-line definition, prefix each
|
| 19911 | |
line with @code{#}, not only the first.
|
| 19912 | |
|
| 19913 | |
@example
|
| 19914 | |
# A = foo \
|
| 19915 | |
# bar \
|
| 19916 | |
# baz
|
| 19917 | |
@end example
|
| 19918 | |
|
| 19919 | |
@node Long Lines in Makefiles
|
| 19920 | |
@section Long Lines in Makefiles
|
| 19921 | |
|
| 19922 | |
Tru64 5.1's @command{make} has been reported to crash when given a
|
| 19923 | |
makefile with lines longer than around 20 kB. Earlier versions are
|
| 19924 | |
reported to exit with @code{Line too long} diagnostics.
|
| 19925 | |
|
| 19926 | |
@node Macros and Submakes
|
| 19927 | |
@section @code{make macro=value} and Submakes
|
| 19928 | |
|
| 19929 | |
A command-line variable definition such as @code{foo=bar} overrides any
|
| 19930 | |
definition of @code{foo} in a makefile. Some @command{make}
|
| 19931 | |
implementations (such as GNU @command{make}) propagate this
|
| 19932 | |
override to subsidiary invocations of @command{make}. Some other
|
| 19933 | |
implementations do not pass the substitution along to submakes.
|
| 19934 | |
|
| 19935 | |
@example
|
| 19936 | |
$ @kbd{cat Makefile}
|
| 19937 | |
foo = foo
|
| 19938 | |
one:
|
| 19939 | |
@@echo $(foo)
|
| 19940 | |
$(MAKE) two
|
| 19941 | |
two:
|
| 19942 | |
@@echo $(foo)
|
| 19943 | |
$ @kbd{make foo=bar} # GNU make 3.79.1
|
| 19944 | |
bar
|
| 19945 | |
make two
|
| 19946 | |
make[1]: Entering directory `/home/adl'
|
| 19947 | |
bar
|
| 19948 | |
make[1]: Leaving directory `/home/adl'
|
| 19949 | |
$ @kbd{pmake foo=bar} # BSD make
|
| 19950 | |
bar
|
| 19951 | |
pmake two
|
| 19952 | |
foo
|
| 19953 | |
@end example
|
| 19954 | |
|
| 19955 | |
You have a few possibilities if you do want the @code{foo=bar} override
|
| 19956 | |
to propagate to submakes. One is to use the @option{-e}
|
| 19957 | |
option, which causes all environment variables to have precedence over
|
| 19958 | |
the makefile macro definitions, and declare foo as an environment
|
| 19959 | |
variable:
|
| 19960 | |
|
| 19961 | |
@example
|
| 19962 | |
$ @kbd{env foo=bar make -e}
|
| 19963 | |
@end example
|
| 19964 | |
|
| 19965 | |
The @option{-e} option is propagated to submakes automatically,
|
| 19966 | |
and since the environment is inherited between @command{make}
|
| 19967 | |
invocations, the @code{foo} macro is overridden in
|
| 19968 | |
submakes as expected.
|
| 19969 | |
|
| 19970 | |
This syntax (@code{foo=bar make -e}) is portable only when used
|
| 19971 | |
outside of a makefile, for instance from a script or from the
|
| 19972 | |
command line. When run inside a @command{make} rule, GNU
|
| 19973 | |
@command{make} 3.80 and prior versions forget to propagate the
|
| 19974 | |
@option{-e} option to submakes.
|
| 19975 | |
|
| 19976 | |
Moreover, using @option{-e} could have unexpected side effects if your
|
| 19977 | |
environment contains some other macros usually defined by the
|
| 19978 | |
makefile. (See also the note about @code{make -e} and @code{SHELL}
|
| 19979 | |
below.)
|
| 19980 | |
|
| 19981 | |
If you can foresee all macros that a user might want to override, then
|
| 19982 | |
you can propagate them to submakes manually, from your makefile:
|
| 19983 | |
|
| 19984 | |
@example
|
| 19985 | |
foo = foo
|
| 19986 | |
one:
|
| 19987 | |
@@echo $(foo)
|
| 19988 | |
$(MAKE) foo=$(foo) two
|
| 19989 | |
two:
|
| 19990 | |
@@echo $(foo)
|
| 19991 | |
@end example
|
| 19992 | |
|
| 19993 | |
Another way to propagate a variable to submakes in a portable way is to
|
| 19994 | |
expand an extra variable in every invocation of @samp{$(MAKE)} within
|
| 19995 | |
your makefile:
|
| 19996 | |
|
| 19997 | |
@example
|
| 19998 | |
foo = foo
|
| 19999 | |
one:
|
| 20000 | |
@@echo $(foo)
|
| 20001 | |
$(MAKE) $(SUBMAKEFLAGS) two
|
| 20002 | |
two:
|
| 20003 | |
@@echo $(foo)
|
| 20004 | |
@end example
|
| 20005 | |
|
| 20006 | |
Users must be aware that this technique is in use to take advantage of
|
| 20007 | |
it, e.g.@: with @code{make foo=bar SUBMAKEFLAGS='foo=bar'}, but it
|
| 20008 | |
allows any macro to be overridden. Makefiles generated by
|
| 20009 | |
@command{automake} use this technique, expanding @code{$(AM_MAKEFLAGS)}
|
| 20010 | |
on the command lines of submakes (@pxref{Subdirectories, , Automake,
|
| 20011 | |
automake, GNU Automake}).
|
| 20012 | |
|
| 20013 | |
@node The Make Macro MAKEFLAGS
|
| 20014 | |
@section The Make Macro MAKEFLAGS
|
| 20015 | |
@cindex @code{MAKEFLAGS} and @command{make}
|
| 20016 | |
@cindex @command{make} and @code{MAKEFLAGS}
|
| 20017 | |
|
| 20018 | |
Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
|
| 20019 | |
current and recursive invocations of make, but allows implementations
|
| 20020 | |
several formats for the variable. It is tricky to parse
|
| 20021 | |
@code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
|
| 20022 | |
or @option{-k} for continued execution are in effect. For example, you
|
| 20023 | |
cannot assume that the first space-separated word in @code{$MAKEFLAGS}
|
| 20024 | |
contains single-letter options, since in the Cygwin version of
|
| 20025 | |
GNU @command{make} it is either @option{--unix} or
|
| 20026 | |
@option{--win32} with the second word containing single-letter options.
|
| 20027 | |
|
| 20028 | |
@example
|
| 20029 | |
$ @kbd{cat Makefile}
|
| 20030 | |
all:
|
| 20031 | |
@@echo MAKEFLAGS = $(MAKEFLAGS)
|
| 20032 | |
$ @kbd{make}
|
| 20033 | |
MAKEFLAGS = --unix
|
| 20034 | |
$ @kbd{make -k}
|
| 20035 | |
MAKEFLAGS = --unix -k
|
| 20036 | |
@end example
|
| 20037 | |
|
| 20038 | |
@node The Make Macro SHELL
|
| 20039 | |
@section The Make Macro @code{SHELL}
|
| 20040 | |
@cindex @code{SHELL} and @command{make}
|
| 20041 | |
@cindex @command{make} and @code{SHELL}
|
| 20042 | |
|
| 20043 | |
Posix-compliant @command{make} internally uses the @code{$(SHELL)}
|
| 20044 | |
macro to spawn shell processes and execute Make rules. This
|
| 20045 | |
is a builtin macro supplied by @command{make}, but it can be modified
|
| 20046 | |
by a makefile or by a command-line argument.
|
| 20047 | |
|
| 20048 | |
Not all @command{make} implementations define this @code{SHELL} macro.
|
| 20049 | |
Tru64
|
| 20050 | |
@command{make} is an example; this implementation always uses
|
| 20051 | |
@code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
|
| 20052 | |
your makefiles. If you use Autoconf, do
|
| 20053 | |
|
| 20054 | |
@example
|
| 20055 | |
SHELL = @@SHELL@@
|
| 20056 | |
@end example
|
| 20057 | |
|
| 20058 | |
@noindent
|
| 20059 | |
If you use Automake, this is done for you.
|
| 20060 | |
|
| 20061 | |
Do not force @code{SHELL = /bin/sh} because that is not correct
|
| 20062 | |
everywhere. Remember, @file{/bin/sh} is not Posix compliant on many
|
| 20063 | |
systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64.
|
| 20064 | |
Additionally, DJGPP lacks @code{/bin/sh}, and when its
|
| 20065 | |
GNU @command{make} port sees such a setting it enters a
|
| 20066 | |
special emulation mode where features like pipes and redirections are
|
| 20067 | |
emulated on top of DOS's @command{command.com}. Unfortunately this
|
| 20068 | |
emulation is incomplete; for instance it does not handle command
|
| 20069 | |
substitutions. Using @code{@@SHELL@@} means that your makefile will
|
| 20070 | |
benefit from the same improved shell, such as @command{bash} or
|
| 20071 | |
@command{ksh}, that was discovered during @command{configure}, so that
|
| 20072 | |
you aren't fighting two different sets of shell bugs between the two
|
| 20073 | |
contexts.
|
| 20074 | |
|
| 20075 | |
Posix-compliant @command{make} should never acquire the value of
|
| 20076 | |
$(SHELL) from the environment, even when @code{make -e} is used
|
| 20077 | |
(otherwise, think about what would happen to your rules if
|
| 20078 | |
@code{SHELL=/bin/tcsh}).
|
| 20079 | |
|
| 20080 | |
However not all @command{make} implementations have this exception.
|
| 20081 | |
For instance it's not surprising that Tru64 @command{make} doesn't
|
| 20082 | |
protect @code{SHELL}, since it doesn't use it.
|
| 20083 | |
|
| 20084 | |
@example
|
| 20085 | |
$ @kbd{cat Makefile}
|
| 20086 | |
SHELL = /bin/sh
|
| 20087 | |
FOO = foo
|
| 20088 | |
all:
|
| 20089 | |
@@echo $(SHELL)
|
| 20090 | |
@@echo $(FOO)
|
| 20091 | |
$ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
|
| 20092 | |
/bin/tcsh
|
| 20093 | |
bar
|
| 20094 | |
$ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
|
| 20095 | |
/bin/sh
|
| 20096 | |
bar
|
| 20097 | |
@end example
|
| 20098 | |
|
| 20099 | |
Conversely, @command{make} is not supposed to export any changes to the
|
| 20100 | |
macro @code{SHELL} to child processes. Again, many implementations
|
| 20101 | |
break this rule:
|
| 20102 | |
|
| 20103 | |
@example
|
| 20104 | |
$ @kbd{cat Makefile}
|
| 20105 | |
all:
|
| 20106 | |
@@echo $(SHELL)
|
| 20107 | |
@@printenv SHELL
|
| 20108 | |
$ @kbd{env SHELL=sh make -e SHELL=/bin/ksh} # BSD Make, GNU make 3.80
|
| 20109 | |
/bin/ksh
|
| 20110 | |
/bin/ksh
|
| 20111 | |
$ @kbd{env SHELL=sh gmake -e SHELL=/bin/ksh} # GNU make 3.81
|
| 20112 | |
/bin/ksh
|
| 20113 | |
sh
|
| 20114 | |
@end example
|
| 20115 | |
|
| 20116 | |
@node Parallel Make
|
| 20117 | |
@section Parallel Make
|
| 20118 | |
@cindex Parallel @command{make}
|
| 20119 | |
|
| 20120 | |
Support for parallel execution in @command{make} implementation varies.
|
| 20121 | |
Generally, using GNU make is your best bet.
|
| 20122 | |
|
| 20123 | |
When NetBSD or FreeBSD @command{make} are run in parallel mode, they will
|
| 20124 | |
reuse the same shell for multiple commands within one recipe. This can
|
| 20125 | |
have various unexpected consequences. For example, changes of directories
|
| 20126 | |
or variables persist between recipes, so that:
|
| 20127 | |
|
| 20128 | |
@example
|
| 20129 | |
all:
|
| 20130 | |
@@var=value; cd /; pwd; echo $$var; echo $$$$
|
| 20131 | |
@@pwd; echo $$var; echo $$$$
|
| 20132 | |
@end example
|
| 20133 | |
|
| 20134 | |
@noindent
|
| 20135 | |
may output the following with @code{make -j1}, at least on NetBSD up to
|
| 20136 | |
5.1 and FreeBSD up to 8.2:
|
| 20137 | |
|
| 20138 | |
@example
|
| 20139 | |
/
|
| 20140 | |
value
|
| 20141 | |
32235
|
| 20142 | |
/
|
| 20143 | |
value
|
| 20144 | |
32235
|
| 20145 | |
@end example
|
| 20146 | |
|
| 20147 | |
@noindent
|
| 20148 | |
while without @option{-j1}, or with @option{-B}, the output looks less
|
| 20149 | |
surprising:
|
| 20150 | |
|
| 20151 | |
@example
|
| 20152 | |
/
|
| 20153 | |
value
|
| 20154 | |
32238
|
| 20155 | |
/tmp
|
| 20156 | |
|
| 20157 | |
32239
|
| 20158 | |
@end example
|
| 20159 | |
|
| 20160 | |
@noindent
|
| 20161 | |
Another consequence is that, if one command in a recipe uses @code{exit 0}
|
| 20162 | |
to indicate a successful exit, the shell will be gone and the remaining
|
| 20163 | |
commands of this recipe will not be executed.
|
| 20164 | |
|
| 20165 | |
The BSD @command{make} implementations, when run in parallel mode,
|
| 20166 | |
will also pass the @command{Makefile} recipes to the shell through
|
| 20167 | |
its standard input, thus making it unusable from the recipes:
|
| 20168 | |
|
| 20169 | |
@example
|
| 20170 | |
$ @kbd{cat Makefile}
|
| 20171 | |
read:
|
| 20172 | |
@@read line; echo LINE: $$line
|
| 20173 | |
@c $$ @c restore font-lock
|
| 20174 | |
$ @kbd{echo foo | make read}
|
| 20175 | |
LINE: foo
|
| 20176 | |
$ @kbd{echo foo | make -j1 read} # NetBSD 5.1 and FreeBSD 8.2
|
| 20177 | |
LINE:
|
| 20178 | |
@end example
|
| 20179 | |
|
| 20180 | |
@noindent
|
| 20181 | |
Moreover, when FreeBSD @command{make} (up at least to 8.2) is run in
|
| 20182 | |
parallel mode, it implements the @code{@@} and @code{-} ``recipe
|
| 20183 | |
modifiers'' by dynamically modifying the active shell flags. This
|
| 20184 | |
behavior has the effects of potentially clobbering the exit status
|
| 20185 | |
of recipes silenced with the @code{@@} modifier if they also unset
|
| 20186 | |
the @option{errexit} shell flag, and of mangling the output in
|
| 20187 | |
unexpected ways:
|
| 20188 | |
|
| 20189 | |
@example
|
| 20190 | |
$ @kbd{cat Makefile}
|
| 20191 | |
a:
|
| 20192 | |
@@echo $$-; set +e; false
|
| 20193 | |
b:
|
| 20194 | |
-echo $$-; false; echo set -
|
| 20195 | |
$ @kbd{make a; echo status: $?}
|
| 20196 | |
ehBc
|
| 20197 | |
*** Error code 1
|
| 20198 | |
status: 1
|
| 20199 | |
$ @kbd{make -j1 a; echo status: $?}
|
| 20200 | |
ehB
|
| 20201 | |
status: 0
|
| 20202 | |
$ @kbd{make b}
|
| 20203 | |
echo $-; echo set -
|
| 20204 | |
hBc
|
| 20205 | |
set -
|
| 20206 | |
$ @kbd{make -j1 b}
|
| 20207 | |
echo $-; echo hvB
|
| 20208 | |
@end example
|
| 20209 | |
|
| 20210 | |
@noindent
|
| 20211 | |
You can avoid all these issues by using the @option{-B} option to enable
|
| 20212 | |
compatibility semantics. However, that will effectively also disable
|
| 20213 | |
all parallelism as that will cause prerequisites to be updated in the
|
| 20214 | |
order they are listed in a rule.
|
| 20215 | |
|
| 20216 | |
Some make implementations (among them, FreeBSD @command{make}, NetBSD
|
| 20217 | |
@command{make}, and Solaris @command{dmake}), when invoked with a
|
| 20218 | |
@option{-j@var{N}} option, connect the standard output and standard
|
| 20219 | |
error of all their child processes to pipes or temporary regular
|
| 20220 | |
files. This can lead to subtly different semantics in the behavior
|
| 20221 | |
of the spawned processes. For example, even if the @command{make}
|
| 20222 | |
standard output is connected to a tty, the recipe command will not be:
|
| 20223 | |
|
| 20224 | |
@example
|
| 20225 | |
$ @kbd{cat Makefile}
|
| 20226 | |
all:
|
| 20227 | |
@@test -t 1 && echo "Is a tty" || echo "Is not a tty"
|
| 20228 | |
$ @kbd{make -j 2} # FreeBSD 8.2 make
|
| 20229 | |
Is not a tty
|
| 20230 | |
$ @kbd{make -j 2} # NetBSD 5.1 make
|
| 20231 | |
--- all ---
|
| 20232 | |
Is not a tty
|
| 20233 | |
$ @kbd{dmake -j 2} # Solaris 10 dmake
|
| 20234 | |
@var{hostname} --> 1 job
|
| 20235 | |
@var{hostname} --> Job output
|
| 20236 | |
Is not a tty
|
| 20237 | |
@end example
|
| 20238 | |
|
| 20239 | |
@noindent
|
| 20240 | |
On the other hand:
|
| 20241 | |
|
| 20242 | |
@example
|
| 20243 | |
$ @kbd{make -j 2} # GNU make, Heirloom make
|
| 20244 | |
Is a tty
|
| 20245 | |
@end example
|
| 20246 | |
|
| 20247 | |
@noindent
|
| 20248 | |
The above examples also show additional status output produced in parallel
|
| 20249 | |
mode for targets being updated by Solaris @command{dmake} and NetBSD
|
| 20250 | |
@command{make} (but @emph{not} by FreeBSD @command{make}).
|
| 20251 | |
|
| 20252 | |
Furthermore, parallel runs of those @command{make} implementations will
|
| 20253 | |
route standard error from commands that they spawn into their own
|
| 20254 | |
standard output, and may remove leading whitespace from output lines.
|
| 20255 | |
|
| 20256 | |
|
| 20257 | |
@node Comments in Make Rules
|
| 20258 | |
@section Comments in Make Rules
|
| 20259 | |
@cindex Comments in @file{Makefile} rules
|
| 20260 | |
@cindex @file{Makefile} rules and comments
|
| 20261 | |
|
| 20262 | |
Never put comments in a rule.
|
| 20263 | |
|
| 20264 | |
Some @command{make} treat anything starting with a tab as a command for
|
| 20265 | |
the current rule, even if the tab is immediately followed by a @code{#}.
|
| 20266 | |
The @command{make} from Tru64 Unix V5.1 is one of them. The following
|
| 20267 | |
makefile runs @code{# foo} through the shell.
|
| 20268 | |
|
| 20269 | |
@example
|
| 20270 | |
all:
|
| 20271 | |
# foo
|
| 20272 | |
@end example
|
| 20273 | |
|
| 20274 | |
As a workaround, you can use the @command{:} no-op command with a string
|
| 20275 | |
argument that gets ignored:
|
| 20276 | |
|
| 20277 | |
@example
|
| 20278 | |
all:
|
| 20279 | |
: "foo"
|
| 20280 | |
@end example
|
| 20281 | |
|
| 20282 | |
Conversely, if you want to use the @samp{#} character in some command,
|
| 20283 | |
you can only do so by expanding it inside a rule (@pxref{Comments in
|
| 20284 | |
Make Macros}). So for example, if @samp{COMMENT_CHAR} is substituted by
|
| 20285 | |
@command{config.status} as @samp{#}, then the following substitutes
|
| 20286 | |
@samp{@@COMMENT_CHAR@@} in a generated header:
|
| 20287 | |
|
| 20288 | |
@example
|
| 20289 | |
foo.h: foo.h.in
|
| 20290 | |
sed -e 's|@@''COMMENT_CHAR''@@|@@COMMENT_CHAR@@|g' \
|
| 20291 | |
$(srcdir)/foo.h.in > $@@
|
| 20292 | |
@end example
|
| 20293 | |
|
| 20294 | |
The funny shell quoting avoids a substitution at @command{config.status}
|
| 20295 | |
run time of the left-hand side of the @command{sed} @samp{s} command.
|
| 20296 | |
|
| 20297 | |
@node Newlines in Make Rules
|
| 20298 | |
@section Newlines in Make Rules
|
| 20299 | |
@cindex Newlines in @file{Makefile} rules
|
| 20300 | |
@cindex @file{Makefile} rules and newlines
|
| 20301 | |
|
| 20302 | |
In shell scripts, newlines can be used inside string literals. But in
|
| 20303 | |
the shell statements of @file{Makefile} rules, this is not possible:
|
| 20304 | |
A newline not preceded by a backslash is a separator between shell
|
| 20305 | |
statements. Whereas a newline that is preceded by a backslash becomes
|
| 20306 | |
part of the shell statement according to POSIX, but gets replaced,
|
| 20307 | |
together with the backslash that precedes it, by a space in GNU
|
| 20308 | |
@command{make} 3.80 and older. So, how can a newline be used in a string
|
| 20309 | |
literal?
|
| 20310 | |
|
| 20311 | |
The trick is to set up a shell variable that contains a newline:
|
| 20312 | |
|
| 20313 | |
@example
|
| 20314 | |
nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"
|
| 20315 | |
@end example
|
| 20316 | |
|
| 20317 | |
For example, in order to create a multiline @samp{sed} expression that
|
| 20318 | |
inserts a blank line after every line of a file, this code can be used:
|
| 20319 | |
|
| 20320 | |
@example
|
| 20321 | |
nlinit=`echo 'nl="'; echo '"'`; eval "$$nlinit"; \
|
| 20322 | |
sed -e "s/\$$/\\$$@{nl@}/" < input > output
|
| 20323 | |
@end example
|
| 20324 | |
|
| 20325 | |
@node Comments in Make Macros
|
| 20326 | |
@section Comments in Make Macros
|
| 20327 | |
@cindex Comments in @file{Makefile} macros
|
| 20328 | |
@cindex @file{Makefile} macros and comments
|
| 20329 | |
|
| 20330 | |
Avoid putting comments in macro values as far as possible. Posix
|
| 20331 | |
specifies that the text starting from the @samp{#} sign until the end of
|
| 20332 | |
the line is to be ignored, which has the unfortunate effect of
|
| 20333 | |
disallowing them even within quotes. Thus, the following might lead to
|
| 20334 | |
a syntax error at compile time:
|
| 20335 | |
|
| 20336 | |
@example
|
| 20337 | |
CPPFLAGS = "-DCOMMENT_CHAR='#'"
|
| 20338 | |
@end example
|
| 20339 | |
|
| 20340 | |
@noindent
|
| 20341 | |
as @samp{CPPFLAGS} may be expanded to @samp{"-DCOMMENT_CHAR='}.
|
| 20342 | |
|
| 20343 | |
Most @command{make} implementations disregard this and treat single and
|
| 20344 | |
double quotes specially here. Also, GNU @command{make} lets you put
|
| 20345 | |
@samp{#} into a macro value by escaping it with a backslash, i.e.,
|
| 20346 | |
@samp{\#}. However, neither of these usages are portable.
|
| 20347 | |
@xref{Comments in Make Rules}, for a portable alternative.
|
| 20348 | |
|
| 20349 | |
Even without quoting involved, comments can have surprising effects,
|
| 20350 | |
because the whitespace before them is part of the variable value:
|
| 20351 | |
|
| 20352 | |
@example
|
| 20353 | |
foo = bar # trailing comment
|
| 20354 | |
print: ; @@echo "$(foo)."
|
| 20355 | |
@end example
|
| 20356 | |
|
| 20357 | |
@noindent
|
| 20358 | |
prints @samp{bar .}, which is usually not intended, and can expose
|
| 20359 | |
@command{make} bugs as described below.
|
| 20360 | |
|
| 20361 | |
@node Trailing whitespace in Make Macros
|
| 20362 | |
@section Trailing whitespace in Make Macros
|
| 20363 | |
@cindex whitespace in @file{Makefile} macros
|
| 20364 | |
@cindex @file{Makefile} macros and whitespace
|
| 20365 | |
|
| 20366 | |
GNU @command{make} 3.80 mistreats trailing whitespace in macro
|
| 20367 | |
substitutions and appends another spurious suffix:
|
| 20368 | |
|
| 20369 | |
@example
|
| 20370 | |
empty =
|
| 20371 | |
foo = bar $(empty)
|
| 20372 | |
print: ; @@echo $(foo:=.test)
|
| 20373 | |
@end example
|
| 20374 | |
|
| 20375 | |
@noindent
|
| 20376 | |
prints @samp{bar.test .test}.
|
| 20377 | |
|
| 20378 | |
BSD and Solaris @command{make} implementations do not honor trailing
|
| 20379 | |
whitespace in macro definitions as Posix requires:
|
| 20380 | |
|
| 20381 | |
@example
|
| 20382 | |
foo = bar # Note the space after "bar".
|
| 20383 | |
print: ; @@echo $(foo)t
|
| 20384 | |
@end example
|
| 20385 | |
|
| 20386 | |
@noindent
|
| 20387 | |
prints @samp{bart} instead of @samp{bar t}. To work around this, you
|
| 20388 | |
can use a helper macro as in the previous example.
|
| 20389 | |
|
| 20390 | |
|
| 20391 | |
@node Command-line Macros and whitespace
|
| 20392 | |
@section Command-line Macros and whitespace
|
| 20393 | |
@cindex whitespace in command-line macros
|
| 20394 | |
@cindex command-line, macros set on
|
| 20395 | |
@cindex environment, macros set from
|
| 20396 | |
|
| 20397 | |
Some @command{make} implementations may strip trailing whitespace off
|
| 20398 | |
of macros set on the command line in addition to leading whitespace.
|
| 20399 | |
Further, some may strip leading whitespace off of macros set from
|
| 20400 | |
environment variables:
|
| 20401 | |
|
| 20402 | |
@example
|
| 20403 | |
$ @kbd{echo 'print: ; @@echo "x$(foo)x$(bar)x"' |
|
| 20404 | |
foo=' f f ' make -f - bar=' b b '}
|
| 20405 | |
x f f xb b x # AIX, BSD, GNU make
|
| 20406 | |
xf f xb b x # HP-UX, IRIX, Tru64/OSF make
|
| 20407 | |
x f f xb bx # Solaris make
|
| 20408 | |
@end example
|
| 20409 | |
|
| 20410 | |
|
| 20411 | |
@node obj/ and Make
|
| 20412 | |
@section The @file{obj/} Subdirectory and Make
|
| 20413 | |
@cindex @file{obj/}, subdirectory
|
| 20414 | |
@cindex BSD @command{make} and @file{obj/}
|
| 20415 | |
|
| 20416 | |
Never name one of your subdirectories @file{obj/} if you don't like
|
| 20417 | |
surprises.
|
| 20418 | |
|
| 20419 | |
If an @file{obj/} directory exists, BSD @command{make} enters it
|
| 20420 | |
before reading the makefile. Hence the makefile in the
|
| 20421 | |
current directory is not read.
|
| 20422 | |
|
| 20423 | |
@example
|
| 20424 | |
$ @kbd{cat Makefile}
|
| 20425 | |
all:
|
| 20426 | |
echo Hello
|
| 20427 | |
$ @kbd{cat obj/Makefile}
|
| 20428 | |
all:
|
| 20429 | |
echo World
|
| 20430 | |
$ @kbd{make} # GNU make
|
| 20431 | |
echo Hello
|
| 20432 | |
Hello
|
| 20433 | |
$ @kbd{pmake} # BSD make
|
| 20434 | |
echo World
|
| 20435 | |
World
|
| 20436 | |
@end example
|
| 20437 | |
|
| 20438 | |
@node make -k Status
|
| 20439 | |
@section Exit Status of @code{make -k}
|
| 20440 | |
@cindex @code{make -k}
|
| 20441 | |
|
| 20442 | |
Do not rely on the exit status of @code{make -k}. Some implementations
|
| 20443 | |
reflect whether they encountered an error in their exit status; other
|
| 20444 | |
implementations always succeed.
|
| 20445 | |
|
| 20446 | |
@example
|
| 20447 | |
$ @kbd{cat Makefile}
|
| 20448 | |
all:
|
| 20449 | |
false
|
| 20450 | |
$ @kbd{make -k; echo exit status: $?} # GNU make
|
| 20451 | |
false
|
| 20452 | |
make: *** [all] Error 1
|
| 20453 | |
exit status: 2
|
| 20454 | |
$ @kbd{pmake -k; echo exit status: $?} # BSD make
|
| 20455 | |
false
|
| 20456 | |
*** Error code 1 (continuing)
|
| 20457 | |
exit status: 0
|
| 20458 | |
@end example
|
| 20459 | |
|
| 20460 | |
@node VPATH and Make
|
| 20461 | |
@section @code{VPATH} and Make
|
| 20462 | |
@cindex @code{VPATH}
|
| 20463 | |
|
| 20464 | |
Posix does not specify the semantics of @code{VPATH}. Typically,
|
| 20465 | |
@command{make} supports @code{VPATH}, but its implementation is not
|
| 20466 | |
consistent.
|
| 20467 | |
|
| 20468 | |
Autoconf and Automake support makefiles whose usages of @code{VPATH} are
|
| 20469 | |
portable to recent-enough popular implementations of @command{make}, but
|
| 20470 | |
to keep the resulting makefiles portable, a package's makefile
|
| 20471 | |
prototypes must take the following issues into account. These issues
|
| 20472 | |
are complicated and are often poorly understood, and installers who use
|
| 20473 | |
@code{VPATH} should expect to find many bugs in this area. If you use
|
| 20474 | |
@code{VPATH}, the simplest way to avoid these portability bugs is to
|
| 20475 | |
stick with GNU @command{make}, since it is the most
|
| 20476 | |
commonly-used @command{make} among Autoconf users.
|
| 20477 | |
|
| 20478 | |
Here are some known issues with some @code{VPATH}
|
| 20479 | |
implementations.
|
| 20480 | |
|
| 20481 | |
@menu
|
| 20482 | |
* Variables listed in VPATH:: @code{VPATH} must be literal on ancient hosts
|
| 20483 | |
* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
|
| 20484 | |
* $< in Explicit Rules:: @code{$<} does not work in ordinary rules
|
| 20485 | |
* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
|
| 20486 | |
* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
|
| 20487 | |
* Make Target Lookup:: More details about @code{VPATH} lookup
|
| 20488 | |
@end menu
|
| 20489 | |
|
| 20490 | |
@node Variables listed in VPATH
|
| 20491 | |
@subsection Variables listed in @code{VPATH}
|
| 20492 | |
@cindex @code{VPATH} and variables
|
| 20493 | |
@cindex variables and @code{VPATH}
|
| 20494 | |
|
| 20495 | |
Do not set @code{VPATH} to the value of another variable, for example
|
| 20496 | |
@samp{VPATH = $(srcdir)}, because some ancient versions of
|
| 20497 | |
@command{make} do not do variable substitutions on the value of
|
| 20498 | |
@code{VPATH}. For example, use this
|
| 20499 | |
|
| 20500 | |
@example
|
| 20501 | |
srcdir = @@srcdir@@
|
| 20502 | |
VPATH = @@srcdir@@
|
| 20503 | |
@end example
|
| 20504 | |
|
| 20505 | |
@noindent
|
| 20506 | |
rather than @samp{VPATH = $(srcdir)}. Note that with GNU
|
| 20507 | |
Automake, there is no need to set this yourself.
|
| 20508 | |
|
| 20509 | |
@node VPATH and Double-colon
|
| 20510 | |
@subsection @code{VPATH} and Double-colon Rules
|
| 20511 | |
@cindex @code{VPATH} and double-colon rules
|
| 20512 | |
@cindex double-colon rules and @code{VPATH}
|
| 20513 | |
|
| 20514 | |
With ancient versions of Sun @command{make},
|
| 20515 | |
any assignment to @code{VPATH} causes @command{make} to execute only
|
| 20516 | |
the first set of double-colon rules.
|
| 20517 | |
However, this problem is no longer of practical concern.
|
| 20518 | |
|
| 20519 | |
@node $< in Explicit Rules
|
| 20520 | |
@subsection @code{$<} Not Supported in Explicit Rules
|
| 20521 | |
@cindex explicit rules, @code{$<}, and @code{VPATH}
|
| 20522 | |
@cindex @code{$<}, explicit rules, and @code{VPATH}
|
| 20523 | |
@cindex @code{VPATH}, explicit rules, and @code{$<}
|
| 20524 | |
|
| 20525 | |
Using @code{$<} in explicit rules is not portable.
|
| 20526 | |
The prerequisite file must be named explicitly in the rule. If you want
|
| 20527 | |
to find the prerequisite via a @code{VPATH} search, you have to code the
|
| 20528 | |
whole thing manually. @xref{Build Directories}.
|
| 20529 | |
|
| 20530 | |
@node Automatic Rule Rewriting
|
| 20531 | |
@subsection Automatic Rule Rewriting
|
| 20532 | |
@cindex @code{VPATH} and automatic rule rewriting
|
| 20533 | |
@cindex automatic rule rewriting and @code{VPATH}
|
| 20534 | |
|
| 20535 | |
Some @command{make} implementations, such as Solaris and Tru64,
|
| 20536 | |
search for prerequisites in @code{VPATH} and
|
| 20537 | |
then rewrite each occurrence as a plain word in the rule.
|
| 20538 | |
For instance:
|
| 20539 | |
|
| 20540 | |
@example
|
| 20541 | |
# This isn't portable to GNU make.
|
| 20542 | |
VPATH = ../pkg/src
|
| 20543 | |
f.c: if.c
|
| 20544 | |
cp if.c f.c
|
| 20545 | |
@end example
|
| 20546 | |
|
| 20547 | |
@noindent
|
| 20548 | |
executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
|
| 20549 | |
found in @file{../pkg/src}.
|
| 20550 | |
|
| 20551 | |
However, this rule leads to real problems in practice. For example, if
|
| 20552 | |
the source directory contains an ordinary file named @file{test} that is
|
| 20553 | |
used in a dependency, Solaris @command{make} rewrites commands like
|
| 20554 | |
@samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
|
| 20555 | |
@dots{}}, which is typically undesirable. In fact, @command{make} is
|
| 20556 | |
completely unaware of shell syntax used in the rules, so the VPATH
|
| 20557 | |
rewrite can potentially apply to @emph{any} whitespace-separated word
|
| 20558 | |
in a rule, including shell variables, functions, and keywords.
|
| 20559 | |
|
| 20560 | |
@example
|
| 20561 | |
$ @kbd{mkdir build}
|
| 20562 | |
$ @kbd{cd build}
|
| 20563 | |
$ @kbd{cat > Makefile <<'END'}
|
| 20564 | |
VPATH = ..
|
| 20565 | |
all: arg func for echo
|
| 20566 | |
func () @{ for arg in "$$@@"; do echo $$arg; done; @}; \
|
| 20567 | |
func "hello world"
|
| 20568 | |
END
|
| 20569 | |
$ @kbd{touch ../arg ../func ../for ../echo}
|
| 20570 | |
$ @kbd{make}
|
| 20571 | |
../func () @{ ../for ../arg in "$@@"; do ../echo $arg; done; @}; \
|
| 20572 | |
../func "hello world"
|
| 20573 | |
sh: syntax error at line 1: `do' unexpected
|
| 20574 | |
*** Error code 2
|
| 20575 | |
@end example
|
| 20576 | |
|
| 20577 | |
@noindent
|
| 20578 | |
To avoid this problem, portable makefiles should never mention a source
|
| 20579 | |
file or dependency whose name is that of a shell keyword like @file{for}
|
| 20580 | |
or @file{until}, a shell command like @command{cat} or @command{gcc} or
|
| 20581 | |
@command{test}, or a shell function or variable used in the corresponding
|
| 20582 | |
@command{Makefile} recipe.
|
| 20583 | |
|
| 20584 | |
Because of these problems GNU @command{make} and many other @command{make}
|
| 20585 | |
implementations do not rewrite commands, so portable makefiles should
|
| 20586 | |
search @code{VPATH} manually. It is tempting to write this:
|
| 20587 | |
|
| 20588 | |
@smallexample
|
| 20589 | |
# This isn't portable to Solaris make.
|
| 20590 | |
VPATH = ../pkg/src
|
| 20591 | |
f.c: if.c
|
| 20592 | |
cp `test -f if.c || echo $(VPATH)/`if.c f.c
|
| 20593 | |
@end smallexample
|
| 20594 | |
|
| 20595 | |
@noindent
|
| 20596 | |
However, the ``prerequisite rewriting'' still applies here. So if
|
| 20597 | |
@file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
|
| 20598 | |
execute
|
| 20599 | |
|
| 20600 | |
@smallexample
|
| 20601 | |
cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
|
| 20602 | |
@end smallexample
|
| 20603 | |
|
| 20604 | |
@noindent
|
| 20605 | |
which reduces to
|
| 20606 | |
|
| 20607 | |
@example
|
| 20608 | |
cp if.c f.c
|
| 20609 | |
@end example
|
| 20610 | |
|
| 20611 | |
@noindent
|
| 20612 | |
and thus fails. Oops.
|
| 20613 | |
|
| 20614 | |
A simple workaround, and good practice anyway, is to use @samp{$?} and
|
| 20615 | |
@samp{$@@} when possible:
|
| 20616 | |
|
| 20617 | |
@smallexample
|
| 20618 | |
VPATH = ../pkg/src
|
| 20619 | |
f.c: if.c
|
| 20620 | |
cp $? $@@
|
| 20621 | |
@end smallexample
|
| 20622 | |
|
| 20623 | |
@noindent
|
| 20624 | |
but this does not generalize well to commands with multiple
|
| 20625 | |
prerequisites. A more general workaround is to rewrite the rule so that
|
| 20626 | |
the prerequisite @file{if.c} never appears as a plain word. For
|
| 20627 | |
example, these three rules would be safe, assuming @file{if.c} is in
|
| 20628 | |
@file{../pkg/src} and the other files are in the working directory:
|
| 20629 | |
|
| 20630 | |
@smallexample
|
| 20631 | |
VPATH = ../pkg/src
|
| 20632 | |
f.c: if.c f1.c
|
| 20633 | |
cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
|
| 20634 | |
g.c: if.c g1.c
|
| 20635 | |
cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
|
| 20636 | |
h.c: if.c h1.c
|
| 20637 | |
cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
|
| 20638 | |
@end smallexample
|
| 20639 | |
|
| 20640 | |
Things get worse when your prerequisites are in a macro.
|
| 20641 | |
|
| 20642 | |
@example
|
| 20643 | |
VPATH = ../pkg/src
|
| 20644 | |
HEADERS = f.h g.h h.h
|
| 20645 | |
install-HEADERS: $(HEADERS)
|
| 20646 | |
for i in $(HEADERS); do \
|
| 20647 | |
$(INSTALL) -m 644 \
|
| 20648 | |
`test -f $$i || echo $(VPATH)/`$$i \
|
| 20649 | |
$(DESTDIR)$(includedir)/$$i; \
|
| 20650 | |
@c $$ restore font-lock
|
| 20651 | |
done
|
| 20652 | |
@end example
|
| 20653 | |
|
| 20654 | |
The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
|
| 20655 | |
i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
|
| 20656 | |
where @code{f.h} and @code{g.h} are plain words and are hence
|
| 20657 | |
subject to @code{VPATH} adjustments.
|
| 20658 | |
|
| 20659 | |
If the three files are in @file{../pkg/src}, the rule is run as:
|
| 20660 | |
|
| 20661 | |
@example
|
| 20662 | |
for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
|
| 20663 | |
install -m 644 \
|
| 20664 | |
`test -f $i || echo ../pkg/src/`$i \
|
| 20665 | |
/usr/local/include/$i; \
|
| 20666 | |
done
|
| 20667 | |
@end example
|
| 20668 | |
|
| 20669 | |
where the two first @command{install} calls fail. For instance,
|
| 20670 | |
consider the @code{f.h} installation:
|
| 20671 | |
|
| 20672 | |
@example
|
| 20673 | |
install -m 644 \
|
| 20674 | |
`test -f ../pkg/src/f.h || \
|
| 20675 | |
echo ../pkg/src/ \
|
| 20676 | |
`../pkg/src/f.h \
|
| 20677 | |
/usr/local/include/../pkg/src/f.h;
|
| 20678 | |
@end example
|
| 20679 | |
|
| 20680 | |
@noindent
|
| 20681 | |
It reduces to:
|
| 20682 | |
|
| 20683 | |
@example
|
| 20684 | |
install -m 644 \
|
| 20685 | |
../pkg/src/f.h \
|
| 20686 | |
/usr/local/include/../pkg/src/f.h;
|
| 20687 | |
@end example
|
| 20688 | |
|
| 20689 | |
Note that the manual @code{VPATH} search did not cause any problems here;
|
| 20690 | |
however this command installs @file{f.h} in an incorrect directory.
|
| 20691 | |
|
| 20692 | |
Trying to quote @code{$(HEADERS)} in some way, as we did for
|
| 20693 | |
@code{foo.c} a few makefiles ago, does not help:
|
| 20694 | |
|
| 20695 | |
@example
|
| 20696 | |
install-HEADERS: $(HEADERS)
|
| 20697 | |
headers='$(HEADERS)'; \
|
| 20698 | |
for i in $$headers; do \
|
| 20699 | |
$(INSTALL) -m 644 \
|
| 20700 | |
`test -f $$i || echo $(VPATH)/`$$i \
|
| 20701 | |
$(DESTDIR)$(includedir)/$$i; \
|
| 20702 | |
done
|
| 20703 | |
@end example
|
| 20704 | |
|
| 20705 | |
Now, @code{headers='$(HEADERS)'} macro-expands to:
|
| 20706 | |
|
| 20707 | |
@example
|
| 20708 | |
headers='f.h g.h h.h'
|
| 20709 | |
@end example
|
| 20710 | |
|
| 20711 | |
@noindent
|
| 20712 | |
but @code{g.h} is still a plain word. (As an aside, the idiom
|
| 20713 | |
@code{headers='$(HEADERS)'; for i in $$headers;} is a good
|
| 20714 | |
idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
|
| 20715 | |
syntax error on @code{for i in;}.)
|
| 20716 | |
|
| 20717 | |
One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
|
| 20718 | |
|
| 20719 | |
@example
|
| 20720 | |
VPATH = ../pkg/src
|
| 20721 | |
HEADERS = f.h g.h h.h
|
| 20722 | |
install-HEADERS: $(HEADERS)
|
| 20723 | |
headers='$(HEADERS)'; \
|
| 20724 | |
for i in $$headers; do \
|
| 20725 | |
i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
|
| 20726 | |
$(INSTALL) -m 644 \
|
| 20727 | |
`test -f $$i || echo $(VPATH)/`$$i \
|
| 20728 | |
$(DESTDIR)$(includedir)/$$i; \
|
| 20729 | |
@c $$ restore font-lock
|
| 20730 | |
done
|
| 20731 | |
@end example
|
| 20732 | |
|
| 20733 | |
Automake does something similar. However the above hack works only if
|
| 20734 | |
the files listed in @code{HEADERS} are in the current directory or a
|
| 20735 | |
subdirectory; they should not be in an enclosing directory. If we had
|
| 20736 | |
@code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
|
| 20737 | |
build with Tru64 @command{make}. The reason is that not only does
|
| 20738 | |
Tru64 @command{make} rewrite dependencies, but it also simplifies
|
| 20739 | |
them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
|
| 20740 | |
@code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
|
| 20741 | |
a leading @file{../pkg/src/} component.
|
| 20742 | |
|
| 20743 | |
The following example makes the behavior of Tru64 @command{make}
|
| 20744 | |
more apparent.
|
| 20745 | |
|
| 20746 | |
@example
|
| 20747 | |
$ @kbd{cat Makefile}
|
| 20748 | |
VPATH = sub
|
| 20749 | |
all: ../foo
|
| 20750 | |
echo ../foo
|
| 20751 | |
$ @kbd{ls}
|
| 20752 | |
Makefile foo
|
| 20753 | |
$ @kbd{make}
|
| 20754 | |
echo foo
|
| 20755 | |
foo
|
| 20756 | |
@end example
|
| 20757 | |
|
| 20758 | |
@noindent
|
| 20759 | |
Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
|
| 20760 | |
@command{make} simplified it as @file{foo}. (Note that the @file{sub/}
|
| 20761 | |
directory does not even exist, this just means that the simplification
|
| 20762 | |
occurred before the file was checked for.)
|
| 20763 | |
|
| 20764 | |
For the record here is how SunOS 4 @command{make} behaves on this
|
| 20765 | |
example.
|
| 20766 | |
|
| 20767 | |
@smallexample
|
| 20768 | |
$ @kbd{make}
|
| 20769 | |
make: Fatal error: Don't know how to make target `../foo'
|
| 20770 | |
$ @kbd{mkdir sub}
|
| 20771 | |
$ @kbd{make}
|
| 20772 | |
echo sub/../foo
|
| 20773 | |
sub/../foo
|
| 20774 | |
@end smallexample
|
| 20775 | |
|
| 20776 | |
|
| 20777 | |
@node Tru64 Directory Magic
|
| 20778 | |
@subsection Tru64 @command{make} Creates Prerequisite Directories Magically
|
| 20779 | |
@cindex @code{VPATH} and prerequisite directories
|
| 20780 | |
@cindex prerequisite directories and @code{VPATH}
|
| 20781 | |
|
| 20782 | |
When a prerequisite is a subdirectory of @code{VPATH}, Tru64
|
| 20783 | |
@command{make} creates it in the current directory.
|
| 20784 | |
|
| 20785 | |
@example
|
| 20786 | |
$ @kbd{mkdir -p foo/bar build}
|
| 20787 | |
$ @kbd{cd build}
|
| 20788 | |
$ @kbd{cat >Makefile <<END
|
| 20789 | |
VPATH = ..
|
| 20790 | |
all: foo/bar
|
| 20791 | |
END}
|
| 20792 | |
$ @kbd{make}
|
| 20793 | |
mkdir foo
|
| 20794 | |
mkdir foo/bar
|
| 20795 | |
@end example
|
| 20796 | |
|
| 20797 | |
This can yield unexpected results if a rule uses a manual @code{VPATH}
|
| 20798 | |
search as presented before.
|
| 20799 | |
|
| 20800 | |
@example
|
| 20801 | |
VPATH = ..
|
| 20802 | |
all : foo/bar
|
| 20803 | |
command `test -d foo/bar || echo ../`foo/bar
|
| 20804 | |
@end example
|
| 20805 | |
|
| 20806 | |
The above @command{command} is run on the empty @file{foo/bar}
|
| 20807 | |
directory that was created in the current directory.
|
| 20808 | |
|
| 20809 | |
@node Make Target Lookup
|
| 20810 | |
@subsection Make Target Lookup
|
| 20811 | |
@cindex @code{VPATH}, resolving target pathnames
|
| 20812 | |
|
| 20813 | |
GNU @command{make} uses a complex algorithm to decide when it
|
| 20814 | |
should use files found via a @code{VPATH} search. @xref{Search
|
| 20815 | |
Algorithm, , How Directory Searches are Performed, make, The GNU Make
|
| 20816 | |
Manual}.
|
| 20817 | |
|
| 20818 | |
If a target needs to be rebuilt, GNU @command{make} discards the
|
| 20819 | |
file name found during the @code{VPATH} search for this target, and
|
| 20820 | |
builds the file locally using the file name given in the makefile.
|
| 20821 | |
If a target does not need to be rebuilt, GNU @command{make} uses the
|
| 20822 | |
file name found during the @code{VPATH} search.
|
| 20823 | |
|
| 20824 | |
Other @command{make} implementations, like NetBSD @command{make}, are
|
| 20825 | |
easier to describe: the file name found during the @code{VPATH} search
|
| 20826 | |
is used whether the target needs to be rebuilt or not. Therefore
|
| 20827 | |
new files are created locally, but existing files are updated at their
|
| 20828 | |
@code{VPATH} location.
|
| 20829 | |
|
| 20830 | |
OpenBSD and FreeBSD @command{make}, however,
|
| 20831 | |
never perform a
|
| 20832 | |
@code{VPATH} search for a dependency that has an explicit rule.
|
| 20833 | |
This is extremely annoying.
|
| 20834 | |
|
| 20835 | |
When attempting a @code{VPATH} build for an autoconfiscated package
|
| 20836 | |
(e.g., @code{mkdir build && cd build && ../configure}), this means
|
| 20837 | |
GNU
|
| 20838 | |
@command{make} builds everything locally in the @file{build}
|
| 20839 | |
directory, while BSD @command{make} builds new files locally and
|
| 20840 | |
updates existing files in the source directory.
|
| 20841 | |
|
| 20842 | |
@example
|
| 20843 | |
$ @kbd{cat Makefile}
|
| 20844 | |
VPATH = ..
|
| 20845 | |
all: foo.x bar.x
|
| 20846 | |
foo.x bar.x: newer.x
|
| 20847 | |
@@echo Building $@@
|
| 20848 | |
$ @kbd{touch ../bar.x}
|
| 20849 | |
$ @kbd{touch ../newer.x}
|
| 20850 | |
$ @kbd{make} # GNU make
|
| 20851 | |
Building foo.x
|
| 20852 | |
Building bar.x
|
| 20853 | |
$ @kbd{pmake} # NetBSD make
|
| 20854 | |
Building foo.x
|
| 20855 | |
Building ../bar.x
|
| 20856 | |
$ @kbd{fmake} # FreeBSD make, OpenBSD make
|
| 20857 | |
Building foo.x
|
| 20858 | |
Building bar.x
|
| 20859 | |
$ @kbd{tmake} # Tru64 make
|
| 20860 | |
Building foo.x
|
| 20861 | |
Building bar.x
|
| 20862 | |
$ @kbd{touch ../bar.x}
|
| 20863 | |
$ @kbd{make} # GNU make
|
| 20864 | |
Building foo.x
|
| 20865 | |
$ @kbd{pmake} # NetBSD make
|
| 20866 | |
Building foo.x
|
| 20867 | |
$ @kbd{fmake} # FreeBSD make, OpenBSD make
|
| 20868 | |
Building foo.x
|
| 20869 | |
Building bar.x
|
| 20870 | |
$ @kbd{tmake} # Tru64 make
|
| 20871 | |
Building foo.x
|
| 20872 | |
Building bar.x
|
| 20873 | |
@end example
|
| 20874 | |
|
| 20875 | |
Note how NetBSD @command{make} updates @file{../bar.x} in its
|
| 20876 | |
VPATH location, and how FreeBSD, OpenBSD, and Tru64
|
| 20877 | |
@command{make} always
|
| 20878 | |
update @file{bar.x}, even when @file{../bar.x} is up to date.
|
| 20879 | |
|
| 20880 | |
Another point worth mentioning is that once GNU @command{make} has
|
| 20881 | |
decided to ignore a @code{VPATH} file name (e.g., it ignored
|
| 20882 | |
@file{../bar.x} in the above example) it continues to ignore it when
|
| 20883 | |
the target occurs as a prerequisite of another rule.
|
| 20884 | |
|
| 20885 | |
The following example shows that GNU @command{make} does not look up
|
| 20886 | |
@file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
|
| 20887 | |
because it ignored the @code{VPATH} result of @file{bar.x} while running
|
| 20888 | |
the @code{bar.x: newer.x} rule.
|
| 20889 | |
|
| 20890 | |
@example
|
| 20891 | |
$ @kbd{cat Makefile}
|
| 20892 | |
VPATH = ..
|
| 20893 | |
all: bar.y
|
| 20894 | |
bar.x: newer.x
|
| 20895 | |
@@echo Building $@@
|
| 20896 | |
.SUFFIXES: .x .y
|
| 20897 | |
.x.y:
|
| 20898 | |
cp $< $@@
|
| 20899 | |
$ @kbd{touch ../bar.x}
|
| 20900 | |
$ @kbd{touch ../newer.x}
|
| 20901 | |
$ @kbd{make} # GNU make
|
| 20902 | |
Building bar.x
|
| 20903 | |
cp bar.x bar.y
|
| 20904 | |
cp: cannot stat `bar.x': No such file or directory
|
| 20905 | |
make: *** [bar.y] Error 1
|
| 20906 | |
$ @kbd{pmake} # NetBSD make
|
| 20907 | |
Building ../bar.x
|
| 20908 | |
cp ../bar.x bar.y
|
| 20909 | |
$ @kbd{rm bar.y}
|
| 20910 | |
$ @kbd{fmake} # FreeBSD make, OpenBSD make
|
| 20911 | |
echo Building bar.x
|
| 20912 | |
cp bar.x bar.y
|
| 20913 | |
cp: cannot stat `bar.x': No such file or directory
|
| 20914 | |
*** Error code 1
|
| 20915 | |
$ @kbd{tmake} # Tru64 make
|
| 20916 | |
Building bar.x
|
| 20917 | |
cp: bar.x: No such file or directory
|
| 20918 | |
*** Exit 1
|
| 20919 | |
@end example
|
| 20920 | |
|
| 20921 | |
Note that if you drop away the command from the @code{bar.x: newer.x}
|
| 20922 | |
rule, GNU @command{make} magically starts to work: it
|
| 20923 | |
knows that @code{bar.x} hasn't been updated, therefore it doesn't
|
| 20924 | |
discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
|
| 20925 | |
uses. Tru64 also works, but FreeBSD and OpenBSD
|
| 20926 | |
still don't.
|
| 20927 | |
|
| 20928 | |
@example
|
| 20929 | |
$ @kbd{cat Makefile}
|
| 20930 | |
VPATH = ..
|
| 20931 | |
all: bar.y
|
| 20932 | |
bar.x: newer.x
|
| 20933 | |
.SUFFIXES: .x .y
|
| 20934 | |
.x.y:
|
| 20935 | |
cp $< $@@
|
| 20936 | |
$ @kbd{touch ../bar.x}
|
| 20937 | |
$ @kbd{touch ../newer.x}
|
| 20938 | |
$ @kbd{make} # GNU make
|
| 20939 | |
cp ../bar.x bar.y
|
| 20940 | |
$ @kbd{rm bar.y}
|
| 20941 | |
$ @kbd{pmake} # NetBSD make
|
| 20942 | |
cp ../bar.x bar.y
|
| 20943 | |
$ @kbd{rm bar.y}
|
| 20944 | |
$ @kbd{fmake} # FreeBSD make, OpenBSD make
|
| 20945 | |
cp bar.x bar.y
|
| 20946 | |
cp: cannot stat `bar.x': No such file or directory
|
| 20947 | |
*** Error code 1
|
| 20948 | |
$ @kbd{tmake} # Tru64 make
|
| 20949 | |
cp ../bar.x bar.y
|
| 20950 | |
@end example
|
| 20951 | |
|
| 20952 | |
It seems the sole solution that would please every @command{make}
|
| 20953 | |
implementation is to never rely on @code{VPATH} searches for targets.
|
| 20954 | |
In other words, @code{VPATH} should be reserved to unbuilt sources.
|
| 20955 | |
|
| 20956 | |
|
| 20957 | |
@node Single Suffix Rules
|
| 20958 | |
@section Single Suffix Rules and Separated Dependencies
|
| 20959 | |
@cindex Single Suffix Inference Rule
|
| 20960 | |
@cindex Rule, Single Suffix Inference
|
| 20961 | |
A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
|
| 20962 | |
(@samp{.from.to:}), but which @emph{destination} suffix is empty
|
| 20963 | |
(@samp{.from:}).
|
| 20964 | |
|
| 20965 | |
@cindex Separated Dependencies
|
| 20966 | |
@dfn{Separated dependencies} simply refers to listing the prerequisite
|
| 20967 | |
of a target, without defining a rule. Usually one can list on the one
|
| 20968 | |
hand side, the rules, and on the other hand side, the dependencies.
|
| 20969 | |
|
| 20970 | |
Solaris @command{make} does not support separated dependencies for
|
| 20971 | |
targets defined by single suffix rules:
|
| 20972 | |
|
| 20973 | |
@example
|
| 20974 | |
$ @kbd{cat Makefile}
|
| 20975 | |
.SUFFIXES: .in
|
| 20976 | |
foo: foo.in
|
| 20977 | |
.in:
|
| 20978 | |
cp $< $@@
|
| 20979 | |
$ @kbd{touch foo.in}
|
| 20980 | |
$ @kbd{make}
|
| 20981 | |
$ @kbd{ls}
|
| 20982 | |
Makefile foo.in
|
| 20983 | |
@end example
|
| 20984 | |
|
| 20985 | |
@noindent
|
| 20986 | |
while GNU Make does:
|
| 20987 | |
|
| 20988 | |
@example
|
| 20989 | |
$ @kbd{gmake}
|
| 20990 | |
cp foo.in foo
|
| 20991 | |
$ @kbd{ls}
|
| 20992 | |
Makefile foo foo.in
|
| 20993 | |
@end example
|
| 20994 | |
|
| 20995 | |
Note it works without the @samp{foo: foo.in} dependency.
|
| 20996 | |
|
| 20997 | |
@example
|
| 20998 | |
$ @kbd{cat Makefile}
|
| 20999 | |
.SUFFIXES: .in
|
| 21000 | |
.in:
|
| 21001 | |
cp $< $@@
|
| 21002 | |
$ @kbd{make foo}
|
| 21003 | |
cp foo.in foo
|
| 21004 | |
@end example
|
| 21005 | |
|
| 21006 | |
@noindent
|
| 21007 | |
and it works with double suffix inference rules:
|
| 21008 | |
|
| 21009 | |
@example
|
| 21010 | |
$ @kbd{cat Makefile}
|
| 21011 | |
foo.out: foo.in
|
| 21012 | |
.SUFFIXES: .in .out
|
| 21013 | |
.in.out:
|
| 21014 | |
cp $< $@@
|
| 21015 | |
$ @kbd{make}
|
| 21016 | |
cp foo.in foo.out
|
| 21017 | |
@end example
|
| 21018 | |
|
| 21019 | |
As a result, in such a case, you have to write target rules.
|
| 21020 | |
|
| 21021 | |
@node Timestamps and Make
|
| 21022 | |
@section Timestamp Resolution and Make
|
| 21023 | |
@cindex timestamp resolution
|
| 21024 | |
Traditionally, file timestamps had 1-second resolution, and
|
| 21025 | |
@command{make} used those timestamps to determine whether one file was
|
| 21026 | |
newer than the other. However, many modern file systems have
|
| 21027 | |
timestamps with 1-nanosecond resolution. Some @command{make}
|
| 21028 | |
implementations look at the entire timestamp; others ignore the
|
| 21029 | |
fractional part, which can lead to incorrect results. Normally this
|
| 21030 | |
is not a problem, but in some extreme cases you may need to use tricks
|
| 21031 | |
like @samp{sleep 1} to work around timestamp truncation bugs.
|
| 21032 | |
|
| 21033 | |
Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
|
| 21034 | |
file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual
|
| 21035 | |
Tools}). Hence you should be wary of rules like this:
|
| 21036 | |
|
| 21037 | |
@example
|
| 21038 | |
dest: src
|
| 21039 | |
cp -p src dest
|
| 21040 | |
@end example
|
| 21041 | |
|
| 21042 | |
as @file{dest} often appears to be older than @file{src} after the
|
| 21043 | |
timestamp is truncated, and this can cause @command{make} to do
|
| 21044 | |
needless rework the next time it is invoked. To work around this
|
| 21045 | |
problem, you can use a timestamp file, e.g.:
|
| 21046 | |
|
| 21047 | |
@example
|
| 21048 | |
dest-stamp: src
|
| 21049 | |
cp -p src dest
|
| 21050 | |
date >dest-stamp
|
| 21051 | |
@end example
|
| 21052 | |
|
| 21053 | |
Apart from timestamp resolution, there are also differences in handling
|
| 21054 | |
equal timestamps. HP-UX @command{make} updates targets if it has the
|
| 21055 | |
same time stamp as one of its prerequisites, in violation of Posix rules.
|
| 21056 | |
|
| 21057 | |
This can cause spurious rebuilds for repeated runs of @command{make}.
|
| 21058 | |
This in turn can cause @command{make} to fail if it tries to rebuild
|
| 21059 | |
generated files in a possibly read-only source tree with tools not
|
| 21060 | |
present on the end-user machine. Use GNU @command{make} instead.
|
| 21061 | |
|
| 21062 | |
|
| 21063 | |
|
| 21064 | |
@c ======================================== Portable C and C++ Programming
|
| 21065 | |
|
| 21066 | |
@node Portable C and C++
|
| 21067 | |
@chapter Portable C and C++ Programming
|
| 21068 | |
@cindex Portable C and C++ programming
|
| 21069 | |
|
| 21070 | |
C and C++ programs often use low-level features of the underlying
|
| 21071 | |
system, and therefore are often more difficult to make portable to other
|
| 21072 | |
platforms.
|
| 21073 | |
|
| 21074 | |
Several standards have been developed to help make your programs more
|
| 21075 | |
portable. If you write programs with these standards in mind, you can
|
| 21076 | |
have greater confidence that your programs work on a wide variety
|
| 21077 | |
of systems.
|
| 21078 | |
@ifhtml
|
| 21079 | |
@uref{http://@/gcc.gnu.org/@/onlinedocs/@/gcc/@/Standards.html, Language
|
| 21080 | |
Standards Supported by GCC}
|
| 21081 | |
@end ifhtml
|
| 21082 | |
@ifnothtml
|
| 21083 | |
@xref{Standards, , Language Standards Supported by
|
| 21084 | |
GCC, gcc, Using the GNU Compiler Collection
|
| 21085 | |
(GCC)},
|
| 21086 | |
@end ifnothtml
|
| 21087 | |
for a list of C-related standards. Many programs also assume the
|
| 21088 | |
@uref{http://@/www.opengroup.org/@/susv3, Posix standard}.
|
| 21089 | |
|
| 21090 | |
Some old code is written to be portable to K&R C, which predates any C
|
| 21091 | |
standard. K&R C compilers are no longer of practical interest, though,
|
| 21092 | |
and the rest of section assumes at least C89, the first C standard.
|
| 21093 | |
|
| 21094 | |
Program portability is a huge topic, and this section can only briefly
|
| 21095 | |
introduce common pitfalls. @xref{System Portability, , Portability
|
| 21096 | |
between System Types, standards, The GNU Coding Standards}, for
|
| 21097 | |
more information.
|
| 21098 | |
|
| 21099 | |
@menu
|
| 21100 | |
* Varieties of Unportability:: How to make your programs unportable
|
| 21101 | |
* Integer Overflow:: When integers get too large
|
| 21102 | |
* Preprocessor Arithmetic:: @code{#if} expression problems
|
| 21103 | |
* Null Pointers:: Properties of null pointers
|
| 21104 | |
* Buffer Overruns:: Subscript errors and the like
|
| 21105 | |
* Volatile Objects:: @code{volatile} and signals
|
| 21106 | |
* Floating Point Portability:: Portable floating-point arithmetic
|
| 21107 | |
* Exiting Portably:: Exiting and the exit status
|
| 21108 | |
@end menu
|
| 21109 | |
|
| 21110 | |
@node Varieties of Unportability
|
| 21111 | |
@section Varieties of Unportability
|
| 21112 | |
@cindex portability
|
| 21113 | |
|
| 21114 | |
Autoconf tests and ordinary programs often need to test what is allowed
|
| 21115 | |
on a system, and therefore they may need to deliberately exceed the
|
| 21116 | |
boundaries of what the standards allow, if only to see whether an
|
| 21117 | |
optional feature is present. When you write such a program, you should
|
| 21118 | |
keep in mind the difference between constraints, unspecified behavior,
|
| 21119 | |
and undefined behavior.
|
| 21120 | |
|
| 21121 | |
In C, a @dfn{constraint} is a rule that the compiler must enforce. An
|
| 21122 | |
example constraint is that C programs must not declare a bit-field with
|
| 21123 | |
negative width. Tests can therefore reliably assume that programs with
|
| 21124 | |
negative-width bit-fields are rejected by a compiler that conforms
|
| 21125 | |
to the standard.
|
| 21126 | |
|
| 21127 | |
@dfn{Unspecified behavior} is valid behavior, where the standard allows
|
| 21128 | |
multiple possibilities. For example, the order of evaluation of
|
| 21129 | |
function arguments is unspecified. Some unspecified behavior is
|
| 21130 | |
@dfn{implementation-defined}, i.e., documented by the implementation,
|
| 21131 | |
but since Autoconf tests cannot read the documentation they cannot
|
| 21132 | |
distinguish between implementation-defined and other unspecified
|
| 21133 | |
behavior. It is common for Autoconf tests to probe implementations to
|
| 21134 | |
determine otherwise-unspecified behavior.
|
| 21135 | |
|
| 21136 | |
@dfn{Undefined behavior} is invalid behavior, where the standard allows
|
| 21137 | |
the implementation to do anything it pleases. For example,
|
| 21138 | |
dereferencing a null pointer leads to undefined behavior. If possible,
|
| 21139 | |
test programs should avoid undefined behavior, since a program with
|
| 21140 | |
undefined behavior might succeed on a test that should fail.
|
| 21141 | |
|
| 21142 | |
The above rules apply to programs that are intended to conform to the
|
| 21143 | |
standard. However, strictly-conforming programs are quite rare, since
|
| 21144 | |
the standards are so limiting. A major goal of Autoconf is to support
|
| 21145 | |
programs that use implementation features not described by the standard,
|
| 21146 | |
and it is fairly common for test programs to violate the above rules, if
|
| 21147 | |
the programs work well enough in practice.
|
| 21148 | |
|
| 21149 | |
@node Integer Overflow
|
| 21150 | |
@section Integer Overflow
|
| 21151 | |
@cindex integer overflow
|
| 21152 | |
@cindex overflow, signed integer
|
| 21153 | |
@cindex signed integer overflow
|
| 21154 | |
@cindex wraparound arithmetic
|
| 21155 | |
|
| 21156 | |
In practice many portable C programs assume that signed integer overflow wraps
|
| 21157 | |
around reliably using two's complement arithmetic. Yet the C standard
|
| 21158 | |
says that program behavior is undefined on overflow, and in a few cases
|
| 21159 | |
C programs do not work on some modern implementations because their
|
| 21160 | |
overflows do not wrap around as their authors expected. Conversely, in
|
| 21161 | |
signed integer remainder, the C standard requires overflow
|
| 21162 | |
behavior that is commonly not implemented.
|
| 21163 | |
|
| 21164 | |
@menu
|
| 21165 | |
* Integer Overflow Basics:: Why integer overflow is a problem
|
| 21166 | |
* Signed Overflow Examples:: Examples of code assuming wraparound
|
| 21167 | |
* Optimization and Wraparound:: Optimizations that break uses of wraparound
|
| 21168 | |
* Signed Overflow Advice:: Practical advice for signed overflow issues
|
| 21169 | |
* Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
|
| 21170 | |
@end menu
|
| 21171 | |
|
| 21172 | |
@node Integer Overflow Basics
|
| 21173 | |
@subsection Basics of Integer Overflow
|
| 21174 | |
@cindex integer overflow
|
| 21175 | |
@cindex overflow, signed integer
|
| 21176 | |
@cindex signed integer overflow
|
| 21177 | |
@cindex wraparound arithmetic
|
| 21178 | |
|
| 21179 | |
In languages like C, unsigned integer overflow reliably wraps around;
|
| 21180 | |
e.g., @code{UINT_MAX + 1} yields zero.
|
| 21181 | |
This is guaranteed by the C standard and is
|
| 21182 | |
portable in practice, unless you specify aggressive,
|
| 21183 | |
nonstandard optimization options
|
| 21184 | |
suitable only for special applications.
|
| 21185 | |
|
| 21186 | |
In contrast, the C standard says that signed integer overflow leads to
|
| 21187 | |
undefined behavior where a program can do anything, including dumping
|
| 21188 | |
core or overrunning a buffer. The misbehavior can even precede the
|
| 21189 | |
overflow. Such an overflow can occur during addition, subtraction,
|
| 21190 | |
multiplication, division, and left shift.
|
| 21191 | |
|
| 21192 | |
Despite this requirement of the standard, many C programs and Autoconf
|
| 21193 | |
tests assume that signed integer overflow silently wraps around modulo a
|
| 21194 | |
power of two, using two's complement arithmetic, so long as you cast the
|
| 21195 | |
resulting value to a signed integer type or store it into a signed
|
| 21196 | |
integer variable. If you use conservative optimization flags, such
|
| 21197 | |
programs are generally portable to the vast majority of modern
|
| 21198 | |
platforms, with a few exceptions discussed later.
|
| 21199 | |
|
| 21200 | |
For historical reasons the C standard also allows implementations with
|
| 21201 | |
ones' complement or signed magnitude arithmetic, but it is safe to
|
| 21202 | |
assume two's complement nowadays.
|
| 21203 | |
|
| 21204 | |
Also, overflow can occur when converting an out-of-range value to a
|
| 21205 | |
signed integer type. Here a standard implementation must define what
|
| 21206 | |
happens, but this might include raising an exception. In practice all
|
| 21207 | |
known implementations support silent wraparound in this case, so you need
|
| 21208 | |
not worry about other possibilities.
|
| 21209 | |
|
| 21210 | |
@node Signed Overflow Examples
|
| 21211 | |
@subsection Examples of Code Assuming Wraparound Overflow
|
| 21212 | |
@cindex integer overflow
|
| 21213 | |
@cindex overflow, signed integer
|
| 21214 | |
@cindex signed integer overflow
|
| 21215 | |
@cindex wraparound arithmetic
|
| 21216 | |
|
| 21217 | |
There has long been a tension between what the C standard requires for
|
| 21218 | |
signed integer overflow, and what C programs commonly assume. The
|
| 21219 | |
standard allows aggressive optimizations based on assumptions that
|
| 21220 | |
overflow never occurs, but many practical C programs rely on overflow
|
| 21221 | |
wrapping around. These programs do not conform to the standard, but
|
| 21222 | |
they commonly work in practice because compiler writers are
|
| 21223 | |
understandably reluctant to implement optimizations that would break
|
| 21224 | |
many programs, unless perhaps a user specifies aggressive optimization.
|
| 21225 | |
|
| 21226 | |
The C Standard says that if a program has signed integer overflow its
|
| 21227 | |
behavior is undefined, and the undefined behavior can even precede the
|
| 21228 | |
overflow. To take an extreme example:
|
| 21229 | |
|
| 21230 | |
@c Inspired by Robert Dewar's example in
|
| 21231 | |
@c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
|
| 21232 | |
@example
|
| 21233 | |
if (password == expected_password)
|
| 21234 | |
allow_superuser_privileges ();
|
| 21235 | |
else if (counter++ == INT_MAX)
|
| 21236 | |
abort ();
|
| 21237 | |
else
|
| 21238 | |
printf ("%d password mismatches\n", counter);
|
| 21239 | |
@end example
|
| 21240 | |
|
| 21241 | |
@noindent
|
| 21242 | |
If the @code{int} variable @code{counter} equals @code{INT_MAX},
|
| 21243 | |
@code{counter++} must overflow and the behavior is undefined, so the C
|
| 21244 | |
standard allows the compiler to optimize away the test against
|
| 21245 | |
@code{INT_MAX} and the @code{abort} call.
|
| 21246 | |
Worse, if an earlier bug in the program lets the compiler deduce that
|
| 21247 | |
@code{counter == INT_MAX} or that @code{counter} previously overflowed,
|
| 21248 | |
the C standard allows the compiler to optimize away the password test
|
| 21249 | |
and generate code that allows superuser privileges unconditionally.
|
| 21250 | |
|
| 21251 | |
Despite this requirement by the standard, it has long been common for C
|
| 21252 | |
code to assume wraparound arithmetic after signed overflow, and all
|
| 21253 | |
known practical C implementations support some C idioms that assume
|
| 21254 | |
wraparound signed arithmetic, even if the idioms do not conform
|
| 21255 | |
strictly to the standard. If your code looks like the following
|
| 21256 | |
examples it will almost surely work with real-world compilers.
|
| 21257 | |
|
| 21258 | |
Here is an example derived from the 7th Edition Unix implementation of
|
| 21259 | |
@code{atoi} (1979-01-10):
|
| 21260 | |
|
| 21261 | |
@example
|
| 21262 | |
char *p;
|
| 21263 | |
int f, n;
|
| 21264 | |
@dots{}
|
| 21265 | |
while (*p >= '0' && *p <= '9')
|
| 21266 | |
n = n * 10 + *p++ - '0';
|
| 21267 | |
return (f ? -n : n);
|
| 21268 | |
@end example
|
| 21269 | |
|
| 21270 | |
@noindent
|
| 21271 | |
Even if the input string is in range, on most modern machines this has
|
| 21272 | |
signed overflow when computing the most negative integer (the @code{-n}
|
| 21273 | |
overflows) or a value near an extreme integer (the first @code{+}
|
| 21274 | |
overflows).
|
| 21275 | |
|
| 21276 | |
Here is another example, derived from the 7th Edition implementation of
|
| 21277 | |
@code{rand} (1979-01-10). Here the programmer expects both
|
| 21278 | |
multiplication and addition to wrap on overflow:
|
| 21279 | |
|
| 21280 | |
@example
|
| 21281 | |
static long int randx = 1;
|
| 21282 | |
@dots{}
|
| 21283 | |
randx = randx * 1103515245 + 12345;
|
| 21284 | |
return (randx >> 16) & 077777;
|
| 21285 | |
@end example
|
| 21286 | |
|
| 21287 | |
In the following example, derived from the GNU C Library 2.5
|
| 21288 | |
implementation of @code{mktime} (2006-09-09), the code assumes
|
| 21289 | |
wraparound arithmetic in @code{+} to detect signed overflow:
|
| 21290 | |
|
| 21291 | |
@example
|
| 21292 | |
time_t t, t1, t2;
|
| 21293 | |
int sec_requested, sec_adjustment;
|
| 21294 | |
@dots{}
|
| 21295 | |
t1 = t + sec_requested;
|
| 21296 | |
t2 = t1 + sec_adjustment;
|
| 21297 | |
if (((t1 < t) != (sec_requested < 0))
|
| 21298 | |
| ((t2 < t1) != (sec_adjustment < 0)))
|
| 21299 | |
return -1;
|
| 21300 | |
@end example
|
| 21301 | |
|
| 21302 | |
If your code looks like these examples, it is probably safe even though
|
| 21303 | |
it does not strictly conform to the C standard. This might lead one to
|
| 21304 | |
believe that one can generally assume wraparound on overflow, but that
|
| 21305 | |
is not always true, as can be seen in the next section.
|
| 21306 | |
|
| 21307 | |
@node Optimization and Wraparound
|
| 21308 | |
@subsection Optimizations That Break Wraparound Arithmetic
|
| 21309 | |
@cindex loop induction
|
| 21310 | |
|
| 21311 | |
Compilers sometimes generate code that is incompatible with wraparound
|
| 21312 | |
integer arithmetic. A simple example is an algebraic simplification: a
|
| 21313 | |
compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
|
| 21314 | |
because it assumes that @code{i * 2000} does not overflow. The
|
| 21315 | |
translation is not equivalent to the original when overflow occurs:
|
| 21316 | |
e.g., in the typical case of 32-bit signed two's complement wraparound
|
| 21317 | |
@code{int}, if @code{i} has type @code{int} and value @code{1073742},
|
| 21318 | |
the original expression returns @minus{}2147483 but the optimized
|
| 21319 | |
version returns the mathematically correct value 2147484.
|
| 21320 | |
|
| 21321 | |
More subtly, loop induction optimizations often exploit the undefined
|
| 21322 | |
behavior of signed overflow. Consider the following contrived function
|
| 21323 | |
@code{sumc}:
|
| 21324 | |
|
| 21325 | |
@example
|
| 21326 | |
int
|
| 21327 | |
sumc (int lo, int hi)
|
| 21328 | |
@{
|
| 21329 | |
int sum = 0;
|
| 21330 | |
int i;
|
| 21331 | |
for (i = lo; i <= hi; i++)
|
| 21332 | |
sum ^= i * 53;
|
| 21333 | |
return sum;
|
| 21334 | |
@}
|
| 21335 | |
@end example
|
| 21336 | |
|
| 21337 | |
@noindent
|
| 21338 | |
To avoid multiplying by 53 each time through the loop, an optimizing
|
| 21339 | |
compiler might internally transform @code{sumc} to the equivalent of the
|
| 21340 | |
following:
|
| 21341 | |
|
| 21342 | |
@example
|
| 21343 | |
int
|
| 21344 | |
transformed_sumc (int lo, int hi)
|
| 21345 | |
@{
|
| 21346 | |
int sum = 0;
|
| 21347 | |
int hic = hi * 53;
|
| 21348 | |
int ic;
|
| 21349 | |
for (ic = lo * 53; ic <= hic; ic += 53)
|
| 21350 | |
sum ^= ic;
|
| 21351 | |
return sum;
|
| 21352 | |
@}
|
| 21353 | |
@end example
|
| 21354 | |
|
| 21355 | |
@noindent
|
| 21356 | |
This transformation is allowed by the C standard, but it is invalid for
|
| 21357 | |
wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
|
| 21358 | |
overflow in computing expressions like @code{hi * 53} can cause the
|
| 21359 | |
expression @code{i <= hi} to yield a different value from the
|
| 21360 | |
transformed expression @code{ic <= hic}.
|
| 21361 | |
|
| 21362 | |
For this reason, compilers that use loop induction and similar
|
| 21363 | |
techniques often do not support reliable wraparound arithmetic when a
|
| 21364 | |
loop induction variable like @code{ic} is involved. Since loop
|
| 21365 | |
induction variables are generated by the compiler, and are not visible
|
| 21366 | |
in the source code, it is not always trivial to say whether the problem
|
| 21367 | |
affects your code.
|
| 21368 | |
|
| 21369 | |
Hardly any code actually depends on wraparound arithmetic in cases like
|
| 21370 | |
these, so in practice these loop induction optimizations are almost
|
| 21371 | |
always useful. However, edge cases in this area can cause problems.
|
| 21372 | |
For example:
|
| 21373 | |
|
| 21374 | |
@example
|
| 21375 | |
int j;
|
| 21376 | |
for (j = 1; 0 < j; j *= 2)
|
| 21377 | |
test (j);
|
| 21378 | |
@end example
|
| 21379 | |
|
| 21380 | |
@noindent
|
| 21381 | |
Here, the loop attempts to iterate through all powers of 2 that
|
| 21382 | |
@code{int} can represent, but the C standard allows a compiler to
|
| 21383 | |
optimize away the comparison and generate an infinite loop,
|
| 21384 | |
under the argument that behavior is undefined on overflow. As of this
|
| 21385 | |
writing this optimization is not done by any production version of
|
| 21386 | |
GCC with @option{-O2}, but it might be performed by other
|
| 21387 | |
compilers, or by more aggressive GCC optimization options,
|
| 21388 | |
and the GCC developers have not decided whether it will
|
| 21389 | |
continue to work with GCC and @option{-O2}.
|
| 21390 | |
|
| 21391 | |
@node Signed Overflow Advice
|
| 21392 | |
@subsection Practical Advice for Signed Overflow Issues
|
| 21393 | |
@cindex integer overflow
|
| 21394 | |
@cindex overflow, signed integer
|
| 21395 | |
@cindex signed integer overflow
|
| 21396 | |
@cindex wraparound arithmetic
|
| 21397 | |
|
| 21398 | |
Ideally the safest approach is to avoid signed integer overflow
|
| 21399 | |
entirely. For example, instead of multiplying two signed integers, you
|
| 21400 | |
can convert them to unsigned integers, multiply the unsigned values,
|
| 21401 | |
then test whether the result is in signed range.
|
| 21402 | |
|
| 21403 | |
Rewriting code in this way will be inconvenient, though, particularly if
|
| 21404 | |
the signed values might be negative. Also, it may hurt
|
| 21405 | |
performance. Using unsigned arithmetic to check for overflow is
|
| 21406 | |
particularly painful to do portably and efficiently when dealing with an
|
| 21407 | |
integer type like @code{uid_t} whose width and signedness vary from
|
| 21408 | |
platform to platform.
|
| 21409 | |
|
| 21410 | |
Furthermore, many C applications pervasively assume wraparound behavior
|
| 21411 | |
and typically it is not easy to find and remove all these assumptions.
|
| 21412 | |
Hence it is often useful to maintain nonstandard code that assumes
|
| 21413 | |
wraparound on overflow, instead of rewriting the code. The rest of this
|
| 21414 | |
section attempts to give practical advice for this situation.
|
| 21415 | |
|
| 21416 | |
If your code wants to detect signed integer overflow in @code{sum = a +
|
| 21417 | |
b}, it is generally safe to use an expression like @code{(sum < a) != (b
|
| 21418 | |
< 0)}.
|
| 21419 | |
|
| 21420 | |
If your code uses a signed loop index, make sure that the index cannot
|
| 21421 | |
overflow, along with all signed expressions derived from the index.
|
| 21422 | |
Here is a contrived example of problematic code with two instances of
|
| 21423 | |
overflow.
|
| 21424 | |
|
| 21425 | |
@example
|
| 21426 | |
for (i = INT_MAX - 10; i <= INT_MAX; i++)
|
| 21427 | |
if (i + 1 < 0)
|
| 21428 | |
@{
|
| 21429 | |
report_overflow ();
|
| 21430 | |
break;
|
| 21431 | |
@}
|
| 21432 | |
@end example
|
| 21433 | |
|
| 21434 | |
@noindent
|
| 21435 | |
Because of the two overflows, a compiler might optimize away or
|
| 21436 | |
transform the two comparisons in a way that is incompatible with the
|
| 21437 | |
wraparound assumption.
|
| 21438 | |
|
| 21439 | |
If your code uses an expression like @code{(i * 2000) / 1000} and you
|
| 21440 | |
actually want the multiplication to wrap around on overflow, use
|
| 21441 | |
unsigned arithmetic
|
| 21442 | |
to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
|
| 21443 | |
|
| 21444 | |
If your code assumes wraparound behavior and you want to insulate it
|
| 21445 | |
against any GCC optimizations that would fail to support that
|
| 21446 | |
behavior, you should use GCC's @option{-fwrapv} option, which
|
| 21447 | |
causes signed overflow to wrap around reliably (except for division and
|
| 21448 | |
remainder, as discussed in the next section).
|
| 21449 | |
|
| 21450 | |
If you need to port to platforms where signed integer overflow does not
|
| 21451 | |
reliably wrap around (e.g., due to hardware overflow checking, or to
|
| 21452 | |
highly aggressive optimizations), you should consider debugging with
|
| 21453 | |
GCC's @option{-ftrapv} option, which causes signed overflow to
|
| 21454 | |
raise an exception.
|
| 21455 | |
|
| 21456 | |
@node Signed Integer Division
|
| 21457 | |
@subsection Signed Integer Division and Integer Overflow
|
| 21458 | |
@cindex division, integer
|
| 21459 | |
|
| 21460 | |
Overflow in signed
|
| 21461 | |
integer division is not always harmless: for example, on CPUs of the
|
| 21462 | |
i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
|
| 21463 | |
which by default terminates the program. Worse, taking the remainder
|
| 21464 | |
of these two values typically yields the same signal on these CPUs,
|
| 21465 | |
even though the C standard requires @code{INT_MIN % -1} to yield zero
|
| 21466 | |
because the expression does not overflow.
|
| 21467 | |
|
| 21468 | |
@node Preprocessor Arithmetic
|
| 21469 | |
@section Preprocessor Arithmetic
|
| 21470 | |
@cindex preprocessor arithmetic
|
| 21471 | |
|
| 21472 | |
In C99, preprocessor arithmetic, used for @code{#if} expressions, must
|
| 21473 | |
be evaluated as if all signed values are of type @code{intmax_t} and all
|
| 21474 | |
unsigned values of type @code{uintmax_t}. Many compilers are buggy in
|
| 21475 | |
this area, though. For example, as of 2007, Sun C mishandles @code{#if
|
| 21476 | |
LLONG_MIN < 0} on a platform with 32-bit @code{long int} and 64-bit
|
| 21477 | |
@code{long long int}. Also, some older preprocessors mishandle
|
| 21478 | |
constants ending in @code{LL}. To work around these problems, you can
|
| 21479 | |
compute the value of expressions like @code{LONG_MAX < LLONG_MAX} at
|
| 21480 | |
@code{configure}-time rather than at @code{#if}-time.
|
| 21481 | |
|
| 21482 | |
@node Null Pointers
|
| 21483 | |
@section Properties of Null Pointers
|
| 21484 | |
@cindex null pointers
|
| 21485 | |
|
| 21486 | |
Most modern hosts reliably fail when you attempt to dereference a null
|
| 21487 | |
pointer.
|
| 21488 | |
|
| 21489 | |
On almost all modern hosts, null pointers use an all-bits-zero internal
|
| 21490 | |
representation, so you can reliably use @code{memset} with 0 to set all
|
| 21491 | |
the pointers in an array to null values.
|
| 21492 | |
|
| 21493 | |
If @code{p} is a null pointer to an object type, the C expression
|
| 21494 | |
@code{p + 0} always evaluates to @code{p} on modern hosts, even though
|
| 21495 | |
the standard says that it has undefined behavior.
|
| 21496 | |
|
| 21497 | |
@node Buffer Overruns
|
| 21498 | |
@section Buffer Overruns and Subscript Errors
|
| 21499 | |
@cindex buffer overruns
|
| 21500 | |
|
| 21501 | |
Buffer overruns and subscript errors are the most common dangerous
|
| 21502 | |
errors in C programs. They result in undefined behavior because storing
|
| 21503 | |
outside an array typically modifies storage that is used by some other
|
| 21504 | |
object, and most modern systems lack runtime checks to catch these
|
| 21505 | |
errors. Programs should not rely on buffer overruns being caught.
|
| 21506 | |
|
| 21507 | |
There is one exception to the usual rule that a portable program cannot
|
| 21508 | |
address outside an array. In C, it is valid to compute the address just
|
| 21509 | |
past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
|
| 21510 | |
so long as you do not dereference the resulting pointer. But it is not
|
| 21511 | |
valid to compute the address just before an object, e.g., @code{&a[-1]};
|
| 21512 | |
nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
|
| 21513 | |
most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
|
| 21514 | |
reliable in general, and it is usually easy enough to avoid the
|
| 21515 | |
potential portability problem, e.g., by allocating an extra unused array
|
| 21516 | |
element at the start or end.
|
| 21517 | |
|
| 21518 | |
@uref{http://@/valgrind.org/, Valgrind} can catch many overruns.
|
| 21519 | |
GCC
|
| 21520 | |
users might also consider using the @option{-fmudflap} option to catch
|
| 21521 | |
overruns.
|
| 21522 | |
|
| 21523 | |
Buffer overruns are usually caused by off-by-one errors, but there are
|
| 21524 | |
more subtle ways to get them.
|
| 21525 | |
|
| 21526 | |
Using @code{int} values to index into an array or compute array sizes
|
| 21527 | |
causes problems on typical 64-bit hosts where an array index might
|
| 21528 | |
be @math{2^{31}} or larger. Index values of type @code{size_t} avoid this
|
| 21529 | |
problem, but cannot be negative. Index values of type @code{ptrdiff_t}
|
| 21530 | |
are signed, and are wide enough in practice.
|
| 21531 | |
|
| 21532 | |
If you add or multiply two numbers to calculate an array size, e.g.,
|
| 21533 | |
@code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
|
| 21534 | |
multiplication overflows.
|
| 21535 | |
|
| 21536 | |
Many implementations of the @code{alloca} function silently misbehave
|
| 21537 | |
and can generate buffer overflows if given sizes that are too large.
|
| 21538 | |
The size limits are implementation dependent, but are at least 4000
|
| 21539 | |
bytes on all platforms that we know about.
|
| 21540 | |
|
| 21541 | |
The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
|
| 21542 | |
@code{ctime_r}, and @code{gets} are prone to buffer overflows, and
|
| 21543 | |
portable code should not use them unless the inputs are known to be
|
| 21544 | |
within certain limits. The time-related functions can overflow their
|
| 21545 | |
buffers if given timestamps out of range (e.g., a year less than -999
|
| 21546 | |
or greater than 9999). Time-related buffer overflows cannot happen with
|
| 21547 | |
recent-enough versions of the GNU C library, but are possible
|
| 21548 | |
with other
|
| 21549 | |
implementations. The @code{gets} function is the worst, since it almost
|
| 21550 | |
invariably overflows its buffer when presented with an input line larger
|
| 21551 | |
than the buffer.
|
| 21552 | |
|
| 21553 | |
@node Volatile Objects
|
| 21554 | |
@section Volatile Objects
|
| 21555 | |
@cindex volatile objects
|
| 21556 | |
|
| 21557 | |
The keyword @code{volatile} is often misunderstood in portable code.
|
| 21558 | |
Its use inhibits some memory-access optimizations, but programmers often
|
| 21559 | |
wish that it had a different meaning than it actually does.
|
| 21560 | |
|
| 21561 | |
@code{volatile} was designed for code that accesses special objects like
|
| 21562 | |
memory-mapped device registers whose contents spontaneously change.
|
| 21563 | |
Such code is inherently low-level, and it is difficult to specify
|
| 21564 | |
portably what @code{volatile} means in these cases. The C standard
|
| 21565 | |
says, ``What constitutes an access to an object that has
|
| 21566 | |
volatile-qualified type is implementation-defined,'' so in theory each
|
| 21567 | |
implementation is supposed to fill in the gap by documenting what
|
| 21568 | |
@code{volatile} means for that implementation. In practice, though,
|
| 21569 | |
this documentation is usually absent or incomplete.
|
| 21570 | |
|
| 21571 | |
One area of confusion is the distinction between objects defined with
|
| 21572 | |
volatile types, and volatile lvalues. From the C standard's point of
|
| 21573 | |
view, an object defined with a volatile type has externally visible
|
| 21574 | |
behavior. You can think of such objects as having little oscilloscope
|
| 21575 | |
probes attached to them, so that the user can observe some properties of
|
| 21576 | |
accesses to them, just as the user can observe data written to output
|
| 21577 | |
files. However, the standard does not make it clear whether users can
|
| 21578 | |
observe accesses by volatile lvalues to ordinary objects. For example:
|
| 21579 | |
|
| 21580 | |
@example
|
| 21581 | |
/* Declare and access a volatile object.
|
| 21582 | |
Accesses to X are "visible" to users. */
|
| 21583 | |
static int volatile x;
|
| 21584 | |
x = 1;
|
| 21585 | |
|
| 21586 | |
/* Access two ordinary objects via a volatile lvalue.
|
| 21587 | |
It's not clear whether accesses to *P are "visible". */
|
| 21588 | |
int y;
|
| 21589 | |
int *z = malloc (sizeof (int));
|
| 21590 | |
int volatile *p;
|
| 21591 | |
p = &y;
|
| 21592 | |
*p = 1;
|
| 21593 | |
p = z;
|
| 21594 | |
*p = 1;
|
| 21595 | |
@end example
|
| 21596 | |
|
| 21597 | |
Programmers often wish that @code{volatile} meant ``Perform the memory
|
| 21598 | |
access here and now, without merging several memory accesses, without
|
| 21599 | |
changing the memory word size, and without reordering.'' But the C
|
| 21600 | |
standard does not require this. For objects defined with a volatile
|
| 21601 | |
type, accesses must be done before the next sequence point; but
|
| 21602 | |
otherwise merging, reordering, and word-size change is allowed. Worse,
|
| 21603 | |
it is not clear from the standard whether volatile lvalues provide more
|
| 21604 | |
guarantees in general than nonvolatile lvalues, if the underlying
|
| 21605 | |
objects are ordinary.
|
| 21606 | |
|
| 21607 | |
Even when accessing objects defined with a volatile type,
|
| 21608 | |
the C standard allows only
|
| 21609 | |
extremely limited signal handlers: the behavior is undefined if a signal
|
| 21610 | |
handler reads any nonlocal object, or writes to any nonlocal object
|
| 21611 | |
whose type is not @code{sig_atomic_t volatile}, or calls any standard
|
| 21612 | |
library function other than @code{abort}, @code{signal}, and (if C99)
|
| 21613 | |
@code{_Exit}. Hence C compilers need not worry about a signal handler
|
| 21614 | |
disturbing ordinary computation, unless the computation accesses a
|
| 21615 | |
@code{sig_atomic_t volatile} lvalue that is not a local variable.
|
| 21616 | |
(There is an obscure exception for accesses via a pointer to a volatile
|
| 21617 | |
character, since it may point into part of a @code{sig_atomic_t
|
| 21618 | |
volatile} object.) Posix
|
| 21619 | |
adds to the list of library functions callable from a portable signal
|
| 21620 | |
handler, but otherwise is like the C standard in this area.
|
| 21621 | |
|
| 21622 | |
Some C implementations allow memory-access optimizations within each
|
| 21623 | |
translation unit, such that actual behavior agrees with the behavior
|
| 21624 | |
required by the standard only when calling a function in some other
|
| 21625 | |
translation unit, and a signal handler acts like it was called from a
|
| 21626 | |
different translation unit. The C standard hints that in these
|
| 21627 | |
implementations, objects referred to by signal handlers ``would require
|
| 21628 | |
explicit specification of @code{volatile} storage, as well as other
|
| 21629 | |
implementation-defined restrictions.'' But unfortunately even for this
|
| 21630 | |
special case these other restrictions are often not documented well.
|
| 21631 | |
@xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
|
| 21632 | |
GNU Compiler Collection (GCC)}, for some
|
| 21633 | |
restrictions imposed by GCC. @xref{Defining Handlers, ,
|
| 21634 | |
Defining Signal Handlers, libc, The GNU C Library}, for some
|
| 21635 | |
restrictions imposed by the GNU C library. Restrictions
|
| 21636 | |
differ on other platforms.
|
| 21637 | |
|
| 21638 | |
If possible, it is best to use a signal handler that fits within the
|
| 21639 | |
limits imposed by the C and Posix standards.
|
| 21640 | |
|
| 21641 | |
If this is not practical, you can try the following rules of thumb. A
|
| 21642 | |
signal handler should access only volatile lvalues, preferably lvalues
|
| 21643 | |
that refer to objects defined with a volatile type, and should not
|
| 21644 | |
assume that the accessed objects have an internally consistent state
|
| 21645 | |
if they are larger than a machine word. Furthermore, installers
|
| 21646 | |
should employ compilers and compiler options that are commonly used
|
| 21647 | |
for building operating system kernels, because kernels often need more
|
| 21648 | |
from @code{volatile} than the C Standard requires, and installers who
|
| 21649 | |
compile an application in a similar environment can sometimes benefit
|
| 21650 | |
from the extra constraints imposed by kernels on compilers.
|
| 21651 | |
Admittedly we are handwaving somewhat here, as there are few
|
| 21652 | |
guarantees in this area; the rules of thumb may help to fix some bugs
|
| 21653 | |
but there is a good chance that they will not fix them all.
|
| 21654 | |
|
| 21655 | |
For @code{volatile}, C++ has the same problems that C does.
|
| 21656 | |
Multithreaded applications have even more problems with @code{volatile},
|
| 21657 | |
but they are beyond the scope of this section.
|
| 21658 | |
|
| 21659 | |
The bottom line is that using @code{volatile} typically hurts
|
| 21660 | |
performance but should not hurt correctness. In some cases its use
|
| 21661 | |
does help correctness, but these cases are often so poorly understood
|
| 21662 | |
that all too often adding @code{volatile} to a data structure merely
|
| 21663 | |
alleviates some symptoms of a bug while not fixing the bug in general.
|
| 21664 | |
|
| 21665 | |
@node Floating Point Portability
|
| 21666 | |
@section Floating Point Portability
|
| 21667 | |
@cindex floating point
|
| 21668 | |
|
| 21669 | |
Almost all modern systems use IEEE-754 floating point, and it is safe to
|
| 21670 | |
assume IEEE-754 in most portable code these days. For more information,
|
| 21671 | |
please see David Goldberg's classic paper
|
| 21672 | |
@uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every Computer
|
| 21673 | |
Scientist Should Know About Floating-Point Arithmetic}.
|
| 21674 | |
|
| 21675 | |
@node Exiting Portably
|
| 21676 | |
@section Exiting Portably
|
| 21677 | |
@cindex exiting portably
|
| 21678 | |
|
| 21679 | |
A C or C++ program can exit with status @var{N} by returning
|
| 21680 | |
@var{N} from the @code{main} function. Portable programs are supposed
|
| 21681 | |
to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
|
| 21682 | |
status @code{EXIT_FAILURE} to fail, but in practice it is portable to
|
| 21683 | |
fail by exiting with status 1, and test programs that assume Posix can
|
| 21684 | |
fail by exiting with status values from 1 through 255. Programs on
|
| 21685 | |
SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
|
| 21686 | |
status when @code{main} returned nonzero, but ancient systems like these
|
| 21687 | |
are no longer of practical concern.
|
| 21688 | |
|
| 21689 | |
A program can also exit with status @var{N} by passing @var{N} to the
|
| 21690 | |
@code{exit} function, and a program can fail by calling the @code{abort}
|
| 21691 | |
function. If a program is specialized to just some platforms, it can fail
|
| 21692 | |
by calling functions specific to those platforms, e.g., @code{_exit}
|
| 21693 | |
(Posix) and @code{_Exit} (C99). However, like other functions, an exit
|
| 21694 | |
function should be declared, typically by including a header. For
|
| 21695 | |
example, if a C program calls @code{exit}, it should include @file{stdlib.h}
|
| 21696 | |
either directly or via the default includes (@pxref{Default Includes}).
|
| 21697 | |
|
| 21698 | |
A program can fail due to undefined behavior such as dereferencing a null
|
| 21699 | |
pointer, but this is not recommended as undefined behavior allows an
|
| 21700 | |
implementation to do whatever it pleases and this includes exiting
|
| 21701 | |
successfully.
|
| 21702 | |
|
| 21703 | |
|
| 21704 | |
@c ================================================== Manual Configuration
|
| 21705 | |
|
| 21706 | |
@node Manual Configuration
|
| 21707 | |
@chapter Manual Configuration
|
| 21708 | |
|
| 21709 | |
A few kinds of features can't be guessed automatically by running test
|
| 21710 | |
programs. For example, the details of the object-file format, or
|
| 21711 | |
special options that need to be passed to the compiler or linker. You
|
| 21712 | |
can check for such features using ad-hoc means, such as having
|
| 21713 | |
@command{configure} check the output of the @code{uname} program, or
|
| 21714 | |
looking for libraries that are unique to particular systems. However,
|
| 21715 | |
Autoconf provides a uniform method for handling unguessable features.
|
| 21716 | |
|
| 21717 | |
@menu
|
| 21718 | |
* Specifying Target Triplets:: Specifying target triplets
|
| 21719 | |
* Canonicalizing:: Getting the canonical system type
|
| 21720 | |
* Using System Type:: What to do with the system type
|
| 21721 | |
@end menu
|
| 21722 | |
|
| 21723 | |
@node Specifying Target Triplets
|
| 21724 | |
@section Specifying target triplets
|
| 21725 | |
@cindex System type
|
| 21726 | |
@cindex Target triplet
|
| 21727 | |
@c This node used to be named Specifying Names. The @anchor allows old
|
| 21728 | |
@c links to still work.
|
| 21729 | |
@anchor{Specifying Names}
|
| 21730 | |
|
| 21731 | |
Autoconf-generated
|
| 21732 | |
@command{configure} scripts can make decisions based on a canonical name
|
| 21733 | |
for the system type, or @dfn{target triplet}, which has the form:
|
| 21734 | |
@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
|
| 21735 | |
@samp{@var{system}} or @samp{@var{kernel}-@var{system}}
|
| 21736 | |
|
| 21737 | |
@command{configure} can usually guess the canonical name for the type of
|
| 21738 | |
system it's running on. To do so it runs a script called
|
| 21739 | |
@command{config.guess}, which infers the name using the @code{uname}
|
| 21740 | |
command or symbols predefined by the C preprocessor.
|
| 21741 | |
|
| 21742 | |
Alternately, the user can specify the system type with command line
|
| 21743 | |
arguments to @command{configure} (@pxref{System Type}. Doing so is
|
| 21744 | |
necessary when
|
| 21745 | |
cross-compiling. In the most complex case of cross-compiling, three
|
| 21746 | |
system types are involved. The options to specify them are:
|
| 21747 | |
|
| 21748 | |
@table @option
|
| 21749 | |
@item --build=@var{build-type}
|
| 21750 | |
the type of system on which the package is being configured and
|
| 21751 | |
compiled. It defaults to the result of running @command{config.guess}.
|
| 21752 | |
Specifying a @var{build-type} that differs from @var{host-type} enables
|
| 21753 | |
cross-compilation mode.
|
| 21754 | |
|
| 21755 | |
@item --host=@var{host-type}
|
| 21756 | |
the type of system on which the package runs. By default it is the
|
| 21757 | |
same as the build machine. Specifying a @var{host-type} that differs
|
| 21758 | |
from @var{build-type}, when @var{build-type} was also explicitly
|
| 21759 | |
specified, enables cross-compilation mode.
|
| 21760 | |
|
| 21761 | |
@item --target=@var{target-type}
|
| 21762 | |
the type of system for which any compiler tools in the package
|
| 21763 | |
produce code (rarely needed). By default, it is the same as host.
|
| 21764 | |
@end table
|
| 21765 | |
|
| 21766 | |
If you mean to override the result of @command{config.guess}, use
|
| 21767 | |
@option{--build}, not @option{--host}, since the latter enables
|
| 21768 | |
cross-compilation. For historical reasons,
|
| 21769 | |
whenever you specify @option{--host},
|
| 21770 | |
be sure to specify @option{--build} too; this will be fixed in the
|
| 21771 | |
future. So, to enter cross-compilation mode, use a command like this
|
| 21772 | |
|
| 21773 | |
@example
|
| 21774 | |
./configure --build=i686-pc-linux-gnu --host=m68k-coff
|
| 21775 | |
@end example
|
| 21776 | |
|
| 21777 | |
@noindent
|
| 21778 | |
Note that if you do not specify @option{--host}, @command{configure}
|
| 21779 | |
fails if it can't run the code generated by the specified compiler. For
|
| 21780 | |
example, configuring as follows fails:
|
| 21781 | |
|
| 21782 | |
@example
|
| 21783 | |
./configure CC=m68k-coff-gcc
|
| 21784 | |
@end example
|
| 21785 | |
|
| 21786 | |
When cross-compiling, @command{configure} will warn about any tools
|
| 21787 | |
(compilers, linkers, assemblers) whose name is not prefixed with the
|
| 21788 | |
host type. This is an aid to users performing cross-compilation.
|
| 21789 | |
Continuing the example above, if a cross-compiler named @command{cc} is
|
| 21790 | |
used with a native @command{pkg-config}, then libraries found by
|
| 21791 | |
@command{pkg-config} will likely cause subtle build failures; but using
|
| 21792 | |
the names @command{m68k-coff-cc} and @command{m68k-coff-pkg-config}
|
| 21793 | |
avoids any confusion. Avoiding the warning is as simple as creating the
|
| 21794 | |
correct symlinks naming the cross tools.
|
| 21795 | |
|
| 21796 | |
@cindex @command{config.sub}
|
| 21797 | |
@command{configure} recognizes short aliases for many system types; for
|
| 21798 | |
example, @samp{decstation} can be used instead of
|
| 21799 | |
@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
|
| 21800 | |
@command{config.sub} to canonicalize system type aliases.
|
| 21801 | |
|
| 21802 | |
This section deliberately omits the description of the obsolete
|
| 21803 | |
interface; see @ref{Hosts and Cross-Compilation}.
|
| 21804 | |
|
| 21805 | |
|
| 21806 | |
@node Canonicalizing
|
| 21807 | |
@section Getting the Canonical System Type
|
| 21808 | |
@cindex System type
|
| 21809 | |
@cindex Canonical system type
|
| 21810 | |
|
| 21811 | |
The following macros make the system type available to @command{configure}
|
| 21812 | |
scripts.
|
| 21813 | |
|
| 21814 | |
@ovindex build_alias
|
| 21815 | |
@ovindex host_alias
|
| 21816 | |
@ovindex target_alias
|
| 21817 | |
|
| 21818 | |
The variables @samp{build_alias}, @samp{host_alias}, and
|
| 21819 | |
@samp{target_alias} are always exactly the arguments of @option{--build},
|
| 21820 | |
@option{--host}, and @option{--target}; in particular, they are left empty
|
| 21821 | |
if the user did not use them, even if the corresponding
|
| 21822 | |
@code{AC_CANONICAL} macro was run. Any configure script may use these
|
| 21823 | |
variables anywhere. These are the variables that should be used when in
|
| 21824 | |
interaction with the user.
|
| 21825 | |
|
| 21826 | |
If you need to recognize some special environments based on their system
|
| 21827 | |
type, run the following macros to get canonical system names. These
|
| 21828 | |
variables are not set before the macro call.
|
| 21829 | |
|
| 21830 | |
If you use these macros, you must distribute @command{config.guess} and
|
| 21831 | |
@command{config.sub} along with your source code. @xref{Output}, for
|
| 21832 | |
information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
|
| 21833 | |
to control in which directory @command{configure} looks for those scripts.
|
| 21834 | |
|
| 21835 | |
|
| 21836 | |
@defmac AC_CANONICAL_BUILD
|
| 21837 | |
@acindex{CANONICAL_BUILD}
|
| 21838 | |
@ovindex build
|
| 21839 | |
@ovindex build_cpu
|
| 21840 | |
@ovindex build_vendor
|
| 21841 | |
@ovindex build_os
|
| 21842 | |
Compute the canonical build-system type variable, @code{build}, and its
|
| 21843 | |
three individual parts @code{build_cpu}, @code{build_vendor}, and
|
| 21844 | |
@code{build_os}.
|
| 21845 | |
|
| 21846 | |
If @option{--build} was specified, then @code{build} is the
|
| 21847 | |
canonicalization of @code{build_alias} by @command{config.sub},
|
| 21848 | |
otherwise it is determined by the shell script @command{config.guess}.
|
| 21849 | |
@end defmac
|
| 21850 | |
|
| 21851 | |
@defmac AC_CANONICAL_HOST
|
| 21852 | |
@acindex{CANONICAL_HOST}
|
| 21853 | |
@ovindex host
|
| 21854 | |
@ovindex host_cpu
|
| 21855 | |
@ovindex host_vendor
|
| 21856 | |
@ovindex host_os
|
| 21857 | |
Compute the canonical host-system type variable, @code{host}, and its
|
| 21858 | |
three individual parts @code{host_cpu}, @code{host_vendor}, and
|
| 21859 | |
@code{host_os}.
|
| 21860 | |
|
| 21861 | |
If @option{--host} was specified, then @code{host} is the
|
| 21862 | |
canonicalization of @code{host_alias} by @command{config.sub},
|
| 21863 | |
otherwise it defaults to @code{build}.
|
| 21864 | |
@end defmac
|
| 21865 | |
|
| 21866 | |
@defmac AC_CANONICAL_TARGET
|
| 21867 | |
@acindex{CANONICAL_TARGET}
|
| 21868 | |
@ovindex target
|
| 21869 | |
@ovindex target_cpu
|
| 21870 | |
@ovindex target_vendor
|
| 21871 | |
@ovindex target_os
|
| 21872 | |
Compute the canonical target-system type variable, @code{target}, and its
|
| 21873 | |
three individual parts @code{target_cpu}, @code{target_vendor}, and
|
| 21874 | |
@code{target_os}.
|
| 21875 | |
|
| 21876 | |
If @option{--target} was specified, then @code{target} is the
|
| 21877 | |
canonicalization of @code{target_alias} by @command{config.sub},
|
| 21878 | |
otherwise it defaults to @code{host}.
|
| 21879 | |
@end defmac
|
| 21880 | |
|
| 21881 | |
Note that there can be artifacts due to the backward compatibility
|
| 21882 | |
code. @xref{Hosts and Cross-Compilation}, for more.
|
| 21883 | |
|
| 21884 | |
@node Using System Type
|
| 21885 | |
@section Using the System Type
|
| 21886 | |
|
| 21887 | |
In @file{configure.ac} the system type is generally used by one or more
|
| 21888 | |
@code{case} statements to select system-specifics. Shell wildcards can
|
| 21889 | |
be used to match a group of system types.
|
| 21890 | |
|
| 21891 | |
For example, an extra assembler code object file could be chosen, giving
|
| 21892 | |
access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
|
| 21893 | |
following would be used in a makefile to add the object to a
|
| 21894 | |
program or library.
|
| 21895 | |
|
| 21896 | |
@example
|
| 21897 | |
AS_CASE([$host],
|
| 21898 | |
[alpha*-*-*], [CYCLE_OBJ=rpcc.o],
|
| 21899 | |
[i?86-*-*], [CYCLE_OBJ=rdtsc.o],
|
| 21900 | |
[CYCLE_OBJ=""]
|
| 21901 | |
)
|
| 21902 | |
AC_SUBST([CYCLE_OBJ])
|
| 21903 | |
@end example
|
| 21904 | |
|
| 21905 | |
@code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
|
| 21906 | |
to select variant source files, for example optimized code for some
|
| 21907 | |
CPUs. The configured CPU type doesn't always indicate exact CPU types,
|
| 21908 | |
so some runtime capability checks may be necessary too.
|
| 21909 | |
|
| 21910 | |
@example
|
| 21911 | |
case $host in
|
| 21912 | |
alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
|
| 21913 | |
powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
|
| 21914 | |
*-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
|
| 21915 | |
esac
|
| 21916 | |
@end example
|
| 21917 | |
|
| 21918 | |
The host system type can also be used to find cross-compilation tools
|
| 21919 | |
with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
|
| 21920 | |
|
| 21921 | |
The above examples all show @samp{$host}, since this is where the code
|
| 21922 | |
is going to run. Only rarely is it necessary to test @samp{$build}
|
| 21923 | |
(which is where the build is being done).
|
| 21924 | |
|
| 21925 | |
Whenever you're tempted to use @samp{$host} it's worth considering
|
| 21926 | |
whether some sort of probe would be better. New system types come along
|
| 21927 | |
periodically or previously missing features are added. Well-written
|
| 21928 | |
probes can adapt themselves to such things, but hard-coded lists of
|
| 21929 | |
names can't. Here are some guidelines,
|
| 21930 | |
|
| 21931 | |
@itemize @bullet
|
| 21932 | |
@item
|
| 21933 | |
Availability of libraries and library functions should always be checked
|
| 21934 | |
by probing.
|
| 21935 | |
@item
|
| 21936 | |
Variant behavior of system calls is best identified with runtime tests
|
| 21937 | |
if possible, but bug workarounds or obscure difficulties might have to
|
| 21938 | |
be driven from @samp{$host}.
|
| 21939 | |
@item
|
| 21940 | |
Assembler code is inevitably highly CPU-specific and is best selected
|
| 21941 | |
according to @samp{$host_cpu}.
|
| 21942 | |
@item
|
| 21943 | |
Assembler variations like underscore prefix on globals or ELF versus
|
| 21944 | |
COFF type directives are however best determined by probing, perhaps
|
| 21945 | |
even examining the compiler output.
|
| 21946 | |
@end itemize
|
| 21947 | |
|
| 21948 | |
@samp{$target} is for use by a package creating a compiler or similar.
|
| 21949 | |
For ordinary packages it's meaningless and should not be used. It
|
| 21950 | |
indicates what the created compiler should generate code for, if it can
|
| 21951 | |
cross-compile. @samp{$target} generally selects various hard-coded CPU
|
| 21952 | |
and system conventions, since usually the compiler or tools under
|
| 21953 | |
construction themselves determine how the target works.
|
| 21954 | |
|
| 21955 | |
|
| 21956 | |
@c ===================================================== Site Configuration.
|
| 21957 | |
|
| 21958 | |
@node Site Configuration
|
| 21959 | |
@chapter Site Configuration
|
| 21960 | |
|
| 21961 | |
@command{configure} scripts support several kinds of local configuration
|
| 21962 | |
decisions. There are ways for users to specify where external software
|
| 21963 | |
packages are, include or exclude optional features, install programs
|
| 21964 | |
under modified names, and set default values for @command{configure}
|
| 21965 | |
options.
|
| 21966 | |
|
| 21967 | |
@menu
|
| 21968 | |
* Help Formatting:: Customizing @samp{configure --help}
|
| 21969 | |
* External Software:: Working with other optional software
|
| 21970 | |
* Package Options:: Selecting optional features
|
| 21971 | |
* Pretty Help Strings:: Formatting help string
|
| 21972 | |
* Option Checking:: Controlling checking of @command{configure} options
|
| 21973 | |
* Site Details:: Configuring site details
|
| 21974 | |
* Transforming Names:: Changing program names when installing
|
| 21975 | |
* Site Defaults:: Giving @command{configure} local defaults
|
| 21976 | |
@end menu
|
| 21977 | |
|
| 21978 | |
@node Help Formatting
|
| 21979 | |
@section Controlling Help Output
|
| 21980 | |
|
| 21981 | |
Users consult @samp{configure --help} to learn of configuration
|
| 21982 | |
decisions specific to your package. By default, @command{configure}
|
| 21983 | |
breaks this output into sections for each type of option; within each
|
| 21984 | |
section, help strings appear in the order @file{configure.ac} defines
|
| 21985 | |
them:
|
| 21986 | |
|
| 21987 | |
@example
|
| 21988 | |
Optional Features:
|
| 21989 | |
@dots{}
|
| 21990 | |
--enable-bar include bar
|
| 21991 | |
|
| 21992 | |
Optional Packages:
|
| 21993 | |
@dots{}
|
| 21994 | |
--with-foo use foo
|
| 21995 | |
@end example
|
| 21996 | |
|
| 21997 | |
@defmac AC_PRESERVE_HELP_ORDER
|
| 21998 | |
@acindex{PRESERVE_HELP_ORDER}
|
| 21999 | |
|
| 22000 | |
Request an alternate @option{--help} format, in which options of all
|
| 22001 | |
types appear together, in the order defined. Call this macro before any
|
| 22002 | |
@code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
|
| 22003 | |
|
| 22004 | |
@example
|
| 22005 | |
Optional Features and Packages:
|
| 22006 | |
@dots{}
|
| 22007 | |
--enable-bar include bar
|
| 22008 | |
--with-foo use foo
|
| 22009 | |
@end example
|
| 22010 | |
|
| 22011 | |
@end defmac
|
| 22012 | |
|
| 22013 | |
@node External Software
|
| 22014 | |
@section Working With External Software
|
| 22015 | |
@cindex External software
|
| 22016 | |
|
| 22017 | |
Some packages require, or can optionally use, other software packages
|
| 22018 | |
that are already installed. The user can give @command{configure}
|
| 22019 | |
command line options to specify which such external software to use.
|
| 22020 | |
The options have one of these forms:
|
| 22021 | |
|
| 22022 | |
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
|
| 22023 | |
@c awful.
|
| 22024 | |
@example
|
| 22025 | |
--with-@var{package}@r{[}=@var{arg}@r{]}
|
| 22026 | |
--without-@var{package}
|
| 22027 | |
@end example
|
| 22028 | |
|
| 22029 | |
For example, @option{--with-gnu-ld} means work with the GNU linker
|
| 22030 | |
instead of some other linker. @option{--with-x} means work with The X
|
| 22031 | |
Window System.
|
| 22032 | |
|
| 22033 | |
The user can give an argument by following the package name with
|
| 22034 | |
@samp{=} and the argument. Giving an argument of @samp{no} is for
|
| 22035 | |
packages that are used by default; it says to @emph{not} use the
|
| 22036 | |
package. An argument that is neither @samp{yes} nor @samp{no} could
|
| 22037 | |
include a name or number of a version of the other package, to specify
|
| 22038 | |
more precisely which other package this program is supposed to work
|
| 22039 | |
with. If no argument is given, it defaults to @samp{yes}.
|
| 22040 | |
@option{--without-@var{package}} is equivalent to
|
| 22041 | |
@option{--with-@var{package}=no}.
|
| 22042 | |
|
| 22043 | |
Normally @command{configure} scripts complain about
|
| 22044 | |
@option{--with-@var{package}} options that they do not support.
|
| 22045 | |
@xref{Option Checking}, for details, and for how to override the
|
| 22046 | |
defaults.
|
| 22047 | |
|
| 22048 | |
For each external software package that may be used, @file{configure.ac}
|
| 22049 | |
should call @code{AC_ARG_WITH} to detect whether the @command{configure}
|
| 22050 | |
user asked to use it. Whether each package is used or not by default,
|
| 22051 | |
and which arguments are valid, is up to you.
|
| 22052 | |
|
| 22053 | |
@anchor{AC_ARG_WITH}
|
| 22054 | |
@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @
|
| 22055 | |
@ovar{action-if-given}, @ovar{action-if-not-given})
|
| 22056 | |
@acindex{ARG_WITH}
|
| 22057 | |
If the user gave @command{configure} the option @option{--with-@var{package}}
|
| 22058 | |
or @option{--without-@var{package}}, run shell commands
|
| 22059 | |
@var{action-if-given}. If neither option was given, run shell commands
|
| 22060 | |
@var{action-if-not-given}. The name @var{package} indicates another
|
| 22061 | |
software package that this program should work with. It should consist
|
| 22062 | |
only of alphanumeric characters, dashes, plus signs, and dots.
|
| 22063 | |
|
| 22064 | |
The option's argument is available to the shell commands
|
| 22065 | |
@var{action-if-given} in the shell variable @code{withval}, which is
|
| 22066 | |
actually just the value of the shell variable named
|
| 22067 | |
@code{with_@var{package}}, with any non-alphanumeric characters in
|
| 22068 | |
@var{package} changed into @samp{_}. You may use that variable instead,
|
| 22069 | |
if you wish.
|
| 22070 | |
|
| 22071 | |
The argument @var{help-string} is a description of the option that
|
| 22072 | |
looks like this:
|
| 22073 | |
@example
|
| 22074 | |
--with-readline support fancy command line editing
|
| 22075 | |
@end example
|
| 22076 | |
|
| 22077 | |
@noindent
|
| 22078 | |
@var{help-string} may be more than one line long, if more detail is
|
| 22079 | |
needed. Just make sure the columns line up in @samp{configure
|
| 22080 | |
--help}. Avoid tabs in the help string. The easiest way to provide the
|
| 22081 | |
proper leading whitespace is to format your @var{help-string} with the macro
|
| 22082 | |
@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
|
| 22083 | |
|
| 22084 | |
The following example shows how to use the @code{AC_ARG_WITH} macro in
|
| 22085 | |
a common situation. You want to let the user decide whether to enable
|
| 22086 | |
support for an external library (e.g., the readline library); if the user
|
| 22087 | |
specified neither @option{--with-readline} nor @option{--without-readline},
|
| 22088 | |
you want to enable support for readline only if the library is available
|
| 22089 | |
on the system.
|
| 22090 | |
|
| 22091 | |
@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
|
| 22092 | |
@example
|
| 22093 | |
AC_ARG_WITH([readline],
|
| 22094 | |
[AS_HELP_STRING([--with-readline],
|
| 22095 | |
[support fancy command line editing @@<:@@default=check@@:>@@])],
|
| 22096 | |
[],
|
| 22097 | |
[with_readline=check])
|
| 22098 | |
|
| 22099 | |
LIBREADLINE=
|
| 22100 | |
AS_IF([test "x$with_readline" != xno],
|
| 22101 | |
[AC_CHECK_LIB([readline], [main],
|
| 22102 | |
[AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
|
| 22103 | |
AC_DEFINE([HAVE_LIBREADLINE], [1],
|
| 22104 | |
[Define if you have libreadline])
|
| 22105 | |
],
|
| 22106 | |
[if test "x$with_readline" != xcheck; then
|
| 22107 | |
AC_MSG_FAILURE(
|
| 22108 | |
[--with-readline was given, but test for readline failed])
|
| 22109 | |
fi
|
| 22110 | |
], -lncurses)])
|
| 22111 | |
@end example
|
| 22112 | |
|
| 22113 | |
The next example shows how to use @code{AC_ARG_WITH} to give the user the
|
| 22114 | |
possibility to enable support for the readline library, in case it is still
|
| 22115 | |
experimental and not well tested, and is therefore disabled by default.
|
| 22116 | |
|
| 22117 | |
@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
|
| 22118 | |
@example
|
| 22119 | |
AC_ARG_WITH([readline],
|
| 22120 | |
[AS_HELP_STRING([--with-readline],
|
| 22121 | |
[enable experimental support for readline])],
|
| 22122 | |
[],
|
| 22123 | |
[with_readline=no])
|
| 22124 | |
|
| 22125 | |
LIBREADLINE=
|
| 22126 | |
AS_IF([test "x$with_readline" != xno],
|
| 22127 | |
[AC_CHECK_LIB([readline], [main],
|
| 22128 | |
[AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
|
| 22129 | |
AC_DEFINE([HAVE_LIBREADLINE], [1],
|
| 22130 | |
[Define if you have libreadline])
|
| 22131 | |
],
|
| 22132 | |
[AC_MSG_FAILURE(
|
| 22133 | |
[--with-readline was given, but test for readline failed])],
|
| 22134 | |
[-lncurses])])
|
| 22135 | |
@end example
|
| 22136 | |
|
| 22137 | |
The last example shows how to use @code{AC_ARG_WITH} to give the user the
|
| 22138 | |
possibility to disable support for the readline library, given that it is
|
| 22139 | |
an important feature and that it should be enabled by default.
|
| 22140 | |
|
| 22141 | |
@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
|
| 22142 | |
@example
|
| 22143 | |
AC_ARG_WITH([readline],
|
| 22144 | |
[AS_HELP_STRING([--without-readline],
|
| 22145 | |
[disable support for readline])],
|
| 22146 | |
[],
|
| 22147 | |
[with_readline=yes])
|
| 22148 | |
|
| 22149 | |
LIBREADLINE=
|
| 22150 | |
AS_IF([test "x$with_readline" != xno],
|
| 22151 | |
[AC_CHECK_LIB([readline], [main],
|
| 22152 | |
[AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
|
| 22153 | |
AC_DEFINE([HAVE_LIBREADLINE], [1],
|
| 22154 | |
[Define if you have libreadline])
|
| 22155 | |
],
|
| 22156 | |
[AC_MSG_FAILURE(
|
| 22157 | |
[readline test failed (--without-readline to disable)])],
|
| 22158 | |
[-lncurses])])
|
| 22159 | |
@end example
|
| 22160 | |
|
| 22161 | |
These three examples can be easily adapted to the case where
|
| 22162 | |
@code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
|
| 22163 | |
@ref{Package Options}).
|
| 22164 | |
@end defmac
|
| 22165 | |
|
| 22166 | |
@node Package Options
|
| 22167 | |
@section Choosing Package Options
|
| 22168 | |
@cindex Package options
|
| 22169 | |
@cindex Options, package
|
| 22170 | |
|
| 22171 | |
If a software package has optional compile-time features, the user can
|
| 22172 | |
give @command{configure} command line options to specify whether to
|
| 22173 | |
compile them. The options have one of these forms:
|
| 22174 | |
|
| 22175 | |
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
|
| 22176 | |
@c awful.
|
| 22177 | |
@example
|
| 22178 | |
--enable-@var{feature}@r{[}=@var{arg}@r{]}
|
| 22179 | |
--disable-@var{feature}
|
| 22180 | |
@end example
|
| 22181 | |
|
| 22182 | |
These options allow users to choose which optional features to build and
|
| 22183 | |
install. @option{--enable-@var{feature}} options should never make a
|
| 22184 | |
feature behave differently or cause one feature to replace another.
|
| 22185 | |
They should only cause parts of the program to be built rather than left
|
| 22186 | |
out.
|
| 22187 | |
|
| 22188 | |
The user can give an argument by following the feature name with
|
| 22189 | |
@samp{=} and the argument. Giving an argument of @samp{no} requests
|
| 22190 | |
that the feature @emph{not} be made available. A feature with an
|
| 22191 | |
argument looks like @option{--enable-debug=stabs}. If no argument is
|
| 22192 | |
given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
|
| 22193 | |
equivalent to @option{--enable-@var{feature}=no}.
|
| 22194 | |
|
| 22195 | |
Normally @command{configure} scripts complain about
|
| 22196 | |
@option{--enable-@var{package}} options that they do not support.
|
| 22197 | |
@xref{Option Checking}, for details, and for how to override the
|
| 22198 | |
defaults.
|
| 22199 | |
|
| 22200 | |
For each optional feature, @file{configure.ac} should call
|
| 22201 | |
@code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
|
| 22202 | |
to include it. Whether each feature is included or not by default, and
|
| 22203 | |
which arguments are valid, is up to you.
|
| 22204 | |
|
| 22205 | |
@anchor{AC_ARG_ENABLE}
|
| 22206 | |
@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @
|
| 22207 | |
@ovar{action-if-given}, @ovar{action-if-not-given})
|
| 22208 | |
@acindex{ARG_ENABLE}
|
| 22209 | |
If the user gave @command{configure} the option
|
| 22210 | |
@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
|
| 22211 | |
shell commands @var{action-if-given}. If neither option was given, run
|
| 22212 | |
shell commands @var{action-if-not-given}. The name @var{feature}
|
| 22213 | |
indicates an optional user-level facility. It should consist only of
|
| 22214 | |
alphanumeric characters, dashes, plus signs, and dots.
|
| 22215 | |
|
| 22216 | |
The option's argument is available to the shell commands
|
| 22217 | |
@var{action-if-given} in the shell variable @code{enableval}, which is
|
| 22218 | |
actually just the value of the shell variable named
|
| 22219 | |
@code{enable_@var{feature}}, with any non-alphanumeric characters in
|
| 22220 | |
@var{feature} changed into @samp{_}. You may use that variable instead,
|
| 22221 | |
if you wish. The @var{help-string} argument is like that of
|
| 22222 | |
@code{AC_ARG_WITH} (@pxref{External Software}).
|
| 22223 | |
|
| 22224 | |
You should format your @var{help-string} with the macro
|
| 22225 | |
@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
|
| 22226 | |
|
| 22227 | |
See the examples suggested with the definition of @code{AC_ARG_WITH}
|
| 22228 | |
(@pxref{External Software}) to get an idea of possible applications of
|
| 22229 | |
@code{AC_ARG_ENABLE}.
|
| 22230 | |
@end defmac
|
| 22231 | |
|
| 22232 | |
@node Pretty Help Strings
|
| 22233 | |
@section Making Your Help Strings Look Pretty
|
| 22234 | |
@cindex Help strings
|
| 22235 | |
|
| 22236 | |
Properly formatting the @samp{help strings} which are used in
|
| 22237 | |
@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
|
| 22238 | |
(@pxref{Package Options}) can be challenging. Specifically, you want
|
| 22239 | |
your own @samp{help strings} to line up in the appropriate columns of
|
| 22240 | |
@samp{configure --help} just like the standard Autoconf @samp{help
|
| 22241 | |
strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
|
| 22242 | |
|
| 22243 | |
@anchor{AS_HELP_STRING}
|
| 22244 | |
@defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side} @
|
| 22245 | |
@dvar{indent-column, 26}, @dvar{wrap-column, 79})
|
| 22246 | |
@asindex{HELP_STRING}
|
| 22247 | |
|
| 22248 | |
Expands into a help string that looks pretty when the user executes
|
| 22249 | |
@samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
|
| 22250 | |
(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
|
| 22251 | |
Options}). The following example makes this clearer.
|
| 22252 | |
|
| 22253 | |
@example
|
| 22254 | |
AC_ARG_WITH([foo],
|
| 22255 | |
[AS_HELP_STRING([--with-foo],
|
| 22256 | |
[use foo (default is no)])],
|
| 22257 | |
[use_foo=$withval],
|
| 22258 | |
[use_foo=no])
|
| 22259 | |
@end example
|
| 22260 | |
|
| 22261 | |
Then the last few lines of @samp{configure --help} appear like
|
| 22262 | |
this:
|
| 22263 | |
|
| 22264 | |
@example
|
| 22265 | |
--enable and --with options recognized:
|
| 22266 | |
--with-foo use foo (default is no)
|
| 22267 | |
@end example
|
| 22268 | |
|
| 22269 | |
Macro expansion is performed on the first argument. However, the second
|
| 22270 | |
argument of @code{AS_HELP_STRING} is treated as a whitespace separated
|
| 22271 | |
list of text to be reformatted, and is not subject to macro expansion.
|
| 22272 | |
Since it is not expanded, it should not be double quoted.
|
| 22273 | |
@xref{Autoconf Language}, for a more detailed explanation.
|
| 22274 | |
|
| 22275 | |
The @code{AS_HELP_STRING} macro is particularly helpful when the
|
| 22276 | |
@var{left-hand-side} and/or @var{right-hand-side} are composed of macro
|
| 22277 | |
arguments, as shown in the following example. Be aware that
|
| 22278 | |
@var{left-hand-side} may not expand to unbalanced quotes,
|
| 22279 | |
although quadrigraphs can be used.
|
| 22280 | |
|
| 22281 | |
@example
|
| 22282 | |
AC_DEFUN([MY_ARG_WITH],
|
| 22283 | |
[AC_ARG_WITH(m4_translit([[$1]], [_], [-]),
|
| 22284 | |
[AS_HELP_STRING([--with-m4_translit([$1], [_], [-])],
|
| 22285 | |
[use $1 (default is $2)])],
|
| 22286 | |
[use_[]$1=$withval],
|
| 22287 | |
[use_[]$1=$2])])
|
| 22288 | |
MY_ARG_WITH([a_b], [no])
|
| 22289 | |
@end example
|
| 22290 | |
@noindent
|
| 22291 | |
Here, the last few lines of @samp{configure --help} will include:
|
| 22292 | |
|
| 22293 | |
@example
|
| 22294 | |
--enable and --with options recognized:
|
| 22295 | |
--with-a-b use a_b (default is no)
|
| 22296 | |
@end example
|
| 22297 | |
|
| 22298 | |
The parameters @var{indent-column} and @var{wrap-column} were introduced
|
| 22299 | |
in Autoconf 2.62. Generally, they should not be specified; they exist
|
| 22300 | |
for fine-tuning of the wrapping.
|
| 22301 | |
@example
|
| 22302 | |
AS_HELP_STRING([--option], [description of option])
|
| 22303 | |
@result{} --option description of option
|
| 22304 | |
AS_HELP_STRING([--option], [description of option], [15], [30])
|
| 22305 | |
@result{} --option description of
|
| 22306 | |
@result{} option
|
| 22307 | |
@end example
|
| 22308 | |
@end defmac
|
| 22309 | |
|
| 22310 | |
|
| 22311 | |
@node Option Checking
|
| 22312 | |
@section Controlling Checking of @command{configure} Options
|
| 22313 | |
@cindex Options, Package
|
| 22314 | |
|
| 22315 | |
The @command{configure} script checks its command-line options against a
|
| 22316 | |
list of known options, like @option{--help} or @option{--config-cache}.
|
| 22317 | |
An unknown option ordinarily indicates a mistake by the user and
|
| 22318 | |
@command{configure} halts with an error. However, by default unknown
|
| 22319 | |
@option{--with-@var{package}} and @option{--enable-@var{feature}}
|
| 22320 | |
options elicit only a warning, to support configuring entire source
|
| 22321 | |
trees.
|
| 22322 | |
|
| 22323 | |
Source trees often contain multiple packages with a top-level
|
| 22324 | |
@command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
|
| 22325 | |
(@pxref{Subdirectories}). Because the packages generally support
|
| 22326 | |
different @option{--with-@var{package}} and
|
| 22327 | |
@option{--enable-@var{feature}} options, the GNU Coding
|
| 22328 | |
Standards say they must accept unrecognized options without halting.
|
| 22329 | |
Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
|
| 22330 | |
automatically disables the warnings.
|
| 22331 | |
|
| 22332 | |
This default behavior may be modified in two ways. First, the installer
|
| 22333 | |
can invoke @code{configure --disable-option-checking} to disable
|
| 22334 | |
these warnings, or invoke @code{configure --enable-option-checking=fatal}
|
| 22335 | |
options to turn them into fatal errors, respectively. Second, the
|
| 22336 | |
maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
|
| 22337 | |
|
| 22338 | |
@defmac AC_DISABLE_OPTION_CHECKING
|
| 22339 | |
@acindex{DISABLE_OPTION_CHECKING}
|
| 22340 | |
|
| 22341 | |
By default, disable warnings related to any unrecognized
|
| 22342 | |
@option{--with-@var{package}} or @option{--enable-@var{feature}}
|
| 22343 | |
options. This is implied by @code{AC_CONFIG_SUBDIRS}.
|
| 22344 | |
|
| 22345 | |
The installer can override this behavior by passing
|
| 22346 | |
@option{--enable-option-checking} (enable warnings) or
|
| 22347 | |
@option{--enable-option-checking=fatal} (enable errors) to
|
| 22348 | |
@command{configure}.
|
| 22349 | |
@end defmac
|
| 22350 | |
|
| 22351 | |
|
| 22352 | |
@node Site Details
|
| 22353 | |
@section Configuring Site Details
|
| 22354 | |
@cindex Site details
|
| 22355 | |
|
| 22356 | |
Some software packages require complex site-specific information. Some
|
| 22357 | |
examples are host names to use for certain services, company names, and
|
| 22358 | |
email addresses to contact. Since some configuration scripts generated
|
| 22359 | |
by Metaconfig ask for such information interactively, people sometimes
|
| 22360 | |
wonder how to get that information in Autoconf-generated configuration
|
| 22361 | |
scripts, which aren't interactive.
|
| 22362 | |
|
| 22363 | |
Such site configuration information should be put in a file that is
|
| 22364 | |
edited @emph{only by users}, not by programs. The location of the file
|
| 22365 | |
can either be based on the @code{prefix} variable, or be a standard
|
| 22366 | |
location such as the user's home directory. It could even be specified
|
| 22367 | |
by an environment variable. The programs should examine that file at
|
| 22368 | |
runtime, rather than at compile time. Runtime configuration is more
|
| 22369 | |
convenient for users and makes the configuration process simpler than
|
| 22370 | |
getting the information while configuring. @xref{Directory Variables, ,
|
| 22371 | |
Variables for Installation Directories, standards, The GNU Coding
|
| 22372 | |
Standards}, for more information on where to put data files.
|
| 22373 | |
|
| 22374 | |
@node Transforming Names
|
| 22375 | |
@section Transforming Program Names When Installing
|
| 22376 | |
@cindex Transforming program names
|
| 22377 | |
@cindex Program names, transforming
|
| 22378 | |
|
| 22379 | |
Autoconf supports changing the names of programs when installing them.
|
| 22380 | |
In order to use these transformations, @file{configure.ac} must call the
|
| 22381 | |
macro @code{AC_ARG_PROGRAM}.
|
| 22382 | |
|
| 22383 | |
@defmac AC_ARG_PROGRAM
|
| 22384 | |
@acindex{ARG_PROGRAM}
|
| 22385 | |
@ovindex program_transform_name
|
| 22386 | |
Place in output variable @code{program_transform_name} a sequence of
|
| 22387 | |
@code{sed} commands for changing the names of installed programs.
|
| 22388 | |
|
| 22389 | |
If any of the options described below are given to @command{configure},
|
| 22390 | |
program names are transformed accordingly. Otherwise, if
|
| 22391 | |
@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
|
| 22392 | |
is given, the target type followed by a dash is used as a prefix.
|
| 22393 | |
Otherwise, no program name transformation is done.
|
| 22394 | |
@end defmac
|
| 22395 | |
|
| 22396 | |
@menu
|
| 22397 | |
* Transformation Options:: @command{configure} options to transform names
|
| 22398 | |
* Transformation Examples:: Sample uses of transforming names
|
| 22399 | |
* Transformation Rules:: Makefile uses of transforming names
|
| 22400 | |
@end menu
|
| 22401 | |
|
| 22402 | |
@node Transformation Options
|
| 22403 | |
@subsection Transformation Options
|
| 22404 | |
|
| 22405 | |
You can specify name transformations by giving @command{configure} these
|
| 22406 | |
command line options:
|
| 22407 | |
|
| 22408 | |
@table @option
|
| 22409 | |
@item --program-prefix=@var{prefix}
|
| 22410 | |
prepend @var{prefix} to the names;
|
| 22411 | |
|
| 22412 | |
@item --program-suffix=@var{suffix}
|
| 22413 | |
append @var{suffix} to the names;
|
| 22414 | |
|
| 22415 | |
@item --program-transform-name=@var{expression}
|
| 22416 | |
perform @code{sed} substitution @var{expression} on the names.
|
| 22417 | |
@end table
|
| 22418 | |
|
| 22419 | |
@node Transformation Examples
|
| 22420 | |
@subsection Transformation Examples
|
| 22421 | |
|
| 22422 | |
These transformations are useful with programs that can be part of a
|
| 22423 | |
cross-compilation development environment. For example, a
|
| 22424 | |
cross-assembler running on a Sun 4 configured with
|
| 22425 | |
@option{--target=i960-vxworks} is normally installed as
|
| 22426 | |
@file{i960-vxworks-as}, rather than @file{as}, which could be confused
|
| 22427 | |
with a native Sun 4 assembler.
|
| 22428 | |
|
| 22429 | |
You can force a program name to begin with @file{g}, if you don't want
|
| 22430 | |
GNU programs installed on your system to shadow other programs with
|
| 22431 | |
the same name. For example, if you configure GNU @code{diff} with
|
| 22432 | |
@option{--program-prefix=g}, then when you run @samp{make install} it is
|
| 22433 | |
installed as @file{/usr/local/bin/gdiff}.
|
| 22434 | |
|
| 22435 | |
As a more sophisticated example, you could use
|
| 22436 | |
|
| 22437 | |
@example
|
| 22438 | |
--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
|
| 22439 | |
@end example
|
| 22440 | |
@noindent
|
| 22441 | |
|
| 22442 | |
to prepend @samp{g} to most of the program names in a source tree,
|
| 22443 | |
excepting those like @code{gdb} that already have one and those like
|
| 22444 | |
@code{less} and @code{lesskey} that aren't GNU programs. (That is
|
| 22445 | |
assuming that you have a source tree containing those programs that is
|
| 22446 | |
set up to use this feature.)
|
| 22447 | |
|
| 22448 | |
One way to install multiple versions of some programs simultaneously is
|
| 22449 | |
to append a version number to the name of one or both. For example, if
|
| 22450 | |
you want to keep Autoconf version 1 around for awhile, you can configure
|
| 22451 | |
Autoconf version 2 using @option{--program-suffix=2} to install the
|
| 22452 | |
programs as @file{/usr/local/bin/autoconf2},
|
| 22453 | |
@file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
|
| 22454 | |
that only the binaries are renamed, therefore you'd have problems with
|
| 22455 | |
the library files which might overlap.
|
| 22456 | |
|
| 22457 | |
@node Transformation Rules
|
| 22458 | |
@subsection Transformation Rules
|
| 22459 | |
|
| 22460 | |
Here is how to use the variable @code{program_transform_name} in a
|
| 22461 | |
@file{Makefile.in}:
|
| 22462 | |
|
| 22463 | |
@example
|
| 22464 | |
PROGRAMS = cp ls rm
|
| 22465 | |
transform = @@program_transform_name@@
|
| 22466 | |
install:
|
| 22467 | |
for p in $(PROGRAMS); do \
|
| 22468 | |
$(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
|
| 22469 | |
sed '$(transform)'`; \
|
| 22470 | |
done
|
| 22471 | |
|
| 22472 | |
uninstall:
|
| 22473 | |
for p in $(PROGRAMS); do \
|
| 22474 | |
rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
|
| 22475 | |
@c $$ restore font-lock
|
| 22476 | |
done
|
| 22477 | |
@end example
|
| 22478 | |
|
| 22479 | |
It is guaranteed that @code{program_transform_name} is never empty, and
|
| 22480 | |
that there are no useless separators. Therefore you may safely embed
|
| 22481 | |
@code{program_transform_name} within a sed program using @samp{;}:
|
| 22482 | |
|
| 22483 | |
@example
|
| 22484 | |
transform = @@program_transform_name@@
|
| 22485 | |
transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
|
| 22486 | |
@end example
|
| 22487 | |
|
| 22488 | |
Whether to do the transformations on documentation files (Texinfo or
|
| 22489 | |
@code{man}) is a tricky question; there seems to be no perfect answer,
|
| 22490 | |
due to the several reasons for name transforming. Documentation is not
|
| 22491 | |
usually particular to a specific architecture, and Texinfo files do not
|
| 22492 | |
conflict with system documentation. But they might conflict with
|
| 22493 | |
earlier versions of the same files, and @code{man} pages sometimes do
|
| 22494 | |
conflict with system documentation. As a compromise, it is probably
|
| 22495 | |
best to do name transformations on @code{man} pages but not on Texinfo
|
| 22496 | |
manuals.
|
| 22497 | |
|
| 22498 | |
@node Site Defaults
|
| 22499 | |
@section Setting Site Defaults
|
| 22500 | |
@cindex Site defaults
|
| 22501 | |
@cindex config.site
|
| 22502 | |
|
| 22503 | |
Autoconf-generated @command{configure} scripts allow your site to provide
|
| 22504 | |
default values for some configuration values. You do this by creating
|
| 22505 | |
site- and system-wide initialization files.
|
| 22506 | |
|
| 22507 | |
@evindex CONFIG_SITE
|
| 22508 | |
If the environment variable @code{CONFIG_SITE} is set, @command{configure}
|
| 22509 | |
uses its value as the name of a shell script to read; it is recommended
|
| 22510 | |
that this be an absolute file name. Otherwise, it
|
| 22511 | |
reads the shell script @file{@var{prefix}/share/config.site} if it exists,
|
| 22512 | |
then @file{@var{prefix}/etc/config.site} if it exists. Thus,
|
| 22513 | |
settings in machine-specific files override those in machine-independent
|
| 22514 | |
ones in case of conflict.
|
| 22515 | |
|
| 22516 | |
Site files can be arbitrary shell scripts, but only certain kinds of
|
| 22517 | |
code are really appropriate to be in them. Because @command{configure}
|
| 22518 | |
reads any cache file after it has read any site files, a site file can
|
| 22519 | |
define a default cache file to be shared between all Autoconf-generated
|
| 22520 | |
@command{configure} scripts run on that system (@pxref{Cache Files}). If
|
| 22521 | |
you set a default cache file in a site file, it is a good idea to also
|
| 22522 | |
set the output variable @code{CC} in that site file, because the cache
|
| 22523 | |
file is only valid for a particular compiler, but many systems have
|
| 22524 | |
several available.
|
| 22525 | |
|
| 22526 | |
You can examine or override the value set by a command line option to
|
| 22527 | |
@command{configure} in a site file; options set shell variables that have
|
| 22528 | |
the same names as the options, with any dashes turned into underscores.
|
| 22529 | |
The exceptions are that @option{--without-} and @option{--disable-} options
|
| 22530 | |
are like giving the corresponding @option{--with-} or @option{--enable-}
|
| 22531 | |
option and the value @samp{no}. Thus, @option{--cache-file=localcache}
|
| 22532 | |
sets the variable @code{cache_file} to the value @samp{localcache};
|
| 22533 | |
@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
|
| 22534 | |
@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
|
| 22535 | |
variable @code{prefix} to the value @samp{/usr}; etc.
|
| 22536 | |
|
| 22537 | |
Site files are also good places to set default values for other output
|
| 22538 | |
variables, such as @code{CFLAGS}, if you need to give them non-default
|
| 22539 | |
values: anything you would normally do, repetitively, on the command
|
| 22540 | |
line. If you use non-default values for @var{prefix} or
|
| 22541 | |
@var{exec_prefix} (wherever you locate the site file), you can set them
|
| 22542 | |
in the site file if you specify it with the @code{CONFIG_SITE}
|
| 22543 | |
environment variable.
|
| 22544 | |
|
| 22545 | |
You can set some cache values in the site file itself. Doing this is
|
| 22546 | |
useful if you are cross-compiling, where it is impossible to check features
|
| 22547 | |
that require running a test program. You could ``prime the cache'' by
|
| 22548 | |
setting those values correctly for that system in
|
| 22549 | |
@file{@var{prefix}/etc/config.site}. To find out the names of the cache
|
| 22550 | |
variables you need to set, see the documentation of the respective
|
| 22551 | |
Autoconf macro. If the variables or their semantics are undocumented,
|
| 22552 | |
you may need to look for shell variables with @samp{_cv_} in their names
|
| 22553 | |
in the affected @command{configure} scripts, or in the Autoconf M4
|
| 22554 | |
source code for those macros; but in that case, their name or semantics
|
| 22555 | |
may change in a future Autoconf version.
|
| 22556 | |
|
| 22557 | |
The cache file is careful to not override any variables set in the site
|
| 22558 | |
files. Similarly, you should not override command-line options in the
|
| 22559 | |
site files. Your code should check that variables such as @code{prefix}
|
| 22560 | |
and @code{cache_file} have their default values (as set near the top of
|
| 22561 | |
@command{configure}) before changing them.
|
| 22562 | |
|
| 22563 | |
Here is a sample file @file{/usr/share/local/@/gnu/share/@/config.site}. The
|
| 22564 | |
command @samp{configure --prefix=/usr/share/local/gnu} would read this
|
| 22565 | |
file (if @code{CONFIG_SITE} is not set to a different file).
|
| 22566 | |
|
| 22567 | |
@example
|
| 22568 | |
# /usr/share/local/gnu/share/config.site for configure
|
| 22569 | |
#
|
| 22570 | |
# Change some defaults.
|
| 22571 | |
test "$prefix" = NONE && prefix=/usr/share/local/gnu
|
| 22572 | |
test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
|
| 22573 | |
test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var
|
| 22574 | |
test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var
|
| 22575 | |
|
| 22576 | |
# Give Autoconf 2.x generated configure scripts a shared default
|
| 22577 | |
# cache file for feature test results, architecture-specific.
|
| 22578 | |
if test "$cache_file" = /dev/null; then
|
| 22579 | |
cache_file="$prefix/var/config.cache"
|
| 22580 | |
# A cache file is only valid for one C compiler.
|
| 22581 | |
CC=gcc
|
| 22582 | |
fi
|
| 22583 | |
@end example
|
| 22584 | |
|
| 22585 | |
@c Leave this use of ``File system'' rendered as one word, but
|
| 22586 | |
@c slightly obfuscated so as not to trigger the syntax-check prohibition.
|
| 22587 | |
@cindex File@/system Hierarchy Standard
|
| 22588 | |
@cindex FHS
|
| 22589 | |
|
| 22590 | |
Another use of @file{config.site} is for priming the directory variables
|
| 22591 | |
@c ``File system'', but slightly obfuscated, as above.
|
| 22592 | |
in a manner consistent with the File@/system Hierarchy Standard
|
| 22593 | |
(FHS). Once the following file is installed at
|
| 22594 | |
@file{/usr/share/config.site}, a user can execute simply
|
| 22595 | |
@code{./configure --prefix=/usr} to get all the directories chosen in
|
| 22596 | |
the locations recommended by FHS.
|
| 22597 | |
|
| 22598 | |
@example
|
| 22599 | |
# /usr/share/config.site for FHS defaults when installing below /usr,
|
| 22600 | |
# and the respective settings were not changed on the command line.
|
| 22601 | |
if test "$prefix" = /usr; then
|
| 22602 | |
test "$sysconfdir" = '$@{prefix@}/etc' && sysconfdir=/etc
|
| 22603 | |
test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var
|
| 22604 | |
test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var
|
| 22605 | |
fi
|
| 22606 | |
@end example
|
| 22607 | |
|
| 22608 | |
@cindex @file{lib64}
|
| 22609 | |
@cindex 64-bit libraries
|
| 22610 | |
Likewise, on platforms where 64-bit libraries are built by default, then
|
| 22611 | |
installed in @file{/usr/local/@/lib64} instead of @file{/usr/local/@/lib},
|
| 22612 | |
it is appropriate to install @file{/usr/local/@/share/config.site}:
|
| 22613 | |
|
| 22614 | |
@example
|
| 22615 | |
# /usr/local/share/config.site for platforms that prefer
|
| 22616 | |
# the directory /usr/local/lib64 over /usr/local/lib.
|
| 22617 | |
test "$libdir" = '$@{exec_prefix@}/lib' && libdir='$@{exec_prefix@}/lib64'
|
| 22618 | |
@end example
|
| 22619 | |
|
| 22620 | |
|
| 22621 | |
@c ============================================== Running configure Scripts.
|
| 22622 | |
|
| 22623 | |
@node Running configure Scripts
|
| 22624 | |
@chapter Running @command{configure} Scripts
|
| 22625 | |
@cindex @command{configure}
|
| 22626 | |
|
| 22627 | |
Below are instructions on how to configure a package that uses a
|
| 22628 | |
@command{configure} script, suitable for inclusion as an @file{INSTALL}
|
| 22629 | |
file in the package. A plain-text version of @file{INSTALL} which you
|
| 22630 | |
may use comes with Autoconf.
|
| 22631 | |
|
| 22632 | |
@menu
|
| 22633 | |
* Basic Installation:: Instructions for typical cases
|
| 22634 | |
* Compilers and Options:: Selecting compilers and optimization
|
| 22635 | |
* Multiple Architectures:: Compiling for multiple architectures at once
|
| 22636 | |
* Installation Names:: Installing in different directories
|
| 22637 | |
* Optional Features:: Selecting optional features
|
| 22638 | |
* Particular Systems:: Particular systems
|
| 22639 | |
* System Type:: Specifying the system type
|
| 22640 | |
* Sharing Defaults:: Setting site-wide defaults for @command{configure}
|
| 22641 | |
* Defining Variables:: Specifying the compiler etc.
|
| 22642 | |
* configure Invocation:: Changing how @command{configure} runs
|
| 22643 | |
@end menu
|
| 22644 | |
|
| 22645 | |
@set autoconf
|
| 22646 | |
@include install.texi
|
| 22647 | |
|
| 22648 | |
|
| 22649 | |
@c ============================================== config.status Invocation
|
| 22650 | |
|
| 22651 | |
@node config.status Invocation
|
| 22652 | |
@chapter config.status Invocation
|
| 22653 | |
@cindex @command{config.status}
|
| 22654 | |
|
| 22655 | |
The @command{configure} script creates a file named @file{config.status},
|
| 22656 | |
which actually configures, @dfn{instantiates}, the template files. It
|
| 22657 | |
also records the configuration options that were specified when the
|
| 22658 | |
package was last configured in case reconfiguring is needed.
|
| 22659 | |
|
| 22660 | |
Synopsis:
|
| 22661 | |
@example
|
| 22662 | |
./config.status @ovar{option}@dots{} @ovar{tag}@dots{}
|
| 22663 | |
@end example
|
| 22664 | |
|
| 22665 | |
It configures each @var{tag}; if none are specified, all the templates
|
| 22666 | |
are instantiated. A @var{tag} refers to a file or other tag associated
|
| 22667 | |
with a configuration action, as specified by an @code{AC_CONFIG_@var{ITEMS}}
|
| 22668 | |
macro (@pxref{Configuration Actions}). The files must be specified
|
| 22669 | |
without their dependencies, as in
|
| 22670 | |
|
| 22671 | |
@example
|
| 22672 | |
./config.status foobar
|
| 22673 | |
@end example
|
| 22674 | |
|
| 22675 | |
@noindent
|
| 22676 | |
not
|
| 22677 | |
|
| 22678 | |
@example
|
| 22679 | |
./config.status foobar:foo.in:bar.in
|
| 22680 | |
@end example
|
| 22681 | |
|
| 22682 | |
The supported options are:
|
| 22683 | |
|
| 22684 | |
@table @option
|
| 22685 | |
@item --help
|
| 22686 | |
@itemx -h
|
| 22687 | |
Print a summary of the command line options, the list of the template
|
| 22688 | |
files, and exit.
|
| 22689 | |
|
| 22690 | |
@item --version
|
| 22691 | |
@itemx -V
|
| 22692 | |
Print the version number of Autoconf and the configuration settings,
|
| 22693 | |
and exit.
|
| 22694 | |
|
| 22695 | |
@item --config
|
| 22696 | |
Print the configuration settings in reusable way, quoted for the shell,
|
| 22697 | |
and exit. For example, for a debugging build that otherwise reuses the
|
| 22698 | |
configuration from a different build directory @var{build-dir} of a
|
| 22699 | |
package in @var{src-dir}, you could use the following:
|
| 22700 | |
|
| 22701 | |
@example
|
| 22702 | |
args=`@var{build-dir}/config.status --config`
|
| 22703 | |
eval @var{src-dir}/configure "$args" CFLAGS=-g --srcdir=@var{src-dir}
|
| 22704 | |
@end example
|
| 22705 | |
|
| 22706 | |
@noindent
|
| 22707 | |
Note that it may be necessary to override a @option{--srcdir} setting
|
| 22708 | |
that was saved in the configuration, if the arguments are used in a
|
| 22709 | |
different build directory.
|
| 22710 | |
|
| 22711 | |
@item --silent
|
| 22712 | |
@itemx --quiet
|
| 22713 | |
@itemx -q
|
| 22714 | |
Do not print progress messages.
|
| 22715 | |
|
| 22716 | |
@item --debug
|
| 22717 | |
@itemx -d
|
| 22718 | |
Don't remove the temporary files.
|
| 22719 | |
|
| 22720 | |
@item --file=@var{file}[:@var{template}]
|
| 22721 | |
Require that @var{file} be instantiated as if
|
| 22722 | |
@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
|
| 22723 | |
@var{file} and @var{template} may be @samp{-} in which case the standard
|
| 22724 | |
output and/or standard input, respectively, is used. If a
|
| 22725 | |
@var{template} file name is relative, it is first looked for in the build
|
| 22726 | |
tree, and then in the source tree. @xref{Configuration Actions}, for
|
| 22727 | |
more details.
|
| 22728 | |
|
| 22729 | |
This option and the following ones provide one way for separately
|
| 22730 | |
distributed packages to share the values computed by @command{configure}.
|
| 22731 | |
Doing so can be useful if some of the packages need a superset of the
|
| 22732 | |
features that one of them, perhaps a common library, does. These
|
| 22733 | |
options allow a @file{config.status} file to create files other than the
|
| 22734 | |
ones that its @file{configure.ac} specifies, so it can be used for a
|
| 22735 | |
different package, or for extracting a subset of values. For example,
|
| 22736 | |
|
| 22737 | |
@example
|
| 22738 | |
echo '@@CC@@' | ./config.status --file=-
|
| 22739 | |
@end example
|
| 22740 | |
|
| 22741 | |
@noindent
|
| 22742 | |
provides the value of @code{@@CC@@} on standard output.
|
| 22743 | |
|
| 22744 | |
@item --header=@var{file}[:@var{template}]
|
| 22745 | |
Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
|
| 22746 | |
|
| 22747 | |
@item --recheck
|
| 22748 | |
Ask @file{config.status} to update itself and exit (no instantiation).
|
| 22749 | |
This option is useful if you change @command{configure}, so that the
|
| 22750 | |
results of some tests might be different from the previous run. The
|
| 22751 | |
@option{--recheck} option reruns @command{configure} with the same arguments
|
| 22752 | |
you used before, plus the @option{--no-create} option, which prevents
|
| 22753 | |
@command{configure} from running @file{config.status} and creating
|
| 22754 | |
@file{Makefile} and other files, and the @option{--no-recursion} option,
|
| 22755 | |
which prevents @command{configure} from running other @command{configure}
|
| 22756 | |
scripts in subdirectories. (This is so other Make rules can
|
| 22757 | |
run @file{config.status} when it changes; @pxref{Automatic Remaking},
|
| 22758 | |
for an example).
|
| 22759 | |
@end table
|
| 22760 | |
|
| 22761 | |
@file{config.status} checks several optional environment variables that
|
| 22762 | |
can alter its behavior:
|
| 22763 | |
|
| 22764 | |
@anchor{CONFIG_SHELL}
|
| 22765 | |
@defvar CONFIG_SHELL
|
| 22766 | |
@evindex CONFIG_SHELL
|
| 22767 | |
The shell with which to run @command{configure}. It must be
|
| 22768 | |
Bourne-compatible, and the absolute name of the shell should be passed.
|
| 22769 | |
The default is a shell that supports @code{LINENO} if available, and
|
| 22770 | |
@file{/bin/sh} otherwise.
|
| 22771 | |
@end defvar
|
| 22772 | |
|
| 22773 | |
@defvar CONFIG_STATUS
|
| 22774 | |
@evindex CONFIG_STATUS
|
| 22775 | |
The file name to use for the shell script that records the
|
| 22776 | |
configuration. The default is @file{./config.status}. This variable is
|
| 22777 | |
useful when one package uses parts of another and the @command{configure}
|
| 22778 | |
scripts shouldn't be merged because they are maintained separately.
|
| 22779 | |
@end defvar
|
| 22780 | |
|
| 22781 | |
You can use @file{./config.status} in your makefiles. For example, in
|
| 22782 | |
the dependencies given above (@pxref{Automatic Remaking}),
|
| 22783 | |
@file{config.status} is run twice when @file{configure.ac} has changed.
|
| 22784 | |
If that bothers you, you can make each run only regenerate the files for
|
| 22785 | |
that rule:
|
| 22786 | |
@example
|
| 22787 | |
@group
|
| 22788 | |
config.h: stamp-h
|
| 22789 | |
stamp-h: config.h.in config.status
|
| 22790 | |
./config.status config.h
|
| 22791 | |
echo > stamp-h
|
| 22792 | |
|
| 22793 | |
Makefile: Makefile.in config.status
|
| 22794 | |
./config.status Makefile
|
| 22795 | |
@end group
|
| 22796 | |
@end example
|
| 22797 | |
|
| 22798 | |
The calling convention of @file{config.status} has changed; see
|
| 22799 | |
@ref{Obsolete config.status Use}, for details.
|
| 22800 | |
|
| 22801 | |
|
| 22802 | |
@c =================================================== Obsolete Constructs
|
| 22803 | |
|
| 22804 | |
@node Obsolete Constructs
|
| 22805 | |
@chapter Obsolete Constructs
|
| 22806 | |
@cindex Obsolete constructs
|
| 22807 | |
|
| 22808 | |
Autoconf changes, and throughout the years some constructs have been
|
| 22809 | |
obsoleted. Most of the changes involve the macros, but in some cases
|
| 22810 | |
the tools themselves, or even some concepts, are now considered
|
| 22811 | |
obsolete.
|
| 22812 | |
|
| 22813 | |
You may completely skip this chapter if you are new to Autoconf. Its
|
| 22814 | |
intention is mainly to help maintainers updating their packages by
|
| 22815 | |
understanding how to move to more modern constructs.
|
| 22816 | |
|
| 22817 | |
@menu
|
| 22818 | |
* Obsolete config.status Use:: Obsolete convention for @command{config.status}
|
| 22819 | |
* acconfig Header:: Additional entries in @file{config.h.in}
|
| 22820 | |
* autoupdate Invocation:: Automatic update of @file{configure.ac}
|
| 22821 | |
* Obsolete Macros:: Backward compatibility macros
|
| 22822 | |
* Autoconf 1:: Tips for upgrading your files
|
| 22823 | |
* Autoconf 2.13:: Some fresher tips
|
| 22824 | |
@end menu
|
| 22825 | |
|
| 22826 | |
@node Obsolete config.status Use
|
| 22827 | |
@section Obsolete @file{config.status} Invocation
|
| 22828 | |
|
| 22829 | |
@file{config.status} now supports arguments to specify the files to
|
| 22830 | |
instantiate; see @ref{config.status Invocation}, for more details.
|
| 22831 | |
Before, environment variables had to be used.
|
| 22832 | |
|
| 22833 | |
@defvar CONFIG_COMMANDS
|
| 22834 | |
@evindex CONFIG_COMMANDS
|
| 22835 | |
The tags of the commands to execute. The default is the arguments given
|
| 22836 | |
to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
|
| 22837 | |
@file{configure.ac}.
|
| 22838 | |
@end defvar
|
| 22839 | |
|
| 22840 | |
@defvar CONFIG_FILES
|
| 22841 | |
@evindex CONFIG_FILES
|
| 22842 | |
The files in which to perform @samp{@@@var{variable}@@} substitutions.
|
| 22843 | |
The default is the arguments given to @code{AC_OUTPUT} and
|
| 22844 | |
@code{AC_CONFIG_FILES} in @file{configure.ac}.
|
| 22845 | |
@end defvar
|
| 22846 | |
|
| 22847 | |
@defvar CONFIG_HEADERS
|
| 22848 | |
@evindex CONFIG_HEADERS
|
| 22849 | |
The files in which to substitute C @code{#define} statements. The
|
| 22850 | |
default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
|
| 22851 | |
macro was not called, @file{config.status} ignores this variable.
|
| 22852 | |
@end defvar
|
| 22853 | |
|
| 22854 | |
@defvar CONFIG_LINKS
|
| 22855 | |
@evindex CONFIG_LINKS
|
| 22856 | |
The symbolic links to establish. The default is the arguments given to
|
| 22857 | |
@code{AC_CONFIG_LINKS}; if that macro was not called,
|
| 22858 | |
@file{config.status} ignores this variable.
|
| 22859 | |
@end defvar
|
| 22860 | |
|
| 22861 | |
In @ref{config.status Invocation}, using this old interface, the example
|
| 22862 | |
would be:
|
| 22863 | |
|
| 22864 | |
@example
|
| 22865 | |
@group
|
| 22866 | |
config.h: stamp-h
|
| 22867 | |
stamp-h: config.h.in config.status
|
| 22868 | |
CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
|
| 22869 | |
CONFIG_HEADERS=config.h ./config.status
|
| 22870 | |
echo > stamp-h
|
| 22871 | |
|
| 22872 | |
Makefile: Makefile.in config.status
|
| 22873 | |
CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
|
| 22874 | |
CONFIG_FILES=Makefile ./config.status
|
| 22875 | |
@end group
|
| 22876 | |
@end example
|
| 22877 | |
|
| 22878 | |
@noindent
|
| 22879 | |
(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
|
| 22880 | |
no need to set @code{CONFIG_HEADERS} in the @command{make} rules. Equally
|
| 22881 | |
for @code{CONFIG_COMMANDS}, etc.)
|
| 22882 | |
|
| 22883 | |
|
| 22884 | |
@node acconfig Header
|
| 22885 | |
@section @file{acconfig.h}
|
| 22886 | |
|
| 22887 | |
@cindex @file{acconfig.h}
|
| 22888 | |
@cindex @file{config.h.top}
|
| 22889 | |
@cindex @file{config.h.bot}
|
| 22890 | |
|
| 22891 | |
In order to produce @file{config.h.in}, @command{autoheader} needs to
|
| 22892 | |
build or to find templates for each symbol. Modern releases of Autoconf
|
| 22893 | |
use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
|
| 22894 | |
Macros}), but in older releases a file, @file{acconfig.h}, contained the
|
| 22895 | |
list of needed templates. @command{autoheader} copied comments and
|
| 22896 | |
@code{#define} and @code{#undef} statements from @file{acconfig.h} in
|
| 22897 | |
the current directory, if present. This file used to be mandatory if
|
| 22898 | |
you @code{AC_DEFINE} any additional symbols.
|
| 22899 | |
|
| 22900 | |
Modern releases of Autoconf also provide @code{AH_TOP} and
|
| 22901 | |
@code{AH_BOTTOM} if you need to prepend/append some information to
|
| 22902 | |
@file{config.h.in}. Ancient versions of Autoconf had a similar feature:
|
| 22903 | |
if @file{./acconfig.h} contains the string @samp{@@TOP@@},
|
| 22904 | |
@command{autoheader} copies the lines before the line containing
|
| 22905 | |
@samp{@@TOP@@} into the top of the file that it generates. Similarly,
|
| 22906 | |
if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
|
| 22907 | |
@command{autoheader} copies the lines after that line to the end of the
|
| 22908 | |
file it generates. Either or both of those strings may be omitted. An
|
| 22909 | |
even older alternate way to produce the same effect in ancient versions
|
| 22910 | |
of Autoconf is to create the files @file{@var{file}.top} (typically
|
| 22911 | |
@file{config.h.top}) and/or @file{@var{file}.bot} in the current
|
| 22912 | |
directory. If they exist, @command{autoheader} copies them to the
|
| 22913 | |
beginning and end, respectively, of its output.
|
| 22914 | |
|
| 22915 | |
In former versions of Autoconf, the files used in preparing a software
|
| 22916 | |
package for distribution were:
|
| 22917 | |
@example
|
| 22918 | |
@group
|
| 22919 | |
configure.ac --. .------> autoconf* -----> configure
|
| 22920 | |
+---+
|
| 22921 | |
[aclocal.m4] --+ `---.
|
| 22922 | |
[acsite.m4] ---' |
|
| 22923 | |
+--> [autoheader*] -> [config.h.in]
|
| 22924 | |
[acconfig.h] ----. |
|
| 22925 | |
+-----'
|
| 22926 | |
[config.h.top] --+
|
| 22927 | |
[config.h.bot] --'
|
| 22928 | |
@end group
|
| 22929 | |
@end example
|
| 22930 | |
|
| 22931 | |
Using only the @code{AH_} macros, @file{configure.ac} should be
|
| 22932 | |
self-contained, and should not depend upon @file{acconfig.h} etc.
|
| 22933 | |
|
| 22934 | |
|
| 22935 | |
@node autoupdate Invocation
|
| 22936 | |
@section Using @command{autoupdate} to Modernize @file{configure.ac}
|
| 22937 | |
@cindex @command{autoupdate}
|
| 22938 | |
|
| 22939 | |
The @command{autoupdate} program updates a @file{configure.ac} file that
|
| 22940 | |
calls Autoconf macros by their old names to use the current macro names.
|
| 22941 | |
In version 2 of Autoconf, most of the macros were renamed to use a more
|
| 22942 | |
uniform and descriptive naming scheme. @xref{Macro Names}, for a
|
| 22943 | |
description of the new scheme. Although the old names still work
|
| 22944 | |
(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
|
| 22945 | |
new names), you can make your @file{configure.ac} files more readable
|
| 22946 | |
and make it easier to use the current Autoconf documentation if you
|
| 22947 | |
update them to use the new macro names.
|
| 22948 | |
|
| 22949 | |
@evindex SIMPLE_BACKUP_SUFFIX
|
| 22950 | |
If given no arguments, @command{autoupdate} updates @file{configure.ac},
|
| 22951 | |
backing up the original version with the suffix @file{~} (or the value
|
| 22952 | |
of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
|
| 22953 | |
set). If you give @command{autoupdate} an argument, it reads that file
|
| 22954 | |
instead of @file{configure.ac} and writes the updated file to the
|
| 22955 | |
standard output.
|
| 22956 | |
|
| 22957 | |
@noindent
|
| 22958 | |
@command{autoupdate} accepts the following options:
|
| 22959 | |
|
| 22960 | |
@table @option
|
| 22961 | |
@item --help
|
| 22962 | |
@itemx -h
|
| 22963 | |
Print a summary of the command line options and exit.
|
| 22964 | |
|
| 22965 | |
@item --version
|
| 22966 | |
@itemx -V
|
| 22967 | |
Print the version number of Autoconf and exit.
|
| 22968 | |
|
| 22969 | |
@item --verbose
|
| 22970 | |
@itemx -v
|
| 22971 | |
Report processing steps.
|
| 22972 | |
|
| 22973 | |
@item --debug
|
| 22974 | |
@itemx -d
|
| 22975 | |
Don't remove the temporary files.
|
| 22976 | |
|
| 22977 | |
@item --force
|
| 22978 | |
@itemx -f
|
| 22979 | |
Force the update even if the file has not changed. Disregard the cache.
|
| 22980 | |
|
| 22981 | |
@item --include=@var{dir}
|
| 22982 | |
@itemx -I @var{dir}
|
| 22983 | |
Also look for input files in @var{dir}. Multiple invocations accumulate.
|
| 22984 | |
Directories are browsed from last to first.
|
| 22985 | |
|
| 22986 | |
@item --prepend-include=@var{dir}
|
| 22987 | |
@itemx -B @var{dir}
|
| 22988 | |
Prepend directory @var{dir} to the search path. This is used to include
|
| 22989 | |
the language-specific files before any third-party macros.
|
| 22990 | |
@end table
|
| 22991 | |
|
| 22992 | |
@node Obsolete Macros
|
| 22993 | |
@section Obsolete Macros
|
| 22994 | |
|
| 22995 | |
Several macros are obsoleted in Autoconf, for various reasons (typically
|
| 22996 | |
they failed to quote properly, couldn't be extended for more recent
|
| 22997 | |
issues, etc.). They are still supported, but deprecated: their use
|
| 22998 | |
should be avoided.
|
| 22999 | |
|
| 23000 | |
During the jump from Autoconf version 1 to version 2, most of the
|
| 23001 | |
macros were renamed to use a more uniform and descriptive naming scheme,
|
| 23002 | |
but their signature did not change. @xref{Macro Names}, for a
|
| 23003 | |
description of the new naming scheme. Below, if there is just the mapping
|
| 23004 | |
from old names to new names for these macros, the reader is invited to
|
| 23005 | |
refer to the definition of the new macro for the signature and the
|
| 23006 | |
description.
|
| 23007 | |
|
| 23008 | |
@defmac AC_AIX
|
| 23009 | |
@acindex{AIX}
|
| 23010 | |
@cvindex _ALL_SOURCE
|
| 23011 | |
This macro is a platform-specific subset of
|
| 23012 | |
@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
|
| 23013 | |
@end defmac
|
| 23014 | |
|
| 23015 | |
@defmac AC_ALLOCA
|
| 23016 | |
@acindex{ALLOCA}
|
| 23017 | |
Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}).
|
| 23018 | |
@end defmac
|
| 23019 | |
|
| 23020 | |
@defmac AC_ARG_ARRAY
|
| 23021 | |
@acindex{ARG_ARRAY}
|
| 23022 | |
Removed because of limited usefulness.
|
| 23023 | |
@end defmac
|
| 23024 | |
|
| 23025 | |
@defmac AC_C_CROSS
|
| 23026 | |
@acindex{C_CROSS}
|
| 23027 | |
This macro is obsolete; it does nothing.
|
| 23028 | |
@end defmac
|
| 23029 | |
|
| 23030 | |
@defmac AC_C_LONG_DOUBLE
|
| 23031 | |
@acindex{C_LONG_DOUBLE}
|
| 23032 | |
@cvindex HAVE_LONG_DOUBLE
|
| 23033 | |
If the C compiler supports a working @code{long double} type with more
|
| 23034 | |
range or precision than the @code{double} type, define
|
| 23035 | |
@code{HAVE_LONG_DOUBLE}.
|
| 23036 | |
|
| 23037 | |
You should use @code{AC_TYPE_LONG_DOUBLE} or
|
| 23038 | |
@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
|
| 23039 | |
@end defmac
|
| 23040 | |
|
| 23041 | |
@defmac AC_CANONICAL_SYSTEM
|
| 23042 | |
@acindex{CANONICAL_SYSTEM}
|
| 23043 | |
Determine the system type and set output variables to the names of the
|
| 23044 | |
canonical system types. @xref{Canonicalizing}, for details about the
|
| 23045 | |
variables this macro sets.
|
| 23046 | |
|
| 23047 | |
The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
|
| 23048 | |
@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
|
| 23049 | |
the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
|
| 23050 | |
other macros (@pxref{Canonicalizing}).
|
| 23051 | |
@end defmac
|
| 23052 | |
|
| 23053 | |
@defmac AC_CHAR_UNSIGNED
|
| 23054 | |
@acindex{CHAR_UNSIGNED}
|
| 23055 | |
Replaced by @code{AC_C_CHAR_UNSIGNED} (@pxref{AC_C_CHAR_UNSIGNED}).
|
| 23056 | |
@end defmac
|
| 23057 | |
|
| 23058 | |
@defmac AC_CHECK_TYPE (@var{type}, @var{default})
|
| 23059 | |
@acindex{CHECK_TYPE}
|
| 23060 | |
Autoconf, up to 2.13, used to provide this version of
|
| 23061 | |
@code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
|
| 23062 | |
it is a member of the @code{CHECK} clan, it does
|
| 23063 | |
more than just checking. Secondly, missing types are defined
|
| 23064 | |
using @code{#define}, not @code{typedef}, and this can lead to
|
| 23065 | |
problems in the case of pointer types.
|
| 23066 | |
|
| 23067 | |
This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
|
| 23068 | |
@ref{Generic Types}, for the description of the current macro.
|
| 23069 | |
|
| 23070 | |
If the type @var{type} is not defined, define it to be the C (or C++)
|
| 23071 | |
builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
|
| 23072 | |
|
| 23073 | |
This macro is equivalent to:
|
| 23074 | |
|
| 23075 | |
@example
|
| 23076 | |
AC_CHECK_TYPE([@var{type}], [],
|
| 23077 | |
[AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
|
| 23078 | |
[Define to `@var{default}'
|
| 23079 | |
if <sys/types.h> does not define.])])
|
| 23080 | |
@end example
|
| 23081 | |
|
| 23082 | |
In order to keep backward compatibility, the two versions of
|
| 23083 | |
@code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
|
| 23084 | |
|
| 23085 | |
@enumerate
|
| 23086 | |
@item
|
| 23087 | |
If there are three or four arguments, the modern version is used.
|
| 23088 | |
|
| 23089 | |
@item
|
| 23090 | |
If the second argument appears to be a C or C++ type, then the
|
| 23091 | |
obsolete version is used. This happens if the argument is a C or C++
|
| 23092 | |
@emph{builtin} type or a C identifier ending in @samp{_t}, optionally
|
| 23093 | |
followed by one of @samp{[(* } and then by a string of zero or more
|
| 23094 | |
characters taken from the set @samp{[]()* _a-zA-Z0-9}.
|
| 23095 | |
|
| 23096 | |
@item
|
| 23097 | |
If the second argument is spelled with the alphabet of valid C and C++
|
| 23098 | |
types, the user is warned and the modern version is used.
|
| 23099 | |
|
| 23100 | |
@item
|
| 23101 | |
Otherwise, the modern version is used.
|
| 23102 | |
@end enumerate
|
| 23103 | |
|
| 23104 | |
@noindent
|
| 23105 | |
You are encouraged either to use a valid builtin type, or to use the
|
| 23106 | |
equivalent modern code (see above), or better yet, to use
|
| 23107 | |
@code{AC_CHECK_TYPES} together with
|
| 23108 | |
|
| 23109 | |
@example
|
| 23110 | |
#ifndef HAVE_LOFF_T
|
| 23111 | |
typedef loff_t off_t;
|
| 23112 | |
#endif
|
| 23113 | |
@end example
|
| 23114 | |
@end defmac
|
| 23115 | |
@c end of AC_CHECK_TYPE
|
| 23116 | |
|
| 23117 | |
@defmac AC_CHECKING (@var{feature-description})
|
| 23118 | |
@acindex{CHECKING}
|
| 23119 | |
Same as
|
| 23120 | |
|
| 23121 | |
@example
|
| 23122 | |
AC_MSG_NOTICE([checking @var{feature-description}@dots{}]
|
| 23123 | |
@end example
|
| 23124 | |
|
| 23125 | |
@noindent
|
| 23126 | |
@xref{AC_MSG_NOTICE}.
|
| 23127 | |
@end defmac
|
| 23128 | |
|
| 23129 | |
@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @
|
| 23130 | |
@var{function-body}, @var{action-if-true}, @ovar{action-if-false})
|
| 23131 | |
@acindex{COMPILE_CHECK}
|
| 23132 | |
This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
|
| 23133 | |
@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
|
| 23134 | |
addition that it prints @samp{checking for @var{echo-text}} to the
|
| 23135 | |
standard output first, if @var{echo-text} is non-empty. Use
|
| 23136 | |
@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
|
| 23137 | |
messages (@pxref{Printing Messages}).
|
| 23138 | |
@end defmac
|
| 23139 | |
|
| 23140 | |
@defmac AC_CONST
|
| 23141 | |
@acindex{CONST}
|
| 23142 | |
Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}).
|
| 23143 | |
@end defmac
|
| 23144 | |
|
| 23145 | |
@defmac AC_CROSS_CHECK
|
| 23146 | |
@acindex{CROSS_CHECK}
|
| 23147 | |
Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
|
| 23148 | |
@code{:-)}.
|
| 23149 | |
@end defmac
|
| 23150 | |
|
| 23151 | |
@defmac AC_CYGWIN
|
| 23152 | |
@acindex{CYGWIN}
|
| 23153 | |
@evindex CYGWIN
|
| 23154 | |
Check for the Cygwin environment in which case the shell variable
|
| 23155 | |
@code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
|
| 23156 | |
means to check the nature of the host is using @code{AC_CANONICAL_HOST}
|
| 23157 | |
(@pxref{Canonicalizing}). As a matter of fact this macro is defined as:
|
| 23158 | |
|
| 23159 | |
@example
|
| 23160 | |
AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
|
| 23161 | |
case $host_os in
|
| 23162 | |
*cygwin* ) CYGWIN=yes;;
|
| 23163 | |
* ) CYGWIN=no;;
|
| 23164 | |
esac
|
| 23165 | |
@end example
|
| 23166 | |
|
| 23167 | |
Beware that the variable @env{CYGWIN} has a special meaning when
|
| 23168 | |
running Cygwin, and should not be changed. That's yet another reason
|
| 23169 | |
not to use this macro.
|
| 23170 | |
@end defmac
|
| 23171 | |
|
| 23172 | |
@defmac AC_DECL_SYS_SIGLIST
|
| 23173 | |
@acindex{DECL_SYS_SIGLIST}
|
| 23174 | |
@cvindex SYS_SIGLIST_DECLARED
|
| 23175 | |
Same as:
|
| 23176 | |
|
| 23177 | |
@example
|
| 23178 | |
AC_CHECK_DECLS([sys_siglist], [], [],
|
| 23179 | |
[#include <signal.h>
|
| 23180 | |
/* NetBSD declares sys_siglist in unistd.h. */
|
| 23181 | |
#ifdef HAVE_UNISTD_H
|
| 23182 | |
# include <unistd.h>
|
| 23183 | |
#endif
|
| 23184 | |
])
|
| 23185 | |
@end example
|
| 23186 | |
|
| 23187 | |
@noindent
|
| 23188 | |
@xref{AC_CHECK_DECLS}.
|
| 23189 | |
@end defmac
|
| 23190 | |
|
| 23191 | |
@defmac AC_DECL_YYTEXT
|
| 23192 | |
@acindex{DECL_YYTEXT}
|
| 23193 | |
Does nothing, now integrated in @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
|
| 23194 | |
@end defmac
|
| 23195 | |
|
| 23196 | |
@defmac AC_DIR_HEADER
|
| 23197 | |
@acindex{DIR_HEADER}
|
| 23198 | |
@cvindex DIRENT
|
| 23199 | |
@cvindex SYSNDIR
|
| 23200 | |
@cvindex SYSDIR
|
| 23201 | |
@cvindex NDIR
|
| 23202 | |
Like calling @code{AC_FUNC_CLOSEDIR_VOID}
|
| 23203 | |
(@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT}
|
| 23204 | |
(@pxref{AC_HEADER_DIRENT}),
|
| 23205 | |
but defines a different set of C preprocessor macros to indicate which
|
| 23206 | |
header file is found:
|
| 23207 | |
|
| 23208 | |
@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
|
| 23209 | |
@item Header @tab Old Symbol @tab New Symbol
|
| 23210 | |
@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
|
| 23211 | |
@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
|
| 23212 | |
@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
|
| 23213 | |
@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
|
| 23214 | |
@end multitable
|
| 23215 | |
@end defmac
|
| 23216 | |
|
| 23217 | |
@defmac AC_DYNIX_SEQ
|
| 23218 | |
@acindex{DYNIX_SEQ}
|
| 23219 | |
If on DYNIX/ptx, add @option{-lseq} to output variable
|
| 23220 | |
@code{LIBS}. This macro used to be defined as
|
| 23221 | |
|
| 23222 | |
@example
|
| 23223 | |
AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
|
| 23224 | |
@end example
|
| 23225 | |
|
| 23226 | |
@noindent
|
| 23227 | |
now it is just @code{AC_FUNC_GETMNTENT} (@pxref{AC_FUNC_GETMNTENT}).
|
| 23228 | |
@end defmac
|
| 23229 | |
|
| 23230 | |
@defmac AC_EXEEXT
|
| 23231 | |
@acindex{EXEEXT}
|
| 23232 | |
@ovindex EXEEXT
|
| 23233 | |
Defined the output variable @code{EXEEXT} based on the output of the
|
| 23234 | |
compiler, which is now done automatically. Typically set to empty
|
| 23235 | |
string if Posix and @samp{.exe} if a DOS variant.
|
| 23236 | |
@end defmac
|
| 23237 | |
|
| 23238 | |
@defmac AC_EMXOS2
|
| 23239 | |
@acindex{EMXOS2}
|
| 23240 | |
Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
|
| 23241 | |
and sets @code{EMXOS2}. Don't use this macro, the dignified means to
|
| 23242 | |
check the nature of the host is using @code{AC_CANONICAL_HOST}
|
| 23243 | |
(@pxref{Canonicalizing}).
|
| 23244 | |
@end defmac
|
| 23245 | |
|
| 23246 | |
@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @
|
| 23247 | |
@ovar{action-if-not-given})
|
| 23248 | |
@acindex{ENABLE}
|
| 23249 | |
This is an obsolete version of @code{AC_ARG_ENABLE} that does not
|
| 23250 | |
support providing a help string (@pxref{AC_ARG_ENABLE}).
|
| 23251 | |
@end defmac
|
| 23252 | |
|
| 23253 | |
@defmac AC_ERROR
|
| 23254 | |
@acindex{ERROR}
|
| 23255 | |
Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}).
|
| 23256 | |
@end defmac
|
| 23257 | |
|
| 23258 | |
@defmac AC_FIND_X
|
| 23259 | |
@acindex{FIND_X}
|
| 23260 | |
Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}).
|
| 23261 | |
@end defmac
|
| 23262 | |
|
| 23263 | |
@defmac AC_FIND_XTRA
|
| 23264 | |
@acindex{FIND_XTRA}
|
| 23265 | |
Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}).
|
| 23266 | |
@end defmac
|
| 23267 | |
|
| 23268 | |
@defmac AC_FOREACH
|
| 23269 | |
@acindex{FOREACH}
|
| 23270 | |
Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}).
|
| 23271 | |
@end defmac
|
| 23272 | |
|
| 23273 | |
@defmac AC_FUNC_CHECK
|
| 23274 | |
@acindex{FUNC_CHECK}
|
| 23275 | |
Replaced by @code{AC_CHECK_FUNC} (@pxref{AC_CHECK_FUNC}).
|
| 23276 | |
@end defmac
|
| 23277 | |
|
| 23278 | |
@anchor{AC_FUNC_SETVBUF_REVERSED}
|
| 23279 | |
@defmac AC_FUNC_SETVBUF_REVERSED
|
| 23280 | |
@acindex{FUNC_SETVBUF_REVERSED}
|
| 23281 | |
@cvindex SETVBUF_REVERSED
|
| 23282 | |
@c @fuindex setvbuf
|
| 23283 | |
@prindex @code{setvbuf}
|
| 23284 | |
Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
|
| 23285 | |
the buffering type as its second argument and the buffer pointer as the
|
| 23286 | |
third, instead of the other way around, and defined
|
| 23287 | |
@code{SETVBUF_REVERSED}. However, the last systems to have the problem
|
| 23288 | |
were those based on SVR2, which became obsolete in 1987, and the macro
|
| 23289 | |
is no longer needed.
|
| 23290 | |
@end defmac
|
| 23291 | |
|
| 23292 | |
@defmac AC_FUNC_WAIT3
|
| 23293 | |
@acindex{FUNC_WAIT3}
|
| 23294 | |
@cvindex HAVE_WAIT3
|
| 23295 | |
@c @fuindex wait3
|
| 23296 | |
@prindex @code{wait3}
|
| 23297 | |
If @code{wait3} is found and fills in the contents of its third argument
|
| 23298 | |
(a @samp{struct rusage *}), which HP-UX does not do, define
|
| 23299 | |
@code{HAVE_WAIT3}.
|
| 23300 | |
|
| 23301 | |
These days portable programs should use @code{waitpid}, not
|
| 23302 | |
@code{wait3}, as @code{wait3} has been removed from Posix.
|
| 23303 | |
@end defmac
|
| 23304 | |
|
| 23305 | |
@defmac AC_GCC_TRADITIONAL
|
| 23306 | |
@acindex{GCC_TRADITIONAL}
|
| 23307 | |
Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}).
|
| 23308 | |
@end defmac
|
| 23309 | |
|
| 23310 | |
@defmac AC_GETGROUPS_T
|
| 23311 | |
@acindex{GETGROUPS_T}
|
| 23312 | |
Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}).
|
| 23313 | |
@end defmac
|
| 23314 | |
|
| 23315 | |
@defmac AC_GETLOADAVG
|
| 23316 | |
@acindex{GETLOADAVG}
|
| 23317 | |
Replaced by @code{AC_FUNC_GETLOADAVG} (@pxref{AC_FUNC_GETLOADAVG}).
|
| 23318 | |
@end defmac
|
| 23319 | |
|
| 23320 | |
@defmac AC_GNU_SOURCE
|
| 23321 | |
@acindex{GNU_SOURCE}
|
| 23322 | |
@cvindex _GNU_SOURCE
|
| 23323 | |
This macro is a platform-specific subset of
|
| 23324 | |
@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
|
| 23325 | |
@end defmac
|
| 23326 | |
|
| 23327 | |
@defmac AC_HAVE_FUNCS
|
| 23328 | |
@acindex{HAVE_FUNCS}
|
| 23329 | |
Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}).
|
| 23330 | |
@end defmac
|
| 23331 | |
|
| 23332 | |
@defmac AC_HAVE_HEADERS
|
| 23333 | |
@acindex{HAVE_HEADERS}
|
| 23334 | |
Replaced by @code{AC_CHECK_HEADERS} (@pxref{AC_CHECK_HEADERS}).
|
| 23335 | |
@end defmac
|
| 23336 | |
|
| 23337 | |
@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @
|
| 23338 | |
@ovar{action-if-not-found}, @ovar{other-libraries})
|
| 23339 | |
@acindex{HAVE_LIBRARY}
|
| 23340 | |
This macro is equivalent to calling @code{AC_CHECK_LIB} with a
|
| 23341 | |
@var{function} argument of @code{main}. In addition, @var{library} can
|
| 23342 | |
be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
|
| 23343 | |
all of those cases, the compiler is passed @option{-lfoo}. However,
|
| 23344 | |
@var{library} cannot be a shell variable; it must be a literal name.
|
| 23345 | |
@xref{AC_CHECK_LIB}.
|
| 23346 | |
@end defmac
|
| 23347 | |
|
| 23348 | |
@defmac AC_HAVE_POUNDBANG
|
| 23349 | |
@acindex{HAVE_POUNDBANG}
|
| 23350 | |
Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}).
|
| 23351 | |
@end defmac
|
| 23352 | |
|
| 23353 | |
@defmac AC_HEADER_CHECK
|
| 23354 | |
@acindex{HEADER_CHECK}
|
| 23355 | |
Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}).
|
| 23356 | |
@end defmac
|
| 23357 | |
|
| 23358 | |
@defmac AC_HEADER_EGREP
|
| 23359 | |
@acindex{HEADER_EGREP}
|
| 23360 | |
Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}).
|
| 23361 | |
@end defmac
|
| 23362 | |
|
| 23363 | |
@defmac AC_HELP_STRING
|
| 23364 | |
@acindex{HELP_STRING}
|
| 23365 | |
Replaced by @code{AS_HELP_STRING} (@pxref{AS_HELP_STRING}).
|
| 23366 | |
@end defmac
|
| 23367 | |
|
| 23368 | |
@defmac AC_INIT (@var{unique-file-in-source-dir})
|
| 23369 | |
@acindex{INIT}
|
| 23370 | |
Formerly @code{AC_INIT} used to have a single argument, and was
|
| 23371 | |
equivalent to:
|
| 23372 | |
|
| 23373 | |
@example
|
| 23374 | |
AC_INIT
|
| 23375 | |
AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
|
| 23376 | |
@end example
|
| 23377 | |
See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}.
|
| 23378 | |
@end defmac
|
| 23379 | |
|
| 23380 | |
@defmac AC_INLINE
|
| 23381 | |
@acindex{INLINE}
|
| 23382 | |
Replaced by @code{AC_C_INLINE} (@pxref{AC_C_INLINE}).
|
| 23383 | |
@end defmac
|
| 23384 | |
|
| 23385 | |
@defmac AC_INT_16_BITS
|
| 23386 | |
@acindex{INT_16_BITS}
|
| 23387 | |
@cvindex INT_16_BITS
|
| 23388 | |
If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
|
| 23389 | |
Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}).
|
| 23390 | |
@end defmac
|
| 23391 | |
|
| 23392 | |
@defmac AC_IRIX_SUN
|
| 23393 | |
@acindex{IRIX_SUN}
|
| 23394 | |
If on IRIX (Silicon Graphics Unix), add @option{-lsun} to output
|
| 23395 | |
@code{LIBS}. If you were using it to get @code{getmntent}, use
|
| 23396 | |
@code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
|
| 23397 | |
of the password and group functions, use @samp{AC_CHECK_LIB(sun,
|
| 23398 | |
getpwnam)}. Up to Autoconf 2.13, it used to be
|
| 23399 | |
|
| 23400 | |
@example
|
| 23401 | |
AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
|
| 23402 | |
@end example
|
| 23403 | |
|
| 23404 | |
@noindent
|
| 23405 | |
now it is defined as
|
| 23406 | |
|
| 23407 | |
@example
|
| 23408 | |
AC_FUNC_GETMNTENT
|
| 23409 | |
AC_CHECK_LIB([sun], [getpwnam])
|
| 23410 | |
@end example
|
| 23411 | |
|
| 23412 | |
@noindent
|
| 23413 | |
See @ref{AC_FUNC_GETMNTENT} and @ref{AC_CHECK_LIB}.
|
| 23414 | |
@end defmac
|
| 23415 | |
|
| 23416 | |
@defmac AC_ISC_POSIX
|
| 23417 | |
@acindex{ISC_POSIX}
|
| 23418 | |
@ovindex LIBS
|
| 23419 | |
This macro adds @option{-lcposix} to output variable @code{LIBS} if
|
| 23420 | |
necessary for Posix facilities. Sun dropped support for the obsolete
|
| 23421 | |
INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs
|
| 23422 | |
need not use this macro. It is implemented as
|
| 23423 | |
@code{AC_SEARCH_LIBS([strerror], [cposix])} (@pxref{AC_SEARCH_LIBS}).
|
| 23424 | |
@end defmac
|
| 23425 | |
|
| 23426 | |
@defmac AC_LANG_C
|
| 23427 | |
@acindex{LANG_C}
|
| 23428 | |
Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}).
|
| 23429 | |
@end defmac
|
| 23430 | |
|
| 23431 | |
@defmac AC_LANG_CPLUSPLUS
|
| 23432 | |
@acindex{LANG_CPLUSPLUS}
|
| 23433 | |
Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}).
|
| 23434 | |
@end defmac
|
| 23435 | |
|
| 23436 | |
@defmac AC_LANG_FORTRAN77
|
| 23437 | |
@acindex{LANG_FORTRAN77}
|
| 23438 | |
Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}).
|
| 23439 | |
@end defmac
|
| 23440 | |
|
| 23441 | |
@defmac AC_LANG_RESTORE
|
| 23442 | |
@acindex{LANG_RESTORE}
|
| 23443 | |
Select the @var{language} that is saved on the top of the stack, as set
|
| 23444 | |
by @code{AC_LANG_SAVE}, remove it from the stack, and call
|
| 23445 | |
@code{AC_LANG(@var{language})}. @xref{Language Choice}, for the
|
| 23446 | |
preferred way to change languages.
|
| 23447 | |
@end defmac
|
| 23448 | |
|
| 23449 | |
@defmac AC_LANG_SAVE
|
| 23450 | |
@acindex{LANG_SAVE}
|
| 23451 | |
Remember the current language (as set by @code{AC_LANG}) on a stack.
|
| 23452 | |
The current language does not change. @code{AC_LANG_PUSH} is preferred
|
| 23453 | |
(@pxref{AC_LANG_PUSH}).
|
| 23454 | |
@end defmac
|
| 23455 | |
|
| 23456 | |
@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
|
| 23457 | |
@acindex{LINK_FILES}
|
| 23458 | |
This is an obsolete version of @code{AC_CONFIG_LINKS}
|
| 23459 | |
(@pxref{AC_CONFIG_LINKS}. An updated version of:
|
| 23460 | |
|
| 23461 | |
@example
|
| 23462 | |
AC_LINK_FILES(config/$machine.h config/$obj_format.h,
|
| 23463 | |
host.h object.h)
|
| 23464 | |
@end example
|
| 23465 | |
|
| 23466 | |
@noindent
|
| 23467 | |
is:
|
| 23468 | |
|
| 23469 | |
@example
|
| 23470 | |
AC_CONFIG_LINKS([host.h:config/$machine.h
|
| 23471 | |
object.h:config/$obj_format.h])
|
| 23472 | |
@end example
|
| 23473 | |
@end defmac
|
| 23474 | |
|
| 23475 | |
@defmac AC_LN_S
|
| 23476 | |
@acindex{LN_S}
|
| 23477 | |
Replaced by @code{AC_PROG_LN_S} (@pxref{AC_PROG_LN_S}).
|
| 23478 | |
@end defmac
|
| 23479 | |
|
| 23480 | |
@defmac AC_LONG_64_BITS
|
| 23481 | |
@acindex{LONG_64_BITS}
|
| 23482 | |
@cvindex LONG_64_BITS
|
| 23483 | |
Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
|
| 23484 | |
Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead
|
| 23485 | |
(@pxref{AC_CHECK_SIZEOF}).
|
| 23486 | |
@end defmac
|
| 23487 | |
|
| 23488 | |
@defmac AC_LONG_DOUBLE
|
| 23489 | |
@acindex{LONG_DOUBLE}
|
| 23490 | |
If the C compiler supports a working @code{long double} type with more
|
| 23491 | |
range or precision than the @code{double} type, define
|
| 23492 | |
@code{HAVE_LONG_DOUBLE}.
|
| 23493 | |
|
| 23494 | |
You should use @code{AC_TYPE_LONG_DOUBLE} or
|
| 23495 | |
@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
|
| 23496 | |
@end defmac
|
| 23497 | |
|
| 23498 | |
@defmac AC_LONG_FILE_NAMES
|
| 23499 | |
@acindex{LONG_FILE_NAMES}
|
| 23500 | |
Replaced by
|
| 23501 | |
@example
|
| 23502 | |
AC_SYS_LONG_FILE_NAMES
|
| 23503 | |
@end example
|
| 23504 | |
@noindent
|
| 23505 | |
@xref{AC_SYS_LONG_FILE_NAMES}.
|
| 23506 | |
@end defmac
|
| 23507 | |
|
| 23508 | |
@defmac AC_MAJOR_HEADER
|
| 23509 | |
@acindex{MAJOR_HEADER}
|
| 23510 | |
Replaced by @code{AC_HEADER_MAJOR} (@pxref{AC_HEADER_MAJOR}).
|
| 23511 | |
@end defmac
|
| 23512 | |
|
| 23513 | |
@defmac AC_MEMORY_H
|
| 23514 | |
@acindex{MEMORY_H}
|
| 23515 | |
@cvindex NEED_MEMORY_H
|
| 23516 | |
Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
|
| 23517 | |
defined in @file{memory.h}. Today it is equivalent to
|
| 23518 | |
@samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust
|
| 23519 | |
your code to depend upon
|
| 23520 | |
@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
|
| 23521 | |
Symbols}.
|
| 23522 | |
@end defmac
|
| 23523 | |
|
| 23524 | |
@defmac AC_MINGW32
|
| 23525 | |
@acindex{MINGW32}
|
| 23526 | |
Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
|
| 23527 | |
environment and sets @code{MINGW32}. Don't use this macro, the
|
| 23528 | |
dignified means to check the nature of the host is using
|
| 23529 | |
@code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
|
| 23530 | |
@end defmac
|
| 23531 | |
|
| 23532 | |
@defmac AC_MINIX
|
| 23533 | |
@acindex{MINIX}
|
| 23534 | |
@cvindex _MINIX
|
| 23535 | |
@cvindex _POSIX_SOURCE
|
| 23536 | |
@cvindex _POSIX_1_SOURCE
|
| 23537 | |
This macro is a platform-specific subset of
|
| 23538 | |
@code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
|
| 23539 | |
@end defmac
|
| 23540 | |
|
| 23541 | |
@defmac AC_MINUS_C_MINUS_O
|
| 23542 | |
@acindex{MINUS_C_MINUS_O}
|
| 23543 | |
Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}).
|
| 23544 | |
@end defmac
|
| 23545 | |
|
| 23546 | |
@defmac AC_MMAP
|
| 23547 | |
@acindex{MMAP}
|
| 23548 | |
Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}).
|
| 23549 | |
@end defmac
|
| 23550 | |
|
| 23551 | |
@defmac AC_MODE_T
|
| 23552 | |
@acindex{MODE_T}
|
| 23553 | |
Replaced by @code{AC_TYPE_MODE_T} (@pxref{AC_TYPE_MODE_T}).
|
| 23554 | |
@end defmac
|
| 23555 | |
|
| 23556 | |
@defmac AC_OBJEXT
|
| 23557 | |
@acindex{OBJEXT}
|
| 23558 | |
@ovindex OBJEXT
|
| 23559 | |
Defined the output variable @code{OBJEXT} based on the output of the
|
| 23560 | |
compiler, after .c files have been excluded. Typically set to @samp{o}
|
| 23561 | |
if Posix, @samp{obj} if a DOS variant.
|
| 23562 | |
Now the compiler checking macros handle
|
| 23563 | |
this automatically.
|
| 23564 | |
@end defmac
|
| 23565 | |
|
| 23566 | |
@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
|
| 23567 | |
@acindex{OBSOLETE}
|
| 23568 | |
Make M4 print a message to the standard error output warning that
|
| 23569 | |
@var{this-macro-name} is obsolete, and giving the file and line number
|
| 23570 | |
where it was called. @var{this-macro-name} should be the name of the
|
| 23571 | |
macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
|
| 23572 | |
it is printed at the end of the warning message; for example, it can be
|
| 23573 | |
a suggestion for what to use instead of @var{this-macro-name}.
|
| 23574 | |
|
| 23575 | |
For instance
|
| 23576 | |
|
| 23577 | |
@example
|
| 23578 | |
AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
|
| 23579 | |
@end example
|
| 23580 | |
|
| 23581 | |
@noindent
|
| 23582 | |
You are encouraged to use @code{AU_DEFUN} instead, since it gives better
|
| 23583 | |
services to the user (@pxref{AU_DEFUN}).
|
| 23584 | |
@end defmac
|
| 23585 | |
|
| 23586 | |
@defmac AC_OFF_T
|
| 23587 | |
@acindex{OFF_T}
|
| 23588 | |
Replaced by @code{AC_TYPE_OFF_T} (@pxref{AC_TYPE_OFF_T}).
|
| 23589 | |
@end defmac
|
| 23590 | |
|
| 23591 | |
@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
|
| 23592 | |
@acindex{OUTPUT}
|
| 23593 | |
The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted
|
| 23594 | |
interface is equivalent to:
|
| 23595 | |
|
| 23596 | |
@example
|
| 23597 | |
@group
|
| 23598 | |
AC_CONFIG_FILES(@var{file}@dots{})
|
| 23599 | |
AC_CONFIG_COMMANDS([default],
|
| 23600 | |
@var{extra-cmds}, @var{init-cmds})
|
| 23601 | |
AC_OUTPUT
|
| 23602 | |
@end group
|
| 23603 | |
@end example
|
| 23604 | |
|
| 23605 | |
@noindent
|
| 23606 | |
See @ref{AC_CONFIG_FILES}, @ref{AC_CONFIG_COMMANDS}, and @ref{AC_OUTPUT}.
|
| 23607 | |
@end defmac
|
| 23608 | |
|
| 23609 | |
@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
|
| 23610 | |
@acindex{OUTPUT_COMMANDS}
|
| 23611 | |
Specify additional shell commands to run at the end of
|
| 23612 | |
@file{config.status}, and shell commands to initialize any variables
|
| 23613 | |
from @command{configure}. This macro may be called multiple times. It is
|
| 23614 | |
obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}).
|
| 23615 | |
|
| 23616 | |
Here is an unrealistic example:
|
| 23617 | |
|
| 23618 | |
@example
|
| 23619 | |
fubar=27
|
| 23620 | |
AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
|
| 23621 | |
[fubar=$fubar])
|
| 23622 | |
AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
|
| 23623 | |
[echo init bit])
|
| 23624 | |
@end example
|
| 23625 | |
|
| 23626 | |
Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
|
| 23627 | |
additional key, an important difference is that
|
| 23628 | |
@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
|
| 23629 | |
@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
|
| 23630 | |
can safely be given macro calls as arguments:
|
| 23631 | |
|
| 23632 | |
@example
|
| 23633 | |
AC_CONFIG_COMMANDS(foo, [my_FOO()])
|
| 23634 | |
@end example
|
| 23635 | |
|
| 23636 | |
@noindent
|
| 23637 | |
Conversely, where one level of quoting was enough for literal strings
|
| 23638 | |
with @code{AC_OUTPUT_COMMANDS}, you need two with
|
| 23639 | |
@code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
|
| 23640 | |
|
| 23641 | |
@example
|
| 23642 | |
@group
|
| 23643 | |
AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
|
| 23644 | |
AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
|
| 23645 | |
@end group
|
| 23646 | |
@end example
|
| 23647 | |
@end defmac
|
| 23648 | |
|
| 23649 | |
@defmac AC_PID_T
|
| 23650 | |
@acindex{PID_T}
|
| 23651 | |
Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}).
|
| 23652 | |
@end defmac
|
| 23653 | |
|
| 23654 | |
@defmac AC_PREFIX
|
| 23655 | |
@acindex{PREFIX}
|
| 23656 | |
Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}).
|
| 23657 | |
@end defmac
|
| 23658 | |
|
| 23659 | |
@defmac AC_PROGRAMS_CHECK
|
| 23660 | |
@acindex{PROGRAMS_CHECK}
|
| 23661 | |
Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}).
|
| 23662 | |
@end defmac
|
| 23663 | |
|
| 23664 | |
@defmac AC_PROGRAMS_PATH
|
| 23665 | |
@acindex{PROGRAMS_PATH}
|
| 23666 | |
Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}).
|
| 23667 | |
@end defmac
|
| 23668 | |
|
| 23669 | |
@defmac AC_PROGRAM_CHECK
|
| 23670 | |
@acindex{PROGRAM_CHECK}
|
| 23671 | |
Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}).
|
| 23672 | |
@end defmac
|
| 23673 | |
|
| 23674 | |
@defmac AC_PROGRAM_EGREP
|
| 23675 | |
@acindex{PROGRAM_EGREP}
|
| 23676 | |
Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}).
|
| 23677 | |
@end defmac
|
| 23678 | |
|
| 23679 | |
@defmac AC_PROGRAM_PATH
|
| 23680 | |
@acindex{PROGRAM_PATH}
|
| 23681 | |
Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}).
|
| 23682 | |
@end defmac
|
| 23683 | |
|
| 23684 | |
@defmac AC_REMOTE_TAPE
|
| 23685 | |
@acindex{REMOTE_TAPE}
|
| 23686 | |
Removed because of limited usefulness.
|
| 23687 | |
@end defmac
|
| 23688 | |
|
| 23689 | |
@defmac AC_RESTARTABLE_SYSCALLS
|
| 23690 | |
@acindex{RESTARTABLE_SYSCALLS}
|
| 23691 | |
This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However,
|
| 23692 | |
these days portable programs should use @code{sigaction} with
|
| 23693 | |
@code{SA_RESTART} if they want restartable system calls. They should
|
| 23694 | |
not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
|
| 23695 | |
system call is restartable is a dynamic issue, not a configuration-time
|
| 23696 | |
issue.
|
| 23697 | |
@end defmac
|
| 23698 | |
|
| 23699 | |
@defmac AC_RETSIGTYPE
|
| 23700 | |
@acindex{RETSIGTYPE}
|
| 23701 | |
Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}), which itself
|
| 23702 | |
is obsolete when assuming C89 or better.
|
| 23703 | |
@end defmac
|
| 23704 | |
|
| 23705 | |
@defmac AC_RSH
|
| 23706 | |
@acindex{RSH}
|
| 23707 | |
Removed because of limited usefulness.
|
| 23708 | |
@end defmac
|
| 23709 | |
|
| 23710 | |
@defmac AC_SCO_INTL
|
| 23711 | |
@acindex{SCO_INTL}
|
| 23712 | |
@ovindex LIBS
|
| 23713 | |
If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
|
| 23714 | |
macro used to do this:
|
| 23715 | |
|
| 23716 | |
@example
|
| 23717 | |
AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
|
| 23718 | |
@end example
|
| 23719 | |
|
| 23720 | |
@noindent
|
| 23721 | |
Now it just calls @code{AC_FUNC_STRFTIME} instead (@pxref{AC_FUNC_STRFTIME}).
|
| 23722 | |
@end defmac
|
| 23723 | |
|
| 23724 | |
@defmac AC_SETVBUF_REVERSED
|
| 23725 | |
@acindex{SETVBUF_REVERSED}
|
| 23726 | |
Replaced by
|
| 23727 | |
@example
|
| 23728 | |
AC_FUNC_SETVBUF_REVERSED
|
| 23729 | |
@end example
|
| 23730 | |
@noindent
|
| 23731 | |
@xref{AC_FUNC_SETVBUF_REVERSED}.
|
| 23732 | |
@end defmac
|
| 23733 | |
|
| 23734 | |
@defmac AC_SET_MAKE
|
| 23735 | |
@acindex{SET_MAKE}
|
| 23736 | |
Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}).
|
| 23737 | |
@end defmac
|
| 23738 | |
|
| 23739 | |
@defmac AC_SIZEOF_TYPE
|
| 23740 | |
@acindex{SIZEOF_TYPE}
|
| 23741 | |
Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}).
|
| 23742 | |
@end defmac
|
| 23743 | |
|
| 23744 | |
@defmac AC_SIZE_T
|
| 23745 | |
@acindex{SIZE_T}
|
| 23746 | |
Replaced by @code{AC_TYPE_SIZE_T} (@pxref{AC_TYPE_SIZE_T}).
|
| 23747 | |
@end defmac
|
| 23748 | |
|
| 23749 | |
@defmac AC_STAT_MACROS_BROKEN
|
| 23750 | |
@acindex{STAT_MACROS_BROKEN}
|
| 23751 | |
Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}).
|
| 23752 | |
@end defmac
|
| 23753 | |
|
| 23754 | |
@defmac AC_STDC_HEADERS
|
| 23755 | |
@acindex{STDC_HEADERS}
|
| 23756 | |
Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}).
|
| 23757 | |
@end defmac
|
| 23758 | |
|
| 23759 | |
@defmac AC_STRCOLL
|
| 23760 | |
@acindex{STRCOLL}
|
| 23761 | |
Replaced by @code{AC_FUNC_STRCOLL} (@pxref{AC_FUNC_STRCOLL}).
|
| 23762 | |
@end defmac
|
| 23763 | |
|
| 23764 | |
@defmac AC_STRUCT_ST_BLKSIZE
|
| 23765 | |
@acindex{STRUCT_ST_BLKSIZE}
|
| 23766 | |
@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
|
| 23767 | |
@cvindex HAVE_ST_BLKSIZE
|
| 23768 | |
If @code{struct stat} contains an @code{st_blksize} member, define
|
| 23769 | |
@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
|
| 23770 | |
@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
|
| 23771 | |
the future. This macro is obsoleted, and should be replaced by
|
| 23772 | |
|
| 23773 | |
@example
|
| 23774 | |
AC_CHECK_MEMBERS([struct stat.st_blksize])
|
| 23775 | |
@end example
|
| 23776 | |
@noindent
|
| 23777 | |
@xref{AC_CHECK_MEMBERS}.
|
| 23778 | |
@end defmac
|
| 23779 | |
|
| 23780 | |
@defmac AC_STRUCT_ST_RDEV
|
| 23781 | |
@acindex{STRUCT_ST_RDEV}
|
| 23782 | |
@cvindex HAVE_ST_RDEV
|
| 23783 | |
@cvindex HAVE_STRUCT_STAT_ST_RDEV
|
| 23784 | |
If @code{struct stat} contains an @code{st_rdev} member, define
|
| 23785 | |
@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
|
| 23786 | |
@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
|
| 23787 | |
in the future. Actually, even the new macro is obsolete and should be
|
| 23788 | |
replaced by:
|
| 23789 | |
@example
|
| 23790 | |
AC_CHECK_MEMBERS([struct stat.st_rdev])
|
| 23791 | |
@end example
|
| 23792 | |
@noindent
|
| 23793 | |
@xref{AC_CHECK_MEMBERS}.
|
| 23794 | |
@end defmac
|
| 23795 | |
|
| 23796 | |
@defmac AC_ST_BLKSIZE
|
| 23797 | |
@acindex{ST_BLKSIZE}
|
| 23798 | |
Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
|
| 23799 | |
@end defmac
|
| 23800 | |
|
| 23801 | |
@defmac AC_ST_BLOCKS
|
| 23802 | |
@acindex{ST_BLOCKS}
|
| 23803 | |
Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}).
|
| 23804 | |
@end defmac
|
| 23805 | |
|
| 23806 | |
@defmac AC_ST_RDEV
|
| 23807 | |
@acindex{ST_RDEV}
|
| 23808 | |
Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
|
| 23809 | |
@end defmac
|
| 23810 | |
|
| 23811 | |
@defmac AC_SYS_RESTARTABLE_SYSCALLS
|
| 23812 | |
@acindex{SYS_RESTARTABLE_SYSCALLS}
|
| 23813 | |
@cvindex HAVE_RESTARTABLE_SYSCALLS
|
| 23814 | |
If the system automatically restarts a system call that is interrupted
|
| 23815 | |
by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
|
| 23816 | |
not check whether system calls are restarted in general---it checks whether a
|
| 23817 | |
signal handler installed with @code{signal} (but not @code{sigaction})
|
| 23818 | |
causes system calls to be restarted. It does not check whether system calls
|
| 23819 | |
can be restarted when interrupted by signals that have no handler.
|
| 23820 | |
|
| 23821 | |
These days portable programs should use @code{sigaction} with
|
| 23822 | |
@code{SA_RESTART} if they want restartable system calls. They should
|
| 23823 | |
not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
|
| 23824 | |
system call is restartable is a dynamic issue, not a configuration-time
|
| 23825 | |
issue.
|
| 23826 | |
@end defmac
|
| 23827 | |
|
| 23828 | |
@defmac AC_SYS_SIGLIST_DECLARED
|
| 23829 | |
@acindex{SYS_SIGLIST_DECLARED}
|
| 23830 | |
This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that
|
| 23831 | |
name is obsolete, as the same functionality is now achieved via
|
| 23832 | |
@code{AC_CHECK_DECLS} (@pxref{AC_CHECK_DECLS}).
|
| 23833 | |
@end defmac
|
| 23834 | |
|
| 23835 | |
@defmac AC_TEST_CPP
|
| 23836 | |
@acindex{TEST_CPP}
|
| 23837 | |
This macro was renamed @code{AC_TRY_CPP}, which in turn was replaced by
|
| 23838 | |
@code{AC_PREPROC_IFELSE} (@pxref{AC_PREPROC_IFELSE}).
|
| 23839 | |
@end defmac
|
| 23840 | |
|
| 23841 | |
@defmac AC_TEST_PROGRAM
|
| 23842 | |
@acindex{TEST_PROGRAM}
|
| 23843 | |
This macro was renamed @code{AC_TRY_RUN}, which in turn was replaced by
|
| 23844 | |
@code{AC_RUN_IFELSE} (@pxref{AC_RUN_IFELSE}).
|
| 23845 | |
@end defmac
|
| 23846 | |
|
| 23847 | |
@defmac AC_TIMEZONE
|
| 23848 | |
@acindex{TIMEZONE}
|
| 23849 | |
Replaced by @code{AC_STRUCT_TIMEZONE} (@pxref{AC_STRUCT_TIMEZONE}).
|
| 23850 | |
@end defmac
|
| 23851 | |
|
| 23852 | |
@defmac AC_TIME_WITH_SYS_TIME
|
| 23853 | |
@acindex{TIME_WITH_SYS_TIME}
|
| 23854 | |
Replaced by @code{AC_HEADER_TIME} (@pxref{AC_HEADER_TIME}).
|
| 23855 | |
@end defmac
|
| 23856 | |
|
| 23857 | |
@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @
|
| 23858 | |
@ovar{action-if-true}, @ovar{action-if-false})
|
| 23859 | |
@acindex{TRY_COMPILE}
|
| 23860 | |
Same as:
|
| 23861 | |
|
| 23862 | |
@example
|
| 23863 | |
AC_COMPILE_IFELSE(
|
| 23864 | |
[AC_LANG_PROGRAM([[@var{includes}]],
|
| 23865 | |
[[@var{function-body}]])],
|
| 23866 | |
[@var{action-if-true}],
|
| 23867 | |
[@var{action-if-false}])
|
| 23868 | |
@end example
|
| 23869 | |
|
| 23870 | |
@noindent
|
| 23871 | |
@xref{Running the Compiler}.
|
| 23872 | |
|
| 23873 | |
This macro double quotes both @var{includes} and @var{function-body}.
|
| 23874 | |
|
| 23875 | |
For C and C++, @var{includes} is any @code{#include} statements needed
|
| 23876 | |
by the code in @var{function-body} (@var{includes} is ignored if
|
| 23877 | |
the currently selected language is Fortran or Fortran 77). The compiler
|
| 23878 | |
and compilation flags are determined by the current language
|
| 23879 | |
(@pxref{Language Choice}).
|
| 23880 | |
@end defmac
|
| 23881 | |
|
| 23882 | |
@defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
|
| 23883 | |
@acindex{TRY_CPP}
|
| 23884 | |
Same as:
|
| 23885 | |
|
| 23886 | |
@example
|
| 23887 | |
AC_PREPROC_IFELSE(
|
| 23888 | |
[AC_LANG_SOURCE([[@var{input}]])],
|
| 23889 | |
[@var{action-if-true}],
|
| 23890 | |
[@var{action-if-false}])
|
| 23891 | |
@end example
|
| 23892 | |
|
| 23893 | |
@noindent
|
| 23894 | |
@xref{Running the Preprocessor}.
|
| 23895 | |
|
| 23896 | |
This macro double quotes the @var{input}.
|
| 23897 | |
@end defmac
|
| 23898 | |
|
| 23899 | |
@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @
|
| 23900 | |
@ovar{action-if-true}, @ovar{action-if-false})
|
| 23901 | |
@acindex{TRY_LINK}
|
| 23902 | |
Same as:
|
| 23903 | |
|
| 23904 | |
@example
|
| 23905 | |
AC_LINK_IFELSE(
|
| 23906 | |
[AC_LANG_PROGRAM([[@var{includes}]],
|
| 23907 | |
[[@var{function-body}]])],
|
| 23908 | |
[@var{action-if-true}],
|
| 23909 | |
[@var{action-if-false}])
|
| 23910 | |
@end example
|
| 23911 | |
|
| 23912 | |
@noindent
|
| 23913 | |
@xref{Running the Compiler}.
|
| 23914 | |
|
| 23915 | |
This macro double quotes both @var{includes} and @var{function-body}.
|
| 23916 | |
|
| 23917 | |
Depending on the current language (@pxref{Language Choice}), create a
|
| 23918 | |
test program to see whether a function whose body consists of
|
| 23919 | |
@var{function-body} can be compiled and linked. If the file compiles
|
| 23920 | |
and links successfully, run shell commands @var{action-if-found},
|
| 23921 | |
otherwise run @var{action-if-not-found}.
|
| 23922 | |
|
| 23923 | |
This macro double quotes both @var{includes} and @var{function-body}.
|
| 23924 | |
|
| 23925 | |
For C and C++, @var{includes} is any @code{#include} statements needed
|
| 23926 | |
by the code in @var{function-body} (@var{includes} is ignored if
|
| 23927 | |
the currently selected language is Fortran or Fortran 77). The compiler
|
| 23928 | |
and compilation flags are determined by the current language
|
| 23929 | |
(@pxref{Language Choice}), and in addition @code{LDFLAGS} and
|
| 23930 | |
@code{LIBS} are used for linking.
|
| 23931 | |
@end defmac
|
| 23932 | |
|
| 23933 | |
@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @
|
| 23934 | |
@ovar{action-if-not-found})
|
| 23935 | |
@acindex{TRY_LINK_FUNC}
|
| 23936 | |
This macro is equivalent to
|
| 23937 | |
@example
|
| 23938 | |
AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
|
| 23939 | |
[@var{action-if-found}], [@var{action-if-not-found}])
|
| 23940 | |
@end example
|
| 23941 | |
@noindent
|
| 23942 | |
@xref{AC_LINK_IFELSE}.
|
| 23943 | |
@end defmac
|
| 23944 | |
|
| 23945 | |
@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @
|
| 23946 | |
@ovar{action-if-false}, @dvar{action-if-cross-compiling, AC_MSG_FAILURE})
|
| 23947 | |
@acindex{TRY_RUN}
|
| 23948 | |
Same as:
|
| 23949 | |
|
| 23950 | |
@example
|
| 23951 | |
AC_RUN_IFELSE(
|
| 23952 | |
[AC_LANG_SOURCE([[@var{program}]])],
|
| 23953 | |
[@var{action-if-true}],
|
| 23954 | |
[@var{action-if-false}],
|
| 23955 | |
[@var{action-if-cross-compiling}])
|
| 23956 | |
@end example
|
| 23957 | |
|
| 23958 | |
@noindent
|
| 23959 | |
@xref{Runtime}.
|
| 23960 | |
@end defmac
|
| 23961 | |
|
| 23962 | |
@anchor{AC_TYPE_SIGNAL}
|
| 23963 | |
@defmac AC_TYPE_SIGNAL
|
| 23964 | |
@acindex{TYPE_SIGNAL}
|
| 23965 | |
@cvindex RETSIGTYPE
|
| 23966 | |
@hdrindex{signal.h}
|
| 23967 | |
If @file{signal.h} declares @code{signal} as returning a pointer to a
|
| 23968 | |
function returning @code{void}, define @code{RETSIGTYPE} to be
|
| 23969 | |
@code{void}; otherwise, define it to be @code{int}. These days, it is
|
| 23970 | |
portable to assume C89, and that signal handlers return @code{void},
|
| 23971 | |
without needing to use this macro or @code{RETSIGTYPE}.
|
| 23972 | |
|
| 23973 | |
When targeting older K&R C, it is possible to define signal handlers as
|
| 23974 | |
returning type @code{RETSIGTYPE}, and omit a return statement:
|
| 23975 | |
|
| 23976 | |
@example
|
| 23977 | |
@group
|
| 23978 | |
RETSIGTYPE
|
| 23979 | |
hup_handler ()
|
| 23980 | |
@{
|
| 23981 | |
@dots{}
|
| 23982 | |
@}
|
| 23983 | |
@end group
|
| 23984 | |
@end example
|
| 23985 | |
@end defmac
|
| 23986 | |
|
| 23987 | |
@defmac AC_UID_T
|
| 23988 | |
@acindex{UID_T}
|
| 23989 | |
Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}).
|
| 23990 | |
@end defmac
|
| 23991 | |
|
| 23992 | |
@defmac AC_UNISTD_H
|
| 23993 | |
@acindex{UNISTD_H}
|
| 23994 | |
Same as @samp{AC_CHECK_HEADERS([unistd.h])} (@pxref{AC_CHECK_HEADERS}).
|
| 23995 | |
@end defmac
|
| 23996 | |
|
| 23997 | |
@defmac AC_USG
|
| 23998 | |
@acindex{USG}
|
| 23999 | |
@cvindex USG
|
| 24000 | |
Define @code{USG} if the BSD string functions are defined in
|
| 24001 | |
@file{strings.h}. You should no longer depend upon @code{USG}, but on
|
| 24002 | |
@code{HAVE_STRING_H}; see @ref{Standard Symbols}.
|
| 24003 | |
@end defmac
|
| 24004 | |
|
| 24005 | |
@defmac AC_UTIME_NULL
|
| 24006 | |
@acindex{UTIME_NULL}
|
| 24007 | |
Replaced by @code{AC_FUNC_UTIME_NULL} (@pxref{AC_FUNC_UTIME_NULL}).
|
| 24008 | |
@end defmac
|
| 24009 | |
|
| 24010 | |
@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
|
| 24011 | |
@acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
|
| 24012 | |
If the cache file is inconsistent with the current host, target and
|
| 24013 | |
build system types, it used to execute @var{cmd} or print a default
|
| 24014 | |
error message. This is now handled by default.
|
| 24015 | |
@end defmac
|
| 24016 | |
|
| 24017 | |
@defmac AC_VERBOSE (@var{result-description})
|
| 24018 | |
@acindex{VERBOSE}
|
| 24019 | |
Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}).
|
| 24020 | |
@end defmac
|
| 24021 | |
|
| 24022 | |
@defmac AC_VFORK
|
| 24023 | |
@acindex{VFORK}
|
| 24024 | |
Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}).
|
| 24025 | |
@end defmac
|
| 24026 | |
|
| 24027 | |
@defmac AC_VPRINTF
|
| 24028 | |
@acindex{VPRINTF}
|
| 24029 | |
Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}).
|
| 24030 | |
@end defmac
|
| 24031 | |
|
| 24032 | |
@defmac AC_WAIT3
|
| 24033 | |
@acindex{WAIT3}
|
| 24034 | |
This macro was renamed @code{AC_FUNC_WAIT3}. However, these days
|
| 24035 | |
portable programs should use @code{waitpid}, not @code{wait3}, as
|
| 24036 | |
@code{wait3} has been removed from Posix.
|
| 24037 | |
@end defmac
|
| 24038 | |
|
| 24039 | |
@defmac AC_WARN
|
| 24040 | |
@acindex{WARN}
|
| 24041 | |
Replaced by @code{AC_MSG_WARN} (@pxref{AC_MSG_WARN}).
|
| 24042 | |
@end defmac
|
| 24043 | |
|
| 24044 | |
@defmac AC_WITH (@var{package}, @var{action-if-given}, @
|
| 24045 | |
@ovar{action-if-not-given})
|
| 24046 | |
@acindex{WITH}
|
| 24047 | |
This is an obsolete version of @code{AC_ARG_WITH} that does not
|
| 24048 | |
support providing a help string (@pxref{AC_ARG_WITH}).
|
| 24049 | |
@end defmac
|
| 24050 | |
|
| 24051 | |
@defmac AC_WORDS_BIGENDIAN
|
| 24052 | |
@acindex{WORDS_BIGENDIAN}
|
| 24053 | |
Replaced by @code{AC_C_BIGENDIAN} (@pxref{AC_C_BIGENDIAN}).
|
| 24054 | |
@end defmac
|
| 24055 | |
|
| 24056 | |
@defmac AC_XENIX_DIR
|
| 24057 | |
@acindex{XENIX_DIR}
|
| 24058 | |
@ovindex LIBS
|
| 24059 | |
This macro used to add @option{-lx} to output variable @code{LIBS} if on
|
| 24060 | |
Xenix. Also, if @file{dirent.h} is being checked for, added
|
| 24061 | |
@option{-ldir} to @code{LIBS}. Now it is merely an alias of
|
| 24062 | |
@code{AC_HEADER_DIRENT} instead, plus some code to detect whether
|
| 24063 | |
running XENIX on which you should not depend:
|
| 24064 | |
|
| 24065 | |
@example
|
| 24066 | |
AC_MSG_CHECKING([for Xenix])
|
| 24067 | |
AC_EGREP_CPP([yes],
|
| 24068 | |
[#if defined M_XENIX && !defined M_UNIX
|
| 24069 | |
yes
|
| 24070 | |
#endif],
|
| 24071 | |
[AC_MSG_RESULT([yes]); XENIX=yes],
|
| 24072 | |
[AC_MSG_RESULT([no]); XENIX=])
|
| 24073 | |
@end example
|
| 24074 | |
@noindent
|
| 24075 | |
Don't use this macro, the dignified means to check the nature of the
|
| 24076 | |
host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
|
| 24077 | |
@end defmac
|
| 24078 | |
|
| 24079 | |
@defmac AC_YYTEXT_POINTER
|
| 24080 | |
@acindex{YYTEXT_POINTER}
|
| 24081 | |
This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was
|
| 24082 | |
integrated into @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
|
| 24083 | |
@end defmac
|
| 24084 | |
|
| 24085 | |
@node Autoconf 1
|
| 24086 | |
@section Upgrading From Version 1
|
| 24087 | |
@cindex Upgrading autoconf
|
| 24088 | |
@cindex Autoconf upgrading
|
| 24089 | |
|
| 24090 | |
Autoconf version 2 is mostly backward compatible with version 1.
|
| 24091 | |
However, it introduces better ways to do some things, and doesn't
|
| 24092 | |
support some of the ugly things in version 1. So, depending on how
|
| 24093 | |
sophisticated your @file{configure.ac} files are, you might have to do
|
| 24094 | |
some manual work in order to upgrade to version 2. This chapter points
|
| 24095 | |
out some problems to watch for when upgrading. Also, perhaps your
|
| 24096 | |
@command{configure} scripts could benefit from some of the new features in
|
| 24097 | |
version 2; the changes are summarized in the file @file{NEWS} in the
|
| 24098 | |
Autoconf distribution.
|
| 24099 | |
|
| 24100 | |
@menu
|
| 24101 | |
* Changed File Names:: Files you might rename
|
| 24102 | |
* Changed Makefiles:: New things to put in @file{Makefile.in}
|
| 24103 | |
* Changed Macros:: Macro calls you might replace
|
| 24104 | |
* Changed Results:: Changes in how to check test results
|
| 24105 | |
* Changed Macro Writing:: Better ways to write your own macros
|
| 24106 | |
@end menu
|
| 24107 | |
|
| 24108 | |
@node Changed File Names
|
| 24109 | |
@subsection Changed File Names
|
| 24110 | |
|
| 24111 | |
If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
|
| 24112 | |
in a particular package's source directory), you must rename it to
|
| 24113 | |
@file{acsite.m4}. @xref{autoconf Invocation}.
|
| 24114 | |
|
| 24115 | |
If you distribute @file{install.sh} with your package, rename it to
|
| 24116 | |
@file{install-sh} so @command{make} builtin rules don't inadvertently
|
| 24117 | |
create a file called @file{install} from it. @code{AC_PROG_INSTALL}
|
| 24118 | |
looks for the script under both names, but it is best to use the new name.
|
| 24119 | |
|
| 24120 | |
If you were using @file{config.h.top}, @file{config.h.bot}, or
|
| 24121 | |
@file{acconfig.h}, you still can, but you have less clutter if you
|
| 24122 | |
use the @code{AH_} macros. @xref{Autoheader Macros}.
|
| 24123 | |
|
| 24124 | |
@node Changed Makefiles
|
| 24125 | |
@subsection Changed Makefiles
|
| 24126 | |
|
| 24127 | |
Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
|
| 24128 | |
your @file{Makefile.in} files, so they can take advantage of the values
|
| 24129 | |
of those variables in the environment when @command{configure} is run.
|
| 24130 | |
Doing this isn't necessary, but it's a convenience for users.
|
| 24131 | |
|
| 24132 | |
Also add @samp{@@configure_input@@} in a comment to each input file for
|
| 24133 | |
@code{AC_OUTPUT}, so that the output files contain a comment saying
|
| 24134 | |
they were produced by @command{configure}. Automatically selecting the
|
| 24135 | |
right comment syntax for all the kinds of files that people call
|
| 24136 | |
@code{AC_OUTPUT} on became too much work.
|
| 24137 | |
|
| 24138 | |
Add @file{config.log} and @file{config.cache} to the list of files you
|
| 24139 | |
remove in @code{distclean} targets.
|
| 24140 | |
|
| 24141 | |
If you have the following in @file{Makefile.in}:
|
| 24142 | |
|
| 24143 | |
@example
|
| 24144 | |
prefix = /usr/local
|
| 24145 | |
exec_prefix = $(prefix)
|
| 24146 | |
@end example
|
| 24147 | |
|
| 24148 | |
@noindent
|
| 24149 | |
you must change it to:
|
| 24150 | |
|
| 24151 | |
@example
|
| 24152 | |
prefix = @@prefix@@
|
| 24153 | |
exec_prefix = @@exec_prefix@@
|
| 24154 | |
@end example
|
| 24155 | |
|
| 24156 | |
@noindent
|
| 24157 | |
The old behavior of replacing those variables without @samp{@@}
|
| 24158 | |
characters around them has been removed.
|
| 24159 | |
|
| 24160 | |
@node Changed Macros
|
| 24161 | |
@subsection Changed Macros
|
| 24162 | |
|
| 24163 | |
Many of the macros were renamed in Autoconf version 2. You can still
|
| 24164 | |
use the old names, but the new ones are clearer, and it's easier to find
|
| 24165 | |
the documentation for them. @xref{Obsolete Macros}, for a table showing the
|
| 24166 | |
new names for the old macros. Use the @command{autoupdate} program to
|
| 24167 | |
convert your @file{configure.ac} to using the new macro names.
|
| 24168 | |
@xref{autoupdate Invocation}.
|
| 24169 | |
|
| 24170 | |
Some macros have been superseded by similar ones that do the job better,
|
| 24171 | |
but are not call-compatible. If you get warnings about calling obsolete
|
| 24172 | |
macros while running @command{autoconf}, you may safely ignore them, but
|
| 24173 | |
your @command{configure} script generally works better if you follow
|
| 24174 | |
the advice that is printed about what to replace the obsolete macros with. In
|
| 24175 | |
particular, the mechanism for reporting the results of tests has
|
| 24176 | |
changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
|
| 24177 | |
via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
|
| 24178 | |
looks better if you switch to @code{AC_MSG_CHECKING} and
|
| 24179 | |
@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
|
| 24180 | |
in conjunction with cache variables. @xref{Caching Results}.
|
| 24181 | |
|
| 24182 | |
|
| 24183 | |
|
| 24184 | |
@node Changed Results
|
| 24185 | |
@subsection Changed Results
|
| 24186 | |
|
| 24187 | |
If you were checking the results of previous tests by examining the
|
| 24188 | |
shell variable @code{DEFS}, you need to switch to checking the values of
|
| 24189 | |
the cache variables for those tests. @code{DEFS} no longer exists while
|
| 24190 | |
@command{configure} is running; it is only created when generating output
|
| 24191 | |
files. This difference from version 1 is because properly quoting the
|
| 24192 | |
contents of that variable turned out to be too cumbersome and
|
| 24193 | |
inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
|
| 24194 | |
Variable Names}.
|
| 24195 | |
|
| 24196 | |
For example, here is a @file{configure.ac} fragment written for Autoconf
|
| 24197 | |
version 1:
|
| 24198 | |
|
| 24199 | |
@example
|
| 24200 | |
AC_HAVE_FUNCS(syslog)
|
| 24201 | |
case "$DEFS" in
|
| 24202 | |
*-DHAVE_SYSLOG*) ;;
|
| 24203 | |
*) # syslog is not in the default libraries. See if it's in some other.
|
| 24204 | |
saved_LIBS="$LIBS"
|
| 24205 | |
for lib in bsd socket inet; do
|
| 24206 | |
AC_CHECKING(for syslog in -l$lib)
|
| 24207 | |
LIBS="-l$lib $saved_LIBS"
|
| 24208 | |
AC_HAVE_FUNCS(syslog)
|
| 24209 | |
case "$DEFS" in
|
| 24210 | |
*-DHAVE_SYSLOG*) break ;;
|
| 24211 | |
*) ;;
|
| 24212 | |
esac
|
| 24213 | |
LIBS="$saved_LIBS"
|
| 24214 | |
done ;;
|
| 24215 | |
esac
|
| 24216 | |
@end example
|
| 24217 | |
|
| 24218 | |
Here is a way to write it for version 2:
|
| 24219 | |
|
| 24220 | |
@example
|
| 24221 | |
AC_CHECK_FUNCS([syslog])
|
| 24222 | |
if test "x$ac_cv_func_syslog" = xno; then
|
| 24223 | |
# syslog is not in the default libraries. See if it's in some other.
|
| 24224 | |
for lib in bsd socket inet; do
|
| 24225 | |
AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
|
| 24226 | |
LIBS="-l$lib $LIBS"; break])
|
| 24227 | |
done
|
| 24228 | |
fi
|
| 24229 | |
@end example
|
| 24230 | |
|
| 24231 | |
If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
|
| 24232 | |
backslashes before quotes, you need to remove them. It now works
|
| 24233 | |
predictably, and does not treat quotes (except back quotes) specially.
|
| 24234 | |
@xref{Setting Output Variables}.
|
| 24235 | |
|
| 24236 | |
All of the Boolean shell variables set by Autoconf macros now use
|
| 24237 | |
@samp{yes} for the true value. Most of them use @samp{no} for false,
|
| 24238 | |
though for backward compatibility some use the empty string instead. If
|
| 24239 | |
you were relying on a shell variable being set to something like 1 or
|
| 24240 | |
@samp{t} for true, you need to change your tests.
|
| 24241 | |
|
| 24242 | |
@node Changed Macro Writing
|
| 24243 | |
@subsection Changed Macro Writing
|
| 24244 | |
|
| 24245 | |
When defining your own macros, you should now use @code{AC_DEFUN}
|
| 24246 | |
instead of @code{define}. @code{AC_DEFUN} automatically calls
|
| 24247 | |
@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
|
| 24248 | |
do not interrupt other macros, to prevent nested @samp{checking@dots{}}
|
| 24249 | |
messages on the screen. There's no actual harm in continuing to use the
|
| 24250 | |
older way, but it's less convenient and attractive. @xref{Macro
|
| 24251 | |
Definitions}.
|
| 24252 | |
|
| 24253 | |
You probably looked at the macros that came with Autoconf as a guide for
|
| 24254 | |
how to do things. It would be a good idea to take a look at the new
|
| 24255 | |
versions of them, as the style is somewhat improved and they take
|
| 24256 | |
advantage of some new features.
|
| 24257 | |
|
| 24258 | |
If you were doing tricky things with undocumented Autoconf internals
|
| 24259 | |
(macros, variables, diversions), check whether you need to change
|
| 24260 | |
anything to account for changes that have been made. Perhaps you can
|
| 24261 | |
even use an officially supported technique in version 2 instead of
|
| 24262 | |
kludging. Or perhaps not.
|
| 24263 | |
|
| 24264 | |
To speed up your locally written feature tests, add caching to them.
|
| 24265 | |
See whether any of your tests are of general enough usefulness to
|
| 24266 | |
encapsulate them into macros that you can share.
|
| 24267 | |
|
| 24268 | |
|
| 24269 | |
@node Autoconf 2.13
|
| 24270 | |
@section Upgrading From Version 2.13
|
| 24271 | |
@cindex Upgrading autoconf
|
| 24272 | |
@cindex Autoconf upgrading
|
| 24273 | |
|
| 24274 | |
The introduction of the previous section (@pxref{Autoconf 1}) perfectly
|
| 24275 | |
suits this section@enddots{}
|
| 24276 | |
|
| 24277 | |
@quotation
|
| 24278 | |
Autoconf version 2.50 is mostly backward compatible with version 2.13.
|
| 24279 | |
However, it introduces better ways to do some things, and doesn't
|
| 24280 | |
support some of the ugly things in version 2.13. So, depending on how
|
| 24281 | |
sophisticated your @file{configure.ac} files are, you might have to do
|
| 24282 | |
some manual work in order to upgrade to version 2.50. This chapter
|
| 24283 | |
points out some problems to watch for when upgrading. Also, perhaps
|
| 24284 | |
your @command{configure} scripts could benefit from some of the new
|
| 24285 | |
features in version 2.50; the changes are summarized in the file
|
| 24286 | |
@file{NEWS} in the Autoconf distribution.
|
| 24287 | |
@end quotation
|
| 24288 | |
|
| 24289 | |
@menu
|
| 24290 | |
* Changed Quotation:: Broken code which used to work
|
| 24291 | |
* New Macros:: Interaction with foreign macros
|
| 24292 | |
* Hosts and Cross-Compilation:: Bugward compatibility kludges
|
| 24293 | |
* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
|
| 24294 | |
* AC_ACT_IFELSE vs AC_TRY_ACT:: A more generic scheme for testing sources
|
| 24295 | |
@end menu
|
| 24296 | |
|
| 24297 | |
@node Changed Quotation
|
| 24298 | |
@subsection Changed Quotation
|
| 24299 | |
|
| 24300 | |
The most important changes are invisible to you: the implementation of
|
| 24301 | |
most macros have completely changed. This allowed more factorization of
|
| 24302 | |
the code, better error messages, a higher uniformity of the user's
|
| 24303 | |
interface etc. Unfortunately, as a side effect, some construct which
|
| 24304 | |
used to (miraculously) work might break starting with Autoconf 2.50.
|
| 24305 | |
The most common culprit is bad quotation.
|
| 24306 | |
|
| 24307 | |
For instance, in the following example, the message is not properly
|
| 24308 | |
quoted:
|
| 24309 | |
|
| 24310 | |
@example
|
| 24311 | |
AC_INIT
|
| 24312 | |
AC_CHECK_HEADERS(foo.h, ,
|
| 24313 | |
AC_MSG_ERROR(cannot find foo.h, bailing out))
|
| 24314 | |
AC_OUTPUT
|
| 24315 | |
@end example
|
| 24316 | |
|
| 24317 | |
@noindent
|
| 24318 | |
Autoconf 2.13 simply ignores it:
|
| 24319 | |
|
| 24320 | |
@example
|
| 24321 | |
$ @kbd{autoconf-2.13; ./configure --silent}
|
| 24322 | |
creating cache ./config.cache
|
| 24323 | |
configure: error: cannot find foo.h
|
| 24324 | |
$
|
| 24325 | |
@end example
|
| 24326 | |
|
| 24327 | |
@noindent
|
| 24328 | |
while Autoconf 2.50 produces a broken @file{configure}:
|
| 24329 | |
|
| 24330 | |
@example
|
| 24331 | |
$ @kbd{autoconf-2.50; ./configure --silent}
|
| 24332 | |
configure: error: cannot find foo.h
|
| 24333 | |
./configure: exit: bad non-numeric arg `bailing'
|
| 24334 | |
./configure: exit: bad non-numeric arg `bailing'
|
| 24335 | |
$
|
| 24336 | |
@end example
|
| 24337 | |
|
| 24338 | |
The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
|
| 24339 | |
too!
|
| 24340 | |
|
| 24341 | |
@example
|
| 24342 | |
AC_INIT([Example], [1.0], [bug-example@@example.org])
|
| 24343 | |
AC_CHECK_HEADERS([foo.h], [],
|
| 24344 | |
[AC_MSG_ERROR([cannot find foo.h, bailing out])])
|
| 24345 | |
AC_OUTPUT
|
| 24346 | |
@end example
|
| 24347 | |
|
| 24348 | |
Many many (and many more) Autoconf macros were lacking proper quotation,
|
| 24349 | |
including no less than@dots{} @code{AC_DEFUN} itself!
|
| 24350 | |
|
| 24351 | |
@example
|
| 24352 | |
$ @kbd{cat configure.in}
|
| 24353 | |
AC_DEFUN([AC_PROG_INSTALL],
|
| 24354 | |
[# My own much better version
|
| 24355 | |
])
|
| 24356 | |
AC_INIT
|
| 24357 | |
AC_PROG_INSTALL
|
| 24358 | |
AC_OUTPUT
|
| 24359 | |
$ @kbd{autoconf-2.13}
|
| 24360 | |
autoconf: Undefined macros:
|
| 24361 | |
***BUG in Autoconf--please report*** AC_FD_MSG
|
| 24362 | |
***BUG in Autoconf--please report*** AC_EPI
|
| 24363 | |
configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
|
| 24364 | |
configure.in:5:AC_PROG_INSTALL
|
| 24365 | |
$ @kbd{autoconf-2.50}
|
| 24366 | |
$
|
| 24367 | |
@end example
|
| 24368 | |
|
| 24369 | |
|
| 24370 | |
@node New Macros
|
| 24371 | |
@subsection New Macros
|
| 24372 | |
|
| 24373 | |
@cindex undefined macro
|
| 24374 | |
@cindex @code{_m4_divert_diversion}
|
| 24375 | |
|
| 24376 | |
While Autoconf was relatively dormant in the late 1990s, Automake
|
| 24377 | |
provided Autoconf-like macros for a while. Starting with Autoconf 2.50
|
| 24378 | |
in 2001, Autoconf provided
|
| 24379 | |
versions of these macros, integrated in the @code{AC_} namespace,
|
| 24380 | |
instead of @code{AM_}. But in order to ease the upgrading via
|
| 24381 | |
@command{autoupdate}, bindings to such @code{AM_} macros are provided.
|
| 24382 | |
|
| 24383 | |
Unfortunately older versions of Automake (e.g., Automake 1.4)
|
| 24384 | |
did not quote the names of these macros.
|
| 24385 | |
Therefore, when @command{m4} finds something like
|
| 24386 | |
@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
|
| 24387 | |
@code{AM_TYPE_PTRDIFF_T} is
|
| 24388 | |
expanded, replaced with its Autoconf definition.
|
| 24389 | |
|
| 24390 | |
Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
|
| 24391 | |
complains, in its own words:
|
| 24392 | |
|
| 24393 | |
@example
|
| 24394 | |
$ @kbd{cat configure.ac}
|
| 24395 | |
AC_INIT([Example], [1.0], [bug-example@@example.org])
|
| 24396 | |
AM_TYPE_PTRDIFF_T
|
| 24397 | |
$ @kbd{aclocal-1.4}
|
| 24398 | |
$ @kbd{autoconf}
|
| 24399 | |
aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
|
| 24400 | |
aclocal.m4:17: the top level
|
| 24401 | |
autom4te: m4 failed with exit status: 1
|
| 24402 | |
$
|
| 24403 | |
@end example
|
| 24404 | |
|
| 24405 | |
Modern versions of Automake no longer define most of these
|
| 24406 | |
macros, and properly quote the names of the remaining macros.
|
| 24407 | |
If you must use an old Automake, do not depend upon macros from Automake
|
| 24408 | |
as it is simply not its job
|
| 24409 | |
to provide macros (but the one it requires itself):
|
| 24410 | |
|
| 24411 | |
@example
|
| 24412 | |
$ @kbd{cat configure.ac}
|
| 24413 | |
AC_INIT([Example], [1.0], [bug-example@@example.org])
|
| 24414 | |
AM_TYPE_PTRDIFF_T
|
| 24415 | |
$ @kbd{rm aclocal.m4}
|
| 24416 | |
$ @kbd{autoupdate}
|
| 24417 | |
autoupdate: `configure.ac' is updated
|
| 24418 | |
$ @kbd{cat configure.ac}
|
| 24419 | |
AC_INIT([Example], [1.0], [bug-example@@example.org])
|
| 24420 | |
AC_CHECK_TYPES([ptrdiff_t])
|
| 24421 | |
$ @kbd{aclocal-1.4}
|
| 24422 | |
$ @kbd{autoconf}
|
| 24423 | |
$
|
| 24424 | |
@end example
|
| 24425 | |
|
| 24426 | |
|
| 24427 | |
@node Hosts and Cross-Compilation
|
| 24428 | |
@subsection Hosts and Cross-Compilation
|
| 24429 | |
@cindex Cross compilation
|
| 24430 | |
|
| 24431 | |
Based on the experience of compiler writers, and after long public
|
| 24432 | |
debates, many aspects of the cross-compilation chain have changed:
|
| 24433 | |
|
| 24434 | |
@itemize @minus
|
| 24435 | |
@item
|
| 24436 | |
the relationship between the build, host, and target architecture types,
|
| 24437 | |
|
| 24438 | |
@item
|
| 24439 | |
the command line interface for specifying them to @command{configure},
|
| 24440 | |
|
| 24441 | |
@item
|
| 24442 | |
the variables defined in @command{configure},
|
| 24443 | |
|
| 24444 | |
@item
|
| 24445 | |
the enabling of cross-compilation mode.
|
| 24446 | |
@end itemize
|
| 24447 | |
|
| 24448 | |
@sp 1
|
| 24449 | |
|
| 24450 | |
The relationship between build, host, and target have been cleaned up:
|
| 24451 | |
the chain of default is now simply: target defaults to host, host to
|
| 24452 | |
build, and build to the result of @command{config.guess}. Nevertheless,
|
| 24453 | |
in order to ease the transition from 2.13 to 2.50, the following
|
| 24454 | |
transition scheme is implemented. @emph{Do not rely on it}, as it will
|
| 24455 | |
be completely disabled in a couple of releases (we cannot keep it, as it
|
| 24456 | |
proves to cause more problems than it cures).
|
| 24457 | |
|
| 24458 | |
They all default to the result of running @command{config.guess}, unless
|
| 24459 | |
you specify either @option{--build} or @option{--host}. In this case,
|
| 24460 | |
the default becomes the system type you specified. If you specify both,
|
| 24461 | |
and they're different, @command{configure} enters cross compilation
|
| 24462 | |
mode, so it doesn't run any tests that require execution.
|
| 24463 | |
|
| 24464 | |
Hint: if you mean to override the result of @command{config.guess},
|
| 24465 | |
prefer @option{--build} over @option{--host}.
|
| 24466 | |
|
| 24467 | |
@sp 1
|
| 24468 | |
|
| 24469 | |
For backward compatibility, @command{configure} accepts a system
|
| 24470 | |
type as an option by itself. Such an option overrides the
|
| 24471 | |
defaults for build, host, and target system types. The following
|
| 24472 | |
configure statement configures a cross toolchain that runs on
|
| 24473 | |
NetBSD/alpha but generates code for GNU Hurd/sparc,
|
| 24474 | |
which is also the build platform.
|
| 24475 | |
|
| 24476 | |
@example
|
| 24477 | |
./configure --host=alpha-netbsd sparc-gnu
|
| 24478 | |
@end example
|
| 24479 | |
|
| 24480 | |
@sp 1
|
| 24481 | |
|
| 24482 | |
In Autoconf 2.13 and before, the variables @code{build}, @code{host},
|
| 24483 | |
and @code{target} had a different semantics before and after the
|
| 24484 | |
invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
|
| 24485 | |
@option{--build} is strictly copied into @code{build_alias}, and is left
|
| 24486 | |
empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
|
| 24487 | |
set to the canonicalized build type. To ease the transition, before,
|
| 24488 | |
its contents is the same as that of @code{build_alias}. Do @emph{not}
|
| 24489 | |
rely on this broken feature.
|
| 24490 | |
|
| 24491 | |
For consistency with the backward compatibility scheme exposed above,
|
| 24492 | |
when @option{--host} is specified but @option{--build} isn't, the build
|
| 24493 | |
system is assumed to be the same as @option{--host}, and
|
| 24494 | |
@samp{build_alias} is set to that value. Eventually, this
|
| 24495 | |
historically incorrect behavior will go away.
|
| 24496 | |
|
| 24497 | |
@sp 1
|
| 24498 | |
|
| 24499 | |
The former scheme to enable cross-compilation proved to cause more harm
|
| 24500 | |
than good, in particular, it used to be triggered too easily, leaving
|
| 24501 | |
regular end users puzzled in front of cryptic error messages.
|
| 24502 | |
@command{configure} could even enter cross-compilation mode only
|
| 24503 | |
because the compiler was not functional. This is mainly because
|
| 24504 | |
@command{configure} used to try to detect cross-compilation, instead of
|
| 24505 | |
waiting for an explicit flag from the user.
|
| 24506 | |
|
| 24507 | |
Now, @command{configure} enters cross-compilation mode if and only if
|
| 24508 | |
@option{--host} is passed.
|
| 24509 | |
|
| 24510 | |
That's the short documentation. To ease the transition between 2.13 and
|
| 24511 | |
its successors, a more complicated scheme is implemented. @emph{Do not
|
| 24512 | |
rely on the following}, as it will be removed in the near future.
|
| 24513 | |
|
| 24514 | |
If you specify @option{--host}, but not @option{--build}, when
|
| 24515 | |
@command{configure} performs the first compiler test it tries to run
|
| 24516 | |
an executable produced by the compiler. If the execution fails, it
|
| 24517 | |
enters cross-compilation mode. This is fragile. Moreover, by the time
|
| 24518 | |
the compiler test is performed, it may be too late to modify the
|
| 24519 | |
build-system type: other tests may have already been performed.
|
| 24520 | |
Therefore, whenever you specify @option{--host}, be sure to specify
|
| 24521 | |
@option{--build} too.
|
| 24522 | |
|
| 24523 | |
@example
|
| 24524 | |
./configure --build=i686-pc-linux-gnu --host=m68k-coff
|
| 24525 | |
@end example
|
| 24526 | |
|
| 24527 | |
@noindent
|
| 24528 | |
enters cross-compilation mode. The former interface, which
|
| 24529 | |
consisted in setting the compiler to a cross-compiler without informing
|
| 24530 | |
@command{configure} is obsolete. For instance, @command{configure}
|
| 24531 | |
fails if it can't run the code generated by the specified compiler if you
|
| 24532 | |
configure as follows:
|
| 24533 | |
|
| 24534 | |
@example
|
| 24535 | |
./configure CC=m68k-coff-gcc
|
| 24536 | |
@end example
|
| 24537 | |
|
| 24538 | |
|
| 24539 | |
@node AC_LIBOBJ vs LIBOBJS
|
| 24540 | |
@subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
|
| 24541 | |
|
| 24542 | |
Up to Autoconf 2.13, the replacement of functions was triggered via the
|
| 24543 | |
variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
|
| 24544 | |
@code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
|
| 24545 | |
Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
|
| 24546 | |
|
| 24547 | |
This change is mandated by the unification of the GNU Build System
|
| 24548 | |
components. In particular, the various fragile techniques used to parse
|
| 24549 | |
a @file{configure.ac} are all replaced with the use of traces. As a
|
| 24550 | |
consequence, any action must be traceable, which obsoletes critical
|
| 24551 | |
variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
|
| 24552 | |
and it can even be handled gracefully (read, ``without your having to
|
| 24553 | |
change something'').
|
| 24554 | |
|
| 24555 | |
There were two typical uses of @code{LIBOBJS}: asking for a replacement
|
| 24556 | |
function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
|
| 24557 | |
|
| 24558 | |
@sp 1
|
| 24559 | |
|
| 24560 | |
As for function replacement, the fix is immediate: use
|
| 24561 | |
@code{AC_LIBOBJ}. For instance:
|
| 24562 | |
|
| 24563 | |
@example
|
| 24564 | |
LIBOBJS="$LIBOBJS fnmatch.o"
|
| 24565 | |
LIBOBJS="$LIBOBJS malloc.$ac_objext"
|
| 24566 | |
@end example
|
| 24567 | |
|
| 24568 | |
@noindent
|
| 24569 | |
should be replaced with:
|
| 24570 | |
|
| 24571 | |
@example
|
| 24572 | |
AC_LIBOBJ([fnmatch])
|
| 24573 | |
AC_LIBOBJ([malloc])
|
| 24574 | |
@end example
|
| 24575 | |
|
| 24576 | |
@sp 1
|
| 24577 | |
|
| 24578 | |
@ovindex LIBOBJDIR
|
| 24579 | |
When used with Automake 1.10 or newer, a suitable value for
|
| 24580 | |
@code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
|
| 24581 | |
can be referenced from any @file{Makefile.am}. Even without Automake,
|
| 24582 | |
arranging for @code{LIBOBJDIR} to be set correctly enables
|
| 24583 | |
referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
|
| 24584 | |
The @code{LIBOBJDIR} feature is experimental.
|
| 24585 | |
|
| 24586 | |
|
| 24587 | |
@node AC_ACT_IFELSE vs AC_TRY_ACT
|
| 24588 | |
@subsection @code{AC_@var{ACT}_IFELSE} vs.@: @code{AC_TRY_@var{ACT}}
|
| 24589 | |
@c the anchor keeps the old node name, to try to avoid breaking links
|
| 24590 | |
@anchor{AC_FOO_IFELSE vs AC_TRY_FOO}
|
| 24591 | |
|
| 24592 | |
@acindex{@var{ACT}_IFELSE}
|
| 24593 | |
@acindex{TRY_@var{ACT}}
|
| 24594 | |
Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
|
| 24595 | |
@code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
|
| 24596 | |
@code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCE},
|
| 24597 | |
and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
|
| 24598 | |
@code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
|
| 24599 | |
@code{AC_TRY_RUN}. The motivations where:
|
| 24600 | |
@itemize @minus
|
| 24601 | |
@item
|
| 24602 | |
a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
|
| 24603 | |
quoting their arguments;
|
| 24604 | |
|
| 24605 | |
@item
|
| 24606 | |
the combinatoric explosion is solved by decomposing on the one hand the
|
| 24607 | |
generation of sources, and on the other hand executing the program;
|
| 24608 | |
|
| 24609 | |
@item
|
| 24610 | |
this scheme helps supporting more languages than plain C and C++.
|
| 24611 | |
@end itemize
|
| 24612 | |
|
| 24613 | |
In addition to the change of syntax, the philosophy has changed too:
|
| 24614 | |
while emphasis was put on speed at the expense of accuracy, today's
|
| 24615 | |
Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
|
| 24616 | |
expense of speed.
|
| 24617 | |
|
| 24618 | |
|
| 24619 | |
As a perfect example of what is @emph{not} to be done, here is how to
|
| 24620 | |
find out whether a header file contains a particular declaration, such
|
| 24621 | |
as a typedef, a structure, a structure member, or a function. Use
|
| 24622 | |
@code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
|
| 24623 | |
header file; on some systems the symbol might be defined in another
|
| 24624 | |
header file that the file you are checking includes.
|
| 24625 | |
|
| 24626 | |
As a (bad) example, here is how you should not check for C preprocessor
|
| 24627 | |
symbols, either defined by header files or predefined by the C
|
| 24628 | |
preprocessor: using @code{AC_EGREP_CPP}:
|
| 24629 | |
|
| 24630 | |
@example
|
| 24631 | |
@group
|
| 24632 | |
AC_EGREP_CPP(yes,
|
| 24633 | |
[#ifdef _AIX
|
| 24634 | |
yes
|
| 24635 | |
#endif
|
| 24636 | |
], is_aix=yes, is_aix=no)
|
| 24637 | |
@end group
|
| 24638 | |
@end example
|
| 24639 | |
|
| 24640 | |
The above example, properly written would (i) use
|
| 24641 | |
@code{AC_LANG_PROGRAM}, and (ii) run the compiler:
|
| 24642 | |
|
| 24643 | |
@example
|
| 24644 | |
@group
|
| 24645 | |
AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
|
| 24646 | |
[[#ifndef _AIX
|
| 24647 | |
error: This isn't AIX!
|
| 24648 | |
#endif
|
| 24649 | |
]])],
|
| 24650 | |
[is_aix=yes],
|
| 24651 | |
[is_aix=no])
|
| 24652 | |
@end group
|
| 24653 | |
@end example
|
| 24654 | |
|
| 24655 | |
|
| 24656 | |
@c ============================= Generating Test Suites with Autotest
|
| 24657 | |
|
| 24658 | |
@node Using Autotest
|
| 24659 | |
@chapter Generating Test Suites with Autotest
|
| 24660 | |
|
| 24661 | |
@cindex Autotest
|
| 24662 | |
|
| 24663 | |
@display
|
| 24664 | |
@strong{N.B.: This section describes a feature which is still
|
| 24665 | |
stabilizing. Although we believe that Autotest is useful as-is, this
|
| 24666 | |
documentation describes an interface which might change in the future:
|
| 24667 | |
do not depend upon Autotest without subscribing to the Autoconf mailing
|
| 24668 | |
lists.}
|
| 24669 | |
@end display
|
| 24670 | |
|
| 24671 | |
It is paradoxical that portable projects depend on nonportable tools
|
| 24672 | |
to run their test suite. Autoconf by itself is the paragon of this
|
| 24673 | |
problem: although it aims at perfectly portability, up to 2.13 its
|
| 24674 | |
test suite was using DejaGNU, a rich and complex testing
|
| 24675 | |
framework, but which is far from being standard on Posix systems.
|
| 24676 | |
Worse yet, it was likely to be missing on the most fragile platforms,
|
| 24677 | |
the very platforms that are most likely to torture Autoconf and
|
| 24678 | |
exhibit deficiencies.
|
| 24679 | |
|
| 24680 | |
To circumvent this problem, many package maintainers have developed their
|
| 24681 | |
own testing framework, based on simple shell scripts whose sole outputs
|
| 24682 | |
are exit status values describing whether the test succeeded. Most of
|
| 24683 | |
these tests share common patterns, and this can result in lots of
|
| 24684 | |
duplicated code and tedious maintenance.
|
| 24685 | |
|
| 24686 | |
Following exactly the same reasoning that yielded to the inception of
|
| 24687 | |
Autoconf, Autotest provides a test suite generation framework, based on
|
| 24688 | |
M4 macros building a portable shell script. The suite itself is
|
| 24689 | |
equipped with automatic logging and tracing facilities which greatly
|
| 24690 | |
diminish the interaction with bug reporters, and simple timing reports.
|
| 24691 | |
|
| 24692 | |
Autoconf itself has been using Autotest for years, and we do attest that
|
| 24693 | |
it has considerably improved the strength of the test suite and the
|
| 24694 | |
quality of bug reports. Other projects are known to use some generation
|
| 24695 | |
of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of
|
| 24696 | |
them with different needs, and this usage has validated Autotest as a general
|
| 24697 | |
testing framework.
|
| 24698 | |
|
| 24699 | |
Nonetheless, compared to DejaGNU, Autotest is inadequate for
|
| 24700 | |
interactive tool testing, which is probably its main limitation.
|
| 24701 | |
|
| 24702 | |
@menu
|
| 24703 | |
* Using an Autotest Test Suite:: Autotest and the user
|
| 24704 | |
* Writing Testsuites:: Autotest macros
|
| 24705 | |
* testsuite Invocation:: Running @command{testsuite} scripts
|
| 24706 | |
* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
|
| 24707 | |
@end menu
|
| 24708 | |
|
| 24709 | |
@node Using an Autotest Test Suite
|
| 24710 | |
@section Using an Autotest Test Suite
|
| 24711 | |
|
| 24712 | |
@menu
|
| 24713 | |
* testsuite Scripts:: The concepts of Autotest
|
| 24714 | |
* Autotest Logs:: Their contents
|
| 24715 | |
@end menu
|
| 24716 | |
|
| 24717 | |
@node testsuite Scripts
|
| 24718 | |
@subsection @command{testsuite} Scripts
|
| 24719 | |
|
| 24720 | |
@cindex @command{testsuite}
|
| 24721 | |
|
| 24722 | |
Generating testing or validation suites using Autotest is rather easy.
|
| 24723 | |
The whole validation suite is held in a file to be processed through
|
| 24724 | |
@command{autom4te}, itself using GNU M4 under the hood, to
|
| 24725 | |
produce a stand-alone Bourne shell script which then gets distributed.
|
| 24726 | |
Neither @command{autom4te} nor GNU M4 are needed at
|
| 24727 | |
the installer's end.
|
| 24728 | |
|
| 24729 | |
@cindex test group
|
| 24730 | |
Each test of the validation suite should be part of some test group. A
|
| 24731 | |
@dfn{test group} is a sequence of interwoven tests that ought to be
|
| 24732 | |
executed together, usually because one test in the group creates data
|
| 24733 | |
files that a later test in the same group needs to read. Complex test
|
| 24734 | |
groups make later debugging more tedious. It is much better to
|
| 24735 | |
keep only a few tests per test group. Ideally there is only one test
|
| 24736 | |
per test group.
|
| 24737 | |
|
| 24738 | |
For all but the simplest packages, some file such as @file{testsuite.at}
|
| 24739 | |
does not fully hold all test sources, as these are often easier to
|
| 24740 | |
maintain in separate files. Each of these separate files holds a single
|
| 24741 | |
test group, or a sequence of test groups all addressing some common
|
| 24742 | |
functionality in the package. In such cases, @file{testsuite.at}
|
| 24743 | |
merely initializes the validation suite, and sometimes does elementary
|
| 24744 | |
health checking, before listing include statements for all other test
|
| 24745 | |
files. The special file @file{package.m4}, containing the
|
| 24746 | |
identification of the package, is automatically included if found.
|
| 24747 | |
|
| 24748 | |
A convenient alternative consists in moving all the global issues
|
| 24749 | |
(local Autotest macros, elementary health checking, and @code{AT_INIT}
|
| 24750 | |
invocation) into the file @code{local.at}, and making
|
| 24751 | |
@file{testsuite.at} be a simple list of @code{m4_include}s of sub test
|
| 24752 | |
suites. In such case, generating the whole test suite or pieces of it
|
| 24753 | |
is only a matter of choosing the @command{autom4te} command line
|
| 24754 | |
arguments.
|
| 24755 | |
|
| 24756 | |
The validation scripts that Autotest produces are by convention called
|
| 24757 | |
@command{testsuite}. When run, @command{testsuite} executes each test
|
| 24758 | |
group in turn, producing only one summary line per test to say if that
|
| 24759 | |
particular test succeeded or failed. At end of all tests, summarizing
|
| 24760 | |
counters get printed. One debugging directory is left for each test
|
| 24761 | |
group which failed, if any: such directories are named
|
| 24762 | |
@file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
|
| 24763 | |
the test group, and they include:
|
| 24764 | |
|
| 24765 | |
@itemize @bullet
|
| 24766 | |
@item a debugging script named @file{run} which reruns the test in
|
| 24767 | |
@dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
|
| 24768 | |
of debugging scripts has the purpose of easing the chase for bugs.
|
| 24769 | |
|
| 24770 | |
@item all the files created with @code{AT_DATA}
|
| 24771 | |
|
| 24772 | |
@item all the Erlang source code files created with @code{AT_CHECK_EUNIT}
|
| 24773 | |
|
| 24774 | |
@item a log of the run, named @file{testsuite.log}
|
| 24775 | |
@end itemize
|
| 24776 | |
|
| 24777 | |
In the ideal situation, none of the tests fail, and consequently no
|
| 24778 | |
debugging directory is left behind for validation.
|
| 24779 | |
|
| 24780 | |
It often happens in practice that individual tests in the validation
|
| 24781 | |
suite need to get information coming out of the configuration process.
|
| 24782 | |
Some of this information, common for all validation suites, is provided
|
| 24783 | |
through the file @file{atconfig}, automatically created by
|
| 24784 | |
@code{AC_CONFIG_TESTDIR}. For configuration information which your
|
| 24785 | |
testing environment specifically needs, you might prepare an optional
|
| 24786 | |
file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
|
| 24787 | |
The configuration process produces @file{atconfig} and @file{atlocal}
|
| 24788 | |
out of these two input files, and these two produced files are
|
| 24789 | |
automatically read by the @file{testsuite} script.
|
| 24790 | |
|
| 24791 | |
Here is a diagram showing the relationship between files.
|
| 24792 | |
|
| 24793 | |
@noindent
|
| 24794 | |
Files used in preparing a software package for distribution:
|
| 24795 | |
|
| 24796 | |
@example
|
| 24797 | |
[package.m4] -->.
|
| 24798 | |
\
|
| 24799 | |
subfile-1.at ->. [local.at] ---->+
|
| 24800 | |
... \ \
|
| 24801 | |
subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
|
| 24802 | |
... /
|
| 24803 | |
subfile-n.at ->'
|
| 24804 | |
@end example
|
| 24805 | |
|
| 24806 | |
@noindent
|
| 24807 | |
Files used in configuring a software package:
|
| 24808 | |
|
| 24809 | |
@example
|
| 24810 | |
.--> atconfig
|
| 24811 | |
/
|
| 24812 | |
[atlocal.in] --> config.status* --<
|
| 24813 | |
\
|
| 24814 | |
`--> [atlocal]
|
| 24815 | |
@end example
|
| 24816 | |
|
| 24817 | |
@noindent
|
| 24818 | |
Files created during test suite execution:
|
| 24819 | |
|
| 24820 | |
@example
|
| 24821 | |
atconfig -->. .--> testsuite.log
|
| 24822 | |
\ /
|
| 24823 | |
>-- testsuite* --<
|
| 24824 | |
/ \
|
| 24825 | |
[atlocal] ->' `--> [testsuite.dir]
|
| 24826 | |
@end example
|
| 24827 | |
|
| 24828 | |
|
| 24829 | |
@node Autotest Logs
|
| 24830 | |
@subsection Autotest Logs
|
| 24831 | |
|
| 24832 | |
When run, the test suite creates a log file named after itself, e.g., a
|
| 24833 | |
test suite named @command{testsuite} creates @file{testsuite.log}. It
|
| 24834 | |
contains a lot of information, usually more than maintainers actually
|
| 24835 | |
need, but therefore most of the time it contains all that is needed:
|
| 24836 | |
|
| 24837 | |
@table @asis
|
| 24838 | |
@item command line arguments
|
| 24839 | |
A bad but unfortunately widespread habit consists of
|
| 24840 | |
setting environment variables before the command, such as in
|
| 24841 | |
@samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
|
| 24842 | |
know this change, hence (i) it cannot report it to you, and (ii)
|
| 24843 | |
it cannot preserve the value of @code{CC} for subsequent runs.
|
| 24844 | |
Autoconf faced exactly the same problem, and solved it by asking
|
| 24845 | |
users to pass the variable definitions as command line arguments.
|
| 24846 | |
Autotest requires this rule, too, but has no means to enforce it; the log
|
| 24847 | |
then contains a trace of the variables that were changed by the user.
|
| 24848 | |
|
| 24849 | |
@item @file{ChangeLog} excerpts
|
| 24850 | |
The topmost lines of all the @file{ChangeLog} files found in the source
|
| 24851 | |
hierarchy. This is especially useful when bugs are reported against
|
| 24852 | |
development versions of the package, since the version string does not
|
| 24853 | |
provide sufficient information to know the exact state of the sources
|
| 24854 | |
the user compiled. Of course, this relies on the use of a
|
| 24855 | |
@file{ChangeLog}.
|
| 24856 | |
|
| 24857 | |
@item build machine
|
| 24858 | |
Running a test suite in a cross-compile environment is not an easy task,
|
| 24859 | |
since it would mean having the test suite run on a machine @var{build},
|
| 24860 | |
while running programs on a machine @var{host}. It is much simpler to
|
| 24861 | |
run both the test suite and the programs on @var{host}, but then, from
|
| 24862 | |
the point of view of the test suite, there remains a single environment,
|
| 24863 | |
@var{host} = @var{build}. The log contains relevant information on the
|
| 24864 | |
state of the @var{build} machine, including some important environment
|
| 24865 | |
variables.
|
| 24866 | |
@c FIXME: How about having an M4sh macro to say `hey, log the value
|
| 24867 | |
@c of `@dots{}'? This would help both Autoconf and Autotest.
|
| 24868 | |
|
| 24869 | |
@item tested programs
|
| 24870 | |
The absolute file name and answers to @option{--version} of the tested
|
| 24871 | |
programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
|
| 24872 | |
|
| 24873 | |
@item configuration log
|
| 24874 | |
The contents of @file{config.log}, as created by @command{configure},
|
| 24875 | |
are appended. It contains the configuration flags and a detailed report
|
| 24876 | |
on the configuration itself.
|
| 24877 | |
@end table
|
| 24878 | |
|
| 24879 | |
|
| 24880 | |
@node Writing Testsuites
|
| 24881 | |
@section Writing @file{testsuite.at}
|
| 24882 | |
|
| 24883 | |
The @file{testsuite.at} is a Bourne shell script making use of special
|
| 24884 | |
Autotest M4 macros. It often contains a call to @code{AT_INIT} near
|
| 24885 | |
its beginning followed by one call to @code{m4_include} per source file
|
| 24886 | |
for tests. Each such included file, or the remainder of
|
| 24887 | |
@file{testsuite.at} if include files are not used, contain a sequence of
|
| 24888 | |
test groups. Each test group begins with a call to @code{AT_SETUP},
|
| 24889 | |
then an arbitrary number of shell commands or calls to @code{AT_CHECK},
|
| 24890 | |
and then completes with a call to @code{AT_CLEANUP}. Multiple test
|
| 24891 | |
groups can be categorized by a call to @code{AT_BANNER}.
|
| 24892 | |
|
| 24893 | |
All of the public Autotest macros have all-uppercase names in the
|
| 24894 | |
namespace @samp{^AT_} to prevent them from accidentally conflicting with
|
| 24895 | |
other text; Autoconf also reserves the namespace @samp{^_AT_} for
|
| 24896 | |
internal macros. All shell variables used in the testsuite for internal
|
| 24897 | |
purposes have mostly-lowercase names starting with @samp{at_}. Autotest
|
| 24898 | |
also uses here-document delimiters in the namespace @samp{^_AT[A-Z]}, and
|
| 24899 | |
makes use of the file system namespace @samp{^at-}.
|
| 24900 | |
|
| 24901 | |
Since Autoconf is built on top of M4sugar (@pxref{Programming in
|
| 24902 | |
M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
|
| 24903 | |
of those namespaces (@samp{^_?\(m4\|AS\)_}). In general, you
|
| 24904 | |
@emph{should not use} the namespace of a package that does not own the
|
| 24905 | |
macro or shell code you are writing.
|
| 24906 | |
|
| 24907 | |
@defmac AT_INIT (@ovar{name})
|
| 24908 | |
@atindex{INIT}
|
| 24909 | |
@c FIXME: Not clear, plus duplication of the information.
|
| 24910 | |
Initialize Autotest. Giving a @var{name} to the test suite is
|
| 24911 | |
encouraged if your package includes several test suites. Before this
|
| 24912 | |
macro is called, @code{AT_PACKAGE_STRING} and
|
| 24913 | |
@code{AT_PACKAGE_BUGREPORT} must be defined, which are used to display
|
| 24914 | |
information about the testsuite to the user. Typically, these macros
|
| 24915 | |
are provided by a file @file{package.m4} built by @command{make}
|
| 24916 | |
(@pxref{Making testsuite Scripts}), in order to inherit the package
|
| 24917 | |
name, version, and bug reporting address from @file{configure.ac}.
|
| 24918 | |
@end defmac
|
| 24919 | |
|
| 24920 | |
@defmac AT_COPYRIGHT (@var{copyright-notice})
|
| 24921 | |
@atindex{COPYRIGHT}
|
| 24922 | |
@cindex Copyright Notice
|
| 24923 | |
State that, in addition to the Free Software Foundation's copyright on
|
| 24924 | |
the Autotest macros, parts of your test suite are covered by
|
| 24925 | |
@var{copyright-notice}.
|
| 24926 | |
|
| 24927 | |
The @var{copyright-notice} shows up in both the head of
|
| 24928 | |
@command{testsuite} and in @samp{testsuite --version}.
|
| 24929 | |
@end defmac
|
| 24930 | |
|
| 24931 | |
@defmac AT_ARG_OPTION (@var{options}, @var{help-text}, @
|
| 24932 | |
@ovar{action-if-given}, @ovar{action-if-not-given})
|
| 24933 | |
@atindex{ARG_OPTION}
|
| 24934 | |
@vrindex at_arg_@var{option}
|
| 24935 | |
Accept options from the space-separated list @var{options}, a list that
|
| 24936 | |
has leading dashes removed from the options. Long options will be
|
| 24937 | |
prefixed with @samp{--}, single-character options with @samp{-}. The
|
| 24938 | |
first word in this list is the primary @var{option}, any others are
|
| 24939 | |
assumed to be short-hand aliases. The variable associated with it
|
| 24940 | |
is @code{at_arg_@var{option}}, with any dashes in @var{option} replaced
|
| 24941 | |
with underscores.
|
| 24942 | |
|
| 24943 | |
If the user passes @option{--@var{option}} to the @command{testsuite},
|
| 24944 | |
the variable will be set to @samp{:}. If the user does not pass the
|
| 24945 | |
option, or passes @option{--no-@var{option}}, then the variable will be
|
| 24946 | |
set to @samp{false}.
|
| 24947 | |
|
| 24948 | |
@vrindex at_optarg
|
| 24949 | |
@vrindex at_optarg_@var{option}
|
| 24950 | |
@var{action-if-given} is run each time the option is encountered; here,
|
| 24951 | |
the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as
|
| 24952 | |
appropriate. @code{at_optarg} is actually just a copy of
|
| 24953 | |
@code{at_arg_@var{option}}.
|
| 24954 | |
|
| 24955 | |
@var{action-if-not-given} will be run once after option parsing is
|
| 24956 | |
complete and if no option from @var{options} was used.
|
| 24957 | |
|
| 24958 | |
@var{help-text} is added to the end of the list of options shown in
|
| 24959 | |
@command{testsuite --help} (@pxref{AS_HELP_STRING}).
|
| 24960 | |
|
| 24961 | |
It is recommended that you use a package-specific prefix to @var{options}
|
| 24962 | |
names in order to avoid clashes with future Autotest built-in options.
|
| 24963 | |
@end defmac
|
| 24964 | |
|
| 24965 | |
@defmac AT_ARG_OPTION_ARG (@var{options}, @var{help-text}, @
|
| 24966 | |
@ovar{action-if-given}, @ovar{action-if-not-given})
|
| 24967 | |
@atindex{ARG_OPTION_ARG}
|
| 24968 | |
@vrindex at_arg_@var{option}
|
| 24969 | |
Accept options with arguments from the space-separated list
|
| 24970 | |
@var{options}, a list that has leading dashes removed from the options.
|
| 24971 | |
Long options will be prefixed with @samp{--}, single-character options
|
| 24972 | |
with @samp{-}. The first word in this list is the primary @var{option},
|
| 24973 | |
any others are assumed to be short-hand aliases. The variable associated
|
| 24974 | |
with it is @code{at_arg_@var{option}}, with any dashes in @var{option}
|
| 24975 | |
replaced with underscores.
|
| 24976 | |
|
| 24977 | |
If the user passes @option{--@var{option}=@var{arg}} or
|
| 24978 | |
@option{--@var{option} @var{arg}} to the @command{testsuite}, the
|
| 24979 | |
variable will be set to @samp{@var{arg}}.
|
| 24980 | |
|
| 24981 | |
@vrindex at_optarg
|
| 24982 | |
@var{action-if-given} is run each time the option is encountered; here,
|
| 24983 | |
the variable @code{at_optarg} will be set to @samp{@var{arg}}.
|
| 24984 | |
@code{at_optarg} is actually just a copy of @code{at_arg_@var{option}}.
|
| 24985 | |
|
| 24986 | |
@var{action-if-not-given} will be run once after option parsing is
|
| 24987 | |
complete and if no option from @var{options} was used.
|
| 24988 | |
|
| 24989 | |
@var{help-text} is added to the end of the list of options shown in
|
| 24990 | |
@command{testsuite --help} (@pxref{AS_HELP_STRING}).
|
| 24991 | |
|
| 24992 | |
It is recommended that you use a package-specific prefix to @var{options}
|
| 24993 | |
names in order to avoid clashes with future Autotest built-in options.
|
| 24994 | |
@end defmac
|
| 24995 | |
|
| 24996 | |
@defmac AT_COLOR_TESTS
|
| 24997 | |
@atindex{COLOR_TESTS}
|
| 24998 | |
Enable colored test results by default when the output is connected to
|
| 24999 | |
a terminal.
|
| 25000 | |
@end defmac
|
| 25001 | |
|
| 25002 | |
@defmac AT_TESTED (@var{executables})
|
| 25003 | |
@atindex{TESTED}
|
| 25004 | |
Log the file name and answer to @option{--version} of each program in
|
| 25005 | |
space-separated list @var{executables}. Several invocations register
|
| 25006 | |
new executables, in other words, don't fear registering one program
|
| 25007 | |
several times.
|
| 25008 | |
|
| 25009 | |
Autotest test suites rely on @env{PATH} to find the tested program.
|
| 25010 | |
This avoids the need to generate absolute names of the various tools, and
|
| 25011 | |
makes it possible to test installed programs. Therefore, knowing which
|
| 25012 | |
programs are being exercised is crucial to understanding problems in
|
| 25013 | |
the test suite itself, or its occasional misuses. It is a good idea to
|
| 25014 | |
also subscribe foreign programs you depend upon, to avoid incompatible
|
| 25015 | |
diagnostics.
|
| 25016 | |
@end defmac
|
| 25017 | |
|
| 25018 | |
@sp 1
|
| 25019 | |
|
| 25020 | |
@defmac AT_BANNER (@var{test-category-name})
|
| 25021 | |
@atindex{BANNER}
|
| 25022 | |
This macro identifies the start of a category of related test groups.
|
| 25023 | |
When the resulting @file{testsuite} is invoked with more than one test
|
| 25024 | |
group to run, its output will include a banner containing
|
| 25025 | |
@var{test-category-name} prior to any tests run from that category. The
|
| 25026 | |
banner should be no more than about 40 or 50 characters. A blank banner
|
| 25027 | |
indicates uncategorized tests; an empty line will be inserted after
|
| 25028 | |
tests from an earlier category, effectively ending that category.
|
| 25029 | |
@end defmac
|
| 25030 | |
|
| 25031 | |
@defmac AT_SETUP (@var{test-group-name})
|
| 25032 | |
@atindex{SETUP}
|
| 25033 | |
This macro starts a group of related tests, all to be executed in the
|
| 25034 | |
same subshell. It accepts a single argument, which holds a few words
|
| 25035 | |
(no more than about 30 or 40 characters) quickly describing the purpose
|
| 25036 | |
of the test group being started. @var{test-group-name} must not expand
|
| 25037 | |
to unbalanced quotes, although quadrigraphs can be used.
|
| 25038 | |
@end defmac
|
| 25039 | |
|
| 25040 | |
@defmac AT_KEYWORDS (@var{keywords})
|
| 25041 | |
@atindex{KEYWORDS}
|
| 25042 | |
Associate the space-separated list of @var{keywords} to the enclosing
|
| 25043 | |
test group. This makes it possible to run ``slices'' of the test suite.
|
| 25044 | |
For instance, if some of your test groups exercise some @samp{foo}
|
| 25045 | |
feature, then using @samp{AT_KEYWORDS(foo)} lets you run
|
| 25046 | |
@samp{./testsuite -k foo} to run exclusively these test groups. The
|
| 25047 | |
@var{test-group-name} of the test group is automatically recorded to
|
| 25048 | |
@code{AT_KEYWORDS}.
|
| 25049 | |
|
| 25050 | |
Several invocations within a test group accumulate new keywords. In
|
| 25051 | |
other words, don't fear registering the same keyword several times in a
|
| 25052 | |
test group.
|
| 25053 | |
@end defmac
|
| 25054 | |
|
| 25055 | |
@defmac AT_CAPTURE_FILE (@var{file})
|
| 25056 | |
@atindex{CAPTURE_FILE}
|
| 25057 | |
If the current test group fails, log the contents of @var{file}.
|
| 25058 | |
Several identical calls within one test group have no additional effect.
|
| 25059 | |
@end defmac
|
| 25060 | |
|
| 25061 | |
@defmac AT_FAIL_IF (@var{shell-condition})
|
| 25062 | |
@atindex{FAIL_IF}
|
| 25063 | |
Make the test group fail and skip the rest of its execution, if
|
| 25064 | |
@var{shell-condition} is true. @var{shell-condition} is a shell expression
|
| 25065 | |
such as a @code{test} command. Tests before @command{AT_FAIL_IF}
|
| 25066 | |
will be executed and may still cause the test group to be skipped.
|
| 25067 | |
You can instantiate this macro many times from within the same test group.
|
| 25068 | |
|
| 25069 | |
You should use this macro only for very simple failure conditions. If the
|
| 25070 | |
@var{shell-condition} could emit any kind of output you should instead
|
| 25071 | |
use @command{AT_CHECK} like
|
| 25072 | |
@example
|
| 25073 | |
AT_CHECK([if @var{shell-condition}; then exit 99; fi])
|
| 25074 | |
@end example
|
| 25075 | |
@noindent
|
| 25076 | |
so that such output is properly recorded in the @file{testsuite.log}
|
| 25077 | |
file.
|
| 25078 | |
@end defmac
|
| 25079 | |
|
| 25080 | |
@defmac AT_SKIP_IF (@var{shell-condition})
|
| 25081 | |
@atindex{SKIP_IF}
|
| 25082 | |
Determine whether the test should be skipped because it requires
|
| 25083 | |
features that are unsupported on the machine under test.
|
| 25084 | |
@var{shell-condition} is a shell expression such as a @code{test}
|
| 25085 | |
command. Tests before @command{AT_SKIP_IF} will be executed
|
| 25086 | |
and may still cause the test group to fail. You can instantiate this
|
| 25087 | |
macro many times from within the same test group.
|
| 25088 | |
|
| 25089 | |
You should use this macro only for very simple skip conditions. If the
|
| 25090 | |
@var{shell-condition} could emit any kind of output you should instead
|
| 25091 | |
use @command{AT_CHECK} like
|
| 25092 | |
@example
|
| 25093 | |
AT_CHECK([if @var{shell-condition}; then exit 77; fi])
|
| 25094 | |
@end example
|
| 25095 | |
@noindent
|
| 25096 | |
so that such output is properly recorded in the @file{testsuite.log}
|
| 25097 | |
file.
|
| 25098 | |
@end defmac
|
| 25099 | |
|
| 25100 | |
@defmac AT_XFAIL_IF (@var{shell-condition})
|
| 25101 | |
@atindex{XFAIL_IF}
|
| 25102 | |
Determine whether the test is expected to fail because it is a known
|
| 25103 | |
bug (for unsupported features, you should skip the test).
|
| 25104 | |
@var{shell-condition} is a shell expression such as a @code{test}
|
| 25105 | |
command; you can instantiate this macro many times from within the
|
| 25106 | |
same test group, and one of the conditions is enough to turn
|
| 25107 | |
the test into an expected failure.
|
| 25108 | |
@end defmac
|
| 25109 | |
|
| 25110 | |
@defmac AT_CLEANUP
|
| 25111 | |
@atindex{CLEANUP}
|
| 25112 | |
End the current test group.
|
| 25113 | |
@end defmac
|
| 25114 | |
|
| 25115 | |
@sp 1
|
| 25116 | |
|
| 25117 | |
@defmac AT_DATA (@var{file}, @var{contents})
|
| 25118 | |
@atindex{DATA}
|
| 25119 | |
Initialize an input data @var{file} with given @var{contents}. Of
|
| 25120 | |
course, the @var{contents} have to be properly quoted between square
|
| 25121 | |
brackets to protect against included commas or spurious M4
|
| 25122 | |
expansion. @var{contents} must be empty or end with a newline.
|
| 25123 | |
@var{file} must
|
| 25124 | |
be a single shell word that expands into a single file name.
|
| 25125 | |
@end defmac
|
| 25126 | |
|
| 25127 | |
@defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @
|
| 25128 | |
@ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass})
|
| 25129 | |
@defmacx AT_CHECK_UNQUOTED (@var{commands}, @dvar{status, 0}, @ovar{stdout}, @
|
| 25130 | |
@ovar{stderr}, @ovar{run-if-fail}, @ovar{run-if-pass})
|
| 25131 | |
@atindex{CHECK}
|
| 25132 | |
@atindex{CHECK_UNQUOTED}
|
| 25133 | |
@vrindex at_status
|
| 25134 | |
Execute a test by performing given shell @var{commands} in a subshell.
|
| 25135 | |
@var{commands} is output as-is, so shell expansions are honored. These
|
| 25136 | |
commands should normally exit with @var{status}, while producing expected
|
| 25137 | |
@var{stdout} and @var{stderr} contents. If @var{commands} exit with
|
| 25138 | |
unexpected status 77, then the rest of the test group is skipped. If
|
| 25139 | |
@var{commands} exit with unexpected status 99, then the test group is
|
| 25140 | |
immediately failed. Otherwise, if this test fails, run shell commands
|
| 25141 | |
@var{run-if-fail} or, if this test passes, run shell commands
|
| 25142 | |
@var{run-if-pass}, both inside the current shell execution environment.
|
| 25143 | |
At the beginning of @var{run-if-fail} and @var{run-if-pass}, the status of
|
| 25144 | |
@var{commands} is available in the @code{at_status} shell variable.
|
| 25145 | |
|
| 25146 | |
This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}.
|
| 25147 | |
|
| 25148 | |
If @var{status} is the literal @samp{ignore}, then the corresponding
|
| 25149 | |
exit status is not checked, except for the special cases of 77 (skip)
|
| 25150 | |
and 99 (hard failure). The existence of hard failures allows one to
|
| 25151 | |
mark a test as an expected failure with @code{AT_XFAIL_IF} because a
|
| 25152 | |
feature has not yet been implemented, but to still distinguish between
|
| 25153 | |
gracefully handling the missing feature and dumping core. A hard
|
| 25154 | |
failure also inhibits post-test actions in @var{run-if-fail}.
|
| 25155 | |
|
| 25156 | |
If the value of the @var{stdout} or @var{stderr} parameter is one of the
|
| 25157 | |
literals in the following table, then the test treats the output
|
| 25158 | |
according to the rules of that literal. Otherwise, the value of the
|
| 25159 | |
parameter is treated as text that must exactly match the output given by
|
| 25160 | |
@var{commands} on standard output and standard error (including an empty
|
| 25161 | |
parameter for no output); any differences are captured in the testsuite
|
| 25162 | |
log and the test is failed (unless an unexpected exit status of 77
|
| 25163 | |
skipped the test instead). The difference between @code{AT_CHECK} and
|
| 25164 | |
@code{AT_CHECK_UNQUOTED} is that only the latter performs shell variable
|
| 25165 | |
expansion (@samp{$}), command substitution (@samp{`}), and backslash
|
| 25166 | |
escaping (@samp{\}) on comparison text given in the @var{stdout} and
|
| 25167 | |
@var{stderr} arguments; if the text includes a trailing newline, this
|
| 25168 | |
would be the same as if it were specified via an unquoted
|
| 25169 | |
here-document. (However, there is no difference in the interpretation
|
| 25170 | |
of @var{commands}).
|
| 25171 | |
|
| 25172 | |
@table @samp
|
| 25173 | |
@item ignore
|
| 25174 | |
The content of the output is ignored, but still captured in the test
|
| 25175 | |
group log (if the testsuite is run with option @option{-v}, the test
|
| 25176 | |
group log is displayed as the test is run; if the test group later
|
| 25177 | |
fails, the test group log is also copied into the overall testsuite
|
| 25178 | |
log). This action is valid for both @var{stdout} and @var{stderr}.
|
| 25179 | |
|
| 25180 | |
@item ignore-nolog
|
| 25181 | |
The content of the output is ignored, and nothing is captured in the log
|
| 25182 | |
files. If @var{commands} are likely to produce binary output (including
|
| 25183 | |
long lines) or large amounts of output, then logging the output can make
|
| 25184 | |
it harder to locate details related to subsequent tests within the
|
| 25185 | |
group, and could potentially corrupt terminal display of a user running
|
| 25186 | |
@command{testsuite -v}.
|
| 25187 | |
|
| 25188 | |
@item stdout
|
| 25189 | |
For the @var{stdout} parameter, capture the content of standard output
|
| 25190 | |
to both the file @file{stdout} and the test group log. Subsequent
|
| 25191 | |
commands in the test group can then post-process the file. This action
|
| 25192 | |
is often used when it is desired to use @command{grep} to look for a
|
| 25193 | |
substring in the output, or when the output must be post-processed to
|
| 25194 | |
normalize error messages into a common form.
|
| 25195 | |
|
| 25196 | |
@item stderr
|
| 25197 | |
Like @samp{stdout}, except that it only works for the @var{stderr}
|
| 25198 | |
parameter, and the standard error capture file will be named
|
| 25199 | |
@file{stderr}.
|
| 25200 | |
|
| 25201 | |
@item stdout-nolog
|
| 25202 | |
@itemx stderr-nolog
|
| 25203 | |
Like @samp{stdout} or @samp{stderr}, except that the captured output is
|
| 25204 | |
not duplicated into the test group log. This action is particularly
|
| 25205 | |
useful for an intermediate check that produces large amounts of data,
|
| 25206 | |
which will be followed by another check that filters down to the
|
| 25207 | |
relevant data, as it makes it easier to locate details in the log.
|
| 25208 | |
|
| 25209 | |
@item expout
|
| 25210 | |
For the @var{stdout} parameter, compare standard output contents with
|
| 25211 | |
the previously created file @file{expout}, and list any differences in
|
| 25212 | |
the testsuite log.
|
| 25213 | |
|
| 25214 | |
@item experr
|
| 25215 | |
Like @samp{expout}, except that it only works for the @var{stderr}
|
| 25216 | |
parameter, and the standard error contents are compared with
|
| 25217 | |
@file{experr}.
|
| 25218 | |
@end table
|
| 25219 | |
@end defmac
|
| 25220 | |
|
| 25221 | |
@defmac AT_CHECK_EUNIT (@var{module}, @var{test-spec}, @ovar{erlflags}, @
|
| 25222 | |
@ovar{run-if-fail}, @ovar{run-if-pass})
|
| 25223 | |
@atindex{CHECK_EUNIT}
|
| 25224 | |
Initialize and execute an Erlang module named @var{module} that performs
|
| 25225 | |
tests following the @var{test-spec} EUnit test specification.
|
| 25226 | |
@var{test-spec} must be a valid EUnit test specification, as defined in
|
| 25227 | |
the @uref{http://@/erlang.org/@/doc/@/apps/@/eunit/@/index.html, EUnit
|
| 25228 | |
Reference Manual}. @var{erlflags} are optional command-line options
|
| 25229 | |
passed to the Erlang interpreter to execute the test Erlang module.
|
| 25230 | |
Typically, @var{erlflags} defines at least the paths to directories
|
| 25231 | |
containing the compiled Erlang modules under test, as @samp{-pa path1
|
| 25232 | |
path2 ...}.
|
| 25233 | |
|
| 25234 | |
For example, the unit tests associated with Erlang module @samp{testme},
|
| 25235 | |
which compiled code is in subdirectory @file{src}, can be performed
|
| 25236 | |
with:
|
| 25237 | |
|
| 25238 | |
@example
|
| 25239 | |
AT_CHECK_EUNIT([testme_testsuite], [@{module, testme@}],
|
| 25240 | |
[-pa "$@{abs_top_builddir@}/src"])
|
| 25241 | |
@end example
|
| 25242 | |
|
| 25243 | |
This macro must be invoked in between @code{AT_SETUP} and @code{AT_CLEANUP}.
|
| 25244 | |
|
| 25245 | |
Variables @code{ERL}, @code{ERLC}, and (optionally) @code{ERLCFLAGS}
|
| 25246 | |
must be defined as the path of the Erlang interpreter, the path of the
|
| 25247 | |
Erlang compiler, and the command-line flags to pass to the compiler,
|
| 25248 | |
respectively. Those variables should be configured in
|
| 25249 | |
@file{configure.ac} using the @command{AC_ERLANG_PATH_ERL} and
|
| 25250 | |
@command{AC_ERLANG_PATH_ERLC} macros, and the configured values of those
|
| 25251 | |
variables are automatically defined in the testsuite. If @code{ERL} or
|
| 25252 | |
@code{ERLC} is not defined, the test group is skipped.
|
| 25253 | |
|
| 25254 | |
If the EUnit library cannot be found, i.e. if module @code{eunit} cannot
|
| 25255 | |
be loaded, the test group is skipped. Otherwise, if @var{test-spec} is
|
| 25256 | |
an invalid EUnit test specification, the test group fails. Otherwise,
|
| 25257 | |
if the EUnit test passes, shell commands @var{run-if-pass} are executed
|
| 25258 | |
or, if the EUnit test fails, shell commands @var{run-if-fail} are
|
| 25259 | |
executed and the test group fails.
|
| 25260 | |
|
| 25261 | |
Only the generated test Erlang module is automatically compiled and
|
| 25262 | |
executed. If @var{test-spec} involves testing other Erlang modules,
|
| 25263 | |
e.g. module @samp{testme} in the example above, those modules must be
|
| 25264 | |
already compiled.
|
| 25265 | |
|
| 25266 | |
If the testsuite is run in verbose mode, with option @option{--verbose},
|
| 25267 | |
EUnit is also run in verbose mode to output more details about
|
| 25268 | |
individual unit tests.
|
| 25269 | |
@end defmac
|
| 25270 | |
|
| 25271 | |
|
| 25272 | |
@node testsuite Invocation
|
| 25273 | |
@section Running @command{testsuite} Scripts
|
| 25274 | |
@cindex @command{testsuite}
|
| 25275 | |
|
| 25276 | |
Autotest test suites support the following options:
|
| 25277 | |
|
| 25278 | |
@table @option
|
| 25279 | |
@item --help
|
| 25280 | |
@itemx -h
|
| 25281 | |
Display the list of options and exit successfully.
|
| 25282 | |
|
| 25283 | |
@item --version
|
| 25284 | |
@itemx -V
|
| 25285 | |
Display the version of the test suite and exit successfully.
|
| 25286 | |
|
| 25287 | |
@item --directory=@var{dir}
|
| 25288 | |
@itemx -C @var{dir}
|
| 25289 | |
Change the current directory to @var{dir} before creating any files.
|
| 25290 | |
Useful for running the testsuite in a subdirectory from a top-level
|
| 25291 | |
Makefile.
|
| 25292 | |
|
| 25293 | |
@item --jobs@r{[}=@var{n}@r{]}
|
| 25294 | |
@itemx -j@ovar{n}
|
| 25295 | |
Run @var{n} tests in parallel, if possible. If @var{n} is not given,
|
| 25296 | |
run all given tests in parallel. Note that there should be no space
|
| 25297 | |
before the argument to @option{-j}, as @option{-j @var{number}} denotes
|
| 25298 | |
the separate arguments @option{-j} and @option{@var{number}}, see below.
|
| 25299 | |
|
| 25300 | |
In parallel mode, the standard input device of the testsuite script is
|
| 25301 | |
not available to commands inside a test group. Furthermore, banner
|
| 25302 | |
lines are not printed, and the summary line for each test group is
|
| 25303 | |
output after the test group completes. Summary lines may appear
|
| 25304 | |
unordered. If verbose and trace output are enabled (see below), they
|
| 25305 | |
may appear intermixed from concurrently running tests.
|
| 25306 | |
|
| 25307 | |
Parallel mode requires the @command{mkfifo} command to work, and will be
|
| 25308 | |
silently disabled otherwise.
|
| 25309 | |
|
| 25310 | |
@item --clean
|
| 25311 | |
@itemx -c
|
| 25312 | |
Remove all the files the test suite might have created and exit. Meant
|
| 25313 | |
for @code{clean} Make targets.
|
| 25314 | |
|
| 25315 | |
@item --list
|
| 25316 | |
@itemx -l
|
| 25317 | |
List all the tests (or only the selection), including their possible
|
| 25318 | |
keywords.
|
| 25319 | |
@end table
|
| 25320 | |
|
| 25321 | |
@sp 1
|
| 25322 | |
|
| 25323 | |
By default all tests are performed (or described with @option{--list})
|
| 25324 | |
silently in the default environment, but the environment, set of tests,
|
| 25325 | |
and verbosity level can be tuned:
|
| 25326 | |
|
| 25327 | |
@table @samp
|
| 25328 | |
@item @var{variable}=@var{value}
|
| 25329 | |
Set the environment @var{variable} to @var{value}. Use this rather
|
| 25330 | |
than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
|
| 25331 | |
different environment.
|
| 25332 | |
|
| 25333 | |
@cindex @code{AUTOTEST_PATH}
|
| 25334 | |
The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
|
| 25335 | |
to @env{PATH}. Relative directory names (not starting with
|
| 25336 | |
@samp{/}) are considered to be relative to the top level of the
|
| 25337 | |
package being built. All directories are made absolute, first
|
| 25338 | |
starting from the top level @emph{build} tree, then from the
|
| 25339 | |
@emph{source} tree. For instance @samp{./testsuite
|
| 25340 | |
AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
|
| 25341 | |
in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
|
| 25342 | |
then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
|
| 25343 | |
@env{PATH}.
|
| 25344 | |
|
| 25345 | |
@item @var{number}
|
| 25346 | |
@itemx @var{number}-@var{number}
|
| 25347 | |
@itemx @var{number}-
|
| 25348 | |
@itemx -@var{number}
|
| 25349 | |
Add the corresponding test groups, with obvious semantics, to the
|
| 25350 | |
selection.
|
| 25351 | |
|
| 25352 | |
@item --keywords=@var{keywords}
|
| 25353 | |
@itemx -k @var{keywords}
|
| 25354 | |
Add to the selection the test groups with title or keywords (arguments
|
| 25355 | |
to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
|
| 25356 | |
of the comma separated list @var{keywords}, case-insensitively. Use
|
| 25357 | |
@samp{!} immediately before the keyword to invert the selection for this
|
| 25358 | |
keyword. By default, the keywords match whole words; enclose them in
|
| 25359 | |
@samp{.*} to also match parts of words.
|
| 25360 | |
|
| 25361 | |
For example, running
|
| 25362 | |
|
| 25363 | |
@example
|
| 25364 | |
@kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
|
| 25365 | |
@end example
|
| 25366 | |
|
| 25367 | |
@noindent
|
| 25368 | |
selects all tests tagged @samp{autoupdate} @emph{and} with tags
|
| 25369 | |
containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
|
| 25370 | |
etc.), while
|
| 25371 | |
|
| 25372 | |
@example
|
| 25373 | |
@kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
|
| 25374 | |
@end example
|
| 25375 | |
|
| 25376 | |
@noindent
|
| 25377 | |
selects all tests not tagged @samp{autoupdate} @emph{or} with tags
|
| 25378 | |
containing @samp{FUNC}.
|
| 25379 | |
|
| 25380 | |
@item --errexit
|
| 25381 | |
@itemx -e
|
| 25382 | |
If any test fails, immediately abort testing. This implies
|
| 25383 | |
@option{--debug}: post test group clean up, and top-level logging
|
| 25384 | |
are inhibited. This option is meant for the full test
|
| 25385 | |
suite, it is not really useful for generated debugging scripts.
|
| 25386 | |
If the testsuite is run in parallel mode using @option{--jobs},
|
| 25387 | |
then concurrently running tests will finish before exiting.
|
| 25388 | |
|
| 25389 | |
@item --verbose
|
| 25390 | |
@itemx -v
|
| 25391 | |
Force more verbosity in the detailed output of what is being done. This
|
| 25392 | |
is the default for debugging scripts.
|
| 25393 | |
|
| 25394 | |
@item --color
|
| 25395 | |
@itemx --color@r{[}=never@r{|}auto@r{|}always@r{]}
|
| 25396 | |
Enable colored test results. Without an argument, or with @samp{always},
|
| 25397 | |
test results will be colored. With @samp{never}, color mode is turned
|
| 25398 | |
off. Otherwise, if either the macro @code{AT_COLOR_TESTS} is used by
|
| 25399 | |
the testsuite author, or the argument @samp{auto} is given, then test
|
| 25400 | |
results are colored if standard output is connected to a terminal.
|
| 25401 | |
|
| 25402 | |
@item --debug
|
| 25403 | |
@itemx -d
|
| 25404 | |
Do not remove the files after a test group was performed---but they are
|
| 25405 | |
still removed @emph{before}, therefore using this option is sane when
|
| 25406 | |
running several test groups. Create debugging scripts. Do not
|
| 25407 | |
overwrite the top-level
|
| 25408 | |
log (in order to preserve a supposedly existing full log file). This is
|
| 25409 | |
the default for debugging scripts, but it can also be useful to debug
|
| 25410 | |
the testsuite itself.
|
| 25411 | |
|
| 25412 | |
@item --recheck
|
| 25413 | |
Add to the selection all test groups that failed or passed unexpectedly
|
| 25414 | |
during the last non-debugging test run.
|
| 25415 | |
|
| 25416 | |
@item --trace
|
| 25417 | |
@itemx -x
|
| 25418 | |
Trigger shell tracing of the test groups.
|
| 25419 | |
@end table
|
| 25420 | |
|
| 25421 | |
Besides these options accepted by every Autotest testsuite, the
|
| 25422 | |
testsuite author might have added package-specific options
|
| 25423 | |
via the @code{AT_ARG_OPTION} and @code{AT_ARG_OPTION_ARG} macros
|
| 25424 | |
(@pxref{Writing Testsuites}); refer to @command{testsuite --help} and
|
| 25425 | |
the package documentation for details.
|
| 25426 | |
|
| 25427 | |
|
| 25428 | |
@node Making testsuite Scripts
|
| 25429 | |
@section Making @command{testsuite} Scripts
|
| 25430 | |
|
| 25431 | |
For putting Autotest into movement, you need some configuration and
|
| 25432 | |
makefile machinery. We recommend, at least if your package uses deep or
|
| 25433 | |
shallow hierarchies, that you use @file{tests/} as the name of the
|
| 25434 | |
directory holding all your tests and their makefile. Here is a
|
| 25435 | |
check list of things to do.
|
| 25436 | |
|
| 25437 | |
@itemize @minus
|
| 25438 | |
|
| 25439 | |
@item
|
| 25440 | |
@cindex @file{package.m4}
|
| 25441 | |
@atindex{PACKAGE_STRING}
|
| 25442 | |
@atindex{PACKAGE_BUGREPORT}
|
| 25443 | |
@atindex{PACKAGE_NAME}
|
| 25444 | |
@atindex{PACKAGE_TARNAME}
|
| 25445 | |
@atindex{PACKAGE_VERSION}
|
| 25446 | |
@atindex{PACKAGE_URL}
|
| 25447 | |
Make sure to create the file @file{package.m4}, which defines the
|
| 25448 | |
identity of the package. It must define @code{AT_PACKAGE_STRING}, the
|
| 25449 | |
full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
|
| 25450 | |
address to which bug reports should be sent. For sake of completeness,
|
| 25451 | |
we suggest that you also define @code{AT_PACKAGE_NAME},
|
| 25452 | |
@code{AT_PACKAGE_TARNAME}, @code{AT_PACKAGE_VERSION}, and
|
| 25453 | |
@code{AT_PACKAGE_URL}.
|
| 25454 | |
@xref{Initializing configure}, for a description of these variables.
|
| 25455 | |
Be sure to distribute @file{package.m4} and to put it into the source
|
| 25456 | |
hierarchy: the test suite ought to be shipped! See below for an example
|
| 25457 | |
@file{Makefile} excerpt.
|
| 25458 | |
|
| 25459 | |
@item
|
| 25460 | |
Invoke @code{AC_CONFIG_TESTDIR}.
|
| 25461 | |
|
| 25462 | |
@defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
|
| 25463 | |
@acindex{CONFIG_TESTDIR}
|
| 25464 | |
An Autotest test suite is to be configured in @var{directory}. This
|
| 25465 | |
macro causes @file{@var{directory}/atconfig} to be created by
|
| 25466 | |
@command{config.status} and sets the default @code{AUTOTEST_PATH} to
|
| 25467 | |
@var{test-path} (@pxref{testsuite Invocation}).
|
| 25468 | |
@end defmac
|
| 25469 | |
|
| 25470 | |
@item
|
| 25471 | |
Still within @file{configure.ac}, as appropriate, ensure that some
|
| 25472 | |
@code{AC_CONFIG_FILES} command includes substitution for
|
| 25473 | |
@file{tests/atlocal}.
|
| 25474 | |
|
| 25475 | |
@item
|
| 25476 | |
The appropriate @file{Makefile} should be modified so the validation in
|
| 25477 | |
your package is triggered by @samp{make check}. An example is provided
|
| 25478 | |
below.
|
| 25479 | |
@end itemize
|
| 25480 | |
|
| 25481 | |
With Automake, here is a minimal example for inclusion in
|
| 25482 | |
@file{tests/Makefile.am}, in order to link @samp{make check} with a
|
| 25483 | |
validation suite.
|
| 25484 | |
|
| 25485 | |
@example
|
| 25486 | |
# The `:;' works around a Bash 3.2 bug when the output is not writable.
|
| 25487 | |
$(srcdir)/package.m4: $(top_srcdir)/configure.ac
|
| 25488 | |
:;@{ \
|
| 25489 | |
echo '# Signature of the current package.' && \
|
| 25490 | |
echo 'm4_define([AT_PACKAGE_NAME],' && \
|
| 25491 | |
echo ' [$(PACKAGE_NAME)])' && \
|
| 25492 | |
echo 'm4_define([AT_PACKAGE_TARNAME],' && \
|
| 25493 | |
echo ' [$(PACKAGE_TARNAME)])' && \
|
| 25494 | |
echo 'm4_define([AT_PACKAGE_VERSION],' && \
|
| 25495 | |
echo ' [$(PACKAGE_VERSION)])' && \
|
| 25496 | |
echo 'm4_define([AT_PACKAGE_STRING],' && \
|
| 25497 | |
echo ' [$(PACKAGE_STRING)])' && \
|
| 25498 | |
echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \
|
| 25499 | |
echo ' [$(PACKAGE_BUGREPORT)])'; \
|
| 25500 | |
echo 'm4_define([AT_PACKAGE_URL],' && \
|
| 25501 | |
echo ' [$(PACKAGE_URL)])'; \
|
| 25502 | |
@} >'$(srcdir)/package.m4'
|
| 25503 | |
|
| 25504 | |
EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in
|
| 25505 | |
TESTSUITE = $(srcdir)/testsuite
|
| 25506 | |
|
| 25507 | |
check-local: atconfig atlocal $(TESTSUITE)
|
| 25508 | |
$(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
|
| 25509 | |
|
| 25510 | |
installcheck-local: atconfig atlocal $(TESTSUITE)
|
| 25511 | |
$(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
|
| 25512 | |
$(TESTSUITEFLAGS)
|
| 25513 | |
|
| 25514 | |
clean-local:
|
| 25515 | |
test ! -f '$(TESTSUITE)' || \
|
| 25516 | |
$(SHELL) '$(TESTSUITE)' --clean
|
| 25517 | |
|
| 25518 | |
AUTOM4TE = $(SHELL) $(srcdir)/build-aux/missing --run autom4te
|
| 25519 | |
AUTOTEST = $(AUTOM4TE) --language=autotest
|
| 25520 | |
$(TESTSUITE): $(srcdir)/testsuite.at $(srcdir)/package.m4
|
| 25521 | |
$(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
|
| 25522 | |
mv $@@.tmp $@@
|
| 25523 | |
@end example
|
| 25524 | |
|
| 25525 | |
Note that the built testsuite is distributed; this is necessary because
|
| 25526 | |
users might not have Autoconf installed, and thus would not be able to
|
| 25527 | |
rebuild it. Likewise, the use of @file{missing} provides the user with
|
| 25528 | |
a nicer error message if they modify a source file to the testsuite, and
|
| 25529 | |
accidentally trigger the rebuild rules.
|
| 25530 | |
|
| 25531 | |
You might want to list explicitly the dependencies, i.e., the list of
|
| 25532 | |
the files @file{testsuite.at} includes.
|
| 25533 | |
|
| 25534 | |
If you don't use Automake, you should include the above example in
|
| 25535 | |
@file{tests/@/Makefile.in}, along with additional lines inspired from
|
| 25536 | |
the following:
|
| 25537 | |
|
| 25538 | |
@example
|
| 25539 | |
subdir = tests
|
| 25540 | |
PACKAGE_NAME = @@PACKAGE_NAME@@
|
| 25541 | |
PACKAGE_TARNAME = @@PACKAGE_TARNAME@@
|
| 25542 | |
PACKAGE_VERSION = @@PACKAGE_VERSION@@
|
| 25543 | |
PACKAGE_STRING = @@PACKAGE_STRING@@
|
| 25544 | |
PACKAGE_BUGREPORT = @@PACKAGE_BUGREPORT@@
|
| 25545 | |
PACKAGE_URL = @@PACKAGE_URL@@
|
| 25546 | |
|
| 25547 | |
atconfig: $(top_builddir)/config.status
|
| 25548 | |
cd $(top_builddir) && \
|
| 25549 | |
$(SHELL) ./config.status $(subdir)/$@@
|
| 25550 | |
|
| 25551 | |
atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
|
| 25552 | |
cd $(top_builddir) && \
|
| 25553 | |
$(SHELL) ./config.status $(subdir)/$@@
|
| 25554 | |
@end example
|
| 25555 | |
|
| 25556 | |
@noindent
|
| 25557 | |
and manage to have @code{$(EXTRA_DIST)} distributed. You will also want
|
| 25558 | |
to distribute the file @file{build-aux/@/missing} from the Automake
|
| 25559 | |
project; a copy of this file resides in the Autoconf source tree.
|
| 25560 | |
|
| 25561 | |
With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
|
| 25562 | |
within your makefile, you can fine-tune test suite execution with this
|
| 25563 | |
variable, for example:
|
| 25564 | |
|
| 25565 | |
@example
|
| 25566 | |
make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
|
| 25567 | |
@end example
|
| 25568 | |
|
| 25569 | |
|
| 25570 | |
|
| 25571 | |
@c =============================== Frequent Autoconf Questions, with answers
|
| 25572 | |
|
| 25573 | |
@node FAQ
|
| 25574 | |
@chapter Frequent Autoconf Questions, with answers
|
| 25575 | |
|
| 25576 | |
Several questions about Autoconf come up occasionally. Here some of them
|
| 25577 | |
are addressed.
|
| 25578 | |
|
| 25579 | |
@menu
|
| 25580 | |
* Distributing:: Distributing @command{configure} scripts
|
| 25581 | |
* Why GNU M4:: Why not use the standard M4?
|
| 25582 | |
* Bootstrapping:: Autoconf and GNU M4 require each other?
|
| 25583 | |
* Why Not Imake:: Why GNU uses @command{configure} instead of Imake
|
| 25584 | |
* Defining Directories:: Passing @code{datadir} to program
|
| 25585 | |
* Autom4te Cache:: What is it? Can I remove it?
|
| 25586 | |
* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
|
| 25587 | |
* Expanded Before Required:: Expanded Before Required
|
| 25588 | |
* Debugging:: Debugging @command{configure} scripts
|
| 25589 | |
@end menu
|
| 25590 | |
|
| 25591 | |
@node Distributing
|
| 25592 | |
@section Distributing @command{configure} Scripts
|
| 25593 | |
@cindex License
|
| 25594 | |
|
| 25595 | |
@display
|
| 25596 | |
What are the restrictions on distributing @command{configure}
|
| 25597 | |
scripts that Autoconf generates? How does that affect my
|
| 25598 | |
programs that use them?
|
| 25599 | |
@end display
|
| 25600 | |
|
| 25601 | |
There are no restrictions on how the configuration scripts that Autoconf
|
| 25602 | |
produces may be distributed or used. In Autoconf version 1, they were
|
| 25603 | |
covered by the GNU General Public License. We still encourage
|
| 25604 | |
software authors to distribute their work under terms like those of the
|
| 25605 | |
GPL, but doing so is not required to use Autoconf.
|
| 25606 | |
|
| 25607 | |
Of the other files that might be used with @command{configure},
|
| 25608 | |
@file{config.h.in} is under whatever copyright you use for your
|
| 25609 | |
@file{configure.ac}. @file{config.sub} and @file{config.guess} have an
|
| 25610 | |
exception to the GPL when they are used with an Autoconf-generated
|
| 25611 | |
@command{configure} script, which permits you to distribute them under the
|
| 25612 | |
same terms as the rest of your package. @file{install-sh} is from the X
|
| 25613 | |
Consortium and is not copyrighted.
|
| 25614 | |
|
| 25615 | |
@node Why GNU M4
|
| 25616 | |
@section Why Require GNU M4?
|
| 25617 | |
|
| 25618 | |
@display
|
| 25619 | |
Why does Autoconf require GNU M4?
|
| 25620 | |
@end display
|
| 25621 | |
|
| 25622 | |
Many M4 implementations have hard-coded limitations on the size and
|
| 25623 | |
number of macros that Autoconf exceeds. They also lack several
|
| 25624 | |
builtin macros that it would be difficult to get along without in a
|
| 25625 | |
sophisticated application like Autoconf, including:
|
| 25626 | |
|
| 25627 | |
@example
|
| 25628 | |
m4_builtin
|
| 25629 | |
m4_indir
|
| 25630 | |
m4_bpatsubst
|
| 25631 | |
__file__
|
| 25632 | |
__line__
|
| 25633 | |
@end example
|
| 25634 | |
|
| 25635 | |
Autoconf requires version 1.4.6 or later of GNU M4.
|
| 25636 | |
|
| 25637 | |
Since only software maintainers need to use Autoconf, and since GNU
|
| 25638 | |
M4 is simple to configure and install, it seems reasonable to require
|
| 25639 | |
GNU M4 to be installed also. Many maintainers of GNU and
|
| 25640 | |
other free software already have most of the GNU utilities
|
| 25641 | |
installed, since they prefer them.
|
| 25642 | |
|
| 25643 | |
@node Bootstrapping
|
| 25644 | |
@section How Can I Bootstrap?
|
| 25645 | |
@cindex Bootstrap
|
| 25646 | |
|
| 25647 | |
@display
|
| 25648 | |
If Autoconf requires GNU M4 and GNU M4 has an Autoconf
|
| 25649 | |
@command{configure} script, how do I bootstrap? It seems like a chicken
|
| 25650 | |
and egg problem!
|
| 25651 | |
@end display
|
| 25652 | |
|
| 25653 | |
This is a misunderstanding. Although GNU M4 does come with a
|
| 25654 | |
@command{configure} script produced by Autoconf, Autoconf is not required
|
| 25655 | |
in order to run the script and install GNU M4. Autoconf is only
|
| 25656 | |
required if you want to change the M4 @command{configure} script, which few
|
| 25657 | |
people have to do (mainly its maintainer).
|
| 25658 | |
|
| 25659 | |
@node Why Not Imake
|
| 25660 | |
@section Why Not Imake?
|
| 25661 | |
@cindex Imake
|
| 25662 | |
|
| 25663 | |
@display
|
| 25664 | |
Why not use Imake instead of @command{configure} scripts?
|
| 25665 | |
@end display
|
| 25666 | |
|
| 25667 | |
Several people have written addressing this question, so
|
| 25668 | |
adaptations of their explanations are included here.
|
| 25669 | |
|
| 25670 | |
The following answer is based on one written by Richard Pixley:
|
| 25671 | |
|
| 25672 | |
@quotation
|
| 25673 | |
Autoconf generated scripts frequently work on machines that it has
|
| 25674 | |
never been set up to handle before. That is, it does a good job of
|
| 25675 | |
inferring a configuration for a new system. Imake cannot do this.
|
| 25676 | |
|
| 25677 | |
Imake uses a common database of host specific data. For X11, this makes
|
| 25678 | |
sense because the distribution is made as a collection of tools, by one
|
| 25679 | |
central authority who has control over the database.
|
| 25680 | |
|
| 25681 | |
GNU tools are not released this way. Each GNU tool has a
|
| 25682 | |
maintainer; these maintainers are scattered across the world. Using a
|
| 25683 | |
common database would be a maintenance nightmare. Autoconf may appear
|
| 25684 | |
to be this kind of database, but in fact it is not. Instead of listing
|
| 25685 | |
host dependencies, it lists program requirements.
|
| 25686 | |
|
| 25687 | |
If you view the GNU suite as a collection of native tools, then the
|
| 25688 | |
problems are similar. But the GNU development tools can be
|
| 25689 | |
configured as cross tools in almost any host+target permutation. All of
|
| 25690 | |
these configurations can be installed concurrently. They can even be
|
| 25691 | |
configured to share host independent files across hosts. Imake doesn't
|
| 25692 | |
address these issues.
|
| 25693 | |
|
| 25694 | |
Imake templates are a form of standardization. The GNU coding
|
| 25695 | |
standards address the same issues without necessarily imposing the same
|
| 25696 | |
restrictions.
|
| 25697 | |
@end quotation
|
| 25698 | |
|
| 25699 | |
|
| 25700 | |
Here is some further explanation, written by Per Bothner:
|
| 25701 | |
|
| 25702 | |
@quotation
|
| 25703 | |
One of the advantages of Imake is that it is easy to generate large
|
| 25704 | |
makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
|
| 25705 | |
However, @code{cpp} is not programmable: it has limited conditional
|
| 25706 | |
facilities, and no looping. And @code{cpp} cannot inspect its
|
| 25707 | |
environment.
|
| 25708 | |
|
| 25709 | |
All of these problems are solved by using @code{sh} instead of
|
| 25710 | |
@code{cpp}. The shell is fully programmable, has macro substitution,
|
| 25711 | |
can execute (or source) other shell scripts, and can inspect its
|
| 25712 | |
environment.
|
| 25713 | |
@end quotation
|
| 25714 | |
|
| 25715 | |
|
| 25716 | |
Paul Eggert elaborates more:
|
| 25717 | |
|
| 25718 | |
@quotation
|
| 25719 | |
With Autoconf, installers need not assume that Imake itself is already
|
| 25720 | |
installed and working well. This may not seem like much of an advantage
|
| 25721 | |
to people who are accustomed to Imake. But on many hosts Imake is not
|
| 25722 | |
installed or the default installation is not working well, and requiring
|
| 25723 | |
Imake to install a package hinders the acceptance of that package on
|
| 25724 | |
those hosts. For example, the Imake template and configuration files
|
| 25725 | |
might not be installed properly on a host, or the Imake build procedure
|
| 25726 | |
might wrongly assume that all source files are in one big directory
|
| 25727 | |
tree, or the Imake configuration might assume one compiler whereas the
|
| 25728 | |
package or the installer needs to use another, or there might be a
|
| 25729 | |
version mismatch between the Imake expected by the package and the Imake
|
| 25730 | |
supported by the host. These problems are much rarer with Autoconf,
|
| 25731 | |
where each package comes with its own independent configuration
|
| 25732 | |
processor.
|
| 25733 | |
|
| 25734 | |
Also, Imake often suffers from unexpected interactions between
|
| 25735 | |
@command{make} and the installer's C preprocessor. The fundamental problem
|
| 25736 | |
here is that the C preprocessor was designed to preprocess C programs,
|
| 25737 | |
not makefiles. This is much less of a problem with Autoconf,
|
| 25738 | |
which uses the general-purpose preprocessor M4, and where the
|
| 25739 | |
package's author (rather than the installer) does the preprocessing in a
|
| 25740 | |
standard way.
|
| 25741 | |
@end quotation
|
| 25742 | |
|
| 25743 | |
|
| 25744 | |
Finally, Mark Eichin notes:
|
| 25745 | |
|
| 25746 | |
@quotation
|
| 25747 | |
Imake isn't all that extensible, either. In order to add new features to
|
| 25748 | |
Imake, you need to provide your own project template, and duplicate most
|
| 25749 | |
of the features of the existing one. This means that for a sophisticated
|
| 25750 | |
project, using the vendor-provided Imake templates fails to provide any
|
| 25751 | |
leverage---since they don't cover anything that your own project needs
|
| 25752 | |
(unless it is an X11 program).
|
| 25753 | |
|
| 25754 | |
On the other side, though:
|
| 25755 | |
|
| 25756 | |
The one advantage that Imake has over @command{configure}:
|
| 25757 | |
@file{Imakefile} files tend to be much shorter (likewise, less redundant)
|
| 25758 | |
than @file{Makefile.in} files. There is a fix to this, however---at least
|
| 25759 | |
for the Kerberos V5 tree, we've modified things to call in common
|
| 25760 | |
@file{post.in} and @file{pre.in} makefile fragments for the
|
| 25761 | |
entire tree. This means that a lot of common things don't have to be
|
| 25762 | |
duplicated, even though they normally are in @command{configure} setups.
|
| 25763 | |
@end quotation
|
| 25764 | |
|
| 25765 | |
|
| 25766 | |
@node Defining Directories
|
| 25767 | |
@section How Do I @code{#define} Installation Directories?
|
| 25768 | |
|
| 25769 | |
@display
|
| 25770 | |
My program needs library files, installed in @code{datadir} and
|
| 25771 | |
similar. If I use
|
| 25772 | |
|
| 25773 | |
@example
|
| 25774 | |
AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
|
| 25775 | |
[Define to the read-only architecture-independent
|
| 25776 | |
data directory.])
|
| 25777 | |
@end example
|
| 25778 | |
|
| 25779 | |
@noindent
|
| 25780 | |
I get
|
| 25781 | |
|
| 25782 | |
@example
|
| 25783 | |
#define DATADIR "$@{prefix@}/share"
|
| 25784 | |
@end example
|
| 25785 | |
@end display
|
| 25786 | |
|
| 25787 | |
As already explained, this behavior is on purpose, mandated by the
|
| 25788 | |
GNU Coding Standards, see @ref{Installation Directory
|
| 25789 | |
Variables}. There are several means to achieve a similar goal:
|
| 25790 | |
|
| 25791 | |
@itemize @minus
|
| 25792 | |
@item
|
| 25793 | |
Do not use @code{AC_DEFINE} but use your makefile to pass the
|
| 25794 | |
actual value of @code{datadir} via compilation flags.
|
| 25795 | |
@xref{Installation Directory Variables}, for the details.
|
| 25796 | |
|
| 25797 | |
@item
|
| 25798 | |
This solution can be simplified when compiling a program: you may either
|
| 25799 | |
extend the @code{CPPFLAGS}:
|
| 25800 | |
|
| 25801 | |
@example
|
| 25802 | |
CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
|
| 25803 | |
@end example
|
| 25804 | |
|
| 25805 | |
@noindent
|
| 25806 | |
If you are using Automake, you should use @code{AM_CPPFLAGS} instead:
|
| 25807 | |
|
| 25808 | |
@example
|
| 25809 | |
AM_CPPFLAGS = -DDATADIR='"$(datadir)"'
|
| 25810 | |
@end example
|
| 25811 | |
|
| 25812 | |
@noindent
|
| 25813 | |
Alternatively, create a dedicated header file:
|
| 25814 | |
|
| 25815 | |
@example
|
| 25816 | |
DISTCLEANFILES = myprog-paths.h
|
| 25817 | |
myprog-paths.h: Makefile
|
| 25818 | |
echo '#define DATADIR "$(datadir)"' >$@@
|
| 25819 | |
@end example
|
| 25820 | |
|
| 25821 | |
@noindent
|
| 25822 | |
The gnulib module @samp{configmake} provides such a header with all the
|
| 25823 | |
standard directory variables defined, @pxref{configmake,,, gnulib, GNU
|
| 25824 | |
Gnulib}.
|
| 25825 | |
|
| 25826 | |
@item
|
| 25827 | |
Use @code{AC_DEFINE} but have @command{configure} compute the literal
|
| 25828 | |
value of @code{datadir} and others. Many people have wrapped macros to
|
| 25829 | |
automate this task; for an example, see the macro @code{AC_DEFINE_DIR} from
|
| 25830 | |
the @uref{http://@/www.gnu.org/@/software/@/autoconf-archive/, Autoconf Macro
|
| 25831 | |
Archive}.
|
| 25832 | |
|
| 25833 | |
This solution does not conform to the GNU Coding Standards.
|
| 25834 | |
|
| 25835 | |
@item
|
| 25836 | |
Note that all the previous solutions hard wire the absolute name of
|
| 25837 | |
these directories in the executables, which is not a good property. You
|
| 25838 | |
may try to compute the names relative to @code{prefix}, and try to
|
| 25839 | |
find @code{prefix} at runtime, this way your package is relocatable.
|
| 25840 | |
@end itemize
|
| 25841 | |
|
| 25842 | |
|
| 25843 | |
@node Autom4te Cache
|
| 25844 | |
@section What is @file{autom4te.cache}?
|
| 25845 | |
|
| 25846 | |
@display
|
| 25847 | |
What is this directory @file{autom4te.cache}? Can I safely remove it?
|
| 25848 | |
@end display
|
| 25849 | |
|
| 25850 | |
In the GNU Build System, @file{configure.ac} plays a central
|
| 25851 | |
role and is read by many tools: @command{autoconf} to create
|
| 25852 | |
@file{configure}, @command{autoheader} to create @file{config.h.in},
|
| 25853 | |
@command{automake} to create @file{Makefile.in}, @command{autoscan} to
|
| 25854 | |
check the completeness of @file{configure.ac}, @command{autoreconf} to
|
| 25855 | |
check the GNU Build System components that are used. To
|
| 25856 | |
``read @file{configure.ac}'' actually means to compile it with M4,
|
| 25857 | |
which can be a long process for complex @file{configure.ac}.
|
| 25858 | |
|
| 25859 | |
This is why all these tools, instead of running directly M4, invoke
|
| 25860 | |
@command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
|
| 25861 | |
a specific demand, stores additional information in
|
| 25862 | |
@file{autom4te.cache} for future runs. For instance, if you run
|
| 25863 | |
@command{autoconf}, behind the scenes, @command{autom4te} also
|
| 25864 | |
stores information for the other tools, so that when you invoke
|
| 25865 | |
@command{autoheader} or @command{automake} etc., reprocessing
|
| 25866 | |
@file{configure.ac} is not needed. The speed up is frequently 30%,
|
| 25867 | |
and is increasing with the size of @file{configure.ac}.
|
| 25868 | |
|
| 25869 | |
But it is and remains being simply a cache: you can safely remove it.
|
| 25870 | |
|
| 25871 | |
@sp 1
|
| 25872 | |
|
| 25873 | |
@display
|
| 25874 | |
Can I permanently get rid of it?
|
| 25875 | |
@end display
|
| 25876 | |
|
| 25877 | |
The creation of this cache can be disabled from
|
| 25878 | |
@file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
|
| 25879 | |
details. You should be aware that disabling the cache slows down the
|
| 25880 | |
Autoconf test suite by 40%. The more GNU Build System
|
| 25881 | |
components are used, the more the cache is useful; for instance
|
| 25882 | |
running @samp{autoreconf -f} on the Core Utilities is twice slower without
|
| 25883 | |
the cache @emph{although @option{--force} implies that the cache is
|
| 25884 | |
not fully exploited}, and eight times slower than without
|
| 25885 | |
@option{--force}.
|
| 25886 | |
|
| 25887 | |
|
| 25888 | |
@node Present But Cannot Be Compiled
|
| 25889 | |
@section Header Present But Cannot Be Compiled
|
| 25890 | |
|
| 25891 | |
The most important guideline to bear in mind when checking for
|
| 25892 | |
features is to mimic as much as possible the intended use.
|
| 25893 | |
Unfortunately, old versions of @code{AC_CHECK_HEADER} and
|
| 25894 | |
@code{AC_CHECK_HEADERS} failed to follow this idea, and called
|
| 25895 | |
the preprocessor, instead of the compiler, to check for headers. As a
|
| 25896 | |
result, incompatibilities between headers went unnoticed during
|
| 25897 | |
configuration, and maintainers finally had to deal with this issue
|
| 25898 | |
elsewhere.
|
| 25899 | |
|
| 25900 | |
The transition began with Autoconf 2.56. As of Autoconf 2.64 both
|
| 25901 | |
checks are performed, and @command{configure} complains loudly if the
|
| 25902 | |
compiler and the preprocessor do not agree. However, only the compiler
|
| 25903 | |
result is considered.
|
| 25904 | |
|
| 25905 | |
Consider the following example:
|
| 25906 | |
|
| 25907 | |
@smallexample
|
| 25908 | |
$ @kbd{cat number.h}
|
| 25909 | |
typedef int number;
|
| 25910 | |
$ @kbd{cat pi.h}
|
| 25911 | |
const number pi = 3;
|
| 25912 | |
$ @kbd{cat configure.ac}
|
| 25913 | |
AC_INIT([Example], [1.0], [bug-example@@example.org])
|
| 25914 | |
AC_CHECK_HEADERS([pi.h])
|
| 25915 | |
$ @kbd{autoconf -Wall}
|
| 25916 | |
$ @kbd{./configure}
|
| 25917 | |
checking for gcc... gcc
|
| 25918 | |
checking for C compiler default output file name... a.out
|
| 25919 | |
checking whether the C compiler works... yes
|
| 25920 | |
checking whether we are cross compiling... no
|
| 25921 | |
checking for suffix of executables...
|
| 25922 | |
checking for suffix of object files... o
|
| 25923 | |
checking whether we are using the GNU C compiler... yes
|
| 25924 | |
checking whether gcc accepts -g... yes
|
| 25925 | |
checking for gcc option to accept ISO C89... none needed
|
| 25926 | |
checking how to run the C preprocessor... gcc -E
|
| 25927 | |
checking for grep that handles long lines and -e... grep
|
| 25928 | |
checking for egrep... grep -E
|
| 25929 | |
checking for ANSI C header files... yes
|
| 25930 | |
checking for sys/types.h... yes
|
| 25931 | |
checking for sys/stat.h... yes
|
| 25932 | |
checking for stdlib.h... yes
|
| 25933 | |
checking for string.h... yes
|
| 25934 | |
checking for memory.h... yes
|
| 25935 | |
checking for strings.h... yes
|
| 25936 | |
checking for inttypes.h... yes
|
| 25937 | |
checking for stdint.h... yes
|
| 25938 | |
checking for unistd.h... yes
|
| 25939 | |
checking pi.h usability... no
|
| 25940 | |
checking pi.h presence... yes
|
| 25941 | |
configure: WARNING: pi.h: present but cannot be compiled
|
| 25942 | |
configure: WARNING: pi.h: check for missing prerequisite headers?
|
| 25943 | |
configure: WARNING: pi.h: see the Autoconf documentation
|
| 25944 | |
configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
|
| 25945 | |
configure: WARNING: pi.h: proceeding with the compiler's result
|
| 25946 | |
configure: WARNING: ## -------------------------------------- ##
|
| 25947 | |
configure: WARNING: ## Report this to bug-example@@example.org ##
|
| 25948 | |
configure: WARNING: ## -------------------------------------- ##
|
| 25949 | |
checking for pi.h... yes
|
| 25950 | |
@end smallexample
|
| 25951 | |
|
| 25952 | |
@noindent
|
| 25953 | |
The proper way the handle this case is using the fourth argument
|
| 25954 | |
(@pxref{Generic Headers}):
|
| 25955 | |
|
| 25956 | |
@example
|
| 25957 | |
$ @kbd{cat configure.ac}
|
| 25958 | |
AC_INIT([Example], [1.0], [bug-example@@example.org])
|
| 25959 | |
AC_CHECK_HEADERS([number.h pi.h], [], [],
|
| 25960 | |
[[#ifdef HAVE_NUMBER_H
|
| 25961 | |
# include <number.h>
|
| 25962 | |
#endif
|
| 25963 | |
]])
|
| 25964 | |
$ @kbd{autoconf -Wall}
|
| 25965 | |
$ @kbd{./configure}
|
| 25966 | |
checking for gcc... gcc
|
| 25967 | |
checking for C compiler default output... a.out
|
| 25968 | |
checking whether the C compiler works... yes
|
| 25969 | |
checking whether we are cross compiling... no
|
| 25970 | |
checking for suffix of executables...
|
| 25971 | |
checking for suffix of object files... o
|
| 25972 | |
checking whether we are using the GNU C compiler... yes
|
| 25973 | |
checking whether gcc accepts -g... yes
|
| 25974 | |
checking for gcc option to accept ANSI C... none needed
|
| 25975 | |
checking for number.h... yes
|
| 25976 | |
checking for pi.h... yes
|
| 25977 | |
@end example
|
| 25978 | |
|
| 25979 | |
See @ref{Particular Headers}, for a list of headers with their
|
| 25980 | |
prerequisites.
|
| 25981 | |
|
| 25982 | |
@node Expanded Before Required
|
| 25983 | |
@section Expanded Before Required
|
| 25984 | |
|
| 25985 | |
@cindex expanded before required
|
| 25986 | |
Older versions of Autoconf silently built files with incorrect ordering
|
| 25987 | |
between dependent macros if an outer macro first expanded, then later
|
| 25988 | |
indirectly required, an inner macro. Starting with Autoconf 2.64, this
|
| 25989 | |
situation no longer generates out-of-order code, but results in
|
| 25990 | |
duplicate output and a syntax warning:
|
| 25991 | |
|
| 25992 | |
@example
|
| 25993 | |
$ @kbd{cat configure.ac}
|
| 25994 | |
@result{}AC_DEFUN([TESTA], [[echo in A
|
| 25995 | |
@result{}if test -n "$SEEN_A" ; then echo duplicate ; fi
|
| 25996 | |
@result{}SEEN_A=:]])
|
| 25997 | |
@result{}AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B
|
| 25998 | |
@result{}if test -z "$SEEN_A" ; then echo bug ; fi]])
|
| 25999 | |
@result{}AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]])
|
| 26000 | |
@result{}AC_DEFUN([OUTER], [[echo in OUTER]
|
| 26001 | |
@result{}TESTA
|
| 26002 | |
@result{}TESTC])
|
| 26003 | |
@result{}AC_INIT
|
| 26004 | |
@result{}OUTER
|
| 26005 | |
@result{}AC_OUTPUT
|
| 26006 | |
$ @kbd{autoconf}
|
| 26007 | |
@result{}configure.ac:11: warning: AC_REQUIRE:
|
| 26008 | |
@result{} `TESTA' was expanded before it was required
|
| 26009 | |
@result{}configure.ac:4: TESTB is expanded from...
|
| 26010 | |
@result{}configure.ac:6: TESTC is expanded from...
|
| 26011 | |
@result{}configure.ac:7: OUTER is expanded from...
|
| 26012 | |
@result{}configure.ac:11: the top level
|
| 26013 | |
@end example
|
| 26014 | |
|
| 26015 | |
@noindent
|
| 26016 | |
To avoid this warning, decide what purpose the macro in question serves.
|
| 26017 | |
If it only needs to be expanded once (for example, if it provides
|
| 26018 | |
initialization text used by later macros), then the simplest fix is to
|
| 26019 | |
change the macro to be declared with @code{AC_DEFUN_ONCE}
|
| 26020 | |
(@pxref{One-Shot Macros}), although this only works in Autoconf 2.64 and
|
| 26021 | |
newer. A more portable fix is to change all
|
| 26022 | |
instances of direct calls to instead go through @code{AC_REQUIRE}
|
| 26023 | |
(@pxref{Prerequisite Macros}). If, instead, the macro is parameterized
|
| 26024 | |
by arguments or by the current definition of other macros in the m4
|
| 26025 | |
environment, then the macro should always be directly expanded instead
|
| 26026 | |
of required.
|
| 26027 | |
|
| 26028 | |
For another case study, consider this example trimmed down from an
|
| 26029 | |
actual package. Originally, the package contained shell code and
|
| 26030 | |
multiple macro invocations at the top level of @file{configure.ac}:
|
| 26031 | |
|
| 26032 | |
@example
|
| 26033 | |
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
|
| 26034 | |
foobar=
|
| 26035 | |
AC_PROG_CC
|
| 26036 | |
FOO
|
| 26037 | |
@end example
|
| 26038 | |
|
| 26039 | |
@noindent
|
| 26040 | |
but that was getting complex, so the author wanted to offload some of
|
| 26041 | |
the text into a new macro in another file included via
|
| 26042 | |
@file{aclocal.m4}. The na@"ive approach merely wraps the text in a new
|
| 26043 | |
macro:
|
| 26044 | |
|
| 26045 | |
@example
|
| 26046 | |
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
|
| 26047 | |
AC_DEFUN([BAR], [
|
| 26048 | |
foobar=
|
| 26049 | |
AC_PROG_CC
|
| 26050 | |
FOO
|
| 26051 | |
])
|
| 26052 | |
BAR
|
| 26053 | |
@end example
|
| 26054 | |
|
| 26055 | |
@noindent
|
| 26056 | |
With older versions of Autoconf, the setting of @samp{foobar=} occurs
|
| 26057 | |
before the single compiler check, as the author intended. But with
|
| 26058 | |
Autoconf 2.64, this issues the ``expanded before it was required''
|
| 26059 | |
warning for @code{AC_PROG_CC}, and outputs two copies of the compiler
|
| 26060 | |
check, one before @samp{foobar=}, and one after. To understand why this
|
| 26061 | |
is happening, remember that the use of @code{AC_COMPILE_IFELSE} includes
|
| 26062 | |
a call to @code{AC_REQUIRE([AC_PROG_CC])} under the hood. According to
|
| 26063 | |
the documented semantics of @code{AC_REQUIRE}, this means that
|
| 26064 | |
@code{AC_PROG_CC} @emph{must} occur before the body of the outermost
|
| 26065 | |
@code{AC_DEFUN}, which in this case is @code{BAR}, thus preceding the
|
| 26066 | |
use of @samp{foobar=}. The older versions of Autoconf were broken with
|
| 26067 | |
regards to the rules of @code{AC_REQUIRE}, which explains why the code
|
| 26068 | |
changed from one over to two copies of @code{AC_PROG_CC} when upgrading
|
| 26069 | |
autoconf. In other words, the author was unknowingly relying on a bug
|
| 26070 | |
exploit to get the desired results, and that exploit broke once the bug
|
| 26071 | |
was fixed.
|
| 26072 | |
|
| 26073 | |
So, what recourse does the author have, to restore their intended
|
| 26074 | |
semantics of setting @samp{foobar=} prior to a single compiler check,
|
| 26075 | |
regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to
|
| 26076 | |
remember that only @code{AC_DEFUN} is impacted by @code{AC_REQUIRE};
|
| 26077 | |
there is always the possibility of using the lower-level
|
| 26078 | |
@code{m4_define}:
|
| 26079 | |
|
| 26080 | |
@example
|
| 26081 | |
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
|
| 26082 | |
m4_define([BAR], [
|
| 26083 | |
foobar=
|
| 26084 | |
AC_PROG_CC
|
| 26085 | |
FOO
|
| 26086 | |
])
|
| 26087 | |
BAR
|
| 26088 | |
@end example
|
| 26089 | |
|
| 26090 | |
@noindent
|
| 26091 | |
This works great if everything is in the same file. However, it does
|
| 26092 | |
not help in the case where the author wants to have @command{aclocal}
|
| 26093 | |
find the definition of @code{BAR} from its own file, since
|
| 26094 | |
@command{aclocal} requires the use of @code{AC_DEFUN}. In this case, a
|
| 26095 | |
better fix is to recognize that if @code{BAR} also uses
|
| 26096 | |
@code{AC_REQUIRE}, then there will no longer be direct expansion prior
|
| 26097 | |
to a subsequent require. Then, by creating yet another helper macro,
|
| 26098 | |
the author can once again guarantee a single invocation of
|
| 26099 | |
@code{AC_PROG_CC}, which will still occur after @code{foobar=}. The
|
| 26100 | |
author can also use @code{AC_BEFORE} to make sure no other macro
|
| 26101 | |
appearing before @code{BAR} has triggered an unwanted expansion of
|
| 26102 | |
@code{AC_PROG_CC}.
|
| 26103 | |
|
| 26104 | |
@example
|
| 26105 | |
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([@dots{}])])
|
| 26106 | |
AC_DEFUN([BEFORE_CC], [
|
| 26107 | |
foobar=
|
| 26108 | |
])
|
| 26109 | |
AC_DEFUN([BAR], [
|
| 26110 | |
AC_BEFORE([$0], [AC_PROG_CC])dnl
|
| 26111 | |
AC_REQUIRE([BEFORE_CC])dnl
|
| 26112 | |
AC_REQUIRE([AC_PROG_CC])dnl
|
| 26113 | |
FOO
|
| 26114 | |
])
|
| 26115 | |
BAR
|
| 26116 | |
@end example
|
| 26117 | |
|
| 26118 | |
|
| 26119 | |
@node Debugging
|
| 26120 | |
@section Debugging @command{configure} scripts
|
| 26121 | |
|
| 26122 | |
While in general, @command{configure} scripts generated by Autoconf
|
| 26123 | |
strive to be fairly portable to various systems, compilers, shells, and
|
| 26124 | |
other tools, it may still be necessary to debug a failing test, broken
|
| 26125 | |
script or makefile, or fix or override an incomplete, faulty, or erroneous
|
| 26126 | |
test, especially during macro development. Failures can occur at all levels,
|
| 26127 | |
in M4 syntax or semantics, shell script issues, or due to bugs in the
|
| 26128 | |
test or the tools invoked by @command{configure}. Together with the
|
| 26129 | |
rather arcane error message that @command{m4} and @command{make} may
|
| 26130 | |
produce when their input contains syntax errors, this can make debugging
|
| 26131 | |
rather painful.
|
| 26132 | |
|
| 26133 | |
Nevertheless, here is a list of hints and strategies that may help:
|
| 26134 | |
|
| 26135 | |
@itemize
|
| 26136 | |
@item
|
| 26137 | |
When @command{autoconf} fails, common causes for error include:
|
| 26138 | |
|
| 26139 | |
@itemize
|
| 26140 | |
@item
|
| 26141 | |
mismatched or unbalanced parentheses or braces (@pxref{Balancing
|
| 26142 | |
Parentheses}),
|
| 26143 | |
|
| 26144 | |
@item under- or overquoted macro arguments (@pxref{Autoconf
|
| 26145 | |
Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested
|
| 26146 | |
Macros}),
|
| 26147 | |
|
| 26148 | |
@item spaces between macro name and opening parenthesis (@pxref{Autoconf
|
| 26149 | |
Language}).
|
| 26150 | |
@end itemize
|
| 26151 | |
|
| 26152 | |
Typically, it helps to go back to the last working version of the input
|
| 26153 | |
and compare the differences for each of these errors. Another
|
| 26154 | |
possibility is to sprinkle pairs of @code{m4_traceon} and
|
| 26155 | |
@code{m4_traceoff} judiciously in the code, either without a parameter
|
| 26156 | |
or listing some macro names and watch @command{m4} expand its input
|
| 26157 | |
verbosely (@pxref{Debugging via autom4te}).
|
| 26158 | |
|
| 26159 | |
@item
|
| 26160 | |
Sometimes @command{autoconf} succeeds but the generated
|
| 26161 | |
@command{configure} script has invalid shell syntax. You can detect this
|
| 26162 | |
case by running @samp{bash -n configure} or @samp{sh -n configure}.
|
| 26163 | |
If this command fails, the same tips apply, as if @command{autoconf} had
|
| 26164 | |
failed.
|
| 26165 | |
|
| 26166 | |
@item
|
| 26167 | |
Debugging @command{configure} script execution may be done by sprinkling
|
| 26168 | |
pairs of @code{set -x} and @code{set +x} into the shell script before
|
| 26169 | |
and after the region that contains a bug. Running the whole script with
|
| 26170 | |
@samp{@var{shell} -vx ./configure 2>&1 | tee @var{log-file}} with a decent
|
| 26171 | |
@var{shell} may work, but produces lots of output. Here, it can help to
|
| 26172 | |
search for markers like @samp{checking for} a particular test in the
|
| 26173 | |
@var{log-file}.
|
| 26174 | |
|
| 26175 | |
@item
|
| 26176 | |
Alternatively, you might use a shell with debugging capabilities like
|
| 26177 | |
@uref{http://bashdb.sourceforge.net/, bashdb}.
|
| 26178 | |
|
| 26179 | |
@item
|
| 26180 | |
When @command{configure} tests produce invalid results for your system,
|
| 26181 | |
it may be necessary to override them:
|
| 26182 | |
|
| 26183 | |
@itemize
|
| 26184 | |
@item
|
| 26185 | |
For programs, tools or libraries variables, preprocessor, compiler, or
|
| 26186 | |
linker flags, it is often sufficient to override them at @command{make}
|
| 26187 | |
run time with some care (@pxref{Macros and Submakes}). Since this
|
| 26188 | |
normally won't cause @command{configure} to be run again with these
|
| 26189 | |
changed settings, it may fail if the changed variable would have caused
|
| 26190 | |
different test results from @command{configure}, so this may work only
|
| 26191 | |
for simple differences.
|
| 26192 | |
|
| 26193 | |
@item
|
| 26194 | |
Most tests which produce their result in a substituted variable allow to
|
| 26195 | |
override the test by setting the variable on the @command{configure}
|
| 26196 | |
command line (@pxref{Compilers and Options}, @pxref{Defining Variables},
|
| 26197 | |
@pxref{Particular Systems}).
|
| 26198 | |
|
| 26199 | |
@item
|
| 26200 | |
Many tests store their result in a cache variable (@pxref{Caching
|
| 26201 | |
Results}). This lets you override them either on the
|
| 26202 | |
@command{configure} command line as above, or through a primed cache or
|
| 26203 | |
site file (@pxref{Cache Files}, @pxref{Site Defaults}). The name of a
|
| 26204 | |
cache variable is documented with a test macro or may be inferred from
|
| 26205 | |
@ref{Cache Variable Names}; the precise semantics of undocumented
|
| 26206 | |
variables are often internal details, subject to change.
|
| 26207 | |
@end itemize
|
| 26208 | |
|
| 26209 | |
@item
|
| 26210 | |
Alternatively, @command{configure} may produce invalid results because
|
| 26211 | |
of uncaught programming errors, in your package or in an upstream
|
| 26212 | |
library package. For example, when @code{AC_CHECK_LIB} fails to find a
|
| 26213 | |
library with a specified function, always check @file{config.log}. This
|
| 26214 | |
will reveal the exact error that produced the failing result: the
|
| 26215 | |
library linked by @code{AC_CHECK_LIB} probably has a fatal bug.
|
| 26216 | |
@end itemize
|
| 26217 | |
|
| 26218 | |
Conversely, as macro author, you can make it easier for users of your
|
| 26219 | |
macro:
|
| 26220 | |
|
| 26221 | |
@itemize
|
| 26222 | |
@item
|
| 26223 | |
by minimizing dependencies between tests and between test results as far
|
| 26224 | |
as possible,
|
| 26225 | |
|
| 26226 | |
@item
|
| 26227 | |
by using @command{make} variables to factorize and allow
|
| 26228 | |
override of settings at @command{make} run time,
|
| 26229 | |
|
| 26230 | |
@item
|
| 26231 | |
by honoring the GNU Coding Standards and not overriding flags
|
| 26232 | |
reserved for the user except temporarily during @command{configure}
|
| 26233 | |
tests,
|
| 26234 | |
|
| 26235 | |
@item
|
| 26236 | |
by not requiring users of your macro to use the cache variables.
|
| 26237 | |
Instead, expose the result of the test via @var{run-if-true} and
|
| 26238 | |
@var{run-if-false} parameters. If the result is not a boolean,
|
| 26239 | |
then provide it through documented shell variables.
|
| 26240 | |
@end itemize
|
| 26241 | |
|
| 26242 | |
|
| 26243 | |
@c ===================================================== History of Autoconf.
|
| 26244 | |
|
| 26245 | |
@node History
|
| 26246 | |
@chapter History of Autoconf
|
| 26247 | |
@cindex History of autoconf
|
| 26248 | |
|
| 26249 | |
@emph{This chapter was written by the original author, David MacKenzie.}
|
| 26250 | |
|
| 26251 | |
You may be wondering, Why was Autoconf originally written? How did it
|
| 26252 | |
get into its present form? (Why does it look like gorilla spit?) If
|
| 26253 | |
you're not wondering, then this chapter contains no information useful
|
| 26254 | |
to you, and you might as well skip it. If you @emph{are} wondering,
|
| 26255 | |
then let there be light@enddots{}
|
| 26256 | |
|
| 26257 | |
@menu
|
| 26258 | |
* Genesis:: Prehistory and naming of @command{configure}
|
| 26259 | |
* Exodus:: The plagues of M4 and Perl
|
| 26260 | |
* Leviticus:: The priestly code of portability arrives
|
| 26261 | |
* Numbers:: Growth and contributors
|
| 26262 | |
* Deuteronomy:: Approaching the promises of easy configuration
|
| 26263 | |
@end menu
|
| 26264 | |
|
| 26265 | |
@node Genesis
|
| 26266 | |
@section Genesis
|
| 26267 | |
|
| 26268 | |
In June 1991 I was maintaining many of the GNU utilities for the
|
| 26269 | |
Free Software Foundation. As they were ported to more platforms and
|
| 26270 | |
more programs were added, the number of @option{-D} options that users
|
| 26271 | |
had to select in the makefile (around 20) became burdensome.
|
| 26272 | |
Especially for me---I had to test each new release on a bunch of
|
| 26273 | |
different systems. So I wrote a little shell script to guess some of
|
| 26274 | |
the correct settings for the fileutils package, and released it as part
|
| 26275 | |
of fileutils 2.0. That @command{configure} script worked well enough that
|
| 26276 | |
the next month I adapted it (by hand) to create similar @command{configure}
|
| 26277 | |
scripts for several other GNU utilities packages. Brian Berliner
|
| 26278 | |
also adapted one of my scripts for his CVS revision control system.
|
| 26279 | |
|
| 26280 | |
Later that summer, I learned that Richard Stallman and Richard Pixley
|
| 26281 | |
were developing similar scripts to use in the GNU compiler tools;
|
| 26282 | |
so I adapted my @command{configure} scripts to support their evolving
|
| 26283 | |
interface: using the file name @file{Makefile.in} as the templates;
|
| 26284 | |
adding @samp{+srcdir}, the first option (of many); and creating
|
| 26285 | |
@file{config.status} files.
|
| 26286 | |
|
| 26287 | |
@node Exodus
|
| 26288 | |
@section Exodus
|
| 26289 | |
|
| 26290 | |
As I got feedback from users, I incorporated many improvements, using
|
| 26291 | |
Emacs to search and replace, cut and paste, similar changes in each of
|
| 26292 | |
the scripts. As I adapted more GNU utilities packages to use
|
| 26293 | |
@command{configure} scripts, updating them all by hand became impractical.
|
| 26294 | |
Rich Murphey, the maintainer of the GNU graphics utilities, sent me
|
| 26295 | |
mail saying that the @command{configure} scripts were great, and asking if
|
| 26296 | |
I had a tool for generating them that I could send him. No, I thought,
|
| 26297 | |
but I should! So I started to work out how to generate them. And the
|
| 26298 | |
journey from the slavery of hand-written @command{configure} scripts to the
|
| 26299 | |
abundance and ease of Autoconf began.
|
| 26300 | |
|
| 26301 | |
Cygnus @command{configure}, which was being developed at around that time,
|
| 26302 | |
is table driven; it is meant to deal mainly with a discrete number of
|
| 26303 | |
system types with a small number of mainly unguessable features (such as
|
| 26304 | |
details of the object file format). The automatic configuration system
|
| 26305 | |
that Brian Fox had developed for Bash takes a similar approach. For
|
| 26306 | |
general use, it seems to me a hopeless cause to try to maintain an
|
| 26307 | |
up-to-date database of which features each variant of each operating
|
| 26308 | |
system has. It's easier and more reliable to check for most features on
|
| 26309 | |
the fly---especially on hybrid systems that people have hacked on
|
| 26310 | |
locally or that have patches from vendors installed.
|
| 26311 | |
|
| 26312 | |
I considered using an architecture similar to that of Cygnus
|
| 26313 | |
@command{configure}, where there is a single @command{configure} script that
|
| 26314 | |
reads pieces of @file{configure.in} when run. But I didn't want to have
|
| 26315 | |
to distribute all of the feature tests with every package, so I settled
|
| 26316 | |
on having a different @command{configure} made from each
|
| 26317 | |
@file{configure.in} by a preprocessor. That approach also offered more
|
| 26318 | |
control and flexibility.
|
| 26319 | |
|
| 26320 | |
I looked briefly into using the Metaconfig package, by Larry Wall,
|
| 26321 | |
Harlan Stenn, and Raphael Manfredi, but I decided not to for several
|
| 26322 | |
reasons. The @command{Configure} scripts it produces are interactive,
|
| 26323 | |
which I find quite inconvenient; I didn't like the ways it checked for
|
| 26324 | |
some features (such as library functions); I didn't know that it was
|
| 26325 | |
still being maintained, and the @command{Configure} scripts I had
|
| 26326 | |
seen didn't work on many modern systems (such as System V R4 and NeXT);
|
| 26327 | |
it wasn't flexible in what it could do in response to a feature's
|
| 26328 | |
presence or absence; I found it confusing to learn; and it was too big
|
| 26329 | |
and complex for my needs (I didn't realize then how much Autoconf would
|
| 26330 | |
eventually have to grow).
|
| 26331 | |
|
| 26332 | |
I considered using Perl to generate my style of @command{configure}
|
| 26333 | |
scripts, but decided that M4 was better suited to the job of simple
|
| 26334 | |
textual substitutions: it gets in the way less, because output is
|
| 26335 | |
implicit. Plus, everyone already has it. (Initially I didn't rely on
|
| 26336 | |
the GNU extensions to M4.) Also, some of my friends at the
|
| 26337 | |
University of Maryland had recently been putting M4 front ends on
|
| 26338 | |
several programs, including @code{tvtwm}, and I was interested in trying
|
| 26339 | |
out a new language.
|
| 26340 | |
|
| 26341 | |
@node Leviticus
|
| 26342 | |
@section Leviticus
|
| 26343 | |
|
| 26344 | |
Since my @command{configure} scripts determine the system's capabilities
|
| 26345 | |
automatically, with no interactive user intervention, I decided to call
|
| 26346 | |
the program that generates them Autoconfig. But with a version number
|
| 26347 | |
tacked on, that name would be too long for old Unix file systems,
|
| 26348 | |
so I shortened it to Autoconf.
|
| 26349 | |
|
| 26350 | |
In the fall of 1991 I called together a group of fellow questers after
|
| 26351 | |
the Holy Grail of portability (er, that is, alpha testers) to give me
|
| 26352 | |
feedback as I encapsulated pieces of my handwritten scripts in M4 macros
|
| 26353 | |
and continued to add features and improve the techniques used in the
|
| 26354 | |
checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
|
| 26355 | |
with the idea of making an Autoconf shell script to run M4
|
| 26356 | |
and check for unresolved macro calls; Richard Pixley, who suggested
|
| 26357 | |
running the compiler instead of searching the file system to find
|
| 26358 | |
include files and symbols, for more accurate results; Karl Berry, who
|
| 26359 | |
got Autoconf to configure @TeX{} and added the macro index to the
|
| 26360 | |
documentation; and Ian Lance Taylor, who added support for creating a C
|
| 26361 | |
header file as an alternative to putting @option{-D} options in a
|
| 26362 | |
makefile, so he could use Autoconf for his UUCP package.
|
| 26363 | |
The alpha testers cheerfully adjusted their files again and again as the
|
| 26364 | |
names and calling conventions of the Autoconf macros changed from
|
| 26365 | |
release to release. They all contributed many specific checks, great
|
| 26366 | |
ideas, and bug fixes.
|
| 26367 | |
|
| 26368 | |
@node Numbers
|
| 26369 | |
@section Numbers
|
| 26370 | |
|
| 26371 | |
In July 1992, after months of alpha testing, I released Autoconf 1.0,
|
| 26372 | |
and converted many GNU packages to use it. I was surprised by how
|
| 26373 | |
positive the reaction to it was. More people started using it than I
|
| 26374 | |
could keep track of, including people working on software that wasn't
|
| 26375 | |
part of the GNU Project (such as TCL, FSP, and Kerberos V5).
|
| 26376 | |
Autoconf continued to improve rapidly, as many people using the
|
| 26377 | |
@command{configure} scripts reported problems they encountered.
|
| 26378 | |
|
| 26379 | |
Autoconf turned out to be a good torture test for M4 implementations.
|
| 26380 | |
Unix M4 started to dump core because of the length of the
|
| 26381 | |
macros that Autoconf defined, and several bugs showed up in GNU
|
| 26382 | |
M4 as well. Eventually, we realized that we needed to use some
|
| 26383 | |
features that only GNU M4 has. 4.3BSD M4, in
|
| 26384 | |
particular, has an impoverished set of builtin macros; the System V
|
| 26385 | |
version is better, but still doesn't provide everything we need.
|
| 26386 | |
|
| 26387 | |
More development occurred as people put Autoconf under more stresses
|
| 26388 | |
(and to uses I hadn't anticipated). Karl Berry added checks for X11.
|
| 26389 | |
david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
|
| 26390 | |
invalid arguments. Jim Blandy bravely coerced it into configuring
|
| 26391 | |
GNU Emacs, laying the groundwork for several later improvements.
|
| 26392 | |
Roland McGrath got it to configure the GNU C Library, wrote the
|
| 26393 | |
@command{autoheader} script to automate the creation of C header file
|
| 26394 | |
templates, and added a @option{--verbose} option to @command{configure}.
|
| 26395 | |
Noah Friedman added the @option{--autoconf-dir} option and
|
| 26396 | |
@code{AC_MACRODIR} environment variable. (He also coined the term
|
| 26397 | |
@dfn{autoconfiscate} to mean ``adapt a software package to use
|
| 26398 | |
Autoconf''.) Roland and Noah improved the quoting protection in
|
| 26399 | |
@code{AC_DEFINE} and fixed many bugs, especially when I got sick of
|
| 26400 | |
dealing with portability problems from February through June, 1993.
|
| 26401 | |
|
| 26402 | |
@node Deuteronomy
|
| 26403 | |
@section Deuteronomy
|
| 26404 | |
|
| 26405 | |
A long wish list for major features had accumulated, and the effect of
|
| 26406 | |
several years of patching by various people had left some residual
|
| 26407 | |
cruft. In April 1994, while working for Cygnus Support, I began a major
|
| 26408 | |
revision of Autoconf. I added most of the features of the Cygnus
|
| 26409 | |
@command{configure} that Autoconf had lacked, largely by adapting the
|
| 26410 | |
relevant parts of Cygnus @command{configure} with the help of david zuhn
|
| 26411 | |
and Ken Raeburn. These features include support for using
|
| 26412 | |
@file{config.sub}, @file{config.guess}, @option{--host}, and
|
| 26413 | |
@option{--target}; making links to files; and running @command{configure}
|
| 26414 | |
scripts in subdirectories. Adding these features enabled Ken to convert
|
| 26415 | |
GNU @code{as}, and Rob Savoye to convert DejaGNU, to using
|
| 26416 | |
Autoconf.
|
| 26417 | |
|
| 26418 | |
I added more features in response to other peoples' requests. Many
|
| 26419 | |
people had asked for @command{configure} scripts to share the results of
|
| 26420 | |
the checks between runs, because (particularly when configuring a large
|
| 26421 | |
source tree, like Cygnus does) they were frustratingly slow. Mike
|
| 26422 | |
Haertel suggested adding site-specific initialization scripts. People
|
| 26423 | |
distributing software that had to unpack on MS-DOS asked for a way to
|
| 26424 | |
override the @file{.in} extension on the file names, which produced file
|
| 26425 | |
names like @file{config.h.in} containing two dots. Jim Avera did an
|
| 26426 | |
extensive examination of the problems with quoting in @code{AC_DEFINE}
|
| 26427 | |
and @code{AC_SUBST}; his insights led to significant improvements.
|
| 26428 | |
Richard Stallman asked that compiler output be sent to @file{config.log}
|
| 26429 | |
instead of @file{/dev/null}, to help people debug the Emacs
|
| 26430 | |
@command{configure} script.
|
| 26431 | |
|
| 26432 | |
I made some other changes because of my dissatisfaction with the quality
|
| 26433 | |
of the program. I made the messages showing results of the checks less
|
| 26434 | |
ambiguous, always printing a result. I regularized the names of the
|
| 26435 | |
macros and cleaned up coding style inconsistencies. I added some
|
| 26436 | |
auxiliary utilities that I had developed to help convert source code
|
| 26437 | |
packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
|
| 26438 | |
the macros not interrupt each others' messages. (That feature revealed
|
| 26439 | |
some performance bottlenecks in GNU M4, which he hastily
|
| 26440 | |
corrected!) I reorganized the documentation around problems people want
|
| 26441 | |
to solve. And I began a test suite, because experience had shown that
|
| 26442 | |
Autoconf has a pronounced tendency to regress when we change it.
|
| 26443 | |
|
| 26444 | |
Again, several alpha testers gave invaluable feedback, especially
|
| 26445 | |
Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
|
| 26446 | |
and Mark Eichin.
|
| 26447 | |
|
| 26448 | |
Finally, version 2.0 was ready. And there was much rejoicing. (And I
|
| 26449 | |
have free time again. I think. Yeah, right.)
|
| 26450 | |
|
| 26451 | |
|
| 26452 | |
@c ========================================================== Appendices
|
| 26453 | |
|
| 26454 | |
|
| 26455 | |
@node GNU Free Documentation License
|
| 26456 | |
@appendix GNU Free Documentation License
|
| 26457 | |
|
| 26458 | |
@include fdl.texi
|
| 26459 | |
|
| 26460 | |
@node Indices
|
| 26461 | |
@appendix Indices
|
| 26462 | |
|
| 26463 | |
@menu
|
| 26464 | |
* Environment Variable Index:: Index of environment variables used
|
| 26465 | |
* Output Variable Index:: Index of variables set in output files
|
| 26466 | |
* Preprocessor Symbol Index:: Index of C preprocessor symbols defined
|
| 26467 | |
* Cache Variable Index:: Index of documented cache variables
|
| 26468 | |
* Autoconf Macro Index:: Index of Autoconf macros
|
| 26469 | |
* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
|
| 26470 | |
* Autotest Macro Index:: Index of Autotest macros
|
| 26471 | |
* Program & Function Index:: Index of those with portability problems
|
| 26472 | |
* Concept Index:: General index
|
| 26473 | |
@end menu
|
| 26474 | |
|
| 26475 | |
@node Environment Variable Index
|
| 26476 | |
@appendixsec Environment Variable Index
|
| 26477 | |
|
| 26478 | |
This is an alphabetical list of the environment variables that might
|
| 26479 | |
influence Autoconf checks.
|
| 26480 | |
|
| 26481 | |
@printindex ev
|
| 26482 | |
|
| 26483 | |
@node Output Variable Index
|
| 26484 | |
@appendixsec Output Variable Index
|
| 26485 | |
|
| 26486 | |
This is an alphabetical list of the variables that Autoconf can
|
| 26487 | |
substitute into files that it creates, typically one or more
|
| 26488 | |
makefiles. @xref{Setting Output Variables}, for more information
|
| 26489 | |
on how this is done.
|
| 26490 | |
|
| 26491 | |
@printindex ov
|
| 26492 | |
|
| 26493 | |
@node Preprocessor Symbol Index
|
| 26494 | |
@appendixsec Preprocessor Symbol Index
|
| 26495 | |
|
| 26496 | |
This is an alphabetical list of the C preprocessor symbols that the
|
| 26497 | |
Autoconf macros define. To work with Autoconf, C source code needs to
|
| 26498 | |
use these names in @code{#if} or @code{#ifdef} directives.
|
| 26499 | |
|
| 26500 | |
@printindex cv
|
| 26501 | |
|
| 26502 | |
@node Cache Variable Index
|
| 26503 | |
@appendixsec Cache Variable Index
|
| 26504 | |
|
| 26505 | |
This is an alphabetical list of documented cache variables used
|
| 26506 | |
by macros defined in Autoconf. Autoconf macros may use additional cache
|
| 26507 | |
variables internally.
|
| 26508 | |
@ifset shortindexflag
|
| 26509 | |
To make the list easier to use, the variables are listed without their
|
| 26510 | |
preceding @samp{ac_cv_}.
|
| 26511 | |
@end ifset
|
| 26512 | |
|
| 26513 | |
@printindex CA
|
| 26514 | |
|
| 26515 | |
@node Autoconf Macro Index
|
| 26516 | |
@appendixsec Autoconf Macro Index
|
| 26517 | |
|
| 26518 | |
This is an alphabetical list of the Autoconf macros.
|
| 26519 | |
@ifset shortindexflag
|
| 26520 | |
To make the list easier to use, the macros are listed without their
|
| 26521 | |
preceding @samp{AC_}.
|
| 26522 | |
@end ifset
|
| 26523 | |
|
| 26524 | |
@printindex AC
|
| 26525 | |
|
| 26526 | |
@node M4 Macro Index
|
| 26527 | |
@appendixsec M4 Macro Index
|
| 26528 | |
|
| 26529 | |
This is an alphabetical list of the M4, M4sugar, and M4sh macros.
|
| 26530 | |
@ifset shortindexflag
|
| 26531 | |
To make the list easier to use, the macros are listed without their
|
| 26532 | |
preceding @samp{m4_} or @samp{AS_}. The prefix is @samp{m4_} for
|
| 26533 | |
all-lowercase macro names and @samp{AS_} for all-uppercase macro
|
| 26534 | |
names.
|
| 26535 | |
@end ifset
|
| 26536 | |
|
| 26537 | |
@printindex MS
|
| 26538 | |
|
| 26539 | |
@node Autotest Macro Index
|
| 26540 | |
@appendixsec Autotest Macro Index
|
| 26541 | |
|
| 26542 | |
This is an alphabetical list of the Autotest macros.
|
| 26543 | |
@ifset shortindexflag
|
| 26544 | |
To make the list easier to use, the macros are listed without their
|
| 26545 | |
preceding @samp{AT_}.
|
| 26546 | |
@end ifset
|
| 26547 | |
|
| 26548 | |
@printindex AT
|
| 26549 | |
|
| 26550 | |
@node Program & Function Index
|
| 26551 | |
@appendixsec Program and Function Index
|
| 26552 | |
|
| 26553 | |
This is an alphabetical list of the programs and functions whose
|
| 26554 | |
portability is discussed in this document.
|
| 26555 | |
|
| 26556 | |
@printindex pr
|
| 26557 | |
|
| 26558 | |
@node Concept Index
|
| 26559 | |
@appendixsec Concept Index
|
| 26560 | |
|
| 26561 | |
This is an alphabetical list of the files, tools, and concepts
|
| 26562 | |
introduced in this document.
|
| 26563 | |
|
| 26564 | |
@printindex cp
|
| 26565 | |
|
| 26566 | |
@bye
|
| 26567 | |
|
| 26568 | |
@c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
|
| 26569 | |
@c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
|
| 26570 | |
@c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
|
| 26571 | |
@c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
|
| 26572 | |
@c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
|
| 26573 | |
@c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
|
| 26574 | |
@c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
|
| 26575 | |
@c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
|
| 26576 | |
@c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
|
| 26577 | |
@c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
|
| 26578 | |
@c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
|
| 26579 | |
@c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
|
| 26580 | |
@c LocalWords: distclean uninstall noindent versioning Tromey dir
|
| 26581 | |
@c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
|
| 26582 | |
@c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
|
| 26583 | |
@c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
|
| 26584 | |
@c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
|
| 26585 | |
@c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
|
| 26586 | |
@c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
|
| 26587 | |
@c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
|
| 26588 | |
@c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
|
| 26589 | |
@c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
|
| 26590 | |
@c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
|
| 26591 | |
@c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
|
| 26592 | |
@c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
|
| 26593 | |
@c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
|
| 26594 | |
@c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
|
| 26595 | |
@c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
|
| 26596 | |
@c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
|
| 26597 | |
@c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
|
| 26598 | |
@c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
|
| 26599 | |
@c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
|
| 26600 | |
@c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
|
| 26601 | |
@c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
|
| 26602 | |
@c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
|
| 26603 | |
@c LocalWords: SETGID getloadavg nlist GETMNTENT irix
|
| 26604 | |
@c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
|
| 26605 | |
@c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
|
| 26606 | |
@c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
|
| 26607 | |
@c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
|
| 26608 | |
@c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
|
| 26609 | |
@c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
|
| 26610 | |
@c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
|
| 26611 | |
@c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
|
| 26612 | |
@c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
|
| 26613 | |
@c LocalWords: STDBOOL BOOL stdbool cplusplus bool Bool stdarg tm
|
| 26614 | |
@c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
|
| 26615 | |
@c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
|
| 26616 | |
@c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
|
| 26617 | |
@c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
|
| 26618 | |
@c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
|
| 26619 | |
@c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
|
| 26620 | |
@c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
|
| 26621 | |
@c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
|
| 26622 | |
@c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
|
| 26623 | |
@c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
|
| 26624 | |
@c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
|
| 26625 | |
@c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
|
| 26626 | |
@c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
|
| 26627 | |
@c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
|
| 26628 | |
@c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
|
| 26629 | |
@c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
|
| 26630 | |
@c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
|
| 26631 | |
@c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
|
| 26632 | |
@c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
|
| 26633 | |
@c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
|
| 26634 | |
@c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
|
| 26635 | |
@c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
|
| 26636 | |
@c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
|
| 26637 | |
@c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
|
| 26638 | |
@c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
|
| 26639 | |
@c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
|
| 26640 | |
@c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped
|
| 26641 | |
@c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
|
| 26642 | |
@c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
|
| 26643 | |
@c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
|
| 26644 | |
@c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
|
| 26645 | |
@c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
|
| 26646 | |
@c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
|
| 26647 | |
@c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
|
| 26648 | |
@c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
|
| 26649 | |
@c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
|
| 26650 | |
@c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
|
| 26651 | |
@c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
|
| 26652 | |
@c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
|
| 26653 | |
@c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
|
| 26654 | |
@c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
|
| 26655 | |
@c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
|
| 26656 | |
@c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
|
| 26657 | |
@c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
|
| 26658 | |
@c LocalWords: Dynix basename aname cname macroexpands xno xcheck
|
| 26659 | |
@c LocalWords: LIBREADLINE lreadline lncurses libreadline
|
| 26660 | |
|
| 26661 | |
@c Local Variables:
|
| 26662 | |
@c fill-column: 72
|
| 26663 | |
@c ispell-local-dictionary: "american"
|
| 26664 | |
@c indent-tabs-mode: nil
|
| 26665 | |
@c whitespace-check-buffer-indent: nil
|
| 26666 | |
@c End:
|