pw_target_runner

Pigweed AI summary: The pw_target_runner module is a gRPC server that runs executables in parallel, either directly on the host or on attached targets. It allows unit tests to be run across multiple devices simultaneously, reducing the overall time it takes to run a collection of tests. The module provides a library in various programming languages that includes a core gRPC server and a mechanism for registering worker routines. It also provides a standalone program, pw_target_runner_server, which runs the server with configurable workers that launch external processes to

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

Pigweed AI summary: The target runner server is a library that processes requests to distribute executables among a pool of workers that run in parallel, reducing the overall time it takes to run a collection of tests. It 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. The target runner is implemented as a library in various programming languages and provides a standalone program that runs the server with configurable workers that launch external processes to

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

Pigweed AI summary: This section explains how to use the pw_target_runner_server program to set up a unit test server with workers. The server is configured using a Protobuf text file that specifies at least one worker, each referring to a script or program that is invoked with the path to an executable file as a positional argument. The section provides an example config file with two workers connecting to an STM32F429I Discovery board. To run the server, the pw_target_runner_server program is executed with the config file and

This section describes how to use the pw_target_runner_server program to set up a simple unit test server with workers.

Configuration

Pigweed AI summary: The standalone server is configured using a Protobuf text format file that contains a message defined in exec_server_config.proto. The file must specify at least one worker, which refers to a script or program that is invoked with the path to an executable file as a positional argument. The example config file provided in the text defines two workers, each connecting to an STM32F429I Discovery board with a specified serial number.

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

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

Pigweed AI summary: To run the standalone server, use the "pw_target_runner_server" program and specify the location of the config file. The command should include the config file name and the port number.

To start the standalone server, run the pw_target_runner_server program and point it to your config file.

$ pw_target_runner_server -config server_config.txt -port 8080

Sending requests

Pigweed AI summary: To request the server to run an executable, use the "pw_target_runner_client" command and specify the path to the executable through the "-binary" option. The command will block until the executable has finished running, and multiple requests can be scheduled in parallel. The server will distribute the requests among its available workers.

To request the server to run an executable, run the pw_target_runner_client, specifying the path to the executable through a -binary option.

$ 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

Pigweed AI summary: This paragraph provides information on how to use the target runner library in your own code by referring to one of its programming language APIs listed below.

To use the target runner library in your own code, refer to one of its programming language APIs below.

• Go