Better document usage of static plugins so it's clearer with CMake subproject setup

[hsdk123]

Hi, I'm currently finding trouble importing plugins:

Containers::Pointer<Trade::AbstractImporter> importer =
        manager.loadAndInstantiate("TgaImporter");

The above line always returns nullptr.
I'm currently using the bootstrap base project, and I've configured cmake s.t.

WITH_TGAIMPORTER
WITH_ANYIMAGEIMPORTER

are both true.
Are there any other settings that I need to set?

The documentation on plugin setup is very dispersed and I'm somewhat confused as to a first time setup.

References:
https://doc.magnum.graphics/magnum/plugins.html
https://doc.magnum.graphics/magnum/building-plugins.html

[mosra]

You should get an error message printed to the standard output, telling you why. To sum it up, so, there's two possible approaches:

1. Building Corrade and Magnum separately, enable all WITH_* options you need and install using the install target to some location on the filesystem. That's the alternative setup method suggested by the Getting Started Guide. That way you'll get a bin directory containing DLLs and also a magnum/ subdirectory of it containing all plugins. Then, if you build your app, you copy this directly along with all other DLLs next to the exe and the plugin manager will find see the magnum/ directory and load the plugin DLLs from there. There's also the Vcpkg package manager, which makes this process all a lot simpler and helpfully copies all needed DLLs to your deploy path as well.
2. Building Corrade and Magnum as part of your project (as you do now and as the Getting Started Guide suggests, because it's the easier setup to begin with). That way you don't install anything, so the built plugin DLLs are buried somewhere deep in the build directory and the manager has no way to see where they are. Solution is to build the plugins as static (enabling BUILD_PLUGINS_STATIC and potentially also BUILD_STATIC) and then linking those explicitly via CMake to the final executable. Complete guide in the Static plugins section of the docs.

I think point 2 would work for you. Let me know if you need anything else.

By the way, for general broad questions like this I think it's better to make use of our Gitter channel on https://gitter.im/mosra/magnum -- it's less formal and people there are happy to help. Simply log in with your GitHub account :)

[hsdk123]

Gitter
I completely agree that Gitter would be more appropriate. Thanks for the ongoing responses!

[mosra]

Let's keep this open as a reminder to improve the docs (subproject setup, CMake namespacing).

[hsdk123]

Just a bit of feedback - I think for newcomers using the system, it would be great to have a step by step process displaying how to get from the bootstrap base project, and add magnum-plugins.

The current documentation suddenly flies to a link that requests resetting the project structure so all modules are in the same directory, thus completely diverging from the bootstrap setup. I feel this disconnect might be a hurdle for more people than one might expect.

I really like magnum's general idea of breaking things up, but I'd feel users might be more comfortable in trying out a more cleaner partitioning of projects once they've gotten a simple centralised project up and running that has access to all materials.

[hsdk123]

To streamline with the steps for adding magnum and corrade, I feel it would be ideal if we could just do

add_subdirectory(magnum-plugins)

and be done with it

[mosra]

I think I have an idea how to fix this (and yes, I recognize this to be a very big pain point unless you use prepackaged versions from the very beginning). If it would detect a CMake subproject setup, it would put all shared libraries into a single well-known place, thus solving the issues of

• PATH on Windows (because unlike on Unix systems there's no RPATH and thus the main app fails to start due to missing DLLs),
• and plugin locations on all platforms

Together with the recent introduction of 0d71c1d, where plugins are searched relative to their "parent" DLL instead of "next to the executable", I think this could be doable.

[hsdk123]

Great to see updates on this! I see this also as a needed feature in many cases of trying to propose magnum usage within companies - proposals usually need to go through a screening process, and screening usually tends to clear much smoother when there doesn't need to be any global installations of any sort, and things can just be packaged into a single user defined location.

Even if it isn't company screening, I also just usually find people more open to testing things when they know I won't be 'polluting' their environment with global requirements.

Summary: really looking forward to this.

[mosra]

Since mosra/corrade@73d3f31, 3a243a0 and mosra/magnum-plugins@dff98d8, plugins are put in the build directory into a common location, which makes CMake subprojects with default config (i.e., dynamic plugins) "just work". This change also improves the experience for Windows users as all DLLs are placed next to the executables.