Chapter 21. Multi-Platform Configuration (Autoconf Functionality)

SCons has integrated support for build configuration similar in style to GNU Autoconf, but designed to be transparently multi-platform. The configuration system can help figure out if external build requirements such as system libraries or header files are available on the build system. This section describes how to use this SCons feature. (See also the SCons man page for additional information).

21.1. Configure Contexts

The basic framework for multi-platform build configuration in SCons is to create a configure context inside a construction environment by calling the Configure function, perform the desired checks for libraries, functions, header files, etc., and then call the configure context's Finish method to finish off the configuration:

env = Environment()
conf = Configure(env)
# Checks for libraries, header files, etc. go here!
env = conf.Finish()

The Finish call is required; if a new context is created while a context is active, even in a different construction environment, scons will complain and exit.

SCons provides a number of pre-defined basic checks, as well as a mechanism for adding your own custom checks.

There are a few possible strategies for failing configure checks. Some checks may be for features without which you cannot proceed. The simple approach here is just to exit SCons at that point - a number of the examples in this chapter are coded that way. If there are multiple hard requirements, however, it may be friendlier to the user to set a flag in case of any fails of hard requirements and accumulate a record of them, so that on the completion of the configure context they can all be listed prior to failing the build - as it can be frustrating to have to iterate through the setup, fixing one new requirement each iteration. Other checks may be for features which you can do without, and here the strategy will usually be to set a construction variable which the rest of the build can examine for its absence/presence, or to set particular compiler flags, library lists, etc. as appropriate for the circumstances, so you can proceed with the build appropriately based on available features.

Note that SCons uses its own dependency mechanism to determine when a check needs to be run--that is, SCons does not run the checks every time it is invoked, but caches the values returned by previous checks and uses the cached values unless something has changed. This saves a tremendous amount of developer time while working on cross-platform build issues.

The next sections describe the basic checks that SCons supports, as well as how to add your own custom checks.