Expose a single canonical flatbuffers::flatbuffers target

.github/workflows/build.yml

@@ -1,5 +1,5 @@
 name: CI
 permissions: read-all
 
 on:
   # For manual tests.
@@ -30,7 +30,7 @@
         cxx: [g++-13, clang++-18]
       fail-fast: false
     steps:
     - uses: actions/checkout@v6
     - name: cmake
       run: CXX=${{ matrix.cxx }} cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_STRICT_MODE=ON -DFLATBUFFERS_STATIC_FLATC=ON .
     - name: build
@@ -42,7 +42,7 @@
         chmod +x flatc
         ./flatc --version
     - name: upload build artifacts
       uses: actions/upload-artifact@v7
       with:
         name: Linux flatc binary ${{ matrix.cxx }}
         path: flatc
@@ -51,7 +51,7 @@
       if: startsWith(github.ref, 'refs/tags/')
       run: zip Linux.flatc.binary.${{ matrix.cxx }}.zip flatc
     - name: Release zip file
       uses: softprops/action-gh-release@v2
       if: startsWith(github.ref, 'refs/tags/')
       with:
         files: Linux.flatc.binary.${{ matrix.cxx }}.zip
@@ -68,7 +68,7 @@
     name: Build Linux with -DFLATBUFFERS_NO_FILE_TESTS
     runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v6
     - name: cmake
       run: CXX=clang++-18 cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_STRICT_MODE=ON -DFLATBUFFERS_CXX_FLAGS="-DFLATBUFFERS_NO_FILE_TESTS" .
     - name: build
@@ -80,7 +80,7 @@
     name: Build Linux with out-of-source build location
     runs-on: ubuntu-24.04
     steps:
     - uses: actions/checkout@v6
     - name: make build directory
       run: mkdir build
     - name: cmake
@@ -112,7 +112,7 @@
             std: 23
 
     steps:
     - uses: actions/checkout@v6
     - name: cmake
       run: >
         CXX=${{ matrix.cxx }} cmake -G "Unix Makefiles"
@@ -135,9 +135,9 @@
         std: [11, 14, 17, 20, 23]
       fail-fast: false
     steps:
     - uses: actions/checkout@v6
     - name: Add msbuild to PATH
       uses: microsoft/setup-msbuild@v2
     - name: cmake
       run: >
         cmake -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release
@@ -160,9 +160,9 @@
     name: Build Windows 2022
     runs-on: windows-2022
     steps:
     - uses: actions/checkout@v6
     - name: Add msbuild to PATH
       uses: microsoft/setup-msbuild@v2
     - name: cmake
       run: cmake -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release -DFLATBUFFERS_BUILD_CPP17=ON -DFLATBUFFERS_STRICT_MODE=ON .
     - name: build
@@ -179,7 +179,7 @@
       if: startsWith(github.ref, 'refs/tags/')
       run: move Release/flatc.exe . && Compress-Archive flatc.exe Windows.flatc.binary.zip
     - name: Release binary
       uses: softprops/action-gh-release@v2
       if: startsWith(github.ref, 'refs/tags/')
       with:
         files: Windows.flatc.binary.zip
@@ -255,7 +255,7 @@
       if: startsWith(github.ref, 'refs/tags/')
       run: mv Release/flatc . && zip MacIntel.flatc.binary.zip flatc
     - name: Release binary
       uses: softprops/action-gh-release@v2
       if: startsWith(github.ref, 'refs/tags/')
       with:
         files: MacIntel.flatc.binary.zip
@@ -298,7 +298,7 @@
       if: startsWith(github.ref, 'refs/tags/')
       run: mv Release/flatc . && zip Mac.flatc.binary.zip flatc
     - name: Release binary
       uses: softprops/action-gh-release@v2
       if: startsWith(github.ref, 'refs/tags/')
       with:
         files: Mac.flatc.binary.zip
@@ -435,6 +435,15 @@
       # gradlew
       run: gradle jvmMainClasses jvmTest jsTest jsBrowserTest
 
+  build-cmake-package:
+    name: Test CMake package (static/shared)
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v6
+    - name: test
+      working-directory: tests
+      run: bash CMakePackageTest.sh
+
   build-rust-linux:
     name: Build Rust Linux
     runs-on: ubuntu-24.04

CMake/flatbuffers-config.cmake

@@ -1,4 +1,72 @@
-include("${CMAKE_CURRENT_LIST_DIR}/FlatBuffersTargets.cmake" OPTIONAL)
+set(FlatBuffers_known_comps static shared)
+set(FlatBuffers_comp_static NO)
+set(FlatBuffers_comp_shared NO)
+foreach(FlatBuffers_comp IN LISTS ${CMAKE_FIND_PACKAGE_NAME}_FIND_COMPONENTS)
+    if(FlatBuffers_comp IN_LIST FlatBuffers_known_comps)
+        set(FlatBuffers_comp_${FlatBuffers_comp} YES)
+    else()
+        set(${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE
+            "FlatBuffers does not recognize component `${FlatBuffers_comp}`.")
+        set(${CMAKE_FIND_PACKAGE_NAME}_FOUND FALSE)
+        return()
+    endif()
+endforeach()
+
+if(FlatBuffers_comp_static AND FlatBuffers_comp_shared)
+    set(${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE
+        "FlatBuffers `static` and `shared` components are mutually exclusive.")
+    set(${CMAKE_FIND_PACKAGE_NAME}_FOUND FALSE)
+    return()
+endif()
+
+set(FlatBuffers_static_targets "${CMAKE_CURRENT_LIST_DIR}/FlatBuffersStaticTargets.cmake")
+set(FlatBuffers_shared_targets "${CMAKE_CURRENT_LIST_DIR}/FlatBuffersSharedTargets.cmake")
+
+macro(FlatBuffers_load_targets type)
+    if(NOT EXISTS "${FlatBuffers_${type}_targets}")
+        set(${CMAKE_FIND_PACKAGE_NAME}_NOT_FOUND_MESSAGE
+            "FlatBuffers `${type}` libraries were requested but not found.")
+        set(${CMAKE_FIND_PACKAGE_NAME}_FOUND FALSE)
+        return()
+    endif()
+    include("${FlatBuffers_${type}_targets}")
+endmacro()
+
+if(FlatBuffers_comp_static)
+    FlatBuffers_load_targets(static)
+elseif(FlatBuffers_comp_shared)
+    FlatBuffers_load_targets(shared)
+elseif(DEFINED FlatBuffers_SHARED_LIBS AND FlatBuffers_SHARED_LIBS)
+    FlatBuffers_load_targets(shared)
+elseif(DEFINED FlatBuffers_SHARED_LIBS AND NOT FlatBuffers_SHARED_LIBS)
+    FlatBuffers_load_targets(static)
+elseif(BUILD_SHARED_LIBS)
+    if(EXISTS "${FlatBuffers_shared_targets}")
+        FlatBuffers_load_targets(shared)
+    else()
+        FlatBuffers_load_targets(static)
+    endif()
+else()
+    if(EXISTS "${FlatBuffers_static_targets}")
+        FlatBuffers_load_targets(static)
+    else()
+        FlatBuffers_load_targets(shared)
+    endif()
+endif()
+
+# flatbuffers never materializes a separate "_shared"-suffixed physical
+# library; flatbuffers::flatbuffers is the only real target. This alias
+# exists purely so that consumers hardcoded to the legacy
+# flatbuffers::flatbuffers_shared name keep working when the target we just
+# loaded happens to be shared. ALIAS of an IMPORTED target needs CMake 3.11+;
+# older consumers just don't get the compatibility alias.
+if(NOT CMAKE_VERSION VERSION_LESS 3.11 AND NOT TARGET flatbuffers::flatbuffers_shared)
+    get_target_property(FlatBuffers_imported_type flatbuffers::flatbuffers TYPE)
+    if(FlatBuffers_imported_type STREQUAL "SHARED_LIBRARY")
+        add_library(flatbuffers::flatbuffers_shared ALIAS flatbuffers::flatbuffers)
+    endif()
+    unset(FlatBuffers_imported_type)
+endif()
+
 include("${CMAKE_CURRENT_LIST_DIR}/FlatcTargets.cmake" OPTIONAL)
-include("${CMAKE_CURRENT_LIST_DIR}/FlatBuffersSharedTargets.cmake" OPTIONAL)
-include("${CMAKE_CURRENT_LIST_DIR}/BuildFlatBuffers.cmake" OPTIONAL)
+include("${CMAKE_CURRENT_LIST_DIR}/BuildFlatBuffers.cmake" OPTIONAL)

CMakeLists.txt

@@ -25,9 +25,6 @@ option(FLATBUFFERS_BUILD_FLATHASH "Enable the build of flathash" OFF)
 option(FLATBUFFERS_BUILD_BENCHMARKS "Enable the build of flatbenchmark."
        OFF)
 option(FLATBUFFERS_BUILD_GRPCTEST "Enable the build of grpctest" OFF)
-option(FLATBUFFERS_BUILD_SHAREDLIB
-       "Enable the build of the flatbuffers shared library"
-       OFF)
 option(FLATBUFFERS_LIBCXX_WITH_CLANG "Force libc++ when using Clang" ON)
 # NOTE: Sanitizer check only works on Linux & OSX (gcc & llvm).
 option(FLATBUFFERS_CODE_SANITIZE
@@ -437,8 +434,37 @@ else()
   endif()
 endif()
 
+# Deprecated: FLATBUFFERS_BUILD_SHAREDLIB
+
+if(DEFINED FLATBUFFERS_BUILD_SHAREDLIB)
+  message(DEPRECATION
+    "FLATBUFFERS_BUILD_SHAREDLIB is deprecated and will be removed in a "
+    "future release. flatbuffers::flatbuffers is now the only library "
+    "target; its type follows BUILD_SHARED_LIBS (or FlatBuffers_SHARED_LIBS) "
+    "instead of a separately-typed flatbuffers::flatbuffers_shared target. "
+    "Use -DBUILD_SHARED_LIBS=ON in place of -DFLATBUFFERS_BUILD_SHAREDLIB=ON.")
+  if(FLATBUFFERS_BUILD_SHAREDLIB)
+    set(BUILD_SHARED_LIBS ON)
+    if(NOT FLATBUFFERS_BUILD_FLATLIB)
+      message(DEPRECATION
+        "FLATBUFFERS_BUILD_SHAREDLIB=ON with FLATBUFFERS_BUILD_FLATLIB=OFF "
+        "used to build only the shared library, under its own name. That "
+        "library is now built through FLATBUFFERS_BUILD_FLATLIB itself (as "
+        "shared, per BUILD_SHARED_LIBS above), so FLATBUFFERS_BUILD_FLATLIB "
+        "is being forced back ON to preserve the resulting library.")
+      set(FLATBUFFERS_BUILD_FLATLIB ON)
+    endif()
+  endif()
+endif()
+
+# Honor FlatBuffers_SHARED_LIBS to match the install interface
+if(DEFINED FlatBuffers_SHARED_LIBS)
+  set(BUILD_SHARED_LIBS "${FlatBuffers_SHARED_LIBS}")
+endif()
+
 if(FLATBUFFERS_BUILD_FLATLIB)
-  add_library(flatbuffers STATIC ${FlatBuffers_Library_SRCS})
+  add_library(flatbuffers ${FlatBuffers_Library_SRCS})
+  add_library(flatbuffers::flatbuffers ALIAS flatbuffers)
 
   # Attach header directory for when build via add_subdirectory().
   target_include_directories(flatbuffers
@@ -450,6 +476,21 @@ if(FLATBUFFERS_BUILD_FLATLIB)
   if(FLATBUFFERS_ENABLE_PCH)
     add_pch_to_target(flatbuffers include/flatbuffers/pch/pch.h)
   endif()
+
+  # FlatBuffers use calendar-based versioning and do not provide any ABI
+  # stability guarantees. Therefore, always use the full version as SOVERSION
+  # in order to avoid breaking reverse dependencies on upgrades. These
+  # properties are no-ops when flatbuffers is built STATIC.
+  set_target_properties(flatbuffers PROPERTIES
+                        SOVERSION "${PROJECT_VERSION}"
+                        VERSION "${PROJECT_VERSION}")
+
+  get_target_property(FlatBuffers_Library_TYPE flatbuffers TYPE)
+  if(FlatBuffers_Library_TYPE STREQUAL "SHARED_LIBRARY")
+    # Legacy target name, to be removed eventually.
+    add_library(flatbuffers_shared ALIAS flatbuffers)
+    add_library(flatbuffers::flatbuffers_shared ALIAS flatbuffers)
+  endif()
 endif()
 
 if(FLATBUFFERS_BUILD_FLATC)
@@ -482,23 +523,7 @@ if(FLATBUFFERS_BUILD_FLATHASH)
   target_link_libraries(flathash PRIVATE $<BUILD_INTERFACE:ProjectConfig>)
 endif()
 
-if(FLATBUFFERS_BUILD_SHAREDLIB)
-  add_library(flatbuffers_shared SHARED ${FlatBuffers_Library_SRCS})
-  target_link_libraries(flatbuffers_shared PRIVATE $<BUILD_INTERFACE:ProjectConfig>)
-  # FlatBuffers use calendar-based versioning and do not provide any ABI
-  # stability guarantees. Therefore, always use the full version as SOVERSION
-  # in order to avoid breaking reverse dependencies on upgrades.
-  set(FlatBuffers_Library_SONAME_FULL "${PROJECT_VERSION}")
-  set_target_properties(flatbuffers_shared PROPERTIES
-                        OUTPUT_NAME flatbuffers
-                        SOVERSION "${FlatBuffers_Library_SONAME_FULL}"
-                        VERSION "${FlatBuffers_Library_SONAME_FULL}")
-  if(FLATBUFFERS_ENABLE_PCH)
-    add_pch_to_target(flatbuffers_shared include/flatbuffers/pch/pch.h)
-  endif()
-endif()
-
-function(compile_schema SRC_FBS OPT SUFFIX OUT_GEN_FILE) 
+function(compile_schema SRC_FBS OPT SUFFIX OUT_GEN_FILE)
   get_filename_component(SRC_FBS_DIR ${SRC_FBS} PATH)
   string(REGEX REPLACE "\\.fbs$" "${SUFFIX}.h" GEN_HEADER ${SRC_FBS})
   add_custom_command(
@@ -643,11 +668,23 @@ if(FLATBUFFERS_INSTALL)
     install(
       TARGETS flatbuffers EXPORT FlatBuffersTargets
       ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+      RUNTIME DESTINATION ${CMAKE_INSTALL_LIBDIR}
+      LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
       INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
     )
 
+    # flatbuffers::flatbuffers is exported under a type-specific file name
+    # so that a packager who wants to offer both flavors can run two separate
+    # configure/build/install passes into the same prefix. The CMake package
+    # picks between them at find_package() time.
+    if(FlatBuffers_Library_TYPE STREQUAL "SHARED_LIBRARY")
+      set(FlatBuffers_Targets_FILE "FlatBuffersSharedTargets.cmake")
+    else()
+      set(FlatBuffers_Targets_FILE "FlatBuffersStaticTargets.cmake")
+    endif()
+
     install(EXPORT FlatBuffersTargets
-      FILE FlatBuffersTargets.cmake
+      FILE "${FlatBuffers_Targets_FILE}"
       NAMESPACE flatbuffers::
       DESTINATION ${FB_CMAKE_DIR}
     )
@@ -667,24 +704,7 @@ if(FLATBUFFERS_INSTALL)
     )
   endif()
 
-  if(FLATBUFFERS_BUILD_SHAREDLIB)
-    install(
-      TARGETS flatbuffers_shared EXPORT FlatBuffersSharedTargets
-      ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
-      RUNTIME DESTINATION ${CMAKE_INSTALL_LIBDIR}
-      LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
-      INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
-    )
-
-    install(
-      EXPORT FlatBuffersSharedTargets
-      FILE FlatBuffersSharedTargets.cmake
-      NAMESPACE flatbuffers::
-      DESTINATION ${FB_CMAKE_DIR}
-    )
-  endif()
-
-  if(FLATBUFFERS_BUILD_SHAREDLIB OR FLATBUFFERS_BUILD_FLATLIB)
+  if(FLATBUFFERS_BUILD_FLATLIB)
       configure_file(CMake/flatbuffers.pc.in flatbuffers.pc @ONLY)
       install(
         FILES "${CMAKE_CURRENT_BINARY_DIR}/flatbuffers.pc"

tests/CMakeConsumerTest/CMakeLists.txt

@@ -0,0 +1,32 @@
+# Minimal downstream consumer used by CMakePackageTest.sh to exercise
+# find_package(FlatBuffers) against differently-packaged installs (static
+# only, shared only, both) and the component/variable/BUILD_SHARED_LIBS
+# precedence chain in flatbuffers-config.cmake.
+#
+# This project is never add_subdirectory()'d into the main flatbuffers
+# build; it is always configured standalone, against an install tree, with
+# CMAKE_PREFIX_PATH pointing at the package under test.
+cmake_minimum_required(VERSION 3.11)
+project(flatbuffers_consumer_test CXX)
+
+# Optional COMPONENTS argument to pass through to find_package(FlatBuffers),
+# e.g. -DFLATBUFFERS_CONSUMER_TEST_COMPONENTS=static
+set(FLATBUFFERS_CONSUMER_TEST_COMPONENTS "" CACHE STRING
+    "COMPONENTS argument to pass to find_package(FlatBuffers), if any")
+
+if(FLATBUFFERS_CONSUMER_TEST_COMPONENTS)
+  find_package(FlatBuffers REQUIRED COMPONENTS ${FLATBUFFERS_CONSUMER_TEST_COMPONENTS})
+else()
+  find_package(FlatBuffers REQUIRED)
+endif()
+
+add_executable(consumer_canonical consumer.cpp)
+target_link_libraries(consumer_canonical PRIVATE flatbuffers::flatbuffers)
+
+if(TARGET flatbuffers::flatbuffers_shared)
+  add_executable(consumer_legacy_shared consumer.cpp)
+  target_link_libraries(consumer_legacy_shared PRIVATE flatbuffers::flatbuffers_shared)
+endif()
+
+get_target_property(FLATBUFFERS_CONSUMER_TEST_TYPE flatbuffers::flatbuffers TYPE)
+message(STATUS "flatbuffers::flatbuffers TYPE = ${FLATBUFFERS_CONSUMER_TEST_TYPE}")

tests/CMakeConsumerTest/consumer.cpp

@@ -0,0 +1,6 @@
+#include <flatbuffers/flatbuffers.h>
+
+int main() {
+  flatbuffers::FlatBufferBuilder builder;
+  return 0;
+}