1Config::AutoConf(3) User Contributed Perl Documentation Config::AutoConf(3)
2
6 Config::AutoConf - A module to implement some of AutoConf macros in
7 pure perl.
8
10 With this module I pretend to simulate some of the tasks AutoConf
11 macros do. To detect a command, to detect a library, etc.
12
14 use Config::AutoConf;
15 Config::AutoConf->check_prog("agrep");
17 my $grep = Config::AutoConf->check_progs("agrep", "egrep", "grep");
18 Config::AutoConf->check_header("ncurses.h");
20 my $curses = Config::AutoConf->check_headers("ncurses.h","curses.h");
21 Config::AutoConf->check_prog_awk;
23 Config::AutoConf->check_prog_egrep;
24 Config::AutoConf->check_cc();
26 Config::AutoConf->check_lib("ncurses", "tgoto");
28 Config::AutoConf->check_file("/etc/passwd"); # -f && -r
30
32 Config::AutoConf is intended to provide the same opportunities to Perl
33 developers as GNU Autoconf <http://www.gnu.org/software/autoconf/> does
34 for Shell developers.
35 As Perl is the second most deployed language (mind: every Unix comes
37 with Perl, several mini-computers have Perl and even lot's of Windows
38 machines run Perl software - which requires deployed Perl there, too),
39 this gives wider support than Shell based probes.
40 The API is leaned against GNU Autoconf, but we try to make the API
42 (especially optional arguments) more Perl'ish than m4 abilities allow
43 to the original.
44
46 new
47 This function instantiates a new instance of Config::AutoConf, e.g. to
48 configure child components. The constructor adds also values set via
49 environment variable "PERL5_AUTOCONF_OPTS".
50
52 check_file
53 This function checks if a file exists in the system and is readable by
54 the user. Returns a boolean. You can use '-f $file && -r $file' so you
55 don't need to use a function call.
56 check_files
58 This function checks if a set of files exist in the system and are
59 readable by the user. Returns a boolean.
60 check_prog( $prog, \@dirlist?, \%options? )
62 This function checks for a program with the supplied name. In success
63 returns the full path for the executable;
64 An optional array reference containing a list of directories to be
66 searched instead of $PATH is gracefully honored.
67 If the very last parameter contains a hash reference, "CODE" references
69 to action_on_true or action_on_false are executed, respectively.
70 check_progs(progs, [dirlist])
72 This function takes a list of program names. Returns the full path for
73 the first found on the system. Returns undef if none was found.
74 An optional array reference containing a list of directories to be
76 searched instead of $PATH is gracefully honored.
77 If the very last parameter contains a hash reference, "CODE" references
79 to action_on_true or action_on_false are executed, respectively. The
80 name of the $prog to check and the found full path are passed as first
81 and second argument to the action_on_true callback.
82 check_prog_yacc
84 From the GNU Autoconf
85 <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
86 If `bison' is found, set [...] `bison -y'.
88 Otherwise, if `byacc' is found, set [...] `byacc'.
89 Otherwise set [...] `yacc'. The result of this test can be influenced
90 by setting the variable YACC or the cache variable ac_cv_prog_YACC.
91 Returns the full path, if found.
93 check_prog_awk
95 From the GNU Autoconf
96 <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
97 Check for `gawk', `mawk', `nawk', and `awk', in that order, and
99 set output [...] to the first one that is found. It tries
100 `gawk' first because that is reported to be the best implementation.
101 The result can be overridden by setting the variable AWK or the
102 cache variable ac_cv_prog_AWK.
103 Note that it returns the full path, if found.
105 check_prog_egrep
107 From the GNU Autoconf
108 <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
109 Check for `grep -E' and `egrep', in that order, and [...] output
111 [...] the first one that is found. The result can be overridden by
112 setting the EGREP variable and is cached in the ac_cv_path_EGREP
113 variable.
114 Note that it returns the full path, if found.
116 check_prog_lex
118 From the GNU Autoconf
119 <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
120 If flex is found, set output [...] to ‘flex’ and [...] to -lfl, if that
122 library is in a standard place. Otherwise set output [...] to ‘lex’ and
123 [...] to -ll, if found. If [...] packages [...] ship the generated
124 file.yy.c alongside the source file.l, this [...] allows users without a
125 lexer generator to still build the package even if the timestamp for
126 file.l is inadvertently changed.
127 Note that it returns the full path, if found.
129 The structure $self->{lex} is set with attributes
131 prog => $LEX
133 lib => $LEXLIB
134 root => $lex_root
135 check_prog_sed
137 From the GNU Autoconf
138 <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
139 Set output variable [...] to a Sed implementation that conforms to Posix
141 and does not have arbitrary length limits. Report an error if no
142 acceptable Sed is found. See Limitations of Usual Tools, for more
143 information about portability problems with Sed.
144 The result of this test can be overridden by setting the SED variable and
146 is cached in the ac_cv_path_SED variable.
147 Note that it returns the full path, if found.
149 check_prog_pkg_config
151 Checks for "pkg-config" program. No additional tests are made for it
152 ...
153 check_prog_cc
155 Determine a C compiler to use. Currently the probe is delegated to
156 ExtUtils::CBuilder.
157 check_cc
159 (Deprecated) Old name of "check_prog_cc".
160 check_valid_compiler
162 This function checks for a valid compiler for the currently active
163 language. At the very moment only "C" is understood (corresponding to
164 your compiler default options, e.g. -std=gnu89).
165 check_valid_compilers(;\@)
167 Checks for valid compilers for each given language. When unspecified
168 defaults to "[ "C" ]".
169 msg_checking
171 Prints "Checking @_ ..."
172 msg_result
174 Prints result \n
175 msg_notice
177 Prints "configure: " @_ to stdout
178 msg_warn
180 Prints "configure: " @_ to stderr
181 msg_error
183 Prints "configure: " @_ to stderr and exits with exit code 0 (tells
184 toolchain to stop here and report unsupported environment)
185 msg_failure
187 Prints "configure: " @_ to stderr and exits with exit code 0 (tells
188 toolchain to stop here and report unsupported environment). Additional
189 details are provides in config.log (probably more information in a
190 later stage).
191 define_var( $name, $value [, $comment ] )
193 Defines a check variable for later use in further checks or code to
194 compile. Returns the value assigned value
195 write_config_h( [$target] )
197 Writes the defined constants into given target:
198 Config::AutoConf->write_config_h( "config.h" );
200 push_lang(lang [, implementor ])
202 Puts the current used language on the stack and uses specified language
203 for subsequent operations until ending pop_lang call.
204 pop_lang([ lang ])
206 Pops the currently used language from the stack and restores previously
207 used language. If lang specified, it's asserted that the current used
208 language equals to specified language (helps finding control flow
209 bugs).
210 lang_build_program( prologue, body )
212 Builds program for current chosen language. If no prologue is given
213 (undef), the default headers are used. If body is missing, default body
214 is used.
215 Typical call of
217 Config::AutoConf->lang_build_program( "const char hw[] = \"Hello, World\\n\";",
219 "fputs (hw, stdout);" )
220 will create
222 const char hw[] = "Hello, World\n";
224 /* Override any gcc2 internal prototype to avoid an error. */
226 #ifdef __cplusplus
227 extern "C" {
228 #endif
229 int
231 main (int argc, char **argv)
232 {
233 (void)argc;
234 (void)argv;
235 fputs (hw, stdout);;
236 return 0;
237 }
238 #ifdef __cplusplus
240 }
241 #endif
242 lang_call( [prologue], function )
244 Builds program which simply calls given function. When given, prologue
245 is prepended otherwise, the default includes are used.
246 lang_builtin( [prologue], builtin )
248 Builds program which simply proves whether a builtin is known to
249 language compiler.
250 lang_build_bool_test (prologue, test, [@decls])
252 Builds a static test which will fail to compile when test evaluates to
253 false. If @decls is given, it's prepended before the test code at the
254 variable definition place.
255 push_includes
257 Adds given list of directories to preprocessor/compiler invocation.
258 This is not proved to allow adding directories which might be created
259 during the build.
260 push_preprocess_flags
262 Adds given flags to the parameter list for preprocessor invocation.
263 push_compiler_flags
265 Adds given flags to the parameter list for compiler invocation.
266 push_libraries
268 Adds given list of libraries to the parameter list for linker
269 invocation.
270 push_library_paths
272 Adds given list of library paths to the parameter list for linker
273 invocation.
274 push_link_flags
276 Adds given flags to the parameter list for linker invocation.
277 compile_if_else( $src, \%options? )
279 This function tries to compile specified code and returns a boolean
280 value containing check success state.
281 If the very last parameter contains a hash reference, "CODE" references
283 to action_on_true or action_on_false are executed, respectively.
284 link_if_else( $src, \%options? )
286 This function tries to compile and link specified code and returns a
287 boolean value containing check success state.
288 If the very last parameter contains a hash reference, "CODE" references
290 to action_on_true or action_on_false are executed, respectively.
291 check_cached( $cache-key, $check-title, \&check-call, \%options? )
293 Retrieves the result of a previous "check_cached" invocation from
294 "cache-key", or (when called for the first time) populates the cache by
295 invoking "\&check_call".
296 If the very last parameter contains a hash reference, "CODE" references
298 to action_on_true or action_on_false are executed on every call to
299 check_cached (not just the first cache-populating invocation),
300 respectively.
301 cache_val
303 This function returns the value of a previously check_cached call.
304 check_decl( $symbol, \%options? )
306 This method actually tests whether symbol is defined as a macro or can
307 be used as an r-value, not whether it is really declared, because it is
308 much safer to avoid introducing extra declarations when they are not
309 needed. In order to facilitate use of C++ and overloaded function
310 declarations, it is possible to specify function argument types in
311 parentheses for types which can be zero-initialized:
312 Config::AutoConf->check_decl("basename(char *)")
314 This method caches its result in the "ac_cv_decl_<set lang>"_symbol
316 variable.
317 If the very last parameter contains a hash reference, "CODE" references
319 to action_on_true or action_on_false are executed, respectively. When
320 a prologue exists in the optional hash at end, it will be favored over
321 "default includes" (represented by "_default_includes"). If any of
322 action_on_cache_true, action_on_cache_false is defined, both callbacks
323 are passed to "check_cached" as action_on_true or action_on_false to
324 "check_cached", respectively.
325 check_decls( symbols, \%options? )
327 For each of the symbols (with optional function argument types for C++
328 overloads), run check_decl.
329 Contrary to GNU Autoconf, this method does not declare
331 "HAVE_DECL_symbol" macros for the resulting "confdefs.h", because it
332 differs as "check_decl" between compiling languages.
333 If the very last parameter contains a hash reference, "CODE" references
335 to action_on_true or action_on_false are executed, respectively. When
336 a prologue exists in the optional hash at end, it will be favored over
337 "default includes" (represented by "_default_includes"). If any of
338 action_on_cache_true, action_on_cache_false is defined, both callbacks
339 are passed to "check_cached" as action_on_true or action_on_false to
340 "check_cached", respectively. Given callbacks for
341 action_on_symbol_true or action_on_symbol_false are called for each
342 symbol checked using "check_decl" receiving the symbol as first
343 argument.
344 check_func( $function, \%options? )
346 This method actually tests whether $funcion can be linked into a
347 program trying to call $function. This method caches its result in the
348 ac_cv_func_FUNCTION variable.
349 If the very last parameter contains a hash reference, "CODE" references
351 to action_on_true or action_on_false are executed, respectively. If
352 any of action_on_cache_true, action_on_cache_false is defined, both
353 callbacks are passed to "check_cached" as action_on_true or
354 action_on_false to "check_cached", respectively.
355 Returns: True if the function was found, false otherwise
357 check_funcs( \@functions-list, $action-if-true?, $action-if-false? )
359 The same as check_func, but takes a list of functions in
360 \@functions-list to look for and checks for each in turn. Define
361 HAVE_FUNCTION for each function that was found.
362 If the very last parameter contains a hash reference, "CODE" references
364 to action_on_true or action_on_false are executed, respectively. If
365 any of action_on_cache_true, action_on_cache_false is defined, both
366 callbacks are passed to "check_cached" as action_on_true or
367 action_on_false to "check_cached", respectively. Given callbacks for
368 action_on_function_true or action_on_function_false are called for each
369 symbol checked using "check_func" receiving the symbol as first
370 argument.
371 check_builtin( $builtin, \%options? )
373 This method actually tests whether $builtin is a supported built-in
374 known by the compiler. Either, by giving us the type of the built-in or
375 by taking the value from "__has_builtin". This method caches its
376 result in the ac_cv_builtin_FUNCTION variable.
377 If the very last parameter contains a hash reference, "CODE" references
379 to action_on_true or action_on_false are executed, respectively. If
380 any of action_on_cache_true, action_on_cache_false is defined, both
381 callbacks are passed to "check_cached" as action_on_true or
382 action_on_false to "check_cached", respectively.
383 Returns: True if the function was found, false otherwise
385 check_type( $symbol, \%options? )
387 Check whether type is defined. It may be a compiler builtin type or
388 defined by the includes. In C, type must be a type-name, so that the
389 expression "sizeof (type)" is valid (but "sizeof ((type))" is not).
390 If type type is defined, preprocessor macro HAVE_type (in all capitals,
392 with "*" replaced by "P" and spaces and dots replaced by underscores)
393 is defined.
394 This method caches its result in the "ac_cv_type_"type variable.
396 If the very last parameter contains a hash reference, "CODE" references
398 to action_on_true or action_on_false are executed, respectively. When
399 a prologue exists in the optional hash at end, it will be favored over
400 "default includes" (represented by "_default_includes"). If any of
401 action_on_cache_true, action_on_cache_false is defined, both callbacks
402 are passed to "check_cached" as action_on_true or action_on_false to
403 "check_cached", respectively.
404 check_types( \@type-list, \%options? )
406 For each type in @type-list, call check_type is called to check for
407 type and return the accumulated result (accumulation op is binary and).
408 If the very last parameter contains a hash reference, "CODE" references
410 to action_on_true or action_on_false are executed, respectively. When
411 a prologue exists in the optional hash at end, it will be favored over
412 "default includes" (represented by "_default_includes"). If any of
413 action_on_cache_true, action_on_cache_false is defined, both callbacks
414 are passed to "check_cached" as action_on_true or action_on_false to
415 "check_cached", respectively. Given callbacks for action_on_type_true
416 or action_on_type_false are called for each symbol checked using
417 "check_type" receiving the symbol as first argument.
418 compute_int( $expression, @decls?, \%options )
420 Returns the value of the integer expression. The value should fit in an
421 initializer in a C variable of type signed long. It should be possible
422 to evaluate the expression at compile-time. If no includes are
423 specified, the default includes are used.
424 If the very last parameter contains a hash reference, "CODE" references
426 to action_on_true or action_on_false are executed, respectively. When
427 a prologue exists in the optional hash at end, it will be favored over
428 "default includes" (represented by "_default_includes"). If any of
429 action_on_cache_true, action_on_cache_false is defined, both callbacks
430 are passed to "check_cached" as action_on_true or action_on_false to
431 "check_cached", respectively.
432 check_sizeof_type( $type, \%options? )
434 Checks for the size of the specified type by compiling and define
435 "SIZEOF_type" using the determined size.
436 In opposition to GNU AutoConf, this method can determine size of
438 structure members, e.g.
439 $ac->check_sizeof_type( "SV.sv_refcnt", { prologue => $include_perl } );
441 # or
442 $ac->check_sizeof_type( "struct utmpx.ut_id", { prologue => "#include <utmpx.h>" } );
443 This method caches its result in the "ac_cv_sizeof_<set lang>"_type
445 variable.
446 If the very last parameter contains a hash reference, "CODE" references
448 to action_on_true or action_on_false are executed, respectively. When
449 a prologue exists in the optional hash at end, it will be favored over
450 "default includes" (represented by "_default_includes"). If any of
451 action_on_cache_true, action_on_cache_false is defined, both callbacks
452 are passed to "check_cached" as action_on_true or action_on_false to
453 "check_cached", respectively.
454 check_sizeof_types( type, \%options? )
456 For each type check_sizeof_type is called to check for size of type.
457 If action-if-found is given, it is additionally executed when all of
459 the sizes of the types could determined. If action-if-not-found is
460 given, it is executed when one size of the types could not determined.
461 If the very last parameter contains a hash reference, "CODE" references
463 to action_on_true or action_on_false are executed, respectively. When
464 a prologue exists in the optional hash at end, it will be favored over
465 "default includes" (represented by "_default_includes"). If any of
466 action_on_cache_true, action_on_cache_false is defined, both callbacks
467 are passed to "check_cached" as action_on_true or action_on_false to
468 "check_cached", respectively. Given callbacks for action_on_size_true
469 or action_on_size_false are called for each symbol checked using
470 "check_sizeof_type" receiving the symbol as first argument.
471 check_alignof_type( type, \%options? )
473 Define ALIGNOF_type to be the alignment in bytes of type. type must be
474 valid as a structure member declaration or type must be a structure
475 member itself.
476 This method caches its result in the "ac_cv_alignof_<set lang>"_type
478 variable, with * mapped to "p" and other characters not suitable for a
479 variable name mapped to underscores.
480 If the very last parameter contains a hash reference, "CODE" references
482 to action_on_true or action_on_false are executed, respectively. When
483 a prologue exists in the optional hash at end, it will be favored over
484 "default includes" (represented by "_default_includes"). If any of
485 action_on_cache_true, action_on_cache_false is defined, both callbacks
486 are passed to "check_cached" as action_on_true or action_on_false to
487 "check_cached", respectively.
488 check_alignof_types (type, [action-if-found], [action-if-not-found],
490 [prologue = default includes])
491 For each type check_alignof_type is called to check for align of type.
492 If action-if-found is given, it is additionally executed when all of
494 the aligns of the types could determined. If action-if-not-found is
495 given, it is executed when one align of the types could not determined.
496 If the very last parameter contains a hash reference, "CODE" references
498 to action_on_true or action_on_false are executed, respectively. When
499 a prologue exists in the optional hash at end, it will be favored over
500 "default includes" (represented by "_default_includes"). If any of
501 action_on_cache_true, action_on_cache_false is defined, both callbacks
502 are passed to "check_cached" as action_on_true or action_on_false to
503 "check_cached", respectively. Given callbacks for action_on_align_true
504 or action_on_align_false are called for each symbol checked using
505 "check_alignof_type" receiving the symbol as first argument.
506 check_member( member, \%options? )
508 Check whether member is in form of aggregate.member and member is a
509 member of the aggregate aggregate.
510 which are used prior to the aggregate under test.
512 Config::AutoConf->check_member(
514 "struct STRUCT_SV.sv_refcnt",
515 {
516 action_on_false => sub { Config::AutoConf->msg_failure( "sv_refcnt member required for struct STRUCT_SV" ); },
517 prologue => "#include <EXTERN.h>\n#include <perl.h>"
518 }
519 );
520 This function will return a true value (1) if the member is found.
522 If aggregate aggregate has member member, preprocessor macro
524 HAVE_aggregate_MEMBER (in all capitals, with spaces and dots replaced
525 by underscores) is defined.
526 This macro caches its result in the "ac_cv_"aggr_member variable.
528 If the very last parameter contains a hash reference, "CODE" references
530 to action_on_true or action_on_false are executed, respectively. When
531 a prologue exists in the optional hash at end, it will be favored over
532 "default includes" (represented by "_default_includes"). If any of
533 action_on_cache_true, action_on_cache_false is defined, both callbacks
534 are passed to "check_cached" as action_on_true or action_on_false to
535 "check_cached", respectively.
536 check_members( members, \%options? )
538 For each member check_member is called to check for member of
539 aggregate.
540 This function will return a true value (1) if at least one member is
542 found.
543 If the very last parameter contains a hash reference, "CODE" references
545 to action_on_true or action_on_false are executed, respectively. When
546 a prologue exists in the optional hash at end, it will be favored over
547 "default includes" (represented by "_default_includes"). If any of
548 action_on_cache_true, action_on_cache_false is defined, both callbacks
549 are passed to "check_cached" as action_on_true or action_on_false to
550 "check_cached", respectively. Given callbacks for
551 action_on_member_true or action_on_member_false are called for each
552 symbol checked using "check_member" receiving the symbol as first
553 argument.
554 check_header( $header, \%options? )
556 This function is used to check if a specific header file is present in
557 the system: if we detect it and if we can compile anything with that
558 header included. Note that normally you want to check for a header
559 first, and then check for the corresponding library (not all at once).
560 The standard usage for this module is:
562 Config::AutoConf->check_header("ncurses.h");
564 This function will return a true value (1) on success, and a false
566 value if the header is not present or not available for common usage.
567 If the very last parameter contains a hash reference, "CODE" references
569 to action_on_true or action_on_false are executed, respectively. When
570 a prologue exists in the optional hash at end, it will be prepended to
571 the tested header. If any of action_on_cache_true,
572 action_on_cache_false is defined, both callbacks are passed to
573 "check_cached" as action_on_true or action_on_false to "check_cached",
574 respectively.
575 check_headers
577 This function uses check_header to check if a set of include files
578 exist in the system and can be included and compiled by the available
579 compiler. Returns the name of the first header file found.
580 Passes an optional \%options hash to each "check_header" call.
582 check_all_headers
584 This function checks each given header for usability and returns true
585 when each header can be used -- otherwise false.
586 If the very last parameter contains a hash reference, "CODE" references
588 to action_on_true or action_on_false are executed, respectively. Each
589 of existing key/value pairs using prologue, action_on_cache_true or
590 action_on_cache_false as key are passed-through to each call of
591 "check_header". Given callbacks for action_on_header_true or
592 action_on_header_false are called for each symbol checked using
593 "check_header" receiving the symbol as first argument.
594 check_stdc_headers
596 Checks for standard C89 headers, namely stdlib.h, stdarg.h, string.h
597 and float.h. If those are found, additional all remaining C89 headers
598 are checked: assert.h, ctype.h, errno.h, limits.h, locale.h, math.h,
599 setjmp.h, signal.h, stddef.h, stdio.h and time.h.
600 Returns a false value if it fails.
602 Passes an optional \%options hash to each "check_all_headers" call.
604 check_default_headers
606 This function checks for some default headers, the std c89 headers and
607 sys/types.h, sys/stat.h, memory.h, strings.h, inttypes.h, stdint.h and
608 unistd.h
609 Passes an optional \%options hash to each "check_all_headers" call.
611 check_dirent_header
613 Check for the following header files. For the first one that is found
614 and defines 'DIR', define the listed C preprocessor macro:
615 dirent.h HAVE_DIRENT_H
617 sys/ndir.h HAVE_SYS_NDIR_H
618 sys/dir.h HAVE_SYS_DIR_H
619 ndir.h HAVE_NDIR_H
620 The directory-library declarations in your source code should look
622 something like the following:
623 #include <sys/types.h>
625 #ifdef HAVE_DIRENT_H
626 # include <dirent.h>
627 # define NAMLEN(dirent) strlen ((dirent)->d_name)
628 #else
629 # define dirent direct
630 # define NAMLEN(dirent) ((dirent)->d_namlen)
631 # ifdef HAVE_SYS_NDIR_H
632 # include <sys/ndir.h>
633 # endif
634 # ifdef HAVE_SYS_DIR_H
635 # include <sys/dir.h>
636 # endif
637 # ifdef HAVE_NDIR_H
638 # include <ndir.h>
639 # endif
640 #endif
641 Using the above declarations, the program would declare variables to be
643 of type "struct dirent", not "struct direct", and would access the
644 length of a directory entry name by passing a pointer to a "struct
645 dirent" to the "NAMLEN" macro.
646 For the found header, the macro HAVE_DIRENT_IN_${header} is defined.
648 This method might be obsolescent, as all current systems with directory
650 libraries have "<dirent.h>". Programs supporting only newer OS might
651 not need to use this method.
652 If the very last parameter contains a hash reference, "CODE" references
654 to action_on_true or action_on_false are executed, respectively. Each
655 of existing key/value pairs using prologue, action_on_header_true (as
656 action_on_true having the name of the tested header as first argument)
657 or action_on_header_false (as action_on_false having the name of the
658 tested header as first argument) as key are passed-through to each call
659 of "_check_header". Given callbacks for action_on_cache_true or
660 action_on_cache_false are passed to the call of "check_cached".
661 _check_perlapi_program
663 This method provides the program source which is suitable to do basic
664 compile/link tests to prove perl development environment.
665 _check_compile_perlapi
667 This method can be used from other checks to prove whether we have a
668 perl development environment or not (perl.h, reasonable basic checks -
669 types, etc.)
670 check_compile_perlapi
672 This method can be used from other checks to prove whether we have a
673 perl development environment or not (perl.h, reasonable basic checks -
674 types, etc.)
675 check_compile_perlapi_or_die
677 Dies when not being able to compile using the Perl API
678 check_linkable_xs_so
680 Checks whether a dynamic loadable object containing an XS module can be
681 linked or not. Due the nature of the beast, this test currently always
682 succeed.
683 check_linkable_xs_so_or_die
685 Dies when "check_linkable_xs_so" fails.
686 check_loadable_xs_so
688 Checks whether a dynamic loadable object containing an XS module can be
689 loaded or not. Due the nature of the beast, this test currently always
690 succeed.
691 check_loadable_xs_so_or_die
693 Dies when "check_loadable_xs_so" fails.
694 _check_link_perlapi
696 This method can be used from other checks to prove whether we have a
697 perl development environment including a suitable libperl or not
698 (perl.h, reasonable basic checks - types, etc.)
699 Caller must ensure that the linker flags are set appropriate ("-lperl"
701 or similar).
702 check_link_perlapi
704 This method can be used from other checks to prove whether we have a
705 perl development environment or not (perl.h, libperl.la, reasonable
706 basic checks - types, etc.)
707 check_lib( lib, func, @other-libs?, \%options? )
709 This function is used to check if a specific library includes some
710 function. Call it with the library name (without the lib portion), and
711 the name of the function you want to test:
712 Config::AutoConf->check_lib("z", "gzopen");
714 It returns 1 if the function exist, 0 otherwise.
716 In case of function found, the HAVE_LIBlibrary (all in capitals)
718 preprocessor macro is defined with 1 and $lib together with @other_libs
719 are added to the list of libraries to link with.
720 If linking with library results in unresolved symbols that would be
722 resolved by linking with additional libraries, give those libraries as
723 the other-libs argument: e.g., "[qw(Xt X11)]". Otherwise, this routine
724 may fail to detect that library is present, because linking the test
725 program can fail with unresolved symbols. The other-libraries argument
726 should be limited to cases where it is desirable to test for one
727 library in the presence of another that is not already in LIBS.
728 This method caches its result in the "ac_cv_lib_"lib_func variable.
730 If the very last parameter contains a hash reference, "CODE" references
732 to action_on_true or action_on_false are executed, respectively. If
733 any of action_on_cache_true, action_on_cache_false is defined, both
734 callbacks are passed to "check_cached" as action_on_true or
735 action_on_false to "check_cached", respectively.
736 It's recommended to use search_libs instead of check_lib these days.
738 search_libs( function, search-libs, @other-libs?, @extra_link_flags?,
740 \%options? )
741 Config::AutoConf->search_libs("gethostent", "nsl", [qw(socket net)], {
742 action_on_true => sub { ... }
743 });
744 Config::AutoConf->search_libs("log4cplus_initialize", ["log4cplus"],
745 [[qw(stdc++)], [qw(stdc++ unwind)]],
746 [qw(-pthread -thread)]
747 );
748 Search for a library defining function if it's not already available.
750 This equates to calling
751 Config::AutoConf->link_if_else(
753 Config::AutoConf->lang_call( "", "$function" ) );
754 first with no libraries, then for each library listed in search-libs.
756 search-libs must be specified as an array reference to avoid confusion
757 in argument order.
758 Prepend -llibrary to LIBS for the first library found to contain
760 function.
761 If linking with library results in unresolved symbols that would be
763 resolved by linking with additional libraries, give those libraries as
764 the other-libraries argument: e.g., "[qw(Xt X11)]" or "[qw(intl),
765 qw(intl iconv)]". Otherwise, this method fails to detect that function
766 is present, because linking the test program always fails with
767 unresolved symbols.
768 The result of this test is cached in the ac_cv_search_function variable
770 as "none required" if function is already available, as 0 if no library
771 containing function was found, otherwise as the -llibrary option that
772 needs to be prepended to LIBS.
773 If the very last parameter contains a hash reference, "CODE" references
775 to action_on_true or action_on_false are executed, respectively. If
776 any of action_on_cache_true, action_on_cache_false is defined, both
777 callbacks are passed to "check_cached" as action_on_true or
778 action_on_false to "check_cached", respectively. Given callbacks for
779 action_on_lib_true or action_on_lib_false are called for each library
780 checked using "link_if_else" receiving the library as first argument
781 and all @other_libs subsequently.
782 check_lm( \%options? )
784 This method is used to check if some common "math.h" functions are
785 available, and if "-lm" is needed. Returns the empty string if no
786 library is needed, or the "-lm" string if libm is needed.
787 If the very last parameter contains a hash reference, "CODE" references
789 to action_on_true or action_on_false are executed, respectively. Each
790 of existing key/value pairs using action_on_func_true (as
791 action_on_true having the name of the tested functions as first
792 argument), action_on_func_false (as action_on_false having the name of
793 the tested functions as first argument), action_on_func_lib_true (as
794 action_on_lib_true having the name of the tested functions as first
795 argument), action_on_func_lib_false (as action_on_lib_false having the
796 name of the tested functions as first argument) as key are passed-
797 through to each call of "search_libs". Given callbacks for
798 action_on_lib_true, action_on_lib_false, action_on_cache_true or
799 action_on_cache_false are passed to the call of "search_libs".
800 Note that action_on_lib_true and action_on_func_lib_true or
802 action_on_lib_false and action_on_func_lib_false cannot be used at the
803 same time, respectively.
804 pkg_config_package_flags($package, \%options?)
806 use Config::AutoConf
807 my $c = Config::AutoConf->new;
809 $c->pkg_config_package_flags('log4cplus');
810 WriteMakefile(
811 ...
812 INC => $c->_get_extra_compiler_flags,
813 LIBS => $c->_get_extra_linker_flags,
814 );
815 Search for "pkg-config" flags for package as specified. The flags which
817 are extracted are "--cflags" and "--libs". The extracted flags are
818 appended to the global "extra_preprocess_flags", "extra_link_flags" or
819 "extra_libs", respectively. Distinguishing between "extra_link_flags"
820 and "extra_libs" is essential to avoid conflicts with search_libs
821 function and family. In case, no package configuration matching given
822 criteria could be found, return a "false" value (0).
823 The "pkg-config" flags are taken from environment variables
825 "${package}_CFLAGS" or "${package}_LIBS" when defined, respectively.
826 It will be a nice touch to document the particular environment
827 variables for your build procedure - as for above example it should be
828 $ env log4cplus_CFLAGS="-I/opt/coolapp/include" \
830 log4cplus_LIBS="-L/opt/coolapp/lib -Wl,-R/opt/coolapp/lib -llog4cplus" \
831 perl Makefile.PL
832 Call "pkg_config_package_flags" with the package you're looking for and
834 optional callback whether found or not.
835 To support stage compiling properly ("rpath" vs. library file
837 location), the internal representation is a moving target. Do not use
838 the result directly - the getters _get_extra_compiler_flags and
839 _get_extra_linker_flags are strongly encouraged. In case this is not
840 possible, please open a ticket to get informed on invasive changes.
841 If the very last parameter contains a hash reference, "CODE" references
843 to action_on_true or action_on_false are executed, respectively. If
844 any of action_on_cache_true, action_on_cache_false is defined, both
845 callbacks are passed to "check_cached" as action_on_true or
846 action_on_false to "check_cached", respectively.
847 _check_mm_pureperl_build_wanted
849 This method proves the "_argv" attribute and (when set) the
850 "PERL_MM_OPT" whether they contain PUREPERL_ONLY=(0|1) or not. The
851 attribute "_force_xs" is set as appropriate, which allows a compile
852 test to bail out when "Makefile.PL" is called with PUREPERL_ONLY=0.
853 _check_mb_pureperl_build_wanted
855 This method proves the "_argv" attribute and (when set) the
856 "PERL_MB_OPT" whether they contain --pureperl-only or not.
857 _check_pureperl_required
859 This method calls "_check_mm_pureperl_build_wanted" when running under
860 ExtUtils::MakeMaker ("Makefile.PL") or
861 "_check_mb_pureperl_build_wanted" when running under a "Build.PL"
862 (Module::Build compatible) environment.
863 When neither is found ($0 contains neither "Makefile.PL" nor
865 "Build.PL"), simply 0 is returned.
866 check_pureperl_required
868 This check method proves whether a pure perl build is wanted or not by
869 cached-checking "$self->_check_pureperl_required".
870 check_produce_xs_build
872 This routine checks whether XS can be produced. Therefore it does
873 following checks in given order:
874 · check pure perl environment variables ("check_pureperl_required")
876 or command line arguments and return false when pure perl is
877 requested
878 · check whether a compiler is available ("check_valid_compilers") and
880 return false if none found
881 · check whether a test program accessing Perl API can be compiled and
883 die with error if not
884 When all checks passed successfully, return a true value.
886 If the very last parameter contains a hash reference, "CODE" references
888 to action_on_true or action_on_false are executed, respectively.
889 check_produce_loadable_xs_build
891 This routine proves whether XS should be built and it's possible to
892 create a dynamic linked object which can be loaded using Perl's
893 Dynaloader.
894 The extension over "check_produce_xs_build" can be avoided by adding
896 the "notest_loadable_xs" to $ENV{PERL5_AC_OPTS}.
897 If the very last parameter contains a hash reference, "CODE" references
899 to action_on_true or action_on_false are executed, respectively.
900 _set_argv
902 Intended to act as a helper for evaluating given command line
903 arguments. Stores given arguments in instances "_argv" attribute.
904 Call once at very begin of "Makefile.PL" or "Build.PL":
906 Your::Pkg::Config::AutoConf->_set_args(@ARGV);
908 _default_includes
910 returns a string containing default includes for program prologue taken
911 from "autoconf/headers.m4":
912 #include <stdio.h>
914 #ifdef HAVE_SYS_TYPES_H
915 # include <sys/types.h>
916 #endif
917 #ifdef HAVE_SYS_STAT_H
918 # include <sys/stat.h>
919 #endif
920 #ifdef STDC_HEADERS
921 # include <stdlib.h>
922 # include <stddef.h>
923 #else
924 # ifdef HAVE_STDLIB_H
925 # include <stdlib.h>
926 # endif
927 #endif
928 #ifdef HAVE_STRING_H
929 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
930 # include <memory.h>
931 # endif
932 # include <string.h>
933 #endif
934 #ifdef HAVE_STRINGS_H
935 # include <strings.h>
936 #endif
937 #ifdef HAVE_INTTYPES_H
938 # include <inttypes.h>
939 #endif
940 #ifdef HAVE_STDINT_H
941 # include <stdint.h>
942 #endif
943 #ifdef HAVE_UNISTD_H
944 # include <unistd.h>
945 #endif
946 _default_includes_with_perl
948 returns a string containing default includes for program prologue
949 containing _default_includes plus
950 #include <EXTERN.h>
952 #include <perl.h>
953 add_log_fh
955 Push new file handles at end of log-handles to allow tee'ing log-output
956 delete_log_fh
958 Removes specified log file handles. This method allows you to shoot
959 yourself in the foot - it doesn't prove whether the primary nor the
960 last handle is removed. Use with caution.
961 _get_extra_compiler_flags
963 Returns the determined flags required to run the compile stage as
964 string
965 _get_extra_linker_flags
967 Returns the determined flags required to run the link stage as string
968
970 Alberto Simões, "<ambs@cpan.org>"
971 Jens Rehsack, "<rehsack@cpan.org>"
973
975 Although a lot of work needs to be done, these are the next steps I
976 intend to take.
977 - detect flex/lex
979 - detect yacc/bison/byacc
980 - detect ranlib (not sure about its importance)
981 These are the ones I think not too much important, and will be
983 addressed later, or by request.
984 - detect an 'install' command
986 - detect a 'ln -s' command -- there should be a module doing
987 this kind of task.
988
990 A lot. Portability is a pain. <Patches welcome!>.
991 Please report any bugs or feature requests to
993 "bug-Config-AutoConf@rt.cpan.org", or through the web interface at
994 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-AutoConf>. We will be
995 notified, and then you'll automatically be notified of progress on your
996 bug as we make changes.
997
999 You can find documentation for this module with the perldoc command.
1000 perldoc Config::AutoConf
1002 You can also look for information at:
1004 · AnnoCPAN: Annotated CPAN documentation
1006 <http://annocpan.org/dist/Config-AutoConf>
1008 · CPAN Ratings
1010 <http://cpanratings.perl.org/dist/Config-AutoConf>
1012 · MetaCPAN
1014 <https://metacpan.org/release/Config-AutoConf>
1016 · Git Repository
1018 <https://github.com/ambs/Config-AutoConf>
1020
1022 Michael Schwern for kind MacOS X help.
1023 Ken Williams for ExtUtils::CBuilder
1025 Peter Rabbitson for help on refactoring and making the API more
1027 Perl'ish
1028
1030 Copyright 2004-2020 by the Authors
1031 This program is free software; you can redistribute it and/or modify it
1033 under the same terms as Perl itself.
1034
1036 ExtUtils::CBuilder(3)
1037perl v5.32.0 2021-01-12 Config::AutoConf(3)