fate-scheduler

= Fate

The operating system-level command scheduler and manager.

TODO: Objectives/justifications; features; installation and quick start-up....

== Creating tasks

Fate tasks are merely executables available through the file system. Tasks abiding by the framework's expectations may be added with a minimum of effort.

=== The contract

TODO

=== Testing

==== execute

Any executable may be invoked (with optional arguments) by the Fate execute command:

[source,sh]

fate debug execute [options] command [arguments]

The above generates an execution report for use in development and debugging.

Options such as -i|--stdin may be useful to supply measurment parameters to the executable according to the link:#_the_contract[framework's contract].

==== run

Once added to Fate configuration, executables become tasks. These may be invoked ad-hoc by the run command:

[source,sh]

fate debug run [options] task

The options and output of the run command are similar to those of execute.

Unlike with scheduled tasks, the results of tasks performed by run are not, by default, persisted to file. Either specify option --record to capture these as configured, or option --stdout to capture these at an arbitrary path.

== Development

=== Extending the framework

==== Set-up

Fate is implemented in https://www.python.org/[Python] and the framework's distribution is managed via https://python-poetry.org/[Poetry].

Python v3.10 may be supplied by an operating system package manager, by https://www.python.org/[python.org], or by a utility such as https://github.com/pyenv/pyenv[pyenv]; pyenv is recommended for development but not required.

With Python installed, Poetry may be installed https://python-poetry.org/docs/#installation[according to its instructions].

TIP: If you are managing your own virtual environment, e.g. via https://github.com/pyenv/pyenv-virtualenv[pyenv-virtualenv], then this step may be as simple as pip install poetry. However, this tooling is not required, and Poetry offers its own automated set-up, as well as management of virtual environments.

Finally, from the root directory of a repository clone, the framework may be installed in development mode:

[source,sh]

poetry install

NOTE: Poetry will use any existing, activated virtual environment, or create its own into which dependencies will be installed.

The fate command is now available for use in your development environment.

[IMPORTANT]

For simplicity, it will be presumed that fate is available on your PATH. However, this depends upon activation of your virtual environment.

A virtual environment under management by Poetry may be activated via sub-shell with:

[source,sh]

poetry shell

Alternatively, any command installed into Poetry's virtual environment may be executed ad-hoc via the run command:

[source,sh]

poetry run fate ...

====