basistest-slave.sh

Go to the documentation of this file.

#! /bin/bash
##############################################################################
# @file  basistest-slave.sh
# @brief Test execution command.
#
# This shell script runs the tests of a BASIS project. It is a wrapper for
# a CTest script. In particular, the testing master basistest-master.sh uses
# this script by default in order to run a test.
#
# Copyright (c) 2011, 2012 University of Pennsylvania. All rights reserved.<br />
# See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.
#
# Contact: SBIA Group <sbia-software at uphs.upenn.edu>
#
# @ingroup Tools
##############################################################################


# constants used by the shflags.sh module
HELP_COMMAND='basistest-slave (BASIS)'
HELP_CONTACT='SBIA Group <sbia-software at uphs.upenn.edu>'
HELP_VERSION='version 1.2.3 (revision 2104)'
HELP_COPYRIGHT='Copyright (c) University of Pennsylvania. All rights reserved.
See https://www.rad.upenn.edu/sbia/software/license.html or COPYING file.'


# ----------------------------------------------------------------------------
## @brief Get real path of given file or directory.
#
# @note This function was substituted by BASIS either for the string
#       \@BASIS_BASH_UTILITIES\@ or \@BASIS_BASH_FUNCTION_realpath\@.
#
# Example:
# @code
# exec_dir=`realpath $0`
# @endcode
#
# @param [in] path File or directory path.
#
# @returns Canonical path.
#
# @sa http://stackoverflow.com/questions/7665/how-to-resolve-symbolic-links-in-a-shell-script
function realpath
{
    local path=$1

    local linkdir=''
    local symlink=''

    while [ -h ${path} ]; do
        # 1) change to directory of the symbolic link
        # 2) change to directory where the symbolic link points to
        # 3) get the current working directory
        # 4) append the basename
        linkdir=$(dirname -- "${path}")
        symlink=$(readlink ${path})
        path=$(cd "${linkdir}" && cd $(dirname -- "${symlink}") && pwd)/$(basename -- "${symlink}")
    done

    echo -n "$(cd -P -- "$(dirname "${path}")" && pwd -P)/$(basename -- "${path}")"
}

readonly _SBIA_BASIS_BASISTEST_SLAVE_DIR="$(dirname -- "$(realpath "$(cd -P -- "$(dirname -- "${BASH_SOURCE}")" && pwd -P)/$(basename -- "$BASH_SOURCE")")")"
source "${_SBIA_BASIS_BASISTEST_SLAVE_DIR}/../lib/basis.sh" || exit 1


# ============================================================================
# constants
# ============================================================================

get_executable_directory _EXEC_DIR  && readonly _EXEC_DIR
get_executable_name      _EXEC_NAME && readonly _EXEC_NAME

# ============================================================================
# help/version
# ============================================================================

# ----------------------------------------------------------------------------
## @brief Print documentation of options.
#
# @returns Nothing.
function print_options
{
    cat - << EOF-OPTIONS
Optional arguments:
  --project, -p   The name of the project to be tested.
  --branch, -b    The branch to be tested, e.g., "tags/1.0.0".
                  Default: "trunk".
  --model, -m     The name of the dashboard model, i.e., either "Nightly",
                  "Continuous", or "Experimental".
                  Default: "Experimental".
  --script, -S    CTest script which performs the testing.
                  Default: basistest.ctest script of BASIS.
  --args, -a      Additional arguments for the CTest script. See below.
                  Instead of using the --args option, the additional arguments
                  can be given directly with only two dashes (--) prefixed.

Standard arguments:
  --verbose, -v   Increases verbosity of output messages. Can be given multiple times.
  --help, -h      Print help and exit.
  --helpshort     Print short help and exit.
  --version       Print version information and exit.

All other arguments are passed on as additional arguments to the CTest script
without the leading two dashes (--). For example, the optional argument
--coverage corresponds to supplying the option --args with the value 'coverage'.
Both result in the argument 'coverage' being passed on to the CTest script.
See below for a list of valid arguments of the CTest script.
EOF-OPTIONS
}

# ----------------------------------------------------------------------------
## @brief Print help.
#
# @returns Nothing.
function print_help
{
    echo "Usage:"
    echo "  ${_EXEC_NAME} [options]"
    echo
    cat - << EOF-DESCRIPTION
Description:
  This program performs the testing of a BASIS project.
EOF-DESCRIPTION
    echo
    print_options
    echo
    echo "Arguments of CTest script:"
    which ctest &> /dev/null
    if [ $? -ne 0 ]; then
        echo "  Missing ctest command!" 1>&2
    else
        if [ ! -f "${ctest_script}" ]; then
            echo "  Missing CTest script ${ctest_script}" 1>&2
        else
            helpstr=`ctest -S "${ctest_script},helpoptions"`
            helpstr="${helpstr%CMake Error*}"
            echo -n "${helpstr}"
        fi
    fi
    echo
    cat - << EOF-EXAMPLES
Examples:
  ${_EXEC_NAME}

    Run this command in the build tree of your BASIS project to run the tests
    with submission of the test results to the Experimental dashboard.

  ${_EXEC_NAME} --memcheck

    Run this command in the build tree of your BASIS project to run the memory
    checks with the submission of the results to the Experimental dashboard.

  ${_EXEC_NAME} --project BASIS --coverage

    Performs the testing of the project BASIS. The project source files are
    first download into the source directory, then the build tree is configured
    and the project is build. When these steps were successful, the tests are run,
    including coverage analysis.
EOF-EXAMPLES
    echo
    print_contact
}

# ----------------------------------------------------------------------------
## @brief Print usage (i.e., only usage and options).
#
# @returns Nothing.
function print_helpshort
{
    echo "Usage:"
    echo "  ${_EXEC_NAME} [options]"
    echo
    print_options
    echo
    print_contact
}

# ============================================================================
# options
# ============================================================================

# CTest script
ctest_script="${_EXEC_DIR}/../share/cmake/basistest.ctest"

project=''           # name of the BASIS project
branch='trunk'       # the branch to test
model='Experimental' # the dashboard model
args=''              # additional CTest script arguments
verbosity=0          # verbosity of output messages

function add_arg
{
    if [ -n "${args}" ]; then
        args="${args},$1"
    else
        args="$1"
    fi
}

while [ $# -gt 0 ]; do
    case "$1" in
        -p|--project)
            shift
            if [ $# -gt 0 ]; then
                project=$1
            else
                echo "Option --project requires an argument!" 1>&2
                exit 1
            fi
            ;;
        -b|--branch)
            shift
            if [ $# -gt 0 ]; then
                branch=$1
            else
                echo "Option --branch requires an argument!" 1>&2
                exit 1
            fi
            ;;
        -m|--model)
            shift
            if [ $# -gt 0 ]; then
                model=$1
            else
                echo "Option --model requires an argument!" 1>&2
                exit 1
            fi
            ;;
        -S|--script)
            shift
            if [ $# -gt 0 ]; then
                ctest_script=$1
            else
                echo "Option --script requires an argument!" 1>&2
                exit 1
            fi
            ;;
        -a|--args)
            shift
            if [ $# -gt 0 ]; then
                add_arg "$1"
            else
                echo "Option --args requires an argument!" 1>&2
                exit 1
            fi
            ;;

        # standard options
        -h|--help)    print_help; exit 0; ;;
        --helpshort)  print_helpshort; exit 0; ;;
        --version)    print_version "basistest-slave"; exit 0; ;;
        -v|--verbose) ((verbosity++)); ;;
        -vv)          verbosity=$((${verbosity} + 2));;

        # pass all unknown options as arguments to the CTest script
        *)
            if [ "${1:0:2}" != '--' ]; then
                if [ "${1:0:1}" == '-' ]; then
                    echo "Invalid option: $1" 1>&2
                else
                    echo "Invalid argument: $1" 1>&2
                    echo "Did you mean --$1 instead?" 1>&2
                fi
                exit 1
            fi
            add_arg "${1:2}"
            ;;
    esac
    shift
done

# ============================================================================
# main
# ============================================================================

if [ ${verbosity} -gt 0 ]; then
    echo "${_EXEC_NAME} running on host $(hostname)"
    echo
fi

# see if ctest can be found
which ctest &> /dev/null
if [ $? -ne 0 ]; then
    echo "Could not find the ctest command" 1>&2
    exit 1
fi

# check existence of CTest script
if [ ! -f "${ctest_script}" ]; then
    echo "Missing CTest script ${ctest_script}" 1>&2
    exit 1
fi

# compose command
cmd='ctest'
if [ ${verbosity} -gt 1 ]; then
    cmd="${cmd} -VV"
else
    cmd="${cmd} -V"
fi
cmd="${cmd} -S ${ctest_script}"
if [ -n "${project}" ]; then cmd="${cmd},project=${project}"; fi
if [ -n "${branch}"  ]; then cmd="${cmd},branch=${branch}"; fi
if [ -n "${model}"   ]; then cmd="${cmd},model=${model}"; fi
if [ ! -z "${args}"  ]; then cmd="${cmd},${args}"; fi
cmd="${cmd}"

# run test
if [ ${verbosity} -gt 1 ]; then
    echo "Exec ${cmd}"
fi
exec ${cmd}