testing.jam

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

# Copyright 2005 Dave Abrahams
# Copyright 2002, 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 module implements regression testing framework. It declares a number of
# main target rules which perform some action and, if the results are OK,
# creates an output file.
#
# The exact list of rules is:
# 'compile'       -- creates .test file if compilation of sources was
#                    successful.
# 'compile-fail'  -- creates .test file if compilation of sources failed.
# 'run'           -- creates .test file is running of executable produced from
#                    sources was successful. Also leaves behind .output file
#                    with the output from program run.
# 'run-fail'      -- same as above, but .test file is created if running fails.
#
# In all cases, presence of .test file is an indication that the test passed.
# For more convenient reporting, you might want to use C++ Boost regression
# testing utilities (see http://www.boost.org/more/regression.html).
#
# For historical reason, a 'unit-test' rule is available which has the same
# syntax as 'exe' and behaves just like 'run'.

# Things to do:
#  - Teach compiler_status handle Jamfile.v2.
# Notes:
#  - <no-warn> is not implemented, since it is Como-specific, and it is not
#    clear how to implement it
#  - std::locale-support is not implemented (it is used in one test).


import alias ;
import "class" ;
import common ;
import errors ;
import feature ;
import generators ;
import os ;
import path ;
import project ;
import property ;
import property-set ;
import regex ;
import sequence ;
import targets ;
import toolset ;
import type ;
import virtual-target ;


rule init ( )
{
}


# Feature controling the command used to lanch test programs.
feature.feature testing.launcher   : : free optional ;

feature.feature test-info          : : free incidental ;
feature.feature testing.arg        : : free incidental ;
feature.feature testing.input-file : : free dependency ;


# Register target types.
type.register TEST         : test          ;
type.register COMPILE      :        : TEST ;
type.register COMPILE_FAIL :        : TEST ;
type.register RUN_OUTPUT   : run           ;
type.register RUN          :        : TEST ;
type.register RUN_FAIL     :        : TEST ;
type.register LINK_FAIL    :        : TEST ;
type.register LINK         :        : TEST ;
type.register UNIT_TEST    : passed : TEST ;


# Declare the rules which create main targets. While the 'type' module already
# creates rules with the same names for us, we need extra convenience: default
# name of main target, so write our own versions.

# Helper rule. Create a test target, using basename of first source if no target
# name is explicitly passed. Remembers the created target in a global variable.
#
rule make-test ( target-type : sources + : requirements * : target-name ? )
{
    target-name ?= $(sources[1]:D=:S=) ;

    # Having periods (".") in the target name is problematic because the typed
    # generator will strip the suffix and use the bare name for the file
    # targets. Even though the location-prefix averts problems most times it
    # does not prevent ambiguity issues when referring to the test targets. For
    # example when using the XML log output. So we rename the target to remove
    # the periods, and provide an alias for users.
    local real-name = [ regex.replace $(target-name) "[.]" "~" ] ;

    local project = [ project.current ] ;
    # The <location-prefix> forces the build system for generate paths in the
    # form '$build_dir/array1.test/gcc/debug'. This is necessary to allow
    # post-processing tools to work.
    local t = [ targets.create-typed-target [ type.type-from-rule-name
        $(target-type) ] : $(project) : $(real-name) : $(sources) :
        $(requirements) <location-prefix>$(real-name).test ] ;

    # The alias to the real target, per period replacement above.
    if $(real-name) != $(target-name)
    {
        alias $(target-name) : $(t) ;
    }

    # Remember the test (for --dump-tests). A good way would be to collect all
    # given a project. This has some technical problems: e.g. we can not call
    # this dump from a Jamfile since projects referred by 'build-project' are
    # not available until the whole Jamfile has been loaded.
    .all-tests += $(t) ;
    return $(t) ;
}


# Note: passing more that one cpp file here is known to fail. Passing a cpp file
# and a library target works.
#
rule compile ( sources + : requirements * : target-name ? )
{
    return [ make-test compile : $(sources) : $(requirements) : $(target-name) ]
        ;
}


rule compile-fail ( sources + : requirements * : target-name ? )
{
    return [ make-test compile-fail : $(sources) : $(requirements) :
        $(target-name) ] ;
}


rule link ( sources + : requirements * : target-name ? )
{
    return [ make-test link : $(sources) : $(requirements) : $(target-name) ] ;
}


rule link-fail ( sources + : requirements * : target-name ? )
{
    return [ make-test link-fail : $(sources) : $(requirements) : $(target-name)
        ] ;
}


rule handle-input-files ( input-files * )
{
    if $(input-files[2])
    {
        # Check that sorting made when creating property-set instance will not
        # change the ordering.
        if [ sequence.insertion-sort $(input-files) ] != $(input-files)
        {
            errors.user-error "Names of input files must be sorted alphabetically"
                : "due to internal limitations" ;
        }
    }
    return <testing.input-file>$(input-files) ;
}


rule run ( sources + : args * : input-files * : requirements * : target-name ? :
    default-build * )
{
    requirements += <testing.arg>$(args:J=" ") ;
    requirements += [ handle-input-files $(input-files) ] ;
    return [ make-test run : $(sources) : $(requirements) : $(target-name) ] ;
}


rule run-fail ( sources + : args * : input-files * : requirements * :
    target-name ? : default-build * )
{
    requirements += <testing.arg>$(args:J=" ") ;
    requirements += [ handle-input-files $(input-files) ] ;
    return [ make-test run-fail : $(sources) : $(requirements) : $(target-name)
        ] ;
}


# Use 'test-suite' as a synonym for 'alias', for backward compatibility.
IMPORT : alias : : test-suite ;


# For all main targets in 'project-module', which are typed targets with type
# derived from 'TEST', produce some interesting information.
#
rule dump-tests
{
    for local t in $(.all-tests)
    {
        dump-test $(t) ;
    }
}


# Given a project location in normalized form (slashes are forward), compute the
# name of the Boost library.
#
local rule get-library-name ( path )
{
    # Path is in normalized form, so all slashes are forward.
    local match1 = [ MATCH /libs/(.*)/(test|example) : $(path) ] ;
    local match2 = [ MATCH /libs/(.*)$ : $(path) ] ;
    local match3 = [ MATCH (/status$) : $(path) ] ;

    if $(match1) { return $(match1[0]) ; }
    else if $(match2) { return $(match2[0]) ; }
    else if $(match3) { return "" ; }
    else if --dump-tests in [ modules.peek : ARGV ]
    {
        # The 'run' rule and others might be used outside boost. In that case,
        # just return the path, since the 'library name' makes no sense.
        return $(path) ;
    }
}


# Was an XML dump requested?
.out-xml = [ MATCH --out-xml=(.*) : [ modules.peek : ARGV ] ] ;


# Takes a target (instance of 'basic-target') and prints
#   - its type
#   - its name
#   - comments specified via the <test-info> property
#   - relative location of all source from the project root.
#
rule dump-test ( target )
{
    local type = [ $(target).type ] ;
    local name = [ $(target).name ] ;
    local project = [ $(target).project ] ;

    local project-root = [ $(project).get project-root ] ;
    local library = [ get-library-name [ path.root [ $(project).get location ]
        [ path.pwd ] ] ] ;
    if $(library)
    {
        name = $(library)/$(name) ;
    }

    local sources = [ $(target).sources ] ;
    local source-files ;
    for local s in $(sources)
    {
        if [ class.is-a $(s) : file-reference ]
        {
            local location = [ path.root [ path.root [ $(s).name ]
                [ $(s).location ] ] [ path.pwd ] ] ;

            source-files += [ path.relative-to [ path.root $(project-root)
                [ path.pwd ] ] $(location) ] ;
        }
    }

    local target-name = [ $(project).get location ] // [ $(target).name ] .test
        ;
    target-name = $(target-name:J=) ;

    local r = [ $(target).requirements ] ;
    # Extract values of the <test-info> feature.
    local test-info = [ $(r).get <test-info> ] ;

    # If the user requested XML output on the command-line, add the test info to
    # that XML file rather than dumping them to stdout.
    if $(.out-xml)
    {
        local nl = "
" ;
        .contents on $(.out-xml) +=
            "$(nl)  <test type=\"$(type)\" name=\"$(name)\">"
            "$(nl)    <target><![CDATA[$(target-name)]]></target>"
            "$(nl)    <info><![CDATA[$(test-info)]]></info>"
            "$(nl)    <source><![CDATA[$(source-files)]]></source>"
            "$(nl)  </test>"
            ;
    }
    else
    {
        # Format them into a single string of quoted strings.
        test-info = \"$(test-info:J=\"\ \")\" ;

        ECHO boost-test($(type)) \"$(name)\" [$(test-info)] ":"
            \"$(source-files)\" ;
    }
}