Development
===========


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

.. _sdk-setup:

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:

.. code::

         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 :ref:`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

   a. Look at the first not-yet implemented interface in ``tests/definitions``
   b. Implement the functionality in the templates of your language
   c. Run the ``tests/generate.sh`` script
   d. 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
   e. Run the behave test for the respective interface to check whether it works
   f. Repeat from (a) until all interfaces are implemented

.. _language_folder:

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