Metadata-Version: 2.4
Name: runner-framework
Version: 0.1.0
Summary: Deterministic automation engine for real-time workloads.
Author: William Christopher White
License-Expression: GPL-2.0-or-later
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: PyYAML
Dynamic: license-file

=================
Runner Framework
=================

Overview
========

The Runner Framework is a Python-based system that provides a unified command-line interface for executing various real-time testing tools. The core of this framework is the ``runner.py`` script, which acts as a dispatcher for different testing modules.

Build and Installation
======================

The Runner Framework uses a Makefile-based build system for installation and management.

Prerequisites
-------------

- Python 3.6 or higher
- Make

Installation Steps
------------------

1. **Standard Installation**

   To install the Runner Framework to the default location (``/usr/bin``):

   .. code-block:: bash

       make install

   This will:
   - Install the runner script to ``/usr/bin/runner``
   - Install the framework modules to ``/usr/lib/runner-framework/``
   - Install configuration examples to ``/etc/samestack/runner/yaml_examples/``

2. **Custom Installation Path**

   To install to a custom location:

   .. code-block:: bash

       make install PREFIX=/custom/path

   This will install the runner script to ``/custom/path/bin/runner``.

3. **Development Installation**

   For development purposes, you can create symbolic links instead of copying files:

   .. code-block:: bash

       make dev-install

4. **Uninstallation**

   To remove the Runner Framework:

   .. code-block:: bash

       make uninstall

Runner Script (runner.py)
=========================

The ``runner.py`` script is the main entry point for the Runner Framework. It dynamically loads and executes the appropriate runner module based on the provided subcommand.

Basic Usage
-----------

.. code-block:: bash

    runner <subcommand> [options]

Where ``<subcommand>`` is the name of the testing tool to run (e.g., rteval, cyclictest).

Command-line Options
--------------------

- ``--list``: List all available runners
- ``<subcommand>``: The runner to execute (e.g., rteval, rtla)
- Additional options are passed to the specified runner

How It Works
------------

1. The script parses the command line to determine which runner to execute
2. It dynamically imports the corresponding module (e.g., ``rteval_runner.py`` for the ``rteval`` subcommand)
3. It then either:
   - Calls the module's ``main()`` function if it exists
   - Or instantiates the module's runner class (e.g., ``RtevalRunner``) and calls its ``run()`` method

Available Runners
-----------------

To see which runners are available in your installation:

.. code-block:: bash

    runner --list

This will display a list of all available testing tools that can be executed through the runner framework.

Module Structure
----------------

The Runner Framework expects runner modules to follow a specific naming convention:

- Module file: ``<subcommand>_runner.py``
- Class name: ``<Subcommand>Runner`` (capitalized first letter)

For example:
- For the ``rteval`` subcommand: ``rteval_runner.py`` with class ``RtevalRunner``
- For the ``cyclictest`` subcommand: ``cyclictest_runner.py`` with class ``CyclictestRunner``

Each runner module should either:
- Define a ``main()`` function, or
- Define a runner class that extends ``ApplicationRunner``

Example
-------

To run the rteval runner:

.. code-block:: bash

    runner rteval --config my_config.yaml

This command will:
1. Load the ``rteval_runner.py`` module
2. Execute either its ``main()`` function or instantiate the ``RtevalRunner`` class and call its ``run()`` method
3. Pass the ``--config my_config.yaml`` argument to the runner

Troubleshooting
===============

Common Issues
-------------

1. **Runner Not Found**

   If you see an error like "Runner '<subcommand>' not found", ensure:
   
   - The runner module is installed correctly in ``/usr/lib/runner-framework/``
   - The module name follows the pattern ``<subcommand>_runner.py``

2. **Module Import Error**

   If you see an import error when running a command:
   
   - Check that all required Python dependencies are installed
   - Verify that the module is correctly implemented

3. **Permission Issues**

   When running tests that require system access:
   
   - Ensure you have appropriate permissions (usually root)
   - When using containers, use the ``--privileged`` flag
