sascha/workload-automation
1
0
Fork 0
mirror of https://github.com/ARM-software/workload-automation.git synced 2025-01-18 12:06:08 +00:00
Code Issues Releases Wiki Activity

pluginloader: Updated documentation to say plugin instead of extension

Browse Source
This commit is contained in:
Sebastian Goscik 2016-03-17 15:25:54 +00:00
parent 1e6763ee9b
commit c51593a729
16 changed files with 154 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/Makefile
View File

@ -10,8 +10,8 @@ BUILDDIR = build
SPHINXAPI = sphinx-apidoc
SPHINXAPIOPTS =
WAEXT = ./build_extension_docs.py
WAEXTOPTS = source/extensions ../wlauto ../wlauto/external ../wlauto/tests
WAEXT = ./build_plugin_docs.py
WAEXTOPTS = source/plugins ../wlauto ../wlauto/external ../wlauto/tests
# Internal variables.
@ -50,7 +50,7 @@ help:
clean:
rm -rf $(BUILDDIR)/*
rm -rf source/api/*
rm -rf source/extensions/*
rm -rf source/plugins/*
rm -rf source/instrumentation_method_map.rst
coverage:
@ -63,8 +63,8 @@ api: ../wlauto
$(SPHINXAPI) $(ALLSPHINXAPIOPTS)
waext: ../wlauto
rm -rf source/extensions
mkdir -p source/extensions
rm -rf source/plugins
mkdir -p source/plugins
$(WAEXT) $(WAEXTOPTS)

19
doc/build_extension_docs.py
View File

@ -18,29 +18,28 @@
import os
import sys
from wlauto import ExtensionLoader
from wlauto.utils.doc import get_rst_from_extension, underline
from wlauto import pluginloader
from wlauto.utils.doc import get_rst_from_plugin, underline
from wlauto.utils.misc import capitalize
GENERATE_FOR = ['workload', 'instrument', 'result_processor', 'device']
def generate_extension_documentation(source_dir, outdir, ignore_paths):
loader = ExtensionLoader(keep_going=True)
loader.clear()
loader.update(paths=[source_dir], ignore_paths=ignore_paths)
for ext_type in loader.extension_kinds:
def generate_plugin_documentation(source_dir, outdir, ignore_paths):
pluginloader.clear()
pluginloader.update(paths=[source_dir], ignore_paths=ignore_paths)
for ext_type in pluginloader.kinds:
if not ext_type in GENERATE_FOR:
continue
outfile = os.path.join(outdir, '{}s.rst'.format(ext_type))
with open(outfile, 'w') as wfh:
wfh.write('.. _{}s:\n\n'.format(ext_type))
wfh.write(underline(capitalize('{}s'.format(ext_type))))
exts = loader.list_extensions(ext_type)
exts = pluginloader.list_plugins(ext_type)
for ext in sorted(exts, key=lambda x: x.name):
wfh.write(get_rst_from_extension(ext))
wfh.write(get_rst_from_plugin(ext))
if __name__ == '__main__':
generate_extension_documentation(sys.argv[2], sys.argv[1], sys.argv[3:])
generate_plugin_documentation(sys.argv[2], sys.argv[1], sys.argv[3:])

20
doc/source/additional_topics.rst
View File

@ -4,14 +4,14 @@ Additional Topics
Modules
=======
Modules are essentially plug-ins for Extensions. They provide a way of defining
common and reusable functionality. An Extension can load zero or more modules
Modules are essentially plug-ins for Plugins. They provide a way of defining
common and reusable functionality. An Plugin can load zero or more modules
during its creation. Loaded modules will then add their capabilities (see
Capabilities_) to those of the Extension. When calling code tries to access an
attribute of an Extension the Extension doesn't have, it will try to find the
Capabilities_) to those of the Plugin. When calling code tries to access an
attribute of an Plugin the Plugin doesn't have, it will try to find the
attribute among its loaded modules and will return that instead.
.. note:: Modules are themselves extensions, and can therefore load their own
.. note:: Modules are themselves plugins, and can therefore load their own
modules. *Do not* abuse this.
For example, calling code may wish to reboot an unresponsive device by calling
@ -22,7 +22,7 @@ is in a rack and is powered through such a switch). The module has
``reset_power`` capability (see Capabilities_ below) and so implements
``hard_reset``. This will get invoked when ``device.hard_rest()`` is called.
.. note:: Modules can only extend Extensions with new attributes; they cannot
.. note:: Modules can only extend Plugins with new attributes; they cannot
override existing functionality. In the example above, if the
``Device`` has implemented ``hard_reset()`` itself, then *that* will
get invoked irrespective of which modules it has loaded.
@ -34,16 +34,16 @@ effectively overriding the module that was loaded previously.
Specifying Modules
------------------
Modules get loaded when an Extension is instantiated by the extension loader.
Modules get loaded when an Plugin is instantiated by the plugin loader.
There are two ways to specify which modules should be loaded for a device.
Capabilities
============
Capabilities define the functionality that is implemented by an Extension,
either within the Extension itself or through loadable modules. A capability is
just a label, but there is an implied contract. When an Extension claims to have
Capabilities define the functionality that is implemented by an Plugin,
either within the Plugin itself or through loadable modules. A capability is
just a label, but there is an implied contract. When an Plugin claims to have
a particular capability, it promises to expose a particular set of
functionality through a predefined interface.

2
doc/source/agenda.rst
View File

@ -430,7 +430,7 @@ elsewhere.
Disabling result processors and instrumentation
-----------------------------------------------
As seen above, extensions specified with ``instrumentation`` and
As seen above, plugins specified with ``instrumentation`` and
``result_processor`` clauses get added to those already specified previously.
Just because an instrument specified in ``config.py`` is not listed in the
``config`` section of the agenda, does not mean it will be disabled. If you do

22
doc/source/changes.rst
View File

@ -93,7 +93,7 @@ Framework
- ``wlauto.core.result``:
- Added "classifiers" field to Metric objects. This is a dict mapping
classifier names (arbitrary strings) to corresponding values for that
specific metrics. This is to allow extensions to add extension-specific
specific metrics. This is to allow plugins to add plugin-specific
annotations to metric that could be handled in a generic way (e.g. by
result processors). They can also be set in agendas.
- Failed jobs will now be automatically retired
@ -261,7 +261,7 @@ Framework
- Added ``swipe_to_unlock`` method.
- Fixed initialization of ``~/.workload_automation.``.
- Fixed replaying events using revent on 64 bit platforms.
- Improved error repoting when loading extensions.
- Improved error repoting when loading plugins.
- ``result`` objects now track their output directories.
- ``context.result`` will not result in ``context.run_result`` when not
executing a job.
@ -279,7 +279,7 @@ Framework
- Now handles backspaces in serial output
- Added ``port`` argument for telnet connections.
- Now allows telnet connections without a password.
- Fixed config processing for extensions with non-identifier names.
- Fixed config processing for plugins with non-identifier names.
- Fixed ``get_meansd`` for numbers < 1
- ``wlatuo.utils.ipython``:
- Now supports old versions of IPython
@ -306,7 +306,7 @@ Framework
- Updated csv result processor with the option to use classifiers to
add columns to ``results.csv``.
- ``wlauto.utils.formatter``: Fix terminal size discovery.
- The extension loader will now follow symlinks.
- The plugin loader will now follow symlinks.
- Added arm64-v8a to ABI map
- WA now reports syntax errors in a more informative way.
- Resource resolver: now prints the path of the found resource to the log.
@ -322,7 +322,7 @@ Framework
- ``boolean`` now interprets ``'off'`` as ``False``
- ``wlauto.utils.uefi``: Added support for debug builds.
- ``wlauto.utils.serial_port``: Now supports fdexpect versions > 4.0.0
- Semanatics for ``initialize``/``finalize`` for *all* Extensions are changed
- Semanatics for ``initialize``/``finalize`` for *all* Plugins are changed
so that now they will always run at most once per run. They will not be
executed twice even if invoked via instances of different subclasses (if
those subclasses defined their own verions, then their versions will be
@ -345,9 +345,9 @@ Documentation
- ``device_setup``: fixed ``generic_linux`` ``device_config`` example.
- ``contributing``: Clarified style guidelines
- ``daq_device_setup``: Added an illustration for DAQ wiring.
- ``writing_extensions``: Documented the Workload initialize and finalize
- ``writing_plugins``: Documented the Workload initialize and finalize
methods.
- Added descriptions to extension that didn't have one.
- Added descriptions to plugin that didn't have one.
Other
~~~~~
@ -365,16 +365,16 @@ Other
- ``status`` result processor is now enabled by default.
- Commands:
- ``show``:
- Now shows what platform extensions support.
- Now shows what platform plugins support.
- Will no longer try to use a pager if ``PAGER=''`` in the environment.
- ``list``:
- Added ``"-p"`` option to filter results by supported platforms.
- Added ``"--packaged-only"`` option to only list extensions packaged
- Added ``"--packaged-only"`` option to only list plugins packaged
with WA.
- ``run``: Added ``"--disable"`` option to diable instruments.
- ``create``:
- Added ``agenda`` sub-command to generate agendas for a set of
extensions.
plugins.
- ``create workload`` now gives more informative errors if Android SDK
installed but no platform has been downloaded.
@ -387,7 +387,7 @@ Framework
- Renamed ``active_cpus`` to ``online_cpus``
- Renamed ``get_cluster_cpu`` to ``get_cluster_active_cpu``
- Renamed ``get_core_cpu`` to ``get_core_online_cpu``
- All extension's ``initialize`` function now takes one (and only one)
- All plugin's ``initialize`` function now takes one (and only one)
parameter, ``context``.
- ``wlauto.core.device``: Removed ``init`` function. Replaced with
``initialize``

40
doc/source/configuration.rst
View File

@ -4,7 +4,7 @@
Configuration
=============
In addition to specifying run execution parameters through an agenda, the
In addition to specifying run execution parameters through an agenda, the
behavior of WA can be modified through configuration file(s). The default
configuration file is ``~/.workload_automation/config.py`` (the location can be
changed by setting ``WA_USER_DIRECTORY`` environment variable, see :ref:`envvars`
@ -28,10 +28,10 @@ and used to modify the behavior of Workload automation.
Available Settings
==================
.. note:: Extensions such as workloads, instrumentation or result processors
.. note:: Plugins such as workloads, instrumentation or result processors
may also pick up certain settings from this file, so the list below is
not exhaustive. Please refer to the documentation for the specific
extensions to see what settings they accept.
plugins to see what settings they accept.
.. confval:: device
@ -49,15 +49,15 @@ Available Settings
This defines when during execution of a run the Device will be rebooted. The
possible values are:
``"never"``
The device will never be rebooted.
``"initial"``
``"never"``
The device will never be rebooted.
``"initial"``
The device will be rebooted when the execution first starts, just before
executing the first workload spec.
``"each_spec"``
``"each_spec"``
The device will be rebooted before running a new workload spec.
Note: this acts the same as each_iteration when execution order is set to by_iteration
``"each_iteration"``
``"each_iteration"``
The device will be rebooted before each new iteration.
.. seealso::
@ -69,7 +69,7 @@ Available Settings
Defines the order in which the agenda spec will be executed. At the moment,
the following execution orders are supported:
``"by_iteration"``
``"by_iteration"``
The first iteration of each workload spec is executed one after the other,
so all workloads are executed before proceeding on to the second iteration.
E.g. A1 B1 C1 A2 C2 A3. This is the default if no order is explicitly specified.
@ -80,9 +80,9 @@ Available Settings
X.A1, Y.A1, X.B1, Y.B1, X.A2, Y.A2, X.B2, Y.B2
``"by_section"``
``"by_section"``
Same as ``"by_iteration"``, however this will group specs from the same
section together, so given sections X and Y, global specs A and B, and two iterations,
section together, so given sections X and Y, global specs A and B, and two iterations,
this will run ::
X.A1, X.B1, Y.A1, Y.B1, X.A2, X.B2, Y.A2, Y.B2
@ -107,19 +107,19 @@ Available Settings
``"OK"``
This iteration has completed and no errors have been detected
``"PARTIAL"``
``"PARTIAL"``
One or more instruments have failed (the iteration may still be running).
``"FAILED"``
``"FAILED"``
The workload itself has failed.
``"ABORTED"``
``"ABORTED"``
The user interupted the workload
.. confval:: max_retries
The maximum number of times failed jobs will be retried before giving up. If
not set, this will default to ``3``.
not set, this will default to ``3``.
.. note:: this number does not include the original attempt
@ -169,7 +169,7 @@ Available Settings
There are also a couple of settings are used to provide additional metadata
for a run. These may get picked up by instruments or result processors to
for a run. These may get picked up by instruments or result processors to
attach context to results.
.. confval:: project
@ -212,9 +212,9 @@ various assets when it starts.
.. note:: This location **must** be writable by the user who runs WA.
.. confval:: WA_EXTENSION_PATHS
.. confval:: WA_PLUGIN_PATHS
By default, WA will look for extensions in its own package and in
subdirectories under ``WA_USER_DIRECTORY``. This environment variable can
By default, WA will look for plugins in its own package and in
subdirectories under ``WA_USER_DIRECTORY``. This environment variable can
be used specify a colon-separated list of additional locations WA should
use to look for extensions.
use to look for plugins.

6
doc/source/contributing.rst
View File

@ -17,8 +17,8 @@ consistent with the rest of WA code. Briefly, it is
"stats" for "statistics", "config" for "configuration", etc are OK). Do
*not* use Hungarian notation (so prefer ``birth_date`` over ``dtBirth``).
New extensions should also follow implementation guidelines specified in
:ref:`writing_extensions` section of the documentation.
New plugins should also follow implementation guidelines specified in
:ref:`writing_plugins` section of the documentation.
We ask that the following checks are performed on the modified code prior to
submitting a pull request:
@ -46,7 +46,7 @@ submitting a pull request:
tests should be added to cover the new functionality.
- If modifications have been made to documentation (this includes description
attributes for Parameters and Extensions), documentation should be built to
attributes for Parameters and Plugins), documentation should be built to
make sure no errors or warning during build process, and a visual inspection
of new/updated sections in resulting HTML should be performed to ensure
everything renders as expected.

2
doc/source/conventions.rst
View File

@ -58,7 +58,7 @@ Core Class Names
When core classes are referenced throughout the documentation, usually their
fully-qualified names are given e.g. :class:`wlauto.core.workload.Workload`.
This is done so that Sphinx_ can resolve them and provide a link. While
implementing extensions, however, you should *not* be importing anything
implementing plugins, however, you should *not* be importing anything
directly form under :mod:`wlauto.core`. Instead, classes you are meant to
instantiate or subclass have been aliased in the root :mod:`wlauto` package,
and should be imported from there, e.g. ::

2
doc/source/daq_device_setup.rst
View File

@ -105,7 +105,7 @@ installation may be different).
- Install NI-DAQmx driver, as described in the previous section.
- Install Python 2.7.
- Download and install ``pip``, ``numpy`` and ``twisted`` Python packages.
These packages have C extensions, an so you will need a native compiler set
These packages have C plugins, an so you will need a native compiler set
up if you want to install them from PyPI. As an easier alternative, you can
find pre-built Windows installers for these packages here_ (the versions are
likely to be older than what's on PyPI though).

4
doc/source/device_setup.rst
View File

@ -402,6 +402,6 @@ If you are working with a particularly unusual device (e.g. a early stage
development board) or need to be able to handle some quirk of your Android build,
configuration available in ``generic_android`` interface may not be enough for
you. In that case, you may need to write a custom interface for your device. A
device interface is an ``Extension`` (a plug-in) type in WA and is implemented
similar to other extensions (such as workloads or instruments). Pleaser refer to
device interface is an ``Plugin`` (a plug-in) type in WA and is implemented
similar to other plugins (such as workloads or instruments). Pleaser refer to
:ref:`adding_a_device` section for information on how this may be done.

4
doc/source/execution_model.rst
View File

@ -69,7 +69,7 @@ transition and interactions and will not attempt to describe very single thing t
device interface, based on the RunConfiguration. The executor also initialise a
``wlauto.core.execution.ExecutionContext`` which is used to track the current state of the run
execution and also serves as a means of communication between the core framework and the
extensions.
plugins.
#. Finally, the Executor instantiates a ``wlauto.core.execution.Runner``, initializes its job
queue with workload specs from the RunConfiguraiton, and kicks it off.
#. The Runner performs the run time initialization of the device and goes through the workload specs
@ -100,7 +100,7 @@ The full list of method names and the signals they map to may be viewed
:ref:`here <instrumentation_method_map>`.
Signal dispatching mechanism may also be used directly, for example to dynamically register
callbacks at runtime or allow extensions other than ``Instruments`` to access stages of the run
callbacks at runtime or allow plugins other than ``Instruments`` to access stages of the run
they are normally not aware of.
The sending of signals is the responsibility of the Runner. Signals gets sent during transitions

24
doc/source/index.rst
View File

@ -42,16 +42,16 @@ installation and configuration guides.
configuration
Extensions
Plugins
~~~~~~~~~~
This section lists extensions that currently come with WA2. Each package below
represents a particular type of extension (e.g. a workload); each sub-package of
that package is a particular instance of that extension (e.g. the Andebench
workload). Clicking on a link will show what the individual extension does,
This section lists plugins that currently come with WA2. Each package below
represents a particular type of plugin (e.g. a workload); each sub-package of
that package is a particular instance of that plugin (e.g. the Andebench
workload). Clicking on a link will show what the individual plugin does,
what configuration parameters it takes, etc.
For how to implement you own extensions, please refer to the guides in the
For how to implement you own plugins, please refer to the guides in the
:ref:`in-depth` section.
.. raw:: html
@ -66,7 +66,7 @@ For how to implement you own extensions, please refer to the guides in the
.. toctree::
:maxdepth: 2
extensions/workloads
plugins/workloads
.. raw:: html
@ -75,7 +75,7 @@ For how to implement you own extensions, please refer to the guides in the
.. toctree::
:maxdepth: 2
extensions/instruments
plugins/instruments
.. raw:: html
@ -85,7 +85,7 @@ For how to implement you own extensions, please refer to the guides in the
.. toctree::
:maxdepth: 2
extensions/result_processors
plugins/result_processors
.. raw:: html
@ -94,7 +94,7 @@ For how to implement you own extensions, please refer to the guides in the
.. toctree::
:maxdepth: 2
extensions/devices
plugins/devices
.. raw:: html
@ -105,14 +105,14 @@ For how to implement you own extensions, please refer to the guides in the
In-depth
~~~~~~~~
This section contains more advanced topics, such how to write your own extensions
This section contains more advanced topics, such how to write your own plugins
and detailed descriptions of how WA functions under the hood.
.. toctree::
:maxdepth: 2
conventions
writing_extensions
writing_plugins
execution_model
resources
additional_topics

12
doc/source/installation.rst
View File

@ -133,9 +133,9 @@ Optional Python Packages
to explicitly install them if/when you need them.
In addition to the mandatory packages listed in the previous sections, some WA
functionality (e.g. certain extensions) may have additional dependencies. Since
functionality (e.g. certain plugins) may have additional dependencies. Since
they are not necessary to be able to use most of WA, they are not made mandatory
to simplify initial WA installation. If you try to use an extension that has
to simplify initial WA installation. If you try to use an plugin that has
additional, unmet dependencies, WA will tell you before starting the run, and
you can install it then. They are listed here for those that would rather
install them upfront (e.g. if you're planning to use WA to an environment that
@ -148,7 +148,7 @@ may not always have Internet access).
* jinja2
.. note:: Some packages have C extensions and will require Python development
.. note:: Some packages have C plugins and will require Python development
headers to install. You can get those by installing ``python-dev``
package in apt on Ubuntu (or the equivalent for your distribution).
@ -184,7 +184,7 @@ version $version".
(Optional) Post Installation
============================
Some WA extensions have additional dependencies that need to be
Some WA plugins have additional dependencies that need to be
statisfied before they can be used. Not all of these can be provided with WA and
so will need to be supplied by the user. They should be placed into
``~/.workload_uatomation/dependencies/<extenion name>`` so that WA can find
@ -292,12 +292,12 @@ Maintaining Centralized Assets Repository
-----------------------------------------
If there are multiple users within an organization that may need to deploy
assets for WA extensions, that organization may wish to maintain a centralized
assets for WA plugins, that organization may wish to maintain a centralized
repository of assets that individual WA installs will be able to automatically
retrieve asset files from as they are needed. This repository can be any
directory on a network filer that mirrors the structure of
``~/.workload_automation/dependencies``, i.e. has a subdirectories named after
the extensions which assets they contain. Individual WA installs can then set
the plugins which assets they contain. Individual WA installs can then set
``remote_assets_path`` setting in their config to point to the local mount of
that location.

6
doc/source/invocation.rst
View File

@ -84,18 +84,18 @@ configuration files used during execution.
list
----
This lists all extensions of a particular type. For example ::
This lists all plugins of a particular type. For example ::
wa list workloads
will list all workloads currently included in WA. The list will consist of
extension names and short descriptions of the functionality they offer.
plugin names and short descriptions of the functionality they offer.
show
----
This will show detailed information about an extension, including more in-depth
This will show detailed information about an plugin, including more in-depth
description and any parameters/configuration that are available. For example
executing ::

2
doc/source/revent.rst
View File

@ -28,7 +28,7 @@ Recording
To record, transfer the revent binary to the device, then invoke ``revent
record``, giving it the time (in seconds) you want to record for, and the
file you want to record to (WA expects these files to have .revent
extension)::
plugin)::
host$ adb push revent /data/local/revent
host$ adb shell

134
doc/source/writing_extensions.rst
View File

@ -1,10 +1,10 @@
.. _writing_extensions:
.. _writing_plugins:
==================
Writing Extensions
Writing Plugins
==================
Workload Automation offers several extension points (or plugin types).The most
Workload Automation offers several plugin points (or plugin types).The most
interesting of these are
:workloads: These are the tasks that get executed and measured on the device. These
@ -21,26 +21,26 @@ interesting of these are
iteration or at the end of the run, after all of the results have been
collected.
You create an extension by subclassing the appropriate base class, defining
You create an plugin by subclassing the appropriate base class, defining
appropriate methods and attributes, and putting the .py file with the class into
an appropriate subdirectory under ``~/.workload_automation`` (there is one for
each extension type).
each plugin type).
Extension Basics
Plugin Basics
================
This sub-section covers things common to implementing extensions of all types.
This sub-section covers things common to implementing plugins of all types.
It is recommended you familiarize yourself with the information here before
proceeding onto guidance for specific extension types.
proceeding onto guidance for specific plugin types.
To create an extension, you basically subclass an appropriate base class and them
To create an plugin, you basically subclass an appropriate base class and them
implement the appropriate methods
The Context
-----------
The majority of methods in extensions accept a context argument. This is an
The majority of methods in plugins accept a context argument. This is an
instance of :class:`wlauto.core.execution.ExecutionContext`. If contains
of information about current state of execution of WA and keeps track of things
like which workload is currently running and the current iteration.
@ -79,7 +79,7 @@ In addition to these, context also defines a few useful paths (see below).
Paths
-----
You should avoid using hard-coded absolute paths in your extensions whenever
You should avoid using hard-coded absolute paths in your plugins whenever
possible, as they make your code too dependent on a particular environment and
may mean having to make adjustments when moving to new (host and/or device)
platforms. To help avoid hard-coded absolute paths, WA automation defines
@ -90,7 +90,7 @@ On the host
~~~~~~~~~~~
Host paths are available through the context object, which is passed to most
extension methods.
plugin methods.
context.run_output_directory
This is the top-level output directory for all WA results (by default,
@ -103,14 +103,14 @@ context.output_directory
this will point to the same location as ``root_output_directory``.
context.host_working_directory
This an addition location that may be used by extensions to store
This an addition location that may be used by plugins to store
non-iteration specific intermediate files (e.g. configuration).
Additionally, the global ``wlauto.settings`` object exposes on other location:
settings.dependency_directory
this is the root directory for all extension dependencies (e.g. media
files, assets etc) that are not included within the extension itself.
this is the root directory for all plugin dependencies (e.g. media
files, assets etc) that are not included within the plugin itself.
As per Python best practice, it is recommended that methods and values in
``os.path`` standard library module are used for host path manipulation.
@ -147,7 +147,7 @@ Deploying executables to a device
---------------------------------
Some devices may have certain restrictions on where executable binaries may be
placed and how they should be invoked. To ensure your extension works with as
placed and how they should be invoked. To ensure your plugin works with as
wide a range of devices as possible, you should use WA APIs for deploying and
invoking executables on a device, as outlined below.
@ -160,7 +160,7 @@ As with other resources (see :ref:`resources`) , host-side paths to the exectuab
In order for the binary to be obtained in this way, it must be stored in one of
the locations scanned by the resource resolver in a directry structure
``<root>/bin/<abi>/<binary>`` (where ``root`` is the base resource location to
be searched, e.g. ``~/.workload_automation/depencencies/<extension name>``, and
be searched, e.g. ``~/.workload_automation/depencencies/<plugin name>``, and
``<abi>`` is the ABI for which the exectuable has been compiled, as returned by
``self.device.abi``).
@ -193,14 +193,14 @@ device. The executable should be invoked *only* via that path; do **not** assume
Parameters
----------
All extensions can be parameterized. Parameters are specified using
All plugins can be parameterized. Parameters are specified using
``parameters`` class attribute. This should be a list of
:class:`wlauto.core.Parameter` instances. The following attributes can be
specified on parameter creation:
name
This is the only mandatory argument. The name will be used to create a
corresponding attribute in the extension instance, so it must be a valid
corresponding attribute in the plugin instance, so it must be a valid
Python identifier.
kind
@ -247,8 +247,8 @@ constraint
a ``bool`` indicating whether the constraint has been satisfied).
override
A parameter name must be unique not only within an extension but also
with that extension's class hierarchy. If you try to declare a parameter
A parameter name must be unique not only within an plugin but also
with that plugin's class hierarchy. If you try to declare a parameter
with the same name as already exists, you will get an error. If you do
want to override a parameter from further up in the inheritance
hierarchy, you can indicate that by setting ``override`` attribute to
@ -262,19 +262,19 @@ override
Validation and cross-parameter constraints
------------------------------------------
An extension will get validated at some point after constructions. When exactly
this occurs depends on the extension type, but it *will* be validated before it
An plugin will get validated at some point after constructions. When exactly
this occurs depends on the plugin type, but it *will* be validated before it
is used.
You can implement ``validate`` method in your extension (that takes no arguments
You can implement ``validate`` method in your plugin (that takes no arguments
beyond the ``self``) to perform any additions *internal* validation in your
extension. By "internal", I mean that you cannot make assumptions about the
plugin. By "internal", I mean that you cannot make assumptions about the
surrounding environment (e.g. that the device has been initialized).
The contract for ``validate`` method is that it should raise an exception
(either ``wlauto.exceptions.ConfigError`` or extension-specific exception type -- see
(either ``wlauto.exceptions.ConfigError`` or plugin-specific exception type -- see
further on this page) if some validation condition has not, and cannot, been met.
If the method returns without raising an exception, then the extension is in a
If the method returns without raising an exception, then the plugin is in a
valid internal state.
Note that ``validate`` can be used not only to verify, but also to impose a
@ -287,12 +287,12 @@ on creation and should instead be set inside ``validate``.
Logging
-------
Every extension class has it's own logger that you can access through
``self.logger`` inside the extension's methods. Generally, a :class:`Device` will log
Every plugin class has it's own logger that you can access through
``self.logger`` inside the plugin's methods. Generally, a :class:`Device` will log
everything it is doing, so you shouldn't need to add much additional logging in
your expansion's. But you might what to log additional information, e.g.
what settings your extension is using, what it is doing on the host, etc.
Operations on the host will not normally be logged, so your extension should
what settings your plugin is using, what it is doing on the host, etc.
Operations on the host will not normally be logged, so your plugin should
definitely log what it is doing on the host. One situation in particular where
you should add logging is before doing something that might take a significant amount
of time, such as downloading a file.
@ -301,10 +301,10 @@ of time, such as downloading a file.
Documenting
-----------
All extensions and their parameter should be documented. For extensions
All plugins and their parameter should be documented. For plugins
themselves, this is done through ``description`` class attribute. The convention
for an extension description is that the first paragraph should be a short
summary description of what the extension does and why one would want to use it
for an plugin description is that the first paragraph should be a short
summary description of what the plugin does and why one would want to use it
(among other things, this will get extracted and used by ``wa list`` command).
Subsequent paragraphs (separated by blank lines) can then provide a more
detailed description, including any limitations and setup instructions.
@ -316,15 +316,15 @@ documentation utilities will automatically pull those). If the ``default`` is se
in ``validate`` or additional cross-parameter constraints exist, this *should*
be documented in the parameter description.
Both extensions and their parameters should be documented using reStructureText
Both plugins and their parameters should be documented using reStructureText
markup (standard markup for Python documentation). See:
http://docutils.sourceforge.net/rst.html
Aside from that, it is up to you how you document your extension. You should try
to provide enough information so that someone unfamiliar with your extension is
Aside from that, it is up to you how you document your plugin. You should try
to provide enough information so that someone unfamiliar with your plugin is
able to use it, e.g. you should document all settings and parameters your
extension expects (including what the valid value are).
plugin expects (including what the valid value are).
Error Notification
@ -332,7 +332,7 @@ Error Notification
When you detect an error condition, you should raise an appropriate exception to
notify the user. The exception would typically be :class:`ConfigError` or
(depending the type of the extension)
(depending the type of the plugin)
:class:`WorkloadError`/:class:`DeviceError`/:class:`InstrumentError`/:class:`ResultProcessorError`.
All these errors are defined in :mod:`wlauto.exception` module.
@ -341,12 +341,12 @@ specified by the user (either through the agenda or config files). These errors
are meant to be resolvable by simple adjustments to the configuration (and the
error message should suggest what adjustments need to be made. For all other
errors, such as missing dependencies, mis-configured environment, problems
performing operations, etc., the extension type-specific exceptions should be
performing operations, etc., the plugin type-specific exceptions should be
used.
If the extension itself is capable of recovering from the error and carrying
If the plugin itself is capable of recovering from the error and carrying
on, it may make more sense to log an ERROR or WARNING level message using the
extension's logger and to continue operation.
plugin's logger and to continue operation.
Utils
@ -355,7 +355,7 @@ Utils
Workload Automation defines a number of utilities collected under
:mod:`wlauto.utils` subpackage. These utilities were created to help with the
implementation of the framework itself, but may be also be useful when
implementing extensions.
implementing plugins.
Adding a Workload
@ -371,7 +371,7 @@ New workloads can be added by subclassing :class:`wlauto.core.workload.Workload`
The Workload class defines the following interface::
class Workload(Extension):
class Workload(Plugin):
name = None
@ -513,7 +513,7 @@ file of a particular size on the device.
self.device_infile = devpath.join(self.device.working_directory, 'infile')
self.device_outfile = devpath.join(self.device.working_directory, 'outfile')
# Push the file to the device
self.device.push_file(host_infile, self.device_infile)
self.device.push(host_infile, self.device_infile)
def run(self, context):
self.device.execute('cd {} && (time gzip {}) &>> {}'.format(self.device.working_directory,
@ -523,7 +523,7 @@ file of a particular size on the device.
def update_result(self, context):
# Pull the results file to the host
host_outfile = os.path.join(context.output_directory, 'outfile')
self.device.pull_file(self.device_outfile, host_outfile)
self.device.pull(self.device_outfile, host_outfile)
# Extract metrics form the file's contents and update the result
# with them.
content = iter(open(host_outfile).read().strip().split())
@ -533,8 +533,8 @@ file of a particular size on the device.
def teardown(self, context):
# Clean up on-device file.
self.device.delete_file(self.device_infile)
self.device.delete_file(self.device_outfile)
self.device.remove(self.device_infile)
self.device.remove(self.device_outfile)
@ -560,7 +560,7 @@ The interface should be implemented as follows
:name: This identifies the workload (e.g. it used to specify it in the
agenda_.
:package: This is the name of the '.apk' package without its file extension.
:package: This is the name of the '.apk' package without its file plugin.
:activity: The name of the main activity that runs the package.
Example:
@ -615,7 +615,7 @@ execution (e.g. collect power readings). An instrument can hook into almost any
stage of workload execution. A typical instrument would implement a subset of
the following interface::
class Instrument(Extension):
class Instrument(Plugin):
name = None
description = None
@ -736,7 +736,7 @@ You can add your own result processors by creating a Python file in
``~/.workload_automation/result_processors`` with a class that derives from
:class:`wlauto.core.result.ResultProcessor`, which has the following interface::
class ResultProcessor(Extension):
class ResultProcessor(Plugin):
name = None
description = None
@ -806,7 +806,7 @@ table::
Adding a Resource Getter
========================
A resource getter is a new extension type added in version 2.1.3. A resource
A resource getter is a new plugin type added in version 2.1.3. A resource
getter implement a method of acquiring resources of a particular type (such as
APK files or additional workload assets). Resource getters are invoked in
priority order until one returns the desired resource.
@ -818,7 +818,7 @@ invoked first.
Instances of a resource getter should implement the following interface::
class ResourceGetter(Extension):
class ResourceGetter(Plugin):
name = None
resource_type = None
@ -827,7 +827,7 @@ Instances of a resource getter should implement the following interface::
def get(self, resource, **kwargs):
raise NotImplementedError()
The getter should define a name (as with all extensions), a resource
The getter should define a name (as with all plugins), a resource
type, which should be a string, e.g. ``'jar'``, and a priority (see `Getter
Prioritization`_ below). In addition, ``get`` method should be implemented. The
first argument is an instance of :class:`wlauto.core.resource.Resource`
@ -953,10 +953,10 @@ Please refer to the API documentation for :class:`wlauto.common.AndroidDevice`
for the full list of its methods and their functionality.
Other Extension Types
Other Plugin Types
=====================
In addition to extension types covered above, there are few other, more
In addition to plugin types covered above, there are few other, more
specialized ones. They will not be covered in as much detail. Most of them
expose relatively simple interfaces with only a couple of methods and it is
expected that if the need arises to extend them, the API-level documentation
@ -965,19 +965,19 @@ provide enough guidance.
:commands: This allows extending WA with additional sub-commands (to supplement
exiting ones outlined in the :ref:`invocation` section).
:modules: Modules are "extensions for extensions". They can be loaded by other
extensions to expand their functionality (for example, a flashing
:modules: Modules are "plugins for plugins". They can be loaded by other
plugins to expand their functionality (for example, a flashing
module maybe loaded by a device in order to support flashing).
Packaging Your Extensions
Packaging Your Plugins
=========================
If your have written a bunch of extensions, and you want to make it easy to
If your have written a bunch of plugins, and you want to make it easy to
deploy them to new systems and/or to update them on existing systems, you can
wrap them in a Python package. You can use ``wa create package`` command to
generate appropriate boiler plate. This will create a ``setup.py`` and a
directory for your package that you can place your extensions into.
directory for your package that you can place your plugins into.
For example, if you have a workload inside ``my_workload.py`` and a result
processor in ``my_result_processor.py``, and you want to package them as
@ -987,17 +987,17 @@ processor in ``my_result_processor.py``, and you want to package them as
This will create a ``my_wa_exts`` directory which contains a
``my_wa_exts/setup.py`` and a subdirectory ``my_wa_exts/my_wa_exts`` which is
the package directory for your extensions (you can rename the top-level
the package directory for your plugins (you can rename the top-level
``my_wa_exts`` directory to anything you like -- it's just a "container" for the
setup.py and the package directory). Once you have that, you can then copy your
extensions into the package directory, creating
plugins into the package directory, creating
``my_wa_exts/my_wa_exts/my_workload.py`` and
``my_wa_exts/my_wa_exts/my_result_processor.py``. If you have a lot of
extensions, you might want to organize them into subpackages, but only the
plugins, you might want to organize them into subpackages, but only the
top-level package directory is created by default, and it is OK to have
everything in there.
.. note:: When discovering extensions thorugh this mechanism, WA traveries the
.. note:: When discovering plugins thorugh this mechanism, WA traveries the
Python module/submodule tree, not the directory strucuter, therefore,
if you are going to create subdirectories under the top level dictory
created for you, it is important that your make sure they are valid
@ -1023,9 +1023,9 @@ management tools, e.g. ::
As part of the installation process, the setup.py in the package, will write the
package's name into ``~/.workoad_automoation/packages``. This will tell WA that
the package contains extension and it will load them next time it runs.
the package contains plugin and it will load them next time it runs.
.. note:: There are no unistall hooks in ``setuputils``, so if you ever
uninstall your WA extensions package, you will have to manually remove
uninstall your WA plugins package, you will have to manually remove
it from ``~/.workload_automation/packages`` otherwise WA will complain
abou a missing package next time you try to run it.