Tags

Projucer Manual

Latest Projucer manual.

Date posted
Share on Social Media

Welcome to the Projucer manual.

This document will be updated regularly as new features are added to the Projucer. The manual is up to date as of the Projucer version displayed below.

Version: 5.3.0

Table of Contents


1. Introduction

1.1 Welcome to the Projucer!

The Projucer is a convenient application that allows you to develop, manage and deploy cross-platform applications in conjunction with your preferred IDE. It comes packaged with the JUCE library when downloaded or can be alternatively built from the latest development branch of the GitHub repository.

It is also a very powerful tool to manage all settings for your project, add source files, and much more. As you develop your JUCE application, the Projucer will be your faithful companion throughout the process.

If you haven't downloaded JUCE yet, visit the JUCE website at www.juce.com to download the library first. Unpack the JUCE folder and place it to some location on your computer. Your user home folder is a convenient place.

Go into the JUCE folder you just installed. You will find the Projucer that you can launch, located there.

1.2 System Requirements

The Projucer is available for all three major operating systems and has the following system requirements:

macOSWindowsLinux
10.9 or higher8.1 or higherUbuntu 16.04.3 LTS
Xcode 7.3 or higherVisual Studio 2015 or higherMakefile
64 Bit

You need to install the appropriate native IDE/build system on your computer before you can use the full features of JUCE with the Projucer. For some platforms, you may need to install additional dependencies as well, for example you need to install the Android SDK to develop for Android. On Linux, you may need to rebuild the Projucer for your specific distribution.

All of the files that you need to create VST and AU (macOS only) plug-ins are packaged with JUCE. In order to build VST3 or AAX plugins, please download the appropriate SDKs from Steinberg and Avid respectively.

To build AAX plug-ins (for Pro Tools) you will need to contact Avid for a developer license in order to access their SDK.

1.3 Sign in to my.roli

In order to use the Projucer, you will need a my.roli account and sign in when the application launches. If you need to create a my.roli account, please visit the ROLI website to register.

When first launched, the application will ask you to sign in with your my.roli credentials. Enter your email or username and password to log in.

Sign in with your my.roli account

If you have trouble signing in to your my.roli account, please make sure that you have entered the same email address you used when signing up or purchasing your JUCE license.

If you want to use the Projucer under the GPL license and bypass this screen, you can recompile the application by setting the JUCER_ENABLE_GPL_MODE flag to 1 in the AppConfig.h file.

1.4 Purchasing a JUCE License

You will also need a JUCE license registered in your ROLI account to use the Projucer. In the following screen, you can choose the type of license you wish to use:

Purchasing a JUCE license

You can learn more about licenses on the JUCE website and in the notices section of this manual.

1.5 Create a New Project

The first time you launch the Projucer, you are presented with the new project wizard. (You can also launch the wizard later by selecting New Project... from the Projucer's main menu.) To create a new Projucer project, select the project type of your choice in the project template chooser:

Create new project window

For each project type, the Projucer will generate all project files and add the appropriate minimal code that sets everything up. In this way, after you have created your project, you can immediately get started with developing your actual functionality.

If you are exploring JUCE for the first time and don't know where to start, go for a GUI application --- this will set up all the basics for a working application for you, for both desktop and mobile platforms.

The following table describes the different types of template project that the Projucer can create for you:

Project TypeDescription
GUI ApplicationThis creates a minimal JUCE application with an empty application window. You can start here and add more functionality, such as more GUI components, using the various classes that JUCE offers.
Animated ApplicationThis creates an application which draws an animated graphical display. You can start here to create an animated mobile app, for example.
OpenGL ApplicationThis creates a blank JUCE application, like GUI Application, but adds support for OpenGL to draw features including 3D model import and GLSL shaders.
Console ApplicationJUCE is also very useful for developing command-line applications that do not have any GUI at all. Use this project type to create such an application.
Audio ApplicationThis creates a blank JUCE application, like GUI Application, but automatically adds all the setup code that you need to easily get audio input and output. You can use this for games, multimedia applications, and much more.
Audio Plug-InThis creates a blank audio plug-in. All the code to support VST, AudioUnit and AAX plug-in formats, is added automatically. Depending on your setup, this project type may require some additional preparation steps to work correctly.
Static LibraryThis project type is useful to create re-usable software libraries that build on top of JUCE. Use this for static library linking.
Dynamic LibraryThis project type is useful to create re-usable software libraries that build on top of JUCE. Use this for dynamic library linking.

Optionally, you can open existing projects or create blank templates in the same screen as described below:

CommandDescription
Open Existing ProjectOpens an existing project from the file browser.
Create Blank ProjectThis creates a blank project with no source files at all.
Browse JUCE DemosOpens the DemoRunner app to browse through demo projects from the JUCE/examples directory.
View JUCE TutorialsOpens the default browser to view JUCE tutorials on the website.

There are also many example projects which can serve as an alternative starting point for your project. They are located in the subfolder JUCE/examples. You can open an example project by navigating to File > Open Example from the menu items.

You are not limited by the project type you choose; for example, if you selected GUI Application, you can always add animations and OpenGL later. However, you cannot easily convert an Application to a Library or an Audio Plug-In later.

After you have selected the appropriate project type, the Projucer will take you through some additional settings, such as the target platform of your application and various project paths. In the second page of the wizard, you will be prompted with a configuration screen like this:

Create new project window (continued)

In this screen you can specify the name of your project and its location on your local system and choose which type of files to auto-generate. You will also select the location of your modules folder and the target platforms of your choice.

  • Project Name: Choose a name for your app in the top left corner.
  • Project Type: The selected project type from the previous screen.
  • Files to Auto-Generate: Depending on the project type, this field may offer some options on what code to auto-generate. If you are new to JUCE, the default selection is usually the best way to go to auto-generate everything you need and get you going quickly.
  • Modules Folder: The JUCE framework code is organised into modules. So you need to tell your project where the JUCE modules are located. Specify the location of the modules subfolder located inside the JUCE folder installed on your system. You can alternatively choose to use the Global Module Paths by checking the appropriate checkbox below the field.
  • Project Folder: Choose the folder where the Projucer should create your project. (Note: this is completely independent from the location where the JUCE modules folder is.)
  • Target Platforms: Select which native IDEs you want to use to build and debug your app. This also defines the desktop and mobile platforms that your app will support. Don't worry, this is not a final choice --- with the Projucer, you can add additional platforms and IDEs later.
  • Cancel/Create Buttons: When you have reviewed all your settings, click the Create button to actually generate the Projucer project at the location you specified or hit the Cancel button to revert to the previous screen.

The following target platforms are currently supported in the Projucer:

Target PlatformDescription
Xcode (macOS)Exports an Xcode project to build an executable for macOS.
Xcode (iOS)Exports an Xcode project to build an executable for iOS.
Visual Studio 2017Exports a Visual Studio 2017 project to build an executable for Windows.
Visual Studio 2015Exports a Visual Studio 2015 project to build an executable for Windows.
Visual Studio 2013Exports a Visual Studio 2013 project to build an executable for Windows.
Linux MakefileExports a Makefile project to build an executable for Linux.
AndroidExports an Android Studio project to build an executable for Android.
Code::Blocks (Windows)Exports a Code::Blocks project to build an executable for Windows.
Code::Blocks (Linux)Exports a Code::Blocks project to build an executable for Linux.
CLion (beta)Exports a CLion project to build an executable for macOS, Windows or Linux.

This table shows the currently supported IDEs depending on your target platform:

Target PlatformSupported IDEs
macOSXcode, CLion
WindowsVisual Studio, Code::Blocks, CLion
LinuxMakefile, Code::Blocks, CLion
iOSXcode, CLion
AndroidAndroid Studio

All export targets (which are the native IDE projects) are generated when you create your Projucer project. They are also updated every time you save it in the Projucer. At any time, you can create new export targets to add support for more IDEs and platforms to your project.

Below is the folder structure of a JUCE project that the Projucer generates for you:

Folder/FileContent
.jucer FileContains all project settings.
Source FolderThe C++ source code of your JUCE app.
Builds FolderThe export targets generated by the Projucer. Open these files to start coding, debugging, and running your JUCE app.
JuceLibraryCode FolderAuto-generated header files that include the JUCE library code via the JUCE modules. Note that the actual JUCE library code is not located here, but inside your globally-installed JUCE folder.

1.6 Global Paths

Instead of specifying an absolute or relative path for your modules in each of your Projucer projects, you can choose to use the global paths that are set on your development machine. This way you can open up the same Projucer project on another machine and it will automatically search for the global paths set on that system. You can access this setup screen by navigating under the menu items to Projucer > Global Paths...:

Global paths window

If you remove the text from the field for a particular path first, you can then drag-and-drop the directory from your operating system.

If the path is correct it should be displayed in white text (or red if there is a problem).

These paths are platform-specific and they are stored locally on your development machine:

JUCE PathDescription
Path to JUCELocation of the JUCE library on your local system as an absolute or relative path.
Module PathDescription
JUCE ModulesLocation of the JUCE library modules on your local system as an absolute or relative path.
User ModulesLocation of the custom user modules on your local system as an absolute or relative path.

You can also set the global paths for your plug-in SDKs and Android SDKs in the same window:

SDK PathDescription
VST3 SDKLocation of the Steinberg VST3 SDK on your local system as an absolute or relative path.
RTAS SDK[Except Linux] - Location of the Avid RTAS SDK on your local system as an absolute or relative path.
AAX SDK[Except Linux] - Location of the Avid AAX SDK on your local system as an absolute or relative path.
Android SDKLocation of the Android SDK on your local system as an absolute or relative path.
Android NDKLocation of the Android NDK on your local system as an absolute or relative path.
Other PathDescription
CLion app/executable/startup scriptLocation of the CLion application on your local system as an absolute or relative path.

2. Main Window

2.1 Main Window Sections

The main Projucer project window is separated into three different sections namely the toolbar at the top, the side panel on the left and the editor on the right as shown in the following screenshot:

Main window of the Projucer

2.2 Main Window Controls

The toolbar at the top of the window provides various functionalities described in this table:

IconActionDescription
Cog IconProject SettingsOpens the project settings panel.
IDE IconSave and Open in IDESaves the project and opens it in the default IDE for the chosen exporter. Icon varies depending on IDE.
Launch IconLaunch ApplicationLaunches the application in the Projucer. This action is only available when compilation is enabled.
User IconUser SettingsOpens the user settings popup window.

2.3 Side Panel Controls

The side panel of the Projucer is divided into two sections namely the project tab with file explorer, modules and exporters panels and a live-build engine tab as shown here:

Side panel concertina

In various sections of the side panel, you will find buttons with different functionalities described in this table:

IconActionDescription
Info IconInfo PopupProvides useful help text as a popup for the parameter in question.
Add IconAdd File/Module/ExporterProvides a contextual menu to add files, modules and exporters in the appropriate section.
Cog IconLive Build/Module SettingsOpens the live build settings or the global module settings window to manage all module settings at once.

Hover over and click on the info icon anywhere in the Projucer to get additional information on the parameter in question.


3. Project Settings

In the Projucer’s configuration settings, you can change project settings, such as which plug-in types you wish to export and whether the plug-in receives or produces MIDI notes (amongst many other things). You can change these settings at any time.

3.1 Project Settings for an Application

The project settings page can be accessed by clicking on the corresponding button in the toolbar or through the menu items under View > Show Project Settings.

Project settings window

The following table describes the settings for an application type project:

Project SettingDescription
Project NameThe name of the project.
Project VersionThe project's version number, This should be in the format major.minor.point[.point].
Company NameYour company name, which will be added to the properties of the binary where possible.
Company CopyrightYour company copyright, which will be added to the properties of the binary where possible.
Company WebsiteYour company website, which will be added to the properties of the binary where possible.
Company E-mailYour company e-mail, which will be added to the properties of the binary where possible.
Report JUCE app usageThis option controls the collection of usage data from users of this JUCE application. Required for closed source applications without an Indie or Pro JUCE license. In accordance with the terms of the JUCE 5 End-Use License Agreement (www.juce.com/juce-5-licence), this option can only be disabled for closed source applications if you have a JUCE Indie or Pro license, or are using JUCE under the GPL v3 license.
Display the JUCE splash screenThis option controls the display of the standard JUCE splash screen. Required for closed source applications without an Indie or Pro JUCE license. In accordance with the terms of the JUCE 5 End-Use License Agreement (www.juce.com/juce-5-licence), this option can only be disabled for closed source applications if you have a JUCE Indie or Pro license, or are using JUCE under the GPL v3 license.
Splash screen colourChoose the colour of the JUCE splash screen between "Dark" and "Light".
Project TypeThe project type for which settings should be shown. Can be selected from "GUI Application", "Console Application", "Static Library", "Dynamic Library" and "Audio Plug-In".
Bundle IdentifierA unique identifier for this product, mainly for use in OSX/iOS builds. It should be something like 'com.yourcompanyname.yourproductname'.
BinaryData.cpp size limitWhen splitting binary data into multiple cpp files, the Projucer attempts to keep the file sizes below this threshold. (Note that individual resource files which are larger than this size cannot be split across multiple cpp files). The options are "64 KB", "128 KB", "256 KB", "512 KB", "1 MB", "2 MB", "6 MB", "10 MB", "20MB" and "Default".
Include BinaryData in AppConfigEnable this if you want to include the BinaryData header in your AppConfig header.
BinaryData NamespaceThe namespace containing the binary assests. If left empty this defaults to "BinaryData".
C++ Language StandardThe standard of the C++ language that will be used for compilation. Can be selected from C++11, C++14, C++17 and the latest C++ version.
Preprocessor definitionsGlobal preprocessor definitions. Use the form "NAME1=value NAME2=value", using whitespace, commas, or new-lines to separate the items - to include a space or comma in a definition, precede it with a backslash.
Header search pathsGlobal header search paths.
NotesExtra comments: This field is not used for code or project generation, it's just a space where you can express your thoughts.

3.2 Project Settings for a Plug-In

When the project is set as an audio plug-in, you will find different settings on the same page:

Project settings window (continued)

The following settings allow you to build different plug-in formats within the same Projucer project:

Plugin SettingDescription
Build VSTWhether the project should produce a VST plugin.
Build VST3Whether the project should produce a VST3 plugin.
Build AudioUnitWhether the project should produce an AudioUnit plugin.
Build AudioUnit v3Whether the project should produce an AudioUnit version 3 plugin.
Build RTASWhether the project should produce an RTAS plugin.
Build AAXWhether the project should produce an AAX plugin.
Build Standalone Plug-InWhether the project should produce a standalone version of your plugin.
Enable Inter-App AudioWhether a standalone plug-in should be an Inter-App Audio app. You should also enable the audio background capability in the iOS exporter.

The following table describes additional plug-in settings shown on the project settings page:

Plugin SettingDescription
Plugin NameThe name of your plugin. (Keep it short!)
Plugin DescriptionA short description of your plugin.
Plugin ManufacturerThe name of your company (cannot be blank).
Plugin Manufacturer CodeA four-character unique ID for your company. Note that for AU compatibility, this must contain at least one upper-case letter!
Plugin CodeA four-character unique ID for your plugin. Note that for AU compatibility, this must contain at least one upper-case letter!
Plugin Channel ConfigurationsThis list is a comma-separated set list in the form {numIns, numOuts} and each pair indicates a valid plug-in configuration. For example {1, 1}, {2, 2} means that the plugin can be used either with 1 input and 1 output, or with 2 inputs and 2 outputs. If your plug-in requires side-chains, aux output buses etc., then you must leave this field empty and override the isBusesLayoutSupported callback in your AudioProcessor.
Plugin is a SynthEnable this if you want your plugin to be treated as a synth or generator. It doesn't make much difference to the plugin itself, but some hosts treat synths differently to other plugins.
Plugin Midi InputEnable this if you want your plugin to accept midi messages.
Plugin Midi OutputEnable this if your plugin is going to produce midi messages.
Midi Effect PluginEnable this if your plugin only processes midi and no audio.
Plugin Editor Requires Keyboard FocusEnable this if your plugin needs keyboard input - some hosts can be a bit funny about keyboard focus.
Plugin AU Export PrefixA prefix for the names of exported entry-point functions that the component exposes - typically this will be a version of your plugin's name that can be used as part of a C++ token.
Plugin AU Main TypeIn an AU, this is the value that is set as JucePlugin_AUMainType, such as: kAudioUnitType_Effect, kAudioUnitType_FormatConverter, kAudioUnitType_Generator, kAudioUnitType_MIDIProcessor, kAudioUnitType_Mixer, kAudioUnitType_MusicDevice, kAudioUnitType_MusicEffect, kAudioUnitType_OfflineEffect, kAudioUnitType_Output and kAudioUnitType_Panner. Leave it blank unless you want to use a custom value.
Plugin VST CategoryIn a VST, this is the value that is set as JucePlugin_VSTCategory, such as: kPlugCategUnknown, kPlugCategEffect, kPlugCategSynth, kPlugCategAnalysis, kPlugCategMastering, kPlugCategSpacializer, kPlugCategRoomFx, kPlugSurroundFx, kPlugCategRestoration, kPlugCategOfflineProcess, kPlugCategShell and kPlugCategGenerator. Leave it blank unless you want to use a custom value.
Plugin RTAS CategoryThis is one of the RTAS categories from FicPluginEnums.h, such as: ePlugInCategory_None, ePlugInCategory_EQ, ePlugInCategory_Dynamics, ePlugInCategory_PitchShift, ePlugInCategory_Reverb, ePlugInCategory_Delay, ePlugInCategory_Modulation, ePlugInCategory_Harmonic, ePlugInCategory_NoiseReduction, ePlugInCategory_Dither and ePlugInCategory_SoundField. (Leave this blank if your plugin is a synth).
Plugin AAX CategoryThis is one of the categories from the AAX_EPlugInCategory enum, such as: AAX_ePlugInCategory_None, AAX_ePlugInCategory_EQ, AAX_ePlugInCategory_Dynamics, AAX_ePlugInCategory_PitchShift, AAX_ePlugInCategory_Reverb, AAX_ePlugInCategory_Delay, AAX_ePlugInCategory_Modulation, AAX_ePlugInCategory_Harmonic, AAX_ePlugInCategory_NoiseReduction, AAX_ePlugInCategory_Dither, AAX_ePlugInCategory_SoundField, AAX_ePlugInCategory_HWGenerators, AAX_ePlugInCategory_SWGenerators, AAX_ePlugInCategory_WrappedPlugin, AAX_EPlugInCategory_Effect, AAX_ePlugInCategory_Example and AAX_ePlugInCategory_INT32_MAX.
Plugin AAX IdentifierThe value to use for the JucePlugin_AAXIdentifier setting.

4. Code Editor

The projucer offers a basic code editor for C++ source files. It is located on the right hand side of the interface.

4.1 Code Editor Panel

When a header or CPP file is selected in the side panel file explorer, the editor window will show a code editor with syntax highlighting as shown below:

Code editor window

You can choose to edit your code directly in the Projucer or use your favourite IDE after exporting your project. The code editor in the Projucer has convenient features such as slider controls on numeric types and colour picker wheels on colour types.

4.2 Editor Colour Scheme

You can also choose to change the colour scheme of the code editor to fit your needs using the editor colour scheme window that you can find under View > Editor Colour Scheme > Create...:

Editor colour scheme window

You can optionally save and load custom colour schemes on your local machine.


5. File Explorer

The projucer offers a file browser for C++ source files. It is located under the File explorer tab on the left hand side.

With the Projucer, you can add new source files to your project and delete or rename existing ones, as well as organise files into groups.

Groups are not the same as folders. If you create a file in a group in Projucer, you will also be asked in which folder to save the file. With this, it is possible to have a folder structure that is different from the group structure. However, it is highly recommended and good practice to have your groups follow the structure and names of the folders.

5.1 File Explorer Side Panel

The file explorer shows a hierarchical view of your project files. You can rename, delete and create files as well as folders in this side panel.

File explorer panel

5.2 File Explorer Folder Settings

If you select a folder in the side panel, you can access the bulk settings of all the files contained in that folder as shown in the following screen:

File explorer window

The various options offered on this screen are described in the following table:

ToggleDescription
Binary ResourceThe file is added as a binary resource in your executable. Counts towards your platform-specific binary app size limits.
Xcode ResourceThe file is added as a resource in a separate folder. Counts towards your total resource size limits.
CompileWhether the file should be compiled and added to the appropriate build target.

5.3 Adding New Files

By clicking on the + button of the file explorer, you are presented with different options as shown here:

File explorer popup menu

If you make changes to the file structure and then save the project afterwards, your changes will be reflected in all native IDE projects that are exported. In this way, you can easily keep the file structure of the project consistent across all platforms you are developing on.

You should never add, rename, and/or remove source files from JUCE projects inside your native IDE (such as Xcode, Visual Studio). These changes would be overwritten the next time you save the project in Projucer (which re-generates the native IDE projects every time). Instead, always use the Projucer itself to make such changes.


6. Module Settings

The JUCE library code is organised into different modules. By default, all modules that are needed for the type of your project are added.

6.1 JUCE Modules

The JUCE library is organised into different modules with separate functionalities. You can choose to include certain modules in the modules section of the Projucer depending on the requirements and features of your project.

Most JUCE modules require other JUCE modules to properly compile. If you ever remove a module on which other modules of your project depend on, then the Projucer will highlight the now "broken" modules in red. You must then either remove the "broken" modules or add the missing modules.

The following table shows the currently available modules to JUCE users:

ModuleDescription
juce_analyticsClasses to collect analytics and send to destinations
juce_audio_basicsClasses for audio buffer manipulation, midi message handling, synthesis, etc
juce_audio_devicesClasses to play and record from audio and MIDI I/O devices
juce_audio_formatsClasses for reading and writing various audio file formats
juce_audio_plugin_clientClasses for building VST, VST3, AudioUnit, AAX and RTAS plugins
juce_audio_processorsClasses for loading and playing VST, AU, or internally-generated audio processors
juce_audio_utilsClasses for audio-related GUI and miscellaneous tasks
juce_blocks_basicsJUCE wrapper for low-level control over ROLI BLOCKS devices
juce_box2dThe Box2D physics engine and some utility classes
juce_coreThe essential set of basic JUCE classes, as required by all the other JUCE modules
juce_cryptographyClasses for various basic cryptography functions, including RSA, Blowfish, MD5, SHA, etc
juce_data_structuresClasses for undo/redo management, and smart data structures
juce_dspClasses for audio buffer manipulation, digital audio processing, filtering, oversampling, fast math functions etc
juce_eventsClasses for running an application's main event loop and sending/receiving messages, timers, etc
juce_graphicsClasses for 2D vector graphics, image loading/saving, font handling, etc
juce_gui_basicsBasic user-interface components and related classes
juce_gui_extraMiscellaneous GUI classes for specialised tasks
juce_openglClasses for rendering OpenGL in a JUCE window
juce_oscOpen Sound Control implementation
juce_product_unlockingClasses for online product authentication
juce_videoClasses for playing video and capturing camera input

6.2 Modules Side Panel

The modules side panel shows the modules that are currently included in your project and lets you manage the settings associated with them.

Modules panel

6.3 Modules Global Settings

To manage all the modules at once, click on the settings icon of the side panel to access the global settings as shown in the following screenshot:

Modules window

It provides an overview over all currently used modules and allows you to set the paths to them.

The table of modules shown on the screen describe current settings for individual modules.

SettingDescription
VersionDescribes the module version according to the JUCE library version.
Make Local CopyCreates a local copy of the entire module into your project making it self-contained and free of references into other folders.
PathsLocation of the module on your local system as an absolute or relative path. You can specify different paths for different platforms or optionally instruct the module to use the global path set in the Global Paths... menu.

These settings can be modified in bulk by clicking on the buttons at the bottom of the window.

6.4 Individual Module Settings

By clicking on an individual module in the side panel, you can access individual settings for the specified module:

Module settings window

Here, you can check the version and licence of a particular module, and set the paths to additional dependencies such as SDKs and external libraries that a particular module is using. Usually, the default settings work just fine and you should rarely need to go into this page.

6.4.1 Common Module Settings

The following table shows the settings common to all modules:

SettingDescription
VersionDescribes the module version according to the JUCE library version.
LicenseDescribes the module license such as ISC or GPL/Commercial.
LocationDescribes the location of the module on your local system as an absolute path.
Path for "Exporter"Location of the module per exporter on your local system as an absolute or relative path.
Use global pathWhether to use the global path set in the Global Paths... menu instead of the exporter-specific paths.
Create local copyCreates a local copy of the entire module into your project making it self-contained and free of references into other folders.
Add source to projectWhether to include all the files of the module or only the necessary files to compile the project.
6.4.2 Special Module Settings

The following table shows module-specific settings for all the included JUCE modules:

ModuleSettingDescription
juce_audio_devicesJUCE_ASIO[Windows Only] - Enables ASIO audio devices. Turning this on means that you'll need to have the Steinberg ASIO SDK installed on your Windows build machine.
juce_audio_devicesJUCE_WASAPI[Windows Vista and Above Only] - Enables WASAPI audio devices. See also the JUCE_WASAPI_EXCLUSIVE flag.
juce_audio_devicesJUCE_WASAPI_EXCLUSIVE[Windows Vista and Above Only] - Enables WASAPI audio devices in exclusive mode.
juce_audio_devicesJUCE_DIRECTSOUND[Windows Only] - Enables DirectSound audio.
juce_audio_devicesJUCE_ALSA[Linux Only] - Enables ALSA audio devices.
juce_audio_devicesJUCE_JACK[Linux Only] - Enables JACK audio devices.
juce_audio_devicesJUCE_USE_ANDROID_OBOE[Android Only] - Enables Oboe devices (API 16 or above). Requires Oboe repository path to be specified in Android exporter.
juce_audio_devicesJUCE_USE_ANDROID_OPENSLES[Android Only] - Enables OpenSLES devices.
juce_audio_devicesJUCE_USE_WINRT_MIDI[Windows 10 and Above Only] - Enables the use of the Windows Runtime API for MIDI, which supports Bluetooth Low Energy connections on computers with the Anniversary Update of Windows 10. To compile with this flag requires version 10.0.14393.0 of the Windows Standalone SDK and you must add the path to the WinRT headers. This path should be something similar to "C:\Program Files (x86)\Windows Kits\10\Include\10.0.14393.0\winrt". Microsoft's Bluetooth MIDI stack has multiple issues, use at your own risk!
juce_audio_devicesJUCE_DISABLE_AUDIO_MIXING_WITH_OTHER_APPS[iOS Only] - Turning this on gives your app exclusive access to the system's audio on platforms which support it.
juce_audio_formatsJUCE_USE_FLACEnables the FLAC audio codec classes. If your app doesn't need to read FLAC files, you might want to disable this to reduce the size of your codebase and build time.
juce_audio_formatsJUCE_USE_OGGVORBISEnables the Ogg-Vorbis audio codec classes. If your app doesn't need to read Ogg-Vorbis files, you might want to disable this to reduce the size of your codebase and build time.
juce_audio_formatsJUCE_USE_MP3AUDIOFORMATEnables the software-based MP3AudioFormat class. IMPORTANT DISCLAIMER: By choosing to enable the JUCE_USE_MP3AUDIOFORMAT flag and to compile this MP3 code into your software, you do so AT YOUR OWN RISK! By doing so, you are agreeing that ROLI Ltd. is in no way responsible for any patent, copyright, or other legal issues that you may suffer as a result. The code in juce_MP3AudioFormat.cpp is NOT guaranteed to be free from infringements of 3rd-party intellectual property. If you wish to use it, please seek your own independent advice about the legality of doing so. If you are not willing to accept full responsibility for the consequences of using this code, then do not enable this setting.
juce_audio_formatsJUCE_USE_LAME_AUDIO_FORMATEnables the LameEncoderAudioFormat class.
juce_audio_formatsJUCE_USE_WINDOWS_MEDIA_FORMAT[Windows Only] - Enables the Windows Media SDK codecs.
juce_audio_plugin_clientJUCE_FORCE_USE_LEGACY_PARAM_IDS[Plugin Only] - Enable this if you want to force JUCE to use a continuous parameter index to identify a parameter in a DAW (this was the default in old versions of JUCE). This is index is usually used by the DAW to save automation data and enabling this may mess up user's DAW projects.
juce_audio_plugin_clientJUCE_FORCE_LEGACY_PARAMETER_AUTOMATION_TYPE[Plugin Only] - Enable this if you want to force JUCE to use a legacy scheme for identifying plug-in parameters as either continuous or discrete. DAW projects with automation data written by an AudioUnit, VST3 or AAX plug-in built with JUCE version 5.1.1 or earlier may load incorrectly when opened by an AudioUnit, VST3 or AAX plug-in built with JUCE version 5.2.0 and later.
juce_audio_plugin_clientJUCE_USE_STUDIO_ONE_COMPATIBLE_PARAMETERS[Plugin Only] - Enable this if you want JUCE to use parameter ids which are compatible with Studio One. Studio One ignores any parameter ids which are negative. Enabling this option will make JUCE generate only positive parameter ids. Note that if you have already released a plug-in prior to JUCE 4.3.0 then enabling this will change your parameter ids making your plug-in incompatible to old automation data.
juce_audio_plugin_clientJUCE_STANDALONE_FILTER_WINDOW_USE_KIOSK_MODE[Plugin Only] - Enable this if you want your standalone plugin window to use kiosk mode. By default, kiosk mode is enabled on iOS and Android.
juce_audio_processorsJUCE_PLUGINHOST_VST[Plugin Only] - Enables the VST audio plugin hosting classes.
juce_audio_processorsJUCE_PLUGINHOST_VST3[Plugin Only] - Enables the VST3 audio plugin hosting classes. This requires the Steinberg VST3 SDK to be installed on your machine.
juce_audio_processorsJUCE_PLUGINHOST_AU[Plugin and macOS Only] - Enables the AudioUnit plugin hosting classes.
juce_audio_utilsJUCE_USE_CDREADEREnables the AudioCDReader class (on supported platforms).
juce_audio_utilsJUCE_USE_CDBURNEREnables the AudioCDBurner class (on supported platforms).
juce_coreJUCE_FORCE_DEBUGNormally, JUCE_DEBUG is set to 1 or 0 based on compiler and project settings, but if you define this value, you can override this to force it to be true or false.
juce_coreJUCE_LOG_ASSERTIONSIf this flag is enabled, the jassert and jassertfalse macros will always use Logger::writeToLog() to write a message when an assertion happens. Enabling it will also leave this turned on in release builds. When it's disabled, however, the jassert and jassertfalse macros will not be compiled in a release build.
juce_coreJUCE_CHECK_MEMORY_LEAKSEnables a memory-leak check for certain objects when the app terminates. See the LeakedObjectDetector class and the JUCE_LEAK_DETECTOR macro for more details about enabling leak checking for specific classes.
juce_coreJUCE_DONT_AUTOLINK_TO_WIN32_LIBRARIES[Visual Studio Only] - In a Visual C++ build, this can be used to stop the required system libs being automatically added to the link stage.
juce_coreJUCE_INCLUDE_ZLIB_CODEThis can be used to disable JUCE's embedded 3rd-party zlib code. You might need to tweak this if you're linking to an external zlib library in your app, but for normal apps, this option should be left alone. If you disable this, you might also want to set a value for JUCE_ZLIB_INCLUDE_PATH, to specify the path where your zlib headers live.
juce_coreJUCE_USE_CURL[Linux Only] - Enables http/https support via libcurl. Enabling this will add an additional run-time dynamic dependency to libcurl. If you disable this then https/ssl support will not be available on linux.
juce_coreJUCE_CATCH_UNHANDLED_EXCEPTIONSIf enabled, this will add some exception-catching code to forward unhandled exceptions to your JUCEApplicationBase::unhandledException() callback.
juce_coreJUCE_ALLOW_STATIC_NULL_VARIABLESIf disabled, this will turn off dangerous static globals like String::empty, var::null, etc which can cause nasty order-of-initialisation problems if they are referenced during static constructor code.
juce_dspJUCE_ASSERTION_FIRFILTERWhen this flag is enabled, an assertion will be generated during the execution of DEBUG configurations if you use a FIRFilter class to process FIRCoefficients with a size higher than 128, to tell you that's it would be more efficient to use the Convolution class instead. It is enabled by default, but you may want to disable it if you really want to process such a filter in the time domain.
juce_dspJUCE_DSP_USE_INTEL_MKLIf this flag is set, then JUCE will use Intel's MKL for JUCE's FFT and convolution classes. The folder containing the mkl_dfti.h header must be in your header search paths when using this flag. You also need to add all the necessary intel mkl libraries to the "External Libraries to Link" field in the Projucer.
juce_dspJUCE_DSP_USE_SHARED_FFTWIf this flag is set, then JUCE will search for the fftw shared libraries at runtime and use the library for JUCE's FFT and convolution classes. If the library is not found, then JUCE's fallback FFT routines will be used. This is especially useful on linux as fftw often comes pre-installed on popular linux distros. You must respect the FFTW license when enabling this option.
juce_dspJUCE_DSP_USE_STATIC_FFTWIf this flag is set, then JUCE will use the statically linked fftw libraries for JUCE's FFT and convolution classes. You must add the fftw header/library folder to the extra header/library search paths of your JUCE project. You also need to add the fftw library itself to the extra libraries supplied to your JUCE project during linking. You must respect the FFTW license when enabling this option.
juce_dspJUCE_DSP_ENABLE_SNAP_TO_ZEROEnables code in the dsp module to avoid floating point denormals during the processing of some of the dsp module's filters. Enabling this will add a slight performance overhead to the DSP module's filters and algorithms. If your audio app already disables denormals altogether (for exmaple, by using the ScopedNoDenormals class or the FloatVectorOperations::disableDenormalisedNumberSupport method), then you can safely disable this flag to shave off a few cpu cycles from the DSP module's filters and algorithms.
juce_eventsJUCE_EXECUTE_APP_SUSPEND_ON_IOS_BACKGROUND_TASK[iOS Only] - Will execute your application's suspend method on an iOS background task, giving you extra time to save your applications state.
juce_graphicsJUCE_USE_COREIMAGE_LOADER[macOS Only] - On OSX, enabling this flag means that the CoreImage codecs will be used to load PNG/JPEG/GIF files. It is enabled by default, but you may want to disable it if you'd rather use libpng, libjpeg, etc.
juce_graphicsJUCE_USE_DIRECTWRITE[Windows Only] - Enabling this flag means that DirectWrite will be used when available for font management and layout.
juce_gui_basicsJUCE_ENABLE_REPAINT_DEBUGGINGIf this option is turned on, each area of the screen that gets repainted will flash in a random colour, so that you can see exactly which bits of your components are being drawn.
juce_gui_basicsJUCE_USE_XRANDR[Linux Only] - Enables Xrandr multi-monitor support. Unless you specifically want to disable this, it's best to leave this option turned on. Note that your users do not need to have Xrandr installed for your JUCE app to run, as the availability of Xrandr is queried during runtime.
juce_gui_basicsJUCE_USE_XINERAMA[Linux Only] - Enables Xinerama multi-monitor support. Unless you specifically want to disable this, it's best to leave this option turned on. This will be used as a fallback if JUCE_USE_XRANDR not set or libxrandr cannot be found. Note that your users do not need to have Xinerama installed for your JUCE app to run, as the availability of Xinerama is queried during runtime.
juce_gui_basicsJUCE_USE_XSHM[Linux Only] - Enables X shared memory for faster rendering on Linux. This is best left turned on unless you have a good reason to disable it.
juce_gui_basicsJUCE_USE_XRENDER[Linux Only] - Enables XRender to allow semi-transparent windowing on Linux.
juce_gui_basicsJUCE_USE_XCURSOR[Linux Only] - Uses XCursor to allow ARGB cursor on Linux. This is best left turned on unless you have a good reason to disable it.
juce_gui_extraJUCE_WEB_BROWSER[macOS and Windows Only] - This lets you disable the WebBrowserComponent class. If you're not using any embedded web-pages, turning this off may reduce your code size.
juce_gui_extraJUCE_ENABLE_LIVE_CONSTANT_EDITOR[Debug Only] - This lets you turn on the JUCE_ENABLE_LIVE_CONSTANT_EDITOR support. See the documentation for that macro for more details.
juce_videoJUCE_USE_CAMERA[macOS and Windows Only] - Enables web-cam support using the CameraDevice class.

7. Exporter Settings

The different exporter targets created (Xcode, Visual Studio, and so on) can be found in the Exporters tab on the left hand side.

This is the place to specify additional compiler and linker flags and other platform-specific build settings.

7.1 Exporters Side Panel

The exporters side panel shows all the different configurations for the exporters selected in the project.

Exporters panel

7.2 Individual Exporter Settings

By clicking on the parent exporter in the side panel, you can access the individual settings for the selected exporter:

Exporter settings window

7.2.1 Common Exporter Settings

The following table shows the settings common to all exporters:

Common Exporter SettingsDescription
Target Project FolderThe location of the folder in which the project will be created. This path can be absolute, but it's much more sensible to make it relative to the jucer project directory.
VST3 SDK Folder[Plugin Only] - If you are building a VST3 plugin or host, this must be the folder containing the VST3 SDK. This can be an absolute path, or a path relative to the Projucer project file.
AAX SDK Folder[Plugin Only] - If you are building an AAX plugin, this must be the folder containing the AAX SDK. This can be an absolute path, or a path relative to the Projucer project file.
RTAS SDK Folder[Plugin Only] - If you are building an RTAS, this must be the folder containing the RTAS SDK. This can be an absolute path, or a path relative to the Projucer project file.
Extra Preprocessor DefinitionsExtra preprocessor definitions. Use the form "NAME1=value NAME2=value", using whitespace, commas, or new-lines to separate the items - to include a space or comma in a definition, precede it with a backslash.
Extra compiler flagsExtra command-line flags to be passed to the compiler. This string can contain references to preprocessor definitions in the form ${NAME_OF_DEFINITION}, which will be replaced with their values.
Extra linker flagsExtra command-line flags to be passed to the linker. You might want to use this for adding additional libraries. This string can contain references to preprocessor definitions in the form ${NAME_OF_VALUE}, which will be replaced with their values.
External libraries to linkAdditional libraries to link (one per line). You should not add any platform specific decoration to these names. This string can contain references to preprocessor definitions in the form ${NAME_OF_VALUE}, which will be replaced with their values.
GNU Compiler Extensions[Except Visual Studio] - Enabling this will use the GNU C++ language standard variant for compilation.
Icon (small)Sets an icon to use for the executable. Set to "<None>" by default.
Icon (large)Sets an icon to use for the executable. Set to "<None>" by default.
NotesExtra comments: This field is not used for code or project generation, it's just a space where you can express your thoughts.
7.2.2 Xcode Exporter Settings

The following table shows specific settings for Xcode:

Xcode Exporter SettingsDescription
Custom Xcassets folder[iOS Only] - If this field is not empty, your Xcode project will use the custom xcassets folder specified here for the app icons and launchimages, and will ignore the Icon files specified above.
Custom Xcode Resource foldersYou can specify a list of custom resource folders here (separated by newlines or whitespace). References to these folders will then be added to the Xcode resources. This way you can specify them for OS X and iOS separately, and modify the content of the resource folders without re-saving the Projucer project.
Don't add resources folder to app extension[Plugin and iOS Only] - Enable this to prevent the Projucer from creating a resources folder for AUv3 app extensions.
Device Family[iOS Only] - The device family to target. Options include "iPhone", "iPad" and "Universal".
iPhone Screen orientation[iOS Only] - The screen orientations that this app should support on iPhones. Options include "Portrait and Landscape", "Portrait" and "Landscape".
iPad Screen orientation[iOS Only] - The screen orientations that this app should support on iPad. Options include "Portrait and Landscape", "Portrait" and "Landscape".
File Sharing Enabled[iOS Only] - Enable this to expose your app's files to iTunes.
Support Document Browser[iOS Only] - Enable this to allow the user to access your app documents from a native file chooser.
Status Bar Hidden[iOS Only] - Enable this to disable the status bar in your app.
Microphone access[iOS Only] - Enable this to allow your app to use the microphone. The user of your app will be prompted to grant microphone access permissions.
Microphone access text[iOS Only] - A short description of why your app needs microphone access.
Document file extensions[GUI Application Only] - A comma-separated list of file extensions for documents that your app can open. Using a leading '.' is optional, and the extensions are not case-sensitive.
In-App purchases capabilityEnable this to grant your app the capability for in-app purchases. This option requires that you specify a valid Development Team ID.
Audio background capability[iOS Only] - Enable this to grant your app the capability to access audio when in background mode.
Bluetooth MIDI background capability[iOS Only] - Enable this to grant your app the capability to connect to Bluetooth LE devices when in background mode.
App groups capability[iOS Only] - Enable this to grant your app the capability to share resources between apps using the same app group ID.
iCloud Permissions[iOS Only] - Enable this to grant your app the capability to use native file load/save browser windows on iOS.
Push Notifications capabilityEnable this to grant your app the capability to receive push notifications.
Custom PListYou can paste the contents of an XML PList file in here, and the settings that it contains will override any settings that the Projucer creates. BEWARE! When doing this, be careful to remove from the XML any values that you DO want the Projucer to change!
PList PreprocessEnable this to preprocess PList file. This will allow you to set values to preprocessor defines, for instance if you define: #define MY_FLAG 1 in a prefix header file (see PList prefix header), you can have a key with MY_FLAG value and it will be replaced with 1.
PList Prefix HeaderHeader file containing definitions used in plist file (see PList Preprocess).
Extra FrameworksA comma-separated list of extra frameworks that should be added to the build. (Don't include the .framework extension in the name).
Pre-build shell scriptSome shell-script that will be run before a build starts.
Post-build shell scriptSome shell-script that will be run after a build completes.
Development Team IDThe Development Team ID to be used for setting up code-signing your iOS app. This is a ten-character string (for example, "S7B6T5XJ2Q") that describes the distribution certificate Apple issued to you. You can find this string in the OS X app Keychain Access under "Certificates".
App Group ID[iOS Only] - The App Group ID to be used for allowing multiple apps to access a shared resource folder. Multiple IDs can be added separated by a semicolon.
Keep custom Xcode schemesEnable this to keep any Xcode schemes you have created for debugging or running, e.g. to launch a plug-in in various hosts. If disabled, all schemes are replaced by a default set.
USE_HEADERMAPEnable this to make Xcode search all the projects folders for include files. This means you can be lazy and not bother using relative paths to include your headers, but it means your code won't be compatible with other build systems.
7.2.3 Visual Studio Exporter Settings

The following table shows specific settings for Visual Studio:

Visual Studio Exporter SettingsDescription
Manifest filePath to a manifest input file which should be linked into your binary (path is relative to jucer file).
Platform ToolsetSpecifies the version of the platform toolset that will be used when building this project. Options include the "Default" toolset, "v140", "v140_xp", "v141" and "v141_xp".
Use IPP LibraryEnable this to use Intel's Integrated Performance Primitives library. Options include "No", "Yes (Default Mode)", "Multi-Threaded Static Library", "Single-Threaded Static Library", "Multi-Threaded DLL" and "Single-Threaded DLL".
Windows Target PlatformSpecifies the version of the Windows SDK that will be used when building this project. On Windows 10, you can see which SDKs you have installed on your machine by going to "Program Files (x86)\Windows Kits\10\Lib". The default value for this exporter depends on your Visual Studio version.
7.2.4 Linux Makefile Exporter Settings

The following table shows specific settings for Linux Makefile:

Linux Makefile Exporter SettingsDescription
pkg-config librariesExtra pkg-config libraries for you application. Each package should be space separated.
7.2.5 Android Exporter Settings

The following table shows specific settings for Android:

Android Exporter SettingsDescription
Java libraries to includeJava libs (JAR files) (one per line). These will be copied to app/libs folder and "implementation files" dependency will be automatically added to module "dependencies" section for each library, so do not add the dependency yourself.
Module repositoriesModule repositories (one per line). These will be added to module-level gradle file repositories section.
Module dependenciesModule dependencies (one per line). These will be added to module-level gradle file dependencies section.
Screen orientationThe screen orientations that this app should support. Options include "Portrait and Landscape", "Portrait" and "Landscape".
Android Activity class nameThe full java class name to use for the app's Activity class.
Android Activity sub-class nameIf not empty, specifies the Android Activity class name stored in the app's manifest. Use this if you would like to use your own Android Activity sub-class.
Android Activity base classIf not empty, specifies the base class to use for your activity. If custom base class is specified, that base class should be a sub-class of android.app.Activity. When empty, Activity (android.app.Activity) will be used as the base class. Use this if you would like to use your own Android Activity base class.
Android Version CodeAn integer value that represents the version of the application code, relative to other versions.
Android SDK PathThe path to the Android SDK folder on the target build machine.
Android NDK PathThe path to the Android NDK folder on the target build machine.
Minimum SDK versionThe number of the minimum version of the Android SDK that the app requires.
Extra Android AssetsA path to a folder (relative to the project folder) which contains extra android assets.
gradle versionThe version of gradle that is used to build this app (3.3 is fine for JUCE).
android plug-in versionThe version of the android build plugin for gradle that is used to build this app.
NDK ToolchainThe toolchain that gradle should invoke for NDK compilation (variable model.android.ndk.tooclhain in app/build.gradle). Choice between "clang" and "gcc".
Android build tools versionThe Android build tools version that should use to build this app.
Oboe repository pathPath to the root of Oboe repository. Make sure to point Oboe repository to commit with SHA 44c6b6ea9c8fa9b5b74cbd60f355068b57b50b37 before building.
Internet AccessIf enabled, this will set the android.permission.INTERNET flag in the manifest.
Audio Input RequiredIf enabled, this will set the android.permission.RECORD_AUDIO flag in the manifest.
Bluetooth permissions RequiredIf enabled, this will set the android.permission.BLUETOOTH and android.permission.BLUETOOTH_ADMIN flag in the manifest. This is required for Bluetooth MIDI on Android.
Read from external storageIf enabled, this will set the android.permission.READ_EXTERNAL_STORAGE flag in the manifest.
Write to external storageIf enabled, this will set the android.permission.WRITE_EXTERNAL_STORAGE flag in the manifest.
In-App BillingIf enabled, this will set the com.android.vending.BILLING flag in the manifest.
VibrateIf enabled, this will set the android.permission.VIBRATE flag in the manifest.
Content SharingIf enabled, your app will be able to share content with other apps.
Custom permissionsA space-separated list of other permission flags that should be added to the manifest.
Remote NotificationsEnable to be able to send remote notifications to devices running your app (min API level 14). Provide Remote Notifications Config File, configure your app in Firebase Console and ensure you have the latest Google Repository in Android Studio's SDK Manager.
Remote Notifications Config FilePath to google-services.json file. This will be the file provided by Firebase when creating a new app in Firebase console.
Custom manifest XML contentYou can specify custom AndroidManifest.xml content overriding the default one generated by Projucer. Projucer will automatically create any missing and required XML elements and attributes and merge them into your custom content.
Import static library modulesComma or whitespace delimited list of static libraries (.a) defined in NDK_MODULE_PATH.
Import shared library modulesComma or whitespace delimited list of shared libraries (.so) defined in NDK_MODULE_PATH.
Key Signing: key.storeThe key.store value, used when signing the release package.
Key Signing: key.store.passwordThe key.store password, used when signing the release package.
Key Signing: key.aliasThe key.alias value, used when signing the release package.
Key Signing: key.alias.passwordThe key.alias password, used when signing the release package.
Android ThemeThe Android theme to use, e.g. @android:style/Theme.NoTitleBar or leave blank for default.
7.2.6 Code::Blocks Exporter Settings

The following table shows specific settings for Code::Blocks:

Code::Blocks Exporter SettingsDescription
Target platform[Windows Only] - This sets the preprocessor macro WINVER to an appropriate value for the corresponding platform. Options include the "Default" platform, "Windows NT 4.0", "Windows 2000", "Windows XP", "Windows Server 2003", "Windows Vista", "Windows Server 2008", "Windows 7", "Windows 8", "Windows 8.1" and "Windows 10".
7.2.7 CLion Exporter Settings

The following table shows specific settings for CLion:

CLion Exporter SettingsDescription
Import settings from exporterIf this is enabled then settings from the corresponding exporter will be used in the generated CMakeLists.txt file. There are three possible exporter options namely Xcode (macOS), Code::Blocks (Windows) and Linux Makefile.

CLion aggregates exporter settings from Xcode, Code::Blocks and Linux Makefile depending on your platform but does not contain specific settings like other exporters.

7.3 Adding New Exporters

By clicking on the + button of the exporter panel, you can add additional exporters as shown here:

Exporters popup menu

You can do this at any time. For example, if you originally created a JUCE application for Windows and macOS, but then later you decided to also add support for Linux, you can do it with ease.

You can also delete export targets by right-clicking on them and selecting Delete this exporter.

7.4 Configuration Settings

The Projucer creates build configurations to each export target which your native IDE will use to actually compile and run your app.

Each exporter can have several deployment configurations and these settings can be accessed by selecting the corresponding child configuration in the exporters side panel. By default, the two configurations Debug and Release are added to every export target.

7.4.1 Common Configuration Settings

The following table shows the settings common to all configurations:

Common Configuration SettingsDescription
NameThe name of this configuration.
Debug modeIf enabled, this means that the configuration should be built with debug symbols.
Binary nameThe filename to use for the destination binary executable file. If you don't add a suffix to this name, a suitable platform-specific suffix will be added automatically.
Binary locationThe folder in which the finished binary should be placed. Leave this blank to cause the binary to be placed in its default location in the build folder.
Header search pathsExtra header search paths.
Extra library search pathsExtra library search paths.
Preprocessor definitionsExtra preprocessor definitions. Use the form "NAME1=value NAME2=value", using whitespace, commas, or new-lines to separate the items - to include a space or comma in a definition, precede it with a backslash.
Link-Time OptimisationEnable this to perform link-time code optimisation. This is recommended for release builds.
NotesExtra comments: This field is not used for code or project generation, it's just a space where you can express your thoughts.
7.4.2 Xcode Configuration Settings

The following table shows specific settings for Xcode:

Xcode Configuration SettingsDescription
Enable Plugin Copy Step[Plugin Only] - Enable this to copy plugin binaries to the specified folder after building.
VST Binary Location[Plugin Only] - The folder in which the compiled VST binary should be placed.
VST3 Binary Location[Plugin Only] - The folder in which the compiled VST3 binary should be placed.
AU Binary Location[Plugin Only] - The folder in which the compiled AU binary should be placed.
RTAS Binary Location[Plugin Only] - The folder in which the compiled RTAS binary should be placed.
AAX Binary Location[Plugin Only] - The folder in which the compiled AAX binary should be placed.
OptimisationThe optimisation level for this configuration. Options include "-O0 (no optimisation)", "-Os (minimise code size)", "-O1 (fast)", "-O2 (faster)", "-O3 (fastest with safe optimisations)" and "-Ofast (uses aggressive optimisations)".
iOS Deployment Target[iOS Only] - The minimum version of iOS that the target binary will run on. Options include "Use Default", "7.0", "7.1", "8.0", "8.1", "8.2", "8.3", "8.4", "9.0", "9.1", "9.2", "9.3", "10.0", "10.1", "10.2", "10.3" and "11.0".
OSX Base SDK Version[macOS Only] - The version of OSX to link against in the Xcode build. Options include "Use Default", "10.5 SDK", "10.6 SDK", "10.7 SDK", "10.8 SDK", "10.9 SDK", "10.10 SDK", "10.11 SDK" and "10.12 SDK".
OSX Deployment Target[macOS Only] - The minimum version of OSX that the target binary will be compatible with. Options include "Use Default", "10.5", "10.6", "10.7", "10.8", "10.9", "10.10", "10.11" and "10.12".
OSX Architecture[macOS Only] - The type of OSX binary that will be produced. Options include "Use Default", "Native architecture of build machine", "Universal Binary (32-bit)", "Universal Binary (32/64-bit)" and "64-bit Intel".
Custom Xcode flagsA comma-separated list of custom Xcode setting flags which will be appended to the list of generated flags, e.g. MACOSX_DEPLOYMENT_TARGET_i386 = 10.5, VALID_ARCHS = "ppc i386 x86_64".
PList Preprocessor DefinitionsPreprocessor definitions used during PList preprocessing (see PList Preprocess).
C++ LibraryThe type of C++ std lib that will be linked. Options include "Use Default", "LLVM libc++" and "GNU libstdc++".
Code-signing IdentityThe name of a code-signing identity for Xcode to apply.
Relax IEEE complianceEnable this to use FAST_MATH non-IEEE mode. (Warning: this can have unexpected results!)
Strip local symbolsEnable this to strip any locally defined symbols resulting in a smaller binary size. Enabling this will also remove any function names from crash logs. Must be disabled for static library projects.
7.4.3 Visual Studio Configuration Settings

The following table shows specific settings for Visual Studio:

Visual Studio Configuration SettingsDescription
Enable Plugin Copy Step[Plugin Only] - Enable this to copy plugin binaries to a specified folder after building.
VST Binary Location[Plugin Only] - The folder in which the compiled VST binary should be placed.
VST3 Binary Location[Plugin Only] - The folder in which the compiled VST3 binary should be placed.
RTAS Binary Location[Plugin Only] - The folder in which the compiled RTAS binary should be placed.
AAX Binary Location[Plugin Only] - The folder in which the compiled AAX binary should be placed.
ArchitectureWhether to use a 32-bit or 64-bit architecture. Choice between "Win32" and "x64".
Debug Information Format[Debug Only] - The type of debugging information created for your program for this configuration. This will always be used in a debug configuration and will be used in a release configuration with forced generation of debug symbols. Options include "None", "C7 Compatible (/Z7)", "Program Database (/Zi)" and "Program Database for Edit And Continue (/ZI)".
Relax IEEE complianceEnable this to use FAST_MATH non-IEEE mode. (Warning: this can have unexpected results!)
OptimisationThe optimisation level for this configuration. Options include "No optimisation", "Minimise size" and "Maximise speed".
Intermediates pathAn optional path to a folder to use for the intermediate build files. Note that Visual Studio allows you to use macros in this path, e.g. "$(TEMP)\MyAppBuildFiles\$(Configuration)", which is a handy way to send them to the user's temp folder.
Warning LevelThe compilation warning level to use. Options include "Low", "Medium" and "High".
Treat Warnings as ErrorsEnable this to treat compilation warnings as errors.
Runtime LibraryIf the static runtime is selected then your app/plug-in will not be dependent upon users having Microsoft's redistributable C++ runtime installed. However, if you are linking libraries from different sources you must select the same type of runtime used by the libraries. Options include "Default", "Use static runtime" and "Use DLL runtime".
Incremental LinkingEnable to avoid linking from scratch for every new build. Disable to ensure that your final release build does not contain padding or thunks.
Force Generation of Debug Symbols[Except Debug] - Enable this to force generation of debug symbols in a release configuration.
Pre-build CommandSome command that will be run before a build starts.
Post-build CommandSome command that will be run after a build starts.
Generate ManifestEnable this to generate a Manifest file.
Character SetSpecifies the character set used when building. Options include "Default", "MultiByte" and "Unicode".
7.4.4 Linux Makefile Configuration Settings

The following table shows specific settings for Linux Makefile:

Linux Makefile Configuration SettingsDescription
OptimisationThe optimisation level for this configuration. Options include "-O0 (no optimisation)", "-Os (minimise code size)", "-O1 (fast)", "-O2 (faster)", "-O3 (fastest with safe optimisations)" and "-Ofast (uses aggressive optimisations)".
ArchitectureSpecifies the 32/64-bit architecture to use. Options include "Default", "<None>", "32-bit (-m32)", "64-bit (-m64)", "ARM v6" and "ARM v7".
7.4.5 Android Configuration Settings

The following table shows specific settings for Android:

Android Configuration SettingsDescription
OptimisationThe optimisation level for this configuration. Options include "-O0 (no optimisation)", "-Os (minimise code size)", "-O1 (fast)", "-O2 (faster)", "-O3 (fastest with safe optimisations)" and "-Ofast (uses aggressive optimisations)".
ArchitecturesA list of the ARM architectures to build (for a fat binary). Leave empty to build for all possible android archiftectures.
Remote Notifications Config FilePath to google-services.json file. This will be the file provided by Firebase when creating a new app in Firebase console. This will override the setting from the main Android exporter node.
Extra Android XML Value ResourcesPaths to additional "value resource" files in XML format that should be included in the app (one per line). If you have additional XML resources that should be treated as value resources, add them here.
Extra Android Drawable ResourcesPaths to additional "drawable resource" directories that should be included in the app (one per line). They will be added to "res" directory of Android project. Each path should point to a directory named "drawable" or "drawable-<size>" where <size> should be something like "hdpi", "ldpi", "xxxhdpi" etc, for instance "drawable-xhdpi". Refer to Android Studio documentation for available sizes.
Extra Android Raw ResourcesPaths to additional "raw resource" files that should be included in the app (one per line). Resource file names must contain only lowercase a-z, 0-9 or underscore.
Custom string resourcesCustom XML resources that will be added to string.xml as children of <resources> element. Example: <string name="value">text</string><string name2="value2">text2</string>.
7.4.6 Code::Blocks Configuration Settings

The following table shows specific settings for Code::Blocks:

Code::Blocks Configuration SettingsDescription
OptimisationThe optimisation level for this configuration. Options include "-O0 (no optimisation)", "-Os (minimise code size)", "-O1 (fast)", "-O2 (faster)", "-O3 (fastest with safe optimisations)" and "-Ofast (uses aggressive optimisations)".
ArchitectureSpecifies the 32/64-bit architecture to use. Options include "32-bit (-m32)", "64-bit (-m64)", "ARM v6" and "ARM v7".

CLion does not have configuration settings as it borrows configurations from other exporters.


8. Live Build Engine

The live build engine allows for compilation of source code within the Projucer.

8.1 Live Build Engine Side Panel

It can be access through the live build tab in the side panel and activated by clicking the Enable Now button or through the menu items under Build > Enable Compilation.

Live build engine window

8.2 Live Build Engine Controls

When compilation is enabled, the side panel will show compilation errors, Component objects and compilation activities in different sections of the panel as shown below:

Live build engine window (continued)

8.3 Live Build Engine Settings

To access the live build settings, click on the settings icon of the side panel as shown in the following screenshot:

Live build engine settings window

The following table shows the live build engine settings:

Live Build Engine SettingsDescription
User header pathsUser header search paths.
System header pathsSystem header search paths.
Preprocessor DefinitionsExtra preprocessor definitions. Use the form "NAME1=value NAME2=value", using whitespace or commas to separate the items. To include a space or comma in a definition, precede it with a backslash.
Extra compiler flagsExtra command-line flags to be passed to the compiler. This string can contain references to preprocessor definitions in the form ${NAME_OF_DEFINITION}, which will be replaced with their values.
Extra dynamic librariesExtra dynamic libs that the running code may require. Use new-lines or commas to separate the items.
Windows Target PlatformThe Windows target platform to use. Options include "(default)", "8.1", "10.0.10240.0", "10.0.10586.0", "10.0.14393.0" and "10.0.16299.0".

8.4 Live Build Engine Preview

The live build engine allows you to conveniently preview components within the Projucer. To preview a component, click on the arrow next to the corresponding component in the side panel and the following window will be launched.

Live build engine preview window

The window provides a toolbar at the bottom that presents useful features to help you debug your GUI:

Toolbar ElementDescription
ZoomAlters the zoom factor to scale the content to the screen.
Set SizeAllows selection of common device sizes from a dropdown list.
Flip OrientationChanges the orientation from portrait to landscape and vice versa.
ReinstantiateReinstantiates Components after modifications in the code.
View codeJumps to the corresponding section of the code relating to the Component.

9. GUI Editor

When a GUI component file is created within the Projucer, the editor will show different parameters in the editor window. These changes will be reflected immediately in the code by filling the appropriate functions in the GUI component class created.

9.1 GUI Editor Class Tab

The class tab provides general settings for the class:

GUI editor class tab

On the left side of the panel, general class settings can be found:

General Class SettingsDescription
Class nameThe name of the Component class to create.
Template fileThe template file to use for this Component class.
Component nameThe name of the actual Component to use in the setName() function.
Parent classesThe classes to inherit from along with their access modifiers.
Constructor paramsThe parameters of the class constructor.
Member initialisersThe members to initialise in the class constructor.
Initial widthThe initial width of the Component to use in the setSize() function.
Initial heightThe initial height of the Component to use in the setSize() function.
Fixed sizeWhether to resize the component to fit the workspace or keep the component size fixed.

On the right side of the panel, extra callback methods can be added to the Component by checking the box next to the function to override.

9.2 GUI Editor Subcomponents Tab

The subcomponent tab provides preview and settings for subcomponents created in the class:

GUI editor subcomponents tab

9.3 GUI Editor Graphics Tab

The graphics tab provides general graphics settings for the class:

GUI editor graphics tab

9.4 GUI Editor Resources Tab

The resources tab provides settings to manage resources used by the class:

GUI editor resources tab

9.5 GUI Editor Code Tab

The code tab displays the generated code for the class:

GUI editor code tab


10. Tools

The Projucer comes with its own set of handy tools.

10.1 UTF-8 String Literal Helper

The UTF-8 String Literal Helper allows you to instantly convert any text to UTF-8 encoding.

UTF-8 String Literal Helper

10.2 SVG Path Converter

The SVG Path Converter allows you to convert a single SVG path into a JUCE Path object in C++ that you can insert into your code right away.

SVG Path Converter

10.3 Translation File Builder

The Translation File Builder allows you to generate annotated text from all your TRANS() macros in your project in order to facilitate translation in different languages.

Translation File Builder

10.4 Command Line Tools

The Projucer can also be run in command line mode by invoking the executable from the terminal like so:

// macOS
Projucer.app/Contents/MacOS/Projucer --help

// Linux
Projucer --help

// Windows
Projucer.exe --help

The following table lists all the possible command line arguments and their corresponding descriptions:

Command Line ArgumentDescription
--helpDisplays the help manual.
--resave [project_file]Resaves all files and resources in a project.
--resave-resources [project_file]Resaves just the binary resources for a project.
--get-version [project_file]Returns the version number of a project.
--set-version [version_number] [project_file]Updates the version number in a project.
--bump-version [project_file]Updates the minor version number in a project by 1.
--git-tag-version [project_file]Invokes 'git tag' to attach the project's version number to the current git repository.
--status [project_file]Displays information about a project.
--buildmodule [target_folder] [module_folder]Zips a module into a downloadable file format.
--buildallmodules [target_folder] [module_folder]Zips all modules in a given folder and creates an index for them.
--trim-whitespace [target_folder]Scans the given folder for C/C++ source files (recursively), and trims any trailing whitespace from their lines, as well as normalising their line-endings to CR-LF.
--remove-tabs [target_folder]Scans the given folder for C/C++ source files (recursively), and replaces any tab characters with 4 spaces.
--tidy-divider-comments [target_folder]Scans the given folder for C/C++ source files (recursively), and normalises any juce-style comment division lines (i.e. any lines that look like //===== or //----- or /////// will be replaced).
--fix-broken-include-paths [target_folder]Scans the given folder for C/C++ source files (recursively). Where a file contains an #include of one of the other filenames, it changes it to use the optimum relative path. Helpful for auto-fixing includes when re-arranging files and folders in a project.
--obfuscated-string-code [string_to_obfuscate]Generates a C++ function which returns the given string, but in an obfuscated way.
--encode-binary [source_binary_file] [target_cpp_file]Converts a binary file to a C++ file containing its contents as a block of data. Provide a .h file as the target if you want a single output file, or a .cpp file if you want a pair of .h/.cpp files.
--trans [target_folders...]Scans each of the given folders (recursively) for any NEEDS_TRANS macros, and generates a translation file that can be used with Projucer's translation file builder
--trans-finish [pre_translated_file] [post_translated_file] [optional_existing_translation_file]Creates a completed translations mapping file, that can be used to initialise a LocalisedStrings object. This allows you to localise the strings in your project.
--set-global-search-path [os] [identifier_to_set] [new_path]Sets the global path for a specified os and identifier. The os should be either osx, windows or linux and the identifiers can be any of the following: defaultJuceModulePath, defaultUserModulePath, vst3path, aaxPath (not valid on linux), rtasPath (not valid on linux), androidSDKPath or androidNDKPath.
--create-project-from-pip [path/to/PIP] [path/to/output]Generates a JUCE project from a PIP file.

10.5 PIP (Projucer Instant Project)

A Projucer project can be generated from a single header file containing metadata called a Projucer Instant Project or PIP.

A PIP file can be opened by a simple drag-and-drop onto the Projucer interface or by navigating to File > Open... from the menu items.

The following block of code illustrates an example of the PIP metadata that should be placed at the top of a header file:

 BEGIN_JUCE_PIP_METADATA

 name:             HelloWorldDemo
 version:          1.0.0
 vendor:           juce
 website:          http://juce.com
 description:      Simple HelloWorld application.

 dependencies:     juce_core, juce_data_structures, juce_events, juce_graphics,
                   juce_gui_basics
 exporters:        xcode_mac, vs2017, linux_make, xcode_iphone

 type:             Component
 mainClass:        HelloWorldDemo

 useLocalCopy:     1

 END_JUCE_PIP_METADATA

The following table lists all the possible PIP metadata and their corresponding descriptions:

Metadata NameDescription
name[Required] - The JUCE project name.
versionUsed for the "Project Version" field in the Projucer.
vendorUsed for the "Company Name" field in the Projucer.
websiteUsed for the "Company Website" field in the Projucer.
descriptionA short description of the PIP.
dependencies[Required] - The JUCE modules that should be added to the project.
exporters[Required] - The exporters that should be added to the project.
moduleFlagsSets one or many of the JUCE module flags.
definesSets some global preprocessor definitions for the project. Used to populate the "Preprocessor Definitions" field in the Projucer.
type[Required] - The type of project. This can either be Console, Component or AudioProcessor.
mainClass[Required] - The name of the main class that should be instantiated. There can only be one main class and it must have a default constructor. Depending on the type, this may need to inherit from a specific JUCE class.
useLocalCopySet this to specify that the PIP file should be copied to the generated project directory instead of just referred to. This is used for the JUCE examples to prevent modification of original example code when creating a project from one of the example PIPs.

Depending on the project type, the behaviour of the PIP output differs as follows:

  • A Console application must contain a main function and the generated Main.cpp only includes the PIP file.
  • A Component PIP must have its main class (specified using the mainClass field) inherit from Component and must have a default constructor. The Main.cpp that is generated will instantiate this main class and put it in a simple desktop window.
  • An AudioProcessor PIP must have its main class inherit from AudioProcessor. The Main.cpp that is generated implements the createPluginFilter() method only and returns a new instance of this class.

11. Help

11.1 Help Menu

The Help menu provides quick and easy access to useful website links by launching the corresponding resource in your default browser.

CommandDescription
JUCE Community ForumShows the JUCE community forum in a browser
API ModulesShows the API modules documentation in a browser
API ClassesShows the API classes documentation in a browser
JUCE TutorialsShows the JUCE tutorials in a browser

11.2 About Screen

Find out about the Projucer version you are running by going to Projucer > About Projucer.

About screen window

11.3 Application Usage Analytics

Display the analytics notice by going to Projucer > Application Usage Analytics.

Application usage analytics notice


12. Shortcuts

12.1 Shortcuts Table

The following table shows all the shortcut commands to the menu bar items of the Projucer:

MenuCommandShortcut
ProjucerHide Projucer⌘H
ProjucerHide Others⌥⌘H
ProjucerQuit Projucer⌘Q
FileNew Project...⌘N
FileNew Project From Clipboard...⇧⌘N
FileOpen...⌘O
FileClose File⌃⌘W
FileSave File⌘S
FileSave As...⇧⌘S
FileSave All⌥⌘S
FileSave Project and Open in IDE...⇧⌘L
EditUndo⌘Z
EditRedo⇧⌘Z
EditCut⌘X
EditCopy⌘C
EditPaste⌘V
EditSelect All⌘A
EditDeselect All⌘D
EditFind⌘F
EditFind Selection⌘L
EditFind Next⌘G
EditFind Previous⇧⌘G
ViewShow Project Settings⌃⌘X
ViewShow Project Tab⌃⌘P
ViewShow Build Tab⌃⌘B
ViewShow File Explorer Panel⌃⌘F
ViewShow Modules Panel⌃⌘M
ViewShow Exporters Panel⌃⌘E
ViewShow Exporter Settings⇧⌘E
BuildEnable Compilation⇧⌘B
BuildBuild Now⌘B
BuildLaunch Application⌘R
BuildStop Application.
BuildClean All⇧⌘K
BuildRe-instantiate Components⇧⌘R
BuildHighlight next error⌘'
BuildHighlight previous error⌘"
WindowPrevious Window⌃⇧⇥
WindowNext Window⌃⇥
WindowClose Window⌘W
DocumentPrevious Document⌃⌘←
DocumentNext Document⌃⌘→
DocumentOpen Counterpart File⌃⌘↑
GUI EditorEdit sub-component layout⌘N
GUI EditorEdit background graphics⌘M
GUI EditorCut⌘X
GUI EditorCopy⌘C
GUI EditorPaste⌘V
GUI EditorSelect All⌘A
GUI EditorDeselect All⌘D
GUI EditorBring to front⌘F
GUI EditorSend to back⌘B
GUI EditorGroup selected items⌘K
GUI EditorUngroup selected items⇧⌘K
GUI EditorRetrieve offscreen items⌘M
GUI EditorShow snap-to-grid⇧⌘G
GUI EditorEnable snap-to-grid⌘G
GUI EditorZoom in⌘]
GUI EditorZoom out[
GUI EditorZoom to 100%⌘1
GUI EditorTest component...⌘T
GUI EditorComponent Overlay > No component overlay⌘2
GUI EditorComponent Overlay > Overlay with opacity of 33%⌘3
GUI EditorComponent Overlay > Overlay with opacity of 66%⌘4
GUI EditorComponent Overlay > Overlay with opacity of 100%⌘5

13. Notices

13.1 License

==============================================================================

This manual is part of the JUCE library. Copyright (c) 2017 - ROLI Ltd.

JUCE is an open source library subject to commercial or open-source licensing.

By using JUCE, you agree to the terms of both the JUCE 5 End-User License Agreement and JUCE 5 Privacy Policy (both updated and effective as of the 27th April 2017).

End User License Agreement: www.juce.com/juce-5-licence Privacy Policy: www.juce.com/juce-5-privacy-policy

Or: You may also use this code under the terms of the GPL v3 (see www.gnu.org/licenses).

JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE DISCLAIMED.

==============================================================================

13.2 End User License Agreement

13.3 Privacy Policy


14. Support

14.1 JUCE Website

14.2 JUCE Community Forum

14.3 JUCE API Documentation

14.4 JUCE Tutorials

Further Information

© 2018 JUCE