Developer's Guide
Recommended Directory Structure
The following directory structure is recommended for building the plugins:
. └── Twonker ├── twonker -- Twonker source code │ ├── ARTISTIC │ ├── JUCE │ ├── README-devs.md │ ├── README.md │ ├── Release_pub.asc │ └── VERSION └── twonker_libs ├── JUCE -- JUCE source code │ ├── BREAKING-CHANGES.txt │ ├── ChangeList.txt │ ├── cmake-build │ ├── CMakeLists.txt │ ├── docs │ ├── examples │ ├── extras │ ├── LICENSE.md │ ├── modules │ └── README.md └── vstsdk -- VST2 legacy library ├── base ├── pluginterfaces ├── public.sdk └── vstgui4
Under the Twonker
folder:
twonker
: This is The Twonker source code.-
twonker_libs
: Under this folder:JUCE
: JUCE source code (downloadable from https://github.com/juce-framework/JUCE)vstsdk
: VST2 legacy library. This library cannot be redistributed legally, and is no longer available from Steinberg. If you accepted the license years ago when it was being actively maintained then you can continue using it today. However, the code base is no longer actively maintained and has been superceded by VST3.
Note: The VST2 build target is disabled by default, given that the VST2 specification is obsolete and not everyone can still obtain the VST2 SDK. It can be enabled from within the Projucer under Project Settings
, then Plugin Formats
.
JUCE
https://juce.comJUCE 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 Projucer
https://juce.com/discover/projucerThe 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 └── JuceLibraryCodeThe 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.
The Steinberg VST2 SDK however cannot be included with the repository due to licensing restrictions. Each developer needs their own license in order to use the VST2 SDK.
Minimal Configuration
In the Projucer application from the menubar, navigate to File
, then Global Paths
. From here you can configure:
- Path to JUCE: Top-level directory of the JUCE folder.
- VST (Legacy) SDK: (Optional) Top-level directory of the VST2 SDK folder. This SDK cannot be redistributed according to the VST2 license.
These two configuration options correspond to the recommended layout as follows:
. └── Twonker └── twonker_libs ├── JUCE -- Path to JUCE └── vstsdk -- VST (Legacy) SDK
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. 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 packages must be installed prior to compiling The Twonker on Linux:
- g++
- clang
- libasound2-dev
- libjack-jackd2-dev
- ladspa-sdk
- libcurl4-openssl-dev
- libfreetype6-dev
- libx11-dev
- libxcomposite-dev
- libxcursor-dev
- libxcursor-dev
- libxext-dev
- libxinerama-dev
- libxrandr-dev
- libxrender-dev
- libwebkit2gtk-4.0-dev
- libglu1-mesa-dev
- mesa-common-dev
The following apt
command will install all the required libraries:
sudo apt update sudo apt install g++ clang \ libasound2-dev libjack-jackd2-dev \ ladspa-sdk \ libcurl4-openssl-dev \ libfreetype6-dev \ libx11-dev libxcomposite-dev libxcursor-dev \ libxcursor-dev libxext-dev libxinerama-dev \ libxrandr-dev libxrender-dev \ libwebkit2gtk-4.0-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 must be stored. The build
directory will contain the final versions of all three packages along with the source tarball and digital signatures.
. └── Twonker ├── 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\VisualStudio2019\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.
- Continue development under new version.
Keep on keepin' on.
― Joe Dirt
Further Reading
- "A Brief Introduction"
- "User's Guide": General guide on how to setup and use The Twonker.
- "Overtones": The mathematical theory behind overtones and how they relate to our modern system of music.
- Initial Interface Sketches: The very first pencil-based sketches of the various interface elements for The Twonker.