The Ware & Driver concept

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

A Ware can contain an arbitrary set of WNodes.

WNodes have a type and a name, which are strings relevant to the Ware only. Ware objects have accessors for nodes by name, by type, 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. drive()) Wares:

• If Ware is an intermediate representation, Drivers can transform it into another Ware.
• If Ware is the final representation, Drivers 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 driver construction.

Commands are not directly run by the Drivers, but Drivers use dsx.runner.Runner objects. In turn, Runners may directly call commands, or create Makefiles.

The Ware model

exception dsx.ware.WareContentsError

class dsx.ware.Ware

A ware object

• Object construction

  __init__()

  Creates a new empty ware object

• Access to WNodes

  add(*nodes)

  Add nodes to the ware object.

  Parameters:nodes (variadic of WNode objects) – Nodes to add

  nodeTypes()

  Retrieves all the node types seen in this ware.

  Returns:an iterable of type strings

  all()

  Retrieves all nodes

  Returns:an iterable of WNode objects

  nodesOfType(_type)

  Retrieves the nodes of a given type.

  Parameters:_type (str) – Type of nodes to get Returns:an iterable containing WNode objects

  __getitem__(name)

  Retrieves a node by its name

  Parameters:name (str) – Node name Returns:a WNode object Raises :KeyError if not found

  __contains__(name)

  Whether a node name exists in this ware

  Parameters:name (str) – Node name Returns:a boolean

• Usage with Drivers

  prepared()

  Whether this ware is prepared.

  Returns:a boolean

  prepare()

  Sets this ware as prepared.

  addPostDriver(ware, driver_class, *args, **kwargs)

  Adds a given ware to be also driven when this ware is finally driven. The driver used for the ware will be:

  driver_class(*args, parent = self, **kwargs)

  Parameters:

  • ware (A Ware object) – The ware to drive afterwards
  • driver (A dsx.driver.Driver object) – The ware driver
  • args – Arguments to pass to the driver
  • kwargs – Keyword arguments to pass to the driver

  generate(*drivers, **kwargs)

  Do the generation.

  For each driver, call the drive method of the driver with given keyword arguments.

  This also does the post-driver, i.e. call all drivers added through addPostDriver().

  Parameters:

  • drivers (a variadic of dsx.driver.Driver objects) – Drivers to run
  • kwargs – Keyword arguments to pass to the driver

class dsx.ware.WNode

Node of a Ware object.

name

Name of the node in the Ware

type

Type of the node

priority = 0

Sorting order.

__init__(name, type=None)

Creates a new node.

Parameters:

• name (str) – Name of node
• type (str) – Type of node. If left to None, class name is used as type.

__hash__()

Comparison helper, always differ unless this is the same object.

The Driver model

exception dsx.driver.DriverImplementationError

class dsx.driver.Driver

Driver class. WNode can register their generation method to this class.

• Object construction

  __init__(outdir, parent=None)

  Creates a new Driver.

  Parameters:

  • outdir (str) – Path of the output directory for this driver.
  • parent (Driver) – Parent driver

• File-related

  outdir

  Output directory

  fileName(name)

  Generate a filename inside the output directory.

  Parameters:name (str) – Filename relative to the output directory Returns:Absolute path corresponding to the filename

  safeOutdir()

  Generate a name corresponding to the output directory, but suitable for a file name without special characters.

  Returns:A filename corresponding to output directory, without directory separators

  mkdir(subdir=None)

  Create a directory in the output directory.

  Parameters:subdir (str) – Subdirectory relative dir name. If None, this creates the output directory

• Generation of file and links

  addLink(from_, to=None)

  Adds a symlink in the current directory to a file in the output directory of this driver.

  Link name defaults to the target name.

  Parameters:

  • from (str) – Path of target file
  • to (str or None) – Path of symlink

  genFile(filename, contents)

  Generates a file in output directory.

  Parameters:

  • filename (path string or fd) – Relative filename in output directory, or open file descriptor
  • contents (str) – Future contents of the file

• Subset generation support

  isForMe()

  Whether the selected output directories contain the one of this driver.

  isNotForMe()

  Whether the selected output directories do not contain the one of this driver.

• Actual generation entry-points

  prepare()

  Prepare the driver:

  • Create the output directory

  drive(desc)

  Does the actual work of the driver. This method should be overloaded for inherited classes.

  Parameters:desc (dsx.ware.Ware) – A ware to work on.

• Runner settings

  setRunner(runner, **kwargs)

  Override the runner for this driver.

  kwargs are passed verbatim to the runner.

  Parameters:

  • runner (dsx.runner.Runner) – The runner instance
  • kwargs – Arguments to pass to the runner

  runner

  dsx.runner.Runner object associated to the driver

• Generation low-level primitives, are wrappers around Runner‘s methods

  cmd_compile(*args, **kwargs)

  Run a command by calling the current runner. If the runner does not directly call the program, errors may be reported later.

  Parameters:

  • args – Variadic argument list to runner’s run()
  • kwargs – Variadic argument list to runner’s run()

  cmd_clean_dep(target)

  Add a dependency to target for the “clean” target of current runner.

  Parameters:target – Target name

  cmd_compile_dep(target)

  Add a dependency to target for the “compile” target of current runner.

  Parameters:target – Target name

  cmd_clean(*args, **kwargs)

  Run a clean command calling the current runner. If the runner does not directly call the program, errors may be reported later.

  Parameters:

  • args – Variadic argument list to runner’s run()
  • kwargs – Variadic argument list to runner’s run()

The Runners

class dsx.runner.Runner

A class able to run commands, immediately or delayed.

run(driver, cmd, target, cwd=None, fatal=True, output=None, input=None, **kwargs)

Adds a command to the run queue.

Parameters:

• driver (dsx.driver.Driver) – Associated driver
• cmd (list of str) – Command’s argv
• target (str) – Command target (“compile” or “clean”)
• cwd (str or None) – Current working directory required by the command, if relevant. If left to None, current working directory for command execution is not predictable.
• fatal (bool) – Whether command failure is fatal for the build pipeline.
• output (str or None) – File path to open as command’s stdout
• input (str or None) – File path to open as command’s stdin
• kwargs – Additional implementation-specific parameters

class dsx.runner.InstantRunner

An instantaneous runner. Directly runs the commands.

run()

See dsx.runner.Runner.run()

class dsx.runner.MakefileRunner

A Makefile-based runner. Saves all the commands to run in a Makefile. This does not directly run the commands.

__init__(makefile_path)

Creates a new Makefile-based runner.

Parameters:makefile_path (str) – Path where to save the Makefile to.

save()

Saves the Makefile to its destination path.

run()

See dsx.runner.Runner.run()