Skip to content

Getting Started

Jump to bottom
p0nce edited this page Dec 7, 2024 · 68 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 CLAP, VST3, and Audio Unit.

The basics

💠 Step 1: Install a D language environment

Install the LDC language compiler. LDC is the recommended compiler for Dplug use.

Specific instructions for Windows.
Installing D on Windows can be painful if you want to have everything: VisualD, 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 and ldc2 commands working.

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

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

dub

That's it! Welcome to the D programming language.

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.
Since macOS 10.15 Sequoia: Running a D compiler got harder. First try to run ldc2 and dub binary, then unblock them from System Settings > Privacy and Security and click "run anyway".

Specific instruction for Linux
Install the X11 development libraries.

  • Redhat, Fedora => sudo yum install libX11-dev
  • Ubuntu => sudo apt-get install libX11-dev AskUbuntu

💠 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

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 give your plug-ins the required file structure.
  • dplug-build can build plug-ins in different DUB configurations and architectures in a single command-line run, then make an installer.
  • dplug-build manages code signing and notarization, necessary for wide software distribution.
  • dplug-build will fake the VST2_SDK envvarif you don't have a VST2 SDK, to build other formats without errors.

Specific instructions for macOS Big Sur and superior
dplug-build should 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 simple plug-in that does absolutely nothing
cd Dplug/examples/template

# 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 CLAP                 # build a CLAP plug-in
dplug-build -c VST3                 # build a VST3 plug-in
dplug-build -c AU                   # build an AU plug-in (macOS only)
dplug-build -a x86_64               # Specify the x86_64 architecture
dplug-build --final                 # build an optimized plug-in
dplug-build -c CLAP -c VST3         # build several formats at once
dplug-build --help                  # get help for dplug-build

See the --help output of dplug-build for an explanation for each flag.

💠 Step 5: Make your own plug-in 🚀

  • Copy one fo the example in your repositery.
  • Open dub.json:
    • Change "name" to any name
    • Change dependencies specifications from "path"-based to "~>MAJOR.0" like in the Template example. That way your plug-in can be located anywhere.
    • Adjust the "configurations" to support the formats you really want.
  • Open plugin.json:
    • Change the vendor name, the unique ID, etc.
  • Type dplug-build to build with the first configuration.

Going further

💡Inline documentation

💡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

You can build just the plug-in binary with a dub command, without using dplug-build.

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

It can be useful if your DAW supports plug-ins in a single file.

Troubleshooting

Be sure to check our new page: https://dplug.org/tutorials for any question you may have.

⚠️ "I get a link error in Windows, using LDC"

Most probably the right MSVC runtime, or Windows SDK, is missing. Reinstall Dlang following those steps.

⚠️ "I get no completion in VSCode"

Look at code-d's debug log.

⚠️ "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 have another question"

See: https://dplug.org/tutorials

Clone this wiki locally