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
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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 buildtest config view which will print content of buildtest configuration.

$ 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: gcc
        fc: gfortran
        cxx: g++
cdash:
  url: https://my.cdash.org/
  project: buildtest
  site: generic
  buildname: tutorials

________________________________________________________________________________
Settings File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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.6
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: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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
File: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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: /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/v0.10.1/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

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.