Autoconfiguration functions and variables

Jump to: |  | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: |  | All • Variables • Functions • Objects • Targets • Options

# 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.14 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.7) 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.

Jump to: |  | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: |  | All • Variables • Functions • Objects • Targets • Options