From 0fd095622cd9df3ac157206807499a5ee46c43e6 Mon Sep 17 00:00:00 2001 From: Marc Bonnici Date: Thu, 26 Apr 2018 17:18:38 +0100 Subject: [PATCH] doc: Improve installing executables documentation --- .../writing_extensions.rst | 7 ++-- .../how_tos/developers/adding_plugins.rst | 38 +++++++++++++++++++ doc/source/migration_guide.rst | 6 +++ 3 files changed, 48 insertions(+), 3 deletions(-) diff --git a/doc/source/developer_reference/writing_extensions.rst b/doc/source/developer_reference/writing_extensions.rst index 0dcc8ae6..d6a3121e 100644 --- a/doc/source/developer_reference/writing_extensions.rst +++ b/doc/source/developer_reference/writing_extensions.rst @@ -265,6 +265,7 @@ looking for an executable file would do so like this:: Currently available resource types are defined in :py:mod:`wa.framework.resources`. +.. _deploying-executables: Deploying executables to a target ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -309,10 +310,9 @@ target. The executable should be invoked *only* via that path; do **not** assume that it will be in ``PATH`` on the target (or that the executable with the same name in ``PATH`` is the version deployed by WA. -.. code:: python +For more information on how to implement this, please see the +:ref:`how to guide `. - self.command = "{} -a -b -c".format(target_binary) - self.target.execute(self.command) Deploying assets ----------------- @@ -487,6 +487,7 @@ 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 plugin's logger and to continue operation. +.. _decorators: Execution Decorators --------------------- diff --git a/doc/source/how_tos/developers/adding_plugins.rst b/doc/source/how_tos/developers/adding_plugins.rst index 696ee3a9..842e9543 100644 --- a/doc/source/how_tos/developers/adding_plugins.rst +++ b/doc/source/how_tos/developers/adding_plugins.rst @@ -1,3 +1,41 @@ +.. _deploying-executables-guide: + +Installing Binaries Example +=========================== + +Installing binaries for a particular plugin should generally only be performed +once during a run. This should typically be done in the ``initialize`` method, +if the only functionality performed in the method is to install the required binaries +then the ``initialize`` method should be decorated with the ``@once`` +:ref:`decorator ` otherwise this should be placed into a dedicated +method which is decorated instead. Please note if doing this then any installed +paths should be added as class attributes rather than instance variables. As a +general rule if binaries are installed as part of ``initialize`` then they +should be installed in the complementary ``finalize`` method. + +Part of an example workload demonstrating this is shown below: + +.. code:: python + + class MyWorkload(Workload): + #.. + @once + def initialize(self, context): + resource = Executable(self, self.target.abi, 'my_executable') + host_binary = context.resolver.get(resource) + MyWorkload.target_binary = self.target.install(host_binary) + #.. + + def setup(self, context): + self.command = "{} -a -b -c".format(self.target_binary) + self.target.execute(self.command) + #.. + + @once + def finalize(self, context): + self.target.uninstall('my_executable') + + .. _adding-a-workload: Adding a Workload Examples diff --git a/doc/source/migration_guide.rst b/doc/source/migration_guide.rst index 3dc24879..700b51cf 100644 --- a/doc/source/migration_guide.rst +++ b/doc/source/migration_guide.rst @@ -147,6 +147,12 @@ The ``update_results`` method has been split out into 2 stages. There is now any results from the target back to the host system and to update the output with any metrics or artefacts for the specific workload iteration respectively. +WA now features :ref:`decorators ` which can be used to allow for more efficient +binary deployment and that they are only installed to the device once per run. For +more information of implementing this please see +:ref:`deploying executables to a target `. + + APK Functionality ^^^^^^^^^^^^^^^^^ All apk functionality has re-factored into an APKHandler object which is