Command Line Interface to buildtest configuration¶
Once you have implemented your buildtest configuration, you can query the configuration
details using buildtest config command. Shown below is the command usage.
$ buildtest config --help
usage: buildtest [options] [COMMANDS] config [-h] ...
optional arguments:
-h, --help show this help message and exit
subcommands:
Query information from buildtest configuration file
executors
Query executors from buildtest configuration
view View Buildtest Configuration File
validate Validate buildtest settings file with schema.
summary Provide summary of buildtest settings.
systems List all available systems
compilers
search or find compilers
Validate buildtest configuration¶
First thing you should do once you implement your configuration file is to make sure your configuration is valid with the schema.
This can be achieved by running buildtest config validate. When you invoke this
command, buildtest will load the configuration and attempt to validate the file with
schema settings.schema.json. If validation is successful you will get the following message:
$ buildtest config validate
/Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/settings/config.yml is valid
Note
If you defined a user setting (~/.buildtest/config.yml) buildtest will validate this file instead of default one.
If there is an error during validation, the output from jsonschema.exceptions.ValidationError
will be displayed in terminal. For example the error below indicates that
moduletool property was expecting one of the values
[environment-modules, lmod, N/A] but it recieved a value of none:
$ buildtest config validate
Traceback (most recent call last):
File "/Users/siddiq90/Documents/buildtest/bin/buildtest", line 17, in <module>
buildtest.main.main()
File "/Users/siddiq90/Documents/buildtest/buildtest/main.py", line 39, in main
buildtest_configuration = check_settings(settings_file, retrieve_settings=True)
File "/Users/siddiq90/Documents/buildtest/buildtest/config.py", line 41, in check_settings
validate(instance=user_schema, schema=config_schema)
File "/Users/siddiq90/.local/share/virtualenvs/buildtest-1gHVG2Pd/lib/python3.7/site-packages/jsonschema/validators.py", line 934, in validate
raise error
jsonschema.exceptions.ValidationError: 'none' is not one of ['environment-modules', 'lmod', 'N/A']
Failed validating 'enum' in schema['properties']['moduletool']:
{'description': 'Specify modules tool used for interacting with '
'``module`` command. ',
'enum': ['environment-modules', 'lmod', 'N/A'],
'type': 'string'}
On instance['moduletool']:
'none'
View buildtest configuration¶
If you want to view buildtest configuration you can run the following
$ buildtest config view
hostnames:
- .*
description: Generic System
moduletool: N/A
load_default_buildspecs: true
executors:
local:
bash:
description: submit jobs on local machine using bash shell
shell: bash
sh:
description: submit jobs on local machine using sh shell
shell: sh
csh:
description: submit jobs on local machine using csh shell
shell: csh
zsh:
description: submit jobs on local machine using zsh shell
shell: zsh
python:
description: submit jobs on local machine using python shell
shell: python
compilers:
compiler:
gcc:
builtin_gcc:
cc: /usr/bin/gcc
fc: /usr/bin/gfortran
cxx: /usr/bin/g++
cdash:
url: https://my.cdash.org/
project: buildtest
site: generic
buildname: tutorials
________________________________________________________________________________
Settings File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/settings/config.yml
Note
buildtest config view will display contents of user buildtest settings ~/.buildtest/config.yml if found, otherwise it will display the default configuration
View Executors¶
You can use the command buildtest config executors to view executors from buildtest
configuration file. Shown below is the command usage
$ buildtest config executors --help
usage: buildtest [options] [COMMANDS] config executors [-h] [-j] [-y]
optional arguments:
-h, --help show this help message and exit
-j, --json View executor in JSON format
-y, --yaml View executors in YAML format
You can run buildtest config executors without any options and it will report a list of named executors that
you would reference in buildspec using the executor property. If you prefer json or yaml format you can use --json or --yaml option.
$ buildtest config executors
generic.local.bash
generic.local.sh
generic.local.csh
generic.local.zsh
generic.local.python
View Registered Systems¶
Your buildtest configuration may compose of one or more systems since you can define multiple systems
in a single configuration file to run buildtest for different HPC clusters. You can use
buildtest config systems to report all system details defined in your configuration file.
In this example below we should the generic system. If you have multiple entries, you will see one
entry per system record.
$ buildtest config systems
+----------+----------------+-------------+--------------+
| system | description | hostnames | moduletool |
+==========+================+=============+==============+
| generic | Generic System | ['.*'] | N/A |
+----------+----------------+-------------+--------------+
Configuration Summary¶
You can get a summary of buildtest using buildtest config summary, this will
display information from several sources into one single command along.
$ buildtest config summary
buildtest version: 0.9.5
buildtest Path: /Users/siddiq90/Documents/GitHubDesktop/buildtest/bin/buildtest
Machine Details
______________________________
Operating System: darwin
Hostname: DOE-7086392.local
Machine: x86_64
Processor: i386
Python Path /Users/siddiq90/.local/share/virtualenvs/buildtest-KLOcDrW0/bin/python
Python Version: 3.7.3
User: siddiq90
Buildtest Settings
________________________________________________________________________________
Buildtest Settings: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/settings/config.yml
Executors: ['local.bash', 'local.sh', 'local.csh', 'local.zsh', 'local.python']
Buildspec Cache File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/var/buildspecs/cache.json
Buildtest Schemas
________________________________________________________________________________
Available Schemas: ['script-v1.0.schema.json', 'compiler-v1.0.schema.json', 'global.schema.json', 'settings.schema.json']
Example Configurations¶
buildtest provides a few example configurations for configuring buildtest this
can be retrieved by running buildtest schema -n settings.schema.json --examples
or short option (-e), which will validate each example with schema file
settings.schema.json.
$ buildtest schema -n settings.schema.json -e
File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/schemas/examples/settings.schema.json/valid/local-executor.yml
________________________________________________________________________________
system:
generic:
hostnames: ['.*']
logdir: $BUILDTEST_ROOT/logs
testdir: $BUILDTEST_ROOT/tests
moduletool: N/A
load_default_buildspecs: False
cdash:
url: https://my.cdash.org
project: buildtest
site: laptop
processor:
numcpus: 8
cores: 4
threads_per_core: 2
sockets: 1
model: "Intel(R) Core(TM) i7-8569U CPU @ 2.80GHz"
executors:
local:
bash:
description: submit jobs on local machine using bash shell
shell: bash
before_script: |
time
echo "commands run before job"
sh:
description: submit jobs on local machine using sh shell
shell: sh
csh:
description: submit jobs on local machine using csh shell
shell: csh -x
tcsh:
description: submit jobs on local machine using tcsh shell
shell: /bin/tcsh
zsh:
description: submit jobs on local machine using zsh shell
shell: /bin/zsh
python:
description: submit jobs on local machine using python shell
shell: python
compilers:
find:
gcc: "^(gcc|GCC|PrgEnv-gnu)"
intel: "^(intel|Intel|PrgEnv-intel)"
cray: "^(cray|PrgEnv-cray)"
clang: "^(clang|Clang)"
cuda: "^(cuda|CUDA)"
pgi: "^(pgi|PGI|PrgEnv-pgi)"
compiler:
gcc:
default:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
fc: /usr/bin/gfortran
gcc@7.2.0:
cc: 'cc'
cxx: 'cxx'
fc: 'fc'
module:
load:
- gcc/7.2.0
intel:
intel@2019:
cc: 'icc'
cxx: 'icpc'
fc: 'ifort'
module:
purge: True
load:
- gcc/7.2.0
- intel/2019
cray:
craype@2.6.2:
cc: 'cc'
cxx: 'CC'
fc: 'fc'
module:
load: [craype/2.6.2]
swap: [PrgEnv-gnu, PrgEnv-cray]
clang:
clang@12.0.0:
cc: 'clang'
cxx: 'clang++'
fc: 'None'
module:
load: [clang/12.0]
cuda:
cuda@11.0:
cc: 'nvcc'
cxx: 'nvcc'
fc: 'None'
module:
load: [cuda/11.0]
pgi:
pgi@18.0:
cc: 'pgcc'
cxx: 'pgc++'
fc: 'pgfortran'
module:
load: [pgi/18.0]
File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/schemas/examples/settings.schema.json/valid/cobalt-example.yml
________________________________________________________________________________
system:
generic:
hostnames: ['.*']
moduletool: lmod
load_default_buildspecs: True
executors:
defaults:
launcher: qsub
max_pend_time: 30
cobalt:
knl:
queue: knl
haswell:
queue: haswell
compilers:
compiler:
gcc:
default:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
fc: /usr/bin/gfortran
File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/schemas/examples/settings.schema.json/valid/pbs-example.yml
________________________________________________________________________________
system:
generic:
hostnames: ['.*']
moduletool: N/A
load_default_buildspecs: True
executors:
defaults:
pollinterval: 10
launcher: qsub
max_pend_time: 30
pbs:
workq:
queue: workq
compilers:
compiler:
gcc:
default:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
fc: /usr/bin/gfortran
File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/schemas/examples/settings.schema.json/valid/slurm-example.yml
________________________________________________________________________________
system:
generic:
hostnames: ['.*']
moduletool: lmod
load_default_buildspecs: True
buildspec_roots:
- $HOME/buildtest-cori
testdir: /tmp/buildtest
executors:
defaults:
pollinterval: 20
launcher: sbatch
max_pend_time: 30
account: admin
slurm:
normal:
options: ["-C haswell"]
qos: normal
before_script: |
time
echo "commands run before job"
compilers:
compiler:
gcc:
default:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
fc: /usr/bin/gfortran
File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/schemas/examples/settings.schema.json/valid/combined_executor.yml
________________________________________________________________________________
system:
generic:
hostnames: ['.*']
moduletool: N/A
load_default_buildspecs: True
executors:
local:
bash:
description: submit jobs on local machine
shell: bash -v
slurm:
haswell:
launcher: sbatch
options:
- "-p haswell"
- "-t 00:10"
lsf:
batch:
launcher: bsub
queue: batch
options:
- "-q batch"
- "-t 00:10"
cobalt:
normal:
launcher: qsub
queue: normal
options:
- "-n 1"
- "-t 10"
compilers:
compiler:
gcc:
default:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
fc: /usr/bin/gfortran
File: /Users/siddiq90/Documents/GitHubDesktop/buildtest/buildtest/schemas/examples/settings.schema.json/valid/lsf-example.yml
________________________________________________________________________________
system:
generic:
hostnames: ['.*']
moduletool: lmod
load_default_buildspecs: False
executors:
defaults:
pollinterval: 10
launcher: bsub
max_pend_time: 45
lsf:
batch:
description: "LSF Executor name 'batch' that submits jobs to 'batch' queue"
queue: batch
account: developer
options: ["-W 20"]
before_script: |
time
echo "commands run before job"
test:
description: "LSF Executor name 'test' that submits jobs to 'test' queue"
launcher: bsub
queue: test
account: qa
options: ["-W 20"]
compilers:
compiler:
gcc:
default:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
fc: /usr/bin/gfortran
If you want to retrieve full json schema file for buildtest configuration you can
run buildtest schema -n settings.schema.json --json or short option -j.