diff options
-rw-r--r-- | docs/dev/IncrementingTheMumbleAPI.md | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/docs/dev/IncrementingTheMumbleAPI.md b/docs/dev/IncrementingTheMumbleAPI.md new file mode 100644 index 000000000..36327e2d6 --- /dev/null +++ b/docs/dev/IncrementingTheMumbleAPI.md @@ -0,0 +1,34 @@ +# 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. |