How to add more modules?

[TheGuyWhoo]

Hi!

I would really like to add the MindMeld modules. How can I go about doing that?

[falkTX]

You can always follow the existing examples already there.
They are all done similarly.

If it was not obvious by now, only open-source modules can be added, as we need their source.
Also they must be for v2 and be cross-platform, cross-architecture friendly.
The latter meaning at least Linux, macOS and Windows as supported systems, plus both x86/64 and ARM builds successfully.
If one plugin fails to build for ARM but works on x86, we need to fix that first.
It is essential that all added modules work on all the builds produced by CI (GitHub actions right now).

But let's go through the steps, knowledge of git is a requirement.

1. Add the new plugin/module in git, as a git submodule, for example:

git submodule add https://github.com/cfoulc/cf.git plugins/cf
# maybe needed to adjust the commit of new added repo, so it points to v2
pushd plugins/cf
git checkout v2
# make sure module's git submodules, if any, are available to this local build
git submodule update --init --recursive
# go back to the old path
popd

2. Add the module files to build in plugins/Makefile
   This should be based on the upstream repo Makefile, but ignoring the entry point C++ file (typically "src/plugin.cpp")
   For "cf" module we simply add this, following the already existing definitions on the file:

PLUGIN_FILES += $(filter-out cf/src/plugin.cpp,$(wildcard cf/src/*.cpp))

3. Add the build rule for the new files in plugins/Makefile
   Near the end of the file there are build rules that define how each one is built. If the upstream Makefile uses custom build definitions (those -DFOO=BAR things) we need to manually import them in here.
   Again for "cf" module, we add this, just following the others on the same file:

$(BUILD_DIR)/cf/src/%.cpp.o: cf/src/%.cpp
	-@mkdir -p "$(shell dirname $(BUILD_DIR)/$<)"
	@echo "Compiling $<"
	$(SILENT)$(CXX) $< $(BUILD_CXX_FLAGS) -c -o $@ \
		$(foreach m,$(CF_CUSTOM),$(call custom_module_names,$(m),cf)) \
		-DpluginInstance=pluginInstance__cf \
		-DFOO=BAR

(adjust "cf" name for the relevant one)

4. Insert the module entry point in plugins/plugins.cpp, again following the same existing modules already in the file.
   Make sure to keep the added stuff in alphabetically order, with "Cardinal" as exception.
   This is devided into subsections.

4a. Include the module entry point header, something like:

// cf
#include "cf/src/plugin.hpp"

4b. Create the plugin instance, something like:

Plugin* pluginInstance__cf;

4c. Create a static function where the modules are loaded, something like:

static void initStatic__cf()
{
    Plugin* const p = new Plugin;
    pluginInstance__cf = p;

    const StaticPluginLoader spl(p, "cf");
    if (spl.ok())
    {
        p->addModel(modelMETRO);
        p->addModel(modelEACH);
        // etc, this should have exactly the same content as the entry point C++ file we are ignoring in the `plugins/Makefile`
    }
}

4d. Call into the function defined in the previous step during init, like so:

void initStaticPlugins()
{
    initStatic__Cardinal();
#ifndef NOPLUGINS
    initStatic__AmalgamatedHarmonics();
    initStatic__AnimatedCircuits();
    initStatic__AS();
    initStatic__AudibleInstruments();
    initStatic__Befaco();
    initStatic__Bidoo();
    initStatic__BogaudioModules();
    // the next line is new
    initStatic__cf();
    initStatic__ESeries();
    initStatic__Fundamental();
    initStatic__GrandeModular();
    initStatic__ImpromptuModular();
    initStatic__JW();
    initStatic__rackwindows();
    /* does not build against v2
    initStatic__ValleyAudio();
    */
    initStatic__ZetaCarinaeModules();
#endif // NOPLUGINS
}

And that is the jist of it.

There can be additional setup if:

• plugin requires extra libraries, these would go in dep/Makefile instead, needs to be done on a case-by-case basis
• plugin has too much noise on its entry point include, see how it was done for ImpromptuModular
• modules in the new collection have name conflicts with existing ones, see how it is solved in AS, Bogaudio and JW

[falkTX]

if you submit a PR I can see about the last details to get the linking step working.

[TheGuyWhoo]

Okay thank you, I submitted a pull request. Apologies once again if I made a mess!

[TheGuyWhoo]

It works! Thanks a ton, I really appreciate.

[flarn2006]

Why can't it load binary modules at runtime? Isn't there an official paid fork of VCV that runs as a VST plugin? If it can do that, why can't Cardinal?

[dromer]

Because cardinal builds everything into a single optimized binary that doesn't load external resources. That's the goal of the project and that's how it works.

[Diagram23]

Hello, do you know if someone has managed to add more modules?

[falkTX]

I did a couple of times.
For example for the ESeries 15b137e

Adding modules here requires messing with the build system, so it is not going to be an easy task by any means.
If you are unable to do it yourself but really want to see a specific (open-source!!) module integrated, open a ticket or start a discussion.

[Diagram23]

Okay, thank you so much

[strongheart1]

Thanks for this nice instruction!
I think the step to add the line
Plugin* pluginInstance__cf;
is missing, between 4a and 4b.

[dromer]

Thnx, added!

[testerkid303022]

I know nobody posted in a long time, but I need help with importing modules, but don't want the hard code to deal with.

[mrneutronismissing]

Hi! maybe these modules could be added to Cardinal, they´re open source...
https://github.com/stuart78/SignalFunctionSet-VCV-Rack

[dromer]

The plugin.json says GPL-3.0-or-later so that possibly could be (other included code and assets need to be checked as well of course).

You can add them to this wiki page together with a good reason why this set of modules brings something unique: https://github.com/DISTRHO/Cardinal/wiki/Possible-modules-to-include