Introduction - License - Installation - Building with Visual Studio - Building with VC6 - Building with XCode - Building on Linux - Building with Android -

JUCE

Introduction

JUCE is an all-encompassing C++ class library for developing cross-platform applications and plugins.

For lots more help and information, please visit the JUCE website.

A complete set of class documentation is available here.

License

JUCE is released under the Gnu Public License, which means it can be freely copied and distributed, and costs nothing to use in open-source applications.

If you'd like to release a closed-source application that uses JUCE, commercial licenses are available for a fee - click here for more information on pricing and terms.

Installation

Installing the source code

There are a few ways to install a copy of JUCE:

You can download a zip file containing the last stable release from the JUCE downloads section on SourceForge
Download the GIT repository: To grab the latest bleeding-edge version of the code, you can use the command:
git clone --depth 1 git://juce.git.sourceforge.net/gitroot/juce/juce
Download via the Introjucer: The Introjucer is JUCE's tool for creating and managing JUCE projects, and it also includes a handy tool which lets you download the latest (bleeding-edge) version of JUCE without needing to install GIT. To use this, just download a binary of the Introjucer from SourceForge, and run it - its 'update' menu contains an option to download JUCE.

The JUCE source code all lives in a folder called, unsurprisingly, juce, which you can unzip and put somewhere on your system.

Building the demo applications

In the juce/extras folder, there are a few demo apps to get you started and to show off JUCE's features. Each one contains a folder called Builds, containing various projects for different compilers and platforms. These should all work straight out-of-the-box if you load them into the appropriate development environment. Some of them (e.g. the audio plugin demo) may require 3rd party libraries or headers to have been installed, but I've made sure that any include statements that may not be present have comments with a detailed explanation of what's going on, so if you hit a compile error, just have a look at the code it's pointing to and everything should become clear.

Creating a new application with the Introjucer

By far the easiest way to create a new cross-platform JUCE app (or audio plugin) is to let the Introjucer do the hard work of creating all your projects with the correct settings.

You can either build the Introjucer yourself from the source (in juce/extras/Introjucer), or download a pre-built binary from SourceForge.

If you run it and select the 'new project' menu item, it'll walk you through the stages in setting up an app or plugin project, and will automatically spit out a collection of project files for all the different platforms and compilers that you need.

Requirements for building on different platforms

Microsoft Visual Studio 2005 or later

JUCE projects should build and run with no extra set-up needed in all versions of Visual Studio from 2005 onwards.

By far the easiest way to create a new project is by letting the Introjucer do all the hard work, as explained above. But if you really insist on creating one manually, here are a few tips:

Create your new application project as an 'empty' WIN32 application - avoid saying yes to MFC or any of the other rubbish that Visual Studio might offer you.
Make sure that your project has exception handling and run-time type information (RTTI) turned ON.
Have a look at the example projects, demo projects, or the API documentation about the JUCEApplication class to find out how to create the application launch code.

Microsoft Visual Studio 6

JUCE can still be compiled with VC6, although support for this will be dropped at some point in the future... but here are some tips for getting it going:

Install the latest Platform SDK from Microsoft.

Set up your include and library search paths. The first few items on your include path should look like this (obviously you might have things installed in different places, but the order is important!):

C:\Program Files\Microsoft Platform SDK\include
C:\Program Files\Microsoft Platform SDK\include\crt
C:\Program Files\Microsoft Platform SDK\include\mfc
C:\mycode\juce
...

And the library search path should begin like this:

C:\Program Files\Microsoft Visual Studio\VC98\LIB
C:\Program Files\Microsoft Platform SDK\lib
C:\mycode\juce\bin
...

Note that there's a rather lame bug in VC6 that causes an internal compiler error if you include filenames that are too long. This can get triggered if you put the juce folder in a deeply-nested directory (such as your user home directory). Unfortunately I think the only workaround for this is to move the source tree to a shallower directory.

XCode on OSX

Use XCode 3 or later. You might want to tick the option to install the 10.4 SDK if you want to build binaries that are backward-compatible with 10.4 and PPCs. If you're going to build for iOS, you'll obviously need the iOS version of XCode.

The easiest way to create a new application is by using the Intojucer, but here are a few tips if you're mad enough to want to set one up manually:

You'll need to add some or all of the following OSX frameworks to your "External Frameworks and Libraries" list, depending on what features your application uses:
```
Cocoa.framework
Carbon.framework
IOKit.framework
CoreAudio.framework
CoreMIDI.framework
WebKit.framework
DiscRecording.framework
QTKit.framework
QuickTime.framework
QuartzCore.framework
AudioUnit.framework
AudioToolbox.framework
OpenGL.framework
AppKit.framework
CoreAudioKit.framework
CoreFoundation.framework
```
In future there may be other frameworks that you'll need to link with to support new JUCE features. (It should be pretty obvious from the link-time error when one of these is missing).
If you need to link to the JUCE static library rather than using the amalgamated files, you'll need to drag-and-drop the juce.xcodeproj file into your project's "External Frameworks and Libraries" list. Then, expand this item in the treeview, and inside there'll be an item "libjuce.a" or "libjucedebug.a" - drag-and-drop this into the "link binary with libraries" phase inside the xcode target. When you select either a debug or release juce build these entries will (usually) update themselves to show the correct debug or release library name. If you want your project to automatically rebuild JUCE when you make changes to a JUCE file, you can also add JUCE to your target's "Direct Dependency" list (show information for the target, and this is on the "general" tab).
Alternative ways of linking to JUCE would be to add the libjuce.a or libjucedebug.a library to your "External Frameworks and Libraries" list, or to add switch to the linker's command-line of either "-ljuce" or "-ljucedebug".

Linux with GCC

Most linux distros should come with the tools you need. You may need to install the development packages of freetype, X11 and pthreads if they're not already available.

If you've enabled the JUCE_USE_XINERAMA option, then you'll also need to install the Xinerama package. And you'll need the GL and GLU libraries if you've enabled JUCE_OPENGL

The makefiles that are generated by the Introjucer can be run by "make CONFIG=Debug", or "make CONFIG=Release". You can also use "make clean" to delete the intermediate files.

Android

First of all, get yourself over to www.android.com, and install the latest Android SDK and NDK. Follow their instructions for installing Eclipse, and get to the point where you can build and run some of the Android NDK demo apps in Eclipse before even thinking about trying to do anything with JUCE. The Android development environment is a hugely complicated mish-mash of random bits of software, lashed together with scripts, so don't expect a slick installation experience - be prepared to mess about. Once it's installed though, it all more-or-less seems to work..
The only sensible way to create an Android JUCE project is with the Introjucer - doing it with Eclipse is a nightmare and if you want to do it manaually, good luck. The Introjucer will produce a folder containing a whole heap of files, and you can open the folder in Eclipse as a new project (use the "create project" option in Eclipse).
Eclipse should be able to automatically build the project and run it, but you can also build it from the command-line, by setting your CWD to the Android build folder and using "ant debug" or "ant release"
Be careful that your project folder doesn't contain any spaces in its path - the Android tools can't handle this (!)
The structure that a JUCE app uses is to have a couple of boilerplate java classes which load and run a big native library containing the juce library and all your app code. JUCE uses JNI internally to call java classes to interact with the OS.
When you change some of your app code and need to recompile and re-test the app, Eclipse will usually (but certainly not always) detect the change and re-compile the library. Unfortunately, if there are any errors during compilation, it'll ignore them, and carry on trying to run the app, after having cleared the console so you can no longer see the errors that occurred. In these cases, you probably want to build it using the command-line 'ant debug' so you can actually see what happened.
Although Eclipse does manage to rebuild the native library when you change some c++ code, it will fail utterly to re-package the new library file or to re-install it on the target device. So far, my way of getting it to do this has been to touch one of the java files whenever I change any c++, and this seems to kick it into life. If anyone has ever had the patience to become an Eclipse expert and can suggest a proper solution to this, please let me know!!
Often, Eclipse gets confused and insist that there are "mistakes" in the java which prevent it from running the app. Needless to say, there aren't really any mistakes, and usually doing a "clean" sorts it out.

***