From c51593a729469bc58641c302261199834f3132e6 Mon Sep 17 00:00:00 2001 From: Sebastian Goscik Date: Thu, 17 Mar 2016 15:25:54 +0000 Subject: [PATCH] pluginloader: Updated documentation to say plugin instead of extension --- doc/Makefile | 10 +-- doc/build_extension_docs.py | 19 ++--- doc/source/additional_topics.rst | 20 ++--- doc/source/agenda.rst | 2 +- doc/source/changes.rst | 22 ++--- doc/source/configuration.rst | 40 ++++----- doc/source/contributing.rst | 6 +- doc/source/conventions.rst | 2 +- doc/source/daq_device_setup.rst | 2 +- doc/source/device_setup.rst | 4 +- doc/source/execution_model.rst | 4 +- doc/source/index.rst | 24 +++--- doc/source/installation.rst | 12 +-- doc/source/invocation.rst | 6 +- doc/source/revent.rst | 2 +- doc/source/writing_extensions.rst | 134 +++++++++++++++--------------- 16 files changed, 154 insertions(+), 155 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 64237c70..4d7c0cf2 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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) diff --git a/doc/build_extension_docs.py b/doc/build_extension_docs.py index bee61cdd..3abd0c5d 100755 --- a/doc/build_extension_docs.py +++ b/doc/build_extension_docs.py @@ -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:]) diff --git a/doc/source/additional_topics.rst b/doc/source/additional_topics.rst index 8a49a93a..3668aaaf 100644 --- a/doc/source/additional_topics.rst +++ b/doc/source/additional_topics.rst @@ -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. diff --git a/doc/source/agenda.rst b/doc/source/agenda.rst index 5b5ac690..2b90af83 100644 --- a/doc/source/agenda.rst +++ b/doc/source/agenda.rst @@ -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 diff --git a/doc/source/changes.rst b/doc/source/changes.rst index 6bc3fba2..297965b7 100644 --- a/doc/source/changes.rst +++ b/doc/source/changes.rst @@ -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`` diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 1a0b1c50..c72be203 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -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. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index f79b4ca2..31dcaaf3 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -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. diff --git a/doc/source/conventions.rst b/doc/source/conventions.rst index c811f522..e35a0b6a 100644 --- a/doc/source/conventions.rst +++ b/doc/source/conventions.rst @@ -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. :: diff --git a/doc/source/daq_device_setup.rst b/doc/source/daq_device_setup.rst index bf261e4a..0c4b4350 100644 --- a/doc/source/daq_device_setup.rst +++ b/doc/source/daq_device_setup.rst @@ -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). diff --git a/doc/source/device_setup.rst b/doc/source/device_setup.rst index 9c5b867b..c589e3ab 100644 --- a/doc/source/device_setup.rst +++ b/doc/source/device_setup.rst @@ -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. diff --git a/doc/source/execution_model.rst b/doc/source/execution_model.rst index 3140583b..640b03d1 100644 --- a/doc/source/execution_model.rst +++ b/doc/source/execution_model.rst @@ -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 `. 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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 46095f5d..d1c92cf9 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 7c2fbf09..3bcb92f1 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -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/`` 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. diff --git a/doc/source/invocation.rst b/doc/source/invocation.rst index 5c8ead92..115adb19 100644 --- a/doc/source/invocation.rst +++ b/doc/source/invocation.rst @@ -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 :: diff --git a/doc/source/revent.rst b/doc/source/revent.rst index d5811683..9f52c342 100644 --- a/doc/source/revent.rst +++ b/doc/source/revent.rst @@ -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 diff --git a/doc/source/writing_extensions.rst b/doc/source/writing_extensions.rst index 15fa6713..c2e4d366 100644 --- a/doc/source/writing_extensions.rst +++ b/doc/source/writing_extensions.rst @@ -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 ``/bin//`` (where ``root`` is the base resource location to -be searched, e.g. ``~/.workload_automation/depencencies/``, and +be searched, e.g. ``~/.workload_automation/depencencies/``, and ```` 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.