.. module:: dsx.ware

=========================
The Ware & Driver concept
=========================

:py:class:`dsx.ware.Ware` is an object containing a description of
something made of elements.  In DSX, this can be an application's
:py:class:`~dsx.application.tcg.Tcg`, an
:py:class:`~dsx.hard.hard.Hardware` description, or a
:py:class:`~dsx.soft.soft.Software`.  Other wares exist in DSX. These
are the most used ones.  In any case, their elements are subclasses of
the :py:class:`dsx.ware.WNode` class.

A |ware| can contain an arbitrary set of |wnode|\s.

|wnode|\s have a :py:attr:`~dsx.ware.WNode.type` and a
:py:attr:`~dsx.ware.WNode.name`, which are strings relevant to the
|ware| only.  Ware objects have accessors for nodes :py:meth:`by name
<dsx.ware.Ware.__getitem__>`, :py:meth:`by type
<dsx.ware.Ware.nodesOfType>`, :py:meth:`all <dsx.ware.Ware.all>`.

|ware| subclasses are actually an internal representation of some part
of the design in DSX.  Main goal is to transform the |ware| into
something else. |driver| objects are there to transform
(i.e. :py:meth:`~dsx.driver.Driver.drive`) `Wares`:

* If |ware| is an intermediate representation, |driver|\s can transform
  it into another |ware|.

* If |ware| is the final representation, |driver|\s can run commands,
  or create files.

|driver| objects can be nested, like |ware| objects may contain other
|ware| objects. This hierarchy is explicitly built at :py:meth:`driver
construction <dsx.driver.Driver.__init__>`.

Commands are not directly run by the |driver|\s, but |driver|\s use
:py:class:`dsx.runner.Runner` objects. In turn, |runner|\s may
directly :py:class:`call commands <dsx.runner.InstantRunner>`, or
:py:class:`create Makefiles <dsx.runner.MakefileRunner>`.

.. image:: /_static/ware_driving.*

The Ware model
==============

.. autoexception:: WareContentsError()

.. autoclass:: Ware()

   * Object construction

     .. automethod:: __init__

   * Access to |wnode|\s
  
     .. automethod:: add
  
     .. automethod:: nodeTypes
  
     .. automethod:: all
  
     .. automethod:: nodesOfType
  
     .. automethod:: __getitem__
  
     .. automethod:: __contains__
  
   * Usage with |driver|\s

     .. automethod:: prepared
  
     .. automethod:: prepare
  
     .. automethod:: addPostDriver
  
     .. automethod:: generate

.. autoclass:: WNode()

   .. attribute:: name

      Name of the node in the |ware|

   .. attribute:: type

      Type of the node

   .. autoattribute:: priority

   .. automethod:: __init__

   .. automethod:: __cmp__

   .. automethod:: __hash__

The Driver model
================

.. module:: dsx.driver

.. autoexception:: DriverImplementationError()

.. autoclass:: Driver()

   * Object construction

     .. automethod:: __init__
  
   * File-related

     .. autoattribute:: outdir
  
     .. automethod:: fileName
  
     .. automethod:: safeOutdir
  
     .. automethod:: mkdir
  
   * Generation of file and links

     .. automethod:: addLink
  
     .. automethod:: genFile
  
   * Subset generation support

     .. automethod:: isForMe
  
     .. automethod:: isNotForMe
  
   * Actual generation entry-points

     .. automethod:: prepare
  
     .. automethod:: drive
  
   * |runner| settings

     .. automethod:: setRunner
  
     .. autoattribute:: runner
  
   * Generation low-level primitives, are wrappers around |runner|\'s
     methods

     .. automethod:: cmd_compile
  
     .. automethod:: cmd_clean_dep
  
     .. automethod:: cmd_compile_dep
  
     .. automethod:: cmd_clean

The Runners
===========

.. module:: dsx.runner

.. autoclass:: Runner()

   .. automethod:: run

.. autoclass:: InstantRunner()

   .. method:: run

      See :py:meth:`dsx.runner.Runner.run`

.. autoclass:: MakefileRunner()

   .. automethod:: __init__

   .. automethod:: save

   .. method:: run

      See :py:meth:`dsx.runner.Runner.run`

.. |wnode| replace:: :py:class:`~dsx.ware.WNode`
.. |ware| replace:: :py:class:`~dsx.ware.Ware`
.. |driver| replace:: :py:class:`~dsx.driver.Driver`
.. |runner| replace:: :py:class:`~dsx.runner.Runner`