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?, \%options? )
740 Search for a library defining function if it's not already available.
741 This equates to calling
742 Config::AutoConf->link_if_else(
744 Config::AutoConf->lang_call( "", "$function" ) );
745 first with no libraries, then for each library listed in search-libs.
747 search-libs must be specified as an array reference to avoid confusion
748 in argument order.
749 Prepend -llibrary to LIBS for the first library found to contain
751 function.
752 If linking with library results in unresolved symbols that would be
754 resolved by linking with additional libraries, give those libraries as
755 the other-libraries argument: e.g., "[qw(Xt X11)]" or "[qw(intl),
756 qw(intl iconv)]". Otherwise, this method fails to detect that function
757 is present, because linking the test program always fails with
758 unresolved symbols.
759 The result of this test is cached in the ac_cv_search_function variable
761 as "none required" if function is already available, as 0 if no library
762 containing function was found, otherwise as the -llibrary option that
763 needs to be prepended to LIBS.
764 If the very last parameter contains a hash reference, "CODE" references
766 to action_on_true or action_on_false are executed, respectively. If
767 any of action_on_cache_true, action_on_cache_false is defined, both
768 callbacks are passed to "check_cached" as action_on_true or
769 action_on_false to "check_cached", respectively. Given callbacks for
770 action_on_lib_true or action_on_lib_false are called for each library
771 checked using "link_if_else" receiving the library as first argument
772 and all @other_libs subsequently.
773 check_lm( \%options? )
775 This method is used to check if some common "math.h" functions are
776 available, and if "-lm" is needed. Returns the empty string if no
777 library is needed, or the "-lm" string if libm is needed.
778 If the very last parameter contains a hash reference, "CODE" references
780 to action_on_true or action_on_false are executed, respectively. Each
781 of existing key/value pairs using action_on_func_true (as
782 action_on_true having the name of the tested functions as first
783 argument), action_on_func_false (as action_on_false having the name of
784 the tested functions as first argument), action_on_func_lib_true (as
785 action_on_lib_true having the name of the tested functions as first
786 argument), action_on_func_lib_false (as action_on_lib_false having the
787 name of the tested functions as first argument) as key are passed-
788 through to each call of "search_libs". Given callbacks for
789 action_on_lib_true, action_on_lib_false, action_on_cache_true or
790 action_on_cache_false are passed to the call of "search_libs".
791 Note that action_on_lib_true and action_on_func_lib_true or
793 action_on_lib_false and action_on_func_lib_false cannot be used at the
794 same time, respectively.
795 pkg_config_package_flags($package, \%options?)
797 use Config::AutoConf
798 my $c = Config::AutoConf->new;
800 $c->pkg_config_package_flags('log4cplus');
801 WriteMakefile(
802 ...
803 INC => $c->_get_extra_compiler_flags,
804 LIBS => $c->_get_extra_linker_flags,
805 );
806 Search for "pkg-config" flags for package as specified. The flags which
808 are extracted are "--cflags" and "--libs". The extracted flags are
809 appended to the global "extra_preprocess_flags", "extra_link_flags" or
810 "extra_libs", respectively. Distinguishing between "extra_link_flags"
811 and "extra_libs" is essential to avoid conflicts with search_libs
812 function and family. In case, no package configuration matching given
813 criteria could be found, return a "false" value (0).
814 The "pkg-config" flags are taken from environment variables
816 "${package}_CFLAGS" or "${package}_LIBS" when defined, respectively.
817 It will be a nice touch to document the particular environment
818 variables for your build procedure - as for above example it should be
819 $ env log4cplus_CFLAGS="-I/opt/coolapp/include" \
821 log4cplus_LIBS="-L/opt/coolapp/lib -Wl,-R/opt/coolapp/lib -llog4cplus" \
822 perl Makefile.PL
823 Call "pkg_config_package_flags" with the package you're looking for and
825 optional callback whether found or not.
826 To support stage compiling properly ("rpath" vs. library file
828 location), the internal representation is a moving target. Do not use
829 the result directly - the getters _get_extra_compiler_flags and
830 _get_extra_linker_flags are strongly encouraged. In case this is not
831 possible, please open a ticket to get informed on invasive changes.
832 If the very last parameter contains a hash reference, "CODE" references
834 to action_on_true or action_on_false are executed, respectively. If
835 any of action_on_cache_true, action_on_cache_false is defined, both
836 callbacks are passed to "check_cached" as action_on_true or
837 action_on_false to "check_cached", respectively.
838 _check_mm_pureperl_build_wanted
840 This method proves the "_argv" attribute and (when set) the
841 "PERL_MM_OPT" whether they contain PUREPERL_ONLY=(0|1) or not. The
842 attribute "_force_xs" is set as appropriate, which allows a compile
843 test to bail out when "Makefile.PL" is called with PUREPERL_ONLY=0.
844 _check_mb_pureperl_build_wanted
846 This method proves the "_argv" attribute and (when set) the
847 "PERL_MB_OPT" whether they contain --pureperl-only or not.
848 _check_pureperl_required
850 This method calls "_check_mm_pureperl_build_wanted" when running under
851 ExtUtils::MakeMaker ("Makefile.PL") or
852 "_check_mb_pureperl_build_wanted" when running under a "Build.PL"
853 (Module::Build compatible) environment.
854 When neither is found ($0 contains neither "Makefile.PL" nor
856 "Build.PL"), simply 0 is returned.
857 check_pureperl_required
859 This check method proves whether a pure perl build is wanted or not by
860 cached-checking "$self->_check_pureperl_required".
861 check_produce_xs_build
863 This routine checks whether XS can be produced. Therefore it does
864 following checks in given order:
865 · check pure perl environment variables ("check_pureperl_required")
867 or command line arguments and return false when pure perl is
868 requested
869 · check whether a compiler is available ("check_valid_compilers") and
871 return false if none found
872 · check whether a test program accessing Perl API can be compiled and
874 die with error if not
875 When all checks passed successfully, return a true value.
877 If the very last parameter contains a hash reference, "CODE" references
879 to action_on_true or action_on_false are executed, respectively.
880 check_produce_loadable_xs_build
882 This routine proves whether XS should be built and it's possible to
883 create a dynamic linked object which can be loaded using Perl's
884 Dynaloader.
885 The extension over "check_produce_xs_build" can be avoided by adding
887 the "notest_loadable_xs" to $ENV{PERL5_AC_OPTS}.
888 If the very last parameter contains a hash reference, "CODE" references
890 to action_on_true or action_on_false are executed, respectively.
891 _set_argv
893 Intended to act as a helper for evaluating given command line
894 arguments. Stores given arguments in instances "_argv" attribute.
895 Call once at very begin of "Makefile.PL" or "Build.PL":
897 Your::Pkg::Config::AutoConf->_set_args(@ARGV);
899 _default_includes
901 returns a string containing default includes for program prologue taken
902 from "autoconf/headers.m4":
903 #include <stdio.h>
905 #ifdef HAVE_SYS_TYPES_H
906 # include <sys/types.h>
907 #endif
908 #ifdef HAVE_SYS_STAT_H
909 # include <sys/stat.h>
910 #endif
911 #ifdef STDC_HEADERS
912 # include <stdlib.h>
913 # include <stddef.h>
914 #else
915 # ifdef HAVE_STDLIB_H
916 # include <stdlib.h>
917 # endif
918 #endif
919 #ifdef HAVE_STRING_H
920 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
921 # include <memory.h>
922 # endif
923 # include <string.h>
924 #endif
925 #ifdef HAVE_STRINGS_H
926 # include <strings.h>
927 #endif
928 #ifdef HAVE_INTTYPES_H
929 # include <inttypes.h>
930 #endif
931 #ifdef HAVE_STDINT_H
932 # include <stdint.h>
933 #endif
934 #ifdef HAVE_UNISTD_H
935 # include <unistd.h>
936 #endif
937 _default_includes_with_perl
939 returns a string containing default includes for program prologue
940 containing _default_includes plus
941 #include <EXTERN.h>
943 #include <perl.h>
944 add_log_fh
946 Push new file handles at end of log-handles to allow tee'ing log-output
947 delete_log_fh
949 Removes specified log file handles. This method allows you to shoot
950 yourself in the foot - it doesn't prove whether the primary nor the
951 last handle is removed. Use with caution.
952 _get_extra_compiler_flags
954 Returns the determined flags required to run the compile stage as
955 string
956 _get_extra_linker_flags
958 Returns the determined flags required to run the link stage as string
959
961 Alberto Simões, "<ambs@cpan.org>"
962 Jens Rehsack, "<rehsack@cpan.org>"
964
966 Although a lot of work needs to be done, these are the next steps I
967 intend to take.
968 - detect flex/lex
970 - detect yacc/bison/byacc
971 - detect ranlib (not sure about its importance)
972 These are the ones I think not too much important, and will be
974 addressed later, or by request.
975 - detect an 'install' command
977 - detect a 'ln -s' command -- there should be a module doing
978 this kind of task.
979
981 A lot. Portability is a pain. <Patches welcome!>.
982 Please report any bugs or feature requests to
984 "bug-Config-AutoConf@rt.cpan.org", or through the web interface at
985 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-AutoConf>. We will be
986 notified, and then you'll automatically be notified of progress on your
987 bug as we make changes.
988
990 You can find documentation for this module with the perldoc command.
991 perldoc Config::AutoConf
993 You can also look for information at:
995 · AnnoCPAN: Annotated CPAN documentation
997 <http://annocpan.org/dist/Config-AutoConf>
999 · CPAN Ratings
1001 <http://cpanratings.perl.org/dist/Config-AutoConf>
1003 · MetaCPAN
1005 <https://metacpan.org/release/Config-AutoConf>
1007 · Git Repository
1009 <https://github.com/ambs/Config-AutoConf>
1011
1013 Michael Schwern for kind MacOS X help.
1014 Ken Williams for ExtUtils::CBuilder
1016 Peter Rabbitson for help on refactoring and making the API more
1018 Perl'ish
1019
1021 Copyright 2004-2020 by the Authors
1022 This program is free software; you can redistribute it and/or modify it
1024 under the same terms as Perl itself.
1025
1027 ExtUtils::CBuilder(3)
1028perl v5.30.1 2020-01-29 Config::AutoConf(3)