Tutorial: Projucer Part 1: Getting started with the Projucer

This tutorial shows you how to install JUCE and how to create a new cross-platform JUCE project using the Projucer.

You also learn how to export the project to an IDE such as Xcode or Visual Studio to develop, run and debug your JUCE application.

Level: Beginner

Platforms: Windows, macOS, Linux, iOS, Android

Getting started

Download JUCE. 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. Launch the Projucer, which is located there.

The new project wizard

The first time you launch 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.)

Select your project type

On the first page of the wizard, select which type of project you want to create:

Projucer wizard - select type of the project you want to create.

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.

Below is an overview over all currently supported project types.

Project type Description
GUI Application This 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 Application This creates an application which draws an animated graphical display. You can start here to create an animated mobile app, for example.
OpenGL Application This creates a blank JUCE application, like GUI Application, but adds support for OpenGL to draw features including 3D model import and GLSL shaders.
Console Application JUCE 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 Application This 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-In This 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. See Tutorial: Create a basic Audio/MIDI plugin, Part 1: Setting up for more information.
Static Library, Dynamic Library This project type is useful to create re-usable software libraries that build on top of JUCE. The Projucer supports creating libraries for both static and dynamic linking.

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 will be directed to this subfolder if you click on the Open Example Project button in the lower right corner.

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.

Create your new project

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 can set everything up:

Projucer wizard - create your project.
  1. Here, you choose a name for your app.
  2. This field shows the project type again (which you selected on the previous wizard page).
  3. 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.
  4. The JUCE framework code is organised into modules. So you need to tell your project where the JUCE modules are located. Here, you specify the location of the modules subfolder located inside the JUCE folder you installed earlier.
  5. Here, you choose the folder where the Projucer should create your project. (Note: this is completely independent from the location where the JUCE modules folder is.)
  6. Here, you 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.
  7. When you have reviewed all your settings, click the Create button to actually generate the Projucer project at the location you specified.

The Projucer currently has exporters for the following IDEs, build systems, and platforms:

Target OS Supported build systems
Windows Visual Studio, Code::Blocks
Linux Makefile, Code::Blocks
iOS Xcode
Android Android Studio

Export the project and open in your native IDE

After you have created your project, you can launch the native IDE with your project directly from the Projucer. Use the button near the top:

The project settings page (right) and the buttons for opening the project in your native IDE (bottom left, highlighted).

Now that you have opened your IDE (Xcode, Visual Studio, and so on), you can compile and run your JUCE app, and get started with coding!

You need to install the appropriate native IDE/build system on your computer before you can use it. 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.

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. You can read about this and more features for managing your Projucer project in Tutorial: Projucer Part 2: Manage your Projucer projects.

Open an existing project

To open up an existing Projucer project, you can either double-click on the .jucer file contained in the project folder or click on Open Existing Project from the wizard. (You can also navigate to Open... from the Projucer's main menu.)

Opening PIP files

You may come across Projucer Instant Project (PIP) files when following other JUCE tutorials. These are essentially header files with the usual .h extension that provide metadata to the Projucer in order to automatically create a project with the correct modules and exporters from a single file.

PIP files can be opened similarly by either selecting the file from the Open... dialog of the Projucer's main menu or a simple drag-and-drop onto the Projucer interface window.


After reading this tutorial, you should be able to:

  • Install JUCE.
  • Create a new project using the Projucer.
  • Export this project to your native IDE such as Xcode on OSX, or Visual Studio on Windows.
  • Compile, run, and debug your app in the native IDE for the platform(s) you want to target.
  • Open existing projects and PIP files in the Projucer.

See also