build-system.jam

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

# Copyright 2003, 2005, 2007 Dave Abrahams
# Copyright 2006, 2007 Rene Rivera
# Copyright 2003, 2004, 2005, 2006 Vladimir Prus
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)

# This file is part of Boost Build version 2. You can think of it as forming the
# main() routine. It is invoked by the bootstrapping code in bootstrap.jam.

import build-request ;
import builtin ;
import "class" : new ;
import errors ;
import feature ;
import make ;
import modules ;
import os ;
import path ;
import project ;
import property-set ;
import regex ;
import sequence ;
import targets ;
import toolset ;
import utility ;
import version ;
import virtual-target ;


################################################################################
#
# Module global data.
#
################################################################################

# Shortcut used in this module for accessing used command-line parameters.
.argv = [ modules.peek : ARGV ] ;

# Flag indicating we should display additional debugging information related to
# locating and loading Boost Build configuration files.
.debug-config = [ MATCH ^(--debug-configuration)$ : $(.argv) ] ;

# Legacy option doing too many things, some of which are not even documented.
# Should be phased out.
#   * Disables loading site and user configuration files.
#   * Disables auto-configuration for toolsets specified explicitly on the
#     command-line.
#   * Causes --toolset command-line options to be ignored.
#   * Prevents the default toolset from being used even if no toolset has been
#     configured at all.
.legacy-ignore-config = [ MATCH ^(--ignore-config)$ : $(.argv) ] ;

# The cleaning is tricky. Say, if user says 'bjam --clean foo' where 'foo' is a
# directory, then we want to clean targets which are in 'foo' as well as those
# in any children Jamfiles under foo but not in any unrelated Jamfiles. To
# achieve this we collect a list of projects under which cleaning is allowed.
.project-targets = ;

# Virtual targets obtained when building main targets references on the command
# line. When running 'bjam --clean main_target' we want to clean only files
# belonging to that main target so we need to record which targets are produced
# for it.
.results-of-main-targets = ;

# Was an XML dump requested?
.out-xml = [ MATCH ^--out-xml=(.*)$ : $(.argv) ] ;

# Default toolset & version to be used in case no other toolset has been used
# explicitly by either the loaded configuration files, the loaded project build
# scripts or an explicit toolset request on the command line. If not specified,
# an arbitrary default will be used based on the current host OS. This value,
# while not strictly necessary, has been added to allow testing Boost-Build's
# default toolset usage functionality.
.default-toolset = ;
.default-toolset-version = ;


################################################################################
#
# Public rules.
#
################################################################################

# Returns the property set with the free features from the currently processed
# build request.
#
rule command-line-free-features ( )
{
    return $(.command-line-free-features) ;
}


# Returns the location of the build system. The primary use case is building
# Boost where it is sometimes needed to get the location of other components
# (e.g. BoostBook files) and it is convenient to use locations relative to the
# Boost Build path.
#
rule location ( )
{
    local r = [ modules.binding build-system ] ;
    return $(r:P) ;
}


# Sets the default toolset & version to be used in case no other toolset has
# been used explicitly by either the loaded configuration files, the loaded
# project build scripts or an explicit toolset request on the command line. For
# more detailed information see the comment related to used global variables.
#
rule set-default-toolset ( toolset : version ? )
{
    .default-toolset = $(toolset) ;
    .default-toolset-version = $(version) ;
}


################################################################################
#
# Local rules.
#
################################################################################

# Returns actual Jam targets to be used for executing a clean request.
#
local rule actual-clean-targets ( )
{
    # Construct a list of projects explicitly detected as targets on this build
    # system run. These are the projects under which cleaning is allowed.
    for local t in $(targets)
    {
        if [ class.is-a $(t) : project-target ]
        {
            .project-targets += [ $(t).project-module ] ;
        }
    }

    # Construct a list of targets explicitly detected on this build system run
    # as a result of building main targets.
    local targets-to-clean ;
    for local t in $(.results-of-main-targets)
    {
        # Do not include roots or sources.
        targets-to-clean += [ virtual-target.traverse $(t) ] ;
    }
    targets-to-clean = [ sequence.unique $(targets-to-clean) ] ;

    local to-clean ;
    for local t in [ virtual-target.all-targets ]
    {
        local p = [ $(t).project ] ;

        # Remove only derived targets.
        if [ $(t).action ]
        {
            if $(t) in $(targets-to-clean) ||
                [ should-clean-project [ $(p).project-module ] ] = true
            {
                to-clean += $(t) ;
            }
        }
    }

    local to-clean-actual ;
    for local t in $(to-clean)
    {
        to-clean-actual += [ $(t).actualize ] ;
    }
    return $(to-clean-actual) ;
}


# Given a target id, try to find and return the corresponding target. This is
# only invoked when there is no Jamfile in ".". This code somewhat duplicates
# code in project-target.find but we can not reuse that code without a
# project-targets instance.
#
local rule find-target ( target-id )
{
    local split = [ MATCH (.*)//(.*) : $(target-id) ] ;

    local pm ;
    if $(split)
    {
        pm = [ project.find $(split[1]) : "." ] ;
    }
    else
    {
        pm = [ project.find $(target-id) : "." ] ;
    }

    local result ;
    if $(pm)
    {
        result = [ project.target $(pm) ] ;
    }

    if $(split)
    {
        result = [ $(result).find $(split[2]) ] ;
    }

    return $(result) ;
}


# Initializes a new configuration module.
#
local rule initialize-config-module ( module-name )
{
    project.initialize $(module-name) ;
    if USER_MODULE in [ RULENAMES ]
    {
        USER_MODULE $(module-name) ;
    }
}


# Helper rule used to load configuration files. Loads the first configuration
# file with the given 'filename' at 'path' into module with name 'module-name'.
# Not finding the requested file may or may not be treated as an error depending
# on the must-find parameter. Returns a normalized path to the loaded
# configuration file or nothing if no file was loaded.
#
local rule load-config ( module-name : filename : path + : must-find ? )
{
    if $(.debug-config)
    {
        ECHO "notice: Searching" "$(path)" "for" "$(module-name)"
            "configuration file" "$(filename)" "." ;
    }
    local where = [ GLOB $(path) : $(filename) ] ;
    if $(where)
    {
        where = [ NORMALIZE_PATH $(where[1]) ] ;
        if $(.debug-config)
        {
            ECHO "notice: Loading" "$(module-name)" "configuration file"
                "$(filename)" "from" $(where) "." ;
        }

        modules.load $(module-name) : $(filename) : $(path) ;
        project.load-used-projects $(module-name) ;
    }
    else
    {
        if $(must-find)
        {
            errors.user-error "Configuration file" "$(filename)" "not found in"
                "$(path)" "." ;
        }
        if $(.debug-config)
        {
            ECHO "notice:" "Configuration file" "$(filename)" "not found in"
                "$(path)" "." ;
        }
    }
    return $(where) ;
}


# Loads all the configuration files used by Boost Build in the following order:
#
#   -- test-config --
#   Loaded only if specified on the command-line using the --test-config
# command-line parameter. It is ok for this file not to exist even if specified.
# If this configuration file is loaded, regular site and user configuration
# files will not be. If a relative path is specified, file is searched for in
# the current folder.
#
#   -- site-config --
#   Always named site-config.jam. Will only be found if located on the system
# root path (Windows), /etc (non-Windows), user's home folder or the Boost Build
# path, in that order. Not loaded in case the test-config configuration file is
# loaded or either the --ignore-site-config or the --ignore-config command-line
# option is specified.
#
#   -- user-config --
#   Named user-config.jam by default or may be named explicitly using the
# --user-config command-line option or the BOOST_BUILD_USER_CONFIG environment
# variable. If named explicitly the file is looked for from the current working
# directory and if the default one is used then it is searched for in the
# user's home directory and the Boost Build path, in that order. Not loaded in
# case either the test-config configuration file is loaded, --ignore-config
# command-line option is specified or an empty file name is explicitly
# specified. If the file name has been given explicitly then the file must
# exist.
#
# Test configurations have been added primarily for use by Boost Build's
# internal unit testing system but may be used freely in other places as well.
#
local rule load-configuration-files
{
    # Flag indicating that site configuration should not be loaded.
    local ignore-site-config =
        [ MATCH ^(--ignore-site-config)$ : $(.argv) ] ;

    if $(.legacy-ignore-config) && $(.debug-config)
    {
        ECHO "notice: Regular site and user configuration files will be ignored" ;
        ECHO "notice: due to the --ignore-config command-line option." ;
    }

    initialize-config-module test-config ;