BaseLinuxDevice: documentation update

Added docs explaining how extension developers should deploy binaries.

doc/source/resources.rst

@@ -1,3 +1,5 @@
+.. _resources:
+
 Dynamic Resource Resolution
 ===========================
 

doc/source/writing_extensions.rst

@@ -132,12 +132,63 @@ device, the ``os.path`` modules should *not* be used for on-device path
 manipulation. Instead device has an equipment module exposed through
 ``device.path`` attribute. This has all the same attributes and behaves the
 same way as ``os.path``, but is guaranteed to produce valid paths for the device,
-irrespective of the host's path notation.
+irrespective of the host's path notation. For example:
+
+.. code:: python
+
+    result_file = self.device.path.join(self.device.working_directory, "result.txt")
+    self.command = "{} -a -b -c {}".format(target_binary, result_file)
 
 .. note:: result processors, unlike workloads and instruments, do not have their
           own device attribute; however they can access the device through the
           context.
 
+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
+wide a range of devices as possible, you should use WA APIs for deploying and
+invoking executables on a device, as outlined below.
+
+As with other resources (see :ref:`resources`) , host-side paths to the exectuable
+ binary to be deployed should be obtained via the resource resolver. A special
+ resource type, ``Executable`` is used to identify  a binary to be deployed.
+ This  is simiar to the regular ``File`` resource, however it takes an additional
+ parameter that specifies the ABI for which executable was compiled.
+
+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
+ ``<abi>`` is the ABI for which the exectuable has been compiled, as returned by
+  ``self.device.abi``).
+
+Once the path to the host-side binary has been obtained, it may be deployed using
+one of two methods of a ``Device`` instace -- ``install`` or ``install_if_needed``.
+The latter will check a version of that binary has been perviously deployed by
+WA and will not try to re-install.
+
+.. code:: python
+
+  from wlauto import Executable
+
+  host_binary = context.resolver.get(Executable(self, self.device.abi, 'some_binary'))
+  target_binary = self.device.install_if_needed(host_binary)
+
+
+.. note:: Please also note that the check is done based solely on the binary name.
+          For more information please see: :func:`wlauto.common.linux.BaseLinuxDevice.install_if_needed`
+
+Both of the above methods will return the path to the installed binary on the
+device. 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
+
+  self.command = "{} -a -b -c".format(target_binary)
+  self.device.execute(self.command)
 
 Parameters
 ----------