Skip to content

Commit

Permalink
BUILDING.md: Mention sub-project best practices
Browse files Browse the repository at this point in the history
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: mozilla#122, mozilla#173, mozilla#176, mozilla#202, mozilla#241, mozilla#349, mozilla#353, mozilla#412, #504,
libjpeg-turbo/libjpeg-turbo@a3d4aad#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.
  • Loading branch information
dcommander committed Mar 1, 2022
1 parent c5f269e commit 0565548
Showing 1 changed file with 8 additions and 0 deletions.
8 changes: 8 additions & 0 deletions BUILDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
------------------

Expand Down

0 comments on commit 0565548

Please sign in to comment.