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