Updated main README with CMake support info and changed docs extension from .txt to .md

2026-01-08 23:24:19 +00:00 · 2020-06-28 09:34:54 +01:00 · 2020-06-28 09:34:54 +01:00 · 67925d384f
commit 67925d384f
parent 0d410ef3e6
31 changed files with 154 additions and 98 deletions
--- a/README.md
+++ b/README.md
@ -1,63 +1,97 @@
-# JUCE 6 Technical Preview
+![alt text](https://assets.juce.com/juce/JUCE_banner.png "JUCE")

-__This branch is a technical preview of JUCE 6. It provides the opportunity to
-try out the new features and provide any feedback on how they can best work for
-you before the official release. Please use [this
-topic](https://forum.juce.com/t/juce6-technical-preview-branch/38699) on the
-JUCE forum to discuss the new features.__
+JUCE is an open-source cross-platform C++ application framework used for rapidly
+developing high quality desktop and mobile applications, including VST, AU (and AUv3),
+RTAS and AAX audio plug-ins. JUCE can be easily integrated with existing projects or can
+be used as a project generation tool via the [Projucer](https://juce.com/discover/projucer),
+which supports exporting projects for Xcode (macOS and iOS), Visual Studio, Android Studio,
+Code::Blocks, CLion and Linux Makefiles as well as containing a source code editor and
+live-coding engine which can be used for rapid prototyping.

-## Getting Started with CMake
+## Getting Started

-For comprehensive documentation on JUCE's CMake API, see
-`docs/CMake API.txt` in this repo.
+The JUCE repository contains a [master](https://github.com/juce-framework/JUCE/tree/master)
+and [develop](https://github.com/juce-framework/JUCE/tree/develop) branch. The develop branch
+contains the latest bugfixes and features and is periodically merged into the master
+branch in stable [tagged releases](https://github.com/juce-framework/JUCE/releases)
+(the latest release containing pre-built binaries can be also downloaded from the
+[JUCE website](https://juce.com/get-juce)).

-### Building Examples
+JUCE projects can be managed with either the Projucer (JUCE's own project-configuration
+tool) or with CMake.

-To build the examples and extras bundled with JUCE, simply clone JUCE and then
-run:
+### The Projucer

-```
-# Go to JUCE directory
-cd /path/to/cloned/JUCE
-# Configure build with all examples and extras enabled
-cmake -B cmake-build -DJUCE_BUILD_EXAMPLES=ON -DJUCE_BUILD_EXTRAS=ON
-# Build a specific target (building everything will take a long time!)
-cmake --build cmake-build --target DemoRunner
-```
+The repository doesn't contain a pre-built Projucer so you will need to build it
+for your platform - Xcode, Visual Studio and Linux Makefile projects are located in
+[extras/Projucer/Builds](/extras/Projucer/Builds)
+(the minumum system requirements are listed in the __System Requirements__ section below).
+The Projucer can then be used to create new JUCE projects, view tutorials and run examples.
+It is also possible to include the JUCE modules source code in an existing project directly,
+or build them into a static or dynamic library which can be linked into a project.

-### Using `add_subdirectory`
+For further help getting started, please refer to the JUCE
+[documentation](https://juce.com/learn/documentation) and
+[tutorials](https://juce.com/learn/tutorials).

-The simplest way to include JUCE in your project is to add JUCE as a
-subdirectory of your project, and to include the line `add_subdirectory(JUCE)`
-in your project CMakeLists.txt. This will make the JUCE targets and helper
-functions available for use by your custom targets.
+### CMake

-### Using `find_package`
+Version 3.15 or higher is required for plugin projects, and strongly
+recommended for other project types. To use CMake, you will need to install it,
+either from your system package manager or from the [official download
+page](https://cmake.org/download/). For comprehensive documentation on JUCE's
+CMake API, see the [JUCE CMake documentation](/docs/CMake API.md). For examples
+which may be useful as starting points for new CMake projects, see the [CMake
+examples directory](/examples/CMake).

-To install JUCE globally on your system, you'll need to tell CMake where to
-place the installed files. As this is a preview branch, we recommend that you
-*avoid* installing to the default install location, and instead choose a path
-that you can easily delete and recreate when installing newer preview versions.
+#### Building Examples

-```
-# Go to JUCE directory
-cd /path/to/clone/JUCE
-# Configure build with library components only
-cmake -B cmake-build-install -DCMAKE_INSTALL_PREFIX=/path/to/JUCE/install
-# Run the installation
-cmake --build cmake-build-install --target install
-```
+To use CMake to build the examples and extras bundled with JUCE, simply clone
+JUCE and then run the following commands, replacing "DemoRunner" with the name
+of the target you wish to build.

-Make sure the dependent project CMakeLists.txt contains the line
-`find_package(JUCE CONFIG REQUIRED)`. This will make the JUCE modules and CMake
-helper functions available for use in the rest of your build. Then, run the
-build like so:
+    cd /path/to/JUCE
+    cmake . -B cmake-build -DJUCE_BUILD_EXAMPLES=ON -DJUCE_BUILD_EXTRAS=ON
+    cmake --build cmake-build --target DemoRunner

-```
-# Go to project directory
-cd /path/to/my/project
-# Configure build, passing the JUCE install path you used earlier
-cmake -B cmake-build -DCMAKE_PREFIX_PATH=/path/to/JUCE/install
-# Build the project
-cmake --build cmake-build
-```
+## Minimum System Requirements
+
+#### Building JUCE Projects
+
+- __macOS/iOS__: macOS 10.11 and Xcode 7.3.1
+- __Windows__: Windows 8.1 and Visual Studio 2015 64-bit
+- __Linux__: GCC 4.8
+- __Android__: Android Studio on Windows, macOS or Linux
+
+#### Deployment Targets
+
+- __macOS__: macOS 10.7
+- __Windows__: Windows Vista
+- __Linux__: Mainstream Linux distributions
+- __iOS__: iOS 9.0
+- __Android__: Jelly Bean (API 16)
+
+## Contributing
+
+For bug reports and features requests, please visit the [JUCE Forum](https://forum.juce.com/) -
+the JUCE developers are active there and will read every post and respond accordingly. When
+submitting a bug report, please ensure that it follows the
+[issue template](/.github/ISSUE_TEMPLATE.txt).
+We don't accept third party GitHub pull requests directly due to copyright restrictions
+but if you would like to contribute any changes please contact us.
+
+## License
+
+The core JUCE modules (juce_audio_basics, juce_audio_devices, juce_blocks_basics, juce_core
+and juce_events) are permissively licensed under the terms of the
+[ISC license](http://www.isc.org/downloads/software-support-policy/isc-license/).
+Other modules are covered by a
+[GPL/Commercial license](https://www.gnu.org/licenses/gpl-3.0.en.html).
+
+There are multiple commercial licensing tiers for JUCE, with different terms for each:
+- JUCE Personal (developers or startup businesses with revenue under 50K USD) - free
+- JUCE Indie (small businesses with revenue under 500K USD) - $40/month
+- JUCE Pro (no revenue limit) - $130/month
+- JUCE Educational (no revenue limit) - free for bona fide educational institutes
+
+For full terms see [LICENSE.md](LICENSE.md).
--- a/docs/CMake
+++ b/docs/CMake
@ -16,6 +16,38 @@ In addition to CMake you'll need a build toolchain for your platform, such as Xc

 ## Getting Started

+### Using `add_subdirectory`
+
+The simplest way to include JUCE in your project is to add JUCE as a
+subdirectory of your project, and to include the line `add_subdirectory(JUCE)`
+in your project CMakeLists.txt. This will make the JUCE targets and helper
+functions available for use by your custom targets.
+
+### Using `find_package`
+
+To install JUCE globally on your system, you'll need to tell CMake where to
+place the installed files.
+
+    # Go to JUCE directory
+    cd /path/to/clone/JUCE
+    # Configure build with library components only
+    cmake -B cmake-build-install -DCMAKE_INSTALL_PREFIX=/path/to/JUCE/install
+    # Run the installation
+    cmake --build cmake-build-install --target install
+
+In your project which consumes JUCE, make sure the project CMakeLists.txt contains the line
+`find_package(JUCE CONFIG REQUIRED)`. This will make the JUCE modules and CMake helper functions
+available for use in the rest of your build. Then, run the build like so:
+
+    # Go to project directory
+    cd /path/to/my/project
+    # Configure build, passing the JUCE install path you used earlier
+    cmake -B cmake-build -DCMAKE_PREFIX_PATH=/path/to/JUCE/install
+    # Build the project
+    cmake --build cmake-build
+
+### Example projects
+
 In the JUCE/examples/CMake directory, you'll find example projects for a GUI app, a console app,
 and an audio plugin. You can simply copy one of these subdirectories out of the JUCE repo, add JUCE
 as a submodule, and uncomment the call to `add_subdirectory` where indicated in the CMakeLists.txt.
--- a/Format.txt
+++ b/Format.txt
@ -1,5 +1,4 @@
-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.
@ -9,8 +8,7 @@ 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.
@ -26,8 +24,7 @@ the user's' project will include. The module may have as many other internal sou
 it needs, but these must all be inside sub-folders!


-Master header file
------------------
+### Master header file

 In this root folder there must be ONE master header file, which includes all the necessary
 header files for the module. This header must have the same name as the module, with
@ -46,8 +43,7 @@ This master header file must also contain a comment with a BEGIN_JUCE_MODULE_DEC
 block which defines the module's requirements - the syntax for this is described later on..


-Module CPP files
----------------
+### Module CPP files

 A module consists of a single header file and zero or more .cpp files. Fewer is better!

@ -94,8 +90,7 @@ both a .mm and a .cpp file whose names are otherwise identical, then on OSX/iOS
 will be used and the cpp ignored. (And vice-versa for other platforms, of course).


-Precompiled libraries
---------------------
+### Precompiled libraries

 Precompiled libraries can be included in a module by placing them in a libs/ subdirectory.
 The following directories are automatically added to the library search paths, and libraries
@ -128,8 +123,7 @@ section).
  - 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
--- a/docs/README.txt
+++ b/docs/README.txt
@ -1,5 +1,4 @@
-JUCE Documentation
-==================
+# JUCE Documentation

 This directory contains files documenting the JUCE Module Format, and the JUCE
 CMake API.
@ -15,11 +14,9 @@ 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
-=====================================
+# Generating Offline HTML Documentation

-Dependencies
------------
+## Dependencies

 - doxygen
 - python
@ -28,8 +25,7 @@ Dependencies

 Make sure that all the dependencies can be found on your PATH.

-Building
--------
+## Building

 - cd into the `doxygen` directory on the command line
 - run `make`
--- a/docs/doxygen/Doxyfile
+++ b/docs/doxygen/Doxyfile
@ -802,8 +802,8 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.

 INPUT                  = build \
-                         "../JUCE Module Format.txt" \
-                         "../CMake API.txt"
+                         "../JUCE Module Format.md" \
+                         "../CMake API.md"

 # 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
--- a/examples/CMake/AudioPlugin/CMakeLists.txt
+++ b/examples/CMake/AudioPlugin/CMakeLists.txt
@ -35,7 +35,7 @@ project(AUDIO_PLUGIN_EXAMPLE VERSION 0.0.1)
 # (AudioPluginExample here). This target is a normal CMake target, but has a lot of extra properties set
 # up by default. As well as this shared code static library, this function adds targets for each of
 # the formats specified by the FORMATS arguments. This function accepts many optional arguments.
-# Check the readme at `docs/CMake API.txt` in the JUCE repo for the full list.
+# Check the readme at `docs/CMake API.md` in the JUCE repo for the full list.

 juce_add_plugin(AudioPluginExample
    # VERSION ...                               # Set this if the plugin version is different to the project version
--- a/examples/CMake/ConsoleApp/CMakeLists.txt
+++ b/examples/CMake/ConsoleApp/CMakeLists.txt
@ -30,7 +30,7 @@ project(CONSOLE_APP_EXAMPLE VERSION 0.0.1)
 # `juce_add_console_app` adds an executable target with the name passed as the first argument
 # (ConsoleAppExample here). This target is a normal CMake target, but has a lot of extra properties
 # set up by default. This function accepts many optional arguments. Check the readme at
-# `docs/CMake API.txt` in the JUCE repo for the full list.
+# `docs/CMake API.md` in the JUCE repo for the full list.

 juce_add_console_app(ConsoleAppExample
    PRODUCT_NAME "Console App Example")     # The name of the final executable, which can differ from the target name
--- a/examples/CMake/GuiApp/CMakeLists.txt
+++ b/examples/CMake/GuiApp/CMakeLists.txt
@ -34,7 +34,7 @@ project(GUI_APP_EXAMPLE VERSION 0.0.1)
 # `juce_add_gui_app` adds an executable target with the name passed as the first argument
 # (GuiAppExample here). This target is a normal CMake target, but has a lot of extra properties set
 # up by default. This function accepts many optional arguments. Check the readme at
-# `docs/CMake API.txt` in the JUCE repo for the full list.
+# `docs/CMake API.md` in the JUCE repo for the full list.

 juce_add_gui_app(GuiAppExample
    # VERSION ...                       # Set this if the app version is different to the project version
--- a/extras/Build/CMake/JUCEUtils.cmake
+++ b/extras/Build/CMake/JUCEUtils.cmake
@ -21,7 +21,7 @@
 # Functions beginning with an underscore should be considered private and susceptible to
 # change, so don't call them directly.
 #
-# See the readme at `docs/CMake API.txt` for more information about CMake usage,
+# See the readme at `docs/CMake API.md` for more information about CMake usage,
 # including documentation of the public functions in this file.
 # ==================================================================================================

--- a/extras/Build/juce_build_tools/juce_build_tools.h
+++ b/extras/Build/juce_build_tools/juce_build_tools.h
@ -20,7 +20,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_analytics/juce_analytics.h
+++ b/modules/juce_analytics/juce_analytics.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_audio_basics/juce_audio_basics.h
+++ b/modules/juce_audio_basics/juce_audio_basics.h
@ -25,7 +25,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_audio_devices/juce_audio_devices.h
+++ b/modules/juce_audio_devices/juce_audio_devices.h
@ -25,7 +25,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_audio_formats/juce_audio_formats.h
+++ b/modules/juce_audio_formats/juce_audio_formats.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_audio_plugin_client/juce_audio_plugin_client.h
+++ b/modules/juce_audio_plugin_client/juce_audio_plugin_client.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_audio_processors/juce_audio_processors.h
+++ b/modules/juce_audio_processors/juce_audio_processors.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_audio_utils/juce_audio_utils.h
+++ b/modules/juce_audio_utils/juce_audio_utils.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_blocks_basics/juce_blocks_basics.h
+++ b/modules/juce_blocks_basics/juce_blocks_basics.h
@ -25,7 +25,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_box2d/juce_box2d.h
+++ b/modules/juce_box2d/juce_box2d.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_core/juce_core.h
+++ b/modules/juce_core/juce_core.h
@ -25,7 +25,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_cryptography/juce_cryptography.h
+++ b/modules/juce_cryptography/juce_cryptography.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_data_structures/juce_data_structures.h
+++ b/modules/juce_data_structures/juce_data_structures.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_dsp/juce_dsp.h
+++ b/modules/juce_dsp/juce_dsp.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_events/juce_events.h
+++ b/modules/juce_events/juce_events.h
@ -25,7 +25,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_graphics/juce_graphics.h
+++ b/modules/juce_graphics/juce_graphics.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_gui_basics/juce_gui_basics.h
+++ b/modules/juce_gui_basics/juce_gui_basics.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_gui_extra/juce_gui_extra.h
+++ b/modules/juce_gui_extra/juce_gui_extra.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_opengl/juce_opengl.h
+++ b/modules/juce_opengl/juce_opengl.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_osc/juce_osc.h
+++ b/modules/juce_osc/juce_osc.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_product_unlocking/juce_product_unlocking.h
+++ b/modules/juce_product_unlocking/juce_product_unlocking.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION
--- a/modules/juce_video/juce_video.h
+++ b/modules/juce_video/juce_video.h
@ -21,7 +21,7 @@
 The block below describes the properties of this module, and is read by
 the Projucer to automatically generate project code that uses it.
 For details about the syntax and how to create or use a module, see the
- JUCE Module Format.txt file.
+ JUCE Module Format.md file.


 BEGIN_JUCE_MODULE_DECLARATION