Development

This project uses a Docker image to containerize the development environment.

SDK setup

• clone the repository

• build the SDK image via ./sdk/build.sh

• start the SDK via ./sdk/run.sh

• In the SDK, install the image via pdm install -p yarpc

Testing

While there exist some unit tests for yarpc, that can be run via yarpc/run_tests.sh, most of the functionality is tested via behave tests.

The interface definitions in tests/definitions are used to generate mock, service and client code covering all features supported by yarpc. For each supported language, there exists a service that will connect to the defined client interface and forward the signals, method calls and properties to its own D-Bus interface.

The behave tests then use the generated mocks to connect to the service and test the interfaces:

      Behave                Service under test            Behave
BackendServiceMock <-> [BackendClient <-> Service ] <-> ClientMock

The interface code can be generated by running tests/generate.sh. The behave tests can be run via tests/run_tests.sh.

Manual Testing

For manual testing, the BackendServiceMock can also be started manually via pdm run -p tests/python_mocks mock.

The SDK contains d-feet to call D-Bus methods and interact with properties and bustle to monitor signals.

Adding support for a new language

1. Add language support to the SDK

   If the new language needs additional libraries, compilers or other tools, install them in the sdk/Dockerfile.

2. Run bootstrapping script

   Start the SDK and run the sdk/add_language.sh script and answer the questions.

   This will create skeleton entries for the new language in

   • yarpc/languages for the generation of the language

   • tests for the service used in the behave tests

   • tests/definitions for the output to be generated

   • tests/behave-tests for the behave tests of this language

   • docs/source/chapters/outputs for the documentation of this language

   It will also add the behave tests to the run_tests.sh script and the CI workflow.

3. Adjust the skeleton entries

   • Document dependencies (such as the library used for D-Bus) and additional options for the output of your language

   • Adjust the templates, json schema and Language class for your language (see Language folder)

   • Flesh out the app in tests/<language>_service, so it can be compiled and started using the run.sh (and optionally build.sh) script

4. Implement the generator

   1. Look at the first not-yet implemented interface in tests/definitions

   2. Implement the functionality in the templates of your language

   3. Run the tests/generate.sh script

   4. Implement the D-Bus interface in your service using the generated code, so that the interface of your service mirrors the backend interface it connects to

   5. Run the behave test for the respective interface to check whether it works

   6. Repeat from (a) until all interfaces are implemented

Language folder

Yarpc will automatically load all languages found in the languages folder of its package. These languages consist of a folder with the same name as the key used for them in the YAML interface definitions. The folder contains

• The __init__.py containing the Language class The Language class determines which templates are used for which objects and how the resulting output should be named and the mapping of D-Bus types to types of this language.

• The schema.json jsonschema for this language. This determines the format of the output for this language. Modify it to add additional keys (e.g. for namespaces or mocks)

• The templates referenced in the Language class