DISTRHO
/
JUCE
mirror of https://github.com/DISTRHO/JUCE


			
				
					
						
						
							
							<?xml version="1.0" encoding="windows-1250"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Language" content="en-us" />
<meta name="description" content="Raw Material Software" />
<meta name="keywords" content="audio, music, juce, tracktion, c++, sequencer, library, programming, software, julian storer$otherkeywords" />
<meta name="robots" content="index,follow" />
<title>JUCE - installation and compiling</title>
<link href="rawmat.css" rel="stylesheet" type="text/css" media="all" />
</head>

<body>
<div class="pageholder">

<div class="banner">
<a href="http://www.rawmaterialsoftware.com">
<img src="images/rms_logo.gif" alt="raw material software" title="raw material software"/></a>
</div>

<p><a href="#intro">Introduction</a> - <a href="#license">License</a> - 
<a href="#install">Installation</a> -
<a href="#buildvc">Building with Visual Studio</a> - 
<a href="#buildvc6">Building with VC6</a> -
<a href="#buildxcode">Building with XCode</a> -
<a href="#buildlinux">Building on Linux</a> -
<a href="#buildandroid">Building with Android</a> -
</p>

<h1>JUCE</h1>

<h2><a name="intro"></a>Introduction</h2>

<p>JUCE is an all-encompassing C++ class library for developing cross-platform applications and plugins.</p>
<p>For lots more help and information, please visit the <a href="http://www.rawmaterialsoftware.com/juce">JUCE website</a>.</p>
<p>A complete set of class documentation is available <a href="http://www.rawmaterialsoftware.com/juce/api/index.html" target="juce api">here</a>.</p>

<h2><a name="license"></a>License</h2>

<p>JUCE is released under the <a href="http://www.gnu.org/copyleft/gpl.html">Gnu Public License</a>, 
which means it can be freely copied and distributed, and costs nothing to use in open-source applications.</p>
<p>If you'd like to release a closed-source application that uses JUCE, commercial licenses are available 
for a fee - click <a href="http://www.rawmaterialsoftware.com/jucelicense.php">here</a> for more information 
on pricing and terms.</p>

<h2><a name="install"></a>Installation</h2>

<h3>Installing the source code</h3>

<p>There are a few ways to install a copy of JUCE:</p>
<ul>
<li>You can download a zip file containing the last stable release from <a href="http://sourceforge.net/projects/juce/files/juce/">the JUCE downloads section on SourceForge</a></li>
<li>Download the GIT repository: To grab the latest bleeding-edge version of the code, you can use the command:
    <br><code>git clone --depth 1 git://juce.git.sourceforge.net/gitroot/juce/juce</code></li>
<li>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 <a href="http://sourceforge.net/projects/juce/files/juce/">SourceForge</a>,
and run it - its 'update' menu contains an option to download JUCE.</li>
</ul>
<p>The JUCE source code all lives in a folder called, unsurprisingly, <code>juce</code>, which you can unzip 
and put somewhere on your system.</p>

<h3>Building the demo applications</h3>

<p>In the <code>juce/extras</code> folder, there are a few demo apps to get you started and to show off JUCE's features. 
Each one contains a folder called <code>Builds</code>, 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.</p>

<h2>Creating a new application with the Introjucer</h2>

<p>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.</p>
<p>You can either build the Introjucer yourself from the source (in <code>juce/extras/Introjucer</code>), or download 
a pre-built binary from <a href="http://sourceforge.net/projects/juce/files/juce/">SourceForge</a>.
<p>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.</p>

<h1>Requirements for building on different platforms</h1>

<h3><a name="buildvc"></a>Microsoft Visual Studio 2005 or later</h3>

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

<p>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:</p>
<ol>
<li>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.</li>
<li>Make sure that your project has exception handling and run-time type information (RTTI) turned ON.</li>
<li>Have a look at the example projects, demo projects, or the API documentation about the 
<code>JUCEApplication</code> class to find out how to create the application launch code.</li>
</ol>

<h3><a name="buildvc6"></a>Microsoft Visual Studio 6</h3>

<p>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:</p>

<ol>
<li>Install the latest Platform SDK from Microsoft.</li>
<li>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!):
<pre>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
...</pre>
And the library search path should begin like this:
<pre>C:\Program Files\Microsoft Visual Studio\VC98\LIB
C:\Program Files\Microsoft Platform SDK\lib
C:\mycode\juce\bin
...</pre>
</li>
</ol>

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

<h3><a name="buildxcode"></a>XCode on OSX</h3>

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

<p>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:</p>

<ul>
<li>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:
<pre>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</pre>

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).
</li>
<li>If you need to link to the JUCE static library rather than using the amalgamated files, you'll need to drag-and-drop 
the <code>juce.xcodeproj</code> 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).<br/>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".</li>
</ul>

<h3><a name="buildlinux"></a>Linux with GCC</h3>

<p>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.</p>
<p>If you've enabled the <code>JUCE_USE_XINERAMA</code> option, then you'll also need to install the Xinerama package.
And you'll need the <code>GL</code> and <code>GLU</code> libraries if you've enabled <code>JUCE_OPENGL</code></p>
<p>The makefiles that are generated by the Introjucer can be run by "<code>make CONFIG=Debug</code>", 
or "<code>make CONFIG=Release</code>". You can also use "<code>make clean</code>" to delete the 
intermediate files.</p>

<h3><a name="buildandroid"></a>Android</h3>

<ul>
<li>First of all, get yourself over to <a href="http://www.android.com">www.android.com</a>, 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..</li>
<li>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).</li>
<li>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 "<code>ant debug</code>" or "<code>ant release</code>"</li>
<li>Be careful that your project folder doesn't contain any spaces in its path - the Android tools can't handle this (!)</li>
<li>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.</li>
<li>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.</li>
<li>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!!</li>
<li>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.</li>
</ul>

<div class="ad">
<p class="ad">***</p>
</div>
<div class="bottomsection">
<p class="bottombar">- Copyright 2005 Raw Material Software Ltd -</p> 
</div>
</div>

</body>
</html>