Fix Linking Errors on AXLinkHelpers.cmake in release/2.11.4

[WUCJ638]

2026.07.27 Fix Linking Errors on AXLinkHelpers.cmake

---

Summary

This PR contains several fixes for Axmol 2.11.4. All of them are around Prebuilt Feature in AXLinkHelpers.cmake:

• Lack of Include Directories for Extensions;
• Wrong Configuration for Ninja Generator;
• Failing to find axmol.lib;
• Wrong setting for CMAKE_BUILD_TYPE.

When the Prebuilt Function is enabled (AX_PREBUILT_DIR is defined), most general linking steps are skipped, which consiquently leads to linking errors.

Only tested on Windows.

Fixes

1. Lack of Include Directories for Extensions

   • With AX_PREBUILT_DIR defined, the following scripts would be skipped:

     # (AXGameEngineSetup.cmake 28-30)
     if(NOT _AX_USE_PREBUILT)
         add_subdirectory(${_AX_ROOT}/core ${ENGINE_BINARY_PATH}/axmol/core)
     endif()

   • All extensions' CMakeLists.txt, which define subdirectory addition, won't be included.

   • Some extensions, like FairyGUI, would lack several include directories, causing errors like...

     • Cannot find source file 'FairyGUI.h'(from OurOwnProjectFile.h);
     • Cannot find source file 'FairyGUIMacros.h'(from FUILabel.h).

   • Solved by rewriting include dirs according to those inside CMakeLists.txt from every extension.

     The following script does exist in AXGameEngineSetup.cmake...

     ax_link_ext(AX_ENABLE_EXT_IMGUI "ImGui"
         "${AX_ROOT_DIR}/extensions/ImGui/src" "${AX_ROOT_DIR}/extensions/ImGui/src/ImGui/imgui"
     )

     so we imitate it and write the following scripts...

     # (AxLinkHelpers.cmake 174+)
     ax_link_ext(AX_ENABLE_EXT_FAIRYGUI "fairygui" 
         "${AX_ROOT_DIR}/extensions/fairygui/src"
         "${AX_ROOT_DIR}/extensions/fairygui/src/fairygui" # redundant
     )

     Note:

     1. All ax_link_ext are reordered by extension's name.
     2. Effekseer hasn't been modified because I couldn't determine its complex include structure.

2. Wrong Configuration for Ninja Generator

   • For system using Ninja to generate project, its BUILD_CONFIG_DIR is empty.

     # (AXLinkHelper.cmake 4-8)
     if(NOT CMAKE_GENERATOR MATCHES "Ninja")
         set(BUILD_CONFIG_DIR "\$\(Configuration\)/")
     else()
         set(BUILD_CONFIG_DIR "") # need to change into"$<CONFIG>/"
     endif()

     Would affect the use of OpenAL32.dll with Audio feature enabled, because
     • the directory structure looks like this:

       build(Project Axmol)
       |--bin
         |--Debug
         | |--OpenAL32.dll
         |--Release
           |--OpenAL32.dll
       

     • relative CMake script is:

       # (AXLinkHelper.cmake 243-248)
       if(AX_ENABLE_AUDIO)
           add_custom_command(TARGET ${APP_NAME} POST_BUILD
               COMMAND ${CMAKE_COMMAND} -E copy_if_different
               "${AX_ROOT_DIR}/${AX_PREBUILT_DIR}/bin/${BUILD_CONFIG_DIR}OpenAL32.dll"
               # in Ninja, BUILD_CONFIG_DIR is empty ^
               $<TARGET_FILE_DIR:${APP_NAME}>)
       endif()

3. Failing to find axmol.lib

   • Problem occurs at

     # (AXLinkHelper.cmake 126-133)
     target_link_directories(${APP_NAME}
         PRIVATE ${AX_ROOT_DIR}/3rdparty/openssl/_x/lib/${PLATFORM_NAME}/${ARCH_ALIAS}
         PRIVATE ${AX_ROOT_DIR}/3rdparty/zlib/_x/lib/${PLATFORM_NAME}/${ARCH_ALIAS}
         PRIVATE ${AX_ROOT_DIR}/3rdparty/jpeg-turbo/_x/lib/${PLATFORM_NAME}/${ARCH_ALIAS}
         PRIVATE ${AX_ROOT_DIR}/3rdparty/curl/_x/lib/${PLATFORM_NAME}/${ARCH_ALIAS}
         PRIVATE ${AX_ROOT_DIR}/3rdparty/opus/_x/lib/${PLATFORM_NAME}/${ARCH_ALIAS}
         # vvvvvv here
         PRIVATE ${AX_ROOT_DIR}/${AX_PREBUILT_DIR}/lib/ # cmake will auto add suffix '/$(Configuration)', refer to https://github.com/Kitware/CMake/blob/master/Source/cmVisualStudio10TargetGenerator.cxx#L4145
     )

     Project generation would fail with Cannot find library file: axmol.lib, because the dir structure is:

     build(Project Axmol)
     |--lib
       |--Debug
       | |--axmol.lib
       |--Release
         |--axmol.lib
     

     I'm wondering about the comment. I entered the .cxx file, only to find that the code is around CUDA function.
     And Never had CMake auto add '/$(Configuration)'.

   • Solution is to add ${CMAKE_BUILD_TYPE} to PRIVATE ${AX_ROOT_DIR}/${AX_PREBUILT_DIR}/lib/.

     # (AXLinkHelper.cmake 132)
         PRIVATE ${AX_ROOT_DIR}/${AX_PREBUILT_DIR}/lib/${CMAKE_BUILD_TYPE}

4. Wrong setting for CMAKE_BUILD_TYPE

   • ax_link_cxx_prebuilt indicates that the CMAKE_BUILD_TYPE of every project relies on the one from the Prebuilt Axmol:

     function(ax_link_cxx_prebuilt APP_NAME AX_ROOT_DIR AX_PREBUILT_DIR)
         # stupid: exclude CMAKE_CXX_FLAGS_DEBUG CMAKE_C_FLAGS_DEBUG to avoid cmake generate
         # .vcxproj with incorrect debug msvc runtime, should be /MDd but got /MD
         set(AXSLCC_OUT_DIR_PROJ "${AXSLCC_OUT_DIR}")
         # v CMAKE_BUILD_TYPE is not excluded, thus polluted by CMAKE_BUILD_TYPE in `${AX_ROOT_DIR}/${AX_PREBUILT_DIR}/CMakeCache.txt`.
         load_cache("${AX_ROOT_DIR}/${AX_PREBUILT_DIR}" INCLUDE_INTERNALS _NUGET_PACKAGE_DIR EXCLUDE thirdparty_LIB_DEPENDS CMAKE_CXX_FLAGS_DEBUG CMAKE_C_FLAGS_DEBUG)
         set(AXSLCC_OUT_DIR_ENGINE ${AXSLCC_OUT_DIR})

     For example, if Axmol is prebuilt in Release mode, every Axmol Project's CMAKE_BUILD_TYPE would be forced to Release regardless of its own setting.

   • Visual Studio 2026 would fail to configure the Startup Project and CMake Intellisence;
     

   • Visual Studio Code would output, using CMake-Kits Extension, with:

     ...
     [cmake] -- _NUGET_PACKAGE_DIR=D:/axmol-dev/cache/packages
     [cmake] -- Configuring done (5.9s)
     [cmake] -- Generating done (0.1s)
     [cmake] -- Build files have been written to: D:/Interest/Axmol_Cocos2DX/ParticAX/build
     [cpptools] 生成的生成配置不包含活动生成配置。对 CMAKE_BUILD_TYPE 使用 "Release" 而不是 "Debug"，以确保可以找到 IntelliSense 配置
     

     Indicating that current generated project is not configured with Debug, but Release.

   • Solved by adding CMAKE_BUILD_TYPE to load_cache.

     load_cache("${AX_ROOT_DIR}/${AX_PREBUILT_DIR}" 
         INCLUDE_INTERNALS _NUGET_PACKAGE_DIR 
         EXCLUDE thirdparty_LIB_DEPENDS 
             CMAKE_CXX_FLAGS_DEBUG 
             CMAKE_C_FLAGS_DEBUG 
             CMAKE_BUILD_TYPE
     )

Testing

• Verified on Windows 10 (22h2) with MSVC 19.51, CMake 4.2.0.
• In Axmol Root Directory, run script sequently to prebuild Axmol in Debug and Release Mode.
  (For example, in folder D/axmol-2.11.4)

  cmake -B build_x64 -A x64 "-DAX_BUILD_TESTS=OFF"
  cmake --build build_x64 --config Release
  cmake --build build_x64 --config Debug

• Then create/open an Axmol Projects, with AX_PREBUILT_DIR set (for example, build_x64).

  You can use my project, which contains FairyGUI, or DragonBones-Test, which contains Dragonbones, to test,

• Opening CMake Project var Visual Studio 2026, we're able to set our executable as Startup Project.
  
• Without defining AX_PREBUILT_DIR, the project could still be built, but consuming more time to build the whole engine.

  (Without using AX_PREBUILT_DIR)
  ...
  [831/836] Building CXX object CMakeFiles\ParticAX.dir\Source\FUI638\Panels\PanelColorEdit.cpp.obj
  [832/836] Building CXX object CMakeFiles\ParticAX.dir\proj.win32\main.cpp.obj
  [833/836] Building CXX object CMakeFiles\ParticAX.dir\Source\FUI638\Panels\PanelListParticle.cpp.obj
  [834/836] Building CXX object CMakeFiles\ParticAX.dir\Source\FileLoader.cpp.obj
  [835/836] Building CXX object CMakeFiles\ParticAX.dir\Source\MainEditor.cpp.obj
  [836/836] Linking CXX executable bin\ParticAX\ParticAX.exe
  

  (With using AX_PREBUILT_DIR)
  ...
  [37/42] Building CXX object CMakeFiles\ParticAX.dir\Source\FUI638\Panels\PanelColorEdit.cpp.obj
  [38/42] Building CXX object CMakeFiles\ParticAX.dir\proj.win32\main.cpp.obj
  [39/42] Building CXX object CMakeFiles\ParticAX.dir\Source\FUI638\Panels\PanelListParticle.cpp.obj
  [40/42] Building CXX object CMakeFiles\ParticAX.dir\Source\FileLoader.cpp.obj
  [41/42] Building CXX object CMakeFiles\ParticAX.dir\Source\MainEditor.cpp.obj
  [42/42] Linking CXX executable bin\ParticAX\ParticAX.exe
  

Note:

1. Effekseer hasn't been modified yet in Fixes 1.
2. Only Windows 10 is tested, because I have no access to the other platforms.