You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
105 lines
3.7 KiB
105 lines
3.7 KiB
.. _module-pw_target_runner:
|
|
|
|
----------------
|
|
pw_target_runner
|
|
----------------
|
|
The target runner module implements a gRPC server designed to run executables
|
|
in parallel. These executables may be run directly on the host, or flashed to
|
|
one or more attached targets.
|
|
|
|
Overview
|
|
--------
|
|
The target runner server is responsible for processing requests to distribute
|
|
executables among a pool of workers that run in parallel. This allows things
|
|
like unit tests to be run across multiple devices simultaneously, greatly
|
|
reducing the overall time it takes to run a collection of tests.
|
|
|
|
Additionally, the server allows many executables to be queued up at once and
|
|
scheduled across available devices, making it possible to automatically run unit
|
|
tests from a Ninja build after code is updated. This integrates nicely with the
|
|
``pw watch`` command to re-run all affected unit tests after modifying code.
|
|
|
|
The target runner is implemented as a library in various programming languages.
|
|
This library provides the core gRPC server and a mechanism through which worker
|
|
routines can be registered. Code using the library instantiates a server with
|
|
some custom workers for the desired target to run passed executables.
|
|
|
|
The ``pw_target_runner`` module also provides a standalone
|
|
``pw_target_runner_server`` program which runs the server with configurable
|
|
workers that launch external processes to execute passed binaries. This
|
|
program should be sufficient to quickly get unit tests running in a simple
|
|
setup, such as multiple devices plugged into a development machine.
|
|
|
|
Standalone executable
|
|
---------------------
|
|
This section describes how to use the ``pw_target_runner_server`` program to
|
|
set up a simple unit test server with workers.
|
|
|
|
Configuration
|
|
^^^^^^^^^^^^^
|
|
The standalone server is configured from a file written in Protobuf text format
|
|
containing a ``pw.target_runner.ServerConfig`` message as defined in
|
|
``//pw_target_runner/pw_target_runner_server_protos/exec_server_config.proto``.
|
|
|
|
At least one ``worker`` message must be specified. Each of the workers refers to
|
|
a script or program which is invoked with the path to an executable file as a
|
|
positional argument. Other arguments provided to the program must be options/
|
|
switches.
|
|
|
|
For example, the config file below defines two workers, each connecting to an
|
|
STM32F429I Discovery board with a specified serial number.
|
|
|
|
**server_config.txt**
|
|
|
|
.. code:: text
|
|
|
|
runner {
|
|
command: "stm32f429i_disc1_unit_test_runner"
|
|
args: "--openocd-config"
|
|
args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg"
|
|
args: "--serial"
|
|
args: "066DFF575051717867013127"
|
|
}
|
|
|
|
runner {
|
|
command: "stm32f429i_disc1_unit_test_runner"
|
|
args: "--openocd-config"
|
|
args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg"
|
|
args: "--serial"
|
|
args: "0667FF494849887767196023"
|
|
}
|
|
|
|
|
|
Running the server
|
|
^^^^^^^^^^^^^^^^^^
|
|
To start the standalone server, run the ``pw_target_runner_server`` program and
|
|
point it to your config file.
|
|
|
|
.. code:: text
|
|
|
|
$ pw_target_runner_server -config server_config.txt -port 8080
|
|
|
|
|
|
Sending requests
|
|
^^^^^^^^^^^^^^^^
|
|
To request the server to run an executable, run the ``pw_target_runner_client``,
|
|
specifying the path to the executable through a ``-binary`` option.
|
|
|
|
.. code:: text
|
|
|
|
$ pw_target_runner_client -host localhost -port 8080 -binary /path/to/my/test.elf
|
|
|
|
This command blocks until the executable has finished running. Multiple
|
|
requests can be scheduled in parallel; the server will distribute them among its
|
|
available workers.
|
|
|
|
Library APIs
|
|
------------
|
|
To use the target runner library in your own code, refer to one of its
|
|
programming language APIs below.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
go/docs
|