Ziminli · Oct 22, 2026 · Oct 15, 2026 · Oct 15, 2026 · Oct 22, 2026
diff --git a/CMakeLists.txt b/CMakeLists.txt
diff --git a/README.md b/README.md
@@ -161,8 +161,9 @@ These options are available in any CMake project and can be passed during config
 | `CMAKE_BUILD_TYPE` | Build type (`Release`, `Debug`, `RelWithDebInfo`, `MinSizeRel`) | (empty, but `build.sh` sets `Release`) |
 
 > **Notes**:
-> - `AUTO_DETECT_DEVICES` overrides device options like `WITH_NVIDIA` when detection succeeds.
-> - `AUTO_DETECT_BACKENDS` overrides backend options like `WITH_OMPI` when detection succeeds.
+> - `AUTO_DETECT_DEVICES` enables detected devices in addition to devices explicitly enabled with `WITH_*=ON`; explicit selections are preserved.
+> - `AUTO_DETECT_BACKENDS` enables detected backends in addition to backends explicitly enabled with `WITH_*=ON`; explicit selections are preserved.
+> - Disable the corresponding auto-detection option for a strictly manual configuration.
 
 </details>
 

diff --git a/cmake/backends/CNCL.cmake b/cmake/backends/CNCL.cmake
@@ -0,0 +1,40 @@
+include_guard(GLOBAL)
+
+function(_infiniccl_find_cncl prefix required include_output library_output)
+    infiniccl_collect_cambricon_hints(_hints)
+    set(_include_var "${prefix}_INC")
+    set(_library_var "${prefix}_LIB")
+
+    if(required)
+        find_path(${_include_var} NAMES cncl.h
+            HINTS ${_hints} PATH_SUFFIXES include REQUIRED)
+        find_library(${_library_var} NAMES cncl
+            HINTS ${_hints} PATH_SUFFIXES lib lib64 REQUIRED)
+    else()
+        find_path(${_include_var} NAMES cncl.h
+            HINTS ${_hints} PATH_SUFFIXES include QUIET)
+        find_library(${_library_var} NAMES cncl
+            HINTS ${_hints} PATH_SUFFIXES lib lib64 QUIET)
+    endif()
+
+    set(${include_output} "${${_include_var}}" PARENT_SCOPE)
+    set(${library_output} "${${_library_var}}" PARENT_SCOPE)
+endfunction()
+
+function(infiniccl_probe_cncl output)
+    _infiniccl_find_cncl(_INFINICCL_AUTO_CNCL FALSE _include _library)
+    if(_include AND _library)
+        set(${output} TRUE PARENT_SCOPE)
+    else()
+        set(${output} FALSE PARENT_SCOPE)
+    endif()
+endfunction()
+
+function(infiniccl_configure_cncl include_output library_output)
+    if(NOT WITH_CAMBRICON)
+        message(FATAL_ERROR "CNCL backend requires Cambricon device support. Please enable `WITH_CAMBRICON`.")
+    endif()
+    _infiniccl_find_cncl(_INFINICCL_CNCL TRUE _include _library)
+    set(${include_output} "${_include}" PARENT_SCOPE)
+    set(${library_output} "${_library}" PARENT_SCOPE)
+endfunction()
diff --git a/cmake/backends/MCCL.cmake b/cmake/backends/MCCL.cmake
@@ -0,0 +1,63 @@
+include_guard(GLOBAL)
+
+function(_infiniccl_find_mccl prefix provider required include_output library_output)
+    if(provider STREQUAL "METAX")
+        infiniccl_collect_metax_hints(_hints)
+    elseif(provider STREQUAL "MOORE")
+        infiniccl_collect_moore_hints(_hints)
+    else()
+        message(FATAL_ERROR "Unknown MCCL provider `${provider}`.")
+    endif()
+
+    set(_include_var "${prefix}_INC")
+    set(_library_var "${prefix}_LIB")
+    if(required)
+        find_path(${_include_var} NAMES mccl.h
+            HINTS ${_hints} PATH_SUFFIXES include REQUIRED)
+        find_library(${_library_var} NAMES mccl
+            HINTS ${_hints} PATH_SUFFIXES lib lib64 REQUIRED)
+    else()
+        find_path(${_include_var} NAMES mccl.h
+            HINTS ${_hints} PATH_SUFFIXES include QUIET)
+        find_library(${_library_var} NAMES mccl
+            HINTS ${_hints} PATH_SUFFIXES lib lib64 QUIET)
+    endif()
+
+    set(${include_output} "${${_include_var}}" PARENT_SCOPE)
+    set(${library_output} "${${_library_var}}" PARENT_SCOPE)
+endfunction()
+
+function(infiniccl_probe_mccl output)
+    if(WITH_METAX)
+        set(_provider METAX)
+    elseif(WITH_MOORE)
+        set(_provider MOORE)
+    else()
+        set(${output} FALSE PARENT_SCOPE)
+        return()
+    endif()
+
+    _infiniccl_find_mccl(_INFINICCL_AUTO_MCCL ${_provider} FALSE _include _library)
+    if(_include AND _library)
+        set(${output} TRUE PARENT_SCOPE)
+    else()
+        set(${output} FALSE PARENT_SCOPE)
+    endif()
+endfunction()
+
+function(infiniccl_configure_mccl include_output library_output)
+    if(NOT WITH_METAX AND NOT WITH_MOORE)
+        message(FATAL_ERROR
+            "MCCL backend requires MetaX or Moore GPU support. "
+            "Please enable `WITH_METAX` or `WITH_MOORE`.")
+    endif()
+
+    if(WITH_MOORE)
+        set(_provider MOORE)
+    else()
+        set(_provider METAX)
+    endif()
+    _infiniccl_find_mccl(_INFINICCL_MCCL ${_provider} TRUE _include _library)
+    set(${include_output} "${_include}" PARENT_SCOPE)
+    set(${library_output} "${_library}" PARENT_SCOPE)
+endfunction()
diff --git a/cmake/backends/MPI.cmake b/cmake/backends/MPI.cmake
@@ -0,0 +1,29 @@
+include_guard(GLOBAL)
+
+function(infiniccl_detect_mpi output)
+    set(_implementation)
+    find_program(_INFINICCL_MPIRUN_PATH NAMES mpirun mpiexec)
+    find_program(_INFINICCL_MPICC_PATH NAMES mpicc)
+
+    if(_INFINICCL_MPIRUN_PATH AND _INFINICCL_MPICC_PATH)
+        execute_process(
+            COMMAND ${_INFINICCL_MPIRUN_PATH} --version
+            OUTPUT_VARIABLE _version_out
+            ERROR_VARIABLE _version_err
+        )
+        set(_version_info "${_version_out}${_version_err}")
+
+        if(_version_info MATCHES "Open MPI" OR _version_info MATCHES "PRRTE")
+            set(_implementation OMPI)
+        elseif(_version_info MATCHES "MPICH"
+               OR _version_info MATCHES "Hydra"
+               OR _version_info MATCHES "Intel\\(R\\) MPI")
+            set(_implementation MPICH)
+        else()
+            set(_implementation OMPI)
+            message(STATUS "Unknown MPI implementation. Defaulting to `WITH_OMPI=ON`")
+        endif()
+    endif()
+
+    set(${output} "${_implementation}" PARENT_SCOPE)
+endfunction()
diff --git a/cmake/backends/NCCL.cmake b/cmake/backends/NCCL.cmake
@@ -0,0 +1,87 @@
+include_guard(GLOBAL)
+
+function(_infiniccl_find_nccl prefix required include_output library_output definitions_output)
+    set(_hints)
+    set(_header_names nccl.h)
+    set(_library_names nccl)
+    set(_include_suffixes include)
+    set(_library_suffixes lib lib64)
+    set(_definitions)
+
+    if(WITH_THEAD)
+        if(_THEAD_CUDA_HINTS)
+            set(_hints ${_THEAD_CUDA_HINTS})
+        else()
+            infiniccl_collect_thead_hints(_hints)
+        endif()
+        list(APPEND _include_suffixes targets/x86_64-linux/include)
+        list(APPEND _library_suffixes targets/x86_64-linux/lib)
+        message(STATUS "T-Head detected. Searching for NCCL in ${_hints}")
+    elseif(WITH_ILUVATAR)
+        set(_hints /usr/local/corex)
+        message(STATUS "Iluvatar detected. Searching for NCCL in ${_hints}")
+    elseif(WITH_HYGON)
+        infiniccl_collect_hygon_hints(_hints)
+        if(HYGON_DTK_ROOT)
+            list(PREPEND _hints "${HYGON_DTK_ROOT}")
+        endif()
+        set(_roots ${_hints})
+        foreach(_root IN LISTS _roots)
+            list(APPEND _hints "${_root}/rccl")
+        endforeach()
+        set(_header_names rccl/rccl.h rccl.h)
+        set(_library_names rccl)
+        set(_definitions INFINI_CCL_USE_RCCL)
+        list(APPEND _library_suffixes rccl/lib)
+        message(STATUS "Hygon detected. Searching for NCCL-compatible RCCL in ${_hints}")
+    endif()
+    list(REMOVE_DUPLICATES _hints)
+
+    set(_include_var "${prefix}_INC")
+    set(_library_var "${prefix}_LIB")
+    if(required)
+        find_path(${_include_var} NAMES ${_header_names}
+            HINTS ${_hints}
+            PATH_SUFFIXES ${_include_suffixes}
+            REQUIRED)
+        find_library(${_library_var} NAMES ${_library_names}
+            HINTS ${_hints}
+            PATH_SUFFIXES ${_library_suffixes}
+            REQUIRED)
+    else()
+        find_path(${_include_var} NAMES ${_header_names}
+            HINTS ${_hints}
+            PATH_SUFFIXES ${_include_suffixes}
+            QUIET)
+        find_library(${_library_var} NAMES ${_library_names}
+            HINTS ${_hints}
+            PATH_SUFFIXES ${_library_suffixes}
+            QUIET)
+    endif()
+
+    set(${include_output} "${${_include_var}}" PARENT_SCOPE)
+    set(${library_output} "${${_library_var}}" PARENT_SCOPE)
+    set(${definitions_output} "${_definitions}" PARENT_SCOPE)
+endfunction()
+
+function(infiniccl_probe_nccl output)
+    _infiniccl_find_nccl(_INFINICCL_AUTO_NCCL FALSE _include _library _definitions)
+    if(_include AND _library)
+        set(${output} TRUE PARENT_SCOPE)
+    else()
+        set(${output} FALSE PARENT_SCOPE)
+    endif()
+endfunction()
+
+function(infiniccl_configure_nccl include_output library_output definitions_output)
+    if(NOT WITH_NVIDIA AND NOT WITH_THEAD AND NOT WITH_ILUVATAR AND NOT WITH_HYGON)
+        message(FATAL_ERROR
+            "NCCL backend requires NVIDIA, T-Head, Iluvatar, or Hygon GPU support. "
+            "Please enable `WITH_NVIDIA`, `WITH_THEAD`, `WITH_ILUVATAR`, or `WITH_HYGON`.")
+    endif()
+
+    _infiniccl_find_nccl(_INFINICCL_NCCL TRUE _include _library _definitions)
+    set(${include_output} "${_include}" PARENT_SCOPE)
+    set(${library_output} "${_library}" PARENT_SCOPE)
+    set(${definitions_output} "${_definitions}" PARENT_SCOPE)
+endfunction()
diff --git a/cmake/devices/Cambricon.cmake b/cmake/devices/Cambricon.cmake
@@ -0,0 +1,53 @@
+include_guard(GLOBAL)
+
+function(infiniccl_collect_cambricon_hints output)
+    set(_hints)
+    if(DEFINED ENV{NEUWARE_HOME} AND NOT "$ENV{NEUWARE_HOME}" STREQUAL "")
+        list(APPEND _hints "$ENV{NEUWARE_HOME}")
+    endif()
+    list(APPEND _hints /usr/local/neuware)
+    list(REMOVE_DUPLICATES _hints)
+    set(${output} "${_hints}" PARENT_SCOPE)
+endfunction()
+
+function(infiniccl_detect_cambricon output)
+    set(_found FALSE)
+    if(DEFINED ENV{NEUWARE_HOME})
+        set(_found TRUE)
+    else()
+        find_program(_INFINICCL_CAMBRICON_CNMON_PATH cnmon)
+        if(_INFINICCL_CAMBRICON_CNMON_PATH)
+            execute_process(
+                COMMAND ${_INFINICCL_CAMBRICON_CNMON_PATH} -l
+                RESULT_VARIABLE _cnmon_result
+                OUTPUT_QUIET
+                ERROR_QUIET
+            )
+            if(_cnmon_result EQUAL 0)
+                set(_found TRUE)
+            endif()
+        endif()
+    endif()
+    set(${output} ${_found} PARENT_SCOPE)
+endfunction()
+
+function(infiniccl_configure_cambricon)
+    set(_neuware_home "$ENV{NEUWARE_HOME}")
+
+    include_directories("${_neuware_home}/include")
+    link_directories("${_neuware_home}/lib" "${_neuware_home}/lib64")
+    find_library(_INFINICCL_CAMBRICON_RUNTIME_LIB
+        NAMES cnrt HINTS "${_neuware_home}/lib64" REQUIRED)
+    find_library(_INFINICCL_CAMBRICON_CNNL_LIB
+        NAMES cnnl HINTS "${_neuware_home}/lib64" REQUIRED)
+    find_library(_INFINICCL_CAMBRICON_CNNL_EXTRA_LIB
+        NAMES cnnl_extra HINTS "${_neuware_home}/lib64" REQUIRED)
+    find_library(_INFINICCL_CAMBRICON_PAPI_LIB
+        NAMES cnpapi HINTS "${_neuware_home}/lib64" REQUIRED)
+
+    set(NEUWARE_HOME "${_neuware_home}" PARENT_SCOPE)
+    set(CAMBRICON_RUNTIME_LIB "${_INFINICCL_CAMBRICON_RUNTIME_LIB}" PARENT_SCOPE)
+    set(CAMBRICON_CNNL_LIB "${_INFINICCL_CAMBRICON_CNNL_LIB}" PARENT_SCOPE)
+    set(CAMBRICON_CNNL_EXTRA_LIB "${_INFINICCL_CAMBRICON_CNNL_EXTRA_LIB}" PARENT_SCOPE)
+    set(CAMBRICON_PAPI_LIB "${_INFINICCL_CAMBRICON_PAPI_LIB}" PARENT_SCOPE)
+endfunction()
diff --git a/cmake/devices/DeviceDetection.cmake b/cmake/devices/DeviceDetection.cmake
@@ -0,0 +1,28 @@
+include_guard(GLOBAL)
+
+# Preserve explicitly enabled device options and probe only devices that have
+# not been requested. The caller retains responsibility for cross-device
+# policies after all individual device results are available.
+function(infiniccl_resolve_device_detection option display_name detector result_output)
+    if(NOT COMMAND ${detector})
+        message(FATAL_ERROR "Unknown device detector `${detector}` for `${display_name}`.")
+    endif()
+
+    set(_requested ${${option}})
+    if(_requested)
+        set(_found TRUE)
+        message(STATUS "${display_name} support explicitly enabled.")
+    else()
+        cmake_language(CALL ${detector} _found)
+        if(_found)
+            message(STATUS "Auto-detected ${display_name} environment.")
+        else()
+            message(STATUS "${display_name} environment not detected.")
+        endif()
+    endif()
+
+    if(_found)
+        set(${option} ON PARENT_SCOPE)
+    endif()
+    set(${result_output} ${_found} PARENT_SCOPE)
+endfunction()