README.debug-plugins

otopi - debug plugins
=====================

The optional package otopi-debug-plugins provides plugins that can help
debug otopi-based tools.

wait_on_error
-------------
Activated by setting in the system environment OTOPI_WAIT_ON_ERROR=1.

If activated, each occurrence of an [ERROR] message triggers a prompt:

    Press Enter to continue.

force_fail
----------
Activated by setting in the system environment OTOPI_FORCE_FAIL_STAGE.
The value set there should be a name of one of the STAGE_* constants
in plugin.Stages .

Optionally can set priority for the failure by setting also
OTOPI_FORCE_FAIL_PRIORITY to one of the PRIORITY_* constants in the
same class.

If activated, causes a RuntimeError at the specified stage and priority.

test_command
------------
Activated by setting in the system environment OTOPI_TEST_COMMAND=1.
Activates some code to test the 'command' module. The log will have
some results of the tests, around lines containing 'test_command'.

test_note
---------
Activated by setting ODEBUG/note to some text to be output with dialog.note.

packages
--------
Activated by passing in otopi's environment:

ODEBUG/packagesAction=str:@action@
ODEBUG/packages=str:@packages@

Valid options for @action@:

These do not need params, and ignore ODEBUG/packages:

queryGroups

These take a single param, passed as @packages@:

installGroup
updateGroup
removeGroup

These take a comma-separated list of params, passed as @packages@:

install
update
installUpdate
remove
queryPackages

test_failure
------------
Always active, if installed. Runs some commands to help debug failures.

Examples
========

- Fail at STAGE_SETUP, prompt before exiting:

OTOPI_WAIT_ON_ERROR=1 OTOPI_FORCE_FAIL_STAGE=STAGE_SETUP engine-setup

- Query available yum/dnf groups:

otopi ODEBUG/packagesAction=str:queryGroups

- Install a yum/dnf group:

otopi ODEBUG/packagesAction=str:installGroup ODEBUG/packages=str:compat-libraries

- Install some packages using yum/dnf:

otopi ODEBUG/packagesAction=str:install ODEBUG/packages=str:zziplib,zsh