Basic usage

Once PCVS is installed through the Installation Guide, the pcvs is available in PATH. This program is the only entry point to PCVS:

$ pcvs

Usage: pcvs [OPTIONS] COMMAND [ARGS]...

PCVS main program.

  Options
 --verbose      -v             INTEGER RANGE  Enable PCVS verbosity (cumulative) [env var: PCVS_VERBOSE]
 --debug        -d                            Enable Debug mode (implies `-vvv`) [env var: PCVS_DEBUG]
 --color        -c/--no-color                 Use colors to beautify the output [env var: PCVS_COLOR]
 --glyph        -g/--no-glyph                 enable/disable Unicode glyphs [env var: PCVS_ENCODING]
 --exec-path    -C             DIRECTORY      [env var: PCVS_EXEC_PATH]
 --version      -V                            Display current version
 --plugin-path  -P             PATH           Default Plugin path prefix [env var: PCVS_PLUGIN_PATH]
 --plugin       -m             TEXT
 --tui          -t                            Use a TUI-based interface. [env var: PCVS_TUI]
 --help         -help,-h                      Show this message and exit.

  Commands
 bank                      Persistent data repository management
 check                     Ensure future input will be compliant with standards
 clean                     Remove artifacts generated from PCVS
 config                    Manage Configuration blocks
 convert                   YAML to YAML converter
 exec                      Running aspecific test
 graph                     Export graph from tests results.
 profile                   Manage Profiles
 remote-run                Internal command to re-run a PCVS instance. Should not be used directly
 report                    Manage PCVS result reporting interface
 run                       Run a validation
 scan                      Analyze directories to build up test conf. files
 session                   Manage multiple validations

Create a profile

A profile contains the whole PCVS configuration in a single place. While this approach allow deeply complex approaches, we will target a simple MPI implementation for this example. To create the most basic profile able to run MPI programs, we may herit ours from pre-generated called a template:

$ pcvs profile create -t mpi user.myprofile

This profile can not be references with user.myprofile (or myprofile in short, where there are no possible conflicts. This profile will be available at user-level scope. It is also possible to set this profile as local (only for the current directory or global (anyone using the PCVS installation)). You may replace newprofile by a name of your choice. For a complete list of available templates, please check pcvs profile list --all.

A profile can be edited if necessary with pcvs profile edit newprofile. It will open an $EDITOR. When exiting, the profile is validated to ensure coherency. In case it does not fulfill a proper format, a rejection file is crated in the current directory. Once fixed, the profile can be saved as a replacement with:

$ pcvs profile import newprofile --force --source file.yml

Warning

The --force option will overwrite any profile with the same name, if it exists. Please use this option with care. In case of a rejection, the import needs to be forced in order to replace the old one.

Implement job descriptions

For a short example of implementing test descriptions, please refer to the Test-suite layout shown in the Getting Started guide. A more detailed presentation of test description capabilities is available in its own documentation page.

The most basic pcvs.yml file may look like this:

my_program:
    build:
        files: ['main.c']
    run:
        program: ['a.out']

PCVS also supports building programs through Make, CMake & Autotools, each system having its own set of keys to configure:

  • build.make.target: allow configuring a Make target to invoke.

  • build.cmake.vars: variables to forward to cmake (to be prefixed w/ -D)

  • build.autotools.params: configure script flags

  • build.autotools.autogen: boolean whether to execute autogen.sh first.

Proper YAML formats can be checked before running a test-suite with:

$ pcvs check --directory /path/to/dir
$ pcvs check --profiles

Run a test-suite

Start a run from the local directory with our profile is as simple as:

$ pcvs run --profile newprofile

A list of directories can also be given. Once started, the validation process is logged under $PWD/.pcvs-build directory. If the directory already exists, it is cleaned up and reused. A lock is put in that directory to protect against concurrent PCVS execution in the same directory.