1Config::AutoConf(3)   User Contributed Perl Documentation  Config::AutoConf(3)
2
3
4

NAME

6       Config::AutoConf - A module to implement some of AutoConf macros in
7       pure perl.
8

ABSTRACT

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

SYNOPSIS

14           use Config::AutoConf;
15
16           Config::AutoConf->check_prog("agrep");
17           my $grep = Config::AutoConf->check_progs("agrep", "egrep", "grep");
18
19           Config::AutoConf->check_header("ncurses.h");
20           my $curses = Config::AutoConf->check_headers("ncurses.h","curses.h");
21
22           Config::AutoConf->check_prog_awk;
23           Config::AutoConf->check_prog_egrep;
24
25           Config::AutoConf->check_cc();
26
27           Config::AutoConf->check_lib("ncurses", "tgoto");
28
29           Config::AutoConf->check_file("/etc/passwd"); # -f && -r
30

DESCRIPTION

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
36       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
41       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

CONSTRUCTOR

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

METHODS

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
57   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
61   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
65       An optional array reference containing a list of directories to be
66       searched instead of $PATH is gracefully honored.
67
68       If the very last parameter contains a hash reference, "CODE" references
69       to action_on_true or action_on_false are executed, respectively.
70
71   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
75       An optional array reference containing a list of directories to be
76       searched instead of $PATH is gracefully honored.
77
78       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
83   check_prog_yacc
84       From the GNU Autoconf
85       <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
86
87         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
92       Returns the full path, if found.
93
94   check_prog_awk
95       From the GNU Autoconf
96       <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
97
98         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
104       Note that it returns the full path, if found.
105
106   check_prog_egrep
107       From the GNU Autoconf
108       <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
109
110         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
115       Note that it returns the full path, if found.
116
117   check_prog_lex
118       From the GNU Autoconf
119       <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
120
121         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
128       Note that it returns the full path, if found.
129
130       The structure $self->{lex} is set with attributes
131
132         prog => $LEX
133         lib => $LEXLIB
134         root => $lex_root
135
136   check_prog_sed
137       From the GNU Autoconf
138       <https://www.gnu.org/software/autoconf/autoconf.html> documentation,
139
140         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
145         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
148       Note that it returns the full path, if found.
149
150   check_prog_pkg_config
151       Checks for "pkg-config" program. No additional tests are made for it
152       ...
153
154   check_prog_cc
155       Determine a C compiler to use. Currently the probe is delegated to
156       ExtUtils::CBuilder.
157
158   check_cc
159       (Deprecated) Old name of "check_prog_cc".
160
161   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
166   check_valid_compilers(;\@)
167       Checks for valid compilers for each given language. When unspecified
168       defaults to "[ "C" ]".
169
170   msg_checking
171       Prints "Checking @_ ..."
172
173   msg_result
174       Prints result \n
175
176   msg_notice
177       Prints "configure: " @_ to stdout
178
179   msg_warn
180       Prints "configure: " @_ to stderr
181
182   msg_error
183       Prints "configure: " @_ to stderr and exits with exit code 0 (tells
184       toolchain to stop here and report unsupported environment)
185
186   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
192   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
196   write_config_h( [$target] )
197       Writes the defined constants into given target:
198
199         Config::AutoConf->write_config_h( "config.h" );
200
201   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
205   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
211   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
216       Typical call of
217
218         Config::AutoConf->lang_build_program( "const char hw[] = \"Hello, World\\n\";",
219                                               "fputs (hw, stdout);" )
220
221       will create
222
223         const char hw[] = "Hello, World\n";
224
225         /* Override any gcc2 internal prototype to avoid an error.  */
226         #ifdef __cplusplus
227         extern "C" {
228         #endif
229
230         int
231         main (int argc, char **argv)
232         {
233           (void)argc;
234           (void)argv;
235           fputs (hw, stdout);;
236           return 0;
237         }
238
239         #ifdef __cplusplus
240         }
241         #endif
242
243   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
247   lang_builtin( [prologue], builtin )
248       Builds program which simply proves whether a builtin is known to
249       language compiler.
250
251   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
256   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
261   push_preprocess_flags
262       Adds given flags to the parameter list for preprocessor invocation.
263
264   push_compiler_flags
265       Adds given flags to the parameter list for compiler invocation.
266
267   push_libraries
268       Adds given list of libraries to the parameter list for linker
269       invocation.
270
271   push_library_paths
272       Adds given list of library paths to the parameter list for linker
273       invocation.
274
275   push_link_flags
276       Adds given flags to the parameter list for linker invocation.
277
278   compile_if_else( $src, \%options? )
279       This function tries to compile specified code and returns a boolean
280       value containing check success state.
281
282       If the very last parameter contains a hash reference, "CODE" references
283       to action_on_true or action_on_false are executed, respectively.
284
285   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
289       If the very last parameter contains a hash reference, "CODE" references
290       to action_on_true or action_on_false are executed, respectively.
291
292   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
297       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
302   cache_val
303       This function returns the value of a previously check_cached call.
304
305   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
313         Config::AutoConf->check_decl("basename(char *)")
314
315       This method caches its result in the "ac_cv_decl_<set lang>"_symbol
316       variable.
317
318       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
326   check_decls( symbols, \%options? )
327       For each of the symbols (with optional function argument types for C++
328       overloads), run check_decl.
329
330       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
334       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
345   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
350       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
356       Returns: True if the function was found, false otherwise
357
358   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
363       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
372   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
378       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
384       Returns: True if the function was found, false otherwise
385
386   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
391       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
395       This method caches its result in the "ac_cv_type_"type variable.
396
397       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
405   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
409       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
419   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
425       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
433   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
437       In opposition to GNU AutoConf, this method can determine size of
438       structure members, e.g.
439
440         $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
444       This method caches its result in the "ac_cv_sizeof_<set lang>"_type
445       variable.
446
447       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
455   check_sizeof_types( type, \%options? )
456       For each type check_sizeof_type is called to check for size of type.
457
458       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
462       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
472   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
477       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
481       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
489   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
493       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
497       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
507   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
511       which are used prior to the aggregate under test.
512
513         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
521       This function will return a true value (1) if the member is found.
522
523       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
527       This macro caches its result in the "ac_cv_"aggr_member variable.
528
529       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
537   check_members( members, \%options? )
538       For each member check_member is called to check for member of
539       aggregate.
540
541       This function will return a true value (1) if at least one member is
542       found.
543
544       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
555   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
561       The standard usage for this module is:
562
563         Config::AutoConf->check_header("ncurses.h");
564
565       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
568       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
576   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
581       Passes an optional \%options hash to each "check_header" call.
582
583   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
587       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
595   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
601       Returns a false value if it fails.
602
603       Passes an optional \%options hash to each "check_all_headers" call.
604
605   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
610       Passes an optional \%options hash to each "check_all_headers" call.
611
612   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
616         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
621       The directory-library declarations in your source code should look
622       something like the following:
623
624         #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
642       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
647       For the found header, the macro HAVE_DIRENT_IN_${header} is defined.
648
649       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
653       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
662   _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
666   _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
671   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
676   check_compile_perlapi_or_die
677       Dies when not being able to compile using the Perl API
678
679   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
684   check_linkable_xs_so_or_die
685       Dies when "check_linkable_xs_so" fails.
686
687   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
692   check_loadable_xs_so_or_die
693       Dies when "check_loadable_xs_so" fails.
694
695   _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
700       Caller must ensure that the linker flags are set appropriate ("-lperl"
701       or similar).
702
703   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
708   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
713         Config::AutoConf->check_lib("z", "gzopen");
714
715       It returns 1 if the function exist, 0 otherwise.
716
717       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
721       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
729       This method caches its result in the "ac_cv_lib_"lib_func variable.
730
731       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
737       It's recommended to use search_libs instead of check_lib these days.
738
739   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
749       Search for a library defining function if it's not already available.
750       This equates to calling
751
752           Config::AutoConf->link_if_else(
753               Config::AutoConf->lang_call( "", "$function" ) );
754
755       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
759       Prepend -llibrary to LIBS for the first library found to contain
760       function.
761
762       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
769       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
774       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
783   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
788       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
801       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
805   pkg_config_package_flags($package, \%options?)
806         use Config::AutoConf
807
808         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
816       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
824       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
829         $ 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
833       Call "pkg_config_package_flags" with the package you're looking for and
834       optional callback whether found or not.
835
836       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
842       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
848   _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
854   _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
858   _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
864       When neither is found ($0 contains neither "Makefile.PL" nor
865       "Build.PL"), simply 0 is returned.
866
867   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
871   check_produce_xs_build
872       This routine checks whether XS can be produced. Therefore it does
873       following checks in given order:
874
875       •   check pure perl environment variables ("check_pureperl_required")
876           or command line arguments and return false when pure perl is
877           requested
878
879       •   check whether a compiler is available ("check_valid_compilers") and
880           return false if none found
881
882       •   check whether a test program accessing Perl API can be compiled and
883           die with error if not
884
885       When all checks passed successfully, return a true value.
886
887       If the very last parameter contains a hash reference, "CODE" references
888       to action_on_true or action_on_false are executed, respectively.
889
890   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
895       The extension over "check_produce_xs_build" can be avoided by adding
896       the "notest_loadable_xs" to $ENV{PERL5_AC_OPTS}.
897
898       If the very last parameter contains a hash reference, "CODE" references
899       to action_on_true or action_on_false are executed, respectively.
900
901   _set_argv
902       Intended to act as a helper for evaluating given command line
903       arguments.  Stores given arguments in instances "_argv" attribute.
904
905       Call once at very begin of "Makefile.PL" or "Build.PL":
906
907         Your::Pkg::Config::AutoConf->_set_args(@ARGV);
908
909   _default_includes
910       returns a string containing default includes for program prologue taken
911       from "autoconf/headers.m4":
912
913         #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
947   _default_includes_with_perl
948       returns a string containing default includes for program prologue
949       containing _default_includes plus
950
951         #include <EXTERN.h>
952         #include <perl.h>
953
954   add_log_fh
955       Push new file handles at end of log-handles to allow tee'ing log-output
956
957   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
962   _get_extra_compiler_flags
963       Returns the determined flags required to run the compile stage as
964       string
965
966   _get_extra_linker_flags
967       Returns the determined flags required to run the link stage as string
968

AUTHOR

970       Alberto Simões, "<ambs@cpan.org>"
971
972       Jens Rehsack, "<rehsack@cpan.org>"
973

NEXT STEPS

975       Although a lot of work needs to be done, these are the next steps I
976       intend to take.
977
978         - detect flex/lex
979         - detect yacc/bison/byacc
980         - detect ranlib (not sure about its importance)
981
982       These are the ones I think not too much important, and will be
983       addressed later, or by request.
984
985         - detect an 'install' command
986         - detect a 'ln -s' command -- there should be a module doing
987           this kind of task.
988

BUGS

990       A lot. Portability is a pain. <Patches welcome!>.
991
992       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

SUPPORT

999       You can find documentation for this module with the perldoc command.
1000
1001           perldoc Config::AutoConf
1002
1003       You can also look for information at:
1004
1005       •   AnnoCPAN: Annotated CPAN documentation
1006
1007           <http://annocpan.org/dist/Config-AutoConf>
1008
1009       •   CPAN Ratings
1010
1011           <http://cpanratings.perl.org/dist/Config-AutoConf>
1012
1013       •   MetaCPAN
1014
1015           <https://metacpan.org/release/Config-AutoConf>
1016
1017       •   Git Repository
1018
1019           <https://github.com/ambs/Config-AutoConf>
1020

ACKNOWLEDGEMENTS

1022       Michael Schwern for kind MacOS X help.
1023
1024       Ken Williams for ExtUtils::CBuilder
1025
1026       Peter Rabbitson for help on refactoring and making the API more
1027       Perl'ish
1028
1030       Copyright 2004-2020 by the Authors
1031
1032       This program is free software; you can redistribute it and/or modify it
1033       under the same terms as Perl itself.
1034

SEE ALSO

1036       ExtUtils::CBuilder(3)
1037
1038
1039
1040perl v5.36.0                      2022-07-22               Config::AutoConf(3)
Impressum