NAME
Configure.pm - provide auto-configuration utilities
SUMMARY
This perl module provides tools to figure out what is present in the C compilation environment. This is intended mostly for perl extensions to use to configure themselves. There are a number of functions, with widely varying levels of specificity, so here is a summary of what the functions can do:
CheckHeader: Look for headers.
CheckStructure: Look for a structure.
CheckField: Look for a field in a structure.
CheckHSymbol: Look for a symbol in a header.
CheckLSymbol: Look for a symbol in a library.
CheckSymbol: Look for a symbol in a header and library.
GetTextSymbol: Get the contents of a symbol as text.
GetNumericSymbol: Get the contents of a symbol as a number.
Apply: Try compiling code with a set of headers and libs.
ApplyHeaders: Try compiling code with a set of headers.
ApplyLibraries: Try linking code with a set of libraries.
ApplyHeadersAndLibaries: You get the idea.
ApplyHeadersAndLibariesAnExecute: You get the idea.
CPP: Feed some code through the C preproccessor.
Compile: Try to compile some C code.
Link: Try to compile & link some C code.
Execute: Try to compile, link, & execute some C code.
FUNCTIONS
CPP
Takes one or more arguments. The first is a string containing a C program. Embedded newlines are legal, the text simply being stuffed into a temporary file. The result is then fed to the C preproccessor (that preproccessor being previously determined by perl's Configure script.) Any additional arguments provided are passed to the preprocessing command.
In a scalar context, the return value is either undef, if something went wrong, or the text returned by the preprocessor. In an array context, two values are returned: the numeric exit status and the output of the preproccessor.
Compile
Takes one or more arguments. The first is a string containing a C program. Embedded newlines are legal, the text simply being stuffed into a temporary file. The result is then fed to the C compiler (that compiler being previously determined by perl's Configure script.) Any additional arguments provided are passed to the compiler command.
In a scalar context, either 0 or 1 will be returned, with 1 indicating a successful compilation. In an array context, three values are returned: the numeric exit status of the compiler, a string consisting of the output generated by the compiler, and a numeric value that is false if a ".o" file wasn't produced by the compiler, error status or no.
Link
Takes one or more arguments. The first is a string containing a C program. Embedded newlines are legal, the text simply being stuffed into a temporary file. The result is then fed to the C compiler and linker (that compiler and linker being previously determined by perl's Configure script.) Any additional arguments provided are passed to the compilation/link command.
In a scalar context, either 0 or 1 is returned, with 1 indicating a successful compilation. In an array context, two values are returned: the numeric exit status of the compiler/linker, and a string consisting of the output generated by the compiler/linker.
Note that this command only compiles and links the C code. It does not attempt to execute it.
Execute
Takes one or more arguments. The first is a string containing a C program. Embedded newlines are legal, the text simply being stuffed into a temporary file. The result is then fed to the C compiler and linker (that compiler and linker being previously determined by perl's metaconfig script.) and then executed. Any additional arguments provided are passed to the compilation/link command. (There is no way to feed arguments to the program being executed.)
In a scalar context, the return value is either undef, indicating the compilation or link failed, or that the executed program returned a nonzero status. Otherwise, the return value is the text output by the program.
In an array context, an array consisting of three values is returned: the first value is 0 or 1, 1 if the compile/link succeeded. The second value either the exist status of the compiler or program, and the third is the output text.
FindHeader
Takes an unlimited number of arguments, consisting of both header names in the form "header.h", or directory specifications such as "-I/usr/include/bsd". For each supplied header, FindHeader will attempt to find the complete path. The return value is an array consisting of all the headers that were located.
FindLib
Takes an unlimited number of arguments, consisting of both library names in the form "-llibname", "/usr/lib/libxyz.a" or "dld", or directory specifications such as "-L/usr/lib/foo". For each supplied library, FindLib will attempt to find the complete path. The return value is an array consisting of the full paths to all of the libraries that were located.
Apply takes a chunk of code, a series of libraries and headers, and attempts to apply them, in series, to a given perl command. In a scalar context, the return value of the first set of headers and libraries that produces a non-zero return value from the command is returned. In an array context, the header and library set it returned.
This is best explained by some examples:
Apply(\&Compile,"main(){}","sgtty.h",""); In a scalar context either undef or 1. In an array context, this returns () or ("sgtty.h","").
Apply(\&Link,"main(){int i=COLOR_PAIRS;}","curses.h","-lcurses",
"ncurses.h","-lncurses","ncurses/ncurses.h","-lncurses");In a scalar context, this returns either undef, 1. In an array context, this returns ("curses.h","-lcurses"), ("ncurses.h","-lncurses"), ("ncurses/ncurses.h","-lncurses"), or ().
If we had instead said Apply(\&Execute,'main(){printf("%d",(int)COLOR_PAIRS)',...) then in a scalar context either undef or the value of COLOR_PAIRS would be returned.
Note that you can also supply multiple headers and/or libraries at one time, like this:
Apply(\&Compile,"main(){fcntl(0,F_GETFD);}","fcntl.h","",
"ioctl.h fcntl.h","","sys/ioctl.h fcntl.h"","");So if fcntl needs ioctl or sys/ioctl loaded first, this will catch it. In an array context, (), ("fcntl.h",""), ("ioctl.h fcntl.h",""), or ("sys/ioctl.h fcntl.h","") could be returned.
You can also use nested arrays to get exactly the same effect. The returned array will always consist of a string, though, with elements separated by spaces.
Apply(\&Compile,"main(){fcntl(0,F_GETFD);}",["fcntl.h"],"",
["ioctl.h","fcntl.h"],"",["sys/ioctl.h","fcntl.h"],"");Note that there are many functions that provide simpler ways of doing these things, from GetNumericSymbol to get the value of a symbol, to ApplyHeaders which doesn't ask for libraries.
ApplyHeadersAndLibs
This function takes the same sort of arguments as Apply, it just sends them directly to Link.
ApplyHeadersAndLibsAndExecute
This function is similar to Apply and ApplyHeadersAndLibs, but it always uses Execute.
ApplyHeaders
If you are only checking headers, and don't need to look at libs, then you will probably want to use ApplyHeaders. The return value is the same in a scalar context, but in an array context the returned array will only consists of the headers, spread out.
ApplyLibs
If you are only checking libraries, and don't need to look at headers, then you will probably want to use ApplyLibs. The return value is the same in a scalar context, but in an array context the returned array will only consists of the libraries, spread out.
CheckHeader
Takes an unlimited number of arguments, consiting of headers in the Apply style. The first set that is fully accepted by the compiler is returned.
CheckStructure
Takes the name of a structure, and an unlimited number of further arguments consisting of header groups. The first group that defines that structure properly will be returned. undef will be returned if nothing succeeds.
CheckField
Takes the name of a structure, the name of a field, and an unlimited number of further arguments consisting of header groups. The first group that defines a structure that contains the field will be returned. undef will be returned if nothing succeeds.
CheckLSymbol
Takes the name of a symbol, and an unlimited number of further arguments consisting of library groups. The first group of libraries that defines that symbol will be returned. undef will be returned if nothing succeeds.
CheckSymbol
Takes the name of a symbol, and an unlimited number of further arguments consisting of header and library groups, in the Apply format. The first group of headers and libraries that defines that symbol will be returned. undef will be returned if nothing succeeds.
CheckHSymbol
Takes the name of a symbol, and an unlimited number of further arguments consisting of header groups. The first group of headers that defines that symbol will be returned. undef will be returned if nothing succeeds.
CheckHPrototype (unexported)
An experimental routine that takes a name of a function, a nested array consisting of the prototype, and then the normal header groups. It attempts to deduce whether the given prototype matches what the header supplies. Basically, it doesn't work. Or maybe it does. I wouldn't reccomend it, though.
GetSymbol
Takes the name of a symbol, a printf command, a cast, and an unlimited number of further arguments consisting of header and library groups, in the Apply. The first group of headers and libraries that defines that symbol will be used to get the contents of the symbol in the format, and return it. undef will be returned if nothing defines that symbol.
Example:
GetSymbol("__LINE__","ld","long","","");GetTextSymbol
Takes the name of a symbol, and an unlimited number of further arguments consisting of header and library groups, in the ApplyHeadersAndLibs format. The first group of headers and libraries that defines that symbol will be used to get the contents of the symbol in text format, and return it. undef will be returned if nothing defines that symbol.
Note that the symbol must actually be text, either a char* or a constant string. Otherwise, the results are undefined.
GetNumericSymbol
Takes the name of a symbol, and an unlimited number of further arguments consisting of header and library groups, in the ApplyHeadersAndLibs format. The first group of headers and libraries that defines that symbol will be used to get the contents of the symbol in numeric format, and return it. undef will be returned if nothing defines that symbol.
Note that the symbol must actually be numeric, in a format compatible with a float. Otherwise, the results are undefined.
GetConstants
Takes a list of header names (possibly including -I directives) and attempts to grep the specified files for constants, a constant being something #defined with a name that matches /[A-Z0-9_]+/. Returns the list of names.
DeducePrototype (unexported)
This one is really experimental. The idea is to figure out some basic characteristics of the compiler, and then attempt to "feel out" the prototype of a function. Eventually, it may work. It is guaranteed to be very slow, and it may simply not be capable of working on some systems.