Fix use of libktx project as subproject outside of KTX-Software (#1089)

#### The Fix * Always include `cmake/codesign.cmake` and `cmake/cputypetest.cmake`. Add `include_guard()` to them to prevent multiple inclusion. * Add host project for testing sub-project use and update workflow to build and run it and libktx. #### Other Changes * Add options to select building of full or read-only libktx. * Fix macOS build when CODE_SIGN_IDENTITY not set. Fixes both libktx and the larger KTX-Software project. Fixes #1083
2026-01-18 17:41:19 +01:00 · 2025-11-28 10:24:01 +09:00
parent 998a719d25
commit 7f0f889e3c
8 changed files with 190 additions and 58 deletions
--- a/.github/workflows/check-libktx-only.yml
+++ b/.github/workflows/check-libktx-only.yml
@@ -1,9 +1,10 @@
 # Copyright 2015-2020 The Khronos Group Inc.
 # SPDX-License-Identifier: Apache-2.0
-name: Check Config and Build of Just libktx
+name: Check Config and Build of libktx as top-level project and sub-project

 # The purpose of this is to smoke test building just libktx using its
-# CMakeLists.txt as the top-level project. Testing of various build
+# CMakeLists.txt as both a top-level project and sub-project that is
+# not related to the KTX-Software project. Testing of various build
 # options and running of tests on the library is left to the various
 # KTX-Software platform workflows.

@@ -73,8 +74,11 @@ jobs:
    runs-on: ${{ matrix.os }}
    env:
      GIT_LFS_SKIP_SMUDGE: 1
-      BUILD_DIR: "build"
-      SOURCE_DIR: "lib"
+      BUILD_DIR_TL: "build/tl"
+      BUILD_DIR_UKP: "build/ukp"
+      SOURCE_DIR_LIB: "lib"
+      SOURCE_DIR_UKP: "tests/use-ktx"
+      KTX2_TEST_FILE: "tests/testimages/kodim17_basis.ktx2"
      WERROR: ON

    steps:
@@ -84,10 +88,19 @@ jobs:
        # included (used for version creation)
        fetch-depth: 0

-    - name: Configure CMake build
-      run: cmake -S ${{ env.SOURCE_DIR }} -B ${{ env.BUILD_DIR }} -G "${{ matrix.generator }}" -DLIBKTX_WERROR=${{ env.WERROR }}
-    - name: Build libktx
-      run: cmake --build ${{ env.BUILD_DIR }} --config=Release
+    - name: Fetch test image from LFS and check it out
+      run: git lfs fetch ${{ env.KTX2_TEST_FILE }} && git lfs checkout ${{ env.KTX2_TEST_FILE }}
+
+    - name: Configure as top-level project
+      run: cmake -S ${{ env.SOURCE_DIR_LIB }} -B ${{ env.BUILD_DIR_TL }} -G "${{ matrix.generator }}" -DLIBKTX_WERROR=${{ env.WERROR }} -DLIBKTX_VERSION_READ_ONLY=ON
+    - name: Build libktx with top-level project
+      run: cmake --build ${{ env.BUILD_DIR_TL }} --config=Release
+
+    - name: Configure as sub-project
+      run: cmake -S ${{ env.SOURCE_DIR_UKP }} -B ${{ env.BUILD_DIR_UKP }} -G "${{ matrix.generator }}" -DLIBKTX_WERROR=${{ env.WERROR }}
+
+    - name: Build use-ktx and libktx projects
+      run: cmake --build ${{ env.BUILD_DIR_UKP }} --config=Release

    - name: Prepare version number and architecture for artifact
      id: libktx-version
@@ -101,12 +114,15 @@ jobs:
        if [ "$arch" = "x64" ]; then arch=x86_64; fi
        echo ARCH=$arch >> $GITHUB_ENV

-    - name: Check output directory content
-      run: scripts/check_lib_build_output.sh ${{ env.BUILD_DIR }}/${{ matrix.config }}
+    - name: Check content of output directory from top-level build
+      run: scripts/check_lib_build_output.sh ${{ env.BUILD_DIR_TL }}/${{ matrix.config }}
+
+    - name: Test run use-ktx program
+      run: ${{ env.BUILD_DIR_UKP }}/Release/use-ktx ${{ env.KTX2_TEST_FILE }}

    - name: Upload artifact libktx
      uses: actions/upload-artifact@v4
      with:
        name: libktx-${{ env.KTX_VERSION }}-${{ runner.os }}-${{ env.ARCH }}
-        path: ${{env.BUILD_DIR}}/Release/*ktx*
+        path: ${{env.BUILD_DIR_TL}}/Release/*ktx*

--- a/BUILDING.md
+++ b/BUILDING.md
@@ -41,6 +41,9 @@ cmake . -B build
 cmake --build build
 ```

+By default the project will be configured to build the full library. To build just the read-only library, add
+`-D LIBKTX_VERSION_FULL=OFF -D LIBKTX_VERSION_READ_ONLY=ON` to the CMake configure
+command.
 If you need the library to be static, add `-D BUILD_SHARED_LIBS=OFF` to the CMake configure command (always disabled on iOS and Emscripten).

 > **Note:**
@@ -76,6 +79,15 @@ The only dependencies beyond the build tools are for the build machine to have a
 [bash](#bash) shell and, if using OpenCL, the mentioned OpenCL development
 environment.

+One way to add _libktx_ to your own project is to add the following line to your
+CMakeLists.txt.
+
+```CMake
+add_subdirectory(/path/to/ktx/software/KTX-Software/lib ktx)
+```
+
+You can set any of the aforementioned configuration options by adding a set command, e.g, `set(BUILD_SHARED_LIBS OFF)`, before `add_subdirectory`.
+
 The complete project
 --------------------

--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -200,19 +200,23 @@ add_compile_options( ${fp_options} )
 set(KTX_BUILD_DIR "${CMAKE_BINARY_DIR}")

 if(APPLE OR LINUX OR WIN32)
-    # Normalize the output directory so it is the same regardless of
-    # single or multi-config generator. Note that wrapping this in a
-    # generator expression forces multi-configuration generators (like
-    # Visual Studio, Xcode or Ninja multi-config) to take the exact path
-    # and not add  a further $<CONFIG> to it.
+    # Three reasons for setting CMAKE_RUNTIME_OUTPUT_DIRECTORY.
+    # - Normalize the output directory so it is the same regardless of
+    #   single or multi-config generator. Note that wrapping this in a
+    #   generator expression forces multi-configuration generators (like
+    #   Visual Studio, Xcode or Ninja multi-config) to take the exact path
+    #   and not add  a further $<CONFIG> to it;
+    # - Build all executables into a common output directory.
+    # - On Windows, build dlls into the same directory as the executables,
+    #   so they can find their dlls when run in the build directory.
    set(CMAKE_RUNTIME_OUTPUT_DIRECTORY $<1:${KTX_BUILD_DIR}/$<CONFIG>>)

-    # Use a common RUNTIME_OUTPUT_DIRECTORY and LIBRARY_OUTPUT_DIRECTORY
-    # for all targets. On GNU/Linux and macOS this so that the INSTALL RPATH
-    # we need to add to installed binaries is functional in the build
-    # directory as well. On Windows this is so binaries run in the build
-    # directory can find the dll.
+    # Reason for setting CMAKE_LIBRARY_OUTPUT_DIRECTORY.
+    # - On GNU/Linux and macOS build .{so,dylib}s into the same directory
+    #   as the executables so that the INSTALL RPATH we need to add to
+    #   installed binaries is functional in the build directory as well.
    set(CMAKE_LIBRARY_OUTPUT_DIRECTORY $<1:${KTX_BUILD_DIR}/$<CONFIG>>)
+
    # For GNU/Linux and macOS BUILD_WITH_INSTALL_RPATH is necessary to have
    # the install rpath set duing build. See below for more explanation.
    set(CMAKE_BUILD_WITH_INSTALL_RPATH ON)
@@ -236,8 +240,13 @@ if(APPLE OR LINUX OR WIN32)
    # INSTALL_RPATH the same way for symmetry.
 endif()

+# Ensure the following are set as KTX-Software needs and hide them from users.
 set( LIBKTX_WERROR ${KTX_WERROR} )
 set( LIBKTX_EMBED_BITCODE ${KTX_EMBED_BITCODE} )
+set( LIBKTX_VERSION_FULL ON )
+# Want to expose this one to users so must be a cache variable. Note
+# that this is a different default from the one set in the libktx project.
+set( LIBKTX_VERSION_READ_ONLY ON CACHE BOOL "Build the read-only library")
 add_subdirectory(lib)

 if(KTX_FEATURE_JNI)
--- a/cmake/codesign.cmake
+++ b/cmake/codesign.cmake
@@ -3,9 +3,11 @@

 # Config options for code signing

+include_guard(DIRECTORY)
+
 if(APPLE)
    # Signing
-    set(XCODE_CODE_SIGN_IDENTITY "Development" CACHE STRING "Xcode code sign ID")
+    set(XCODE_CODE_SIGN_IDENTITY "" CACHE STRING "Xcode code sign ID")
    set(XCODE_DEVELOPMENT_TEAM "" CACHE STRING "Xcode development team ID")
    set(PRODUCTBUILD_IDENTITY_NAME "" CACHE STRING "productbuild identity name")
    set(PRODUCTBUILD_KEYCHAIN_PATH "" CACHE FILEPATH "pkgbuild keychain file")
@@ -83,12 +85,22 @@ endif()
 # Macro for setting up code signing on targets
 macro (set_code_sign target)
  if(APPLE)
-    set_target_properties(${target} PROPERTIES
-      XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "${XCODE_CODE_SIGN_IDENTITY}"
-      XCODE_ATTRIBUTE_DEVELOPMENT_TEAM "${XCODE_DEVELOPMENT_TEAM}"
-      XCODE_ATTRIBUTE_OTHER_CODE_SIGN_FLAGS "--timestamp"
-      XCODE_ATTRIBUTE_CODE_SIGN_INJECT_BASE_ENTITLEMENTS $<IF:$<CONFIG:Debug>,YES,NO>
-    )
+    if (XCODE_CODE_SIGN_IDENTITY)
+      set_target_properties(${target} PROPERTIES
+        XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "${XCODE_CODE_SIGN_IDENTITY}"
+        XCODE_ATTRIBUTE_DEVELOPMENT_TEAM "${XCODE_DEVELOPMENT_TEAM}"
+        XCODE_ATTRIBUTE_OTHER_CODE_SIGN_FLAGS "--timestamp"
+        XCODE_ATTRIBUTE_CODE_SIGN_INJECT_BASE_ENTITLEMENTS $<IF:$<CONFIG:Debug>,YES,NO>
+      )
+    else()
+      set_target_properties(${target} PROPERTIES
+        XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY ""
+        XCODE_ATTRIBUTE_CODE_SIGN_INJECT_BASE_ENTITLEMENTS NO
+        XCODE_ATTRIBUTE_CODE_SIGNING_ALLOWED NO
+        XCODE_ATTRIBUTE_CODE_SIGNING_REQUIRED NO
+      )
+    endif()
+
    if(IOS)
      set(set_pps FALSE)
      if(${ARGC} EQUAL 1)
--- a/cmake/cputypetest.cmake
+++ b/cmake/cputypetest.cmake
@@ -1,6 +1,8 @@
 # Copyright 2016, Simon Werta (@webmaster128).
 # SPDX-License-Identifier: Apache-2.0

+include_guard(DIRECTORY)
+
 set(cputypetest_code "
 //
 // https://gist.github.com/webmaster128/e08067641df1dd784eb195282fd0912f
--- a/lib/CMakeLists.txt
+++ b/lib/CMakeLists.txt
@@ -36,18 +36,19 @@ if(POLICY CMP0127)
    cmake_policy(SET CMP0127 NEW)
 endif()

-if(PROJECT_IS_TOP_LEVEL)
-    # Beware of using cmake_print_variables for variables with function
-    # dependent values, e.g. ARGN and CMAKE_CURRENT_FUNCTION_LIST_DIR.
-    include(CMakePrintHelpers)
-    include(CMakeDependentOption)
+# Beware of using cmake_print_variables for variables with function
+# dependent values, e.g. ARGN and CMAKE_CURRENT_FUNCTION_LIST_DIR.
+include(CMakePrintHelpers)
+include(CMakeDependentOption)

-    include(${KTX_ROOT_DIR}/cmake/codesign.cmake) # Needs APPLE_*_OS values.
-    include(${KTX_ROOT_DIR}/cmake/cputypetest.cmake)
-endif()
+include(${KTX_ROOT_DIR}/cmake/codesign.cmake) # Needs APPLE_*_OS values.
+include(${KTX_ROOT_DIR}/cmake/cputypetest.cmake)

 # OPTIONS

+option( LIBKTX_VERSION_READ_ONLY "Build the read only library" OFF)
+option( LIBKTX_VERSION_FULL "Build the full library" ON)
+
 option( LIBKTX_FEATURE_KTX1 "Enable KTX 1 support." ON )
 # TODO: Remove this option?
 option( LIBKTX_FEATURE_KTX2 "Enable KTX 2 support." ON )
@@ -56,7 +57,7 @@ option( LIBKTX_FEATURE_GL_UPLOAD "Enable OpenGL texture upload." ON )
 option( LIBKTX_FEATURE_ETC_UNPACK "ETC decoding support." ON )

 # Intentionally override the BASISU options, only making them visible
-# when it makes sense.
+# when they are useful.
 CMAKE_DEPENDENT_OPTION( BASISU_SSE
    "Compile with SSE support so applications can choose to use it."
    ON
@@ -504,23 +505,25 @@ add_subdirectory(../external/basis_universal basisu-encoder)
 # ktx libraries
 ###################################################

-add_library( ktx ${LIB_TYPE}
-    ${LIBKTX_MAIN_SRC}
-    src/basis_encode.cpp
-    src/writer1.c
-    src/writer2.c
-)
+if(LIBKTX_VERSION_FULL)
+    add_library( ktx ${LIB_TYPE}
+        ${LIBKTX_MAIN_SRC}
+        src/basis_encode.cpp
+        src/writer1.c
+        src/writer2.c
+    )
+    common_libktx_settings(ktx 1 ${LIB_TYPE})
+    add_lib_dependencies(ktx basisu_encoder)
+endif()

 # Read-only library
-add_library( ktx_read ${LIB_TYPE}
-    ${LIBKTX_MAIN_SRC}
-)
-
-common_libktx_settings(ktx 1 ${LIB_TYPE})
-common_libktx_settings(ktx_read 0 ${LIB_TYPE})
-
-add_lib_dependencies(ktx basisu_encoder)
-add_lib_dependencies(ktx_read basisu_encoder)
+if(LIBKTX_VERSION_READ_ONLY)
+    add_library( ktx_read ${LIB_TYPE}
+        ${LIBKTX_MAIN_SRC}
+    )
+    common_libktx_settings(ktx_read 0 ${LIB_TYPE})
+    add_lib_dependencies(ktx_read basisu_encoder)
+endif()

 create_version_header(src ktx)
 if(PROJECT_IS_TOP_LEVEL)
@@ -662,16 +665,28 @@ if(NOT PROJECT_IS_TOP_LEVEL AND ${CMAKE_PROJECT_NAME} STREQUAL "KTX-Software")
    set(ASTCENC_LIB_TARGET ${ASTCENC_LIB_TARGET} PARENT_SCOPE)
 endif()

-add_lib_dependencies(ktx ${ASTCENC_LIB_TARGET})
-add_lib_dependencies(ktx_read ${ASTCENC_LIB_TARGET})
-
-set(LIBKTX_INSTALL_TARGETS ktx)
-if(NOT BUILD_SHARED_LIBS AND NOT APPLE)
-    list(APPEND LIBKTX_INSTALL_TARGETS ${ASTCENC_LIB_TARGET} basisu_encoder)
+if(LIBKTX_VERSION_FULL)
+    add_lib_dependencies(ktx ${ASTCENC_LIB_TARGET})
+endif()
+if(LIBKTX_VERSION_READ_ONLY)
+    add_lib_dependencies(ktx_read ${ASTCENC_LIB_TARGET})
 endif()

 # Install

+if(LIBKTX_VERSION_FULL)
+    list(APPEND LIBKTX_INSTALL_TARGETS ktx)
+endif()
+# ktx_read has never been included in the install packages and no
+# issues have been filed. Only install it if building static libs
+# or full version is not being built.
+if(LIBKTX_VERSION_READ_ONLY AND NOT (BUILD_SHARED_LIBRARIES OR LIBKTX_VERSION_FULL))
+    list(APPEND LIBKTX_INSTALL_TARGETS ktx_read)
+endif()
+if(NOT BUILD_SHARED_LIBS AND NOT APPLE)
+    list(APPEND LIBKTX_INSTALL_TARGETS ${ASTCENC_LIB_TARGET} basisu_encoder)
+endif()
+
 if(APPLE OR LINUX)
    # Have library's name links as separate component
    set(KTX_NAMELINKS ON)
--- a/tests/use-ktx/CMakeLists.txt
+++ b/tests/use-ktx/CMakeLists.txt
@@ -0,0 +1,41 @@
+# Copyright 2025 The Khronos Group Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# Project, that is not KTX-Software, to test using libktx as a sub-project.
+
+cmake_minimum_required(VERSION 3.22)
+
+# MUST be set before project() else it is ignored.
+# N.B IOS and, in the Darwin case, CMAKE_SYSTEM_NAME are not set
+# until after the project() command. The latter is most strange.
+if(CMAKE_SYSTEM_NAME STREQUAL "iOS" OR CMAKE_SYSTEM_NAME STREQUAL "tvOS")
+    set(CMAKE_OSX_DEPLOYMENT_TARGET "14.0" CACHE STRING "iOS/tvOS Deployment Target")
+    set(CMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH NO)
+elseif(CMAKE_SYSTEM_NAME STREQUAL "visionOS")
+    set(CMAKE_OSX_DEPLOYMENT_TARGET "1.0" CACHE STRING "visionOS Deployment Target")
+else()
+    set(CMAKE_OSX_DEPLOYMENT_TARGET "13.3" CACHE STRING "macOS Deployment Target")
+endif()
+
+project(use-ktx
+    VERSION 1.0
+    DESCRIPTION "Test using libktx project independently of KTX-Software"
+)
+
+set(path_to_ktx ../../lib)
+
+if(WIN32)
+    # Set this to make the ktx build put ktx.dll into the same
+    # directory as use-ktx.exe, so use-ktx can be run in its
+    # build location.
+    set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+endif()
+
+add_subdirectory(${path_to_ktx} ktx)
+
+add_executable(use-ktx
+    use-ktx.cc
+)
+
+target_compile_features(use-ktx PRIVATE cxx_std_20)
+target_link_libraries(use-ktx PRIVATE ktx)
--- a/tests/use-ktx/use-ktx.cc
+++ b/tests/use-ktx/use-ktx.cc
@@ -0,0 +1,25 @@
+// Copyright 2025 The Khronos Group Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+#include <iostream>
+#include <format>
+#include <ktx.h>
+#include <KHR/khr_df.h>
+
+int main(int argc, char* argv[])
+{
+    ktxTexture2* tex;
+    ktx_error_code_e result;
+
+    if (argc < 2) {
+        std::cerr << std::format("{}: Need a file to open\n", argv[0]);
+        return 1;
+    }
+    result = ktxTexture2_CreateFromNamedFile(argv[1], KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT, &tex);
+    if (result != KTX_SUCCESS) {
+        std::cerr << std::format("Could not open {}: {}\n", argv[1], ktxErrorString(result));
+        return 1;
+    }
+    ktxTexture2_Destroy(tex);
+    return 0;
+}