From 6dc41faaf39039d1bb6e7148c7762d45cbc24015 Mon Sep 17 00:00:00 2001 From: Davy <95214375+thedavidweng@users.noreply.github.com> Date: Thu, 3 Sep 2026 03:58:14 -0700 Subject: [PATCH 1/2] Refresh stale end-user and build documentation --- BUILDING-cmake.md | 34 ++-- BUILDING.md | 23 +-- EMSCRIPTEN.md | 4 +- README.md | 28 ++- docs/building.rst | 420 +++----------------------------------------- docs/conf.py | 12 +- docs/emscripten.rst | 4 +- docs/index.rst | 77 ++++---- docs/llvm.rst | 21 --- 9 files changed, 111 insertions(+), 512 deletions(-) delete mode 100644 docs/llvm.rst diff --git a/BUILDING-cmake.md b/BUILDING-cmake.md index d169e3815d..f25da75ba9 100644 --- a/BUILDING-cmake.md +++ b/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. diff --git a/BUILDING.md b/BUILDING.md index 64b0415c4e..f99c1b4694 100644 --- a/BUILDING.md +++ b/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 diff --git a/EMSCRIPTEN.md b/EMSCRIPTEN.md index 59e76db961..224758981b 100644 --- a/EMSCRIPTEN.md +++ b/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: diff --git a/README.md b/README.md index 0c8658f229..011049a67f 100644 --- a/README.md +++ b/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. diff --git a/docs/building.rst b/docs/building.rst index 07b8735f4c..425d55221e 100644 --- a/docs/building.rst +++ b/docs/building.rst @@ -1,407 +1,31 @@ Building projectM from source ============================= -Suggested: use CMake. See `BUILDING-cmake.md <./BUILDING-cmake.md>`__. +libprojectM is built with CMake on all platforms. (The GNU Autotools +build was removed in projectM 4.0.) -This document describes the deprecated GNU Autotools setup. +The maintained build instructions live in the repository root and are +the single source of truth — this page only summarizes them: -Quick Start (Debian / Ubuntu) ------------------------------ - -For other operating systems (Windows/macOS), see the OS-specific -sections below. - -Install the build tools and dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Mandatory packages: - -.. code:: bash - - sudo apt install build-essential libgl1-mesa-dev mesa-common-dev libsdl2-dev libglm-dev - -Optional packages for additional features: - -.. code:: bash - - sudo apt install qtbase5-dev # For building Qt-based UIs - sudo apt install llvm-dev # for using the experimental LLVM Jit - sudo apt install libvisual-0.4-dev # To build the libvisual plug-in - sudo apt install libjack-jackd2-dev # To build the JACK visualizer application - sudo apt install ninja # To build projectM with Ninja instead of make - -Download the projectM sources -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you want to use a stable version of projectM, download the latest -release from the `Releases page on -GitHub `__ and -unpack it. You can then skip to the next step. - -If you prefer a bleeding-edge version or want to modify the code, clone -the Git repository and initialize any submodules: +- `BUILDING.md `__: + quick-start guide for Linux, macOS and Windows. +- `BUILDING-cmake.md `__: + all CMake build options and generators, plus how to use libprojectM + in other CMake-based projects. -.. code:: bash - - sudo apt install git # Probably already installed - git clone https://github.com/projectM-visualizer/projectm.git /path/to/local/repo - cd /path/to/local/repo - git fetch --all --tags - git submodule init - 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code:: bash - - sudo apt install cmake - mkdir build - cd build - cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local .. - -To generate Ninja scripts instead of Makefiles, add ``-GNinja`` to the -above command. - -Build and install -^^^^^^^^^^^^^^^^^ - -These commands will build projectM and install it to /usr/local or the -configured installation prefix set in the step before: +Quick start (Debian / Ubuntu) +----------------------------- .. code:: bash - cmake --build . -- -j && sudo cmake --build . --target install - -**Note**: You won’t need to use ``sudo`` if the install prefix is -writeable by your non-privileged user. - -Test projectM -^^^^^^^^^^^^^ - -If you have a desktop environment installed, you can now run -``[prefix]/bin/projectMSDL``. - -Dependencies ------------- - -Depending on the OS/distribution and packaging system, libraries might -be split into separate packages with binaries and development files. To -build projectM, both binaries and development files need to be -installed. - -General build dependencies for all platforms: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- A working build toolchain. -- **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. -- `glm `__: OpenGL Mathematics library. - Optional, will use a bundled version with autotools or if not - installed. -- `SDL2 `__: Simple Directmedia - Layer. Version 2.0.5 or higher is required to build the standalone - visualizer application (projectMSDL). - -Only relevant for Linux distributions, FreeBSD and macOS: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- `Qt5 `__: Qt cross-platform UI framework. Used to - build the Pulseaudio and JACK visualizer applications. Requires the - ``Gui`` and ``OpenGL`` component libraries/frameworks. -- `Pulseaudio `__: - Sound system for POSIX platforms. Required to build the Pulseaudio - visualizer application. -- `JACK `__: Real-time audio server. Required - to build the JACK visualizer application. -- `libvisual 0.4 `__: Audio visualization - library with plug-in support. Required to build the projectM - libvisual plug-in. -- `CMake `__: Used to generate platform-specific - build files. - -Only relevant for Windows: -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `vcpkg `__: C++ Library Manager - for Windows. Optional, but recommended to install the aforementioned - library dependencies and/or using CMake to configure the build. -- `NuGet `__: Dependency manager for .NET. - Required to build the EyeTune app. - -Building on Linux and macOS ---------------------------- - -Installing dependencies -~~~~~~~~~~~~~~~~~~~~~~~ - -- Linux distributions will have packages available for most (if not - all) required libraries. The package names and commands to install - them vary widely between distributions (and even versions of the same - distribution). Please refer to the documentation of your build OS on - how to find and install the required libraries. -- On \*BSD, install the appropriate Ports with ``pkg install``. -- On macOS, using `Homebrew `__ is the recommended - way of installing any dependencies not supplied by Xcode. - -Building with CMake -~~~~~~~~~~~~~~~~~~~ - --------------- - -:exclamation: **IMPORTANT NOTE**: Currently, CMake build support is -still in active development and considered unfinished. It is working and -produces running binaries, but there are still some features, build -internals and whole targets missing. While testing the CMake build files -on any platform and feedback on this is strongly encouraged, CMake-based -builds should not yet be used in any production environment until this -message is gone. - --------------- - -The steps documented below are a bare minimum quickstart guide on how to -build and install the project. If you want to configure the build to -your needs, require more in-depth information about the build process -and available tweaks, or on how to use libprojectM in your own -CMake-based projects, see `BUILDING-cmake.md `__. - -Using CMake is the recommended and future-proof way of building -projectM. CMake is a platform-independent tool that is able to generate -files for multiple build systems and toolsets while using only a single -set of build instructions. CMake support is still new and in -development, but will replace the other project files (automake/autoconf -scripts, Visual Studio solutions and Xcode projects) in this repository -once mature and stable. - -Building the project with CMake requires two steps: - -- Configure the build and generate project files. -- Build and install the project using the selected build tools. - -**Note:** When building with CMake, the build directory should always be -separate from the source directory. Generating the build files directly -inside the source tree is possible, but strongly discouraged. Using a -subdirectory, e.g. ``cmake-build`` inside the source directory is fine -though. - -This documentation only covers project-specific information. CMake is -way too versatile and feature-rich to cover any possible platform- and -toolset-specific configuration details here. If you are not experienced -in using CMake, please first read the `official CMake -documentation `__ (at least the -`User Interaction -Guide `__) -for basic usage instructions. - -Configure the build -^^^^^^^^^^^^^^^^^^^ - -Configuring a non-debug build with default options and install prefix -(``/usr/local``) can be done with these commands, building in a -subdirectory inside the source directory: - -.. code:: shell - - cd /path/to/source - mkdir cmake-build - cd cmake-build - cmake -DCMAKE_BUILD_TYPE=Release .. - -CMake will check all required dependencies and display any errors. If -configuration was successful, a summary of the build configuration is -printed and CMake should display a ``Generating done`` line. The project -is now ready to build. - -Compile and install the project -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Depending on your generator choice, you can use your selected toolset as -usual to build and install projectM: - -- With ``Unix Makefiles``, run ``make && sudo make install``. -- With ``Ninja``, run ``ninja && sudo ninja install``. -- With ``Xcode``, select the appropriate target and configuration in - Xcode and build it, or ``INSTALL`` to install the project. - -You can also use CMake’s build mode to run the selected toolset and -build any specified target. CMake knows which command to call and which -parameters to pass, so the syntax works on all platforms with all -generators. If you’ve already set the top-level build directory as -working directory, simply pass ``.`` as ``/path/to/build/dir``: - -.. code:: shell - - cmake --build /path/to/build/dir --config Release - sudo cmake --build /path/to/build/dir --config Release --target install - -If you don’t need root permissions to install running the second command -without ``sudo`` is sufficient. - -If you want to provide arguments directly to the toolset command, add -``--`` at the end of the CMake command line followed by any additional -arguments. CMake will pass these *unchanged and unchecked* to the -subcommand: - -.. code:: shell - - cmake --build /path/to/build/dir --config Release -- -j 4 - -Building on Windows -------------------- - -To build the projectM library and the SDL-based standalone application, -CMake must be used to create the project files first. Using vcpkg to -pull in the build dependencies is highly recommended, as CMake can’t use -NuGet (NuGet pulls in dependencies using the project files, while CMake -requires the libraries before creating the project files). - -Installing the dependencies with vcpkg -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As stated above, using vcpkg is the easiest way to get the required -dependencies. First, install `vcpkg from -GitHub `__ by following the official -guide. - -We’ve included a vcpkg manifest file in the repository root, designed to -automatically install dependencies when you create your solution. - -Creating the Visual Studio solution -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -CMake provides separate generators for different Visual Studio versions. -Newer CMake versions will support recent Visual Studio releases, but may -remove generators for older ones. To get a list of available generators -from the command line, use the ``-G`` switch without an argument. The -CMake GUI will present you a dropdown list you can easily select from. - -To set the build architecture in Visual Studio builds, use the ``-A`` -switch and specify either ``Win32`` or ``X64`` as the argument. If you -want to build for both architectures, create separate build directories -and configure them accordingly. - -To make CMake aware of the installed vcpkg packages, simply use the -provided toolchain file when configuring the projectM build by pointing -```CMAKE_TOOLCHAIN_FILE`` `__ -to it. - -Here is a full command line example to create a Visual Studio 2019 -solution for X64: - -.. code:: commandline - - cmake -G "Visual Studio 16 2019" -A "X64" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" - -If you use the CMake GUI, check the “Specify toolchain file for -cross-compiling” option in the first page of the configuration -assistant, then select the above ``vcpkg.cmake`` file on the second -page. - -Another option is to open the project folder in a recent Visual Studio -version as a CMake project and configure CMake using Visual Studio’s -JSON-based settings file. - -Building the solution -^^^^^^^^^^^^^^^^^^^^^ - -To build the project, open the generated solution in Visual Studio and -build it like any other solution. Each time the CMake files are changed, -Visual Studio will automatically regenerate the CMake build files and -reload the solution before continuing the build. Be aware that in old -Visual Studio versions (2015 and earlier) the reload-and-continue might -not work properly. - -You can also build the solution with msbuild via the command line, or -use CMake’s build wrapper to do that for you: - -.. code:: commandline - - cmake --build "" --config Release - -Using Ninja to build -^^^^^^^^^^^^^^^^^^^^ - -The Ninja build system is shipped with Visual Studio since version 2019 -and used by default if loading a CMake project directly from within the -IDE. Ninja can also be `installed -separately `__. - -To configure the build directory for Ninja, pass ``Ninja`` or -``Ninja Multi-Config`` as the argument for the ``-G`` switch. The -difference between both generators is that the former uses -``CMAKE_BUILD_TYPE`` to specify the configuration ( e.g. ``Debug`` or -``Release``) while the latter supports all configurations in a single -build directory, specified during build time. - -The architecture is determined from the toolset, so make sure to run the -commands in the correct Visual Studio command prompt, e.g. “Native Tools -for X64”. - -Configure and build for a single-configuration Release build with vcpkg: - -.. code:: commandline - - cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" - cmake --build "" - -Same, but using the multi-configuration generator: - -.. code:: commandline - - cmake -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" - cmake --build "" --config Release - -Notes on other platforms and features -------------------------------------- - -Raspberry Pi (and other embedded systems) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- projectM is arch-independent, although there are some SSE2 - enhancements for x86 -- `Notes on running on raspberry - pi `__ - -Build using NDK for Android -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To build projectM using the Android SDK, please refer to the official -NDK docs: - - https://developer.android.com/ndk/guides/cmake - -It is highly recommended using the latest NDK and CMake >= 3.21 for -building. - -libprojectM ------------ - -``libprojectM`` is the core library. It is made up of three -sub-libraries: - -Renderer -^^^^^^^^ - -Made up of everything in ``src/libprojectM/Renderer``. These files -compose the ``libRenderer`` sub-library. - -Assets -~~~~~~ - -``libprojectM`` can either have a configuration hard-coded or load from -a configuration file. It’s up to each application to decide how to load -the config file. The config file can have paths defined specifying where -to load fonts and presets from. - -You will want to install the config file and presets somewhere, and then -define that path for the application you’re trying to build. + sudo apt install build-essential cmake libgl1-mesa-dev mesa-common-dev + git clone https://github.com/projectM-visualizer/projectm.git + cd projectm + git submodule update --init + cmake -S . -B build -DCMAKE_BUILD_TYPE=Release + cmake --build build + sudo cmake --build build --target install + +projectM requires CMake 3.21 or newer. To additionally build the +SDL-based developer test UI, install ``libsdl2-dev`` and configure with +``-DENABLE_SDL_UI=ON``. diff --git a/docs/conf.py b/docs/conf.py index 7eb660b1db..db6281c24d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,7 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os +import os # import sys # sys.path.insert(0, os.path.abspath('.')) @@ -22,10 +22,10 @@ author = 'libprojectM committers' # The short X.Y version -version = '4.1.0' +version = '4.2.0' # The full version, including alpha/beta/rc tags -release = '4.1.0' +release = '4.2.0' # -- General configuration --------------------------------------------------- @@ -98,5 +98,9 @@ } # -- Extension configuration ------------------------------------------------- -breathe_projects = { "projectm_doxygen": "/home/dwagner/git/cmake-build-projectm/xml" } +# Path to the Doxygen XML output. Override with the PROJECTM_DOXYGEN_XML +# environment variable, e.g. point it at /xml after running the +# "projectm_doxygen" target (see BUILD_DOCS in BUILDING-cmake.md). +breathe_projects = {"projectm_doxygen": os.environ.get( + "PROJECTM_DOXYGEN_XML", "/home/dwagner/git/cmake-build-projectm/xml")} breathe_default_project = 'projectm_doxygen' \ No newline at end of file diff --git a/docs/emscripten.rst b/docs/emscripten.rst index 90803ee03b..a83b5084fa 100644 --- a/docs/emscripten.rst +++ b/docs/emscripten.rst @@ -10,7 +10,7 @@ Additional Build Settings ------------------------- A few additional build settings will be required when building an -Emscripten wrapper. Pass these flags/parameterrs to the Emscripten +Emscripten wrapper. Pass these flags/parameters to the Emscripten linker: - ``-sUSE_SDL=2``: It is highly recommended to use Emscripten’s @@ -29,7 +29,7 @@ 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 +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: diff --git a/docs/index.rst b/docs/index.rst index 8676e80905..744b28d2f1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,16 +4,15 @@ self building emscripten - llvm api/library_root |Windows Build Status| |Linux Build Status| |macOS Build Status| |Emscripten Build Status| |Android Build Status| |Discord Shield| `Chat with us on -Discord `__ +Discord `__ -.. figure:: https://github.com/projectM-visualizer/projectm/raw/master/web/logo.png +.. figure:: https://github.com/projectM-visualizer/projectm/raw/master/docs/web/logo.png :alt: Logo Logo @@ -47,30 +46,29 @@ libraries and headers, which aren’t useful for end users. 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 `__) +- Standalone (`projectMSDL 2.0 + pre-release `__) - `Steam `__ (Same as standalone development preview) - `Windows Store `__ - (Old 3.1.12 release ) + (Old 3.1.12 release) macOS ^^^^^ -- Standalone (currently only available as a `development - preview `__) +- Standalone + + - `C++ app + pre-release `__ + - `Rust app development preview + (signed) `__ - `Steam `__ (Old 3.1.12 release) - Music.app Plugin (currently only available as an *unsigned* @@ -82,9 +80,9 @@ macOS Linux ^^^^^ -- Standalone (currently only available as a `development - preview `__ - for Ubuntu 22.04 and compatible distributions) +- Standalone (`projectMSDL 2.0 + pre-release `__, + also available as ``.deb`` and ``.tar.gz``) - `Steam `__ (Same as standalone development preview) @@ -119,11 +117,12 @@ Source code and other resources, mostly aimed at developers. - `Library source code `__ (this repository) -- `Qt5 `__ based +- `Qt `__ based (Qt5/Qt6) desktop apps for Linux + with `PipeWire `__, `PulseAudio `__ - and JACK desktop apps `as source code for - Linux `__, - currently broken and needs some updating (help wanted!). + and JACK audio backends (`source + code `__, + requires libprojectM 4.x). - `ALSA, XMMS, Winamp, JACK `__ (legacy 2.x sources for historic purposes, unmaintained since 2012) @@ -131,12 +130,13 @@ Source code and other resources, mostly aimed at developers. Discord chat ~~~~~~~~~~~~ -`Chat with us on Discord! `__ +`Chat with us on Discord! `__ -Demo Video -~~~~~~~~~~ +Click For Demo Videos +~~~~~~~~~~~~~~~~~~~~~ -|image6| +A demo playlist is available on +`YouTube `__. Presets ~~~~~~~ @@ -169,9 +169,9 @@ Included with projectM are the bltc201, Milkdrop 1 and 2, projectM, tryptonaut and yin collections. You can grab these presets `here `__. -You can also download an enormous 41,000 preset pack of presets -`here `__ (123MB -zipped). +You can also download an enormous 130k+ presets from the MegaPack +`here `__ +(4.08GB zipped, incl. textures). Also Featured In ~~~~~~~~~~~~~~~~ @@ -241,8 +241,8 @@ Architecture Building from source -------------------- -See `BUILDING.md `__ and the `developer documentation in -the +See `BUILDING.md `__ +and the `developer documentation in the wiki `__. Using the library @@ -263,13 +263,6 @@ There are some open-source applications that make use of libprojectM which can be found in the `projectM organization’s repositories `__ and elsewhere. -Todo ----- - -- Improve projectM using the recently-released Milkdrop source (WIP). -- Update the various implementations using libprojectM. -- Update downstream projects with new versions. - Help ---- @@ -297,7 +290,7 @@ existing issue instead of opening a new ticket. Get in contact with us ---------------------- -`Chat with us on Discord. `__ +`Chat with us on Discord. `__ Contribute to projectM ---------------------- @@ -326,7 +319,7 @@ Please note well: help update them. - The “canonical” application for actually viewing the visualizations is now - `projectM-SDL `__, + `projectMSDL `__, based on libSDL2 because it supports audio input and is completely cross-platform. - This is an open source project! If you don’t like something, feel @@ -367,8 +360,6 @@ Wiki `__. .. |Android Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_android.yml/badge.svg?branch=master :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_android.yml .. |Discord Shield| image:: https://discordapp.com/api/guilds/737206408482914387/widget.png?style=shield -.. |image6| image:: http://img.youtube.com/vi/2dSam8zwSFw/0.jpg - :target: http://www.youtube.com/watch?v=2dSam8zwSFw .. |Kodi| image:: web/kodi.png .. |Helix| image:: web/helix.jpg .. |Silverjuke| image:: web/silverjuke.png diff --git a/docs/llvm.rst b/docs/llvm.rst deleted file mode 100644 index 92cb6b0623..0000000000 --- a/docs/llvm.rst +++ /dev/null @@ -1,21 +0,0 @@ -Building with LLVM JIT -~~~~~~~~~~~~~~~~~~~~~~ - -Install the LLVM libraries. I’ve used llvm-7 so far, see -http://apt.llvm.org/ for LLVM repositories. - -:: - - sudo apt-get install llvm-7-dev llvm-7-tools - -Then run these commands to configure - -:: - - ./autogen.sh && ./configure --enable-sdl --enable-qt --enable-llvm --prefix=$PWD/local - -And a clean build of course. - -:: - - make clean && make -j4 install From bc78b7f145094b90781b05b125e08d7a9cbc58ab Mon Sep 17 00:00:00 2001 From: Davy <95214375+thedavidweng@users.noreply.github.com> Date: Thu, 3 Sep 2026 05:10:24 -0700 Subject: [PATCH 2/2] Consolidate build docs into docs/building.rst per review feedback --- BUILDING-cmake.md | 317 ------------------- BUILDING.md | 330 -------------------- EMSCRIPTEN.md | 58 ---- README.md | 5 +- docs/building.rst | 760 ++++++++++++++++++++++++++++++++++++++++++++-- docs/conf.py | 2 +- docs/index.rst | 3 +- 7 files changed, 745 insertions(+), 730 deletions(-) delete mode 100644 BUILDING-cmake.md delete mode 100644 BUILDING.md delete mode 100644 EMSCRIPTEN.md diff --git a/BUILDING-cmake.md b/BUILDING-cmake.md deleted file mode 100644 index f25da75ba9..0000000000 --- a/BUILDING-cmake.md +++ /dev/null @@ -1,317 +0,0 @@ -# Building with CMake - -This file contains in-depth information for building with the CMake build system. - -## Quickstart - -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-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 -installation directory. - -From the project root, execute: - -```shell -mkdir build -cd build -cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/path/to/install-dir -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(projectM4)` in the other project's `CMakeLists.txt`. - -If you use other build systems, you have to specify the include and library paths manually. - -## Selecting a specific project file generator - -Building libprojectM does not require any specific CMake generator. It should work with any available generator, single- -and multi-config. - -To specify a CMake generator, use the `-G` switch, followed by the generator name. Some newer generators take an -additional architecture using the `-A` switch. To list all available generators available on your current platform, -leave out the generator name: - -```shell -cmake -G -``` - -Additional information on the supported generators can be -found [in the CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html). - -### Popular generators - -By default, CMake will use the [`Unix Makefiles`](https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html) -generator on Linux and macOS, which is a good choice and should work. Yet in some circumstances, you might want to -generate project files for a specific build tool or IDE: - -```shell -cmake -G "Unix Makefiles" -S /path/to/source/dir -B /path/to/build/dir -``` - -A common alternative is the [`Ninja`](https://cmake.org/cmake/help/latest/generator/Ninja.html) generator, which -requires `ninja` to be installed. It is mostly a `make` -replacement with less overhead and should work equally well. It is supported on all major platforms, including Windows: - -```shell -cmake -G Ninja -S /path/to/source/dir -B /path/to/build/dir -``` - -On macOS, CMake also supports the [`Xcode`](https://cmake.org/cmake/help/latest/generator/Xcode.html) generator. It will -create an `.xcodeproj` bundle which you can open in Xcode. It also adds support for automatic code signing, which might -be required if your application using projectM needs to be notarized for store deployment. - -```shell -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 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 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 -use the respective `-A` switch for each. - -## Project-specific configuration options - -CMake has no built-in way of printing all available configuration options. You can either refer to the -top-level `CMakeLists.txt` which contains a block of `option` and `cmake_dependent_option` commands, or use one of the -available CMake UIs which will display the options after configuring the project once. - -### Important build switches - -The following table also gives you an overview of important build options and their defaults. All options accept a -boolean -value (`YES`/`NO`, `TRUE`/`FALSE`, `ON`/`OFF` or `1`/`0`) and can be provided on the configuration-phase command line -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` | (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. - -### Experimental and application-dependent build switches - -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` | `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 - -There are also a few textual parameters that can be used to fine-tune the installation directories. Relative paths in -the following options are appended to the value -of [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) (which, on most UNIX -platforms, defaults to `/usr/local`): - -| CMake option | Default | Description | -|------------------------|----------------|--------------------------------------------------------------------------------------------| -| `CMAKE_INSTALL_PREFIX` | (OS dependent) | Base directory where the projectM libraries, includes and support files will be installed. | -| `PROJECTM_BIN_DIR` | `bin` | Directory where executables (e.g. the SDL standalone application) are installed. | -| `PROJECTM_LIB_DIR` | `lib[64]` | Directory where libprojectM is installed. | -| `PROJECTM_INCLUDE_DIR` | `include` | Directory where the libprojectM include files will be installed under. | - -### Other options - -Various other options for specific needs. - -| CMake option | Default | Description | -|----------------------------|----------------------------------------|-------------------------------------------------------------------------------------------------------------------| -| `CMAKE_DEBUG_POSTFIX` | `d` (if `ENABLE_DEBUG_POSTFIX` is set) | Postfix appended to debug libraries. | -| `CMAKE_INSTALL_BINDIR` | `bin` | Another way to specify the binary installation directory. Used as default value for `PROJECTM_BIN_DIR`. | -| `CMAKE_INSTALL_LIBDIR` | `lib` or `lib64` | Another way to specify the library installation directory. Used as default value for `PROJECTM_LIB_DIR`. | -| `CMAKE_INSTALL_INCLUDEDIR` | `include` | Another way to specify the include file installation directory. Used as default value for `PROJECTM_INCLUDE_DIR`. | - -## Always perform out-of-tree builds! - -Most classic IDEs and build systems directly make use of the source tree and create project files, temporary build -artifacts (e.g. object files) and the final binaries in the same directory structure as the source files. An advantage -of this approach is that you can find all compiled binaries side-by-side with their sources and generated headers are -already in the same directories as the source files including them. This approach has some drawbacks though: - -- Only a single build configuration is supported as files are overwritten in-place. -- A lot of noise is created in the source directory, making it hard to distinguish between generated and original source - files. -- A very large `.gitignore` file is required to cover all unwanted files. -- Mistakes in the build scripts can overwrite source files, causing errors and destroy uncommitted work. - -Some of these can be mitigated by providing additional targets (`make clean` and `make distclean`) or creating -subdirectories for Debug/Release build configurations. - -While CMake also supports in-tree builds, it is "discouraged" in the official documentation, for the above reasons. -Building out-of-tree allows it to create multiple build directories with different configurations which do not influence -each other in any way. If a build directory contains unwanted artifacts, and you want to start fresh, simply delete and -recreate the whole directory - no work is lost. - -This project follow this principle by treating the original source tree as read-only and avoiding potential conflicts: - -- Everything under [`CMAKE_SOURCE_DIR`](https://cmake.org/cmake/help/latest/variable/CMAKE_SOURCE_DIR.html) must only be - read, never changed or written to. -- Everything under [`CMAKE_BINARY_DIR`](https://cmake.org/cmake/help/latest/variable/CMAKE_BINARY_DIR.html) is temporary - and related to the current build configuration. -- When generating configuration-dependent files, - use [`CMAKE_CONFIGURATION_TYPES`](https://cmake.org/cmake/help/latest/variable/CMAKE_CONFIGURATION_TYPES.html) - and [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) to create non-conflicting - files in the build tree. - -While this project will not force you to build out-of-tree, there is no mechanism to clean up the generated files after -running cmake in-tree. - -## CMake build directory layout - -If you are new to CMake, the way of how CMake creates the build directory and where it creates the build targets might -be confusing. Here is a summary of what's in the build directory and how it is structured in general. - -### Using files from the build tree - -It is generally not good practice to directly take binaries and other files from the build tree for packaging, for -several reasons: - -1. The directory structure is generated by CMake and depends on the generator used. The layout might change between - CMake versions, even for the same generator. -2. On platforms with RPATH support, CMake will store absolute paths in executables and shared libraries which point to - the absolute paths of any linked dependencies, either from the build tree or external libraries as well. These - binaries are not relocatable and will most certainly not work if run on any other computer (or even on the same after - deleting the build directory). -3. For some configurations, even Release build artifacts may contain debug symbols until they are installed. - -It is fine to build and run executables from the build directory for development and debugging. For packaging or using -libprojectM in other projects, always use the `install` target and copy files from there. - -### Generated files - -In the top-level build directory, CMake creates a few files that are present on any platform: - -- `CMakeCache.txt`: This file contains all variables and build settings CMake needs to remember from the first - configuration run. This file can be edited on demand either manually or using a CMake UI to change any values. On the - next build, CMake will regenerate the project files if this file has been modified. -- `cmake_install.cmake`: Contains generated install-related settings. -- `install_manifest.txt`: After installing the project, this file contains a list with absolute filenames of all - installed files. It can be used for packaging or deleting installed files as CMake doesn't define an `uninstall` - target. -- The top-level project file for use with the selected build toolset, e.g. `Makefile`, `build.ninja`, `projectm.sln` - or `projectm.xcodeproj`, plus additional toolset-specific files. - -The projectM build files generate additional files used in the build and install phases. These are scattered over the -build tree, but installed into the proper directories. Do not try and gather these files yourself from the build tree. - -### Subdirectory structure - -The rest of the directory structure generally resembles the source tree. Source directories containing -a `CMakeLists.txt` file will also be created in the build tree with the same relative path. Each of these subdirectories -contains a `CMakeFiles` directory with CMake-internal data, generated project files for the select toolset, e.g. -makefiles and any temporary compile artifacts. - -The directory structure is created by CMake and may change depending on the generator and CMake version used. - -### Executable and library locations - -Build targets - shared/static libraries and executables - are created in the same subdirectory in the build tree as -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 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. - -## Using libprojectM in other CMake projects - -The projectM library can be used as a static library or shared library in other CMake-based projects to provide embedded -audio visualization. It is highly recommended to build projectM as shared libraries for maximum compatibility and LGPL -compliance. - -The build directory is not structured in a way that other projects can make use of it. Use the `install` target to copy -all required files to the configured installation prefix. You can customize the subdirectories for libraries, includes -and binaries using the `PROJECTM_>_DIR` variables when configuring the CMake project. - -### Importing libprojectM targets from the build tree - -This approach is not recommended, but can be useful for projects that either require more in-depth access to the -projectM library files, especially to headers that are not installed as part of the public API. This might cause issues -if the internal headers change, but gives a broader set of features and more control to the developer. - -Please refer to the [`ExternalProject`](https://cmake.org/cmake/help/latest/module/ExternalProject.html) CMake module -documentation on how to set up the libprojectM build system for use in another project. - -### Importing libprojectM targets from an installed version - -This is the recommended and supported way of importing libprojectM in your project. This project installs a set of CMake -files in `//cmake/projectM4`, containing target definitions, version and dependency checks as well as -any additional libraries required for linking. Other projects then use CMake's `find_package` command to search for -these files in [different locations](https://cmake.org/cmake/help/latest/command/find_package.html#search-procedure). - -In the case projectM libraries and headers are not installed in any system search path, you need to add either the -install prefix path (the top-level install dir) or the directory containing the libraries (the `lib` dir by default) to -the [`CMAKE_PREFIX_PATH`](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html) list. - -If the package was found, you can then link against libprojectM by using the `libprojectM::projectM` target. - -Depending on how the package was built, targets might be available for multiple configurations or only `Release`. CMake -will automatically select the most appropriate one to link. - -Include dirs, additional link dependencies and possible compiler options will be propagated to any target the library is -linked to. - -#### Using the optional playlist library - -If you want to use the optional playlist library, you need to specifically request it as a component: - -```cmake -find_package(projectM4 COMPONENTS Playlist) -``` - -You can either use `REQUIRED` to force a fatal error if the component cannot be found or check if the target exists -using: - -```cmake -if(TARGET libprojectM::playlist) - # ... -endif() -``` - -If you link the playlist library, the main `libprojectM::projectM` target will be linked automatically as a dependency. - -#### Example - -Searches for projectM and the playlist library and links both to the application: - -```cmake -find_package(projectM4 REQUIRED COMPONENTS Playlist) - -add_executable(MyApp main.cpp) - -target_link_libraries(MyApp PRIVATE - libprojectM::playlist - ) -``` diff --git a/BUILDING.md b/BUILDING.md deleted file mode 100644 index f99c1b4694..0000000000 --- a/BUILDING.md +++ /dev/null @@ -1,330 +0,0 @@ -# Building projectM from source - -Since version 4.0, projectM uses CMake to configure and build the library on all platforms. - -This file only contains quick-start build instructions. For a more detailed guide and a list of all build options, -please read the [BUILDING-cmake.md](BUILDING-cmake.md) file. - -## Quick Start (Debian / Ubuntu) - -For other operating systems (Windows/macOS), see the OS-specific sections below. - -### Install the build tools and dependencies - -Mandatory packages: - -```bash -sudo apt install build-essential cmake libgl1-mesa-dev mesa-common-dev -``` - -**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: - -```bash -sudo apt install ninja-build # To build projectM with Ninja instead of make -sudo apt install libsdl2-dev # To build the development test UI -``` - -### Download the projectM sources - -For production use, it is highly recommended to use the latest stable version of projectM. Download the latest release -from the [Releases page on GitHub](https://github.com/projectM-visualizer/projectm/releases) and unpack it. - -#### Using a development version - -If you prefer a bleeding-edge version or want to modify the code, clone the Git repository and initialize any -submodules: - -```bash -sudo apt install git # Probably already installed -git clone https://github.com/projectM-visualizer/projectm.git /path/to/local/repo -cd /path/to/local/repo -git fetch --all --tags -git submodule init -git submodule update -``` - -### Build and install projectM - -Replace `/usr/local` with your preferred installation prefix. - -#### Configure the project using CMake - -```bash -sudo apt install cmake -mkdir build -cd build -cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local .. -``` - -To generate Ninja scripts instead of Makefiles, add `-GNinja` to the above command. - -#### Build and install - -These commands will build projectM and install it to /usr/local or the configured installation prefix set in the step -before: - -```bash -cmake --build . -- -j && sudo cmake --build . --target install -``` - -**Note**: You won't need to use `sudo` if the install prefix is writeable by your non-privileged user. - -#### Test projectM - -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 - -Depending on the OS/distribution and packaging system, libraries might be split into separate packages with binaries and -development files. To build projectM, both binaries and development files need to be installed. - -#### General build dependencies for all platforms: - -* A working build toolchain (compiler, linker). -* 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. -* [**glm**](https://github.com/g-truc/glm): OpenGL Mathematics library. It is optional, projectM will use a bundled - version if not installed. -* [**SDL2**](https://github.com/libsdl-org/SDL): Simple Directmedia Layer. Version 2.0.5 or higher is required to build - the development test application in the build directory. -* [**vcpkg**](https://github.com/microsoft/vcpkg): C++ Dependency Manager. Optional, but recommended to install - library dependencies and/or using CMake to configure the build. Mainly used on Windows, but also works for Linux and - macOS. - -## Building on Linux and macOS - -### Installing dependencies - -- Linux distributions will have packages available for most (if not all) required libraries. The package names and - commands to install them vary widely between distributions (and even versions of the same distribution). Please refer - to the documentation of your build OS on how to find and install the required libraries. -- On *BSD, install the appropriate Ports with `pkg install`. -- On macOS, a working Xcode installation is required. CMake (and libSDL2 for the test UI) can be installed - using [Homebrew](https://brew.sh/). - -### Building - -The steps documented below are a bare minimum quickstart guide on how to build and install the project. If you want to -configure the build to your needs, require more in-depth information about the build process and available tweaks, or on -how to use libprojectM in your own CMake-based projects, see [BUILDING-cmake.md](BUILDING-cmake.md). - -Using CMake is the only supported way of building projectM since version 4.0. CMake is a platform-independent tool that -is able to generate files for multiple build systems and toolsets while using only a single set of build instructions. - -Building the project with CMake requires two steps: - -- Configure the build and generate project files. -- Build and install the project using the selected build tools. - -**Note:** The build directory should always be different from the source directory. Generating the build files directly -inside the source tree is possible, but strongly discouraged. Using a subdirectory, e.g. `cmake-build` inside the source -directory is fine though. - -This documentation only covers project-specific information. CMake is way too versatile and feature-rich to cover any -possible platform- and toolset-specific configuration details here. If you are not experienced in using CMake, please -first read the [official CMake documentation](https://cmake.org/cmake/help/latest/) (at least -the [User Interaction Guide](https://cmake.org/cmake/help/latest/guide/user-interaction/index.html)) for basic usage -instructions. - -#### Configure the build - -Configuring a non-debug build with default options and install prefix (`/usr/local`) can be done with these commands, -building in a subdirectory inside the source directory: - -```shell -cd /path/to/source -mkdir cmake-build -cd cmake-build -cmake -DCMAKE_BUILD_TYPE=Release .. -``` - -CMake will check all required dependencies and display any errors. If configuration was successful, a summary of the -build configuration is printed and CMake should display a `Generating done` line. The project is now ready to build. - -#### Compile and install the project - -Depending on your generator choice, you can use your selected toolset as usual to build and install projectM: - -- With `Unix Makefiles`, run `make && sudo make install`. -- With `Ninja`, run `ninja && sudo ninja install`. -- With `Xcode`, select the appropriate target and configuration in Xcode and build it, or `INSTALL` to install the - project. - -You can also use CMake's build mode to run the selected toolset and build any specified target. CMake knows which -command to call and which parameters to pass, so the syntax works on all platforms with all generators. If you've -already set the top-level build directory as working directory, simply pass `.` as `/path/to/build/dir`: - -```shell -cmake --build /path/to/build/dir --config Release -sudo cmake --build /path/to/build/dir --config Release --target install -``` - -If you don't need root permissions to install to the given path, running the second command without `sudo` is -sufficient. - -To control how many files are compiled in parallel, pass the `--parallel N` argument to the build command, with `N` -being the number of concurrent compile commands. If not given explicitly, the build processor (make, ninja, MSBuild, -xcodebuild etc.) will decide the limit, which may range from one file at a time to all files at once. - -If you want to provide arguments directly to the toolset command, add `--` at the end of the CMake command line followed -by any additional arguments. CMake will pass these *unchanged and unchecked* to the subcommand: - -```shell -cmake --build /path/to/build/dir --config Release -- -``` - -## Building on Windows - -To build the projectM library and the SDL-based standalone application, CMake must be used to create the project files -first. Using vcpkg to pull in the build dependencies is highly recommended, as CMake can't use NuGet (NuGet pulls in -dependencies using the project files, while CMake requires the libraries before creating the project files). - -#### Installing the dependencies with vcpkg - -As stated above, using vcpkg is the easiest way to get the required dependencies. First, -install [vcpkg from GitHub](https://github.com/microsoft/vcpkg) by following the official guide. - -We've included a vcpkg manifest file in the repository root, designed to automatically install dependencies when you -create your solution. - -#### Creating the Visual Studio solution - -CMake provides separate generators for different Visual Studio versions. Newer CMake versions will support recent Visual -Studio releases, but may remove generators for older ones. To get a list of available generators from the command line, -use the `-G` switch without an argument. The CMake GUI will present you a dropdown list you can easily select from. - -To set the build architecture in Visual Studio builds, use the `-A` switch and specify either `Win32` or `X64` as the -argument. If you want to build for both architectures, create separate build directories and configure them accordingly. - -To make CMake aware of the installed vcpkg packages, simply use the provided toolchain file when configuring the -projectM build by -pointing [`CMAKE_TOOLCHAIN_FILE`](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html) to it. - -Here is a full command line example to create a Visual Studio 2022 solution for X64: - -```commandline -cmake -G "Visual Studio 17 2022" -A "X64" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" -``` - -If you use the CMake GUI, check the "Specify toolchain file for cross-compiling" option in the first page of the -configuration assistant, then select the above `vcpkg.cmake` file on the second page. - -Another option is to open the project folder in a recent Visual Studio version as a CMake project and configure CMake -using Visual Studio's JSON-based settings file. - -#### Building the solution - -To build the project, open the generated solution in Visual Studio and build it like any other solution. Each time the -CMake files are changed, Visual Studio will automatically regenerate the CMake build files and reload the solution -before continuing the build. Be aware that in old Visual Studio versions (2015 and earlier) the reload-and-continue -might not work properly. - -You can also build the solution with msbuild via the command line, or use CMake's build wrapper to do that for you: - -```commandline -cmake --build "" --config Release -``` - -#### Using Ninja to build - -The Ninja build system is shipped with Visual Studio since version 2019 and used by default if loading a CMake project -directly from within the IDE. Ninja can also be [installed separately](https://github.com/ninja-build/ninja/releases). - -To configure the build directory for Ninja, pass `Ninja` or `Ninja Multi-Config` as the argument for the `-G` switch. -The difference between both generators is that the former uses `CMAKE_BUILD_TYPE` to specify the configuration ( -e.g. `Debug` or `Release`) while the latter supports all configurations in a single build directory, specified during -build time. - -The architecture is determined from the toolset, so make sure to run the commands in the correct Visual Studio command -prompt, e.g. "Native Tools for X64". - -Configure and build for a single-configuration Release build with vcpkg: - -```commandline -cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" -cmake --build "" -``` - -Same, but using the multi-configuration generator: - -```commandline -cmake -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" -cmake --build "" --config Release -``` - -## Notes on other platforms and features - -### Supported platforms - -libprojectM is designed to be compatible with as many platforms and architectures as possible. Thus, the code base -doesn't use any non-portable code like OS-specific APIs or assembly instructions. - -The code compiles for the following target architectures: - -- i686 (x32 / x86) -- x86_64 (x64) -- armv7 (arm) -- aarch64 (arm64 / armv8) -- WASM - -Other architectures such as PPC, RISC and MIPS should be supported as well. Big-endian support is untested and thus -might be buggy. - -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 derivatives -- Android -- WebGL/WASM (using emscripten) - -As long as a platform provides OpenGL Core 3.3 or OpenGL ES 3.2 libraries and supports at least C++ 14, libprojectM -should build fine. - -### Raspberry Pi (and other embedded systems) - -Make sure to enable GLES support by passing `-DENABLE_GLES=TRUE` to CMake's configuration command and install the -appropriate OS libraries. Otherwise, follow the Linux build instructions above. - -For applications using projectM, it's highly recommended to keep certain performance-related settings low, such as: - -- The per-point mesh resolution should be kept low, e.g. 48x32 -- The rendering resolution should not exceed 720p on the Pi, though most presets will also run at ~60 FPS in 1080p - -### Build using NDK for Android - -To build projectM using the Android SDK, please refer to the official NDK docs: - -> https://developer.android.com/ndk/guides/cmake - -It is highly recommended using the latest NDK and CMake >= 3.21 for building. - -### Using libprojectM with pkgconfig - -Some UNIX build systems cannot use CMake config packages, like GNU autotools. To use libprojectM with such build -systems, projectM's build system also creates basic `.pc` files during the installation process. - -Note that the resulting pkgconfig files will not necessarily work in all circumstances, because they are much less -flexible than CMake (or Meson). When using pkgconfig, some required libraries will probably not be linked -automatically (e.g. OpenGL libraries) and have to be added manually depending on the application needs. - -### Frontends and audio capturing - -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 -audio data from OS or other external sources. diff --git a/EMSCRIPTEN.md b/EMSCRIPTEN.md deleted file mode 100644 index 224758981b..0000000000 --- a/EMSCRIPTEN.md +++ /dev/null @@ -1,58 +0,0 @@ -# Using libprojectM in Emscripten - -projectM supports OpenGL ES rendering, and can be compiled into WebAssembly for use in browsers. WebGL is similar to -OpenGL ES, but not identical, so a few additional considerations apply to get projectM running with Emscripten. - -## Additional Build Settings - -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 - flag will link the appropriate library. -- `-sMIN_WEBGL_VERSION=2 -sMAX_WEBGL_VERSION=2`: Forces the use of WebGL 2, which is required for OpenGL ES 3 emulation. -- `-sFULL_ES2=1 -sFULL_ES3=1`: Enables full emulation support for both OpenGL ES 2.0 and 3.0 variants. -- `-sALLOW_MEMORY_GROWTH=1`: Allows allocating additional memory if necessary. This may be required to load additional - textures etc. in projectM. - -## 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` 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: - -```c - -#include -#include - -#include - -#include - -int main(void) -{ - // Init SDL's video and audio subsystems - SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO); - - // Create the SDL window (will be tied to the Emscripten HTML5 canvas) - SDL_window* window = NULL; - SDL_renderer* renderer = NULL; - SDL_CreateWindowAndRenderer(1024, 768, SDL_WINDOW_OPENGL, &window, &renderer); - if (window == NULL || renderer == NULL) - { - fprintf(stderr, "Failed to create SDL renderer: %s\n", SDL_GetError()); - return 1; - } - - // Enable floating-point texture support for motion vector grid. - auto webGlContext = emscripten_webgl_get_current_context(); - emscripten_webgl_enable_extension(webGlContext, "OES_texture_float"); - - // Initialize projectM and put all other stuff below. - - return 0; -} - -``` \ No newline at end of file diff --git a/README.md b/README.md index 011049a67f..66be1e0596 100644 --- a/README.md +++ b/README.md @@ -156,7 +156,10 @@ development team. Please report bugs in those applications to their respective d # Building from source -See [BUILDING.md](BUILDING.md) and +See [the build guide](https://github.com/projectM-visualizer/projectm/blob/master/docs/building.rst) for +instructions on building libprojectM from source, including the full CMake reference, +[the Emscripten guide](https://github.com/projectM-visualizer/projectm/blob/master/docs/emscripten.rst) for +WebAssembly builds, and the [developer documentation in the wiki](https://github.com/projectM-visualizer/projectm/wiki/Building-libprojectM). # Using the library diff --git a/docs/building.rst b/docs/building.rst index 425d55221e..32707f05de 100644 --- a/docs/building.rst +++ b/docs/building.rst @@ -1,31 +1,749 @@ Building projectM from source ============================= -libprojectM is built with CMake on all platforms. (The GNU Autotools -build was removed in projectM 4.0.) +Since version 4.0, projectM uses CMake to configure and build the library on all platforms. -The maintained build instructions live in the repository root and are -the single source of truth — this page only summarizes them: +This guide contains both the quick-start build instructions and the in-depth CMake reference. For WebAssembly +builds, see :doc:`emscripten`. -- `BUILDING.md `__: - quick-start guide for Linux, macOS and Windows. -- `BUILDING-cmake.md `__: - all CMake build options and generators, plus how to use libprojectM - in other CMake-based projects. - -Quick start (Debian / Ubuntu) +Quick Start (Debian / Ubuntu) ----------------------------- +For other operating systems (Windows/macOS), see the OS-specific sections below. + +Install the build tools and dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mandatory packages: + .. code:: bash sudo apt install build-essential cmake libgl1-mesa-dev mesa-common-dev - git clone https://github.com/projectM-visualizer/projectm.git - cd projectm - git submodule update --init - cmake -S . -B build -DCMAKE_BUILD_TYPE=Release - cmake --build build - sudo cmake --build build --target install - -projectM requires CMake 3.21 or newer. To additionally build the -SDL-based developer test UI, install ``libsdl2-dev`` and configure with -``-DENABLE_SDL_UI=ON``. + +**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 `__. + +Optional packages: + +.. code:: bash + + sudo apt install ninja-build # To build projectM with Ninja instead of make + sudo apt install libsdl2-dev # To build the development test UI + +Download the projectM sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For production use, it is highly recommended to use the latest stable version of projectM. Download the latest release +from the `Releases page on GitHub `__ and unpack it. + +Using a development version +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you prefer a bleeding-edge version or want to modify the code, clone the Git repository and initialize any +submodules: + +.. code:: bash + + sudo apt install git # Probably already installed + git clone https://github.com/projectM-visualizer/projectm.git /path/to/local/repo + cd /path/to/local/repo + git fetch --all --tags + git submodule init + git submodule update + +Build and install projectM +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Replace ``/usr/local`` with your preferred installation prefix. + +Configure the project using CMake +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: bash + + sudo apt install cmake + mkdir build + cd build + cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local .. + +To generate Ninja scripts instead of Makefiles, add ``-GNinja`` to the above command. + +Build and install +^^^^^^^^^^^^^^^^^ + +These commands will build projectM and install it to /usr/local or the configured installation prefix set in the step +before: + +.. code:: bash + + cmake --build . -- -j && sudo cmake --build . --target install + +**Note**: You won't need to use ``sudo`` if the install prefix is writeable by your non-privileged user. + +Test projectM +^^^^^^^^^^^^^ + +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 +------------ + +Depending on the OS/distribution and packaging system, libraries might be split into separate packages with binaries and +development files. To build projectM, both binaries and development files need to be installed. + +General build dependencies for all platforms: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* A working build toolchain (compiler, linker). +* 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. +* `glm `__: OpenGL Mathematics library. It is optional, projectM will use a bundled + version if not installed. +* `SDL2 `__: Simple Directmedia Layer. Version 2.0.5 or higher is required to build + the development test application in the build directory. +* `vcpkg `__: C++ Dependency Manager. Optional, but recommended to install + library dependencies and/or using CMake to configure the build. Mainly used on Windows, but also works for Linux and + macOS. + +Building on Linux and macOS +--------------------------- + +Installing dependencies +~~~~~~~~~~~~~~~~~~~~~~~ + +- Linux distributions will have packages available for most (if not all) required libraries. The package names and + commands to install them vary widely between distributions (and even versions of the same distribution). Please refer + to the documentation of your build OS on how to find and install the required libraries. +- On *BSD*, install the appropriate Ports with ``pkg install``. +- On macOS, a working Xcode installation is required. CMake (and libSDL2 for the test UI) can be installed + using `Homebrew `__. + +Building +~~~~~~~~ + +The steps documented below are a bare minimum quickstart guide on how to build and install the project. If you want to +configure the build to your needs, require more in-depth information about the build process and available tweaks, or on +how to use libprojectM in your own CMake-based projects, see the `Building with CMake`_ reference section below. + +Using CMake is the only supported way of building projectM since version 4.0. CMake is a platform-independent tool that +is able to generate files for multiple build systems and toolsets while using only a single set of build instructions. + +Building the project with CMake requires two steps: + +- Configure the build and generate project files. +- Build and install the project using the selected build tools. + +**Note:** The build directory should always be different from the source directory. Generating the build files directly +inside the source tree is possible, but strongly discouraged. Using a subdirectory, e.g. ``cmake-build`` inside the source +directory is fine though. + +This documentation only covers project-specific information. CMake is way too versatile and feature-rich to cover any +possible platform- and toolset-specific configuration details here. If you are not experienced in using CMake, please +first read the `official CMake documentation `__ (at least +the `User Interaction Guide `__) for basic usage +instructions. + +Configure the build +^^^^^^^^^^^^^^^^^^^ + +Configuring a non-debug build with default options and install prefix (``/usr/local``) can be done with these commands, +building in a subdirectory inside the source directory: + +.. code:: shell + + cd /path/to/source + mkdir cmake-build + cd cmake-build + cmake -DCMAKE_BUILD_TYPE=Release .. + +CMake will check all required dependencies and display any errors. If configuration was successful, a summary of the +build configuration is printed and CMake should display a ``Generating done`` line. The project is now ready to build. + +Compile and install the project +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Depending on your generator choice, you can use your selected toolset as usual to build and install projectM: + +- With ``Unix Makefiles``, run ``make && sudo make install``. +- With ``Ninja``, run ``ninja && sudo ninja install``. +- With ``Xcode``, select the appropriate target and configuration in Xcode and build it, or ``INSTALL`` to install the + project. + +You can also use CMake's build mode to run the selected toolset and build any specified target. CMake knows which +command to call and which parameters to pass, so the syntax works on all platforms with all generators. If you've +already set the top-level build directory as working directory, simply pass ``.`` as ``/path/to/build/dir``: + +.. code:: shell + + cmake --build /path/to/build/dir --config Release + sudo cmake --build /path/to/build/dir --config Release --target install + +If you don't need root permissions to install to the given path, running the second command without ``sudo`` is +sufficient. + +To control how many files are compiled in parallel, pass the ``--parallel N`` argument to the build command, with ``N`` +being the number of concurrent compile commands. If not given explicitly, the build processor (make, ninja, MSBuild, +xcodebuild etc.) will decide the limit, which may range from one file at a time to all files at once. + +If you want to provide arguments directly to the toolset command, add ``--`` at the end of the CMake command line followed +by any additional arguments. CMake will pass these *unchanged and unchecked* to the subcommand: + +.. code:: shell + + cmake --build /path/to/build/dir --config Release -- + +Building on Windows +------------------- + +To build the projectM library and the SDL-based standalone application, CMake must be used to create the project files +first. Using vcpkg to pull in the build dependencies is highly recommended, as CMake can't use NuGet (NuGet pulls in +dependencies using the project files, while CMake requires the libraries before creating the project files). + +Installing the dependencies with vcpkg +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As stated above, using vcpkg is the easiest way to get the required dependencies. First, +install `vcpkg from GitHub `__ by following the official guide. + +We've included a vcpkg manifest file in the repository root, designed to automatically install dependencies when you +create your solution. + +Creating the Visual Studio solution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CMake provides separate generators for different Visual Studio versions. Newer CMake versions will support recent Visual +Studio releases, but may remove generators for older ones. To get a list of available generators from the command line, +use the ``-G`` switch without an argument. The CMake GUI will present you a dropdown list you can easily select from. + +To set the build architecture in Visual Studio builds, use the ``-A`` switch and specify either ``Win32`` or ``X64`` as the +argument. If you want to build for both architectures, create separate build directories and configure them accordingly. + +To make CMake aware of the installed vcpkg packages, simply use the provided toolchain file when configuring the +projectM build by +pointing `CMAKE_TOOLCHAIN_FILE `__ to it. + +Here is a full command line example to create a Visual Studio 2022 solution for X64: + +.. code:: console + + cmake -G "Visual Studio 17 2022" -A "X64" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" + +If you use the CMake GUI, check the "Specify toolchain file for cross-compiling" option in the first page of the +configuration assistant, then select the above ``vcpkg.cmake`` file on the second page. + +Another option is to open the project folder in a recent Visual Studio version as a CMake project and configure CMake +using Visual Studio's JSON-based settings file. + +Building the solution +~~~~~~~~~~~~~~~~~~~~~ + +To build the project, open the generated solution in Visual Studio and build it like any other solution. Each time the +CMake files are changed, Visual Studio will automatically regenerate the CMake build files and reload the solution +before continuing the build. Be aware that in old Visual Studio versions (2015 and earlier) the reload-and-continue +might not work properly. + +You can also build the solution with msbuild via the command line, or use CMake's build wrapper to do that for you: + +.. code:: console + + cmake --build "" --config Release + +Using Ninja to build +~~~~~~~~~~~~~~~~~~~~ + +The Ninja build system is shipped with Visual Studio since version 2019 and used by default if loading a CMake project +directly from within the IDE. Ninja can also be `installed separately `__. + +To configure the build directory for Ninja, pass ``Ninja`` or ``Ninja Multi-Config`` as the argument for the ``-G`` switch. +The difference between both generators is that the former uses ``CMAKE_BUILD_TYPE`` to specify the configuration ( +e.g. ``Debug`` or ``Release``) while the latter supports all configurations in a single build directory, specified during +build time. + +The architecture is determined from the toolset, so make sure to run the commands in the correct Visual Studio command +prompt, e.g. "Native Tools for X64". + +Configure and build for a single-configuration Release build with vcpkg: + +.. code:: console + + cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" + cmake --build "" + +Same, but using the multi-configuration generator: + +.. code:: console + + cmake -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B "" + cmake --build "" --config Release + +Notes on other platforms and features +------------------------------------- + +Supported platforms +~~~~~~~~~~~~~~~~~~~ + +libprojectM is designed to be compatible with as many platforms and architectures as possible. Thus, the code base +doesn't use any non-portable code like OS-specific APIs or assembly instructions. + +The code compiles for the following target architectures: + +- i686 (x32 / x86) +- x86_64 (x64) +- armv7 (arm) +- aarch64 (arm64 / armv8) +- WASM + +Other architectures such as PPC, RISC and MIPS should be supported as well. Big-endian support is untested and thus +might be buggy. + +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 derivatives +- Android +- WebGL/WASM (using emscripten) + +As long as a platform provides OpenGL Core 3.3 or OpenGL ES 3.2 libraries and supports at least C++ 14, libprojectM +should build fine. + +Raspberry Pi (and other embedded systems) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make sure to enable GLES support by passing ``-DENABLE_GLES=TRUE`` to CMake's configuration command and install the +appropriate OS libraries. Otherwise, follow the Linux build instructions above. + +For applications using projectM, it's highly recommended to keep certain performance-related settings low, such as: + +- The per-point mesh resolution should be kept low, e.g. 48x32 +- The rendering resolution should not exceed 720p on the Pi, though most presets will also run at ~60 FPS in 1080p + +Build using NDK for Android +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To build projectM using the Android SDK, please refer to the official NDK docs: + +https://developer.android.com/ndk/guides/cmake + +It is highly recommended using the latest NDK and CMake >= 3.21 for building. + +Using libprojectM with pkgconfig +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some UNIX build systems cannot use CMake config packages, like GNU autotools. To use libprojectM with such build +systems, projectM's build system also creates basic ``.pc`` files during the installation process. + +Note that the resulting pkgconfig files will not necessarily work in all circumstances, because they are much less +flexible than CMake (or Meson). When using pkgconfig, some required libraries will probably not be linked +automatically (e.g. OpenGL libraries) and have to be added manually depending on the application needs. + +Frontends and audio capturing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 `__ +(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 +audio data from OS or other external sources. + +.. _Building with CMake: + +Building with CMake +------------------- + +This section contains in-depth information for building with the CMake build system. + +To use the library in other projects, it is required to install it. Use ``CMAKE_INSTALL_PREFIX`` to specify the +installation directory. If you use other build systems, you have to specify the include and library paths manually. + +Selecting a specific project file generator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Building libprojectM does not require any specific CMake generator. It should work with any available generator, single- +and multi-config. + +To specify a CMake generator, use the ``-G`` switch, followed by the generator name. Some newer generators take an +additional architecture using the ``-A`` switch. To list all available generators available on your current platform, +leave out the generator name: + +.. code:: shell + + cmake -G + +Additional information on the supported generators can be +found `in the CMake documentation `__. + +Popular generators +^^^^^^^^^^^^^^^^^^ + +By default, CMake will use the `Unix Makefiles `__ +generator on Linux and macOS, which is a good choice and should work. Yet in some circumstances, you might want to +generate project files for a specific build tool or IDE: + +.. code:: shell + + cmake -G "Unix Makefiles" -S /path/to/source/dir -B /path/to/build/dir + +A common alternative is the `Ninja `__ generator, which +requires ``ninja`` to be installed. It is mostly a ``make`` +replacement with less overhead and should work equally well. It is supported on all major platforms, including Windows: + +.. code:: shell + + cmake -G Ninja -S /path/to/source/dir -B /path/to/build/dir + +On macOS, CMake also supports the `Xcode `__ generator. It will +create an ``.xcodeproj`` bundle which you can open in Xcode. It also adds support for automatic code signing, which might +be required if your application using projectM needs to be notarized for store deployment. + +.. code:: shell + + 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 2022 you would use +the `Visual Studio 17 2022 `__ generator +and provide an additional architecture parameter: + +.. code:: shell + + 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 +use the respective ``-A`` switch for each. + +Project-specific configuration options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CMake has no built-in way of printing all available configuration options. You can either refer to the +top-level ``CMakeLists.txt`` which contains a block of ``option`` and ``cmake_dependent_option`` commands, or use one of the +available CMake UIs which will display the options after configuring the project once. + +Important build switches +^^^^^^^^^^^^^^^^^^^^^^^^ + +The following table also gives you an overview of important build options and their defaults. All options accept a +boolean +value (``YES``/``NO``, ``TRUE``/``FALSE``, ``ON``/``OFF`` or ``1``/``0``) and can be provided on the configuration-phase command line +using the ``-D`` switch. + +.. list-table:: + :header-rows: 1 + + * - 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`` + - (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. + +Experimental and application-dependent build switches +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +.. list-table:: + :header-rows: 1 + + * - 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 +^^^^^^^^^^^^ + +There are also a few textual parameters that can be used to fine-tune the installation directories. Relative paths in +the following options are appended to the value +of `CMAKE_INSTALL_PREFIX `__ (which, on most UNIX +platforms, defaults to ``/usr/local``): + +.. list-table:: + :header-rows: 1 + + * - CMake option + - Default + - Description + * - ``CMAKE_INSTALL_PREFIX`` + - (OS dependent) + - Base directory where the projectM libraries, includes and support files will be installed. + * - ``PROJECTM_BIN_DIR`` + - ``bin`` + - Directory where executables (e.g. the SDL standalone application) are installed. + * - ``PROJECTM_LIB_DIR`` + - ``lib[64]`` + - Directory where libprojectM is installed. + * - ``PROJECTM_INCLUDE_DIR`` + - ``include`` + - Directory where the libprojectM include files will be installed under. + +Other options +^^^^^^^^^^^^^ + +Various other options for specific needs. + +.. list-table:: + :header-rows: 1 + + * - CMake option + - Default + - Description + * - ``CMAKE_DEBUG_POSTFIX`` + - ``d`` (if ``ENABLE_DEBUG_POSTFIX`` is set) + - Postfix appended to debug libraries. + * - ``CMAKE_INSTALL_BINDIR`` + - ``bin`` + - Another way to specify the binary installation directory. Used as default value for ``PROJECTM_BIN_DIR``. + * - ``CMAKE_INSTALL_LIBDIR`` + - ``lib`` or ``lib64`` + - Another way to specify the library installation directory. Used as default value for ``PROJECTM_LIB_DIR``. + * - ``CMAKE_INSTALL_INCLUDEDIR`` + - ``include`` + - Another way to specify the include file installation directory. Used as default value for ``PROJECTM_INCLUDE_DIR``. + +Always perform out-of-tree builds! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most classic IDEs and build systems directly make use of the source tree and create project files, temporary build +artifacts (e.g. object files) and the final binaries in the same directory structure as the source files. An advantage +of this approach is that you can find all compiled binaries side-by-side with their sources and generated headers are +already in the same directories as the source files including them. This approach has some drawbacks though: + +- Only a single build configuration is supported as files are overwritten in-place. +- A lot of noise is created in the source directory, making it hard to distinguish between generated and original source + files. +- A very large ``.gitignore`` file is required to cover all unwanted files. +- Mistakes in the build scripts can overwrite source files, causing errors and destroy uncommitted work. + +Some of these can be mitigated by providing additional targets (``make clean`` and ``make distclean``) or creating +subdirectories for Debug/Release build configurations. + +While CMake also supports in-tree builds, it is "discouraged" in the official documentation, for the above reasons. +Building out-of-tree allows it to create multiple build directories with different configurations which do not influence +each other in any way. If a build directory contains unwanted artifacts, and you want to start fresh, simply delete and +recreate the whole directory - no work is lost. + +This project follow this principle by treating the original source tree as read-only and avoiding potential conflicts: + +- Everything under `CMAKE_SOURCE_DIR `__ must only be + read, never changed or written to. +- Everything under `CMAKE_BINARY_DIR `__ is temporary + and related to the current build configuration. +- When generating configuration-dependent files, + use `CMAKE_CONFIGURATION_TYPES `__ + and `CMAKE_BUILD_TYPE `__ to create non-conflicting + files in the build tree. + +While this project will not force you to build out-of-tree, there is no mechanism to clean up the generated files after +running cmake in-tree. + +CMake build directory layout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are new to CMake, the way of how CMake creates the build directory and where it creates the build targets might +be confusing. Here is a summary of what's in the build directory and how it is structured in general. + +Using files from the build tree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is generally not good practice to directly take binaries and other files from the build tree for packaging, for +several reasons: + +1. The directory structure is generated by CMake and depends on the generator used. The layout might change between + CMake versions, even for the same generator. +2. On platforms with RPATH support, CMake will store absolute paths in executables and shared libraries which point to + the absolute paths of any linked dependencies, either from the build tree or external libraries as well. These + binaries are not relocatable and will most certainly not work if run on any other computer (or even on the same after + deleting the build directory). +3. For some configurations, even Release build artifacts may contain debug symbols until they are installed. + +It is fine to build and run executables from the build directory for development and debugging. For packaging or using +libprojectM in other projects, always use the ``install`` target and copy files from there. + +Generated files +^^^^^^^^^^^^^^^ + +In the top-level build directory, CMake creates a few files that are present on any platform: + +- ``CMakeCache.txt``: This file contains all variables and build settings CMake needs to remember from the first + configuration run. This file can be edited on demand either manually or using a CMake UI to change any values. On the + next build, CMake will regenerate the project files if this file has been modified. +- ``cmake_install.cmake``: Contains generated install-related settings. +- ``install_manifest.txt``: After installing the project, this file contains a list with absolute filenames of all + installed files. It can be used for packaging or deleting installed files as CMake doesn't define an ``uninstall`` + target. +- The top-level project file for use with the selected build toolset, e.g. ``Makefile``, ``build.ninja``, ``projectm.sln`` + or ``projectm.xcodeproj``, plus additional toolset-specific files. + +The projectM build files generate additional files used in the build and install phases. These are scattered over the +build tree, but installed into the proper directories. Do not try and gather these files yourself from the build tree. + +Subdirectory structure +^^^^^^^^^^^^^^^^^^^^^^ + +The rest of the directory structure generally resembles the source tree. Source directories containing +a ``CMakeLists.txt`` file will also be created in the build tree with the same relative path. Each of these subdirectories +contains a ``CMakeFiles`` directory with CMake-internal data, generated project files for the select toolset, e.g. +makefiles and any temporary compile artifacts. + +The directory structure is created by CMake and may change depending on the generator and CMake version used. + +Executable and library locations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Build targets - shared/static libraries and executables - are created in the same subdirectory in the build tree as +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 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. + +Using libprojectM in other CMake projects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The projectM library can be used as a static library or shared library in other CMake-based projects to provide embedded +audio visualization. It is highly recommended to build projectM as shared libraries for maximum compatibility and LGPL +compliance. + +The build directory is not structured in a way that other projects can make use of it. Use the ``install`` target to copy +all required files to the configured installation prefix. You can customize the subdirectories for libraries, includes +and binaries using the ``PROJECTM_>_DIR`` variables when configuring the CMake project. + +Importing libprojectM targets from the build tree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This approach is not recommended, but can be useful for projects that either require more in-depth access to the +projectM library files, especially to headers that are not installed as part of the public API. This might cause issues +if the internal headers change, but gives a broader set of features and more control to the developer. + +Please refer to the `ExternalProject `__ CMake module +documentation on how to set up the libprojectM build system for use in another project. + +Importing libprojectM targets from an installed version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is the recommended and supported way of importing libprojectM in your project. This project installs a set of CMake +files in ``//cmake/projectM4``, containing target definitions, version and dependency checks as well as +any additional libraries required for linking. Other projects then use CMake's ``find_package`` command to search for +these files in `different locations `__. + +In the case projectM libraries and headers are not installed in any system search path, you need to add either the +install prefix path (the top-level install dir) or the directory containing the libraries (the ``lib`` dir by default) to +the `CMAKE_PREFIX_PATH `__ list. + +If the package was found, you can then link against libprojectM by using the ``libprojectM::projectM`` target. + +Depending on how the package was built, targets might be available for multiple configurations or only ``Release``. CMake +will automatically select the most appropriate one to link. + +Include dirs, additional link dependencies and possible compiler options will be propagated to any target the library is +linked to. + +Using the optional playlist library +""""""""""""""""""""""""""""""""""" + +If you want to use the optional playlist library, you need to specifically request it as a component: + +.. code:: cmake + + find_package(projectM4 COMPONENTS Playlist) + +You can either use ``REQUIRED`` to force a fatal error if the component cannot be found or check if the target exists +using: + +.. code:: cmake + + if(TARGET libprojectM::playlist) + # ... + endif() + +If you link the playlist library, the main ``libprojectM::projectM`` target will be linked automatically as a dependency. + +Example +""""""" + +Searches for projectM and the playlist library and links both to the application: + +.. code:: cmake + + find_package(projectM4 REQUIRED COMPONENTS Playlist) + + add_executable(MyApp main.cpp) + + target_link_libraries(MyApp PRIVATE + libprojectM::playlist + ) diff --git a/docs/conf.py b/docs/conf.py index db6281c24d..a527b6a513 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -100,7 +100,7 @@ # -- Extension configuration ------------------------------------------------- # Path to the Doxygen XML output. Override with the PROJECTM_DOXYGEN_XML # environment variable, e.g. point it at /xml after running the -# "projectm_doxygen" target (see BUILD_DOCS in BUILDING-cmake.md). +# "projectm_doxygen" target (see BUILD_DOCS in docs/building.rst). breathe_projects = {"projectm_doxygen": os.environ.get( "PROJECTM_DOXYGEN_XML", "/home/dwagner/git/cmake-build-projectm/xml")} breathe_default_project = 'projectm_doxygen' \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 744b28d2f1..85936f5e08 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -241,8 +241,7 @@ Architecture Building from source -------------------- -See `BUILDING.md `__ -and the `developer documentation in the +See :doc:`building` and the `developer documentation in the wiki `__. Using the library