.. -*- mode: rst -*-

.. _development-client-driver:

Writing A Client Tool Driver
============================

This page describes the step-by-step process of writing a client tool
driver for a configuration element type. The included example describes
an existing driver, and the process that was used to create it.

#. Pick a name for the driver. In this case, we picked the name RPM.
#. Create a file in ``src/lib/Client/Tools`` with the same name (RPM.py)
#. Create a class in this file with the same name (class RPM)

   * If it handles **Package** entries, subclass ``Bcfg2.Client.Tools.PkgTool``
     (from here referenced as branch [P])
   * If it handles **Service** entries, subclass ``Bcfg2.Client.Tools.SvcTool``
     (from here referenced as branch [S])
   * Otherwise, subclass ``Bcfg2.Client.Tools.Tool`` (from here referenced
     as branch [T])

#. Set ``name`` to "RPM"
#. Add any required executable programs to ``__execs__``
#. Set ``__handles__`` to a list of (**entry.tag**, **entry.get('type')**)
   tuples. This determines which entries the Tool module can be used
   on. In this case, we set ``__handles__ = [('Package', 'rpm')]``.
#. Add verification. This method should return True/False depending
   on current entry installation status.

   * [T] Add a Verify<entry.tag> method.
   * [P] Add a VerifyPackage method.
   * [S] Add a VerifyService method.
   * In the failure path, the current state of failing entry
     attributes should be set in the entry, to aid in auditing.
     (For example, if a file should be mode 644, and is currently
     mode 600, then set attribute current_perms='600' in the input
     entry)

#. Add installation support. This method should return True/False
   depending on the results of the installation process.

   * [T,S] Add an Install<entry.tag> method.
   * [P] The PkgTool baseclass has a generic mechanism for performing
     all-at-once installations, followed, in the case of failures, 
     by single installations. To enable this support, set the pkgtype 
     attribute to the package type handled by this driver. Set the
     pkgtool to a tuple ("command string %s", ("per-package string
     format", [list of package entry fields])). For RPM, we have
     setup ``pkgtool =  ("rpm --oldpackage --replacepkgs --quiet -U %s", ("%s", ["url"]))``

#. Implement entry removal

   * [T,S] Implement a ``Remove`` method that removes all specified
     entries (``prototype Remove(self, entries)``)
   * [P] Implement a ``RemovePackages`` that removes all specified
     entries (same prototype as Remove)

#. Add a ``FindExtra`` method that locates entries not included in the
   configuration. This may or may not be required, certain drivers
   do not have the capability to find extra entries.
#. [P] Package drivers require a ``RefreshPackages`` method that updates
   the internal representation of the package database.

Writing Tool Driver Methods
---------------------------

#. Programs can be run using ``self.cmd.run``. This function returns a
   (return code, stdout list) tuple.
#. The configuration is available as ``self.config``
#. Runtime options are available in a dictionary as ``self.setup``
#. Informational, error, and debug messages can be produced by 
   running ``self.logger.info/error/debug``.