clang-tool-chain 1.0.42__py3-none-any.whl → 1.0.44__py3-none-any.whl

clang_tool_chain/__version__.py

@@ -1,3 +1,3 @@
 """Version information for clang-tool-chain."""
 
-__version__ = "1.0.42"
+__version__ = "1.0.44"

clang_tool_chain/execution/__init__.py

@@ -5,10 +5,12 @@ This package provides:
 - Core tool execution: execute_tool, run_tool
 - Build utilities: build_main, build_run_main
 - sccache wrappers for compilation caching
+- Sanitizer environment configuration
 """
 
 from clang_tool_chain.execution.build import build_main, build_run_main
 from clang_tool_chain.execution.core import execute_tool, run_tool, sccache_clang_cpp_main, sccache_clang_main
+from clang_tool_chain.execution.sanitizer_env import detect_sanitizers_from_flags, prepare_sanitizer_environment
 
 __all__ = [
     # Core execution
@@ -20,4 +22,7 @@ __all__ = [
     # sccache wrappers
     "sccache_clang_main",
     "sccache_clang_cpp_main",
+    # Sanitizer utilities
+    "prepare_sanitizer_environment",
+    "detect_sanitizers_from_flags",
 ]

clang_tool_chain/execution/arg_transformers.py

@@ -209,9 +209,10 @@ class LLDLinkerTransformer(ArgumentTransformer):
 
     Priority: 200 (runs after SDK but before ABI)
 
-    This transformer adds platform-specific linker flags:
-    - macOS: -fuse-ld=ld64.lld (explicit Mach-O linker, LLVM 21.x+)
-    - Linux: -fuse-ld=lld (standard ELF linker)
+    This transformer adds -fuse-ld=lld linker flag. The clang driver
+    automatically dispatches to the correct linker binary:
+    - macOS: ld64.lld (Mach-O linker)
+    - Linux: ld.lld (ELF linker)
 
     It also translates GNU ld flags to ld64.lld equivalents on macOS:
     - --no-undefined -> -undefined error
@@ -293,11 +294,16 @@ class ASANRuntimeTransformer(ArgumentTransformer):
     This transformer ensures proper ASAN runtime linking on Linux:
     - Detects -fsanitize=address flag
     - Adds -shared-libasan to use shared runtime library
+    - Adds -Wl,--allow-shlib-undefined when building shared libraries with ASAN
     - Prevents undefined symbol errors during linking
 
     The shared runtime library (libclang_rt.asan.so) contains the full
     ASAN implementation, while the static wrapper library only contains stubs.
 
+    When building shared libraries with sanitizers, the library may have undefined
+    symbols that will be provided by the sanitizer runtime when loaded. LLD by
+    default enforces no undefined symbols, so we need to allow them explicitly.
+
     Environment Variables:
         CLANG_TOOL_CHAIN_NO_SHARED_ASAN: Set to '1' to disable shared ASAN
     """
@@ -306,7 +312,9 @@ class ASANRuntimeTransformer(ArgumentTransformer):
         return 250
 
     def transform(self, args: list[str], context: ToolContext) -> list[str]:
-        """Add -shared-libasan when using ASAN on Linux."""
+        """Add -shared-libasan and --allow-shlib-undefined when using ASAN on Linux."""
+        import sys
+
         # Only applies to Linux clang/clang++
         if context.platform_name != "linux" or context.tool_name not in ("clang", "clang++"):
             return args
@@ -316,19 +324,41 @@ class ASANRuntimeTransformer(ArgumentTransformer):
         if not has_asan:
             return args
 
+        result = list(args)
+        injected_flags = []
+
         # Check if user disabled shared ASAN
-        if os.environ.get("CLANG_TOOL_CHAIN_NO_SHARED_ASAN") == "1":
+        if os.environ.get("CLANG_TOOL_CHAIN_NO_SHARED_ASAN") != "1":
+            # Check if -shared-libasan already present
+            if "-shared-libasan" not in args:
+                # Add -shared-libasan to use shared runtime library
+                # This prevents undefined symbol errors during linking
+                logger.info("Adding -shared-libasan for ASAN runtime linking on Linux")
+                result = ["-shared-libasan"] + result
+                injected_flags.append("-shared-libasan")
+        else:
             logger.debug("Shared ASAN disabled via CLANG_TOOL_CHAIN_NO_SHARED_ASAN=1")
-            return args
 
-        # Check if -shared-libasan already present
-        if "-shared-libasan" in args:
-            return args
+        # Check if building a shared library with ASAN
+        # Shared libraries need to allow undefined symbols that will be provided
+        # by the sanitizer runtime when the runner loads them
+        is_shared_lib = "-shared" in args
+        if is_shared_lib:
+            # Check if --allow-shlib-undefined already present
+            has_allow_shlib_undefined = any("--allow-shlib-undefined" in arg for arg in args)
+            if not has_allow_shlib_undefined:
+                logger.info("Adding -Wl,--allow-shlib-undefined for shared library with ASAN")
+                result = ["-Wl,--allow-shlib-undefined"] + result
+                injected_flags.append("-Wl,--allow-shlib-undefined")
+
+        # Warn on stderr if we injected flags
+        if injected_flags:
+            print(
+                f"clang-tool-chain: note: automatically injected sanitizer flags: {' '.join(injected_flags)}",
+                file=sys.stderr,
+            )
 
-        # Add -shared-libasan to use shared runtime library
-        # This prevents undefined symbol errors during linking
-        logger.info("Adding -shared-libasan for ASAN runtime linking on Linux")
-        return ["-shared-libasan"] + args
+        return result
 
 
 class RPathTransformer(ArgumentTransformer):

clang_tool_chain/execution/build_pipeline.py

@@ -137,7 +137,7 @@ def _get_directive_args(source_path: Path) -> list[str]:
             print(f"  Effective args: {' '.join(all_args)}", file=sys.stderr)
 
         return all_args
-    except KeyboardInterrupt:  # noqa: KBI002
+    except KeyboardInterrupt:
         # Re-raise KeyboardInterrupt to allow clean exit
         raise
     except Exception as e:
@@ -249,6 +249,8 @@ class BuildPipeline(ABC):
         Raises:
             SystemExit: Always exits with the executable's return code
         """
+        from clang_tool_chain.execution.sanitizer_env import prepare_sanitizer_environment
+
         program_args = self.config.program_args or []
 
         print(f"\nRunning: {self.config.output_file}", file=sys.stderr)
@@ -256,11 +258,15 @@ class BuildPipeline(ABC):
             print(f"Program arguments: {' '.join(program_args)}", file=sys.stderr)
         print("=" * 60, file=sys.stderr)
 
+        # Prepare environment with sanitizer options for better stack traces
+        # Only inject options if the corresponding sanitizer was used during compilation
+        env = prepare_sanitizer_environment(compiler_flags=self.config.compiler_flags)
+
         # Run the compiled executable
         try:
             # Use absolute path for Windows compatibility
             abs_output = self.output_path.absolute()
-            result = subprocess.run([str(abs_output)] + program_args)
+            result = subprocess.run([str(abs_output)] + program_args, env=env)
             sys.exit(result.returncode)
         except FileNotFoundError:
             print(f"\n{'=' * 60}", file=sys.stderr)

clang_tool_chain/execution/sanitizer_env.py

@@ -0,0 +1,120 @@
+"""
+Sanitizer runtime environment configuration.
+
+This module provides automatic injection of ASAN_OPTIONS and LSAN_OPTIONS
+environment variables to improve stack trace quality when running executables
+compiled with Address Sanitizer or Leak Sanitizer.
+
+The default options fix <unknown module> entries in stack traces from
+dlopen()'d shared libraries by enabling slow unwinding and symbolization.
+"""
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+# Default options to inject for optimal stack traces
+# fast_unwind_on_malloc=0: Use slow but accurate unwinding (fixes <unknown module>)
+# symbolize=1: Enable symbolization for readable stack traces
+# detect_leaks=1: Enable leak detection (ASAN only)
+DEFAULT_ASAN_OPTIONS = "fast_unwind_on_malloc=0:symbolize=1:detect_leaks=1"
+DEFAULT_LSAN_OPTIONS = "fast_unwind_on_malloc=0:symbolize=1"
+
+
+def detect_sanitizers_from_flags(compiler_flags: list[str]) -> tuple[bool, bool]:
+    """
+    Detect which sanitizers are enabled from compiler flags.
+
+    Args:
+        compiler_flags: List of compiler flags passed to clang.
+
+    Returns:
+        Tuple of (asan_enabled, lsan_enabled).
+
+    Example:
+        >>> detect_sanitizers_from_flags(["-fsanitize=address", "-O2"])
+        (True, True)  # ASAN implies LSAN by default
+        >>> detect_sanitizers_from_flags(["-fsanitize=leak"])
+        (False, True)
+        >>> detect_sanitizers_from_flags(["-O2", "-Wall"])
+        (False, False)
+    """
+    asan_enabled = False
+    lsan_enabled = False
+
+    for flag in compiler_flags:
+        if flag.startswith("-fsanitize="):
+            # Extract sanitizer list (e.g., "-fsanitize=address,undefined" -> "address,undefined")
+            sanitizers = flag.split("=", 1)[1].split(",")
+            for sanitizer in sanitizers:
+                sanitizer = sanitizer.strip()
+                if sanitizer == "address":
+                    asan_enabled = True
+                    # ASAN includes LSAN by default (unless detect_leaks=0)
+                    lsan_enabled = True
+                elif sanitizer == "leak":
+                    lsan_enabled = True
+
+    return asan_enabled, lsan_enabled
+
+
+def prepare_sanitizer_environment(
+    base_env: dict[str, str] | None = None,
+    compiler_flags: list[str] | None = None,
+) -> dict[str, str]:
+    """
+    Prepare environment with optimal sanitizer options.
+
+    This function injects ASAN_OPTIONS and/or LSAN_OPTIONS environment variables
+    if they are not already set by the user AND the corresponding sanitizer was
+    enabled during compilation. The injected options improve stack trace quality
+    for executables using dlopen()'d shared libraries.
+
+    Args:
+        base_env: Base environment dictionary to modify. If None, uses os.environ.
+        compiler_flags: List of compiler flags used to build the executable.
+            Used to detect which sanitizers are enabled. If None, no options
+            are injected (safe default).
+
+    Returns:
+        Environment dictionary with sanitizer options injected as appropriate.
+
+    Environment Variables:
+        CLANG_TOOL_CHAIN_NO_SANITIZER_ENV: Set to "1", "true", or "yes" to
+            disable automatic injection of sanitizer options.
+        ASAN_OPTIONS: If already set, preserved as-is (user config takes priority).
+        LSAN_OPTIONS: If already set, preserved as-is (user config takes priority).
+
+    Example:
+        >>> env = prepare_sanitizer_environment(compiler_flags=["-fsanitize=address"])
+        >>> # env now contains ASAN_OPTIONS and LSAN_OPTIONS
+        >>> env = prepare_sanitizer_environment(compiler_flags=["-O2"])
+        >>> # env unchanged - no sanitizers enabled
+    """
+    env = base_env.copy() if base_env is not None else os.environ.copy()
+
+    # Check if disabled via environment variable
+    if os.environ.get("CLANG_TOOL_CHAIN_NO_SANITIZER_ENV", "").lower() in ("1", "true", "yes"):
+        logger.debug("Sanitizer environment injection disabled via CLANG_TOOL_CHAIN_NO_SANITIZER_ENV")
+        return env
+
+    # If no compiler flags provided, don't inject anything (safe default)
+    if compiler_flags is None:
+        logger.debug("No compiler flags provided, skipping sanitizer environment injection")
+        return env
+
+    # Detect which sanitizers are enabled
+    asan_enabled, lsan_enabled = detect_sanitizers_from_flags(compiler_flags)
+
+    # Inject ASAN_OPTIONS if ASAN is enabled and not already set by user
+    if asan_enabled and "ASAN_OPTIONS" not in env:
+        env["ASAN_OPTIONS"] = DEFAULT_ASAN_OPTIONS
+        logger.info(f"Injecting ASAN_OPTIONS={DEFAULT_ASAN_OPTIONS}")
+
+    # Inject LSAN_OPTIONS if LSAN is enabled and not already set by user
+    if lsan_enabled and "LSAN_OPTIONS" not in env:
+        env["LSAN_OPTIONS"] = DEFAULT_LSAN_OPTIONS
+        logger.info(f"Injecting LSAN_OPTIONS={DEFAULT_LSAN_OPTIONS}")
+
+    return env

clang_tool_chain/linker/lld.py

@@ -6,129 +6,48 @@ This module provides functions for:
 - Translating GNU ld flags to ld64.lld equivalents on macOS
 - Managing linker selection based on platform and user preferences
 - Ensuring ld64.lld symlink exists on macOS (runtime fallback)
-- LLVM version detection with caching for compatibility decisions
 """
 
 import logging
 import os
-import re
-import subprocess
 import sys
 
 from clang_tool_chain.interrupt_utils import handle_keyboard_interrupt_properly
+from clang_tool_chain.llvm_versions import get_llvm_version_tuple, supports_ld64_lld_flag
 
 logger = logging.getLogger(__name__)
 
-# Module-level cache for LLVM version (avoids repeated subprocess calls)
-_cached_llvm_version: tuple[int, int, int] | None = None
 
-
-def _get_llvm_version() -> tuple[int, int, int] | None:
+def _get_llvm_version_for_platform() -> tuple[int, int, int]:
     """
-    Get the LLVM version of the installed clang, with caching.
-
-    This runs `clang --version` and parses the version number. The result
-    is cached in memory for the duration of the process, and also cached
-    to a file in the install directory for persistence across invocations.
+    Get the LLVM version for the current platform from centralized configuration.
 
     Returns:
-        Tuple of (major, minor, patch) version numbers, or None if detection fails.
+        Tuple of (major, minor, patch) version numbers.
     """
-    global _cached_llvm_version
-
-    # Return memory-cached version if available
-    if _cached_llvm_version is not None:
-        return _cached_llvm_version
-
-    # Try to read from file cache
-    try:
-        from ..platform.detection import get_platform_binary_dir
-
-        bin_dir = get_platform_binary_dir()
-        cache_file = bin_dir.parent / ".llvm_version_cache"
-
-        if cache_file.exists():
-            cached = cache_file.read_text().strip()
-            parts = cached.split(".")
-            if len(parts) >= 3:
-                _cached_llvm_version = (int(parts[0]), int(parts[1]), int(parts[2]))
-                logger.debug(f"Loaded LLVM version from cache: {_cached_llvm_version}")
-                return _cached_llvm_version
-    except KeyboardInterrupt as ke:
-        handle_keyboard_interrupt_properly(ke)
-    except Exception as e:
-        logger.debug(f"Could not read LLVM version cache: {e}")
+    from ..platform.detection import get_platform_info
 
-    # Detect version by running clang --version
-    try:
-        from ..platform.detection import get_platform_binary_dir
-
-        bin_dir = get_platform_binary_dir()
-        clang_path = bin_dir / "clang"
-
-        if not clang_path.exists():
-            logger.debug(f"Clang binary not found at {clang_path}")
-            return None
-
-        result = subprocess.run(
-            [str(clang_path), "--version"],
-            capture_output=True,
-            text=True,
-            timeout=10,
-        )
-
-        if result.returncode != 0:
-            logger.debug(f"clang --version failed: {result.stderr}")
-            return None
-
-        # Parse version from output like "clang version 19.1.7 (...)"
-        version_match = re.search(r"clang version (\d+)\.(\d+)\.(\d+)", result.stdout)
-        if version_match:
-            major, minor, patch = int(version_match.group(1)), int(version_match.group(2)), int(version_match.group(3))
-            _cached_llvm_version = (major, minor, patch)
-            logger.debug(f"Detected LLVM version: {_cached_llvm_version}")
-
-            # Save to file cache for persistence
-            try:
-                cache_file = bin_dir.parent / ".llvm_version_cache"
-                cache_file.write_text(f"{major}.{minor}.{patch}")
-                logger.debug(f"Saved LLVM version to cache: {cache_file}")
-            except KeyboardInterrupt as ke:
-                handle_keyboard_interrupt_properly(ke)
-            except Exception as e:
-                logger.debug(f"Could not write LLVM version cache: {e}")
-
-            return _cached_llvm_version
-
-        logger.debug(f"Could not parse LLVM version from: {result.stdout[:200]}")
-        return None
-
-    except KeyboardInterrupt as ke:
-        handle_keyboard_interrupt_properly(ke)
-    except Exception as e:
-        logger.debug(f"LLVM version detection failed: {e}")
-        return None
+    platform_name, _ = get_platform_info()
+    return get_llvm_version_tuple(platform_name)
 
 
 def _llvm_supports_ld64_lld_flag() -> bool:
     """
-    Check if the installed LLVM version supports -fuse-ld=ld64.lld.
+    Check if the current platform's LLVM version supports -fuse-ld=ld64.lld.
 
-    The -fuse-ld=ld64.lld flag is only recognized by LLVM 21.x and later.
-    Earlier versions require -fuse-ld=lld (which auto-detects Mach-O from target).
+    Note: The clang driver does NOT recognize -fuse-ld=ld64.lld as a valid option.
+    This function exists for backward compatibility but always returns False in practice
+    because -fuse-ld=lld should be used instead (clang auto-dispatches to ld64.lld on Darwin).
 
     Returns:
-        True if LLVM >= 21.x, False otherwise (or if version detection fails).
+        True if LLVM >= 21.x (but we always fall back to -fuse-ld=lld anyway)
     """
-    version = _get_llvm_version()
-    if version is None:
-        # If we can't detect version, assume older LLVM for safety
-        logger.debug("Could not detect LLVM version, assuming < 21.x for ld64.lld compatibility")
-        return False
+    from ..platform.detection import get_platform_info
 
-    major, _, _ = version
-    supports = major >= 21
-    logger.debug(f"LLVM {major}.x {'supports' if supports else 'does not support'} -fuse-ld=ld64.lld")
+    platform_name, _ = get_platform_info()
+    supports = supports_ld64_lld_flag(platform_name)
+    version = get_llvm_version_tuple(platform_name)
+    logger.debug(f"LLVM {version[0]}.x {'supports' if supports else 'does not support'} -fuse-ld=ld64.lld")
     return supports
 
 
@@ -354,6 +273,39 @@ def _user_specified_lld_on_macos(args: list[str]) -> bool:
     return "-fuse-ld=lld" in args_str or "-fuse-ld=ld64.lld" in args_str
 
 
+def _user_specified_ld64_lld(args: list[str]) -> bool:
+    """
+    Check if the user explicitly specified -fuse-ld=ld64.lld.
+
+    This is used to emit a warning that the flag will be auto-converted
+    to -fuse-ld=lld since clang driver doesn't recognize ld64.lld.
+
+    Args:
+        args: Command-line arguments
+
+    Returns:
+        True if user specified -fuse-ld=ld64.lld
+    """
+    return any("-fuse-ld=ld64.lld" in arg for arg in args)
+
+
+def _convert_ld64_lld_to_lld(args: list[str]) -> list[str]:
+    """
+    Convert -fuse-ld=ld64.lld to -fuse-ld=lld in arguments.
+
+    The clang driver does not recognize -fuse-ld=ld64.lld as a valid option.
+    This function converts it to -fuse-ld=lld which the driver recognizes
+    and automatically dispatches to ld64.lld on Darwin targets.
+
+    Args:
+        args: Original compiler arguments
+
+    Returns:
+        Modified arguments with -fuse-ld=ld64.lld replaced by -fuse-ld=lld
+    """
+    return [arg.replace("-fuse-ld=ld64.lld", "-fuse-ld=lld") for arg in args]
+
+
 # pyright: reportUnusedFunction=false
 def _add_lld_linker_if_needed(platform_name: str, args: list[str]) -> list[str]:
     """
@@ -366,9 +318,10 @@ def _add_lld_linker_if_needed(platform_name: str, args: list[str]) -> list[str]:
     - Faster linking performance
     - Uniform toolchain across all platforms
 
-    Platform-specific linker flags:
-    - macOS: Uses -fuse-ld=ld64.lld (explicit Mach-O variant required by LLVM 21.x+)
-    - Linux: Uses -fuse-ld=lld (standard ELF linker)
+    Platform-specific behavior:
+    - Uses -fuse-ld=lld on all platforms (clang driver auto-dispatches)
+    - macOS: Clang driver finds ld64.lld (Mach-O linker)
+    - Linux: Clang driver finds ld.lld (ELF linker)
 
     The function is skipped when:
     - User sets CLANG_TOOL_CHAIN_USE_SYSTEM_LD=1
@@ -384,14 +337,25 @@ def _add_lld_linker_if_needed(platform_name: str, args: list[str]) -> list[str]:
         args: Original compiler arguments
 
     Returns:
-        Modified arguments with platform-specific -fuse-ld flag prepended if needed
+        Modified arguments with -fuse-ld=lld flag prepended if needed
     """
     # On macOS, if user explicitly specified LLD, we still need to translate flags
     # and ensure ld64.lld symlink exists, even though we don't inject the -fuse-ld flag ourselves
     if platform_name == "darwin" and _user_specified_lld_on_macos(args):
         logger.debug("User specified LLD on macOS, translating GNU ld flags to ld64.lld equivalents")
-        # Ensure ld64.lld symlink exists for user-specified -fuse-ld=ld64.lld
+        # Ensure ld64.lld symlink exists for lld to dispatch to Mach-O mode
         _ensure_ld64_lld_symlink()
+
+        # Check if user specified -fuse-ld=ld64.lld (which is not a valid clang driver option)
+        # and emit a warning about the auto-conversion to -fuse-ld=lld
+        if _user_specified_ld64_lld(args):
+            print(
+                "[clang-tool-chain] Warning: -fuse-ld=ld64.lld is not a valid clang driver option. "
+                "Auto-converting to -fuse-ld=lld (clang driver auto-dispatches to ld64.lld on Darwin).",
+                file=sys.stderr,
+            )
+            args = _convert_ld64_lld_to_lld(args)
+
         return _translate_linker_flags_for_macos_lld(args)
 
     if not _should_force_lld(platform_name, args):
@@ -402,22 +366,13 @@ def _add_lld_linker_if_needed(platform_name: str, args: list[str]) -> list[str]:
     # On macOS, translate GNU ld flags to ld64.lld equivalents
     if platform_name == "darwin":
         args = _translate_linker_flags_for_macos_lld(args)
+        # Ensure ld64.lld symlink exists for lld to dispatch to Mach-O mode
+        _ensure_ld64_lld_symlink()
 
-        # Check LLVM version to determine the correct linker flag
-        if _llvm_supports_ld64_lld_flag():
-            # LLVM 21.x+ supports explicit -fuse-ld=ld64.lld
-            _ensure_ld64_lld_symlink()
-            return ["-fuse-ld=ld64.lld"] + args
-        else:
-            # LLVM < 21.x: rewrite to -fuse-ld=lld with compatibility notice
-            version = _get_llvm_version()
-            version_str = f"{version[0]}.{version[1]}.{version[2]}" if version else "unknown"
-            print(
-                f"[clang-tool-chain] LLVM {version_str} does not support -fuse-ld=ld64.lld, "
-                f"using -fuse-ld=lld instead (lld auto-detects Mach-O from target)",
-                file=sys.stderr,
-            )
-            return ["-fuse-ld=lld"] + args
-    else:
-        # Linux uses standard lld
-        return ["-fuse-ld=lld"] + args
+    # Always use -fuse-ld=lld on all platforms.
+    # Note: -fuse-ld=ld64.lld is NOT a valid clang driver option.
+    # The clang driver only recognizes generic names like "lld", "gold", "bfd".
+    # When -fuse-ld=lld is used, clang automatically dispatches to:
+    # - Darwin: ld64.lld (Mach-O linker)
+    # - Linux: ld.lld (ELF linker)
+    return ["-fuse-ld=lld"] + args

clang_tool_chain/llvm_versions.py

@@ -0,0 +1,101 @@
+"""
+Centralized LLVM version configuration for clang-tool-chain.
+
+This module provides a single source of truth for LLVM versions used by the toolchain.
+When updating LLVM versions, only this file needs to be modified.
+
+Version history:
+- 21.1.6: macOS (darwin) x86_64 and arm64
+- 21.1.5: Windows x86_64, Linux x86_64 and arm64
+"""
+
+from typing import NamedTuple
+
+
+class LLVMVersion(NamedTuple):
+    """LLVM version as a tuple of (major, minor, patch)."""
+
+    major: int
+    minor: int
+    patch: int
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+    @classmethod
+    def from_string(cls, version_str: str) -> "LLVMVersion":
+        """Parse a version string like '21.1.6' into an LLVMVersion."""
+        parts = version_str.split(".")
+        if len(parts) != 3:
+            raise ValueError(f"Invalid version string: {version_str}")
+        return cls(int(parts[0]), int(parts[1]), int(parts[2]))
+
+
+# Centralized LLVM version configuration by platform
+# Format: {platform_name: LLVMVersion}
+# Platform names match detection.py: "darwin", "linux", "win"
+LLVM_VERSIONS: dict[str, LLVMVersion] = {
+    "darwin": LLVMVersion(21, 1, 6),  # macOS x86_64 and arm64
+    "linux": LLVMVersion(21, 1, 5),  # Linux x86_64 and arm64
+    "win": LLVMVersion(21, 1, 5),  # Windows x86_64
+}
+
+# Default version when platform is unknown (should not happen in practice)
+DEFAULT_LLVM_VERSION = LLVMVersion(21, 1, 5)
+
+
+def get_llvm_version(platform_name: str) -> LLVMVersion:
+    """
+    Get the LLVM version for a specific platform.
+
+    Args:
+        platform_name: Platform name ("darwin", "linux", "win")
+
+    Returns:
+        LLVMVersion tuple for the platform
+    """
+    return LLVM_VERSIONS.get(platform_name, DEFAULT_LLVM_VERSION)
+
+
+def get_llvm_version_string(platform_name: str) -> str:
+    """
+    Get the LLVM version string for a specific platform.
+
+    Args:
+        platform_name: Platform name ("darwin", "linux", "win")
+
+    Returns:
+        Version string like "21.1.6"
+    """
+    return str(get_llvm_version(platform_name))
+
+
+def get_llvm_version_tuple(platform_name: str) -> tuple[int, int, int]:
+    """
+    Get the LLVM version as a tuple for a specific platform.
+
+    Args:
+        platform_name: Platform name ("darwin", "linux", "win")
+
+    Returns:
+        Version tuple like (21, 1, 6)
+    """
+    version = get_llvm_version(platform_name)
+    return (version.major, version.minor, version.patch)
+
+
+def supports_ld64_lld_flag(platform_name: str) -> bool:
+    """
+    Check if the platform's LLVM version supports -fuse-ld=ld64.lld.
+
+    The -fuse-ld=ld64.lld flag is only recognized by LLVM 21.x and later.
+    Earlier versions require -fuse-ld=lld (which auto-detects Mach-O from target).
+
+    Args:
+        platform_name: Platform name ("darwin", "linux", "win")
+
+    Returns:
+        True if LLVM >= 21.x, False otherwise
+    """
+    version = get_llvm_version(platform_name)
+    return version.major >= 21

{clang_tool_chain-1.0.42.dist-info → clang_tool_chain-1.0.44.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clang-tool-chain
-Version: 1.0.42
+Version: 1.0.44
 Summary: Clang Tool Chain - C/C++ compilation toolchain utilities
 Project-URL: Homepage, https://github.com/zackees/clang-tool-chain
 Project-URL: Repository, https://github.com/zackees/clang-tool-chain
@@ -240,6 +240,7 @@ Comprehensive reference of all available commands organized by category.
 - [Inlined Build Directives](#-inlined-build-directives)
 - [Executable C++ Scripts](#-executable-c-scripts-shebang-support)
 - [Windows DLL Deployment](#-windows-dll-deployment)
+- [Address Sanitizer (ASAN)](#️-address-sanitizer-asan-support)
 - [sccache Integration](#-sccache-integration)
 
 ### Platform & Configuration
@@ -794,6 +795,7 @@ jobs:
 - `CLANG_TOOL_CHAIN_LIB_DEPLOY_VERBOSE` - Enable verbose library deployment logging
 - `CLANG_TOOL_CHAIN_USE_SYSTEM_LD` - Use system linker instead of LLD
 - `CLANG_TOOL_CHAIN_NO_DIRECTIVES` - Disable inlined build directives
+- `CLANG_TOOL_CHAIN_NO_SANITIZER_ENV` - Disable automatic ASAN/LSAN options injection at runtime
 - `SDKROOT` - Custom macOS SDK path (auto-detected by default)
 
 **📖 [Complete Documentation](docs/CONFIGURATION.md)** - All environment variables, macOS SDK, Windows DLL settings, sccache backends.
@@ -838,6 +840,56 @@ Automatic MinGW runtime DLL deployment for Windows executables (GNU ABI). Progra
 
 ---
 
+## 🛡️ Address Sanitizer (ASAN) Support
+
+Full ASAN support with automatic runtime configuration for better stack traces.
+
+### Compilation
+
+```bash
+# Compile with ASAN
+clang-tool-chain-cpp -fsanitize=address test.cpp -o test
+
+# With automatic library deployment (recommended)
+clang-tool-chain-cpp -fsanitize=address test.cpp -o test --deploy-dependencies
+
+# Run - ASAN errors will be detected
+./test
+```
+
+### Runtime Environment (Automatic)
+
+When running executables via `clang-tool-chain-build-run`, optimal sanitizer options are **automatically injected** to improve stack trace quality - but **only when the corresponding sanitizer was used during compilation**:
+
+- `ASAN_OPTIONS=fast_unwind_on_malloc=0:symbolize=1:detect_leaks=1` (when `-fsanitize=address` is used)
+- `LSAN_OPTIONS=fast_unwind_on_malloc=0:symbolize=1` (when `-fsanitize=address` or `-fsanitize=leak` is used)
+
+**What these options fix:**
+- `<unknown module>` entries in stack traces from `dlopen()`'d shared libraries
+- Missing function names in crash reports
+- Incomplete leak detection
+
+**Your options are always preserved** - if you set `ASAN_OPTIONS` or `LSAN_OPTIONS` yourself, clang-tool-chain won't override them.
+
+**Regular builds are unaffected** - sanitizer options are only injected when the compiler flags indicate sanitizers are being used.
+
+### Configuration
+
+```bash
+# Disable automatic sanitizer environment injection
+export CLANG_TOOL_CHAIN_NO_SANITIZER_ENV=1
+
+# Disable automatic -shared-libasan on Linux (use static ASAN)
+export CLANG_TOOL_CHAIN_NO_SHARED_ASAN=1
+```
+
+**Platform Notes:**
+- **Linux**: Automatically uses `-shared-libasan` for proper runtime linking
+- **Windows**: Works with both GNU and MSVC ABIs
+- **macOS**: Uses bundled LLVM ASAN runtime
+
+---
+
 ## 🔧 How It Works
 
 Auto-downloads on first use (~71-91 MB, 10-60 seconds). Subsequent uses are instant.

{clang_tool_chain-1.0.42.dist-info → clang_tool_chain-1.0.44.dist-info}/RECORD

@@ -1,5 +1,5 @@
 clang_tool_chain/__init__.py,sha256=w3f1hdA72SH-WsfwesNTQbTeiXIlhV8ignySXrV3SfU,23
-clang_tool_chain/__version__.py,sha256=_irBDZ3WPOleeFZ3Cc2qgO4-6MZvkq-a-BKfGhurz7Q,72
+clang_tool_chain/__version__.py,sha256=VyBCcvXR6mMibUFhauoR0iyFq2jth9ReImF-qE_frUY,72
 clang_tool_chain/archive.py,sha256=t3reh7cm5XP2rhTqfRIDAQZv5XQq7SsstyiROYg8wFA,27697
 clang_tool_chain/archive_cache.py,sha256=5ZmlwXIJZDcrDFkTbdgBQYN9sulGn0WyI6qwWqC4HEU,6806
 clang_tool_chain/checksums.py,sha256=KFXeAeDz5ZlcZVOxsHDpNDCrm9UDoJ8bMA4PeNhuzdA,9868
@@ -12,6 +12,7 @@ clang_tool_chain/env_breadcrumbs.py,sha256=bvPTz8xABILhzrXTEBzdGrSbpEXLf2YVgcYEe
 clang_tool_chain/fetch.py,sha256=DwsNl5DZkNqEYXL-FbCTnp6IA2iCAa9pMl5oPjyuOS4,4696
 clang_tool_chain/installer.py,sha256=GuGeUvVcAw4HMj9jrub-I11ixmksw-vgtSOFrlupmPA,3323
 clang_tool_chain/interrupt_utils.py,sha256=7YvazvGzyItRVDZ_pzUSK6at8PCw-Dgih69HLSz0tT4,1153
+clang_tool_chain/llvm_versions.py,sha256=lJuMmrRwOpXJxkrNL6HPbZOCemhZA88t0O0SET3VASo,2963
 clang_tool_chain/logging_config.py,sha256=HS0AMgIiyx2fwdl24mZ1oJDCW_MD5VeLxkTwT3d3v9o,2059
 clang_tool_chain/manifest.py,sha256=kYtUDQLY8RHpKeKRoIlzzA52bDnTG0Thx1rp19LvdNg,22138
 clang_tool_chain/parallel_download.py,sha256=nIyiTzSO8c3NA787TQztHRKko2GtQrZbiNbQiepjbDk,19144
@@ -35,10 +36,10 @@ clang_tool_chain/deployment/factory.py,sha256=Mq6cMMUctoYBZ81I16_hXUmDLQGSAngCmB
 clang_tool_chain/deployment/so_deployer.py,sha256=9mRKcJUXKV-8vXWJGdsUkB5cTPWjmToFUcHTVTCHdVk,11527
 clang_tool_chain/directives/__init__.py,sha256=MJDNYL_MD2MF0HFsrTsSTX645bYo6vtjq2pOTtfykaU,198
 clang_tool_chain/directives/parser.py,sha256=6J7mO1JtvuHkkKS0Xges5b_jT9b3uTF6ULI0ZiwGAdw,11179
-clang_tool_chain/execution/__init__.py,sha256=EeKG_0DGtDr1uqMq2rX_z9bpjHpLD9kgH-PY1_IeCJA,625
-clang_tool_chain/execution/arg_transformers.py,sha256=YkGqz_vbfNE-yFXHnzZREbS1T545AfQcV0DJTkU59YM,18254
+clang_tool_chain/execution/__init__.py,sha256=wSYnlGmfTlaUPEKwW6PgwlxKTti6Wa5yyVjXVipdpcY,875
+clang_tool_chain/execution/arg_transformers.py,sha256=vN-1T1mfD61Mg-P2B6hOQeLdD1RZA3l1pmNBbJSzo-g,19750
 clang_tool_chain/execution/build.py,sha256=PCtHw31WXbjCp2K_qaf1liaCiIjD49036cknqdQyhJM,13040
-clang_tool_chain/execution/build_pipeline.py,sha256=u13iMjsJj6lcguTGNWdJWgPi9QQv1Z_2VrR_l-sF3tg,17283
+clang_tool_chain/execution/build_pipeline.py,sha256=piqh7P2-GR0mVOik3OUGRFqWFIRr8LQM3PU7TcBsujk,17622
 clang_tool_chain/execution/core.py,sha256=7CJ0azznC5lq5bw8amk2kwCIN2I_OnDiKytpapkvrdY,25273
 clang_tool_chain/execution/cosmocc.py,sha256=oGlaPK6Jpz3FaohEkWpRz8sRNu2sT-HYCoIf9xBxJHk,13319
 clang_tool_chain/execution/emscripten.py,sha256=lgxPQpeB1_wWxNILgeyyrW5lEn117dHS9dQ3ikHRn1w,44235
@@ -46,6 +47,7 @@ clang_tool_chain/execution/iwyu.py,sha256=bmP0d_PZObA1JfmFYp3qIOKCb7y32AWPm2_ReF
 clang_tool_chain/execution/lldb.py,sha256=VpxkWTPS6PsyskaKTALeziR5Z5NLwarW174Fm1SMX9k,20718
 clang_tool_chain/execution/nodejs_resolver.py,sha256=8QsJWvIfmt5mBDV7n0ypSjsPyXS-eZTizhBli937I-g,11172
 clang_tool_chain/execution/platform_executor.py,sha256=sF4GyW0ujy2EewG8y2Eo1gUWGzss5G5iIkv02w7-2_o,14362
+clang_tool_chain/execution/sanitizer_env.py,sha256=lrGX17BriqYPsHCCrQnwjw0ttnp9mezsq0eYAOLfBag,4853
 clang_tool_chain/installers/__init__.py,sha256=NAV5woPCEDKSbFr1UmfQsrg4Ua5UdghN4q7H3ymvRsg,279
 clang_tool_chain/installers/base.py,sha256=OS78bau9zoYPitmhla7pKsfCPEj-zLY0DkvVzjE31Tw,15437
 clang_tool_chain/installers/clang.py,sha256=rUtheVRF7mq_1YdmQ3XzIybrJqsHbm2Xf0cbhRbH7RQ,16994
@@ -55,7 +57,7 @@ clang_tool_chain/installers/iwyu.py,sha256=9aAhdGtOTY6BrLuPtladY8Y2mz1i7FjgbMxZf
 clang_tool_chain/installers/lldb.py,sha256=FpG8NMNQk8PoNfg6aeU_plmSQrVET7zo-pTvoK8z838,2261
 clang_tool_chain/installers/nodejs.py,sha256=5N07rotgmCfUaDm1uJfBlIAFKC1iTpgZT0HBRuoYwKI,9343
 clang_tool_chain/linker/__init__.py,sha256=ghzDFpZ2-gPmdDO6K05C7yNbY6pZLANPuUks9TaQwVY,537
-clang_tool_chain/linker/lld.py,sha256=u7UR1GtJbl5SCmuXVxFzBZy2DdtiDGmdJ-KZbwpzgrc,15611
+clang_tool_chain/linker/lld.py,sha256=08qkvoK4-8yACm34GfZzp3vM8rZYHCv_M9fjUeSetd0,13826
 clang_tool_chain/platform/__init__.py,sha256=WkV9Y25ua0mtzEGcsIxF-qExtroSTAMKkcElWuQF2BE,342
 clang_tool_chain/platform/detection.py,sha256=PLHyUfmQ5xuohhpz0KSXJWK3d0u0fCsjx1DbM8f1CxQ,5470
 clang_tool_chain/platform/paths.py,sha256=K0IjeVwbmgPlAWQO8mS3r1WS4C2dN6IYrSqPpckeT5c,6088
@@ -65,8 +67,8 @@ clang_tool_chain/sdk/windows.py,sha256=8zMLAoFz2OKMz-w6Kqxr3A-6Cofto2VWZvCvRi7kn
 clang_tool_chain/testing/__init__.py,sha256=-sYqOOCuTV_u-MkmExrD4uKdTHG4RmMwR3D1kIG281Q,208
 clang_tool_chain/testing/diagnostic_runner.py,sha256=mnmFUEOQulY3-Ggu6hKVGZwjrKQNmV6kY80PRTUu2qU,5293
 clang_tool_chain/testing/diagnostic_tests.py,sha256=GmtKWrDcddZTpx9_yIKfhRAy6YOde8dj7SksCWVEME4,6019
-clang_tool_chain-1.0.42.dist-info/METADATA,sha256=YhVwCSP3VcNbA5LQ-On1o1exq0o5I9vtUqUJzkoBasY,48504
-clang_tool_chain-1.0.42.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-clang_tool_chain-1.0.42.dist-info/entry_points.txt,sha256=DBfnqZJzHFoO6rldGY3ESaX-z2ydAvIueUPM9ss9M-w,2728
-clang_tool_chain-1.0.42.dist-info/licenses/LICENSE,sha256=51FO1oc2pZbQNI0v0_THnznnZIF4iFgawG1xnQ58kKo,10997
-clang_tool_chain-1.0.42.dist-info/RECORD,,
+clang_tool_chain-1.0.44.dist-info/METADATA,sha256=SjvdkUZlqBEHGRSpfaWoAys6sGSSOkH3_b9BdvKFOd0,50425
+clang_tool_chain-1.0.44.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clang_tool_chain-1.0.44.dist-info/entry_points.txt,sha256=DBfnqZJzHFoO6rldGY3ESaX-z2ydAvIueUPM9ss9M-w,2728
+clang_tool_chain-1.0.44.dist-info/licenses/LICENSE,sha256=51FO1oc2pZbQNI0v0_THnznnZIF4iFgawG1xnQ58kKo,10997
+clang_tool_chain-1.0.44.dist-info/RECORD,,