Tutorial: Manage your Projucer project

In Tutorial: Getting started with the Projucer, you learned how to create a new JUCE project, export it to your native IDE, and start coding.

However, the Projucer is not just about that -it is also a very powerful cross-platform 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. This tutorial gives you an overview over some essential features.

Level: Beginner

Platforms: Windows, Mac OS X, Linux, iOS, Android

Getting started

Create a new JUCE project and open it in the Projucer. This is described in Tutorial: Getting started with the Projucer.

Structure of Projucer projects

Let's have a closer look at the anatomy of an Projucer project. Below is the folder structure of a JUCE project that the Projucer generates for you:

Anatomy of an Projucer project.

At the top level is the .jucer file (highlighted above), which contains all project settings. Double-click this file to open the project in the Projucer. In addition to the .jucer file, three subfolders are generated:

Folder Content
Source The C++ source code of your JUCE app.
Builds The export targets generated by the Projucer. The Xcode project file and Visual Studio solution are highlighted as an example in the screenshot above. Open these files to start coding, debugging, and running your JUCE app. (You can also just use the Open in ... buttons in the Projucer, of course.)
JuceLibraryCode Here are some auto-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 global JUCE folder that you installed earlier.

Managing your project

Now we will have a look at the most essential features of the Projucer that you will frequently use as you develop your JUCE app.

Adding and editing source files

The projucer offers a file browser and a basic code editor for C++ source files. It is located under the File exporter tab on the left hand side. This is what it looks like:

The Projucer file navigator (left) and source file editor (right).

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. To do this (and access other functionality as well), click on the "+" symbol in the file browser tab on the left, or right-click on the file or group, and select what you want to do from the pop-up menu.

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.

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.

The Projucer's code editor appears when you select a file in the file browser. To do some quick changes to your code, you don't need to fire up a native IDE, instead just make the changes in the Projucer and save your changes.

Managing JUCE modules

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

The JUCE modules used by this project (left, highlighted) and module settings page (right).

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.

If you click on the settings icon in the Modules tab, the module settings page opens. It provides an overview over all currently used modules and allows you to set the paths to them. To change the paths of all modules at once, enter the correct path into one of the modules, select it, and click on Set paths for all modules...

Alternatively, you can choose to use global search paths for modules by clicking on Enable/disable global path for modules... To set your global search paths, navigate to menu item Projucer > Global Search Paths on MacOS or File > Global Search Paths on Windows and Linux.

If you click on an individual module in the browser, you get access to module-specific settings and properties. There, 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.

Export targets, configurations, and build settings

The different exporter targets that you created earlier (Xcode, Visual Studio, and so on) can be found in the Exporters tab. If you click on these in the browser, you get access to the build settings for this export target. This is the place to specify additional compiler and linker flags and other platform-specific build settings.

To create a new export target for an additional IDE and platform, click on the "+" symbol. You can do this at any time. For example, if you originally created a JUCE application for Windows and OSX, 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.

The Projucer creates build configurations to each export target which your native IDE will use to actually compile and run your app. By default, the two configurations Debug and Release are added to every export target. By clicking on these configurations, you can access the platform-specific build settings for this particular configuration:

The different IDE configurations (left, highlighted) and configuration-specific build settings (right).

You can add additional configurations as well. For example, for Visual Studio export targets the Projucer adds Debug and Release configurations using 32-bit. However, you may also want to add 64-bit support to your Windows app. For this, you can copy the two existing configurations (right-click on the configuration and select Create a copy of this configuration), rename the copies to Debug64 and Release64, respectively, and then change the configuration build setting Architecture from 32-bit to 64-bit for both configurations.


After reading this tutorial, you should be able to:

  • Use the Projucer to edit source files and manage JUCE modules,
  • Configure the build settings of your app,
  • Create new export targets and build configurations.

See also