Build Troubleshooting

Build Troubleshooting Q&A

On this page, you can find a list of common build issues you may encounter while building libprojectM and the frontends, providing possible solutions.

If your problem isn't listed, and you can't find a solution on your own, please note that the projectM developers can not provide technical support. If you think your build issue is caused by the projectM code or build system files (or you are unsure if that is the case), please open a bug report in the respective repository. You can also ask for help in the bug report channel or the projectM Discord server and see if someone can help.

CMake issues

General advice

Things to check and try first:

• Always start with a fresh build directory if there is any issue, especially after checking out new code, switching branches or updating your local copy after a while.
• If you don't want to delete your while build dir, at least try and delete the CMakeCache.txt in the top-level build dir and re-run CMake's configuration phase.
• Make sure your C/C++ toolset and IDE is up-to-date and all components are properly set up.
• Use the latest stable CMake release. If only a very old version is available on your platform or shipped with your IDE, building your own CMake binaries is really easy. There also are binary releases available on cmake.org for many platforms.
• Make sure the cmake/cpack/ctest commands are in your PATH variable.

CMake can't find a working compiler

Depending on your OS and toolset, you might have to run CMake in a specific environment which defines paths for the compiler and other tools:

• On Windows using Visual Studio, either run CMake from within VS (version 2019 or higher is recommended) or from the developer command prompt for your target architecture which you can find in the Windows start menu.
• On macOS using Xcode, make sure you have the command line tools installed. If in doubt, run xcode-select --install ina terminal with the user account you want to run CMake in. Run xcode-select -p to verify the tools are properly installed. When using CMake to create Xcode projects, also make sure to use the latest CMake version.
• On Linux, make sure you have installed all required packages for compiling C/C++ code. Most distributions have meta packages called "build-essential" or similar that will pull in compiler, linker, make and other build tools. Since Linux is highly heterogeneous, refer to your distribution documentation on installing developer packages.
• If the above hints don't work, double-check your developer tools installation and the CMake generator used to create your project files. The default generator might not be the correct one for your setup.

CMake can't find a specific dependency

The projectM CMake scripts do not make any assumptions on where to look for build dependencies and solely rely on CMake's built-in mechanisms to find the needed packages. The lookup process is mostly platform-independent and generally requires packages and other files to be found in a specific set of directories:

• The CMAKE_PREFIX_PATH variable can be used to add one or more directories to the build configuration in which CMake will first look into when searching for packages and libraries. Add any paths separated by ; for libraries that are not installed in the toolset/OS default search paths.
• When using vcpkg to build the dependencies on any platform, always set CMAKE_TOOLCHAIN_FILE to <vcpkg-dir>/scripts/buildsystems/vcpkg.cmake.
• In some cases, even if the dependency normally provides CMake files, pre-built packages might not contain them. In this case, you need to either contact the author of the pre-built package or build the dependency yourself and add the installation dir to CMAKE_PREFIX_PATH.

CMake complains about "IMPORTED_IMPLIB not set for imported target ..."

This warning will be displayed in CMake versions starting with 3.19 and above. It will most probably also contain a note to set policy CMP0111.

Depending on the build type your dependencies, e.g. libprojectM, were built with, the exported package configuration will not contain all default build types CMake will create for multi-configuration generators. It will also be displayed if you use a single-configuration generator with a build type that is not found in the imported package.

There are two solutions:

1. Build the same configuration types the libprojectM package exports.
2. Map your build configuration types to other imported configuration types.

Only build against the same configuration types

• With single configuration generators (e.g. Unix Makefiles), set CMAKE_BUILD_TYPE to one of the exported target configurations.
• With multiple configuration generators (e.g. Xcode and Visual Studio), set CMAKE_CONFIGURATION_TYPES to a semicolon-separated list only containing the exported target configurations.

Map your configuration types to other types on imported libraries

Add a MAP_IMPORTED_CONFIG_<CONFIG> property on the imported library target (e.g. libprojectM::shared) for each build type you want to build with, but that is not available in the library package:

set_target_properties(libprojectM::shared PROPERTIES
        MAP_IMPORTED_CONFIG_MINSIZEREL Release
        MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release
        )

This solution is only useful if the build has a fixed set of known configurations.

Compilation issues

General advice

Things to check and try first:

• Make sure you use the latest available compiler and SDK versions for your platform.
• Use a compiler that supports at least C++14.
• If you build a recent version of projectM, also try to use the most recent versions of the required dependencies, e.g. SDL2.
• Make sure all libraries were built with the same compiler/SDK, for the same architecture and runtime libraries (e.g. MSVC /MD and /MT flags).
• In newly written code, always use case-sensitive filenames in #include directives and other project files. Keep in mind that most OS platforms have case-sensitive filesystems.

There is some compiler error I don't understand

If you're only trying to build projectM, but are not a C/C++ developer, errors during compilation might not provide you with enough information to identify the reason or fix the code. In this case, you can open an issue or ask on Discord to get a possible solution. In some cases the error you're encountering might be a bug that needs to be solved in the source, so it's important that you let us know about it. Please make sure you provide all relevant information, e.g. OS, compiler and library versions etc. so we can reproduce the problem.

An include file could not be found

• Make sure the filename casing in the #include directive is correct.
• Look at the compiler command line if all required include directories are present. If you can't see the compiler commands, add -DCMAKE_VERBOSE_MAKEFILE=ON to CMake's configuration command to enable command output on all generators.
• A third-party library might not be installed correctly or with an unexpected directory layout.
• If the missing include is a system or SDK header, check if your toolset is configured properly.
• Make sure the #include directive uses the correct quotes, e.g. "" for project-internal headers and <> for third-party or SDK headers. Modern compilers differentiate between those.
• Make sure include directories are provided via the correct compiler flag, e.g. -i for project-internal include paths used with #include "header.h"and -I for third-party and SDK/system headers for use with #include <header.h>.