Command Line Interface to buildtest configuration (buildtest config)

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

  
    edit (e)       Open configuration file in editor
    path (p)       Show path to configuration file
    systems        List all available systems
    validate (val)
                   Validate buildtest settings file with schema.
    view (v)       View configuration file
    profiles (prof)
                   Query profile from buildtest configuration
    executors (ex)
                   Query executors from buildtest configuration
    compilers (co)
                   Search compilers

Note

buildtest cg is an alias for buildtest config command.

Validate buildtest configuration (buildtest config validate)

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
/tmp/tmp67fr8ygs/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 received a value of none:

Invalid buildtest configuration
$ 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 (buildtest config view)

If you want to view buildtest configuration you can run buildtest config view which will print content of buildtest configuration.

buildtest config view
$ buildtest config view
───────────────────────── /tmp/tmp67fr8ygs/config.yml ──────────────────────────
   1 system:
   2   generic:
   3     # specify a list of hostnames that is a regular expression where buildtest can run.
   4     hostnames: ['.*']
   5     # system description
   6     description: Generic System
   7     # specify module system to use. Supported module systems are [lmod, environment-modules, none]
   8     moduletool: none
   9 
  10     # specify size of job pool (https://docs.python.org/3/library/multiprocessing.html#multiprocessing.pool.Pool). This will configure the number of processes that can run in parallel.
  11     # If not specified then buildtest will use all available cores on the system.
  12     poolsize: 1
  13 
  14     # maximum number of jobs that can run in parallel. If not specified, buildtest will run all jobs in parallel.
  15     #max_jobs: 1
  16 
  17     # test timeout in number of seconds
  18     # timeout: 3600
  19 
  20     # enable pagination for buildtest
  21     pager: false
  22 
  23     # options for buildtest buildspec find command
  24     buildspecs:
  25       # determine whether to rebuild buildspec cache
  26       rebuild: false
  27       # determine number of records to display
  28       count: 15
  29 
  30       # specify format fields
  31       #format: name,description
  32 
  33       # display output in terse mode
  34       terse: false
  35 
  36       # list of paths to search for buildspecs
  37       #root: ["$BUILDTEST_ROOT/tutorials", "$BUILDTEST_ROOT/examples"]
  38 
  39     # options for buildtest report command
  40     report:
  41       # number of records to display
  42       count: 25
  43       # display output in terse mode
  44       terse: false
  45       # specify format fields
  46       format: name,id,state,runtime,returncode
  47 
  48     # start of executor configuration
  49     executors:
  50       # local executor is used to submit jobs on local machine. In this example we have 4 executors: bash, sh, csh, zsh that will submit jobs using bash, sh, csh, zsh shell respectively.
  51       local:
  52         bash:
  53           description: submit jobs on local machine using bash shell
  54           shell: bash
  55         sh:
  56           description: submit jobs on local machine using sh shell
  57           shell: sh
  58         csh:
  59           description: submit jobs on local machine using csh shell
  60           shell: csh
  61         zsh:
  62           description: submit jobs on local machine using zsh shell
  63           shell: zsh
  64     # specify compiler declaration
  65     compilers:
  66       compiler:
  67         # declaration of all gcc compilers
  68         gcc:
  69           # name of compiler
  70           builtin_gcc:
  71             cc: gcc
  72             fc: gfortran
  73             cxx: g++
  74     # specify CDASH configuration when using 'buildtest cdash upload'
  75     cdash:
  76       # CDASH server
  77       url: https://my.cdash.org/
  78       # name of CDASH project where to push test reports
  79       project: buildtest
  80       # specify the site name which should generally by name of your HPC system. This is used by CDASH to group test results by site
  81       site: generic
  82       # specify the build name which is used to group test results by build name
  83       buildname: tutorials
  84

The --theme option can be used to change the color theme of the output. The default theme is monokai and list of available themes can be retrieved with tab completion for option buildtest config view --theme.

Check path to buildtest configuration file (buildtest config path)

If you want to check path to buildtest configuration file you can run buildtest config path which will print path of buildtest configuration file.

$ buildtest config path
/tmp/tmp67fr8ygs/config.yml

Edit buildtest configuration (buildtest config edit)

The buildtest config edit command is used to open buildtest configuration file in your preferred editor. buildtest will use the environment EDITOR to get the preffered editor; however, one can override the environment variable via command line option buildtest --editor.

View Executors (buildtest config executors list)

You can use the command buildtest config executors list to view executors from buildtest configuration file. Shown below is the command usage

buildtest config executors list --help
$ buildtest config executors list --help
usage: buildtest [options] [COMMANDS] config executors list
       [-h] [-j | -y | -d | -i | -a]

optional arguments:
  -h, --help      show this help message and exit
  -j, --json      View executor in JSON format
  -y, --yaml      View executors in YAML format
  -d, --disabled  Show disabled executors
  -i, --invalid   Show invalid executors
  -a, --all       Show all executors

You can run buildtest config executors list without any options and it will report a list of named executors that you would reference in buildspec using the executor property.

$ buildtest config executors list
generic.local.bash
generic.local.sh
generic.local.csh
generic.local.zsh

If you want to see the executor details, you may want to use --json or --yaml option which will show the executor settings in YAML or JSON format. Shown below is an example output

buildtest config executors list --yaml
$ buildtest config executors list --yaml
executors:
  local:
    bash:
      description: submit jobs on local machine using bash shell
      shell: bash
    csh:
      description: submit jobs on local machine using csh shell
      shell: csh
    sh:
      description: submit jobs on local machine using sh shell
      shell: sh
    zsh:
      description: submit jobs on local machine using zsh shell
      shell: zsh
buildtest config executors list --json
$ buildtest config executors list --json
{
  "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"
      }
    }
  }
}

Note

The command options for buildtest config executors list are mutually exclusive, so if you specify multiple options you will get the following error.

$ buildtest config executors list --json --yaml
usage: buildtest [options] [COMMANDS] config executors list
       [-h] [-j | -y | -d | -i | -a]
buildtest [options] [COMMANDS] config executors list: error: argument -y/--yaml: not allowed with argument -j/--json

Remove Executors (buildtest config executors remove)

The buildtest config executors remove command will remove an executor from buildtest configuration file. The positional arguments are the name of the executor you want to remove. Tab completion is available to retrieve all available executors (buildtest config executors list --all).

Shown below we see tab completion on available executors that can be removed.

  buildtest config executors remove
generic.local.bash  generic.local.csh   generic.local.sh    generic.local.zsh

Let’s try listing all executors and remove generic.local.zsh executor, you will notice after deletion, the configuration file is updated and the executor is no longer present.

Removing executor ‘generic.local.zsh’
$ buildtest --config $BUILDTEST_CI_DIR/config.yml config executors list --all
generic.local.bash
generic.local.sh
generic.local.csh
generic.local.zsh
$ buildtest --config $BUILDTEST_CI_DIR/config.yml config executors remove generic.local.zsh
Removing executor: generic.local.zsh
Updating configuration file: /tmp/tmp67fr8ygs/config.yml

Upon deletion, buildtest will validate the configuration before writing the changes back to disk, to ensure the configuration is valid. Shown below we demonstrate an example where we attempt to remove all executors from the configuration file. Buildtest expects there is atleast 1 executor definition for local executor.

buildtest config executors remove generic.local.bash generic.local.sh generic.local.csh generic.local.zsh
$ buildtest config executors remove generic.local.bash generic.local.sh generic.local.csh generic.local.zsh
Removing executor: generic.local.bash
Removing executor: generic.local.sh
Removing executor: generic.local.csh
Unable to remove executor: generic.local.zsh because there are no executors of type: local
╭───────────────────── Traceback (most recent call last) ──────────────────────╮
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/latest/ │
│ bin/buildtest:38 in <module>                                                 │
│                                                                              │
│   35                                                                         │
│   36 if __name__ == "__main__":                                              │
│   37                                                                         │
│ ❱ 38   sys.exit(main())                                                      │
│   39                                                                         │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │ buildtest_file = '/home/docs/checkouts/readthedocs.org/user_builds/buil… │ │
│ │           main = <function main at 0x7fbdddddfee0>                       │ │
│ │             os = <module 'os' from                                       │ │
│ │                  '/home/docs/.asdf/installs/python/3.8.18/lib/python3.8… │ │
│ │         prefix = '/home/docs/checkouts/readthedocs.org/user_builds/buil… │ │
│ │            sys = <module 'sys' (built-in)>                               │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/latest/ │
│ buildtest/main.py:313 in main                                                │
│                                                                              │
│   310 │   │   if args.config in ["compilers", "co"]:                         │
│   311 │   │   │   compiler_cmd(args, configuration)                          │
│   312 │   │   else:                                                          │
│ ❱ 313 │   │   │   config_cmd(args, configuration, buildtest_editor, system)  │
│   314 │                                                                      │
│   315 │   # buildtest report                                                 │
│   316 │   elif args.subcommands in ["report", "rt"]:                         │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │             args = Namespace(color=None, config='executors',             │ │
│ │                    configfile=None, debug=False, editor=None,            │ │
│ │                    executor_names=['generic.local.bash',                 │ │
│ │                    'generic.local.sh', 'generic.local.csh',              │ │
│ │                    'generic.local.zsh'], executors='remove',             │ │
│ │                    helpcolor=False, listopts=False, loglevel='DEBUG',    │ │
│ │                    logpath=False, no_color=False, print_log=False,       │ │
│ │                    report=None, subcommands='config', verbose=False,     │ │
│ │                    view_log=False)                                       │ │
│ │ buildtest_editor = '/usr/bin/vim'                                        │ │
│ │      config_file = None                                                  │ │
│ │    configuration = <buildtest.config.SiteConfiguration object at         │ │
│ │                    0x7fbddbf61940>                                       │ │
│ │           logger = <Logger buildtest (DEBUG)>                            │ │
│ │         no_color = False                                                 │ │
│ │           parser = <buildtest.cli.BuildTestParser object at              │ │
│ │                    0x7fbddde83a90>                                       │ │
│ │      report_file = None                                                  │ │
│ │           system = <buildtest.system.BuildTestSystem object at           │ │
│ │                    0x7fbddbf09850>                                       │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/latest/ │
│ buildtest/cli/config.py:48 in config_cmd                                     │
│                                                                              │
│    45 │   │   │   │   all_executors=args.all,                                │
│    46 │   │   │   )                                                          │
│    47 │   │   if args.executors in ["remove", "rm"]:                         │
│ ❱  48 │   │   │   remove_executors(configuration, args.executor_names)       │
│    49 │                                                                      │
│    50 │   elif args.config in ["validate", "val"]:                           │
│    51 │   │   validate_config(configuration, system.system["moduletool"])    │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │          args = Namespace(color=None, config='executors',                │ │
│ │                 configfile=None, debug=False, editor=None,               │ │
│ │                 executor_names=['generic.local.bash',                    │ │
│ │                 'generic.local.sh', 'generic.local.csh',                 │ │
│ │                 'generic.local.zsh'], executors='remove',                │ │
│ │                 helpcolor=False, listopts=False, loglevel='DEBUG',       │ │
│ │                 logpath=False, no_color=False, print_log=False,          │ │
│ │                 report=None, subcommands='config', verbose=False,        │ │
│ │                 view_log=False)                                          │ │
│ │ buildexecutor = [buildtest-executor]                                     │ │
│ │ configuration = <buildtest.config.SiteConfiguration object at            │ │
│ │                 0x7fbddbf61940>                                          │ │
│ │        editor = '/usr/bin/vim'                                           │ │
│ │        system = <buildtest.system.BuildTestSystem object at              │ │
│ │                 0x7fbddbf09850>                                          │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/latest/ │
│ buildtest/cli/config.py:337 in remove_executors                              │
│                                                                              │
│   334 │   │   console.print(f"Removing executor: {name}")                    │
│   335 │   │   write_back = True                                              │
│   336 │                                                                      │
│ ❱ 337 │   custom_validator(                                                  │
│   338 │   │   configuration.config, schema_table["settings.schema.json"]["re │
│   339 │   )                                                                  │
│   340                                                                        │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │  configuration = <buildtest.config.SiteConfiguration object at           │ │
│ │                  0x7fbddbf61940>                                         │ │
│ │      exec_name = 'zsh'                                                   │ │
│ │      exec_type = 'local'                                                 │ │
│ │ executor_names = [                                                       │ │
│ │                  │   'generic.local.bash',                               │ │
│ │                  │   'generic.local.sh',                                 │ │
│ │                  │   'generic.local.csh',                                │ │
│ │                  │   'generic.local.zsh'                                 │ │
│ │                  ]                                                       │ │
│ │           name = 'generic.local.zsh'                                     │ │
│ │     write_back = True                                                    │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/latest/ │
│ buildtest/schemas/defaults.py:102 in custom_validator                        │
│                                                                              │
│    99 │   assert isinstance(schema, dict)                                    │
│   100 │                                                                      │
│   101 │   validator = Draft7Validator(schema, resolver=resolver)             │
│ ❱ 102 │   validator.validate(recipe)                                         │
│   103                                                                        │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │    recipe = {                                                            │ │
│ │             │   'system': {                                              │ │
│ │             │   │   'generic': {                                         │ │
│ │             │   │   │   'hostnames': ['.*'],                             │ │
│ │             │   │   │   'description': 'Generic System',                 │ │
│ │             │   │   │   'moduletool': 'none',                            │ │
│ │             │   │   │   'poolsize': 1,                                   │ │
│ │             │   │   │   'pager': False,                                  │ │
│ │             │   │   │   'buildspecs': {                                  │ │
│ │             │   │   │   │   'rebuild': False,                            │ │
│ │             │   │   │   │   'count': 15,                                 │ │
│ │             │   │   │   │   'terse': False                               │ │
│ │             │   │   │   },                                               │ │
│ │             │   │   │   'report': {                                      │ │
│ │             │   │   │   │   'count': 25,                                 │ │
│ │             │   │   │   │   'terse': False,                              │ │
│ │             │   │   │   │   'format': 'name,id,state,runtime,returncode' │ │
│ │             │   │   │   },                                               │ │
│ │             │   │   │   'executors': {},                                 │ │
│ │             │   │   │   'compilers': {                                   │ │
│ │             │   │   │   │   'compiler': {                                │ │
│ │             │   │   │   │   │   'gcc': {                                 │ │
│ │             │   │   │   │   │   │   'builtin_gcc': {                     │ │
│ │             │   │   │   │   │   │   │   'cc': 'gcc',                     │ │
│ │             │   │   │   │   │   │   │   'fc': 'gfortran',                │ │
│ │             │   │   │   │   │   │   │   'cxx': 'g++'                     │ │
│ │             │   │   │   │   │   │   }                                    │ │
│ │             │   │   │   │   │   }                                        │ │
│ │             │   │   │   │   }                                            │ │
│ │             │   │   │   },                                               │ │
│ │             │   │   │   'cdash': {                                       │ │
│ │             │   │   │   │   'url': 'https://my.cdash.org/',              │ │
│ │             │   │   │   │   'project': 'buildtest',                      │ │
│ │             │   │   │   │   'site': 'generic',                           │ │
│ │             │   │   │   │   'buildname': 'tutorials'                     │ │
│ │             │   │   │   }                                                │ │
│ │             │   │   }                                                    │ │
│ │             │   }                                                        │ │
│ │             }                                                            │ │
│ │    schema = {                                                            │ │
│ │             │   '$id': 'settings.schema.json',                           │ │
│ │             │   '$schema': 'http://json-schema.org/draft-07/schema#',    │ │
│ │             │   'title': 'buildtest configuration schema',               │ │
│ │             │   'type': 'object',                                        │ │
│ │             │   'required': ['system'],                                  │ │
│ │             │   'additionalProperties': False,                           │ │
│ │             │   'properties': {                                          │ │
│ │             │   │   'system': {                                          │ │
│ │             │   │   │   'type': 'object',                                │ │
│ │             │   │   │   'patternProperties': {                           │ │
│ │             │   │   │   │   '^.*$': {'$ref': '#/definitions/system'}     │ │
│ │             │   │   │   }                                                │ │
│ │             │   │   }                                                    │ │
│ │             │   },                                                       │ │
│ │             │   'definitions': {                                         │ │
│ │             │   │   'terse': {                                           │ │
│ │             │   │   │   'type': 'boolean',                               │ │
│ │             │   │   │   'description': 'A boolean to determine whether   │ │
│ │             to enable terse mode'                                        │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'format': {                                          │ │
│ │             │   │   │   'type': 'string',                                │ │
│ │             │   │   │   'description': 'Determine the format fields to   │ │
│ │             display when viewing table results'                          │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'count': {                                           │ │
│ │             │   │   │   'type': 'integer',                               │ │
│ │             │   │   │   'minimum': 1,                                    │ │
│ │             │   │   │   'description': 'Determine number of records to   │ │
│ │             display in a table'                                          │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'system': {                                          │ │
│ │             │   │   │   'required': [                                    │ │
│ │             │   │   │   │   'executors',                                 │ │
│ │             │   │   │   │   'moduletool',                                │ │
│ │             │   │   │   │   'hostnames',                                 │ │
│ │             │   │   │   │   'compilers',                                 │ │
│ │             │   │   │   │   'buildspecs',                                │ │
│ │             │   │   │   │   'report'                                     │ │
│ │             │   │   │   ],                                               │ │
│ │             │   │   │   'additionalProperties': False,                   │ │
│ │             │   │   │   'type': 'object',                                │ │
│ │             │   │   │   'properties': {                                  │ │
│ │             │   │   │   │   'hostnames': {                               │ │
│ │             │   │   │   │   │   'type': 'array',                         │ │
│ │             │   │   │   │   │   'description': 'Specify a list of        │ │
│ │             hostnames to check where buildtest can run for the given     │ │
│ │             syste'+8,                                                    │ │
│ │             │   │   │   │   │   'items': {'type': 'string'}              │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'description': {                             │ │
│ │             │   │   │   │   │   'type': 'string',                        │ │
│ │             │   │   │   │   │   'description': 'system description       │ │
│ │             field'                                                       │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'poolsize': {                                │ │
│ │             │   │   │   │   │   'type': 'integer',                       │ │
│ │             │   │   │   │   │   'minimum': 1,                            │ │
│ │             │   │   │   │   │   'description': 'Specify size of Process  │ │
│ │             Pool for parallel processing using ``multiprocessing.Poo'+3  │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'max_jobs': {                                │ │
│ │             │   │   │   │   │   'type': 'integer',                       │ │
│ │             │   │   │   │   │   'minimum': 1,                            │ │
│ │             │   │   │   │   │   'description': 'Maximum number of jobs   │ │
│ │             that can be run at a given time for a particular executor'   │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'testdir': {                                 │ │
│ │             │   │   │   │   │   'type': 'string',                        │ │
│ │             │   │   │   │   │   'description': 'Specify full path to     │ │
│ │             test directory where buildtest will write tests.'            │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'logdir': {                                  │ │
│ │             │   │   │   │   │   'type': 'string',                        │ │
│ │             │   │   │   │   │   'description': 'Specify location where   │ │
│ │             buildtest will write log files'                              │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'moduletool': {                              │ │
│ │             │   │   │   │   │   'type': 'string',                        │ │
│ │             │   │   │   │   │   'description': 'Specify modules tool     │ │
│ │             used for interacting with ``module`` command. ',             │ │
│ │             │   │   │   │   │   'enum': [                                │ │
│ │             │   │   │   │   │   │   'environment-modules',               │ │
│ │             │   │   │   │   │   │   'lmod',                              │ │
│ │             │   │   │   │   │   │   'none'                               │ │
│ │             │   │   │   │   │   ]                                        │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'timeout': {                                 │ │
│ │             │   │   │   │   │   'type': 'integer',                       │ │
│ │             │   │   │   │   │   'minimum': 1,                            │ │
│ │             │   │   │   │   │   'description': 'Specify timeout duration │ │
│ │             in number of seconds'                                        │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'pager': {                                   │ │
│ │             │   │   │   │   │   'type': 'boolean',                       │ │
│ │             │   │   │   │   │   'description': 'A boolean to determine   │ │
│ │             whether to enable paging when viewing buildspec cache'       │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   'buildspecs': {                              │ │
│ │             │   │   │   │   │   'type': 'object',                        │ │
│ │             │   │   │   │   │   'description': 'Specify configuration    │ │
│ │             for ``buildtest buildspec`` command',                        │ │
│ │             │   │   │   │   │   'additionalProperties': False,           │ │
│ │             │   │   │   │   │   'properties': {                          │ │
│ │             │   │   │   │   │   │   'rebuild': {                         │ │
│ │             │   │   │   │   │   │   │   'type': 'boolean',               │ │
│ │             │   │   │   │   │   │   │   'description': 'A boolean to     │ │
│ │             determine whether to rebuild buildspec cache'                │ │
│ │             │   │   │   │   │   │   },                                   │ │
│ │             │   │   │   │   │   │   'count': {                           │ │
│ │             │   │   │   │   │   │   │   '$ref': '#/definitions/count'    │ │
│ │             │   │   │   │   │   │   },                                   │ │
│ │             │   │   │   │   │   │   'format': {                          │ │
│ │             │   │   │   │   │   │   │   '$ref': '#/definitions/format'   │ │
│ │             │   │   │   │   │   │   },                                   │ │
│ │             │   │   │   │   │   │   'terse': {                           │ │
│ │             │   │   │   │   │   │   │   '$ref': '#/definitions/terse'    │ │
│ │             │   │   │   │   │   │   },                                   │ │
│ │             │   │   │   │   │   │   'root': {                            │ │
│ │             │   │   │   │   │   │   │   'type': 'array',                 │ │
│ │             │   │   │   │   │   │   │   'items': {'type': 'string'},     │ │
│ │             │   │   │   │   │   │   │   'description': 'Specify a list   │ │
│ │             of directory paths to search buildspecs. This field can be   │ │
│ │             used w'+108                                                  │ │
│ │             │   │   │   │   │   │   }                                    │ │
│ │             │   │   │   │   │   }                                        │ │
│ │             │   │   │   │   },                                           │ │
│ │             │   │   │   │   ... +6                                       │ │
│ │             │   │   │   }                                                │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'cc': {                                              │ │
│ │             │   │   │   'description': 'Specify path to C compiler       │ │
│ │             wrapper. You may specify a compiler wrapper such as `'+101,  │ │
│ │             │   │   │   'type': 'string'                                 │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'cxx': {                                             │ │
│ │             │   │   │   'type': 'string',                                │ │
│ │             │   │   │   'description': 'Specify path to C++ compiler     │ │
│ │             wrapper. You may specify a compiler wrapper such as'+103     │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'fc': {                                              │ │
│ │             │   │   │   'type': 'string',                                │ │
│ │             │   │   │   'description': 'Specify path to Fortran compiler │ │
│ │             wrapper. You may specify a compiler wrapper suc'+112         │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'compiler_section': {                                │ │
│ │             │   │   │   'description': 'A compiler section is composed   │ │
│ │             of ``cc``, ``cxx`` and ``fc`` wrapper these are r'+50,       │ │
│ │             │   │   │   'type': 'object',                                │ │
│ │             │   │   │   'additionalProperties': False,                   │ │
│ │             │   │   │   'required': ['cc', 'cxx', 'fc'],                 │ │
│ │             │   │   │   'properties': {                                  │ │
│ │             │   │   │   │   'cc': {'$ref': '#/definitions/cc'},          │ │
│ │             │   │   │   │   'cxx': {'$ref': '#/definitions/cxx'},        │ │
│ │             │   │   │   │   'fc': {'$ref': '#/definitions/fc'},          │ │
│ │             │   │   │   │   'module': {'$ref': '#/definitions/module'}   │ │
│ │             │   │   │   }                                                │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'unique_string_array': {                             │ │
│ │             │   │   │   'type': 'array',                                 │ │
│ │             │   │   │   'uniqueItems': True,                             │ │
│ │             │   │   │   'items': {'type': 'string'}                      │ │
│ │             │   │   },                                                   │ │
│ │             │   │   'disable': {                                         │ │
│ │             │   │   │   'type': 'boolean',                               │ │
│ │             │   │   │   'description': 'Disable an executor'             │ │
│ │             │   │   },                                                   │ │
│ │             │   │   ... +12                                              │ │
│ │             │   }                                                        │ │
│ │             }                                                            │ │
│ │ validator = Draft7Validator(                                             │ │
│ │             │   schema={'$id': 'settings.schema.json', '$schema':        │ │
│ │             'http://json-...ft-07/schema#', 'additionalProperties':      │ │
│ │             False, 'definitions': {'account': {'description': 'Specify   │ │
│ │             Job ...ing resources', 'type': 'string'}, 'cc':              │ │
│ │             {'description': 'Specify path...iler wrapper.', 'type':      │ │
│ │             'string'}, 'cobalt': {'additionalProperties': False,         │ │
│ │             'description': 'An instance ...balt executor', 'properties': │ │
│ │             {'account': {'$ref': '#/definitions/account', 'description': │ │
│ │             'overrides de...count`` value'}, 'before_script': {'#ref':   │ │
│ │             '#/definitions/script', 'description': 'The                  │ │
│ │             ``before...active shell.'}, 'description': {'$ref':          │ │
│ │             '#/definitions/description'}, 'disable': {'$ref':            │ │
│ │             '#/definitions/disable'}, ...}, 'required': ['queue'], ...}, │ │
│ │             'compiler_section': {'additionalProperties': False,          │ │
│ │             'description': 'A compiler s...iler wrapper.', 'properties': │ │
│ │             {'cc': {'$ref': '#/definitions/cc'}, 'cxx': {'$ref':         │ │
│ │             '#/definitions/cxx'}, 'fc': {'$ref': '#/definitions/fc'},    │ │
│ │             'module': {'$ref': '#/definitions/module'}}, 'required':     │ │
│ │             ['cc', 'cxx', 'fc'], ...}, ...}, ...},                       │ │
│ │             │   format_checker=None                                      │ │
│ │             )                                                            │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│                                                                              │
│ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/envs/latest/lib/p │
│ ython3.8/site-packages/jsonschema/validators.py:314 in validate              │
│                                                                              │
│    311 │   │                                                                 │
│    312 │   │   def validate(self, *args, **kwargs):                          │
│    313 │   │   │   for error in self.iter_errors(*args, **kwargs):           │
│ ❱  314 │   │   │   │   raise error                                           │
│    315 │   │                                                                 │
│    316 │   │   def is_type(self, instance, type):                            │
│    317 │   │   │   try:                                                      │
│                                                                              │
│ ╭───────────────────────────────── locals ─────────────────────────────────╮ │
│ │   args = (                                                               │ │
│ │          │   {                                                           │ │
│ │          │   │   'system': {                                             │ │
│ │          │   │   │   'generic': {                                        │ │
│ │          │   │   │   │   'hostnames': ['.*'],                            │ │
│ │          │   │   │   │   'description': 'Generic System',                │ │
│ │          │   │   │   │   'moduletool': 'none',                           │ │
│ │          │   │   │   │   'poolsize': 1,                                  │ │
│ │          │   │   │   │   'pager': False,                                 │ │
│ │          │   │   │   │   'buildspecs': {                                 │ │
│ │          │   │   │   │   │   'rebuild': False,                           │ │
│ │          │   │   │   │   │   'count': 15,                                │ │
│ │          │   │   │   │   │   'terse': False                              │ │
│ │          │   │   │   │   },                                              │ │
│ │          │   │   │   │   'report': {                                     │ │
│ │          │   │   │   │   │   'count': 25,                                │ │
│ │          │   │   │   │   │   'terse': False,                             │ │
│ │          │   │   │   │   │   'format':                                   │ │
│ │          'name,id,state,runtime,returncode'                              │ │
│ │          │   │   │   │   },                                              │ │
│ │          │   │   │   │   'executors': {},                                │ │
│ │          │   │   │   │   'compilers': {                                  │ │
│ │          │   │   │   │   │   'compiler': {                               │ │
│ │          │   │   │   │   │   │   'gcc': {                                │ │
│ │          │   │   │   │   │   │   │   'builtin_gcc': {                    │ │
│ │          │   │   │   │   │   │   │   │   'cc': 'gcc',                    │ │
│ │          │   │   │   │   │   │   │   │   'fc': 'gfortran',               │ │
│ │          │   │   │   │   │   │   │   │   'cxx': 'g++'                    │ │
│ │          │   │   │   │   │   │   │   }                                   │ │
│ │          │   │   │   │   │   │   }                                       │ │
│ │          │   │   │   │   │   }                                           │ │
│ │          │   │   │   │   },                                              │ │
│ │          │   │   │   │   'cdash': {                                      │ │
│ │          │   │   │   │   │   'url': 'https://my.cdash.org/',             │ │
│ │          │   │   │   │   │   'project': 'buildtest',                     │ │
│ │          │   │   │   │   │   'site': 'generic',                          │ │
│ │          │   │   │   │   │   'buildname': 'tutorials'                    │ │
│ │          │   │   │   │   }                                               │ │
│ │          │   │   │   }                                                   │ │
│ │          │   │   }                                                       │ │
│ │          │   },                                                          │ │
│ │          )                                                               │ │
│ │  error = <ValidationError: "'local' is a required property">             │ │
│ │ kwargs = {}                                                              │ │
│ │   self = Draft7Validator(                                                │ │
│ │          │   schema={'$id': 'settings.schema.json', '$schema':           │ │
│ │          'http://json-...ft-07/schema#', 'additionalProperties': False,  │ │
│ │          'definitions': {'account': {'description': 'Specify Job ...ing  │ │
│ │          resources', 'type': 'string'}, 'cc': {'description': 'Specify   │ │
│ │          path...iler wrapper.', 'type': 'string'}, 'cobalt':             │ │
│ │          {'additionalProperties': False, 'description': 'An instance     │ │
│ │          ...balt executor', 'properties': {'account': {'$ref':           │ │
│ │          '#/definitions/account', 'description': 'overrides de...count`` │ │
│ │          value'}, 'before_script': {'#ref': '#/definitions/script',      │ │
│ │          'description': 'The ``before...active shell.'}, 'description':  │ │
│ │          {'$ref': '#/definitions/description'}, 'disable': {'$ref':      │ │
│ │          '#/definitions/disable'}, ...}, 'required': ['queue'], ...},    │ │
│ │          'compiler_section': {'additionalProperties': False,             │ │
│ │          'description': 'A compiler s...iler wrapper.', 'properties':    │ │
│ │          {'cc': {'$ref': '#/definitions/cc'}, 'cxx': {'$ref':            │ │
│ │          '#/definitions/cxx'}, 'fc': {'$ref': '#/definitions/fc'},       │ │
│ │          'module': {'$ref': '#/definitions/module'}}, 'required': ['cc', │ │
│ │          'cxx', 'fc'], ...}, ...}, ...},                                 │ │
│ │          │   format_checker=None                                         │ │
│ │          )                                                               │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────╯
ValidationError: 'local' is a required property

Failed validating 'required' in 
schema['properties']['system']['patternProperties']['^.*$']['properties']['execu
tors']:
    {'additionalProperties': False,
     'description': 'The executor section is used for declaring your '
                    'executors that are responsible for running jobs. The '
                    'executor section can be ``local``, ``lsf``, '
                    '``slurm``, ``cobalt``. The executors are referenced '
                    'in buildspec using ``executor`` field.',
     'properties': {'cobalt': {'additionalProperties': {'$ref': 
'#/definitions/cobalt'},
                               'description': 'The ``cobalt`` section is '
                                              'used for declaring Cobalt '
                                              'executors for running jobs '
                                              'using Cobalt scheduler',
                               'propertyNames': {'pattern': 
'^[A-Za-z0-9_.-]+$'},
                               'type': 'object'},
                    'container': {'additionalProperties': {'$ref': 
'#/definitions/container'},
                                  'description': 'The ``container`` '
                                                 'section is used for '
                                                 'declaring container '
                                                 'executors for running '
                                                 'jobs using container '
                                                 'technology',
                                  'propertyNames': {'pattern': 
'^[A-Za-z0-9_.-]+$'},
                                  'type': 'object'},
                    'defaults': {'additionalProperties': False,
                                 'description': 'Specify default executor '
                                                'settings for all '
                                                'executors',
                                 'properties': {'account': {'$ref': 
'#/definitions/account'},
                                                'maxpendtime': {'$ref': 
'#/definitions/maxpendtime'},
                                                'pollinterval': {'default': 30,
                                                                 'description': 
'Specify '
                                                                                
'poll '
                                                                                
'interval '
                                                                                
'in '
                                                                                
'seconds '
                                                                                
'after '
                                                                                
'job '
                                                                                
'submission, '
                                                                                
'where '
                                                                                
'buildtest '
                                                                                
'will '
                                                                                
'sleep '
                                                                                
'and '
                                                                                
'poll '
                                                                                
'all '
                                                                                
'jobs '
                                                                                
'for '
                                                                                
'job '
                                                                                
'states. '
                                                                                
'This '
                                                                                
'field '
                                                                                
'can '
                                                                                
'be '
                                                                                
'configured '
                                                                                
'based '
                                                                                
'on '
                                                                                
'your '
                                                                                
'preference. '
                                                                                
'Excessive '
                                                                                
'polling '
                                                                                
'every '
                                                                                
'few '
                                                                                
'seconds '
                                                                                
'can '
                                                                                
'result '
                                                                                
'in '
                                                                                
'system '
                                                                                
'degradation. ',
                                                                 'minimum': 1,
                                                                 'type': 
'integer'}},
                                 'type': 'object'},
                    'local': {'additionalProperties': {'$ref': 
'#/definitions/local'},
                              'description': 'The ``local`` section is '
                                             'used for declaring local '
                                             'executors for running jobs '
                                             'on local machine',
                              'minProperties': 1,
                              'propertyNames': {'pattern': '^[A-Za-z0-9_.-]+$'},
                              'type': 'object'},
                    'lsf': {'additionalProperties': {'$ref': 
'#/definitions/lsf'},
                            'description': 'The ``lsf`` section is used '
                                           'for declaring LSF executors '
                                           'for running jobs using LSF '
                                           'scheduler',
                            'propertyNames': {'pattern': '^[A-Za-z0-9_.-]+$'},
                            'type': 'object'},
                    'pbs': {'additionalProperties': {'$ref': 
'#/definitions/pbs'},
                            'description': 'The ``pbs`` section is used '
                                           'for declaring PBS executors '
                                           'for running jobs using PBS '
                                           'scheduler',
                            'propertyNames': {'pattern': '^[A-Za-z0-9_.-]+$'},
                            'type': 'object'},
                    'slurm': {'additionalProperties': {'$ref': 
'#/definitions/slurm'},
                              'description': 'The ``slurm`` section is '
                                             'used for declaring Slurm '
                                             'executors for running jobs '
                                             'using Slurm scheduler',
                              'propertyNames': {'pattern': '^[A-Za-z0-9_.-]+$'},
                              'type': 'object'},
                    'torque': {'additionalProperties': {'$ref': 
'#/definitions/pbs'},
                               'description': 'The ``torque`` section is '
                                              'used for declaring '
                                              'PBS/Torque executors for '
                                              'running jobs using Torque '
                                              'scheduler',
                               'propertyNames': {'pattern': 
'^[A-Za-z0-9_.-]+$'},
                               'type': 'object'}},
     'required': ['local'],
     'type': 'object'}

On instance['system']['generic']['executors']:
    {}

View Registered Systems (buildtest config 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 Summary (Configuration=/tmp/tmp67fr8ygs/config.yml)           
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ system        ┃ description             ┃ moduletool        ┃ hostnames      ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ generic       │ Generic System          │ none              │ .*             │
└───────────────┴─────────────────────────┴───────────────────┴────────────────┘