Skip to content

Getting Started

Jump to bottom
p0nce edited this page Nov 6, 2023 · 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.

Specific instructions for Windows.
Installing D on Windows can be painful if you want to have everything: VisualD, DMD, LDC, debuggers, and support for all architectures.
Therefore, it is highly recommended to refer to the Installing Dlang on Windows article.

For other OSes:

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 the recommended compiler for all final builds. DMD can 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 Universal LDC package (for LDC version >= 1.30).
If the "Universal" build is not available, use the x86_64 LDC package instead. (for LDC version < 1.30).
Those builds are cross-compilers, able to target both x86_64 and arm64, with flags -a x86_64 and -a arm64-apple-macos respectively. Make sure you are using the dub executable from those builds. Please install Xcode 12.2+ too.

Specific instruction for Linux
You might have to install a package to get the X11 development libraries.
Redhat, Fedora, etc. => sudo yum install libX11-dev
Ubuntu, etc. => sudo apt-get install libX11-dev
(Reference: https://askubuntu.com/questions/526848/cmake-cant-find-X11)

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 get no completion in VSCode"

Look at code-d's debug log.

"I don't manage to install D!"

In case you encounter an issue while installing D language, post your questions on the D.learn forum: https://forum.dlang.org/group/learn

"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.2 or superior, or a SDK from there.
  • (for LDC 1.24 only) You may have to adapt the SDK path in etc/ldc2.conf for target -mtriple=arm64-apple-macos.

"What can I put in plugin.json?"

  • It is possible to start a project without a plugin.json and work from there using dplug-build errors.
  • Most people copy/paste from an example and work from there.

See plugin.json schema here for all allowed keys.

"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