# Runners

Runners are responsible to execute a list of commands in a set environment defined in the CI yaml file.

## List of runners

* Python - executes python commands in a virtual environment
* Docker - executes each job in a separate Docker container - unimplemented

## Import schema

What you need to do to make Alice recognise and import your custom Runners
TODO

## Runner API

Each runner has to support the following functions:

### __init__(params, config)

* params: dict of runtime variables for the program itself.
* config: Runner config data, aplies to all jobs

#### Params

Currently the only param used is the dict is "verbose", whichis a boolean. The intended purpose is to show debug output if set to True.

#### config

Dict. Has two fix keys, `env` and `workdir`. Env is the environment variables of the host, expanded by CLI parameters, expanded by global config values from yaml. A key defined in the yaml overwrites the value copied from the host. Workdir is similar, can be assigned at CI yaml level as global, but runners may overwrite it.
Order:
    By default: os.cwd()
    if overwritten in global
    ------------------------------- Below this level is the runner's responsibility
    if owerwritten in runner config
    if overwritten in job

Runner shall receive the current working directory, unless stated otherwise in global config.

The expected behaviour of "overwriting" the workdir is adding the new directory name to the existing path. For example:
 * cwd = /root
 * global defines workdir as "projects"
 * runner config defines workdir as "python"
 * job defines workdir as "alice"

 In the case above, the actual working directory of the running job shall be `/root/projects/python/alice`.

### run(job_spec)

This function executes one job attributed ith the type of the runner called. As the only hard requirement for Alice is the "type" field in a job (or the optional "changes"), everything else is handled by the runner.