So people new to the plugin stuff can quickly get to usage introduction
and code snippets. The plugins alone don't list anything like that and
it may be *very* confusing otherwise.
Similar to the change done in Corrade, see the commit for details:
878624ac36
Wow, this is probably the most backwards-compatibility code I've ever
written. Can't wait until I can drop all that.
Somehow. Heh. This causes a non-deprecated build on MSVC to break due to
a similar reason as in 54394e2c2f. And,
similarly to 3717043ae2, *again*
discovered while building bindings.
Except for file callbacks, for these I have another change planned for
zero-copy import and it would be unwise to break stuff twice, providing
two sets of backwards compatibility wrappers. The image / scene
converter plugins went through a similar change earlier already and the
shader converters were made sane since the very beginning. OTOH audio
importers and text stuff are scheduled for merging with Trade or a
larger rework anyway, so I didn't see any point in updating those.
It's mostly a trivial change, except that returned String instances are
now also checked for non-default deleters same as Arrays because yes,
wow such flexibility compared to STL strings. Same was done for
ShaderTools::AbstractConverter already anyway, so nothing unheard-of
either.
The importer plugin interface version is bumped as this likely breaks
ABI in a nasty way that would lead to crashes.
Minor but very important convenience feature, especially useful when
dealing with command-line apps. This now works:
magnum-imageconverter a.png a.jpg -c jpegQuality=0.75
The AnyImageConverter gets the jpegQuality option and then
automatically propagates it to the concrete plugin (which is either
JpegImageConverter or StbImageConverter), possibly warning in case the
target plugin doesn't recognize given option (i.e., doesn't list it in
its default configuration). Previously the user had to always specify a
concrete converter implementation using -C, which was rather annoying
and nonintuitive.
The current testing workflow had quite a few major flaws and it was no
longer possible after the move of Any* plugins to core. Among the flaws
is:
* Every plugin was basically built twice, once as the real plugin and
once as a static testing library. Most of the build shared common
object files, but nevertheless it inflated build times and made the
buildsystem extremely complex.
* Because the actual plugin binary was never actually loaded during the
test, it couldn't spot problems like:
- undefined references
- errors in metadata files
- mismatched plugin interface/version, missing entry points
- broken static plugin import files
* Tests that made use of independent plugins (such as TgaImageConverter
test using TgaImporter to verify the output) had a hardcoded
dependency on such plugins, making a minimal setup very hard.
* Dynamic loading of plugins from the Any* proxies was always directed
to the install location on the filesystem with no possibility to
load these directly from the build tree. That caused random ABI
mismatch crashes, or, on the other hand, if no plugins were
installed, particular portions of the codebase weren't tested at all.
Now the workflow is the following:
* Every plugin is built exactly once, either as dynamic or as static.
* The test always loads it via the plugin manager. If it's dynamic,
it's loaded straight from the build directory; if it's static, it
gets linked to the test executable directly.
* Plugins used indirectly are always served from the build directory
(if enabled) to ensure reproducibility and independence on what's
installed on the filesystem. Missing presence of these plugins causes
particular tests to be simply skipped.
* Plugins that have extensive tests for internal functionality that's
not exposed through the plugin interface are still built in two
parts, but the internal tests are simply consuming the OBJECT files
directly instead of linking to a static library.
Please note that this is not exactly backwards compatible, but as most
uses of the plugin library are without interacting with CMake, it
shouldn't be as painful, hopefully. In any case, recreate the build dir
and update your copy of Find*.cmake modules to avoid weird things
happening.
User-facing changes:
* Documentation of Find*.cmake modules converted to reStructuredText to
follow official CMake guidelines.
* The newfangled way to link the plugins is to use
MagnumPlugins::JpegImporter instead of
${MAGNUMPLUGINS_JPEGIMPORTER_LIBRARIES} and
${MAGNUMPLUGINS_JPEGIMPORTER_INCLUDE_DIRS}.
* The old ${MAGNUMPLUGINS_*_LIBRARIES} are deprecated and
just expand to MagnumPlugins::* target and are exposed only if
building with BUILD_DEPRECATED.
* The old ${MAGNUMPLUGINS_*_INCLUDE_DIRS} are removed, as the
MagnumPlugins::* targets cover that now as well.
Internal changes:
* Removed global state in favor of target-specific settings.
Vladimír Vondruš