← Back to team overview

checkbox-dev team mailing list archive

[PATCH 1/3] plainbox:docs: add plainbox(1) manual page


Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@xxxxxxxxxxxxx>
 plainbox/docs/manpages/plainbox.rst | 201 ++++++++++++++++++++++++++++++++++++
 1 file changed, 201 insertions(+)
 create mode 100644 plainbox/docs/manpages/plainbox.rst

diff --git a/plainbox/docs/manpages/plainbox.rst b/plainbox/docs/manpages/plainbox.rst
new file mode 100644
index 0000000..efd3b3f
--- /dev/null
+++ b/plainbox/docs/manpages/plainbox.rst
@@ -0,0 +1,201 @@
+plainbox -- test developer's swiss army knife
+.. toctree::
+   :maxdepth: 2
+usage: plainbox [-h] [--version] [-v] [-D] [-C]
+                [-T LOGGER] [-P] [-I]
+                subcommand ...
+:term:`PlainBox` is a toolkit consisting of python3 library, development tools,
+documentation and examples. It is targeted at developers working on testing or
+certification applications and authors creating tests for such applications.
+Optional Arguments
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+Logging and Debugging
+  -v, --verbose         be more verbose (same as --log-level=INFO)
+  -D, --debug           enable DEBUG messages on the root logger
+  -C, --debug-console   display DEBUG messages in the console
+  -T LOGGER, --trace LOGGER
+                        enable DEBUG messages on the specified logger (can be
+                        used multiple times)
+  -P, --pdb             jump into pdb (python debugger) when a command crashes
+  -I, --debug-interrupt
+                        crash on SIGINT/KeyboardInterrupt, useful with --pdb
+PlainBox Sub-Commands
+PlainBox uses a number of sub-commands for performing specific operations.
+Since it targets several different audiences commands are arranged into three
+parts: test authors, test users and core developers
+Test Users
+    plainbox run
+        Run a test job. This is the swiss army knife of a swiss army knife. Has
+        lots of options that affect job selection, execution and handling results.
+    plainbox check-config
+        check and display plainbox configuration. While this command doesn't allow
+        to edit any settings it is very useful for figuring out what variables are
+        available and which configuration files are consulted.
+Test Authors
+    plainbox startprovider
+        Create a new provider (directory). This command allows test authors to
+        create a new collection (provider) of test definitions for PlainBox.
+    plainbox dev script
+        Run the command from a job in a way it would run as a part of normal
+        run, ignoring all dependencies / requirements and providing additional
+        diagnostic messages.
+    plainbox dev analyze
+        Analyze how selected jobs would be executed. Takes almost the same
+        arguments as ``plainbox run`` does. Additional optional arguments
+        control the type of analysis performed.
+    plainbox dev parse
+        Parse stdin with the specified parser. PlainBox comes with a system for
+        plugging parser definitions so that shell programs (and developers) get
+        access to structured data exported from otherwise hard-to-parse output.
+    plainbox dev list
+        List and describe various objects. Run without arguments to see all the
+        high-level objects PlainBox knows about. Optional argument can restrict
+        the list to objects of one kind.
+Core Developers
+    plainbox self-test
+        Run unit and integration tests. Unit tests work also after installation
+        so this command can verify a local installation at any time.
+    plainbox dev special
+        Access to special/internal commands.
+    plainbox dev crash
+        Crash the application. Useful for testing the crash handler and crash
+        log files.
+    plainbox dev logtest
+        Log messages at various levels. Useful for testing the logging system.
+Files and Directories
+The following files and directories affect PlainBox:
+Created or written to
+    PlainBox keeps all internal log files in this directory. In particular the
+    ``crash.log`` is generated there on abnormal termination. If extended
+    logging / tracing is enabled via ``--debug`` or ``--trace`` then
+    ``debug.log`` will be created in this directory. The files are generated on
+    demand and are rotated if they grow too large. It is safe to remove them at
+    any time.
+    PlainBox keeps internal state of all running and dormant (suspended or
+    complete) sessions here. Each session is kept in a separate directory with
+    a randomly generated name. This directory may also contain a symlink
+    ``last-session`` that points at one of those sessions. The symlink may be
+    broken as a part of normal operation.
+    Sessions may accumulate, in some cases, and they are not garbage collected
+    at this time. In general it is safe to remove sessions when PlainBox is not
+    running.
+Looked up or read from
+    System wide, locally administered directory with provider definitions. See
+    PROVIDERS for more information. Jobs defined here have access to
+    ``plainbox-trusted-launcher(1)`` and may run as root without prompting
+    (depending on configuration).
+    Like ``/usr/local/share/plainbox-providers-1`` but maintained by the local
+    package management system. This is where packaged providers add their
+    definitions.
+    Per-user directory with provider definitions. This directory may be used to
+    install additional test definitions that are only available to a particular
+    user. Jobs defined there will not have access to
+    ``plainbox-trusted-launcher(1)`` and will use ``pkexec(1)`` or ``sudo(1)``
+    to run as root, if needed.
+    Typically this directory is used by test provider developers transparently
+    by invoking ``manage.py develop`` (manage.py is the per-provider management
+    script generated by ``plainbox startprovider``)
+    System-wide configuration file (lowest priority). See below for details.
+    Per-user configuration (highest priority).
+Configuration Files
+PlainBox (and its derivatives) uses a configuration system composed of
+variables arranged in sections. All configuration files follow the well-known
+INI-style syntax. While PlainBox itself is not really using any variables,
+knowledge of where those can be defined is useful for working with derivative
+applications, such as Checkbox.
+The environment section
+The ``[environment]`` section deserves special attention. If a job advertises
+usage of environment variable ``FOO`` (by using the `environ: FOO` declaration)
+and ``FOO`` is not available in the environment of the user starting plainbox,
+then the value is obtained from the ``[environment]`` section. This mechanism
+is useful for distributing both site-wide and per-user configuration for jobs.
+Environment Variables
+The following environment variables affect PlainBox:
+    Determines the lookup of test providers. Note that unless otherwise
+    essential, it is recommended to install test providers into one of the
+    aforementioned directories instead of using PROVIDERPATH.
+    The default value is composed out of ':'-joined list of:
+    * ``/usr/local/share/plainbox-providers-1``
+    * ``/usr/share/plainbox-providers-1``
+    * ``$XDG_DATA_HOME/plainbox-providers-1``

Follow ups