This is an old revision of the document!
The JUCE Projucer is a code and IDE-project generator. You specify what kind of project you want (e.g. GUI application, Audio Plug-In, etc.), and the target IDEs you intend to work with (e.g. Visual Studio, XCode), plus some other details such as a project name, and the Projucer will generate a complete project/solution for each IDE, including a few “starter” code files. You can then open each project/solution in the appropriate IDE, click on “Build” and within a few minutes have a working app or plugin for your target platform.
Well, that's the theory. In practice, there are lots of little details to understand, which can be overwhelming when you're just getting started. On this page I'll take you step-by-step through building a synthesizer plugin for Windows (VST v2.4) and Macintosh (AU v2).
The first thing you'll see, when you run the Projucer for the very first time (after you clear the hurdles), is the “Create New Project” page, shown below. On subsequent runs, you'll most commonly see the last .jucer
project you had open, which the Projucer remembers. To create a new project, go to the Projucer's File menu and close whatever project is open, then choose “New Project…”
The Create New Project page has eight large graphic buttons for the eight most common project types. Click the button labeled “Audio Plug-In”, which I have outlined in red in the screen shot above. This will take you to the “second half” of the Create New Project page, as shown below. (Note the two pink circles at the bottom of the screen shot; these indicate that the page has two parts, and you can go back and forth between them by clicking on the circles. The filled circle indicates the currently-shown part.)
The first time you try the Projucer, when you haven't a clue what any of this means, it can be a little daunting, but it's actually straightforward.
The left half of this page is where you tell the Projucer where to put your new IDE project(s) and what to call it (them).
The right half of this page is where you select what kind(s) of IDE project(s) you require. Well, mostly. There's also that mysterious “Modules Folder” combo box near the top, and the “Use global module path” checkbox below it. These are related to what I said earlier about where you decided to put your main JUCE folder. I recommend that you DO check the “Use global module path” checkbox, and, if you chose to put the JUCE folder somewhere other than C:\
on Windows or your home directory on Mac/Linux, do the following right now:
JUCE\modules
folder, wherever you decided to put itNow that you have defined your “global paths”, the “Use global module path” checkbox should make sense, and you should understand why I suggested that you check it. So, back to the Projucer's Create New Project page:
The Projucer will create a new folder for your new project, containing three subfolders and a .jucer
file:
The .jucer
file is the Projucer project file, containing all the details you specified above. If you double-click this icon you'll re-open the project.
The Source
folder contains the source code files that are unique to this project. For an Audio Plugin project, there will initially be four files as follows:
PluginProcessor.h
and PluginProcessor.cpp
define a new subclass of the JUCE AudioProcessor class, which represents your plugin itself.PluginEditor.h
and PluginEditor.cpp
define a new subclass of AudioProcessorEditor, which represents your plugin's GUI.I'm not going to go into any detail about the content of these files. You can learn plenty by working through some of the JUCE tutorials. My goal here is to tell you what the tutorials don't mention, which you otherwise have to find out by trial and error.
The JuceLibraryCode
folder's purpose is explained very nicely in a little ReadMe.txt
file in it:
Important Note!!
================
The purpose of this folder is to contain files that are auto-generated by the Projucer,
and ALL files in this folder will be mercilessly DELETED and completely re-written whenever
the Projucer saves your project.
Therefore, it's a bad idea to make any manual changes to the files in here, or to
put any of your own files in here if you don't want to lose them. (Of course you may choose
to add the folder's contents to your version-control system so that you can re-merge your own
modifications after the Projucer has saved its changes).
So, these files are not the entirety of the “Juce Library Code”; the rest is in the JUCE Modules folder we went to such trouble about. These files are simply the few that have to be customized for your specific project.
The Builds
folder is the most interesting one at this point. Here is what my VanillaJuce\Builds
folder contained, after I selected Xcode (MacOSX), Xcode (iOS), and Visual Studio 2017 as my Target Platforms in the Projucer:
The Projucer created two separate folders for the two XCode targets (Mac and iOS), and one for Visual Studio. These folders can simply be copied as-is over to a Mac, and the XCode project files they contain opened and compiled—provided you set your Mac global search paths correctly, and installed put the JUCE modules folder and (optionally) VST3 SDK folder in the corresponding locations (see here for details. If not, you can always open the Projucer project again, modify the settings, and re-save to re-generate all IDE project files.
The contents of the VisualStudio2017
folder look like this:
There is a single .rc
file (binary resources), one .sln
(solution) file, and three pairs of .vcproj
/.vcproj.filters
files for three individual Visual Studio projects:
VanillaJuce_VST
)VanillaJuce_StandalonePlugin
).lib
file from all the code which is common to both plugin and standalone versions
Of these, the “shared code” file is by far the largest. It contains references to all of the code files in the Source
and JuceLibraryCode
folders, as well as a ton of files in the “JUCE modules” folder (which is why the Projucer needed to know where to find it). The others two projects just contain a couple of wrapper code files.
The Projucer's initial output is based on default settings for Audio Plugin projects. Once you have hit the “Create…” button, the Projucer window will change to something like this:
If you decided to close the Projucer, you can simply run it again to get to the same point. The Projucer will normally re-open to whatever project you had open the last time you closed it. If you happened to close the project, then close and re-open the Projucer, You'll see an almost empty window, and you can then get to the same point by going to the File menu to re-open your project's .jucer
file.
You have several options when you have (re-)opened an already-created Projucer project like this:
.jucer
file and re-generate all the IDE project files.Builds
and JuceLibraryCode
folders) will be overwritten. I'll tell you how to handle that in a moment.The large scrolling list of project settings has lots of items that you can ignore until you're ready to fill them in, e.g. Company Name and Website, but there are a few that you will need to set for a synthesizer plugin: