Introduction - License - Installation - Building with VC2005 - Building with VC Express - Building with VC6 - Building with VC7 - Building with XCode - Building with Code::Blocks - Building on Linux -

JUCE

Introduction

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

A complete doxygen-created API guide is available here as HTML, or can be downloaded as a precompiled Windows help file from the downloads page.

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

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

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

To compile the library, there is a subfolder juce/build that contains projects for different operating systems and compilers.

Building the demo application

Inside the juce folder is a demo application that shows off a few of Juce's features. The juce/extras/juce demo/build folder contains projects and workspaces for the various platforms and compilers.

The "amalgamated" version of Juce

A recent new feature is that Juce can be used as a monolithic C++ file, instead of a statically linked library. This means that you can write a juce application without actually needing to build the library beforehand, but instead by just adding juce_amalgamated.cpp to the project, and including juce_amalagamated.h instead of juce.h. The demo apps are designed using this approach, because it means there's less setting-up required for a new user to do before getting stuck-in, but some compilers and debuggers can struggle with the huge files involved, so you may prefer to build your project in the traditional way, using it as a separate library.

A variation on this approach is to include juce_amalgamated_template.cpp in your app, which has the same effect as the normal amalgamated file, but which actually pulls in all the juce cpp files via #include statements rather than by pre-munging them into one file. This makes debugging a lot easier

Building your application with JUCE

Compiling with Microsoft Visual Studio

The quickest way to get started is to try building the demo application - there's a Visual Studio soluion in juce/extras/juce demo/build/win32_vc8/jucedemo.sln.

This should build and run with no extra set-up needed in all versions of Visual Studio from 2005 onwards, including the free version of Visual Express 2009.

One thing to check if you're unfamiliar with Visual Studio is that the jucedemo project needs to be selected as your "startup" project (right-click on the jucedemo project in the solution explorer for this option). Also, the active configuration should be set to "Debug" or "Release", (the first time you load a project, VS selects one of the configurations by default and usually picks "Debug DLL", for reasons best known to itself).

To create your own application that links to Juce:

Either make a copy of the example project in juce/projects and rename/customise it, or create a new application project as an 'empty' WIN32 application - avoid saying yes to MFC or any of the other rubbish that Visual Studio might offer to pollute your application with.
Include the header file juce.h in all your source files (it's best to put this in a precompiled header).
Ensure that the linker's search path for libraries includes the the juce/bin directory. This path can be set globally, or can be added to your project's linker settings.
Choose to link to the "Multithreaded" or "Debug Multithreaded" run-time libraries, depending on whether you're doing a debug or release build. On VC6, this is set in the Project Settings / C/C++ / Code Generation options panel. In Visual Studio, it's in the project properties.
Make sure that your project has exception handling and run-time type information (RTTI) turned ON.
Have a look at the 'hello world' projects, demo projects, or the API documentation about the JUCEApplication class to find out how to create the application launch code.

Alternatively, you can use the amalgamated form of Juce (see note above). To do this, all need to do is to add juce_amalagamated.cpp to your project, and include juce_amalagamated.h instead of juce.h. This pulls the entire library into your project without needing to link to it separately, so you can skip the steps above that involve setting up the link paths, etc. Most of the demo apps are written using the amalgamated version, so refer to these for an example of how to do this.

Compiling with Microsoft Visual Studio 6

To compile the JUCE .lib files from the source code:

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
...

Open the juce.dsp project file in juce/build/win32/vc6
There are several configurations: debug, release, debug-unicode, and release-unicode. You can build all or some of these, and the resultant .lib files should end up in the "juce/bin" folder.

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.

For info on how to create an application that uses Juce, see the VC2005 notes above.

Compiling with Microsoft Visual Studio 7

For VC7, you can import the VC6 projects and this should work ok. It's also possible to tweak the version number in the VC8 projects so that they can be opened in VC7, but that's a less reliable method!

Compiling with XCode on MacOSX

To compile the JUCE binaries from the source code:

Open the Juce.xcodeproj file in juce/build/macosx
This project has "debug" and "release" configurations, and the library files it creates are libjuce.a (release) and libjucedebug.a (debug), which will appear in the juce/bin directory.

Then, to create and build an application:

Either make a copy of the example project in juce/extras/example projects and rename/customise it, or create a new "Carbon Application" project.
Include the header file juce.h in all your source files.
Get rid of any main() functions that XCode might have generated for you, and instead use the JUCEApplication class as your application launcher - see the API documentation for this class for more details, or have a look at the example projects, or demos.
Drag-and-drop the juce.xcodeproj file into the project's "External Frameworks and Libraries" list.
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".
You'll also 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 all this seems too complicated, you can make things slightly easier by using the amalgamated form of Juce (see earlier note). To do this, all you need to do is to add juce_amalagamated.cpp to your project, and include juce_amalagamated.h instead of juce.h. This pulls the entire library into your project without needing to link to it separately, so you can skip the steps above that involve compiling the library, setting up the link paths, etc. Most of the demo apps are written using the amalgamated version, so have a look through their source code for examples of how to do this.

Creating a JUCE application with Code::Blocks and MinGW

open the Juce project: juce/build/win32/codeblocks/juce.cbp
open the demo app project: juce/extras/juce demo/build/win32_codeblocks/JuceDemo.cbp
Build first the "Juce Library" project, and then the "Juce Demo App" project. If your build environment is set up correctly, these should just work and the demo app should run.

To create your own application:

Create a new project, as a "win32 GUI".
Either copy the example main.cpp from the Juce example project, or write your own based around the JUCEApplication class

In your project's build settings, you'll need to make sure the linker uses the following libraries:

libjuce.a or libjucedebug.a (these should be created in the juce/bin/codeblocks directory)
libshell32.a
libole32.a
libvfw32.a
libwinmm.a
libwininet.a
libdsound.a
libwsock32.a
libopengl32.a
libglu32.a
libuuid.a
librpcrt4.a (these are all in the MinGW libraries folder)

Creating a JUCE application on Linux with GCC

Most linux distros should come with the tools you need, although you might want to get hold of premake, which is used to automatically generate the juce makefile. (This isn't necessary if you're just going to use the makefile that's provided).
Get a command prompt and go into /juce/build/linux
To build the debug version, use "make CONFIG=Debug", or use "make CONFIG=Release" to build the release version. You can also use "make clean" to delete the intermediate files.

Then, to create and build an application:

Building the library will have produced the library files /juce/bin/libjuce.a and /juce/bin/libjuce_debug.a. You'll need to link to one of these in your app, and you'll also need to link to these libraries:
```
freetype
pthread
X11
```
If you've set the JUCE_USE_XINERAMA flag in juce_Config.h, you'll also need to link to the xinerama library. And you'll need the GL and GLU libraries if you've enabled JUCE_OPENGL

***