third_party/pigweed/repo/pw_target_runner/docs.rst

   1 .. _module-pw_target_runner:
   2
   3 ----------------
   4 pw_target_runner
   5 ----------------
   6 The target runner module implements a gRPC server designed to run executables
   7 in parallel. These executables may be run directly on the host, or flashed to
   8 one or more attached targets.
   9
  10 Overview
  11 --------
  12 The target runner server is responsible for processing requests to distribute
  13 executables among a pool of workers that run in parallel. This allows things
  14 like unit tests to be run across multiple devices simultaneously, greatly
  15 reducing the overall time it takes to run a collection of tests.
  16
  17 Additionally, the server allows many executables to be queued up at once and
  18 scheduled across available devices, making it possible to automatically run unit
  19 tests from a Ninja build after code is updated. This integrates nicely with the
  20 ``pw watch`` command to re-run all affected unit tests after modifying code.
  21
  22 The target runner is implemented as a library in various programming languages.
  23 This library provides the core gRPC server and a mechanism through which worker
  24 routines can be registered. Code using the library instantiates a server with
  25 some custom workers for the desired target to run passed executables.
  26
  27 The ``pw_target_runner`` module also provides a standalone
  28 ``pw_target_runner_server`` program which runs the server with configurable
  29 workers that launch external processes to execute passed binaries. This
  30 program should be sufficient to quickly get unit tests running in a simple
  31 setup, such as multiple devices plugged into a development machine.
  32
  33 Standalone executable
  34 ---------------------
  35 This section describes how to use the ``pw_target_runner_server`` program to
  36 set up a simple unit test server with workers.
  37
  38 Configuration
  39 ^^^^^^^^^^^^^
  40 The standalone server is configured from a file written in Protobuf text format
  41 containing a ``pw.target_runner.ServerConfig`` message as defined in
  42 ``//pw_target_runner/pw_target_runner_server_protos/exec_server_config.proto``.
  43
  44 At least one ``worker`` message must be specified. Each of the workers refers to
  45 a script or program which is invoked with the path to an executable file as a
  46 positional argument. Other arguments provided to the program must be options/
  47 switches.
  48
  49 For example, the config file below defines two workers, each connecting to an
  50 STM32F429I Discovery board with a specified serial number.
  51
  52 **server_config.txt**
  53
  54 .. code:: text
  55
  56   runner {
  57     command: "stm32f429i_disc1_unit_test_runner"
  58     args: "--openocd-config"
  59     args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg"
  60     args: "--serial"
  61     args: "066DFF575051717867013127"
  62   }
  63
  64   runner {
  65     command: "stm32f429i_disc1_unit_test_runner"
  66     args: "--openocd-config"
  67     args: "targets/stm32f429i-disc1/py/stm32f429i_disc1_utils/openocd_stm32f4xx.cfg"
  68     args: "--serial"
  69     args: "0667FF494849887767196023"
  70   }
  71
  72
  73 Running the server
  74 ^^^^^^^^^^^^^^^^^^
  75 To start the standalone server, run the ``pw_target_runner_server`` program and
  76 point it to your config file.
  77
  78 .. code:: text
  79
  80   $ pw_target_runner_server -config server_config.txt -port 8080
  81
  82
  83 Sending requests
  84 ^^^^^^^^^^^^^^^^
  85 To request the server to run an executable, run the ``pw_target_runner_client``,
  86 specifying the path to the executable through a ``-binary`` option.
  87
  88 .. code:: text
  89
  90   $ pw_target_runner_client -host localhost -port 8080 -binary /path/to/my/test.elf
  91
  92 This command blocks until the executable has finished running. Multiple
  93 requests can be scheduled in parallel; the server will distribute them among its
  94 available workers.
  95
  96 Library APIs
  97 ------------
  98 To use the target runner library in your own code, refer to one of its
  99 programming language APIs below.
 100
 101 .. toctree::
 102   :maxdepth: 1
 103
 104   go/docs