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