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

clang_tool_chain/execution/arg_transformers.py

@@ -14,9 +14,12 @@ The Chain of Responsibility pattern allows:
 
 Architecture:
     ArgumentTransformer (ABC)
-        ├── MacOSSDKTransformer (priority=100)
         ├── DirectivesTransformer (priority=50)
+        ├── MacOSSDKTransformer (priority=100)
+        ├── LinuxUnwindTransformer (priority=150)
         ├── LLDLinkerTransformer (priority=200)
+        ├── ASANRuntimeTransformer (priority=250)
+        ├── RPathTransformer (priority=275)
         ├── GNUABITransformer (priority=300)
         └── MSVCABITransformer (priority=300)
 
@@ -35,6 +38,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from clang_tool_chain.env_utils import is_feature_disabled
+
 if TYPE_CHECKING:
     from clang_tool_chain.directives.parser import ParsedDirectives
 
@@ -111,6 +116,7 @@ class DirectivesTransformer(ArgumentTransformer):
 
     Environment Variables:
         CLANG_TOOL_CHAIN_NO_DIRECTIVES: Set to '1' to disable directive parsing
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
         CLANG_TOOL_CHAIN_DIRECTIVE_VERBOSE: Set to '1' to enable debug logging
     """
 
@@ -119,9 +125,8 @@ class DirectivesTransformer(ArgumentTransformer):
 
     def transform(self, args: list[str], context: ToolContext) -> list[str]:
         """Add arguments from inlined build directives in source files."""
-        # Check if directives are disabled
-        if os.environ.get("CLANG_TOOL_CHAIN_NO_DIRECTIVES") == "1":
-            logger.debug("Directives disabled via CLANG_TOOL_CHAIN_NO_DIRECTIVES=1")
+        # Check if directives are disabled (via NO_DIRECTIVES or NO_AUTO)
+        if is_feature_disabled("DIRECTIVES"):
             return args
 
         # Only apply to clang/clang++ compilation commands
@@ -203,6 +208,86 @@ class MacOSSDKTransformer(ArgumentTransformer):
         return _add_macos_sysroot_if_needed(args)
 
 
+class LinuxUnwindTransformer(ArgumentTransformer):
+    """
+    Transformer for adding bundled libunwind include/library paths on Linux.
+
+    Priority: 150 (runs after SDK but before linker)
+
+    This transformer adds include and library paths for the bundled libunwind
+    headers and libraries on Linux. This allows compilation of code that uses
+    libunwind without requiring system libunwind-dev to be installed.
+
+    When libunwind.h exists in the clang toolchain's include directory:
+    - Adds -I<clang_root>/include for header discovery
+    - Adds -L<clang_root>/lib for library discovery
+    - Adds -Wl,-rpath,<clang_root>/lib for runtime library discovery
+
+    Environment Variables:
+        CLANG_TOOL_CHAIN_NO_BUNDLED_UNWIND: Set to '1' to disable bundled libunwind
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
+    """
+
+    def priority(self) -> int:
+        return 150
+
+    def transform(self, args: list[str], context: ToolContext) -> list[str]:
+        """Add bundled libunwind paths if available on Linux."""
+        # Only applies to Linux clang/clang++
+        if context.platform_name != "linux" or context.tool_name not in ("clang", "clang++"):
+            return args
+
+        # Check if disabled (via NO_BUNDLED_UNWIND or NO_AUTO)
+        if is_feature_disabled("BUNDLED_UNWIND"):
+            return args
+
+        # Check if compile-only (no linking)
+        is_compile_only = "-c" in args
+
+        try:
+            from clang_tool_chain.platform.detection import get_platform_binary_dir
+
+            clang_bin = get_platform_binary_dir()
+            clang_root = clang_bin.parent
+
+            # Check if bundled libunwind.h exists
+            libunwind_header = clang_root / "include" / "libunwind.h"
+            if not libunwind_header.exists():
+                logger.debug("Bundled libunwind.h not found, skipping LinuxUnwindTransformer")
+                return args
+
+            result = list(args)
+            include_dir = clang_root / "include"
+            lib_dir = clang_root / "lib"
+
+            # Add include path (always needed for compilation)
+            include_flag = f"-I{include_dir}"
+            if include_flag not in args:
+                result = [include_flag] + result
+                logger.debug(f"Adding bundled libunwind include path: {include_flag}")
+
+            # Add library path and rpath (only for linking)
+            if not is_compile_only:
+                lib_flag = f"-L{lib_dir}"
+                if lib_flag not in args:
+                    result = [lib_flag] + result
+                    logger.debug(f"Adding bundled libunwind library path: {lib_flag}")
+
+                # Add rpath so runtime can find libunwind.so
+                rpath_flag = f"-Wl,-rpath,{lib_dir}"
+                # Check if any rpath to our lib dir already exists
+                has_our_rpath = any(str(lib_dir) in arg and "-rpath" in arg for arg in args)
+                if not has_our_rpath:
+                    result = [rpath_flag] + result
+                    logger.debug(f"Adding bundled libunwind rpath: {rpath_flag}")
+
+            return result
+
+        except Exception as e:
+            logger.debug(f"LinuxUnwindTransformer error: {e}")
+            return args
+
+
 class LLDLinkerTransformer(ArgumentTransformer):
     """
     Transformer for forcing LLVM's lld linker on macOS and Linux.
@@ -291,32 +376,38 @@ class ASANRuntimeTransformer(ArgumentTransformer):
 
     Priority: 250 (runs after linker but before ABI)
 
-    This transformer ensures proper ASAN runtime linking on Linux:
+    This transformer ensures proper ASAN runtime linking on Linux and Windows:
     - Detects -fsanitize=address flag
     - Adds -shared-libasan to use shared runtime library
-    - Adds -Wl,--allow-shlib-undefined when building shared libraries with ASAN
+    - Adds -Wl,--allow-shlib-undefined when building shared libraries with ASAN (Linux only)
     - 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.
+    The shared runtime library (libclang_rt.asan.so on Linux, libclang_rt.asan_dynamic.dll
+    on Windows) 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.
 
+    Note: macOS uses a different ASAN runtime mechanism and is not affected.
+
     Environment Variables:
         CLANG_TOOL_CHAIN_NO_SHARED_ASAN: Set to '1' to disable shared ASAN
+        CLANG_TOOL_CHAIN_NO_SANITIZER_NOTE: Set to '1' to suppress the injection note
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
     """
 
     def priority(self) -> int:
         return 250
 
     def transform(self, args: list[str], context: ToolContext) -> list[str]:
-        """Add -shared-libasan and --allow-shlib-undefined when using ASAN on Linux."""
+        """Add -shared-libasan and --allow-shlib-undefined when using ASAN on Linux/Windows."""
         import sys
 
-        # Only applies to Linux clang/clang++
-        if context.platform_name != "linux" or context.tool_name not in ("clang", "clang++"):
+        # Only applies to Linux and Windows (GNU ABI) clang/clang++
+        # macOS uses a different ASAN runtime mechanism
+        if context.platform_name not in ("linux", "win") or context.tool_name not in ("clang", "clang++"):
             return args
 
         # Check if ASAN is enabled
@@ -327,23 +418,21 @@ class ASANRuntimeTransformer(ArgumentTransformer):
         result = list(args)
         injected_flags = []
 
-        # Check if user disabled shared ASAN
-        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")
-
-        # Check if building a shared library with ASAN
+        # Check if user disabled shared ASAN (via NO_SHARED_ASAN or NO_AUTO)
+        # Also check if -shared-libasan already present
+        if not is_feature_disabled("SHARED_ASAN") and "-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")
+
+        # Check if building a shared library with ASAN on Linux
         # Shared libraries need to allow undefined symbols that will be provided
         # by the sanitizer runtime when the runner loads them
+        # Note: --allow-shlib-undefined is a Linux ELF linker flag, not supported on Windows
         is_shared_lib = "-shared" in args
-        if is_shared_lib:
+        if is_shared_lib and context.platform_name == "linux":
             # 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:
@@ -351,10 +440,11 @@ class ASANRuntimeTransformer(ArgumentTransformer):
                 result = ["-Wl,--allow-shlib-undefined"] + result
                 injected_flags.append("-Wl,--allow-shlib-undefined")
 
-        # Warn on stderr if we injected flags
-        if injected_flags:
+        # Warn on stderr if we injected flags (unless disabled)
+        if injected_flags and not is_feature_disabled("SANITIZER_NOTE"):
             print(
-                f"clang-tool-chain: note: automatically injected sanitizer flags: {' '.join(injected_flags)}",
+                f"clang-tool-chain: note: automatically injected sanitizer flags: {' '.join(injected_flags)} "
+                "(disable with CLANG_TOOL_CHAIN_NO_SANITIZER_NOTE=1)",
                 file=sys.stderr,
             )
 
@@ -378,6 +468,7 @@ class RPathTransformer(ArgumentTransformer):
 
     Environment Variables:
         CLANG_TOOL_CHAIN_NO_RPATH: Set to '1' to disable automatic rpath injection
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
     """
 
     def priority(self) -> int:
@@ -401,9 +492,8 @@ class RPathTransformer(ArgumentTransformer):
         if not has_deploy_flag and not deploy_from_env:
             return args
 
-        # Check if user disabled rpath
-        if os.environ.get("CLANG_TOOL_CHAIN_NO_RPATH") == "1":
-            logger.debug("Rpath injection disabled via CLANG_TOOL_CHAIN_NO_RPATH=1")
+        # Check if user disabled rpath (via NO_RPATH or NO_AUTO)
+        if is_feature_disabled("RPATH"):
             return args
 
         # Check if rpath already present
@@ -528,11 +618,12 @@ def create_default_pipeline() -> ArgumentPipeline:
     This includes all standard transformers in their default priority order:
     1. DirectivesTransformer (priority=50)
     2. MacOSSDKTransformer (priority=100)
-    3. LLDLinkerTransformer (priority=200)
-    4. ASANRuntimeTransformer (priority=250)
-    5. RPathTransformer (priority=275)
-    6. GNUABITransformer (priority=300)
-    7. MSVCABITransformer (priority=300)
+    3. LinuxUnwindTransformer (priority=150)
+    4. LLDLinkerTransformer (priority=200)
+    5. ASANRuntimeTransformer (priority=250)
+    6. RPathTransformer (priority=275)
+    7. GNUABITransformer (priority=300)
+    8. MSVCABITransformer (priority=300)
 
     Returns:
         Configured ArgumentPipeline ready for use
@@ -541,6 +632,7 @@ def create_default_pipeline() -> ArgumentPipeline:
         [
             DirectivesTransformer(),
             MacOSSDKTransformer(),
+            LinuxUnwindTransformer(),
             LLDLinkerTransformer(),
             ASANRuntimeTransformer(),
             RPathTransformer(),

clang_tool_chain/execution/build.py

@@ -26,6 +26,7 @@ from typing import NoReturn
 
 from clang_tool_chain.cli_parsers import parse_build_args, parse_build_run_args
 from clang_tool_chain.directives import DirectiveParser
+from clang_tool_chain.env_utils import is_feature_disabled
 from clang_tool_chain.execution.core import execute_tool
 from clang_tool_chain.interrupt_utils import handle_keyboard_interrupt_properly
 from clang_tool_chain.platform import get_platform_info
@@ -47,9 +48,13 @@ def _get_directive_args(source_path: Path) -> list[str]:
 
     Returns:
         List of compiler/linker arguments derived from directives
+
+    Environment Variables:
+        CLANG_TOOL_CHAIN_NO_DIRECTIVES: Set to '1' to disable directive parsing
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
     """
-    # Check if directives parsing is disabled via environment variable
-    if os.environ.get("CLANG_TOOL_CHAIN_NO_DIRECTIVES", "").lower() in ("1", "true", "yes"):
+    # Check if directives parsing is disabled (via NO_DIRECTIVES or NO_AUTO)
+    if is_feature_disabled("DIRECTIVES"):
         return []
 
     try:
@@ -106,10 +111,11 @@ def get_directive_args_from_compiler_args(args: list[str]) -> list[str]:
 
     Environment Variables:
         CLANG_TOOL_CHAIN_NO_DIRECTIVES: Set to '1' to disable directive parsing
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
         CLANG_TOOL_CHAIN_DIRECTIVE_VERBOSE: Set to '1' to show parsed directives
     """
-    # Check if directives parsing is disabled via environment variable
-    if os.environ.get("CLANG_TOOL_CHAIN_NO_DIRECTIVES", "").lower() in ("1", "true", "yes"):
+    # Check if directives parsing is disabled (via NO_DIRECTIVES or NO_AUTO)
+    if is_feature_disabled("DIRECTIVES"):
         return []
 
     directive_args: list[str] = []

clang_tool_chain/execution/build_pipeline.py

@@ -24,6 +24,7 @@ from pathlib import Path
 from typing import NoReturn
 
 from clang_tool_chain.directives import DirectiveParser
+from clang_tool_chain.env_utils import is_feature_disabled
 from clang_tool_chain.execution.core import run_tool
 from clang_tool_chain.interrupt_utils import handle_keyboard_interrupt_properly
 
@@ -109,9 +110,13 @@ def _get_directive_args(source_path: Path) -> list[str]:
 
     Returns:
         List of compiler/linker arguments derived from directives
+
+    Environment Variables:
+        CLANG_TOOL_CHAIN_NO_DIRECTIVES: Set to '1' to disable directive parsing
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
     """
-    # Check if directives parsing is disabled via environment variable
-    if os.environ.get("CLANG_TOOL_CHAIN_NO_DIRECTIVES", "").lower() in ("1", "true", "yes"):
+    # Check if directives parsing is disabled (via NO_DIRECTIVES or NO_AUTO)
+    if is_feature_disabled("DIRECTIVES"):
         return []
 
     try:

clang_tool_chain/execution/sanitizer_env.py

@@ -1,16 +1,23 @@
 """
 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.
+This module provides automatic injection of ASAN_OPTIONS, LSAN_OPTIONS, and
+ASAN_SYMBOLIZER_PATH 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.
+
+The symbolizer path is automatically detected from the clang-tool-chain
+installation, enabling proper address-to-symbol resolution without manual
+configuration.
 """
 
 import logging
 import os
+import shutil
+
+from clang_tool_chain.env_utils import is_feature_disabled
 
 logger = logging.getLogger(__name__)
 
@@ -22,6 +29,46 @@ DEFAULT_ASAN_OPTIONS = "fast_unwind_on_malloc=0:symbolize=1:detect_leaks=1"
 DEFAULT_LSAN_OPTIONS = "fast_unwind_on_malloc=0:symbolize=1"
 
 
+def get_symbolizer_path() -> str | None:
+    """
+    Get the path to llvm-symbolizer from the clang-tool-chain installation.
+
+    This function finds the llvm-symbolizer binary bundled with clang-tool-chain,
+    which is required by ASAN/LSAN to convert memory addresses into function names
+    and source locations in stack traces.
+
+    Returns:
+        Absolute path to llvm-symbolizer, or None if not found.
+
+    Example:
+        >>> path = get_symbolizer_path()
+        >>> if path:
+        ...     os.environ["ASAN_SYMBOLIZER_PATH"] = path
+
+    Note:
+        Falls back to system PATH if the clang-tool-chain binary is not available.
+        This allows the function to work even when clang-tool-chain is not fully
+        installed (e.g., during development or in CI environments).
+    """
+    # Try to find llvm-symbolizer from clang-tool-chain installation
+    try:
+        from clang_tool_chain.platform.paths import find_tool_binary
+
+        symbolizer = find_tool_binary("llvm-symbolizer")
+        return str(symbolizer)
+    except (ImportError, RuntimeError) as e:
+        logger.debug(f"Could not find llvm-symbolizer in clang-tool-chain: {e}")
+
+    # Fall back to system PATH
+    system_symbolizer = shutil.which("llvm-symbolizer")
+    if system_symbolizer:
+        logger.debug(f"Using system llvm-symbolizer: {system_symbolizer}")
+        return system_symbolizer
+
+    logger.debug("llvm-symbolizer not found in clang-tool-chain or system PATH")
+    return None
+
+
 def detect_sanitizers_from_flags(compiler_flags: list[str]) -> tuple[bool, bool]:
     """
     Detect which sanitizers are enabled from compiler flags.
@@ -64,12 +111,16 @@ def prepare_sanitizer_environment(
     compiler_flags: list[str] | None = None,
 ) -> dict[str, str]:
     """
-    Prepare environment with optimal sanitizer options.
+    Prepare environment with optimal sanitizer options and symbolizer path.
 
-    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.
+    This function injects ASAN_OPTIONS, LSAN_OPTIONS, and ASAN_SYMBOLIZER_PATH
+    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.
+
+    The ASAN_SYMBOLIZER_PATH is automatically detected from the clang-tool-chain
+    installation, enabling proper address-to-symbol resolution (function names,
+    file paths, line numbers) without manual configuration.
 
     Args:
         base_env: Base environment dictionary to modify. If None, uses os.environ.
@@ -83,20 +134,21 @@ def prepare_sanitizer_environment(
     Environment Variables:
         CLANG_TOOL_CHAIN_NO_SANITIZER_ENV: Set to "1", "true", or "yes" to
             disable automatic injection of sanitizer options.
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to "1" to disable all automatic features.
         ASAN_OPTIONS: If already set, preserved as-is (user config takes priority).
         LSAN_OPTIONS: If already set, preserved as-is (user config takes priority).
+        ASAN_SYMBOLIZER_PATH: 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 now contains ASAN_OPTIONS, LSAN_OPTIONS, and ASAN_SYMBOLIZER_PATH
         >>> 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")
+    # Check if disabled via environment variable (NO_SANITIZER_ENV or NO_AUTO)
+    if is_feature_disabled("SANITIZER_ENV"):
         return env
 
     # If no compiler flags provided, don't inject anything (safe default)
@@ -117,4 +169,17 @@ def prepare_sanitizer_environment(
         env["LSAN_OPTIONS"] = DEFAULT_LSAN_OPTIONS
         logger.info(f"Injecting LSAN_OPTIONS={DEFAULT_LSAN_OPTIONS}")
 
+    # Inject ASAN_SYMBOLIZER_PATH if any sanitizer is enabled and not already set
+    if (asan_enabled or lsan_enabled) and "ASAN_SYMBOLIZER_PATH" not in env:
+        symbolizer_path = get_symbolizer_path()
+        if symbolizer_path:
+            env["ASAN_SYMBOLIZER_PATH"] = symbolizer_path
+            logger.info(f"Injecting ASAN_SYMBOLIZER_PATH={symbolizer_path}")
+        else:
+            logger.warning(
+                "llvm-symbolizer not found - ASAN/LSAN stack traces may show "
+                "raw addresses instead of function names. Install llvm-symbolizer "
+                "or ensure clang-tool-chain is properly installed."
+            )
+
     return env

clang_tool_chain/linker/lld.py

@@ -12,6 +12,7 @@ import logging
 import os
 import sys
 
+from clang_tool_chain.env_utils import is_feature_disabled
 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
 
@@ -187,13 +188,16 @@ def _translate_linker_flags_for_macos_lld(args: list[str]) -> list[str]:
     Translate GNU ld linker flags to ld64.lld equivalents for macOS.
 
     When using lld on macOS (ld64.lld), certain GNU ld flags need to be
-    translated to their Mach-O equivalents:
+    translated to their Mach-O equivalents or removed:
     - --no-undefined -> -undefined error
     - --fatal-warnings -> -fatal_warnings
-    - More translations can be added as needed
+    - --allow-shlib-undefined -> (removed, ld64 allows undefined symbols by default)
 
     This function processes both direct linker flags and flags passed via -Wl,
 
+    A warning is printed to stderr when flags are removed, unless silenced via
+    CLANG_TOOL_CHAIN_NO_LINKER_COMPAT_NOTE=1.
+
     Args:
         args: Original compiler arguments
 
@@ -201,12 +205,19 @@ def _translate_linker_flags_for_macos_lld(args: list[str]) -> list[str]:
         Modified arguments with translated linker flags
     """
     # Map of GNU ld flags to ld64.lld equivalents
-    flag_translations = {
+    # None means the flag should be removed (no equivalent needed)
+    flag_translations: dict[str, str | None] = {
         "--no-undefined": "-undefined error",
         "--fatal-warnings": "-fatal_warnings",
+        # --allow-shlib-undefined: ld64 allows undefined symbols in dylibs by default,
+        # so this flag is a no-op on macOS. We remove it entirely.
+        "--allow-shlib-undefined": None,
         # Add more translations as needed
     }
 
+    # Track removed flags for warning
+    removed_flags: list[str] = []
+
     result = []
     i = 0
     while i < len(args):
@@ -221,14 +232,18 @@ def _translate_linker_flags_for_macos_lld(args: list[str]) -> list[str]:
             for flag in linker_flags:
                 # Check if this flag needs translation
                 if flag in flag_translations:
-                    # Translate the flag (may result in multiple flags)
                     translated = flag_translations[flag]
-                    if " " in translated:
+                    if translated is None:
+                        # Flag should be removed entirely (no equivalent on macOS)
+                        removed_flags.append(flag)
+                        logger.debug(f"Removed linker flag (no macOS equivalent): {flag}")
+                    elif " " in translated:
                         # Multiple flags (e.g., "-undefined error")
                         translated_flags.extend(translated.split())
+                        logger.debug(f"Translated linker flag: {flag} -> {translated}")
                     else:
                         translated_flags.append(translated)
-                    logger.debug(f"Translated linker flag: {flag} -> {translated}")
+                        logger.debug(f"Translated linker flag: {flag} -> {translated}")
                 else:
                     translated_flags.append(flag)
 
@@ -239,19 +254,34 @@ def _translate_linker_flags_for_macos_lld(args: list[str]) -> list[str]:
         # Handle standalone linker flags passed directly
         elif arg in flag_translations:
             translated = flag_translations[arg]
-            logger.debug(f"Translated linker flag: {arg} -> {translated}")
-            # Add via -Wl, to pass to linker
-            if " " in translated:
-                # Multiple flags
-                result.append("-Wl," + ",".join(translated.split()))
+            if translated is None:
+                # Flag should be removed entirely (no equivalent on macOS)
+                removed_flags.append(arg)
+                logger.debug(f"Removed linker flag (no macOS equivalent): {arg}")
             else:
-                result.append("-Wl," + translated)
+                logger.debug(f"Translated linker flag: {arg} -> {translated}")
+                # Add via -Wl, to pass to linker
+                if " " in translated:
+                    # Multiple flags
+                    result.append("-Wl," + ",".join(translated.split()))
+                else:
+                    result.append("-Wl," + translated)
 
         else:
             result.append(arg)
 
         i += 1
 
+    # Emit warning for removed flags (unless silenced)
+    if removed_flags and not is_feature_disabled("LINKER_COMPAT_NOTE"):
+        import sys
+
+        print(
+            f"clang-tool-chain: note: removed GNU linker flags not supported by ld64.lld: "
+            f"{', '.join(removed_flags)} (disable with CLANG_TOOL_CHAIN_NO_LINKER_COMPAT_NOTE=1)",
+            file=sys.stderr,
+        )
+
     return result
 
 

clang_tool_chain/wrapper.py

@@ -151,6 +151,15 @@ from clang_tool_chain.execution.lldb import (
     get_lldb_binary_dir,
 )
 
+# ============================================================================
+# Sanitizer Environment
+# ============================================================================
+from clang_tool_chain.execution.sanitizer_env import (
+    detect_sanitizers_from_flags,
+    get_symbolizer_path,
+    prepare_sanitizer_environment,
+)
+
 # ============================================================================
 # Linker Configuration
 # ============================================================================
@@ -218,6 +227,10 @@ __all__ = [
     "run_tool",
     "sccache_clang_main",
     "sccache_clang_cpp_main",
+    # Sanitizer Environment
+    "prepare_sanitizer_environment",
+    "detect_sanitizers_from_flags",
+    "get_symbolizer_path",
     # Emscripten
     "ensure_nodejs_available",
     "execute_emscripten_tool",