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.

Building your application with JUCE

Compiling with Microsoft Visual Studio 2005

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 Visual Studio. (If you're using VCExpress Edition see below for the few extra steps needed).

The only 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 and usually picks "Debug DLL" as its default, 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 C++ Express edition

Although VCExpress is basically the same thing as Visual Studio 2005, it doesn't come with all the Win32 library code pre-installed, so a couple of extra steps are required before JUCE can be compiled with it:

Install the latest Platform SDK from Microsoft.
A few extra items need to be added to your include and library search paths. The first few entries 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:
```
$(VSInstallDir)VC\lib
C:\Program Files\Microsoft Platform SDK\lib
C:\mycode\juce\bin
...
```

Then, you can follow the same instructions as for Visual Studio 2005 above.

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
CoreFoundation.framework
CoreServices.framework
ApplicationServices.framework
Carbon.framework
IOKit.framework
QuickTime.framework
CoreAudio.framework
CoreMIDI.framework
AudioUnit.framework
OpenGL.framework
AGL.framework
WebKit.framework
DiscRecording.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 use the amalgamated form of Juce (see earlier note). 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 compiling the library, 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.

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

***