mirror of
https://github.com/mumble-voip/mumble.git
synced 2025-10-26 11:19:16 +00:00
35 lines
3.6 KiB
Markdown
35 lines
3.6 KiB
Markdown
# Incrementing the Mumble API version
|
|
|
|
## Overview
|
|
[Plugins](/docs/dev/plugins/) are used to extend the Mumble client with custom functionality. They are compiled against multiple [header files](/plugins/) which
|
|
contain all function and structure signatures that can be used by the plugin. If you are commiting breaking API changes (such as additions or deletions) to these function signatures
|
|
on the Mumble side, the API version will probably have to be increased. This is done to ensure plugins will have access to these functions when they
|
|
are compiled against the new API version, while old plugins, using previous API versions, will still work.
|
|
|
|
## Instructions
|
|
If your commit includes breaking API changes, the following steps have to be followed:
|
|
|
|
1) Create a new ``Mumble_API_v_<MA>_<MI>_x.h`` file in [plugins/](/plugins/).
|
|
* Replace ``<MA>`` with the API major version and ``<MI>`` with the API minor version.
|
|
* Usually, you will have to increase the ``<MI>`` version by 1 compared to the previous latest version. So if the previous API string was ``1.2.0``, you would probably want to increase the second number by one and create the file ``MumbleAPI_v_1_3_x.h``.
|
|
* The last "patch" digit of the version string is reserved for non-breaking API changes such as small fixes. Since non-breaking changes do not require a major or minor API increment, we do not worry about the "patch" digit in this document.
|
|
1) Make sure you correctly set the ``MUMBLE_PLUGIN_API_MAJOR_MACRO``, ``MUMBLE_PLUGIN_API_MINOR_MACRO`` and [include guard](https://en.wikipedia.org/wiki/Include_guard) to the new API version.
|
|
* You probably want to set the ``MUMBLE_PLUGIN_API_PATCH_MACRO`` to ``0``.
|
|
1) Rename the ``struct`` within the file to match the new API version string.
|
|
* There is a ``typedef`` at the end of the file which has to use the new ``struct`` name, too.
|
|
1) Make your desired changes to the function signatures contained in the header file.
|
|
1) Open the [MumbleAPI_structs.h](/src/mumble/MumbleAPI_structs.h) file and add your new API header file as first include.
|
|
* Move the previous first include, the last most recent API version, into the ``NO_AUXILIARY_DEFINITIONS`` section.
|
|
* This will make sure auxiliary variables and macros always contain the most recent version on the mumble side.
|
|
1) Add an ``else`` case to the [Plugin.cpp](/src/mumble/Plugin.cpp) file in the ``Plugin::init`` method.
|
|
* You will want to return the newly created ``struct``, if the API version requested by the plugin matches your new one.
|
|
1) Create a new function signature in [API.h](/src/mumble/API.h). It should return your new ``struct`` and be of the name ``getMumbleAPI_v_<MA>_<MI>_x``.
|
|
1) Amend the previous ``API_v_<MA>_x_x.cpp`` file, or create a new one in [this folder](/src/mumble/).
|
|
* For the foreseeable future, reuse the previous cpp file. Creating a new cpp file will probably only be useful on extensive API re-designs.
|
|
* If you have created a new ``API_v_<MA>_x_x.cpp``, you must add it to the [CMakeLists.txt](/src/mumble/CMakeLists.txt).
|
|
1) Implement the ``getMumbleAPI_v_<MA>_<MI>_x`` function inside the ``API_v_<MA>_x_x.cpp`` file and return a struct with all functions you want to expose in your API version.
|
|
1) When adding a new function or new function signature, copy an existing "C FUNCTION WRAPPER" inside the ``API_v_<MA>_x_x.cpp`` file. That wrapper should then call your new function.
|
|
1) Implement your new API changes in the ``API_v_<MA>_x_x.cpp`` file.
|
|
* If you change the signature of an old function, it is probably best to call the new function in the old implementation with default values.
|
|
* This way, old plugins will still be working more or less as expected.
|