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

One of Juce's features is that it can be linked into your project 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

## Creating a new application with JUCE

### Using the new Jucer

NOTE! By far the easiest way to create a new cross-platform Juce app (or audio plugin) is to use the new and not-yet-finished Jucer to generate all the project files for you... This replacement for the old Jucer is still work-in-progress and at the "experimental" stage, but it has enough project management features to already be extemely useful. To use it, you'll need to build and run it - that's pretty easy to do: just open an appropriate project from the `juce/extras/Jucer (experimental)/Builds` folder, and compile/run it. The new Jucer has a wizard that will create a new Juce project for you, sorting out all the messy paths and project set-up, and will spit out a collection of project files for the various IDEs that you can simply open and build.

When complete, the new Jucer will be a big part of future Juce versions, and is already used to auto-generate the makefiles and project files for all the projects in the juce/extras folder.

However, if you want to create a Juce project manually (i.e. the hard way), here are some instructions:

### 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:

1. 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.
2. Include the header file `juce.h` in all your source files (it's best to put this in a precompiled header).
3. 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.
4. 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.
5. Make sure that your project has exception handling and run-time type information (RTTI) turned ON.
6. 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:

1. Install the latest Platform SDK from Microsoft.
2. 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
       ...

3. Open the juce.dsp project file in `juce/build/win32/vc6`
4. 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:

1. Open the `Juce.xcodeproj` file in `juce/build/macosx`
2. 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:

1. Either make a copy of the example project in `juce/extras/example projects` and rename/customise it, or create a new "Carbon Application" project.
2. Include the header file `juce.h` in all your source files.
3. 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.
4. Drag-and-drop the `juce.xcodeproj` file into the project's "External Frameworks and Libraries" list.
5. 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".
6. 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

1. open the Juce project: `juce/build/win32/codeblocks/juce.cbp`
2. open the demo app project: `juce/extras/juce demo/build/win32_codeblocks/JuceDemo.cbp`
3. 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:

1. Create a new project, as a "win32 GUI".
2. Either copy the example main.cpp from the Juce example project, or write your own based around the `JUCEApplication` class
3. 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

1. 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).
2. Get a command prompt and go into `/juce/build/linux`
3. 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:

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

***

- Copyright 2005 Raw Material Software Ltd -