Installing buildtest

Requirements

You need the following packages to install buildtest.

Cloning buildtest

To get started, clone the buildtest repository in your local machine as follows

git clone https://github.com/buildtesters/buildtest.git

git clone git@github.com:buildtesters/buildtest.git

If you prefer the latest release, you can clone the master branch:

$ git clone -b master git@github.com:buildtesters/buildtest.git

Installing buildtest

buildtest requires a Python 3.9 or higher, we recommend you setup a python environment in order to install buildtest. You can use venv, conda, or pipenv to manage your python environment depending on your preference. Assuming you have cloned buildtest in your HOME directory you will need to follow these instructions to install buildtest.

For bash shell

python3 -m venv $HOME/.pyenv/buildtest
source $HOME/.pyenv/buildtest/bin/activate
source $HOME/buildtest/setup.sh

For csh shell

python3 -m venv $HOME/.pyenv/buildtest
source $HOME/.pyenv/buildtest/bin/activate.csh
source $HOME/buildtest/setup.csh

conda create -n buildtest python=3.9
source activate buildtest
source $HOME/buildtest/setup.sh

pipenv --python 3.9
pipenv shell
source $HOME/buildtest/setup.sh

For csh users you will need to source setup.csh in order to install buildtest.

Upon installation, you should see buildtest in your $PATH and environment variable $BUILDTEST_ROOT will point to root of buildtest repo.

buildtest will provide tab completion for bash shell, this is managed by script bash_completion.sh, if you encounter any issues with tab completion please raise an issue at https://github.com/buildtesters/buildtest/issues/.

Specify Python Wrapper via BUILDTEST_PYTHON

The buildtest program will search for a python wrapper (python, python3) to run buildtest, however you can specify an alternate python wrapper by setting environment variable BUILDTEST_PYTHON wrapper. This variable will be set during execution of buildtest, please note the python wrapper must be 3.9 or higher in-order for buildtest to function properly.

Development Dependencies (Optional)

If you plan to contribute back to buildtest, you will need to install additional dependencies as follows:

$ pip install '.[dev]'

Usage (buildtest --help)

Once you are setup, you can run buildtest --help for more details on how to use buildtest. Shown below is the output

$ buildtest --help
usage: buildtest [options] [COMMANDS]

buildtest is a HPC testing framework for building and running tests.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -c CONFIGFILE, --configfile CONFIGFILE
                        Specify Path to Configuration File
  -d, --debug           Stream log messages to stdout
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Filter log messages based on logging level
  --editor {vi,vim,emacs,nano}
                        Select your preferred editor when opening files.
  --view-log            Show content of last log
  --logpath             Print full path to last log file
  --print-log           Print content of last log without pagination
  --color COLOR         Print output of table with the selected color.
  --no-color            Disable colored output
  --helpcolor           Print available color options in a table format.
  -r REPORT, --report REPORT
                        Specify path to test report file
  -H, --help-all        List all commands and options
  --listopts            List all options for buildtest
  --verbose             Enable verbose output

COMMANDS:
  
    build (bd)          Build and Run test
    buildspec (bc)      Buildspec Interface
    config (cg)         Query buildtest configuration
    report (rt)         Query test report
    inspect (it)        Inspect a test
    path (p)            Show path attributes for a given test
    history (hy)        Query build history
    cdash               Upload test to CDASH server
    cd                  Change directory to root of test given a test name
    clean               Remove all generate files from buildtest including
                        test directory, log files, report file, buildspec
                        cache, history files
    debugreport (debug)
                        Display system information and additional information
                        for debugging purposes.
    stats               Show test statistics for given test
    info                Show details regarding current buildtest setup
    show                buildtest command guide
    commands (cmds)     List all buildtest commands

    References

    GitHub:                  https://github.com/buildtesters/buildtest
    Documentation:           https://buildtest.readthedocs.io/en/latest/index.html
    Slack:                   http://hpcbuildtest.slack.com/

    Please report issues at https://github.com/buildtesters/buildtest/issues

    Copyright (c) 2021-2024, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy), Shahzeb Siddiqui, and Vanessa Sochat. All rights reserved.

If you have got this far, you can check out the Quick Start Guide or Buildtest Command Line Reference