Refresh stale end-user and build documentation

Author: thedavidweng

BUILDING-cmake.md

@@ -9,7 +9,7 @@ Want to build it fast?
 Required tools and dependencies:
 
 - CMake 3.21 or higher.
-- A working toolchain, e.g. Visual Studio on Windows or the `build-essentials` package on Ubuntu Linux.
+- A working toolchain, e.g. Visual Studio on Windows or the `build-essential` package on Ubuntu Linux.
 - Main OpenGL libraries and development files.
 
 To use the library in other projects, it is required to install it. Use `CMAKE_INSTALL_PREFIX` to specify the
@@ -27,7 +27,7 @@ cmake --build . --target install --config Release
 If the build succeeded, you should now have the projectM libraries and include files in the specified install dir.
 
 To use the library in other CMake projects, simply point the build to your install dir by adding it
-to `CMAKE_PREFIX_PATH` and call `find_package(libprojectM)` in the other project's `CMakeLists.txt`.
+to `CMAKE_PREFIX_PATH` and call `find_package(projectM4)` in the other project's `CMakeLists.txt`.
 
 If you use other build systems, you have to specify the include and library paths manually.
 
@@ -75,12 +75,12 @@ cmake -G Xcode -S /path/to/source/dir -B /path/to/build/dir
 
 If you develop on Windows, you will possibly use Visual Studio. While recent visual Studio versions have CMake support
 built-in, you can still pre-generate the solution and project files and open the `.sln` file from the build directory.
-CMake provides a separate generator for each Visual Studio release. For Visual Studio 2019 you would use
-the [`Visual Studio 16 2019`](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2016%202019.html) generator
+CMake provides a separate generator for each Visual Studio release. For Visual Studio 2022 you would use
+the [`Visual Studio 17 2022`](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2017%202022.html) generator
 and provide an additional architecture parameter:
 
 ```shell
-cmake -G "Visual Studio 16 2019" -A "X64" -S /path/to/source/dir -B /path/to/build/dir
+cmake -G "Visual Studio 17 2022" -A "X64" -S /path/to/source/dir -B /path/to/build/dir
 ```
 
 It is not possible to generate multi-arch solutions with CMake though. You need to create separate build directories and
@@ -102,9 +102,10 @@ using the `-D` switch.
 | CMake option        | Default | Required dependencies | Description                                                                                 |
 |---------------------|---------|-----------------------|---------------------------------------------------------------------------------------------|
 | `BUILD_TESTING`     | `OFF`   |                       | Builds the unit tests.                                                                      |
+| `BUILD_DOCS`        | `OFF`   | `Doxygen`, `Sphinx`   | Builds the API/developer documentation in `docs/`.                                          |
 | `BUILD_SHARED_LIBS` | `ON`    |                       | Build projectM as shared libraries. If `OFF`, build static libraries.                       |
 | `ENABLE_PLAYLIST`   | `ON`    |                       | Builds and installs the playlist library.                                                   |
-| `ENABLE_EMSCRIPTEN` | `OFF`   | `Emscripten`          | Build for the web using Emscripten. Only supports build as a static library and using GLES. |
+| `ENABLE_EMSCRIPTEN` | (auto)  | `Emscripten`          | Forced `ON` when building with the Emscripten toolchain, otherwise `OFF`. Not user-settable. |
 | `ENABLE_GLES`       | `OFF`   | `GLES`                | Use OpenGL ES 3 profile for rendering instead of the Core profile.                          |
 
 Note that `ENABLE_GLES` will be forcibly set to `ON` for Emscripten and Android builds, making it mandatory.
@@ -114,14 +115,17 @@ Note that `ENABLE_GLES` will be forcibly set to `ON` for Emscripten and Android
 The following table contains a list of build options which are only useful in special circumstances, e.g. when
 developing libprojectM, trying experimental features or building the library for a special use-case/environment.
 
-| CMake option             | Default | Required dependencies          | Description                                                                                                                                                                                                                                      |
-|--------------------------|---------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `ENABLE_SDL_UI`          | `ON`    | `SDL2`                         | Builds the SDL-based test application. Only used for development testing, will not be installed.                                                                                                                                                 |
-| `ENABLE_INSTALL`         | `OFF`   | Building as a CMake subproject | Enable projectM install targets when built as a subproject via `add_subdirectory()`.                                                                                                                                                             |
-| `ENABLE_DEBUG_POSTFIX`   | `ON`    |                                | Adds `d` (by default) to the name of any binary file in debug builds.                                                                                                                                                                            |
-| `ENABLE_SYSTEM_GLM`      | `OFF`   |                                | Builds against a system-installed GLM library.                                                                                                                                                                                                   |
-| `ENABLE_CXX_INTERFACE`   | `OFF`   |                                | Exports symbols for the `ProjectM` and `PCM` C++ classes and installs the additional the headers. Using the C++ interface is not recommended and unsupported.                                                                                    |
-| `ENABLE_VERBOSE_LOGGING` | `OFF`   |                                | Enables code for `TRACE` and `DEBUG` log levels in release builds. By default, these will only be compiled for `Debug` builds. Enabling this will negatively affect performance, even if the actual log level is set to `INFORMATION` or higher. |
+| CMake option                 | Default                          | Required dependencies          | Description                                                                                                                                                                                                                                      |
+|------------------------------|----------------------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ENABLE_SDL_UI`              | `OFF`                            | `SDL2`                         | Builds the SDL-based test application. Only used for development testing, will not be installed.                                                                                                                                                 |
+| `ENABLE_INSTALL`             | `ON` (top-level) / `OFF` (subproject) |                           | Enable projectM install targets. Automatically `ON` when built standalone, `OFF` when added via `add_subdirectory()`.                                                                                                                            |
+| `ENABLE_DEBUG_POSTFIX`       | `ON`                             |                                | Adds `d` (by default) to the name of any binary file in debug builds.                                                                                                                                                                            |
+| `ENABLE_SYSTEM_GLM`          | `OFF`                            |                                | Builds against a system-installed GLM library.                                                                                                                                                                                                   |
+| `ENABLE_SYSTEM_PROJECTM_EVAL`| `ON`                             |                                | Uses a system-installed projectM-eval library if found, otherwise the bundled sources in `vendor/`.                                                                                                                                              |
+| `ENABLE_BOOST_FILESYSTEM`    | `OFF`                            | `Boost`                        | Forces the use of `boost::filesystem` instead of `std::filesystem`. Only needed on toolchains without C++17 filesystem support.                                                                                                                  |
+| `ENABLE_MACOS_FRAMEWORK`     | `OFF`                            | macOS                          | Build as macOS Framework bundles instead of plain shared libraries.                                                                                                                                                                              |
+| `ENABLE_CXX_INTERFACE`       | `OFF`                            |                                | Exports symbols for the `ProjectM` and `PCM` C++ classes and installs the additional the headers. Using the C++ interface is not recommended and unsupported.                                                                                    |
+| `ENABLE_VERBOSE_LOGGING`     | `OFF`                            |                                | Enables code for `TRACE` and `DEBUG` log levels in release builds. By default, these will only be compiled for `Debug` builds. Enabling this will negatively affect performance, even if the actual log level is set to `INFORMATION` or higher. |
 
 ### Path options
 
@@ -236,7 +240,7 @@ Build targets - shared/static libraries and executables - are created in the sam
 the `CMakeLists.txt` file that defines the target in the source tree (which, in most cases, resides in the same
 directory as the source files). Depending on the generator used, the binaries are created directly in the directory for
 single-configuration generators (like `Unix Makefiles` or `Ninja`) and in a subdirectory with the configuration name,
-e.g. `Debug` or `Release`, for multi-configuration generators like `Xcode` or `Visual Studio 16 2019`.
+e.g. `Debug` or `Release`, for multi-configuration generators like `Xcode` or `Visual Studio 17 2022`.
 
 You may also find additional files and symbolic links in the same location depending on the platform, e.g. `.pdb` files
 on Windows.

BUILDING.md

@@ -17,8 +17,9 @@ Mandatory packages:
 sudo apt install build-essential cmake libgl1-mesa-dev mesa-common-dev
 ```
 
-**Important:** Depending on your distribution, the CMake package might be too old to build projectM, e.g. Debian 11 (
-bookworm) only provides CMake 3.18 while CMake 3.21 is required. In this case, get the latest CMake
+**Important:** projectM requires CMake 3.21 or newer. Current stable distributions already ship a new enough
+CMake (e.g. Debian 12 "bookworm" with CMake 3.25, Ubuntu 22.04 and newer with CMake 3.22+). Only end-of-life releases
+like Debian 11 "bullseye" (CMake 3.18) need a manual install, in which case get the latest CMake
 release [from Kitware's download page](https://cmake.org/download/).
 
 Optional packages:
@@ -49,9 +50,6 @@ git submodule update
 
 ### Build and install projectM
 
-Older projectM releases use autoconf/automake for building. If your repository has a `CMakeLists.txt` file on the top
-level, skip to the CMake part right below.
-
 Replace `/usr/local` with your preferred installation prefix.
 
 #### Configure the project using CMake
@@ -78,7 +76,9 @@ cmake --build . -- -j && sudo cmake --build . --target install
 
 #### Test projectM
 
-If you have a desktop environment installed, you can now run `[prefix]/bin/projectMSDL`.
+The SDL-based developer test UI is off by default. To build it, add `-DENABLE_SDL_UI=ON` to the configure command
+above (requires SDL2, e.g. `sudo apt install libsdl2-dev`). It is not installed; after building, run it from the build
+directory, e.g. `./src/sdl-test-ui/projectM-Test-UI`.
 
 ## Dependencies
 
@@ -88,7 +88,7 @@ development files. To build projectM, both binaries and development files need t
 #### General build dependencies for all platforms:
 
 * A working build toolchain (compiler, linker).
-* CMake 3.21 or highter.
+* CMake 3.21 or higher.
 * **OpenGL**: 3D graphics library. Used to render the visualizations.
 * **GLES3**: OpenGL libraries for embedded systems, version 3. Required to build projectM on mobile devices, Raspberry
   Pi and Emscripten.
@@ -284,7 +284,7 @@ libprojectM builds at least on the following platforms:
 - Windows
 - Linux
 - macOS (iOS/tvOS as well, but be aware that Apple's TOS may prevent its use in Store apps!)
-- BSD derivates
+- BSD derivatives
 - Android
 - WebGL/WASM (using emscripten)
 
@@ -320,9 +320,10 @@ automatically (e.g. OpenGL libraries) and have to be added manually depending on
 
 ### Frontends and audio capturing
 
-Previous projectM versions (before 4.0) came with several UIs and audio capture implementations. To reduce the size of
-the code base and separate the release cycles and development of the core library and the frontends, these have been
-removed from libprojectM and either being rewritten or moved into their own, separate Git repository.
+Previous projectM versions (before 4.0) shipped several UIs and audio capture implementations in this repository.
+To reduce the size of the code base and separate the release cycles of the core library and the frontends, these were
+moved into their own repositories under the [projectM-visualizer organization](https://github.com/projectM-visualizer)
+(e.g. the SDL-based desktop app and the Qt-based desktop app with PipeWire/PulseAudio/JACK backends).
 
 libprojectM on its own does not have any means of capturing audio, it simply takes PCM data via the API. Applications
 using projectM can supply this data from their own audio sources, e.g. music playing in an audio player or capturing

EMSCRIPTEN.md

@@ -5,7 +5,7 @@ OpenGL ES, but not identical, so a few additional considerations apply to get pr
 
 ## Additional Build Settings
 
-A few additional build settings will be required when building an Emscripten wrapper. Pass these flags/parameterrs to
+A few additional build settings will be required when building an Emscripten wrapper. Pass these flags/parameters to
 the Emscripten linker:
 
 - `-sUSE_SDL=2`: It is highly recommended to use Emscripten's built-in SDL2 port to set up the rendering context. This
@@ -18,7 +18,7 @@ the Emscripten linker:
 ## Initializing Emscripten's OpenGL Context
 
 In addition to the above linker flags, some additional initialization steps must be performed to set up the OpenGL
-rendering context for projectM. Specifically, the `OES_texture_float` WenGL extension must be loaded explicitly to
+rendering context for projectM. Specifically, the `OES_texture_float` WebGL extension must be loaded explicitly to
 support the required texture format for the motion vector grid. The following code template can be used to set up a
 proper SDL2/WebGL context for projectM:
 

README.md

@@ -29,23 +29,20 @@ source-code and binary releases of the projectM development libraries and header
 
 ### End-User Applications
 
-**Important**: projectM is currently undergoing heavy development, so the available end-user frontends are either
-outdated or unavailable. We've released a few development previews, which are not feature-complete and may have bugs. As
-soon as we've finished the current modernization of libprojectM, we'll release new and tested versions of most of the
-frontends listed below, while we may remove or replace some of those which are no longer maintained by their original
-developers.
+**Important**: projectM is currently undergoing heavy development. The available end-user frontends are
+development previews, which are not feature-complete and may have bugs.
 
 #### Windows
 
-- Standalone (currently only available as
-  a [development preview](https://github.com/kblaschke/frontend-sdl2/releases/tag/2.0-windows-pre3))
+- Standalone ([projectMSDL 2.0 pre-release](https://github.com/projectM-visualizer/frontend-sdl-cpp/releases))
 - [Steam](https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/) (Same as standalone development
   preview)
+- [Windows Store](https://www.microsoft.com/store/apps/9NDCVH0VCWJN) (Old 3.1.12 release)
 
 #### macOS
 
 - Standalone
-  - [C++ app development preview](https://github.com/kblaschke/frontend-sdl2/releases/tag/2.0-macos-pre1)
+  - [C++ app pre-release](https://github.com/projectM-visualizer/frontend-sdl-cpp/releases)
   - [Rust app development preview (signed)](https://github.com/projectM-visualizer/frontend-sdl-rust/releases/tag/v0.1.0)
 - [Steam](https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/) (Old 3.1.12 release)
 - Music.app Plugin  (currently only available as an
@@ -54,9 +51,8 @@ developers.
 
 #### Linux
 
-- Standalone (currently only available as
-  a [development preview](https://github.com/kblaschke/frontend-sdl2/releases/tag/2.0-linux-pre2) for Ubuntu 22.04 and
-  compatible distributions)
+- Standalone ([projectMSDL 2.0 pre-release](https://github.com/projectM-visualizer/frontend-sdl-cpp/releases), also
+  available as `.deb` and `.tar.gz`)
 - [Steam](https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/) (Same as standalone development
   preview)
 
@@ -81,9 +77,9 @@ Source code and other resources, mostly aimed at developers.
 
 - [Library source code](https://github.com/projectM-visualizer/projectm/) (this repository)
 - [GStreamer plugin](https://github.com/projectM-visualizer/gst-projectm/)
-- [Qt5](https://www.qt.io/) based [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) and JACK desktop
-  apps [as source code for Linux](https://github.com/projectM-visualizer/frontend-qt), currently broken and needs some
-  updating (help wanted!).
+- [Qt](https://www.qt.io/) based (Qt5/Qt6) desktop apps for Linux with
+  [PipeWire](https://pipewire.org/), [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) and JACK audio
+  backends ([source code](https://github.com/projectM-visualizer/frontend-qt), requires libprojectM 4.x).
 - [ALSA, XMMS, Winamp, JACK](https://sourceforge.net/projects/projectm/files/) (legacy 2.x sources for historic
   purposes, unmaintained since 2012)
 
@@ -226,8 +222,8 @@ If you maintain packages of libprojectM, we are happy to work with you! Please n
 - Many of the frontend applications are likely outdated and of less utility than the core library. If you desire to use
   them or depend on them, please file an issue in the respective repository so we can help update them.
 - The "canonical" application for actually viewing the visualizations is
-  now [projectM-SDL](https://github.com/projectM-visualizer/frontend-sdl2), based on libSDL2 because it supports audio
-  input and is completely cross-platform.
+  now [projectMSDL](https://github.com/projectM-visualizer/frontend-sdl-cpp), based on libSDL2 because it supports
+  audio input and is completely cross-platform.
 - If you like Rust, there is a [SDL3 rust frontend](https://github.com/projectM-visualizer/frontend-sdl-rust) in the works looking for contributors.
 - This is an open source project! If you don't like something, feel free to contribute improvements!
 - Yes, you are looking at the official version. This is not a fork.