fate-scheduler 1.1.0

= 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 ...
----
====