"In the land of the blind, the one-eyed man is king"

Developer's Guide

JUCE

JUCE is an open-source cross-platform C++ application framework, used for the development of desktop and mobile applications. JUCE is used in particular for its GUI and plug-ins libraries. The Twonker is a JUCE-based VST plug-in.

The JUCE application framework can be downloaded from https://github.com/juce-framework/JUCE

The Projucer

https://juce.com/discover/projucer

The Projucer is an IDE tool for creating and managing JUCE projects. When the files and settings for a JUCE project have been specified, the Projucer automatically generates a collection of 3rd-party project files to allow the project to be compiled natively on each target platform.

Some files in the repository are generated by The Projucer and should not be modified directly (otherwise changes will be overwritten).

All the files under the following directory are generated by The Projucer:

Twonker
└── JUCE
    └── JuceLibraryCode

The Twonker project is configured to "Make Local Copies" of the required JUCE modules. When JUCE is upgraded, JUCE will copy the updated modules into the following folder:

Twonker
└── JUCE
    └── JuceLibraryCode
        └── modules

This folder is committed to Git so that building The Twonker is made simpler.

When upgrading JUCE, first delete all the code under the modules directory so that any orphaned modules are removed before the updated modules are copied in their place.

The JUCE module path is an absolute reference and only true for my development machine. This is the main reason why the modules are copied into the source repository.

Minimal Configuration

In the Projucer application from the menubar, navigate to File, then Global Paths. From here you can specify the top-level directory of the JUCE source code folder. This allows JUCE to manage the libary files within The Twonker project.

Upgrading JUCE

The JUCE GitLab reposotory is located at the following URL:

https://github.com/juce-framework/JUCE.git

Fetch the new version of JUCE:

git checkout x.y.z

Where x.y.z is the tagged version in GitLab.

Prepare The Twonker source by deleting the contents of the modules directory:

Twonker
└── JUCE
    └── JuceLibraryCode
        └── modules

Rebuild the new version of Projucer and load The Twonker JUCE project. Once loaded, save the project. If this does not actually perform a save (you can tell visually) then navigate to the Modules section and click "Set copy-mode for all modules" before saving. This will:

Update the C++ files generated by JUCE.
Update the JUCE modules.

Close the Projucer and open The Twonker Visual Studio solution file. Once loaded, rebuild the solution.

Commiting the upgraded JUCE modules to Git

When committing the code back to Git:

Delete all the "missing" files.
Add all the "unknown" files.

Platform-Specific Information

Linux

The following apt commands will install all the required libraries (for JUCE 8.0.10):

sudo apt update
sudo apt install libasound2-dev libjack-jackd2-dev \
  ladspa-sdk \
  libcurl4-openssl-dev  \
  libfreetype-dev libfontconfig1-dev \
  libx11-dev libxcomposite-dev libxcursor-dev libxext-dev \
  libxinerama-dev libxrandr-dev libxrender-dev \
  libwebkit2gtk-4.1-dev \
  libglu1-mesa-dev mesa-common-dev

To build on Linux, change to the following directory before running make:

cd ./JUCE/Builds/LinuxMakefile

The binary is placed under the following directory:

Twonker
└── JUCE
    └── Builds
        └── LinuxMakefile
            └── build

Release Procedure

Confirm VERSION file (and within JUCE) have same (new) version. Saving the project in JUCE will regenerate the files with the new version.

The following tree shows where the compiled binaries for each of the three platforms are stored for the release pipeline. The build directory will contain the final versions of all three packages along with the source tarball and digital signatures.

Twonker
├── bin
│   ├── Linux
│   │   └── Twonker.vst3
│   │       └── ...
│   ├── MacOS
│   │   └── Twonker.vst3
│   │       └── ...
│   └── Windows
│       └── Twonker.vst3
└── build

On Windows

Perform a Release build in Visual Studio.
Copy the Twonker.vst3 binary from the location: .\JUCE\Builds\VisualStudio2022\x64\Release\VST.

On MacOS:

Perform the build in XCode.
Copy the Twonker.vst binary from the location: [HOME]/Library/Audio/Plug-Ins/VST.

On Linux:

CD into the following directory: ./JUCE/Builds/LinuxMakefile.
Run the following command to compile the VST: make CONFIG=Release TARGET_ARCH=-m64
Copy the Linux VST from ./JUCE/Builds/LinuxMakefile/build/Twonker.vst3 to ./bin/Linux.
Move the Windows VST into the following folder: ./bin/Windows.
Move the MacOS VST into the following folder: ./bin/MacOS.
Run the script: ./generate.sh.
The distributable binaries and source code are created under the ./bin folder.

Afterwards:

Commit source code to GitLab & tag.
Upload the files to jasonlocke.com/twonker.
Create a new release in GitLab.
Bump VERSION file (and within JUCE) to prepare for future work.
Re-commit the new versions to GitLab.
Update the section "Platform Specific Information for Linux" for current version of JUCE. See JUCE Dependencies on Linux.
Continue development under new version.

Keep on keepin' on.
― Joe Dirt