feat: add flexible compiler flags support and improve documentation

- Add ZIG_COMPILER_FLAGS cache variable for additional compilation flags
- Refactor CPU flags handling to support ZIG_MCPU and ZIG_MCPU_FEATURES separately
- Add comprehensive comments explaining edge case handling for cross-compilation
- Document macOS SDK path prevention and Windows RC compiler syntax requirements
- Bump toolchain version from 0.1.0 to 0.1.1

Author: tayne3

zig.toolchain.cmake

@@ -1,6 +1,6 @@
 include_guard(GLOBAL)
 
-set(ZIG_TOOLCHAIN_VERSION "0.1.0")
+set(ZIG_TOOLCHAIN_VERSION "0.1.1")
 
 if(CMAKE_GENERATOR MATCHES "Visual Studio")
   message(FATAL_ERROR "Zig Toolchain: Visual Studio generator is not supported. Please use '-G Ninja' or '-G MinGW Makefiles'.")
@@ -10,7 +10,6 @@ find_program(ZIG_COMPILER zig)
 if(NOT ZIG_COMPILER)
   message(FATAL_ERROR "Zig Toolchain: Zig compiler not found. Please install Zig and ensure it is in your PATH.")
 endif()
-
 execute_process(
   COMMAND zig version
   OUTPUT_VARIABLE ZIG_COMPILER_VERSION
@@ -29,44 +28,70 @@ if(NOT ZIG_TARGET)
     set(CMAKE_SYSTEM_PROCESSOR "${CMAKE_HOST_SYSTEM_PROCESSOR}")
   endif()
 
-  string(TOLOWER "${CMAKE_SYSTEM_PROCESSOR}" Z_ARCH)
-  if(Z_ARCH MATCHES "arm64|aarch64")
-    set(Z_ARCH "aarch64")
-  elseif(Z_ARCH MATCHES "x64|x86_64|amd64")
-    set(Z_ARCH "x86_64")
+  string(TOLOWER "${CMAKE_SYSTEM_PROCESSOR}" ZIG_ARCH)
+  if(ZIG_ARCH MATCHES "arm64|aarch64")
+    set(ZIG_ARCH "aarch64")
+  elseif(ZIG_ARCH MATCHES "x64|x86_64|amd64")
+    set(ZIG_ARCH "x86_64")
   endif()
 
-  string(TOLOWER "${CMAKE_SYSTEM_NAME}" Z_OS)
-  set(Z_ABI "gnu")
-  if(Z_OS MATCHES "darwin|macos")
-    set(Z_OS "macos")
-    set(Z_ABI "none") # macOS uses its own ABI, not GNU
-  elseif(Z_OS MATCHES "windows")
-    set(Z_OS "windows")
-  elseif(Z_OS MATCHES "linux")
-    set(Z_OS "linux")
+  string(TOLOWER "${CMAKE_SYSTEM_NAME}" ZIG_OS)
+  set(ZIG_ABI "gnu")
+  if(ZIG_OS MATCHES "darwin|macos")
+    set(ZIG_OS "macos")
+    set(ZIG_ABI "none") # macOS uses its own ABI, not GNU
+  elseif(ZIG_OS MATCHES "windows")
+    set(ZIG_OS "windows")
+  elseif(ZIG_OS MATCHES "linux")
+    set(ZIG_OS "linux")
   endif()
 
-  set(ZIG_TARGET "${Z_ARCH}-${Z_OS}-${Z_ABI}")
+  set(ZIG_TARGET "${ZIG_ARCH}-${ZIG_OS}-${ZIG_ABI}")
+else()
+  if(NOT ZIG_TARGET MATCHES "^([a-zA-Z0-9_]+)-([a-zA-Z0-9_]+)(-([a-zA-Z0-9_.]+))?$")
+    message(FATAL_ERROR "Zig Toolchain: ZIG_TARGET is invalid. Please specify it manually using -DZIG_TARGET=<arch>-<os>[-<abi>]")
+  endif()
+  set(ZIG_ARCH ${CMAKE_MATCH_1})
+  set(ZIG_OS ${CMAKE_MATCH_2})
+  if(CMAKE_MATCH_4)
+    set(ZIG_ABI ${CMAKE_MATCH_4})
+  else()
+    set(ZIG_ABI "none")
+  endif()
 endif()
 
-if(ZIG_TARGET MATCHES "^-") 
-  message(FATAL_ERROR "Zig Toolchain: ZIG_TARGET is not set. Please specify it manually using -DZIG_TARGET=...")
+# Dummy version satisfies CMake's cross-compilation requirements without affecting Zig's behavior
+set(CMAKE_SYSTEM_VERSION 1)
+set(CMAKE_SYSTEM_PROCESSOR ${ZIG_ARCH})
+if(ZIG_OS STREQUAL "linux")
+  set(CMAKE_SYSTEM_NAME "Linux")
+elseif(ZIG_OS STREQUAL "windows")
+  set(CMAKE_SYSTEM_NAME "Windows")
+elseif(ZIG_OS STREQUAL "macos")
+  set(CMAKE_SYSTEM_NAME "Darwin")
 else()
-  message(STATUS "Zig Toolchain: v${ZIG_COMPILER_VERSION} → ${ZIG_TARGET}")
+  message(FATAL_ERROR "Unknown OS: ${ZIG_OS}")
 endif()
+message(STATUS "Zig Toolchain: v${ZIG_COMPILER_VERSION} → ${ZIG_TARGET}")
 
-if(ZIG_TARGET MATCHES "windows")
-  set(CMAKE_SYSTEM_NAME Windows)
-elseif(ZIG_TARGET MATCHES "linux")
-  set(CMAKE_SYSTEM_NAME Linux)
-elseif(ZIG_TARGET MATCHES "macos")
-  set(CMAKE_SYSTEM_NAME Darwin)
-endif()
+set(ZIG_MCPU "" CACHE STRING "Target CPU architecture")
+set(ZIG_MCPU_FEATURES "" CACHE STRING "CPU features to enable/disable")
+set(ZIG_COMPILER_FLAGS "" CACHE STRING "Additional compilation flags")
 
-# Dummy version satisfies CMake's cross-compilation requirements without affecting Zig's behavior
-set(CMAKE_SYSTEM_VERSION 1)
-set(CMAKE_SYSTEM_PROCESSOR ${Z_ARCH})
+set(ZIG_WRAPPER_ARGS "")
+if(ZIG_MCPU)
+  string(APPEND ZIG_WRAPPER_ARGS " -mcpu=${ZIG_MCPU}")
+  if(ZIG_MCPU_FEATURES)
+    string(APPEND ZIG_WRAPPER_ARGS "${ZIG_MCPU_FEATURES}")
+  endif()
+endif()
+if(ZIG_COMPILER_FLAGS)
+  string(APPEND ZIG_WRAPPER_ARGS " ${ZIG_COMPILER_FLAGS}")
+endif()
+string(STRIP "${ZIG_WRAPPER_ARGS}" ZIG_WRAPPER_ARGS)
+if(ZIG_WRAPPER_ARGS)
+  message(STATUS "Zig Toolchain: Compiler flags → ${ZIG_WRAPPER_ARGS}")
+endif()
 
 option(ZIG_USE_CCACHE "Enable ccache optimization for Zig toolchain" OFF)
 set(ZIG_CC_PREFIX "")
@@ -93,8 +118,8 @@ else()
   set(ARGS "\"$@\"")
 endif()
 
-file(WRITE "${ZIG_SHIMS_DIR}/zig-cc${EXT}" "${HEADER}\n${ZIG_CC_PREFIX}zig cc -target ${ZIG_TARGET} ${ARGS}\n")
-file(WRITE "${ZIG_SHIMS_DIR}/zig-c++${EXT}" "${HEADER}\n${ZIG_CC_PREFIX}zig c++ -target ${ZIG_TARGET} ${ARGS}\n")
+file(WRITE "${ZIG_SHIMS_DIR}/zig-cc${EXT}" "${HEADER}\n${ZIG_CC_PREFIX}zig cc -target ${ZIG_TARGET} ${ZIG_WRAPPER_ARGS} ${ARGS}\n")
+file(WRITE "${ZIG_SHIMS_DIR}/zig-c++${EXT}" "${HEADER}\n${ZIG_CC_PREFIX}zig c++ -target ${ZIG_TARGET} ${ZIG_WRAPPER_ARGS} ${ARGS}\n")
 file(WRITE "${ZIG_SHIMS_DIR}/zig-ar${EXT}" "${HEADER}\nzig ar ${ARGS}\n")
 file(WRITE "${ZIG_SHIMS_DIR}/zig-rc${EXT}" "${HEADER}\nzig rc ${ARGS}\n")
 file(WRITE "${ZIG_SHIMS_DIR}/zig-ranlib${EXT}" "${HEADER}\nzig ranlib ${ARGS}\n")