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,
a3d4aadd0d (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.
This commit is contained in:
@@ -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
|
||||
------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user