manual/Migrate1.md

Migrating 0.6 plugins to Rack v1

This document is a draft. It is not recommended to migrate plugins at this time. If you begin now, you will likely need to follow this guide again when the Rack v1 API is stabilized.

The easy way: using the rack0.hpp compatibility header

Change #include "rack.hpp" to #include "rack0.hpp"

Create a plugin.json manifest file for your plugin and all modules based on the Template manifest (TODO add actual manifest template/guide).

Remove SLUG and VERSION from the Makefile and p->slug = ... and p->version = ... from your plugin's main .cpp file, since they are now defined in plugin.json.

For each module, change the Model::create call

Model *modelMyModule = Model::create<MyModule, MyModuleWidget>("Template", "MyModule", "My Module", OSCILLATOR_TAG);

to

Model *modelMyModule = Model::create<MyModule, MyModuleWidget>("MyModule");

Make the following string replacements (requires Perl).

# Rename `plugin` variable to avoid a name collision with the `plugin::` namespace
perl -pi -e "s/\bplugin\b/pluginInstance/g" src/*

# Change `X::create()` functions to `createX()`
perl -pi -e "s/Model::create/createModel/g" src/*
perl -pi -e "s/ParamWidget::create/createParam/g" src/*
perl -pi -e "s/ModuleLightWidget::create/createLight/g" src/*
perl -pi -e "s/Port::create/createPort/g" src/*
perl -pi -e "s/Port::OUTPUT/PortWidget::OUTPUT/g" src/*
perl -pi -e "s/Port::INPUT/PortWidget::INPUT/g" src/*
perl -pi -e "s/Widget::create/createWidget/g" src/*
perl -pi -e "s/MenuLabel::create/createMenuLabel/g" src/*
perl -pi -e "s/MenuItem::create/createMenuItem/g" src/*

# Change `to/fromJson()` to `dataTo/FromJson()`
perl -pi -e "s/toJson/dataToJson/g" src/*
perl -pi -e "s/fromJson/dataFromJson/g" src/*

If your plugin uses any of Rack's dsp/*.hpp headers, remove the #include statements since they are now automatically included.

For most plugins, this should do it. Compiling should generate hundreds of deprecation warnings, but it might succeed. If not, read the compile error, and don't hesitate to ask questions in the VCV community forum or GitHub issue tracker.

The right way: using the Rack v1 API

First complete the above section using the compatibility header as a first step.

Once it is able to compile, change #include "rack0.hpp" back to #include "rack.hpp"

# Use `APP` macro for accessing global state
perl -pi -e "s/engineGetSampleRate/APP->engine->getSampleRate/g" src/*
perl -pi -e "s/engineGetSampleTime/APP->engine->getSampleTime/g" src/*
perl -pi -e "s/Font::load/APP->window->loadFont/g" src/*
perl -pi -e "s/Image::load/APP->window->loadImage/g" src/*
perl -pi -e "s/SVG::load/APP->window->loadSvg/g" src/*

# Use `createInput/Output()` functions instead of `createPort()`
perl -pi -e "s/, PortWidget::INPUT//g" src/*
perl -pi -e "s/addInput\(createPort/addInput(createInput/g" src/*
perl -pi -e "s/, PortWidget::OUTPUT//g" src/*
perl -pi -e "s/addOutput\(createPort/addOutput(createOutput/g" src/*

# Add namespaces to global functions
perl -pi -e "s/randomUniform/random::uniform/g" src/*
perl -pi -e "s/randomNormal/random::normal/g" src/*

# Change `void draw(NVGcontext *vg)` to `void draw(const DrawContext &ctx)`
perl -pi -e "s/draw\(NVGcontext \*vg\)/draw\(const DrawContext &ctx\)/g" src/*
perl -pi -e "s/\(vg/(ctx.vg/g" src/*
perl -pi -e "s/draw\(vg\)/draw\(ctx\)/g" src/*

# Add the `dsp::` namespace to dsp classes
# TODO