VCV Rack Plugin Toolchain - Updates


The VCV Rack Plugin Toolchain has been updated for the release of Rack 2.4.1.

Due to changes in the Rack SDK v2.4.1, a rebuild of the toolchain is required IF you are using the Docker-based toolchain image.


I would love to test this out and build plug-ins I’m working on for all platforms. Some of the instructions are unclear to me due to my own level of ignorance and experience. So please forgive me for asking what may seem to be obvious to others with more experience.

It’s unclear if the full Xcode 12.4 install is needed or if the command line tools are sufficient enough to use the plugin tool chain successfully. Both my build systems are currently running MacOS 10.15.7. Will this work on Catalina, or would I have to wait until I have a system that will run a more recent MacOS?

I figured it was worthwhile to ask here while I’m trying to make sense of the instructions I’m reading.

if you can run docker it will work and I think that version of macOS can run docker no problem.

I recently extracted the SDK. It really is a matter of download the Xcode 12.whatever DMG and run the script in the repo. You don’t even need to install it. You just need to mount the image.

Once that’s there if you have docker running just make docker build and go get a cup of coffee. Then finish that cup of coffee then pick up a book. But it wil lfinish

It’s great once you have it working.


you don’t need macos or xcode, just the mac sdk that you snarf up once. You can either run the docker image or run the tools in linux. I don’t have docker, but I could run linux on my windows computer under free vmware. worked great.

1 Like

Thank you @baconpaul and @Squinky, I’ll have to give this a try. I’m running Apple machines, so the Docker method seems to be the way to go. I found some links where I can download Xcode 12.4, and from what Paul said, I wouldn’t have to install it, and it would just need to be mounted while compiling. I’ll see how far I can get with the information outlined here, along with with instructions on GitHub. Hopefully I can get it working on my system. Thanks again guys for your help so far :slight_smile:

You don’t need to even mount it when compiling. You mount it once and then run a script from osxcross to extract the sdk file which you then keep forever. Once you’ve done that you can unmount and toss the ancient Xcode

Docker build will then consume that file to build osxcross.

Once that’s done there’s a single command to build a package for all platforms which works smoothly

1 Like

I’m having some issues trying to build the plugin-toolchain using Docker Desktop. I’m currently in the middle of my second attempt to build the toolchain, as both attempts are taking approximately 1-2 hours. I get this error message when the build fails:

#15 ERROR: executor failed running [/bin/sh -c JOBS=$JOBS make toolchain-mac]: exit code 2 ———

[11/14] RUN JOBS= make toolchain-mac: ——— executor failed running [/bin/sh -c JOBS=$JOBS make toolchain-mac]: exit code 2

I also noticed what seemed to look like some dependency’s (maybe?) show as “failed” while others showed as success, during the build process. I apologize if this is not specific enough, it was hard to tell while the build process was scrolling along in terminal.

After the first build failed I tried to see if building a plugin would work, by cding to the rack-plugin-toolchain folder, then using this command in the instructions:

make docker-plugin-build PLUGIN_DIR=[path to my plugin root folder]

Just to see what would happen, and completely expecting it not to work, and wasn’t surprised when it didn’t work.

I’ve spent the last few days watching Docker tutorials and trying to Google as much as I can, but I fear my ignorance is getting the better of me, as I don’t really know what I’m doing here. I don’t want to give up though, and would really love to get this setup and working properly.

I have the MacOSX11.1.SDK.tar.xz file in the rack-plugin-toolchain folder, and the toolchain build process has downloaded the rack-sdks for all 4 platforms.

I’ve tried “Run the Docker daemon as a non-root user (Rootless mode)” using this link here: Run the Docker daemon as a non-root user (Rootless mode) | Docker Docs but it didn’t seem to do anything. I also saw in a tutorial I watched, that I might not need to run Docker as a non-root user because I’m using Docker Desktop on a Mac. I’m not sure if that’s true or not. Either way, the toolchain build will run for about 1-2 hours, so something is working. It just fails eventually.

I appreciate that you and @Squinky may not use Macs. I could use any sort of push in the right direction here, as I have no experience at all with Docker and running images or containers.

Thank you so far for the advice you’ve shared already.

Can’t help you on the actual toolchain build but once it is up and running the mac build required you to set MAKE.

paul ~/dev/music/rack/rack-plugin-toolchain (v2) % more < 
MAKE=make make -j8 docker-plugin-build$2 PLUGIN_DIR=/Users/paul/dev/music/rack/$1

this is a little script I have that lets me do ./ surge-rack or ./ airwin2rack -win-x86 and so on.



The toolchain build requires a truckload of RAM, and reporting of memory errors is often not great, so it might not be clear that that’s the problem.

Your container probably needs 8GB at least, and/or you could try with JOBS=1 (I’m not sure what happens when you don’t give it a number of jobs - it may default to something bigger than 1).


Yes. Building the toolchain itself requires lots of RAM. I just ran into this with the Docker build on Apple Silicon, where I had seemingly random build failures. I increased the RAM in Docker Desktop and it solved the problem.


Thank you @baconpaul, @Richie, and @cschol, a lot of this seems to be helping. I increased the RAM usage in Docker Desktop to 8GB, which is the max amount of RAM I have on my MacBook Pro. Then I ‘cd’ to ‘rack-plugin-toolchain’ which was cloned to my user folder on my Mac, and ran ‘JOBS=4 make docker-build’ (my MBP is a quad core). It downloaded all the SDKs for each platform and I let it run while I was away from the computer. When I came back hours later, the toolchain build seemed to have run successfully, as there were no errors or build failures visible at the end of the build process. Docker Desktop seemed to restart and have a new image called “rack-plugin-toolchain”, which I assume is what I use to build a container from to perform the plugin build process for each platform?

While trouble shooting the previous day before this recent successful toolchain build, a Docker image called “my-rack-plugin-toolchain” was created, and while learning how to use docker, I built two containers from this older image. These containers didn’t seem to work when trying to build my plugin, as I was unsure if I had to build the toolchain in these containers or on my system. I don’t think I set things up properly on my first few attempts. So I gather I can delete/remove the “my-rack-plugin-toolchain” image and it’s associated containers, as they don’t work, and are taking up disk space I would like to regain.

Now that I seem to have a successful toolchain build, which created a Docker image called “rack-plugin-toolchain”, I need to figure out if I just run the command that @baconpaul mentioned in a Docker container built from the “rack-plugin-toolchain” image, or if I can run this command while inside the original “rack-plugin-toolchain” folder that was cloned from the GitHub repo, that is in my MacOS system user folder? (Probably not the best place for it, but it seemed to work).

What’s also unclear to me, is if I have to run “MAKE=make” first, then run “make -j4 docker-plugin-build PLUGIN_DIR=…” or is this is a single terminal command:

MAKE=make make -j4 docker-plugin-build PLUGIN_DIR=…

The instructions also state:

(-j8 [or -j4 in my case] will not work due to the different build systems used in the toolchain build process.)

But, it seems to me that this relates to the toolchain build, and not the plugin build. So, as long as I’m in the proper directory, the above command should work, if I’m assuming correctly.

On that note, where should I have terminal focused to successfully run this command, in a Docker container built from the image or inside the cloned rack-plugin-toolchain repo on my MacOS system?

In this example @baconpaul shared above:

paul ~/dev/music/rack/rack-plugin-toolchain (v2) % more <


MAKE=make make -j8 docker-plugin-build$2 PLUGIN_DIR=/Users/paul/dev/music/rack/$1

And based on the instructions on the GitHub repo, it seems to me that I should ‘cd’ to the cloned ‘rack-plugin-toolchain’ repo on my MacOS system, which has all the SDKs for all platforms, and then run this command in terminal:

MAKE=make make -j4 docker-plugin-build PLUGIN_DIR=/users/me/rackdev/[my rack plugin folder here]

Is this correct, and the command above should work? Or, the “$2” in the example above suggests that I need another argument after “docker-plugin-build”? Like the container ID/name or something like that?

I want to also take a moment here to apologize for the lengthy message and thank you all again for chiming in and offering your suggestions and help to someone who is new to all of this and experiencing the typical learning curves.

Yes, this is exactly what works for me, where /users/me/rackdev/ is the folder for the plugin. Note, however, that there is no space between the PLUGIN_DIR= and the first / of the path.

For example, to build the VCV Fundamental plugin, assuming you have cloned it into ~/vcv/Fundamental, you would use:

MAKE=make make -j4 docker-plugin-build PLUGIN_DIR=/Users/me/vcv/Fundamental

In order to build for only one architecture—i.e., the one that you are testing on—you can save perhaps three-quarters of the build time by substituting docker-plugin-build-mac-x64, docker-plugin-build-mac-arm64, docker-plugin-build-win-x64 or docker-plugin-build-lin-x64 in place of docker-plugin-build (which builds all four).

Afterward, you should then find a plugin-build directory inside your rack-plugin-toolchain directory, and inside this you will find the *.vcvplugin files that were built. You then move the relevant one of these to the plugins-… subfolder of your normal Rack user folder. Start (or restart) Rack, and voilà, your plugin should, fingers crossed, be available in your module browser.

Docker just works (as long as it’s running in the background, a mistake I’ve made on many occasions). Despite the temptation, don’t overthink it.

1 Like

Thank you @ecuk :slight_smile:

Yeah, for some reason the arrow brackets don’t seem to show up in the forum. This was what it was suppose to show:

MAKE=make make -j4 docker-plugin-build PLUGIN_DIR=/users/me/rackdev/[my rack plugin folder here]

When I’m working on developing my modules I build using the rack SDK, and so far that’s been pretty successful.

I like the idea of being able to build the binaries for all platforms using the toolchain, and this is why I want to set it up and get it working.

It sounds to me like you’ve got the toolchain working, and use Docker. So, if I may ask. Is the Docker image all that is needed, and I would be building for all 4 platforms inside the “rack-plugin-toolchain” folder on my MacOS system, much like how I built the Docker image from this directory? So I would cd to the MacOS system folder called “rack-plugin-toolchain”, and then just run this command “MAKE=make make -j4 docker-plugin-build PLUGIN_DIR= /users/me/rackdev/[my rack plugin folder here]”? I’m not sure if I need to built a Docker container from the rack-plugin-toolchain image, and then build for all 4 platforms while inside the Docker container.

Just work on your Mac, ignore the fact that Docker is even there. Think of it like this: the make command on your Mac just happens to invoke Docker (instead of, say, a compiler).

In other words, I launch the Docker Desktop app and then forget it’s there. (Hence my sometimes forgetting that it isn’t running….) No need to worry about Docker containers or anything else like that.

I believe the only reasons I have ever opened the Docker Desktop window after installing it were to increase its memory from 8GB to 16GB (because I have 32GB available and thought it best to allow Docker to use it) and in order to delete Docker images of previous versions of the racker-plugin-toolchain.

Oh, and do make sure to remove space you have in ‘PLUGIN_DIR=/Users/…’. As you have it, with the space, it assumes that PLUGIN_DIR is an empty string and that the path is an unrelated argument of some kind.

1 Like

Success! It works! Thank you @ecuk, and all who offered advice on building a working plugin toolchain.

I think the RAM issue threw me off when the build started failing, and it’s possible I was leaving that space in as well in the path argument. So thank you again for pointing that out. Although, I don’t think that mattered at the time, because the toolchain build wasn’t successful at that point. Also, thank you for mentioning that I just need to build in the local “rack-plugin-toolchain” folder on my Mac system.

For anyone else who comes here looking for advice on how to build the rack-plugin-toolchain using docker.

Once you generate the MacOS11.1.sdk.tar.xz file and place it in the “rack-plugin-toolchain” folder, just cd to that folder and run

JOBS=4 make docker-build

This will take quite some time to complete, and will produce a rack-plugin-toolchain image in Docker.

Once the toolchain is successfully built, run

MAKE=make make -j4 docker-plugin-build PLUGIN_DIR=[path to your plugin here]

in the same “rack-plugin-toolchain” folder.

This will build your plugin for all platforms in a “plugin-build” folder that gets created in the “rack-plugin-toolchain” folder when the binaries are being compiled.

Just make sure you allocate enough RAM for Docker to use while building the toolchain. I also used JOBS=4 and -j4 because my MBP has 4 logical cores.

1 Like

That’s because forum posts are Markdown, and angle brackets mean HTML elements and get eaten. You have to escape opening angle brackets with a backslash (\<) to get them to show up in plain text. When quoting out of code or makefiles and such, format your content as literal text (code) by enclosing it in single back ticks for inline code, and triple back tick fences for block code.

1 Like

For struggling with enough RAM you could also just use JOBS=1 I’d imagine. Parallel builds will take more RAM.