Installation

cijoe is distributed as a Python package (named cijoe) via the Python Package Index (PyPi). Extensions to cijoe are referred to as cijoe packages, these are conventionally named cijoe-pkg-<project_name>.

Install cijoe, in a virtual-environment via pipx, along with a couple of useful cijoe packages:

python3 -m pipx install cijoe --include-deps
python3 -m pipx inject cijoe cijoe-pkg-qemu
python3 -m pipx inject cijoe cijoe-pkg-linux

Note

Make sure that you follow the recommendation above. The --include-deps ensure that the pytest CLI is made available alongside cijoe. And by having both in the same virtual environment, then pytest can use the cijoe pytest-plugin and cijoe can invoke the pytest CLI.

Installation of Python packages via pip should be done in a virtual environment. For command-line utilities such as cijoe then pipx provides a convenient means, designed for exactly this usecase, to setup the virtual environment and make the command-line utilities provided within available as any other command-line utility. It is thus the recommended approach for cijoe.

Check installation

Check that it installed correctly, by invoking the cijoe command-line tool:

cijoe --help

It should provide a usage page that looks like this:

usage: cijoe [-h] [--config CONFIG] [--workflow WORKFLOW] [--output OUTPUT]
             [--force] [--log-level] [--monitor] [--produce-report]
             [--integrity-check] [--resources] [--example [EXAMPLE]]
             [--version]
             [step ...]

optional arguments:
  -h, --help            show this help message and exit

workflow:
  Run workflow at -w with config at -c output at -o

  step                  One or more workflow steps to run. (default: None)
  --config CONFIG, -c CONFIG
                        Path to the Configuration file. (default:
                        /home/safl/git/joe/cijoe/docs/default.config)
  --workflow WORKFLOW, -w WORKFLOW
                        Path to workflow file. (default:
                        /home/safl/git/joe/cijoe/docs/example.workflow)
  --output OUTPUT, -o OUTPUT
                        Path to output directory. (default:
                        /home/safl/git/joe/cijoe/docs/cijoe-output)
  --force, -f           Force execution even though '-o / --output' exists
                        (moving it) (default: False)
  --log-level, -l       Increase log-level. (default: None)
  --monitor, -m         Monitor workflow-output at '-o / --output'. (default:
                        False)

utilities:
  Workflow, and workflow-related utilities

  --produce-report, -p  Produce report for workflow-output at '-o / --output'
                        and exit. (default: None)
  --integrity-check, -i
                        Check integrity of workflow at '-w / --workflow' and
                        exit. (default: False)
  --resources, -r       List collected resources and exit. (default: False)
  --example [EXAMPLE], -e [EXAMPLE]
                        Create 'default.config' and 'example.workflow' and
                        exit. (default: None)
  --version, -v         Print the version number of 'cijoe' and exit.
                        (default: False)

If this does not produce the help-page as above, then ensure that pipx is installed and your PATH setup correctly. For example, by running the following:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

And then reload your shell.

Once you have verified that cijoe is installed correctly and that you can execute the command-line tool, then procede to Workflows.