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

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.7 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.

python3 -m venv $HOME/.pyenv/buildtest
source $HOME/.pyenv/buildtest/bin/activate
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.7 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 -r docs/requirements.txt

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.

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -c CONFIGFILE, --config CONFIGFILE
                        Specify Path to Configuration File
  -d, --debug           Print debug messages to screen
  --no-color            Disable colored 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 based on NAME or ID
    history (hy)        Query build history
    edit (et)           Edit a buildspec and validate with schema file
    schema              List schema contents and examples
    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.
    path                Show path attributes for a given test
    docs                Open buildtest docs in browser
    schemadocs          Open buildtest schema docs in browser
    debugreport         Display system information and additional information
                        for debugging purposes.
    help (h)            buildtest command guide
    unittests           Run buildtest unit tests
    stylecheck (style)  Run buildtest style checks

References

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

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

Copyright (c) 2021-2022, 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, please go to the next section on Buildtest Tutorial