An error message is printed whenever a fatal condition happens in the configuration script (like not finding a required library). The message can contain information about what went wrong, how to fix it, suggestions, etc. After it is shown, the script aborts the configuration process.

The bt_err function is used to output error messages. Each argument passed to it is treated as a different line, as these messages are usually too long to fit on a single line. A simple example:

bt_err "The required library foobar was not found." \
       "You can download it from http://www.foobar.org/."

A warning message is printed whenever a non-fatal strange condition happens in the configuration script. The script is not aborted after the message is printed.

The bt_warn function is used to output warning messages. Each argument passed to it is treated as a different line, as these messages are usually too long to fit on a single line. A simple example:

bt_warn "The suggested library foobar was not found." \
        "You should install it for optimal results."

A summary message is printed when the configuration finishes. It may contain useful and important information that the user should notice (like if some imporant hidden feature has been enabled or not). These messages can be defined at any point inside the configuration script, using the bt_msg_summary function. The configuration script will keep them in memory until it finishes. The function syntax is:

If the message contains variable names, it should be surrounded by single quotes. This way, they will be evaluated when the script finishes only, thus showing the real value of a variable at the end of the script. An example:

bt_msg_summary 'The installation prefix is ${BT_PREFIX}'

Note that bt_config automatically adds some summary messages for consistency across packages, like the one shown above.

A check usually prints a message when it starts, like checking for feature foobar..., and a result message when it finishes. There are two functions available to print these two types of messages.

The bt_msg_chk function is used to output a message before the check starts. It automatically adds the checking word before the given message and the ellipsis at its end.

The bt_msg_result function is used to output the result of the check.

Here is an example on how to use these two functions during a check function:

bt_msg_chk "for program foobar"
# All the stuff needed to detect the program.
# The $res variable contains the 'yes' or 'no' word depending on the result.
bt_msg_result "$res"

Any directory used to install files or where your package expects to find files should be customizable by the end user. Paths must not be hardcoded in your program (assuming you do not have a very good reason to do so), but instead use variables that contain the values selected during configuration time. You will usually want to provide defaults to these values, though.

Directory values are stored in shell variables. All of them start with the BT_DIR_ string for consistency. The rest of the variable name matches the name used as a configuration argument in the command line. For example, the directory holding example files is customized with the [--dir-examples] argument; therefore, its associated shell variable is BT_DIR_EXAMPLES. Even though, there is a minor exception to this rule: the installation prefix is stored in the BT_PREFIX variable, as it is somewhat special.

See Section 4.1.1, “Standard directories” for a complete list of standard customizable directories.

If you feel the real need to change a default value for a directory, you can do so in the initialization block, simply assigning a new value to the variable (note that this is discouraged, though, as it breaks consistency between packages).

You can also add new, non-standard customizable directories to your script, and they will be made available to the user through the command line. This is done using the bt_dir function. Its synopsis:

The function defines a new customizable directory, which can be referenced by the name given in the directory_name parameter, has a default value of default_value and an associated comment of comment. Note that the directory name omits the BT_DIR_ string.

An example: assume you need a directory to install pixmap files. You could define it with the following call:

bt_dir PIXMAPS '${BT_DIR_SHARE}/pixmaps' 'A directory holding pixmap files.'

Features allow the end user to manually select build details and characteristics during the configuration stage of a source package. These vary from forcing the package to use shared libraries to include optional support for a specific dependency (as OpenSSL).

Feature values are stored in shell variables. All of them start with the BT_FEATURE_ string for consistency. The rest of the variable name matches the name used as a configuration argument in the command line. For example, the developer mode feature is customized with the [--feature-developer] argument; therefore, its associated shell variable is BT_FEATURE_DEVELOPER.

See Section 4.1.2, “Standard features” for a complete list of standard customizable features.

If you feel the real need to change a default value for a feature, you can do so in the initialization block, simply assigning a new value to the variable (note that this is discouraged, though, as it breaks consistency between packages).

You can also add new, non-standard customizable features to your script, and they will be made available to the user through the command line. This is done using the bt_feature function. Its synopsis:

The function defines a new customizable feature, which can be referenced by the name given in the feature_name parameter, has a default value of default_value and an associated comment of comment. Note that the feature name omits the BT_FEATURE_ string.

An example: assume you need a feature to enable or disable OpenSSL support. You could define it with the following call:

bt_feature OPENSSL 'yes' 'Whether to include OpenSSL support or not (yes/no).'

It is often needed to substitute a pattern inside a source file with a check result or some dynamic string passed during the configure stage. Output files are files that receive this special treatment during automatic configuration.

The bt_generate_output function is used to generate output files. Its syntax:

The function starts creating two files: the bt_config.sed configuration file and the bt_output script. The former is used internally by the later, so you shouldn't care about it; the only detail you should know is that it is generated based on the substitution list. The later is an auxiliary program used to really generate output files. You must learn how this script works in order to understand how are output files generated.

bt_output takes file names as arguments. Each name specifies a file that needs to be generated. To generate a file, the script will look for a file with the same name as the one that has to be created, but with an extra .in suffix. If not found, the script will abort. If no file names are passed, the script generates all files that were given to the bt_generate_output function (if any).

Most times it is better to call the function without arguments. The rationale is: files should be created during the build stage of the package, not during its configuration; therefore, they can be removed during a soft clean and regenerated later without problems. If you do this, you must call the script using the BT_OUTPUT variable in logic files (when needed), as its location may change in each build or other Buildtool versions. Note, though, that logic files handle generation of files automatically in most scenarios, so you should not have to call bt_output directly.

The following code illustrates a sample logic file that generates an output file on the fly (do not worry if you do not understand it very well for now). In this specific example, the file to be generated is a C header that may include definitions dependant on the build host (like size of types):

# Sample logic file that uses bt_output.

logic() {
    bt_target myprog

    target_myprog() {
        BT_TYPE=program
        BT_SOURCES=program.c specific.h
    }

    # The following is not really needed, as it is automatic.
    # It generates specific.h from specific.h.in.
    target_specific.h() {
        BT_TYPE=output
    }
}

Let's look at another example that does the same but during configuration time: a single call to the function that could generate the src/specific.h file, based on src/specific.h.in:

bt_generate_output src/specific.h

We are still missing how substitution patterns work. In fact, it is very simple. A substitution pattern is a variable name present in the substitution list surrounded by the @ character. That is, if the variable MYVAR is in the list, the input file can reference its value using the magic string @MYVAR@^[9].

At last, to add a variable to the substitution list during configuration time, you use the bt_subst function. Its syntax:

All arguments are treated as independant variables and are added to the substitution list.

A configuration header is a regular C/C++ header file that is generated during the configuration stage of a package and contains macro definitions describing what features (other headers, functions, size types, etc.) are present or missing in the current system. This header file should be included by all C/C++ source files that form the package, so all of them can benefit from the generated header (which might include more complex things for compatibility). It cannot be included by other header files if they are going to be installed, as this will surely break your package.

Its contents are determined by the defines list, as we described above.

To generate a configuration header, always named bt_config.h, simply call the bt_generate_configh function at the end of the configuration block of your script. For completeness, here is the function syntax:

All source files should include the header using the following syntax:

#include <bt_config.h>

Buildtool will take care to adjust the compiler include path so it locates the header file without problems inside the work directory (which may vary between different Buildtool versions).

You can freely add new values to the defines list to tune what is written to the configuration header. There are two functions available, whose description follows:

This function takes a variables name and its value and adds them to the defines list. When the configuration file is written, variables tagged with this function will have their values surrounded by double quotes. This is usually useful for macros holding string values.

This function takes a variable name and its value and adds them to the defines list. When the configuration file is written, variables tagged with this function will have their values set to the macro result directly, without quotes. This is usually useful for macros holding numerical values.

As an example, consider the following calls:

bt_define MYNAME foobar
bt_define_unquoted MYCONST 5

Which could result in the following lines in the configuration header:

#define MYNAME "foobar"
#define MYCONST 5

Depending on the language you use to write your program, you will need several specific tools to build it. You can think that checking for the compiler or the interpreter is enough, but this is not usually true. The compiler will require extra checks to detect if it works, its vendor (to determine what flags are available), standard header files, standard libraries, etc.

To make things easy, there are some standard checks that automatically detect build environments. You must use them instead of calling the independant checks they execute if you want your configuration script to work properly with future versions of Buildtool.

The bt_check_env function checks for a build environment based on the current language setting (Section 11.6, “Languages support”). See below for a description of all languages supported.

During the build of your program, you will usually need to execute several non-standard programs that may not be installed on the build system. You need to check for these programs during the configuration stage, so that if they are missing, you can tell it to the user.

There are several standard checks to detect very common programs. If you need something more special, there is a generic check available (in fact, all specific checks are based on the generic one).

if bt_check_progs BT_PROG_M4 "gm4 m4"; then :; else
    bt_err "A M4 macro processor is required."
fi

Header files are usually one of the most common problems when it comes to portability issues. They may be present on some systems, but missing on others, or even have different names. Therefore you must check for the presence of non-standard headers in your configuration script. When a header is found, a macro is defined in the configuration header, so you can then check it from inside your C or C++ code and include it or not.

The BT_INCLUDE_FILES variable contains a list of headers that are included in each test program compiled during the configuration process.

bt_check_hdr sys/soundcard.h

System functions are another focus of portability problems. While many of them are standard, they may not be present on ancient systems; the ones that are not standard should be emulated by the program itself or not used at all if not present in the build system.

bt_check_func vfork

#include <bt_config.h>
#ifdef BT_HAVE_HDR_C_UNISTD_H
#include <unistd.h>
#endif

void
sample_function()
{
#ifdef BT_HAVE_FUNC_C_VFORK
    /* code that uses vfork(2) */
#else
    /* code that does not use vfork(2) */
#endif
}

Libraries are usually used during the development of a program to simplify the code, or to use code developed by a third party. You must check for the presence of the required libraries during the configuration stage of the package and notice the user if something goes wrong, so that linking does not fail in the build stage.

There are many other checks that do not fit other categories but are very useful during the configuration stage of your package. These are described in this section.

if bt_check_pkgflags _cflags _ldflags foobar,ge,1.2; then
    BT_FLAGS_CPP="$BT_FLAGS_CPP $_cflags"
    BT_FLAGS_LD="$BT_FLAGS_LD $_ldflags"
else
    bt_err "The foobar library is required.  Install it and retry."
fi

The pkgconfig.subr module provides an interface to the pkgconfig utility, used mainly by GNOME projects. As Buildtool provides a replacement, bt_pkgflags, pkgconfig support is provided as an optional module.

This function first checks for the pkg-config program, and sets the PKGCONFIG_PROG variable pointing to it. If not found, it simply returns false.

After locating the utility, it executes it searching for the given package and matching the version specification given. If successful, PKGCONFIG_FLAGS_<parsed_name>_CC and PKGCONFIG_FLAGS_<parsed_name>_LIBS are defined with the results of the call and added to the substitution list. parsed_name is the name of the package you gave to the check, converted to uppercase and with all special (non-alphabetical) characters converted to underscores.

The pthread.subr module provides a customizable feature and a check to detect a threading library on the system.

The pthread_feature function defines a customizable feature to allow the user tune if threading support has to be enabled or not. The feature can take three values: yes, to force the detection of threading (configuration will break if not found); no, to completely disable threads and auto to leave detection automatic (a check failure will not stop configuration). This function should be used only once inside the initialization block.

If this function is not called, the user is not able to tune threading support through the command line.

The pthread_check function effectively issues the threading detection if it was not disabled. It will try several compiler flags and/or libraries. If any of the checks is successful, the variable PTHREAD_FLAGS_LD is set to the flags needed for compilation and PTHREAD_LIBS lists the required library (if applicable). Both variables are added to the substitution list.

Returns true on success, false if the library (or function) cannot be found.

The x11.subr module provides a customizable feature and a some functions to detect the presence of the X Window System on the system.

The x11_feature function defines a customizable feature to allow the user tune if X11 support has to be enabled or not. The feature can take three values: yes, to force the detection of X11 (configuration will break if not found); no, to completely disable X11 and auto to leave detection automatic (a check failure will not stop configuration). This function should be used only once inside the initialization block.

If this function is not called, the user is not able to tune X11 support through the command line.

The x11_check function effectively issues the X11 detection if it was not manually disabled. It will try several standard directories when searching for include files and libraries. Additional directories may be passed in the whitespace separated lists provided in the X11_DIR_INCLUDE and X11_DIR_LIB variables.

If X11 is found, X11_FLAGS_CPP and X11_FLAGS_LD are defined with the required compiler flags needed to compile and link programs against the X11 system. Both variables are added to the substitution list.

Returns true on success, false if the library (or function) cannot be found.

The x11_failure function can be used when you need to inform the user that X11 was not found. It outputs a consistant error message across packages and terminates the configuration process, requiring user intervention to fix the problems. Note that x11_check will automatically call this function in several situations, so make sure you are not duplicating work.