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

@@ -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
 

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 <Corrade/Containers/Array.h>
+
+#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<char> 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() {
 
 {

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 <string> /** @todo drop when file callbacks are <string>-free */
 #include <unordered_map>
 #include <Corrade/Containers/Array.h>
@@ -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] */

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 <Corrade/Containers/Array.h>
 #include <Corrade/Containers/Optional.h>
 #include <Corrade/Containers/StringView.h>
@@ -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<Text::AbstractLayouter> 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() {
 
 {

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 <unordered_map>
 #include <Corrade/Containers/ArrayTuple.h>
 #include <Corrade/Containers/Optional.h>
@@ -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() {
 
 {

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

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<char> 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

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

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<class Callback, class T> void AbstractConverter::setInputFileCallback(Callback callback, T& userData) {
     /* Don't try to wrap a null function pointer. Need to cast first because

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

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<class Callback, class T> void AbstractFont::setFileCallback(Callback callback, T& userData) {
     /* Don't try to wrap a null function pointer. Need to cast first because

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