doc: Improve installing executables documentation

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 <deploying-executables-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
 ---------------------

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 <decorators>` 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

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 <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 <deploying-executables>`.
+
+
 APK Functionality
 ^^^^^^^^^^^^^^^^^
 All apk functionality has re-factored into an APKHandler object which is