Skip to content

Getting Started

Jump to bottom
p0nce edited this page Aug 18, 2021 · 55 revisions

In this tutorial, we'll see:

  • how to install a D environment,
  • how to build a D program,
  • how to build the dplug-build tool and its purpose,
  • how to build the Dplug examples. We'll build a VST3, Audio Unit and/or LV2 plug-in.

The basics

Step 1: Install a D language environment

Dplug logo

Install a D language compiler. A good starting point is the VisualD installer that bundles everything needed for D.

Alternatively:

At the end of this process, you should have the dub tool and a D compiler (LDC and/or DMD).

$ dub --version    # the DUB D language package manager
$ dmd --version    # the DMD compiler
$ ldc2 --version   # the LDC compiler

LDC is recommended compiler for all final builds. DMD can eventually be used in development on Windows to get faster build times.

A large majority of D programs can be built simply using:

$ dub

That's it! Welcome to D.

Specific instructions for macOS Big Sur and M1
If you are running on Apple Silicon, be sure to use the x86_64 LDC version.
That build is a cross-compiler, able to target both x86_64 and arm64, with flags -a x86_64 and -a arm64-apple-macos respectively.

Step 2: Clone the Dplug repository

First, make a local copy of the Dplug repository:

$ git clone https://github.com/AuburnSounds/Dplug.git Dplug
$ cd Dplug

Step 3: Build the dplug-build tool

Build the dplug-build tool, which is necessary to bundle plug-ins into the correct structure.

$ cd Dplug/tools/dplug-build

From there you can simply build it using:

$ dub

On Linux it is recommended to build dplug-build with the LDC compiler.

$ dub --compiler ldc2

Once dplug-build is built, you can examinate the available possibilities with:

$ dplug-build --help

Put it in your PATH.

It is recommended to put dplug-build in your PATH.

  • On Windows, copy dplug-build.exe to a directory that is in your PATH environment variable.
  • On macOS, you can use the following command: 
    sudo ln -s /my/path/to/Dplug/tools/dplug-build/dplug-build /usr/local/bin/dplug-build

Why another build tool?

  • dplug-build will give to your plug-ins the required structure, necessary for most combinations of plugin format and OS.
  • dplug-build can build plug-ins in different DUB configurations and bitness in the command-line run, and bundle them together in an installer.
  • dplug-build manages code signing and notarization, which is now mandatory for software distribution.
  • dplug-build will fake the VST2_SDK environment variable if you don't have a VST2 SDK, so that you can build other formats without compilation errors.

Specific instructions for macOS Big Sur and M1
dplug-build must be built as a x86_64 executable (dub -a x86_64)

Step 4: Examine and build an example plug-in

Go to the ClipIt or the Distort example directory from the fictional company Witty Audio.

# a clipper distortion using the `dplug:flat-widgets` set of widgets
$ cd Dplug/examples/clipit

# a tanh distortion using the `dplug:pbr-widgets` set of widgets
$ cd Dplug/examples/distort

Inside the folder, you'll find several directories and files. Below is a breakdown of important items and what they are used for.

Structure:

  • main.d (audio processing, parameters, I/O)
  • gui.d (UI code)
  • dub.json (configuration file for dub, also read by dplug-build)
  • plugin.json (contains pluginInfo that is used by both dplug-build and Dplug during compile-time)
  • gfx (images used by the gui)
  • fonts (font used by the gui)

Build the example with the dplug-build command-line:

$ dplug-build -c VST3                    # build a VST3 plug-in with the default bitness
$ dplug-build -c AU                      # build an AU plug-in with the default bitness (64-bit on macOS)
$ dplug-build -c LV2                     # build a LV2 plug-in with the default bitness
$ dplug-build -c VST3 -a x86             # build a 32-bit VST3 plug-in
$ dplug-build -c VST3 -a x86_64          # build a 64-bit VST3 plug-in
$ dplug-build -c VST3 -a x86_64 --final  # build an optimized 64-bit VST3 plug-in
$ dplug-build -c VST3 -c LV2 -c AU       # build several formats at once

Going further

From there, you just have to mimick the structure of existing Dplug example to create your own plug-ins. Be sure to edit the content of plugin.json to avoid unique ID conflicts!

Individual guides for all formats

Making plug-ins is inextricably tied with the legal requirements of signing SDK licences and agreements. Do not skip that step. We warmly recommend that you comply with your local laws.

Building VST 2.4 plug-ins

In order to build VST2 plug-ins with Dplug, you need to setup the VST2 SDK on your machine. https://www.steinberg.net/en/company/developers.html

However this VST2 SDK is generally not available anymore and we cannot do anything about it.

If you happen to have one, point a VST2_SDK environment variable to the matching VST2_SDK directory in the SDK.

Example: export VST2_SDK=/Users/MyName/vstsdk3610_11_06_2018_build_37/VST_SDK/VST2_SDK

If you were to distribute VST2 plug-ins, be aware that you need an agreement with Steinberg.

Building without dplug-build for ease of development

Use the following command to build a VST 2.4 without dplug-build:

$ dub -c VST    # choose the "VST" configuration with -c or --config

Limitations:

  • Note that on macOS, a barebones VST2 plug-in will not be usable by hosts except REAPER.
  • A barebones VST3 plug-in is not usable in VST3 hosts and has to be renamed to .vst3 first, and eventually put into the right system VST3 directory.
  • A barebones LV2, AU or AAX plug-in is not usable in hosts.

If the build is successful, it will generate a new file in the current directory (as opposed to the builds/ directory that dplug-build would use.

Troubleshooting

"I don't manage to build arm64 plug-ins" (Mac)

  • Use LDC 1.24 or superior: https://github.com/ldc-developers/ldc/releases/
  • Use XCode 12 or superior, or a SDK from there. It is yet unknown if this necessitates a Big Sur computer.
  • You may have to adapt the SDK path in etc/ldc2.conf for target -mtriple=arm64-apple-macos.

"I don't manage to build with LDC" (Windows)

Use any of the following methods:

  • Update to a newer LDC.
  • Run LDC in a 'VS Native/Cross Tools Command Prompt' (LDC checks whether the VSINSTALLDIR environment variable is set). LDC assumes the environment variables are all set up appropriately.
  • Set the LDC_VSDIR environment variable to some Visual Studio/Visual C++ Build Tools installation directory, e.g., 'C:\Program Files (x86)\Microsoft Visual Studio\2017\Community'. LDC will invoke a batch file provided by VS to set up the environment variables for the selected 32/64-bit target platform, which adds an overhead of about 1 second for each linking operation. You can also set LDC_VSDIR to some non-existing dummy path; LDC will try to auto-detect your latest Visual C++ installation in that case.
  • Set up the etc\ldc2.conf config file and specify the directories containing the MS libs (appending them to the 'lib-dirs' array; check out the LIB environment variable in a VS tools command prompt) as well as the C runtime flavor (e.g., appending '-mscrtlib=libcmt' to the 'switches' array). In case you prefer the MS linker over LLD, add the switch '-linker=<path\to\link.exe>'.

The dummy path method is recommended, as it's the most painless. Set an envvar LDC_VSDIR to some non-existing path.

Clone this wiki locally