1# The JUCE Module Format 2 3A JUCE module is a collection of header and source files which can be added to a project 4to provide a set of classes and libraries or related functionality. 5 6Their structure is designed to make it as simple as possible for modules to be added to 7user projects on many platforms, either via automated tools, or by manual inclusion. 8 9Each module may have dependencies on other modules, but should be otherwise self-contained. 10 11## File structure 12 13Each module lives inside a folder whose name is the same as the name of the module. The 14JUCE convention for naming modules is lower-case with underscores, e.g. 15 16 juce_core 17 juce_events 18 juce_graphics 19 20But any name that is a valid C++ identifer is OK. 21 22Inside the root of this folder, there must be a set of public header and source files which 23the user's' project will include. The module may have as many other internal source files as 24it needs, but these must all be inside sub-folders! 25 26 27### Master header file 28 29In this root folder there must be ONE master header file, which includes all the necessary 30header files for the module. This header must have the same name as the module, with 31a .h/.hpp/.hxx suffix. E.g. 32 33 juce_core/juce_core.h 34 35IMPORTANT! All code within a module that includes other files from within its own subfolders 36must do so using RELATIVE paths! 37A module must be entirely relocatable on disk, and it must not rely on the user's project 38having any kind of include path set up correctly for it to work. Even if the user has no 39include paths whatsoever and includes the module's master header via an absolute path, 40it must still correctly find all of its internally included sub-files. 41 42This master header file must also contain a comment with a BEGIN_JUCE_MODULE_DECLARATION 43block which defines the module's requirements - the syntax for this is described later on.. 44 45 46### Module CPP files 47 48A module consists of a single header file and zero or more .cpp files. Fewer is better! 49 50Ideally, a module could be header-only module, so that a project can use it by simply 51including the master header file. 52 53For various reasons it's usually necessary or preferable to have a simpler header and 54some .cpp files that the user's project should compile as stand-alone compile units. 55In this case you should ideally provide just a single cpp file in the module's root 56folder, and this should internally include all your other cpps from their sub-folders, 57so that only a single cpp needs to be added to the user's project in order to completely 58compile the module. 59 60In some cases (e.g. if your module internally relies on 3rd-party code which can't be 61easily combined into a single compile-unit) then you may have more than one source file 62here, but avoid this if possible, as it will add a burden for users who are manually 63adding these files to their projects. 64 65The names of these source files must begin with the name of the module, but they can have 66a number or other suffix if there is more than one. 67 68In order to specify that a source file should only be compiled on a specific platform, 69then the filename can be suffixed with one of the following strings: 70 71 _OSX 72 _Windows 73 _Linux 74 _Android 75 _iOS 76 77e.g. 78 79 juce_mymodule/juce_mymodule_1.cpp <- compiled on all platforms 80 juce_mymodule/juce_mymodule_2.cpp <- compiled on all platforms 81 juce_mymodule/juce_mymodule_OSX.cpp <- compiled only on OSX 82 juce_mymodule/juce_mymodule_Windows.cpp <- compiled only on Windows 83 84Often this isn't necessary, as in most cases you can easily add checks inside the files 85to do different things depending on the platform, but this may be handy just to avoid 86clutter in user projects where files aren't needed. 87 88To simplify the use of obj-C++ there's also a special-case rule: If the folder contains 89both a .mm and a .cpp file whose names are otherwise identical, then on OSX/iOS the .mm 90will be used and the cpp ignored. (And vice-versa for other platforms, of course). 91 92 93### Precompiled libraries 94 95Precompiled libraries can be included in a module by placing them in a libs/ subdirectory. 96The following directories are automatically added to the library search paths, and libraries 97placed in these directories can be linked with projects via the OSXLibs, iOSLibs, 98windowsLibs, linuxLibs and mingwLibs keywords in the module declaration (see the following 99section). 100 101- OS X 102 - libs/MacOSX/{arch}, where {arch} is the architecture you are targeting in Xcode ("x86_64" or 103 "i386", for example). 104 105- Visual Studio 106 - libs/VisualStudio{year}/{arch}/{run-time}, where {year} is the four digit year of the Visual Studio 107 release, arch is the target architecture in Visual Studio ("x64" or "Win32", for example), and 108 {runtime} is the type of the run-time library indicated by the corresponding compiler flag 109 ("MD", "MDd", "MT", "MTd"). 110 111- Linux 112 - libs/Linux/{arch}, where {arch} is the architecture you are targeting with the compiler. Some 113 common examples of {arch} are "x86_64", "i386" and "armv6". 114 115- MinGW 116 - libs/MinGW/{arch}, where {arch} can take the same values as Linux. 117 118- iOS 119 - libs/iOS/{arch}, where {arch} is the architecture you are targeting in Xcode ("arm64" or 120 "x86_64", for example). 121 122- Android 123 - libs/Android/{arch}, where {arch} is the architecture provided by the Android Studio variable 124 "${ANDROID_ABI}" ("x86", "armeabi-v7a", "mips", for example). 125 126## The BEGIN_JUCE_MODULE_DECLARATION block 127 128This block of text needs to go inside the module's main header file. It should be commented-out 129and perhaps inside an `#if 0` block too, but the Introjucer will just scan the whole file for the 130string BEGIN_JUCE_MODULE_DECLARATION, and doesn't care about its context in terms of C++ syntax. 131 132The block needs a corresponding END_JUCE_MODULE_DECLARATION to finish the block. 133These should both be on a line of their own. 134 135Inside the block, the parser will expect to find a list of value definitions, one-per-line, with 136the very simple syntax 137 138 value_name: value 139 140The value_name must be one of the items listed below, and is case-sensitive. Whitespace on the 141line is ignored. Some values are compulsory and must be supplied, but others are optional. 142The order in which they're declared doesn't matter. 143 144Possible values: 145 146- ID 147 - (Compulsory) This ID must match the name of the file and folder, e.g. juce_core. 148 The main reason for also including it here is as a sanity-check 149 150- vendor 151 - (Compulsory) A unique ID for the vendor, e.g. "juce". This should be short 152 and shouldn't contain any spaces 153 154- version 155 - (Compulsory) A version number for the module 156 157- name 158 - (Compulsory) A short description of the module 159 160- description 161 - (Compulsory) A longer description (but still only one line of text, please!) 162 163- dependencies 164 - (Optional) A list (space or comma-separated) of other modules that are required by 165 this one. The Introjucer can use this to auto-resolve dependencies. 166 167- website 168 - (Optional) A URL linking to useful info about the module] 169 170- license 171 - (Optional) A description of the type of software license that applies 172 173- minimumCppStandard 174 - (Optional) A number indicating the minimum C++ language standard that is required for this module. 175 This must be just the standard number with no prefix e.g. 14 for C++14 176 177- searchpaths 178 - (Optional) A space-separated list of internal include paths, relative to the module's 179 parent folder, which need to be added to a project's header search path 180 181- OSXFrameworks 182 - (Optional) A list (space or comma-separated) of OSX frameworks that are needed 183 by this module 184 185- iOSFrameworks 186 - (Optional) Like OSXFrameworks, but for iOS targets 187 188- linuxPackages 189 - (Optional) A list (space or comma-separated) pkg-config packages that should be used to pass 190 compiler (CFLAGS) and linker (LDFLAGS) flags 191 192- linuxLibs 193 - (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in a 194 linux build (these are passed to the linker via the -l flag) 195 196- mingwLibs 197 - (Optional) A list (space or comma-separated) of static libs that should be linked in a 198 win32 mingw build (these are passed to the linker via the -l flag) 199 200- OSXLibs 201 - (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in an 202 OS X build (these are passed to the linker via the -l flag) 203 204- iOSLibs 205 - (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in an 206 iOS build (these are passed to the linker via the -l flag) 207 208- windowsLibs 209 - (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in a 210 Visual Studio build (without the .lib suffixes) 211 212Here's an example block: 213 214 BEGIN_JUCE_MODULE_DECLARATION 215 216 ID: juce_audio_devices 217 vendor: juce 218 version: 4.1.0 219 name: JUCE audio and MIDI I/O device classes 220 description: Classes to play and record from audio and MIDI I/O devices 221 website: http://www.juce.com/juce 222 license: GPL/Commercial 223 224 dependencies: juce_audio_basics, juce_audio_formats, juce_events 225 OSXFrameworks: CoreAudio CoreMIDI DiscRecording 226 iOSFrameworks: CoreAudio CoreMIDI AudioToolbox AVFoundation 227 linuxLibs: asound 228 mingwLibs: winmm 229 230 END_JUCE_MODULE_DECLARATION 231 232