How build Plugins using Docker

This document contains information on how to build your audio plugins for the MOD devices, specifically for non-Linux hosts like macOS or Windows, through the use of Docker.

See BUILDING-LINUX.md for instructions on how to build when using Linux.

Step 0: Install Docker Before we start building, we need to install Docker, as the cross-compilation steps are meant to be used under a Linux host, and Docker is a nice and common way to achieve that. You can either install Docker Desktop or any alternative of your choice; the only requirement is being compatible with the Docker buildx command.

How you install Docker is outside the scope of this document; the next step assumes you have it installed and working already.

If you really do not want to install Docker, you can pick any recent Debian-based Linux distribution of your choice and install it on a Virtual Machine. Then follow the BUILDING-LINUX.md instructions inside the Virtual Machine.

Step 1: Build the Docker image To start, we build the Docker image that contains the toolchain, host tools and extra libraries. The Dockerfile can be found here.

Assuming you have Docker installed, you can build it like this:

docker buildx build \
    --build-arg debug=false \
    --build-arg target=full \
    --tag "modduo-new ou modduox-new ou moddwarf-new" \
    /path/to/Plugin-Dev-Setup/docker

The debug argument is optional, the default is false, but it can be set to true if needed. We recommend naming the image with a debug suffix (e.g. --tag "modduo-new ou modduox-new ou moddwarf-new-debug") to easily differentiate between release and debug builds.

The target argument is also optional, with these possible choices:

full (builds everything: toolchain and all libs) minimal (builds minimal libs only, includes host-cmake, fftw and liblo) kernel (builds libs needed for the Linux kernel) toolchain (builds toolchain only, no extra libs or host tools) The full build will take approximately 1 hour in total, and require around 15Gb of disk space.

You can verify that you have a valid Docker image by running docker images. Your output should contain "modduo-new ou modduox-new ou moddwarf-new", for example:

% docker images
REPOSITORY          TAG       IMAGE ID       CREATED          SIZE
moddwarf-new        latest    782ca98b7eff   41 minutes ago   14.6GB

% docker images
REPOSITORY          TAG       IMAGE ID       CREATED          SIZE
modduox-new         latest    782ca98b7eff   41 minutes ago   14.6GB

% docker images
REPOSITORY          TAG       IMAGE ID       CREATED          SIZE
modduo-new          latest    782ca98b7eff   41 minutes ago   14.6GB

Step 2: Run the docker image mounted with your local files After creating a docker image we need to create a container based on that image, so we can dynamically run things from it. Because it is a container, it has no direct access to the host filesystem, so we need to map between a folder on the host and the container.

To create a container, run the docker command like this:

docker run \
    --name "mod-container-name" \
    -ti \
    -v /path/to/your/project:/root/source \
    "moddwarf-new:latest"

The --name argument specifies a container name to use, change it to whatever makes more sense for you.

The -ti argument combines t for enabling a "TTY" and i for making it interactive. These 2 arguments together is what allows us to run commands inside the container.

The -v argument specifies a host folder to mount inside the container folder, using ":" as separator between host and container paths. This argument can be used multiple times to mount multiple folders. The container folder does not need to exist beforehand, docker creates it as needed.

Finally, the "moddwarf-new:latest" specifies the image name from which to create the container from.

The first time you run this command you will be dropped into a bash shell inside container. You can close it at anytime with Ctrl+D. Running it again is possible with docker start -i "mod-container-name" (adjusting name as needed).

Step 3: Build your own project with the custom toolchain Example using cmake

1. setup your project for building (-S specifies cmake project folder, -B specifies build output folder)

cmake -S /path/to/your/project -B build-mod

1. build your project

$(which cmake) --build build-mod NOTE: The odd $(which cmake) above is required; the build environment uses cmake as an alias with a few extra args, which would override --build.

Example using raw makefiles Simply do:

1. build your project (-C specifies the project build folder)

make -C /path/to/your/project

Step 4: Deploy Plugin We can deploy the compiled plugin to the MOD using MOD-SDK or manually using curl (advanced).

If you have mod-sdk installed, start it up using the target plugin dir as LV2_PATH, like so:

$ export LV2_PATH=~/mod-workdir/plugins/
$ modsdk

Then open a browser at localhost:9000, select a plugin from the list and use the "deploy" tab to push the selected plugin's bundle to the Duo.

For advanced users, you can push a bundle to the mod by running this: (adjust as needed)

$ cd ~/mod-workdir/plugins/
$ tar cz eg-amp.lv2 | base64 | curl -F 'package=@-' http://192.168.51.1/sdk/install

That's it! Your plugin is now inside the MOD!