mirror/JUCE
1
0
Fork 0
mirror of https://github.com/juce-framework/JUCE.git synced 2026-01-10 23:44:24 +00:00
Code Activity

Docs: Add new top-level docs folder

Browse source
This commit is contained in:
reuk 2020-05-14 18:22:11 +01:00
parent 15ff62f384
commit 9f03f30ad4
No known key found for this signature in database
GPG key ID: 9ADCD339CFC98A11
9 changed files with 196 additions and 184 deletions
Download patch file Download diff file Expand all files Collapse all files

117
examples/CMake/readme.md → docs/CMake API.txt
View file

@ -1,7 +1,4 @@
# CMake Template Projects
This directory contains project templates which should help you get started using JUCE's CMake
support.
# The JUCE CMake API
## System Requirements
@ -27,9 +24,7 @@ call to `find_package`.
Once your project is set up, you can generate a build tree for it in the normal way. To get started,
you might invoke CMake like this, from the new directory you created.
```
cmake -Bbuild (-GgeneratorName) (-DJUCE_BUILD_EXTRAS=ON) (-DJUCE_BUILD_EXAMPLES=ON)
```
cmake -Bbuild (-GgeneratorName) (-DJUCE_BUILD_EXTRAS=ON) (-DJUCE_BUILD_EXAMPLES=ON)
This will create a build tree in a directory named 'build', using the CMakeLists in the current
working directory, using the default generator (makefiles on mac/linux, and the most recent Visual
@ -41,9 +36,7 @@ these options are on, so you probably won't want to include them most of the tim
Then, to build the project:
```
cmake --build build (--target targetNameFromCMakeLists) (--config Release/Debug/...)
```
cmake --build build (--target targetNameFromCMakeLists) (--config Release/Debug/...)
This tells cmake to build the target named `targetNameFromCMakeLists`, in the specified
configuration, using the appropriate tool. Of course, if you generated makefiles or ninja files, you
@ -58,9 +51,7 @@ fail to run certain parts of the build, such as compiling icons and processing t
default, CMake will build for the same system that originally configured the project, so to enable
cross-compilation for iOS, a few extra flags must be passed to the initial CMake invocation:
```
cmake -Bbuild-ios -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3
```
cmake -Bbuild-ios -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3
Here we create a build tree in the directory named 'build-ios', using the Xcode generator. The
`-DCMAKE_SYSTEM_NAME=iOS` option tells CMake to enable cross-compiling for iOS. The
@ -70,9 +61,7 @@ despite the 'OSX' in the variable name!).
Once the project has generated, we can open it as normal in Xcode (look for the project file in the
build directory). Alternatively, to build from the command-line, we could run this command:
```
cmake --build build-ios --target <targetName> -- -sdk iphonesimulator
```
cmake --build build-ios --target <targetName> -- -sdk iphonesimulator
Here, we're building the target named `<targetName>` from the build tree in the directory
`build-ios`. All the arguments after `--` are ignored by CMake, and are passed through to the
@ -83,11 +72,9 @@ require special code signing.
If we wanted to build for a real device, we would need to pass some extra signing details to the
initial CMake configuration command:
```
cmake -Bbuild-ios -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \
-DCMAKE_XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY="iPhone Developer"
-DCMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM=<10 character id>
```
cmake -Bbuild-ios -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \
-DCMAKE_XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY="iPhone Developer"
-DCMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM=<10 character id>
The `CODE_SIGN_IDENTITY` is the kind of certificate you want to use (iPhone Developer is appropriate
for development) and `DEVELOPMENT_TEAM` is the 10-character ID that can be found by opening the
@ -97,29 +84,25 @@ info field.
When building the target, you may also need to tell Xcode that it can automatically update
provisioning profiles, which is achieved by passing the `-allowProvisioningUpdates` flag:
```
cmake --build build-ios --target <targetName> -- -allowProvisioningUpdates
```
cmake --build build-ios --target <targetName> -- -allowProvisioningUpdates
### A note about compile definitions
Module options and plugin options that would previously have been set in the Projucer can be set on
a target-by-target basis in CMake, via `target_compile_definitions`. To find the options exposed by
a particular module, check its module header for sections with the following structure:
```
/** Config: NAME_OF_KEY
Docs go here...
*/
#ifndef NAME_OF_KEY
#define NAME_OF_KEY ...
#edif
```
/** Config: NAME_OF_KEY
Docs go here...
*/
#ifndef NAME_OF_KEY
#define NAME_OF_KEY ...
#endif
To override the default config option, use the following CMake code, replacing `<value>` as
appropriate:
```
target_compile_definitions(my_target PUBLIC NAME_OF_KEY=<value>)
```
target_compile_definitions(my_target PUBLIC NAME_OF_KEY=<value>)
The `JucePlugin_PreferredChannelConfig` preprocessor definition for plugins is difficult to specify
in a portable way due to its use of curly braces, which may be misinterpreted in Linux/Mac builds
@ -130,11 +113,9 @@ the newer buses API to specify the desired plugin inputs and outputs.
### `juce_add_<target>`
```
juce_add_gui_app(<target> [KEY value]...)
juce_add_console_app(<target> [KEY value]...)
juce_add_plugin(<target> [KEY value]...)
```
juce_add_gui_app(<target> [KEY value]...)
juce_add_console_app(<target> [KEY value]...)
juce_add_plugin(<target> [KEY value]...)
`juce_add_gui_app` and `juce_add_console_app` add an executable target with name `<target>`.
`juce_add_plugin` adds a 'shared code' static library target with name `<target>`, along with extra
@ -447,12 +428,10 @@ attributes directly to these creation functions, rather than adding them later.
### `juce_add_binary_data`
```
juce_add_binary_data(<name>
[HEADER_NAME ...]
[NAMESPACE ...]
SOURCES ...)
```
juce_add_binary_data(<name>
[HEADER_NAME ...]
[NAMESPACE ...]
SOURCES ...)
Create a static library that embeds the contents of the files passed as arguments to this function.
Adds a library target called `<name>` which can be linked into other targets using
@ -471,18 +450,14 @@ and embedded in the resulting static library. This library can be linked as norm
### `juce_add_bundle_resources_directory`
```
juce_add_bundle_resources_directory(<target> <folder>)
```
juce_add_bundle_resources_directory(<target> <folder>)
Copy the entire directory at the location `<folder>` into an Apple bundle's resource directory, i.e.
the `Resources` directory for a macOS bundle, and the top-level directory of an iOS bundle.
### `juce_generate_juce_header`
```
juce_generate_juce_header(<target>)
```
juce_generate_juce_header(<target>)
Introspects the JUCE modules that have been linked to `<target>` and generates a `JuceHeader.h`
which contains `#include` statements for each of the module headers. This header also contains an
@ -495,10 +470,8 @@ require them.
### `juce_set_<kind>_sdk_path`
```
juce_set_aax_sdk_path(<absolute path>)
juce_set_vst2_sdk_path(<absolute path>)
```
juce_set_aax_sdk_path(<absolute path>)
juce_set_vst2_sdk_path(<absolute path>)
Call these functions from your CMakeLists to set up your local AAX and/or VST2 SDKs. These functions
should be called *before* adding any targets that may depend on the AAX/VST2 SDKs (plugin
@ -506,10 +479,8 @@ hosts, VST2/AAX plugins etc.).
### `juce_add_module`
```
juce_add_module(<path to module>)
juce_add_modules(<names of module>...)
```
juce_add_module(<path to module>)
juce_add_modules(<names of module>...)
`juce_add_module` adds a library target for the JUCE module located at the provided path. `<path>`
must be the path to a module directory (e.g. /Users/me/JUCE/modules/juce_core). This will add an
@ -534,9 +505,7 @@ CMakeLists in the `modules` directory.
### `juce_add_pip`
```
juce_add_pip(<header>)
```
juce_add_pip(<header>)
This function parses the PIP metadata block in the provided header, and adds appropriate build
targets for a console app, GUI app, or audio plugin. For audio plugin targets, it builds as many
@ -551,37 +520,29 @@ your target.
### `juce_disable_default_flags`
```
juce_disable_default_flags()
```
juce_disable_default_flags()
This function sets the `CMAKE_<LANG>_FLAGS_<MODE>` to empty in the current directory and below,
allowing alternative optimisation/debug flags to be supplied without conflicting with the
CMake-supplied defaults.
### `juce::juce_recommended_warning_flags
### `juce::juce_recommended_warning_flags`
```
target_link_libraries(myTarget PRIVATE juce::juce_recommended_warning_flags)
```
target_link_libraries(myTarget PRIVATE juce::juce_recommended_warning_flags)
This is a target which can be linked to other targets using `target_link_libraries`, in order to
enable the recommended JUCE warnings when building them.
### `juce::juce_recommended_config_flags
### `juce::juce_recommended_config_flags`
```
target_link_libraries(myTarget PRIVATE juce::juce_recommended_config_flags)
```
target_link_libraries(myTarget PRIVATE juce::juce_recommended_config_flags)
This is a target which can be linked to other targets using `target_link_libraries`, in order to
enable the recommended JUCE optimisation and debug flags.
### `juce::juce_recommended_lto_flags
### `juce::juce_recommended_lto_flags`
```
target_link_libraries(myTarget PRIVATE juce::juce_recommended_lto_flags)
```
target_link_libraries(myTarget PRIVATE juce::juce_recommended_lto_flags)
This is a target which can be linked to other targets using `target_link_libraries`, in order to
enable the recommended JUCE link time optimisation settings.

188
modules/JUCE Module Format.txt → docs/JUCE Module Format.txt
View file

@ -1,6 +1,5 @@
The JUCE Module Format
======================
The JUCE Module Format
======================
A JUCE module is a collection of header and source files which can be added to a project
to provide a set of classes and libraries or related functionality.
@ -10,15 +9,15 @@ user projects on many platforms, either via automated tools, or by manual inclus
Each module may have dependencies on other modules, but should be otherwise self-contained.
File structure
==============
File structure
==============
Each module lives inside a folder whose name is the same as the name of the module. The
JUCE convention for naming modules is lower-case with underscores, e.g.
juce_core
juce_events
juce_graphics
juce_core
juce_events
juce_graphics
But any name that is a valid C++ identifer is OK.
@ -34,7 +33,7 @@ In this root folder there must be ONE master header file, which includes all the
header files for the module. This header must have the same name as the module, with
a .h/.hpp/.hxx suffix. E.g.
juce_core/juce_core.h
juce_core/juce_core.h
IMPORTANT! All code within a module that includes other files from within its own subfolders
must do so using RELATIVE paths!
@ -73,17 +72,18 @@ a number or other suffix if there is more than one.
In order to specify that a source file should only be compiled on a specific platform,
then the filename can be suffixed with one of the following strings:
_OSX
_Windows
_Linux
_Android
_iOS
_OSX
_Windows
_Linux
_Android
_iOS
e.g.
juce_mymodule/juce_mymodule_1.cpp <- compiled on all platforms
juce_mymodule/juce_mymodule_2.cpp <- compiled on all platforms
juce_mymodule/juce_mymodule_OSX.cpp <- compiled only on OSX
juce_mymodule/juce_mymodule_Windows.cpp <- compiled only on Windows
juce_mymodule/juce_mymodule_1.cpp <- compiled on all platforms
juce_mymodule/juce_mymodule_2.cpp <- compiled on all platforms
juce_mymodule/juce_mymodule_OSX.cpp <- compiled only on OSX
juce_mymodule/juce_mymodule_Windows.cpp <- compiled only on Windows
Often this isn't necessary, as in most cases you can easily add checks inside the files
to do different things depending on the platform, but this may be handy just to avoid
@ -103,33 +103,33 @@ placed in these directories can be linked with projects via the OSXLibs, iOSLibs
windowsLibs, linuxLibs and mingwLibs keywords in the module declaration (see the following
section).
OS X:
libs/MacOSX/{arch}, where {arch} is the architecture you are targeting in Xcode ("x86_64" or
- OS X
- libs/MacOSX/{arch}, where {arch} is the architecture you are targeting in Xcode ("x86_64" or
"i386", for example).
Visual Studio:
libs/VisualStudio{year}/{arch}/{run-time}, where {year} is the four digit year of the Visual Studio
- Visual Studio
- libs/VisualStudio{year}/{arch}/{run-time}, where {year} is the four digit year of the Visual Studio
release, arch is the target architecture in Visual Studio ("x64" or "Win32", for example), and
{runtime} is the type of the run-time library indicated by the corresponding compiler flag
("MD", "MDd", "MT", "MTd").
Linux:
libs/Linux/{arch}, where {arch} is the architecture you are targeting with the compiler. Some
- Linux
- libs/Linux/{arch}, where {arch} is the architecture you are targeting with the compiler. Some
common examples of {arch} are "x86_64", "i386" and "armv6".
MinGW:
libs/MinGW/{arch}, where {arch} can take the same values as Linux.
- MinGW
- libs/MinGW/{arch}, where {arch} can take the same values as Linux.
iOS:
libs/iOS/{arch}, where {arch} is the architecture you are targeting in Xcode ("arm64" or
- iOS
- libs/iOS/{arch}, where {arch} is the architecture you are targeting in Xcode ("arm64" or
"x86_64", for example).
Android:
libs/Android/{arch}, where {arch} is the architecture provided by the Android Studio variable
- Android
- libs/Android/{arch}, where {arch} is the architecture provided by the Android Studio variable
"${ANDROID_ABI}" ("x86", "armeabi-v7a", "mips", for example).
The BEGIN_JUCE_MODULE_DECLARATION block
=======================================
The BEGIN_JUCE_MODULE_DECLARATION block
=======================================
This block of text needs to go inside the module's main header file. It should be commented-out
and perhaps inside an #if 0 block too, but the Introjucer will just scan the whole file for the
@ -141,7 +141,7 @@ These should both be on a line of their own.
Inside the block, the parser will expect to find a list of value definitions, one-per-line, with
the very simple syntax
value_name: value
value_name: value
The value_name must be one of the items listed below, and is case-sensitive. Whitespace on the
line is ignored. Some values are compulsory and must be supplied, but others are optional.
@ -149,55 +149,89 @@ The order in which they're declared doesn't matter.
Possible values:
ID: (Compulsory) This ID must match the name of the file and folder, e.g. juce_core.
The main reason for also including it here is as a sanity-check
vendor: (Compulsory) A unique ID for the vendor, e.g. "juce". This should be short
and shouldn't contain any spaces
version: (Compulsory) A version number for the module
name: (Compulsory) A short description of the module
description: (Compulsory) A longer description (but still only one line of text, please!)
- ID
- (Compulsory) This ID must match the name of the file and folder, e.g. juce_core.
The main reason for also including it here is as a sanity-check
dependencies: (Optional) A list (space or comma-separated) of other modules that are required by
this one. The Introjucer can use this to auto-resolve dependencies.
website: (Optional) A URL linking to useful info about the module]
license: (Optional) A description of the type of software license that applies
minimumCppStandard: (Optional) A number indicating the minimum C++ language standard that is required for this module.
This must be just the standard number with no prefix e.g. 14 for C++14
searchpaths: (Optional) A space-separated list of internal include paths, relative to the module's
parent folder, which need to be added to a project's header search path
OSXFrameworks: (Optional) A list (space or comma-separated) of OSX frameworks that are needed
by this module
iOSFrameworks: (Optional) Like OSXFrameworks, but for iOS targets
linuxPackages: (Optional) A list (space or comma-separated) pkg-config packages that should be used to pass
compiler (CFLAGS) and linker (LDFLAGS) flags
linuxLibs: (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in a
linux build (these are passed to the linker via the -l flag)
mingwLibs: (Optional) A list (space or comma-separated) of static libs that should be linked in a
win32 mingw build (these are passed to the linker via the -l flag)
OSXLibs: (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in an
OS X build (these are passed to the linker via the -l flag)
iOSLibs: (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in an
iOS build (these are passed to the linker via the -l flag)
windowsLibs: (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in a
Visual Studio build (without the .lib suffixes)
- vendor
- (Compulsory) A unique ID for the vendor, e.g. "juce". This should be short
and shouldn't contain any spaces
- version
- (Compulsory) A version number for the module
- name
- (Compulsory) A short description of the module
- description
- (Compulsory) A longer description (but still only one line of text, please!)
- dependencies
- (Optional) A list (space or comma-separated) of other modules that are required by
this one. The Introjucer can use this to auto-resolve dependencies.
- website
- (Optional) A URL linking to useful info about the module]
- license
- (Optional) A description of the type of software license that applies
- minimumCppStandard
- (Optional) A number indicating the minimum C++ language standard that is required for this module.
This must be just the standard number with no prefix e.g. 14 for C++14
- searchpaths
- (Optional) A space-separated list of internal include paths, relative to the module's
parent folder, which need to be added to a project's header search path
- OSXFrameworks
- (Optional) A list (space or comma-separated) of OSX frameworks that are needed
by this module
- iOSFrameworks
- (Optional) Like OSXFrameworks, but for iOS targets
- linuxPackages
- (Optional) A list (space or comma-separated) pkg-config packages that should be used to pass
compiler (CFLAGS) and linker (LDFLAGS) flags
- linuxLibs
- (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in a
linux build (these are passed to the linker via the -l flag)
- mingwLibs
- (Optional) A list (space or comma-separated) of static libs that should be linked in a
win32 mingw build (these are passed to the linker via the -l flag)
- OSXLibs
- (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in an
OS X build (these are passed to the linker via the -l flag)
- iOSLibs
- (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in an
iOS build (these are passed to the linker via the -l flag)
- windowsLibs
- (Optional) A list (space or comma-separated) of static or dynamic libs that should be linked in a
Visual Studio build (without the .lib suffixes)
Here's an example block:
BEGIN_JUCE_MODULE_DECLARATION
BEGIN_JUCE_MODULE_DECLARATION
ID: juce_audio_devices
vendor: juce
version: 4.1.0
name: JUCE audio and MIDI I/O device classes
description: Classes to play and record from audio and MIDI I/O devices
website: http://www.juce.com/juce
license: GPL/Commercial
ID: juce_audio_devices
vendor: juce
version: 4.1.0
name: JUCE audio and MIDI I/O device classes
description: Classes to play and record from audio and MIDI I/O devices
website: http://www.juce.com/juce
license: GPL/Commercial
dependencies: juce_audio_basics, juce_audio_formats, juce_events
OSXFrameworks: CoreAudio CoreMIDI DiscRecording
iOSFrameworks: CoreAudio CoreMIDI AudioToolbox AVFoundation
linuxLibs: asound
mingwLibs: winmm
dependencies: juce_audio_basics, juce_audio_formats, juce_events
OSXFrameworks: CoreAudio CoreMIDI DiscRecording
iOSFrameworks: CoreAudio CoreMIDI AudioToolbox AVFoundation
linuxLibs: asound
mingwLibs: winmm
END_JUCE_MODULE_DECLARATION
END_JUCE_MODULE_DECLARATION

38
docs/README.txt Normal file
View file

@ -0,0 +1,38 @@
JUCE Documentation
==================
This directory contains files documenting the JUCE Module Format, and the JUCE
CMake API.
The JUCE modules themselves can be found in the `modules` subdirectory of the
JUCE repository.
CMake example projects are located in the `examples/CMake` directory.
The JUCE API itself is documented inline, but HTML docs can be generated from
the source code using the `doxygen` tool. These HTML docs can be [found
online](https://juce.com/learn/documentation), or you can generate a local copy
which can be used without an internet connection. For instructions on generating
offline docs, see below.
Generating Offline HTML Documentation
=====================================
Dependencies
------------
- doxygen
- python
- make
- graphviz (to generate inheritance diagrams)
Make sure that all the dependencies can be found on your PATH.
Building
--------
- cd into the `doxygen` directory on the command line
- run `make`
Doxygen will create a new subdirectory "doc". Open doc/index.html in your browser
to access the generated HTML documentation.

6
doxygen/Doxyfile → docs/doxygen/Doxyfile
View file

@ -302,7 +302,7 @@ OPTIMIZE_OUTPUT_VHDL = NO
# Note that for custom extensions you also need to set FILE_PATTERNS otherwise
# the files are not read by doxygen.
EXTENSION_MAPPING =
EXTENSION_MAPPING = txt=md
# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
# according to the Markdown format, which allows for more readable
@ -801,7 +801,9 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = build
INPUT = build \
"../JUCE Module Format.txt" \
"../CMake API.txt"
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

4
doxygen/Makefile → docs/doxygen/Makefile
View file

@ -1,6 +1,6 @@
SHELL := /bin/bash
SOURCE_FILES := $(shell find ../modules -type f -name "juce_*.h" -or -name "juce_*.dox" | sed 's/ /\\ /g')
SOURCE_FILES := $(shell find ../../modules -type f -name "juce_*.h" -or -name "juce_*.dox" | sed 's/ /\\ /g')
.PHONEY: clean
@ -8,7 +8,7 @@ doc/index.html: build/juce_modules.dox Doxyfile
doxygen
build/juce_modules.dox: process_source_files.py $(SOURCE_FILES)
python $< ../modules build
python $< ../../modules build
clean:
rm -rf build doc

2
docs/doxygen/make.bat Normal file
View file

@ -0,0 +1,2 @@
python process_source_files.py ..\..\modules build
doxygen

0
doxygen/process_source_files.py → docs/doxygen/process_source_files.py
View file

23
doxygen/README.txt
View file

@ -1,23 +0,0 @@
The JUCE API Reference
======================
From here, you can generate an offline HTML version of the JUCE API Reference.
Dependencies
------------
- doxygen
- python
- graphviz (to generate inheritance diagrams)
Make sure that all the dependencies can be found on your PATH.
Building
--------
- cd into this directory on the command line
- run `make`
Doxygen will create a new subfolder "doc". Open doc/index.html in your browser
to access the generated HTML documentation.

2
doxygen/make.bat
View file

@ -1,2 +0,0 @@
python process_source_files.py ..\modules build
doxygen