Is there a better way to manage dependency libraries? | 是否有更好的依赖库管理方式？

[Demonese]

Current Situation

The dependency libraries of LuaSTG Sub are primarily managed in the following ways:

1. Added as Git submodules, and handled in the CMake scripts by:
   1.1. Manually writing add_library configurations (e.g., imgui)
   1.2. Or directly using add_subdirectory (e.g., luajit)
2. Fetched via CPM.cmake to pull the source code of dependencies, then handled in the CMake scripts by:
   2.1. Letting CPM.cmake configure the dependency automatically (e.g., spdlog)
   2.2. Or downloading only the source code and manually writing add_library configurations (e.g., stb)
   2.3. Or downloading only the source code, manually writing add_custom_command to invoke CMake to build and install the dependency separately, and then manually writing add_library to import it (e.g., zlib-ng)

What Problems Exist?

The most problematic approach is item 2.3 above. Although it can run stably now, the implementation is essentially sh*t.

Why Do We Do This?

Many dependency libraries use wildly inconsistent methods to locate their own transitive dependencies, making it impossible to simply integrate them into our project using add_subdirectory.

The most appropriate way to use such libraries is to build and install them into the system, and then reference them by searching from the installed locations.

For example, when minizip-ng searches for its dependency zlib / zlib-ng, it looks for files like zlib-ng.h and zlib.lib in standard search paths.

Even if you add both libraries to your project like this:

add_subdirectory(zlib-ng)
add_subdirectory(minizip-ng)

minizip-ng still cannot find the CMake target of zlib-ng.

Current Workaround

To handle dependencies with complex transitive dependencies, LuaSTG Sub uses add_custom_command in its CMake scripts to invoke CMake separately for configuring, building, and installing those libraries, and then manually imports them afterward.

Take freetype as an example:

# libfreetype

CPMAddPackage(
    NAME libfreetype
    VERSION 2.13.3
    GITHUB_REPOSITORY freetype/freetype
    GIT_TAG VER-2-13-3
    DOWNLOAD_ONLY YES
)

if(libfreetype_ADDED)
    set(libfreetype_source_dir  ${libfreetype_SOURCE_DIR})
    set(libfreetype_build_dir   ${CMAKE_CURRENT_BINARY_DIR}/libfreetype/$<CONFIG>)
    set(libfreetype_install_dir ${CMAKE_CURRENT_BINARY_DIR}/install/$<CONFIG>)
    set(libfreetype_lib_file    ${libfreetype_install_dir}/lib/freetype$<$<CONFIG:Debug>:d>.lib)
    set(libfreetype_options
        # install location
        -DCMAKE_INSTALL_PREFIX=${libfreetype_install_dir}
        # msvc runtime library
        -DCMAKE_POLICY_DEFAULT_CMP0091=NEW
        -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded$<$<CONFIG:Debug>:Debug>
        # force utf-8
        -DCMAKE_C_FLAGS=/utf-8
        #-DCMAKE_CXX_FLAGS=/utf-8  # freetype is C lib
        # libfreetype options
        -DFT_DISABLE_ZLIB=ON
        -DFT_DISABLE_BZIP2=ON
        -DFT_DISABLE_PNG=ON
        -DFT_DISABLE_HARFBUZZ=ON
        -DFT_DISABLE_BROTLI=ON
    )
    add_custom_command(
        OUTPUT ${libfreetype_lib_file}
        COMMAND echo ${CMAKE_GENERATOR}
        COMMAND echo ${CMAKE_GENERATOR_PLATFORM}
        COMMAND echo $<CONFIG>
        COMMAND cmake -S ${libfreetype_source_dir} -B ${libfreetype_build_dir} -G ${CMAKE_GENERATOR} -A ${CMAKE_GENERATOR_PLATFORM} ${libfreetype_options}
        # magic target for MSVC
        COMMAND cmake --build   ${libfreetype_build_dir} --config $<CONFIG> --target ALL_BUILD
        COMMAND cmake --install ${libfreetype_build_dir} --config $<CONFIG> --prefix ${libfreetype_install_dir}
        VERBATIM
    )
    add_custom_target(libfreetype_build ALL
        DEPENDS ${libfreetype_lib_file}
    )
    add_custom_target(libfreetype_clean
        COMMAND cmake -E rm -rf ${libfreetype_build_dir}
        COMMAND cmake -E rm -f ${libfreetype_lib_file}
        VERBATIM
    )
    set_target_properties(libfreetype_build PROPERTIES FOLDER external)
    set_target_properties(libfreetype_clean PROPERTIES FOLDER external)

    # fuck cmake
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/Debug/include/freetype2/placeholder "")
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/Release/include/freetype2/placeholder "")
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/RelWithDebInfo/include/freetype2/placeholder "")
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/MinSizeRel/include/freetype2/placeholder "")

    # libfreetype
    add_library(libfreetype STATIC IMPORTED GLOBAL)
    add_library(Freetype::Freetype ALIAS libfreetype)
    target_include_directories(libfreetype
    INTERFACE
        ${libfreetype_install_dir}/include
        ${libfreetype_install_dir}/include/freetype2
    )
    set_target_properties(libfreetype PROPERTIES
        IMPORTED_LOCATION       ${CMAKE_CURRENT_BINARY_DIR}/install/Release/lib/freetype.lib
        IMPORTED_LOCATION_DEBUG ${CMAKE_CURRENT_BINARY_DIR}/install/Debug/lib/freetyped.lib
    )
    add_dependencies(libfreetype libfreetype_build)
endif()

The process can be summarized as follows:

1. Download the source code
2. Invoke CMake to configure (CMake Configure)
3. Invoke CMake to build (CMake Build)
4. Invoke CMake to install (CMake Install)
5. Import the library via add_library

Where is a better solution?

Perhaps vcpkg is a better choice.

However, right after getting started, minizip-ng hit me like a ton of bricks: the minizip-ng package in vcpkg doesn’t support linking against zlib-ng at all. Instead, it pulls in and links to a separate zlib library. This completely baffled me, so the migration to vcpkg has been paused.

---

现状

LuaSTG Sub 的依赖库主要由以下几种方式管理：

1. 添加为 Git 子模块，在 CMake 脚本中：
   1.1. 手动编写 add_library 配置（比如 imgui）
   1.2. 或直接 add_subdirectory（比如 luajit）
2. 通过 CPM.cmake 拉取依赖库源代码，在 CMake 脚本中：
   2.1. 由 CPM.cmake 自动配置（比如 spdlog）
   2.2. 或仅下载源码，手动编写 add_library 配置（比如 stb）
   2.3. 或仅下载源码，手动编写 add_custom_command 调用 CMake 构建并安装，并手动编写 add_library 导入（比如 zlib-ng）

存在哪些问题？

问题最严重的是上述的 2.3 点，虽然目前能稳定地配置依赖库，但实现的方式简直就是屎。

为什么要这么做？

因为很多依赖库自身的依赖库的查找方式千奇百怪，无法简单地通过 add_subdirectory 直接添加到我们的项目中。

它们最合适的使用方式就是：编译并安装到系统中，引用这些依赖库时则从安装位置搜索。

比如 minizip-ng 搜索依赖库 zlib / zlib-ng 时，会前往搜索路径下查找对应的 zlib-ng.h、zlib.lib 等文件。

即使你通过：

add_subdirectory(zlib-ng)
add_subdirectory(minizip-ng)

将它们同时添加到项目中，minizip-ng 也无法找到 zlib-ng 的目标（Target）。

目前的解决方式

为了处理这些有着复杂的依赖项的依赖库，LuaSTG Sub 在 CMake 脚本中通过 add_custom_command 调用 CMake 单独执行配置、构建、安装，然后再手动导入。

以 freetype 为例：

# libfreetype

CPMAddPackage(
    NAME libfreetype
    VERSION 2.13.3
    GITHUB_REPOSITORY freetype/freetype
    GIT_TAG VER-2-13-3
    DOWNLOAD_ONLY YES
)

if(libfreetype_ADDED)
    set(libfreetype_source_dir  ${libfreetype_SOURCE_DIR})
    set(libfreetype_build_dir   ${CMAKE_CURRENT_BINARY_DIR}/libfreetype/$<CONFIG>)
    set(libfreetype_install_dir ${CMAKE_CURRENT_BINARY_DIR}/install/$<CONFIG>)
    set(libfreetype_lib_file    ${libfreetype_install_dir}/lib/freetype$<$<CONFIG:Debug>:d>.lib)
    set(libfreetype_options
        # install location
        -DCMAKE_INSTALL_PREFIX=${libfreetype_install_dir}
        # msvc runtime library
        -DCMAKE_POLICY_DEFAULT_CMP0091=NEW
        -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded$<$<CONFIG:Debug>:Debug>
        # force utf-8
        -DCMAKE_C_FLAGS=/utf-8
        #-DCMAKE_CXX_FLAGS=/utf-8  # freetype is C lib
        # libfreetype options
        -DFT_DISABLE_ZLIB=ON
        -DFT_DISABLE_BZIP2=ON
        -DFT_DISABLE_PNG=ON
        -DFT_DISABLE_HARFBUZZ=ON
        -DFT_DISABLE_BROTLI=ON
    )
    add_custom_command(
        OUTPUT ${libfreetype_lib_file}
        COMMAND echo ${CMAKE_GENERATOR}
        COMMAND echo ${CMAKE_GENERATOR_PLATFORM}
        COMMAND echo $<CONFIG>
        COMMAND cmake -S ${libfreetype_source_dir} -B ${libfreetype_build_dir} -G ${CMAKE_GENERATOR} -A ${CMAKE_GENERATOR_PLATFORM} ${libfreetype_options}
        # magic target for MSVC
        COMMAND cmake --build   ${libfreetype_build_dir} --config $<CONFIG> --target ALL_BUILD
        COMMAND cmake --install ${libfreetype_build_dir} --config $<CONFIG> --prefix ${libfreetype_install_dir}
        VERBATIM
    )
    add_custom_target(libfreetype_build ALL
        DEPENDS ${libfreetype_lib_file}
    )
    add_custom_target(libfreetype_clean
        COMMAND cmake -E rm -rf ${libfreetype_build_dir}
        COMMAND cmake -E rm -f ${libfreetype_lib_file}
        VERBATIM
    )
    set_target_properties(libfreetype_build PROPERTIES FOLDER external)
    set_target_properties(libfreetype_clean PROPERTIES FOLDER external)

    # fuck cmake
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/Debug/include/freetype2/placeholder "")
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/Release/include/freetype2/placeholder "")
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/RelWithDebInfo/include/freetype2/placeholder "")
    file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/install/MinSizeRel/include/freetype2/placeholder "")

    # libfreetype
    add_library(libfreetype STATIC IMPORTED GLOBAL)
    add_library(Freetype::Freetype ALIAS libfreetype)
    target_include_directories(libfreetype
    INTERFACE
        ${libfreetype_install_dir}/include
        ${libfreetype_install_dir}/include/freetype2
    )
    set_target_properties(libfreetype PROPERTIES
        IMPORTED_LOCATION       ${CMAKE_CURRENT_BINARY_DIR}/install/Release/lib/freetype.lib
        IMPORTED_LOCATION_DEBUG ${CMAKE_CURRENT_BINARY_DIR}/install/Debug/lib/freetyped.lib
    )
    add_dependencies(libfreetype libfreetype_build)
endif()

流程可以概括为：

1. 下载源代码
2. 调用 CMake 配置（CMake Configure）
3. 调用 CMake 编译（CMake Build）
4. 调用 CMake 安装（CMake Install）
5. 导入库 add_library

更好的方案在哪？

也许 vcpkg 是个更好的选择。

但才刚上手，minizip-ng 就给了我当头一棒，vcpkg 中的 minizip-ng 居然不支持链接到 zlib-ng，而是额外添加 zlib 库并链接。这个操作给我看傻眼了，所以迁移到 vcpkg 的进展被迫暂停。