From 05655481917a2d2761cf2fe19b76f639b7f159ef Mon Sep 17 00:00:00 2001 From: DRC Date: Mon, 28 Feb 2022 20:41:56 -0600 Subject: [PATCH] BUILDING.md: Mention sub-project best practices People keep trying to include libjpeg-turbo into downstream CMake-based build systems by way of the add_subdirectory() function and requesting upstream support when something inevitably breaks. (Refer to: #122, #173, #176, #202, #241, #349, #353, #412, #504, https://github.com/libjpeg-turbo/libjpeg-turbo/commit/a3d4aadd0d1597ad46edcbe3b964499ec785d40c#commitcomment-67575889). libjpeg-turbo has never supported that method of sub-project integration, because doing so would require that we (minimally): 1. avoid using certain CMake variables, such as CMAKE_SOURCE_DIR, CMAKE_BINARY_DIR, and CMAKE_PROJECT_NAME; 2. avoid using implicit include directories and relative paths; 3. provide a way to optionally skip the installation of libjpeg-turbo components in response to 'make install'; 4. provide a way to optionally postfix target names, to avoid namespace conflicts; 5. restructure the top-level CMakeLists.txt so that it properly sets the PROJECT_VERSION variable; and 6. design automated CI tests to ensure that new commits don't break any of the above. Even if we did all of that, issues would still arise, because it is impossible for one upstream build system to anticipate the widely varying needs of every downstream build system. That's why the CMake ExternalProject_Add() function exists, and it is my sincere hope that adding a blurb to BUILDING.md mentioning the need to use that function will head off future GitHub issues on this topic. If not, then I can at least post a link to this commit and the blurb and avoid doing the same song and dance over and over again. --- BUILDING.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/BUILDING.md b/BUILDING.md index e682769e0..43eb50024 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -79,6 +79,14 @@ Build Requirements * If using JDK 11 or later, CMake 3.10.x or later must also be used. +Sub-Project Builds +------------------ + +The libjpeg-turbo build system does not support being included as a sub-project +using the CMake `add_subdirectory()` function. Use the CMake +`ExternalProject_Add()` function instead. + + Out-of-Tree Builds ------------------