From 12fc59bf193d09c2d6b3976c6abfef8aec5d4eae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 9 Apr 2023 14:34:16 +0200 Subject: [PATCH] Add macros with plugin interface strings for easier updates. This means I (and people making their own plugins) don't need to go and update each and every plugin once the version in the interface string gets bumped after a (silent) ABI break. Such as when new virtual functions get added, as those often lead to strange crashes if the plugins don't get rebuilt after. The plugins will now use this macro, which means they'll automatically embed an interface string that was present in the base class header at build time. However, when the base class updates, the previous string is still embedded in the plugin binary, which will then fail to load -- this being automatic doesn't mean the original purpose is lost. Subsequently rebuilding the plugins from source will make them pick up the updated interface string again. --- doc/changelog.dox | 9 +++++ doc/snippets/MagnumAudio.cpp | 27 +++++++++++++ doc/snippets/MagnumShaderTools.cpp | 21 ++++++++++ doc/snippets/MagnumText.cpp | 35 +++++++++++++++++ doc/snippets/MagnumTrade.cpp | 41 ++++++++++++++++++++ src/Magnum/Audio/AbstractImporter.cpp | 6 +-- src/Magnum/Audio/AbstractImporter.h | 25 +++++++++++- src/Magnum/ShaderTools/AbstractConverter.cpp | 6 +-- src/Magnum/ShaderTools/AbstractConverter.h | 25 +++++++++++- src/Magnum/Text/AbstractFont.cpp | 6 +-- src/Magnum/Text/AbstractFont.h | 25 +++++++++++- src/Magnum/Text/AbstractFontConverter.cpp | 6 +-- src/Magnum/Text/AbstractFontConverter.h | 25 +++++++++++- src/Magnum/Trade/AbstractImageConverter.cpp | 6 +-- src/Magnum/Trade/AbstractImageConverter.h | 25 +++++++++++- src/Magnum/Trade/AbstractImporter.cpp | 6 +-- src/Magnum/Trade/AbstractImporter.h | 25 +++++++++++- src/Magnum/Trade/AbstractSceneConverter.cpp | 6 +-- src/Magnum/Trade/AbstractSceneConverter.h | 25 +++++++++++- 19 files changed, 308 insertions(+), 42 deletions(-) diff --git a/doc/changelog.dox b/doc/changelog.dox index 4c081cd317..81508c7352 100644 --- a/doc/changelog.dox +++ b/doc/changelog.dox @@ -431,6 +431,15 @@ See also: @relativeref{Timeline,previousFrameTime()} and @relativeref{Timeline,previousFrameDuration()} (see [mosra/magnum#604](https://github.com/mosra/magnum/pull/604)) +- Added @ref MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE, + @ref MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE, + @ref MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE, + @ref MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE, + @ref MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE, + @ref MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE and + @ref MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE defines with + plugin interface strings to avoid having to update them by hand in every + plugin every time the interface version is bumped after an ABI break @subsubsection changelog-latest-changes-animation Animation library diff --git a/doc/snippets/MagnumAudio.cpp b/doc/snippets/MagnumAudio.cpp index 097fea0c81..cacfea598e 100644 --- a/doc/snippets/MagnumAudio.cpp +++ b/doc/snippets/MagnumAudio.cpp @@ -23,11 +23,38 @@ DEALINGS IN THE SOFTWARE. */ +/* In order to have the CORRADE_PLUGIN_REGISTER() macro not a no-op. Doesn't + affect anything else. */ +#define CORRADE_STATIC_PLUGIN + +#include + +#include "Magnum/Audio/AbstractImporter.h" #include "Magnum/Audio/Context.h" #include "Magnum/Audio/Extensions.h" using namespace Magnum; +namespace MyNamespace { + +struct MyAudioImporter: Audio::AbstractImporter { + explicit MyAudioImporter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin): Audio::AbstractImporter{manager, plugin} {} + + Audio::ImporterFeatures doFeatures() const override { return {}; } + bool doIsOpened() const override { return false; } + void doClose() override {} + Audio::BufferFormat doFormat() const override { return {}; } + UnsignedInt doFrequency() const override { return {}; } + Containers::Array doData() override { return {}; } +}; + +} + +/* [MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE] */ +CORRADE_PLUGIN_REGISTER(MyAudioImporter, MyNamespace::MyAudioImporter, + MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE) +/* [MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE] */ + int main() { { diff --git a/doc/snippets/MagnumShaderTools.cpp b/doc/snippets/MagnumShaderTools.cpp index da4bdca182..843993b03d 100644 --- a/doc/snippets/MagnumShaderTools.cpp +++ b/doc/snippets/MagnumShaderTools.cpp @@ -23,6 +23,10 @@ DEALINGS IN THE SOFTWARE. */ +/* In order to have the CORRADE_PLUGIN_REGISTER() macro not a no-op. Doesn't + affect anything else. */ +#define CORRADE_STATIC_PLUGIN + #include /** @todo drop when file callbacks are -free */ #include #include @@ -41,6 +45,23 @@ using namespace Magnum; +namespace MyNamespace { + +struct MyShaderConverter: ShaderTools::AbstractConverter { + explicit MyShaderConverter(PluginManager::AbstractManager& manager, Containers::StringView plugin): ShaderTools::AbstractConverter{manager, plugin} {} + + ShaderTools::ConverterFeatures doFeatures() const override { return {}; } + void doSetInputFormat(ShaderTools::Format, Containers::StringView) override {} + void doSetOutputFormat(ShaderTools::Format, Containers::StringView) override {} +}; + +} + +/* [MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE] */ +CORRADE_PLUGIN_REGISTER(MyShaderConverter, MyNamespace::MyShaderConverter, + MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE) +/* [MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE] */ + int main() { { /* [AbstractConverter-usage-validation] */ diff --git a/doc/snippets/MagnumText.cpp b/doc/snippets/MagnumText.cpp index 5901d9a4ce..c0059a1248 100644 --- a/doc/snippets/MagnumText.cpp +++ b/doc/snippets/MagnumText.cpp @@ -23,6 +23,10 @@ DEALINGS IN THE SOFTWARE. */ +/* In order to have the CORRADE_PLUGIN_REGISTER() macro not a no-op. Doesn't + affect anything else. */ +#define CORRADE_STATIC_PLUGIN + #include #include #include @@ -36,6 +40,7 @@ #include "Magnum/Math/Matrix3.h" #include "Magnum/Shaders/VectorGL.h" #include "Magnum/Text/AbstractFont.h" +#include "Magnum/Text/AbstractFontConverter.h" #include "Magnum/Text/DistanceFieldGlyphCache.h" #include "Magnum/Text/Renderer.h" @@ -44,6 +49,36 @@ using namespace Magnum; using namespace Magnum::Math::Literals; +namespace MyNamespace { + +struct MyFont: Text::AbstractFont { + explicit MyFont(PluginManager::AbstractManager& manager, Containers::StringView plugin): Text::AbstractFont{manager, plugin} {} + + Text::FontFeatures doFeatures() const override { return {}; } + bool doIsOpened() const override { return false; } + void doClose() override {} + UnsignedInt doGlyphId(char32_t) override { return {}; } + Vector2 doGlyphAdvance(UnsignedInt) override { return {}; } + Containers::Pointer doLayout(const Text::AbstractGlyphCache&, Float, const std::string&) override { return {}; } +}; +struct MyFontConverter: Text::AbstractFontConverter { + explicit MyFontConverter(PluginManager::AbstractManager& manager, Containers::StringView plugin): Text::AbstractFontConverter{manager, plugin} {} + + Text::FontConverterFeatures doFeatures() const override { return {}; } +}; + +} + +/* [MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE] */ +CORRADE_PLUGIN_REGISTER(MyFont, MyNamespace::MyFont, + MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE) +/* [MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE] */ + +/* [MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE] */ +CORRADE_PLUGIN_REGISTER(MyFontConverter, MyNamespace::MyFontConverter, + MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE) +/* [MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE] */ + int main() { { diff --git a/doc/snippets/MagnumTrade.cpp b/doc/snippets/MagnumTrade.cpp index dc05e95091..2c0ec70a7c 100644 --- a/doc/snippets/MagnumTrade.cpp +++ b/doc/snippets/MagnumTrade.cpp @@ -23,6 +23,10 @@ DEALINGS IN THE SOFTWARE. */ +/* In order to have the CORRADE_PLUGIN_REGISTER() macro not a no-op. Doesn't + affect anything else. */ +#define CORRADE_STATIC_PLUGIN + #include #include #include @@ -89,6 +93,43 @@ using namespace Magnum; using namespace Magnum::Math::Literals; +namespace MyNamespace { + +struct MyImporter: Trade::AbstractImporter { + explicit MyImporter(PluginManager::AbstractManager& manager, Containers::StringView plugin): Trade::AbstractImporter{manager, plugin} {} + + Trade::ImporterFeatures doFeatures() const override { return {}; } + bool doIsOpened() const override { return false; } + void doClose() override {} +}; +struct MyImageConverter: Trade::AbstractImageConverter { + explicit MyImageConverter(PluginManager::AbstractManager& manager, Containers::StringView plugin): Trade::AbstractImageConverter{manager, plugin} {} + + Trade::ImageConverterFeatures doFeatures() const override { return {}; } +}; +struct MySceneConverter: Trade::AbstractSceneConverter { + explicit MySceneConverter(PluginManager::AbstractManager& manager, Containers::StringView plugin): Trade::AbstractSceneConverter{manager, plugin} {} + + Trade::SceneConverterFeatures doFeatures() const override { return {}; } +}; + +} + +/* [MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE] */ +CORRADE_PLUGIN_REGISTER(MyImporter, MyNamespace::MyImporter, + MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE) +/* [MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE] */ + +/* [MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE] */ +CORRADE_PLUGIN_REGISTER(MyImageConverter, MyNamespace::MyImageConverter, + MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE) +/* [MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE] */ + +/* [MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE] */ +CORRADE_PLUGIN_REGISTER(MySceneConverter, MyNamespace::MySceneConverter, + MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE) +/* [MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE] */ + int main() { { diff --git a/src/Magnum/Audio/AbstractImporter.cpp b/src/Magnum/Audio/AbstractImporter.cpp index ab7ffd87a0..5d2f2091c4 100644 --- a/src/Magnum/Audio/AbstractImporter.cpp +++ b/src/Magnum/Audio/AbstractImporter.cpp @@ -51,11 +51,7 @@ namespace Magnum { namespace Audio { using namespace Containers::Literals; Containers::StringView AbstractImporter::pluginInterface() { - return -/* [interface] */ -"cz.mosra.magnum.Audio.AbstractImporter/0.1"_s -/* [interface] */ - ; + return MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE ""_s; } #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT diff --git a/src/Magnum/Audio/AbstractImporter.h b/src/Magnum/Audio/AbstractImporter.h index 919e7f1d31..2c4aba5c79 100644 --- a/src/Magnum/Audio/AbstractImporter.h +++ b/src/Magnum/Audio/AbstractImporter.h @@ -124,7 +124,9 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractManagi /** * @brief Plugin interface * - * @snippet Magnum/Audio/AbstractImporter.cpp interface + * @snippet Magnum/Audio/AbstractImporter.h interface + * + * @see @ref MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE */ static Containers::StringView pluginInterface(); @@ -236,6 +238,27 @@ class MAGNUM_AUDIO_EXPORT AbstractImporter: public PluginManager::AbstractManagi virtual Containers::Array doData() = 0; }; +/** +@brief Audio importer plugin interface +@m_since_latest + +Same string as returned by +@relativeref{Magnum::Audio,AbstractImporter::pluginInterface()}, meant to be +used inside @ref CORRADE_PLUGIN_REGISTER() to avoid having to update the +interface string by hand every time the version gets bumped: + +@snippet MagnumAudio.cpp MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE + +The interface string version gets increased on every ABI break to prevent +silent crashes and memory corruption. Plugins built against the previous +version will then fail to load, a subsequent rebuild will make them pick up the +updated interface string. +*/ +/* Silly indentation to make the string appear in pluginInterface() docs */ +#define MAGNUM_AUDIO_ABSTRACTIMPORTER_PLUGIN_INTERFACE /* [interface] */ \ +"cz.mosra.magnum.Audio.AbstractImporter/0.1" +/* [interface] */ + }} #endif diff --git a/src/Magnum/ShaderTools/AbstractConverter.cpp b/src/Magnum/ShaderTools/AbstractConverter.cpp index dec8ac9fdd..dc78f59721 100644 --- a/src/Magnum/ShaderTools/AbstractConverter.cpp +++ b/src/Magnum/ShaderTools/AbstractConverter.cpp @@ -52,11 +52,7 @@ namespace Magnum { namespace ShaderTools { using namespace Containers::Literals; Containers::StringView AbstractConverter::pluginInterface() { - return -/* [interface] */ -"cz.mosra.magnum.ShaderTools.AbstractConverter/0.1.1"_s -/* [interface] */ - ; + return MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE ""_s; } #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT diff --git a/src/Magnum/ShaderTools/AbstractConverter.h b/src/Magnum/ShaderTools/AbstractConverter.h index d1335591e2..0b9c24358b 100644 --- a/src/Magnum/ShaderTools/AbstractConverter.h +++ b/src/Magnum/ShaderTools/AbstractConverter.h @@ -490,7 +490,9 @@ class MAGNUM_SHADERTOOLS_EXPORT AbstractConverter: public PluginManager::Abstrac /** * @brief Plugin interface * - * @snippet Magnum/ShaderTools/AbstractConverter.cpp interface + * @snippet Magnum/ShaderTools/AbstractConverter.h interface + * + * @see @ref MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE */ static Containers::StringView pluginInterface(); @@ -1186,6 +1188,27 @@ class MAGNUM_SHADERTOOLS_EXPORT AbstractConverter: public PluginManager::Abstrac } _inputFileCallbackTemplate{nullptr, nullptr}; }; +/** +@brief Shader converter plugin interface +@m_since_latest + +Same string as returned by +@relativeref{Magnum::ShaderTools,AbstractConverter::pluginInterface()}, meant +to be used inside @ref CORRADE_PLUGIN_REGISTER() to avoid having to update the +interface string by hand every time the version gets bumped: + +@snippet MagnumShaderTools.cpp MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE + +The interface string version gets increased on every ABI break to prevent +silent crashes and memory corruption. Plugins built against the previous +version will then fail to load, a subsequent rebuild will make them pick up the +updated interface string. +*/ +/* Silly indentation to make the string appear in pluginInterface() docs */ +#define MAGNUM_SHADERTOOLS_ABSTRACTCONVERTER_PLUGIN_INTERFACE /* [interface] */ \ +"cz.mosra.magnum.ShaderTools.AbstractConverter/0.1.1" +/* [interface] */ + #ifndef DOXYGEN_GENERATING_OUTPUT template void AbstractConverter::setInputFileCallback(Callback callback, T& userData) { /* Don't try to wrap a null function pointer. Need to cast first because diff --git a/src/Magnum/Text/AbstractFont.cpp b/src/Magnum/Text/AbstractFont.cpp index a926aed6e7..00e21e5fa1 100644 --- a/src/Magnum/Text/AbstractFont.cpp +++ b/src/Magnum/Text/AbstractFont.cpp @@ -54,11 +54,7 @@ namespace Magnum { namespace Text { using namespace Containers::Literals; Containers::StringView AbstractFont::pluginInterface() { - return -/* [interface] */ -"cz.mosra.magnum.Text.AbstractFont/0.3"_s -/* [interface] */ - ; + return MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE ""_s; } #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT diff --git a/src/Magnum/Text/AbstractFont.h b/src/Magnum/Text/AbstractFont.h index 90dadf437b..1a7d4080a5 100644 --- a/src/Magnum/Text/AbstractFont.h +++ b/src/Magnum/Text/AbstractFont.h @@ -185,7 +185,9 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin { /** * @brief Plugin interface * - * @snippet Magnum/Text/AbstractFont.cpp interface + * @snippet Magnum/Text/AbstractFont.h interface + * + * @see @ref MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE */ static Containers::StringView pluginInterface(); @@ -634,6 +636,27 @@ class MAGNUM_TEXT_EXPORT AbstractLayouter { UnsignedInt _glyphCount; }; +/** +@brief Font plugin interface +@m_since_latest + +Same string as returned by +@relativeref{Magnum::Text,AbstractFont::pluginInterface()}, meant to be used +inside @ref CORRADE_PLUGIN_REGISTER() to avoid having to update the interface +string by hand every time the version gets bumped: + +@snippet MagnumText.cpp MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE + +The interface string version gets increased on every ABI break to prevent +silent crashes and memory corruption. Plugins built against the previous +version will then fail to load, a subsequent rebuild will make them pick up the +updated interface string. +*/ +/* Silly indentation to make the string appear in pluginInterface() docs */ +#define MAGNUM_TEXT_ABSTRACTFONT_PLUGIN_INTERFACE /* [interface] */ \ +"cz.mosra.magnum.Text.AbstractFont/0.3" +/* [interface] */ + #ifndef DOXYGEN_GENERATING_OUTPUT template void AbstractFont::setFileCallback(Callback callback, T& userData) { /* Don't try to wrap a null function pointer. Need to cast first because diff --git a/src/Magnum/Text/AbstractFontConverter.cpp b/src/Magnum/Text/AbstractFontConverter.cpp index 89a8f30cee..207f35c624 100644 --- a/src/Magnum/Text/AbstractFontConverter.cpp +++ b/src/Magnum/Text/AbstractFontConverter.cpp @@ -70,11 +70,7 @@ std::u32string uniqueUnicode(const std::string& characters) } Containers::StringView AbstractFontConverter::pluginInterface() { - return -/* [interface] */ -"cz.mosra.magnum.Text.AbstractFontConverter/0.2"_s -/* [interface] */ - ; + return MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE ""_s; } #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT diff --git a/src/Magnum/Text/AbstractFontConverter.h b/src/Magnum/Text/AbstractFontConverter.h index 50d5f81906..3f34173729 100644 --- a/src/Magnum/Text/AbstractFontConverter.h +++ b/src/Magnum/Text/AbstractFontConverter.h @@ -176,7 +176,9 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl /** * @brief Plugin interface * - * @snippet Magnum/Text/AbstractFontConverter.cpp interface + * @snippet Magnum/Text/AbstractFontConverter.h interface + * + * @see @ref MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE */ static Containers::StringView pluginInterface(); @@ -418,6 +420,27 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl virtual Containers::Pointer doImportGlyphCacheFromFile(const std::string& filename) const; }; +/** +@brief Font converter plugin interface +@m_since_latest + +Same string as returned by +@relativeref{Magnum::Text,AbstractFontConverter::pluginInterface()}, meant to +be used inside @ref CORRADE_PLUGIN_REGISTER() to avoid having to update the +interface string by hand every time the version gets bumped: + +@snippet MagnumText.cpp MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE + +The interface string version gets increased on every ABI break to prevent +silent crashes and memory corruption. Plugins built against the previous +version will then fail to load, a subsequent rebuild will make them pick up the +updated interface string. +*/ +/* Silly indentation to make the string appear in pluginInterface() docs */ +#define MAGNUM_TEXT_ABSTRACTFONTCONVERTER_PLUGIN_INTERFACE /* [interface] */ \ +"cz.mosra.magnum.Text.AbstractFontConverter/0.2" +/* [interface] */ + }} #endif diff --git a/src/Magnum/Trade/AbstractImageConverter.cpp b/src/Magnum/Trade/AbstractImageConverter.cpp index 2bad84d742..af3b83aa9b 100644 --- a/src/Magnum/Trade/AbstractImageConverter.cpp +++ b/src/Magnum/Trade/AbstractImageConverter.cpp @@ -54,11 +54,7 @@ namespace Magnum { namespace Trade { using namespace Containers::Literals; Containers::StringView AbstractImageConverter::pluginInterface() { - return -/* [interface] */ -"cz.mosra.magnum.Trade.AbstractImageConverter/0.3.3"_s -/* [interface] */ - ; + return MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE ""_s; } #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT diff --git a/src/Magnum/Trade/AbstractImageConverter.h b/src/Magnum/Trade/AbstractImageConverter.h index fc819399a4..3fffafad42 100644 --- a/src/Magnum/Trade/AbstractImageConverter.h +++ b/src/Magnum/Trade/AbstractImageConverter.h @@ -624,7 +624,9 @@ class MAGNUM_TRADE_EXPORT AbstractImageConverter: public PluginManager::Abstract /** * @brief Plugin interface * - * @snippet Magnum/Trade/AbstractImageConverter.cpp interface + * @snippet Magnum/Trade/AbstractImageConverter.h interface + * + * @see @ref MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE */ static Containers::StringView pluginInterface(); @@ -1928,6 +1930,27 @@ class MAGNUM_TRADE_EXPORT AbstractImageConverter: public PluginManager::Abstract ImageConverterFlags _flags; }; +/** +@brief Image converter plugin interface +@m_since_latest + +Same string as returned by +@relativeref{Magnum::Trade,AbstractImageConverter::pluginInterface()}, meant to +be used inside @ref CORRADE_PLUGIN_REGISTER() to avoid having to update the +interface string by hand every time the version gets bumped: + +@snippet MagnumTrade.cpp MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE + +The interface string version gets increased on every ABI break to prevent +silent crashes and memory corruption. Plugins built against the previous +version will then fail to load, a subsequent rebuild will make them pick up the +updated interface string. +*/ +/* Silly indentation to make the string appear in pluginInterface() docs */ +#define MAGNUM_TRADE_ABSTRACTIMAGECONVERTER_PLUGIN_INTERFACE /* [interface] */ \ +"cz.mosra.magnum.Trade.AbstractImageConverter/0.3.3" +/* [interface] */ + }} #endif diff --git a/src/Magnum/Trade/AbstractImporter.cpp b/src/Magnum/Trade/AbstractImporter.cpp index 4b35804206..3369335151 100644 --- a/src/Magnum/Trade/AbstractImporter.cpp +++ b/src/Magnum/Trade/AbstractImporter.cpp @@ -81,11 +81,7 @@ namespace Magnum { namespace Trade { using namespace Containers::Literals; Containers::StringView AbstractImporter::pluginInterface() { - return -/* [interface] */ -"cz.mosra.magnum.Trade.AbstractImporter/0.5.1"_s -/* [interface] */ - ; + return MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE ""_s; } #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT diff --git a/src/Magnum/Trade/AbstractImporter.h b/src/Magnum/Trade/AbstractImporter.h index 129b6b7a97..99fe9d638a 100644 --- a/src/Magnum/Trade/AbstractImporter.h +++ b/src/Magnum/Trade/AbstractImporter.h @@ -453,7 +453,9 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi /** * @brief Plugin interface * - * @snippet Magnum/Trade/AbstractImporter.cpp interface + * @snippet Magnum/Trade/AbstractImporter.h interface + * + * @see @ref MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE */ static Containers::StringView pluginInterface(); @@ -2605,6 +2607,27 @@ class MAGNUM_TRADE_EXPORT AbstractImporter: public PluginManager::AbstractManagi #endif }; +/** +@brief Importer plugin interface +@m_since_latest + +Same string as returned by +@relativeref{Magnum::Trade,AbstractImporter::pluginInterface()}, meant to be +used inside @ref CORRADE_PLUGIN_REGISTER() to avoid having to update the +interface string by hand every time the version gets bumped: + +@snippet MagnumTrade.cpp MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE + +The interface string version gets increased on every ABI break to prevent +silent crashes and memory corruption. Plugins built against the previous +version will then fail to load, a subsequent rebuild will make them pick up the +updated interface string. +*/ +/* Silly indentation to make the string appear in pluginInterface() docs */ +#define MAGNUM_TRADE_ABSTRACTIMPORTER_PLUGIN_INTERFACE /* [interface] */ \ +"cz.mosra.magnum.Trade.AbstractImporter/0.5.1" +/* [interface] */ + #ifndef DOXYGEN_GENERATING_OUTPUT template void AbstractImporter::setFileCallback(Callback callback, T& userData) { /* Don't try to wrap a null function pointer. Need to cast first because diff --git a/src/Magnum/Trade/AbstractSceneConverter.cpp b/src/Magnum/Trade/AbstractSceneConverter.cpp index 4aa72f880e..f331fbb431 100644 --- a/src/Magnum/Trade/AbstractSceneConverter.cpp +++ b/src/Magnum/Trade/AbstractSceneConverter.cpp @@ -207,11 +207,7 @@ struct AbstractSceneConverter::State { }; Containers::StringView AbstractSceneConverter::pluginInterface() { - return -/* [interface] */ -"cz.mosra.magnum.Trade.AbstractSceneConverter/0.2.1"_s -/* [interface] */ - ; + return MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE ""_s; } #ifndef CORRADE_PLUGINMANAGER_NO_DYNAMIC_PLUGIN_SUPPORT diff --git a/src/Magnum/Trade/AbstractSceneConverter.h b/src/Magnum/Trade/AbstractSceneConverter.h index d7e2bb61c1..a0db79a6e3 100644 --- a/src/Magnum/Trade/AbstractSceneConverter.h +++ b/src/Magnum/Trade/AbstractSceneConverter.h @@ -805,7 +805,9 @@ class MAGNUM_TRADE_EXPORT AbstractSceneConverter: public PluginManager::Abstract /** * @brief Plugin interface * - * @snippet Magnum/Trade/AbstractSceneConverter.cpp interface + * @snippet Magnum/Trade/AbstractSceneConverter.h interface + * + * @see @ref MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE */ static Containers::StringView pluginInterface(); @@ -2410,6 +2412,27 @@ class MAGNUM_TRADE_EXPORT AbstractSceneConverter: public PluginManager::Abstract Containers::Pointer _state; }; +/** +@brief Scene converter plugin interface +@m_since_latest + +Same string as returned by +@relativeref{Magnum::Trade,AbstractSceneConverter::pluginInterface()}, meant to +be used inside @ref CORRADE_PLUGIN_REGISTER() to avoid having to update the +interface string by hand every time the version gets bumped: + +@snippet MagnumTrade.cpp MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE + +The interface string version gets increased on every ABI break to prevent +silent crashes and memory corruption. Plugins built against the previous +version will then fail to load, a subsequent rebuild will make them pick up the +updated interface string. +*/ +/* Silly indentation to make the string appear in pluginInterface() docs */ +#define MAGNUM_TRADE_ABSTRACTSCENECONVERTER_PLUGIN_INTERFACE /* [interface] */ \ +"cz.mosra.magnum.Trade.AbstractSceneConverter/0.2.1" +/* [interface] */ + }} #endif