Chapter 14  Autoconfiguration functions and variables

• General-purpose autoconfiguration functions
• Translating autoconf scripts
• Predefined configuration tests

OMake standard library provides a number of functions and variables intended to help one write build specifications that need to be capable of autoconfiguring itself to adjust to different build environments.

14.1  General-purpose autoconfiguration functions

The following general-purpose functions can be used to discover the properties of your build environment in a fashion similar to the one used by GNU autoconf tool you may be familiar with. It is recommended that these function be used from an appropriate static. block (see Section 4.15 for more information).

In order to use the following general-purpose functions, you need to have the line

open configure/Configure

included in your OMakefile or OMakeroot.

14.1.1  ConfMsgChecking, ConfMsgResult

ConfMsgChecking(<msg>)
...
ConfMsgResult(<msg>)

The ConfMsgChecking function output message of the form --- Checking <msg>... without any trailing newline. After the test advertized by ConfMsgChecking is performed, the ConfMsgResult function should be used to output the result.

In certain cases users may want to redefine these function — for example, to use a different output formatting and/or to copy the messages to a log file.

Example:

static. =
   ConfMsgChecking(which foo to use)
   foo = ...
   ConfMsgResult($(foo))

14.1.2  ConfMsgWarn, ConfMsgError

ConfMsgWarn(<msg>)
ConfMsgError(<msg>)

Print a warning or an error message respectively. ConfMsgError would then abort OMake.

14.1.3  ConfMsgYesNo, ConfMsgFound

flag = $(ConfMsgYesNo <bool expr>
flag = $(ConfMsgFound <bool expr>

The ConfMsgFound function expects to receive a boolean flag describing whether a test previously announced using the ConfMsgChecking function found what it was looking for. ConfMsgFound will output the appropriate result (“found” or “NOT found”) using the ConfMsgResult function and return its argument back.

The ConfMsgYesNo function is similar, outputting a simple (“yes” or “NO”).

14.1.4  TryCompileC, TryLinkC, TryRunC

success = $(TryCompileC <prog_text>)
success = $(TryLinkC <prog_text>)
success = $(TryRunC <prog_text>)

Given the text of a C program, the TryCompileC, TryLinkC, and TryRunC functions would try to compile / compile and link / compile, link, and run, the given program and return a boolean flag indicating whether the attempt was successful.

TryCompileC will use the CC, CFLAGS and INCLUDES variables to run the C compiler. TryLinkC and TryRunC will also use the LDFLAGS variable to run the C compiler and linker. However, the flags like /WX, -Werror and -warn-error will be not be passed to the compiler, even if they occur in CFLAGS.

These functions are silent and should normally be used with an appropriate ConfMsgChecking … ConfMsgResult.

14.1.5  RunCProg

output = $(RunCProg <prog>)

RunCProg is similar to the RunCProg function, except that it returns the output of the function (will return false if the program fails to compile or run).

14.1.6  CheckCHeader, VerboseCheckCHeader

success = $(CheckCHeader <files>)
success = $(VerboseCheckCHeader <files>)

Use the TryCompileC function to check whether your C compiler can locate and process the specified headers files. Will incude <stdio.h> before including the header files.

Both functions return a boolean value. The CheckCHeader function is silent; the VerboseCheckCHeader function will use the ConfMsgChecking and ConfMsgResult functions to describe the test and the outcome.

Example:

static. =
   NCURSES_H_AVAILABLE = $(VerboseCheckCHeader ncurses.h)

14.1.7  CheckCLib, VerboseCheckCLib

success = $(CheckCLib <libs>, <functions>)
success = $(VerboseCheckCLib <libs>, <functions>)

Use the TryLinkC function to check whether your C compiler and linker can find the named functions when linking with the named libraries. Will pass the <libs> to the compiler using the -l flag.

Both functions return a boolean value. The CheckCLib function is silent; the VerboseCheckCHeader function will use the ConfMsgChecking and ConfMsgResult functions to describe the test and the outcome.

Example:

static. =
    NCURSES_LIB_AVAILABLE = $(VerboseCheckCLib ncurses, initscr setupterm tigetstr)

14.1.8  CheckProg

success = $(CheckProg <prog>)

Checks whether the program <prog> exists in your path. Will use the ConfMsgChecking and ConfMsgResult functions to describe the test and the outcome.

14.2  Translating autoconf scripts

Some of the functions described above are very similar to the ones present in autoconf. Below is a brief translation table for such functions.

AC_MSG_CHECKING is very similar to ConfMsgChecking function.

AC_MSG_RESULT is very similar to ConfMsgResult function.

AC_MSG_WARN is very similar to ConfMsgWarn function.

AC_MSG_ERROR is very similar to ConfMsgError function.

AC_TRY_COMPILE is somewhat similar to TryCompileC function, except the TryCompileC function returns a boolean value and only works for C. Similarly,

AC_TRY_LINK is approximated by TryLinkC function, and

AC_TRY_RUN is approximated by TryRunC function.

14.3  Predefined configuration tests

A number of configuration tests are already included in the standard library. In order to use them in your project, simply open (see Section 4.8) the corresponding build file in your OMakefile and the tests will run the first time OMake is executed. Note that it is not a problem to open these files from more than one place in your project — if you do that, the test will still run only once.

14.3.1  NCurses library configuration

Add open configure/ncurses line to your OMakefile to get access to the following autoconfiguration variables.

NCURSES_AVAILABLE

A boolean flag that would be set when both the curses.h header, the term.h header, and the ncurses library very found.

NCURSES_TERMH_IN_NCURSES

A boolean flag that would be set when term.h has to be included as <ncurses/term.h> instead of <term.h>.

NCURSES_CFLAGS

The CFLAGS to use when compiling ncurses code. Will include -DNCURSES and -DTERMH_IN_NCURSES, respectively when NCURSES_AVAILABLE and NCURSES_TERMH_IN_NCURSES are true.

NCURSES_CLIBS

The LDFLAGS to use when linking ncurses code. Will normally contain -lncurses when ncurses is found and remain empty otherwise.

14.3.2  ReadLine library configuration

Add open configure/readline line to your OMakefile to get access to the following autoconfiguration variables.

READLINE_AVAILABLE

A boolean flag that would be set when both the readline/readline.h header, the readline/history.h header, and the readline library very found.

READLINE_GNU

A boolean flag that would be set when the GNU version of the readline library is found (as opposed to the BSD one).

READLINE_CFLAGS

The CFLAGS to use when compiling readline code. Will include -DREADLINE_ENABLED and -DREADLINE_GNU, respectively when READLINE_AVAILABLE and READLINE_GNU are true.

READLINE_CLIBS

The LDFLAGS to use when linking readline code. Will normally contain -lncurses -lreadline when readline is found and remain empty otherwise.

14.3.3  Snprintf configuration

Add open configure/snprintf line to your OMakefile to get access to the following autoconfiguration variables.

SNPRINTF_AVAILABLE

A boolean flag telling whether the snprintf function is available in the standard C library.