clang-tool-chain 1.1.0__py3-none-any.whl → 1.1.3__py3-none-any.whl

clang_tool_chain/__version__.py

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

clang_tool_chain/cli.py

@@ -201,6 +201,19 @@ def cmd_list_tools(args: argparse.Namespace) -> int:
     for cmd, desc in sccache_tools:
         print(f"  {cmd:30s} - {desc}")
 
+    print()
+    print("Debugging and analysis:")
+    print("=" * 60)
+    print()
+
+    debug_tools = [
+        ("clang-tool-chain-lldb", "LLVM debugger (lldb)"),
+        ("clang-tool-chain-iwyu", "Include What You Use analyzer"),
+    ]
+
+    for cmd, desc in debug_tools:
+        print(f"  {cmd:30s} - {desc}")
+
     print()
     print("For more information, run:")
     print("  clang-tool-chain info")

clang_tool_chain/env_utils.py

@@ -31,6 +31,8 @@ CONTROLLABLE_FEATURES = {
     "SYSROOT": "Automatic macOS SDK detection (-isysroot)",
     "DEPLOY_LIBS": "Cross-platform library deployment (all outputs)",
     "DEPLOY_SHARED_LIB": "Library deployment for shared library outputs only (.dll, .so, .dylib)",
+    "BUNDLED_UNWIND": "Bundled libunwind paths on Linux",
+    "MACOS_UNWIND_FIX": "Automatic -lunwind removal on macOS (libunwind in libSystem)",
 }
 
 

clang_tool_chain/execution/arg_transformers.py

@@ -16,6 +16,7 @@ Architecture:
     ArgumentTransformer (ABC)
         ├── DirectivesTransformer (priority=50)
         ├── MacOSSDKTransformer (priority=100)
+        ├── MacOSUnwindTransformer (priority=125)
         ├── LinuxUnwindTransformer (priority=150)
         ├── LLDLinkerTransformer (priority=200)
         ├── ASANRuntimeTransformer (priority=250)
@@ -208,6 +209,52 @@ class MacOSSDKTransformer(ArgumentTransformer):
         return _add_macos_sysroot_if_needed(args)
 
 
+class MacOSUnwindTransformer(ArgumentTransformer):
+    """
+    Transformer for handling -lunwind on macOS.
+
+    Priority: 125 (runs after SDK but before Linux unwind transformer)
+
+    On macOS, libunwind is not a standalone library - it's embedded in libSystem.B.dylib
+    which is automatically linked by the compiler. The -lunwind flag is unnecessary
+    and causes linking errors with ld64.lld:
+
+        ld64.lld: error: library not found for -lunwind
+
+    This transformer removes -lunwind from the arguments on macOS since the
+    libunwind symbols are already available via libSystem (automatically linked).
+
+    Environment Variables:
+        CLANG_TOOL_CHAIN_NO_MACOS_UNWIND_FIX: Set to '1' to disable this transformer
+        CLANG_TOOL_CHAIN_NO_AUTO: Set to '1' to disable all automatic features
+    """
+
+    def priority(self) -> int:
+        return 125
+
+    def transform(self, args: list[str], context: ToolContext) -> list[str]:
+        """Remove -lunwind on macOS since libunwind is in libSystem."""
+        # Only applies to macOS clang/clang++
+        if context.platform_name != "darwin" or context.tool_name not in ("clang", "clang++"):
+            return args
+
+        # Check if disabled (via NO_MACOS_UNWIND_FIX or NO_AUTO)
+        if is_feature_disabled("MACOS_UNWIND_FIX"):
+            return args
+
+        # Check if -lunwind is present
+        if "-lunwind" not in args:
+            return args
+
+        # Remove -lunwind since macOS provides libunwind via libSystem
+        result = [arg for arg in args if arg != "-lunwind"]
+
+        if len(result) != len(args):
+            logger.info("Removed -lunwind on macOS (libunwind is built into libSystem, no standalone library exists)")
+
+        return result
+
+
 class LinuxUnwindTransformer(ArgumentTransformer):
     """
     Transformer for adding bundled libunwind include/library paths on Linux.
@@ -618,12 +665,13 @@ def create_default_pipeline() -> ArgumentPipeline:
     This includes all standard transformers in their default priority order:
     1. DirectivesTransformer (priority=50)
     2. MacOSSDKTransformer (priority=100)
-    3. LinuxUnwindTransformer (priority=150)
-    4. LLDLinkerTransformer (priority=200)
-    5. ASANRuntimeTransformer (priority=250)
-    6. RPathTransformer (priority=275)
-    7. GNUABITransformer (priority=300)
-    8. MSVCABITransformer (priority=300)
+    3. MacOSUnwindTransformer (priority=125)
+    4. LinuxUnwindTransformer (priority=150)
+    5. LLDLinkerTransformer (priority=200)
+    6. ASANRuntimeTransformer (priority=250)
+    7. RPathTransformer (priority=275)
+    8. GNUABITransformer (priority=300)
+    9. MSVCABITransformer (priority=300)
 
     Returns:
         Configured ArgumentPipeline ready for use
@@ -632,6 +680,7 @@ def create_default_pipeline() -> ArgumentPipeline:
         [
             DirectivesTransformer(),
             MacOSSDKTransformer(),
+            MacOSUnwindTransformer(),
             LinuxUnwindTransformer(),
             LLDLinkerTransformer(),
             ASANRuntimeTransformer(),

clang_tool_chain/execution/sanitizer_env.py

@@ -15,7 +15,9 @@ configuration.
 
 import logging
 import os
+import platform
 import shutil
+from pathlib import Path
 
 from clang_tool_chain.env_utils import is_feature_disabled
 
@@ -106,9 +108,37 @@ def detect_sanitizers_from_flags(compiler_flags: list[str]) -> tuple[bool, bool]
     return asan_enabled, lsan_enabled
 
 
+def _get_builtin_suppression_file() -> Path | None:
+    """
+    Get path to built-in LSan suppression file for current platform.
+
+    Returns:
+        Path to built-in suppression file, or None if not applicable.
+
+    Note:
+        - macOS: Returns path to lsan_suppressions_darwin.txt
+        - Linux: Returns path to lsan_suppressions_linux.txt
+        - Windows: Returns None (LSan not supported on Windows)
+    """
+    system = platform.system()
+
+    # Locate data directory in installed package
+    data_dir = Path(__file__).parent.parent / "data"
+
+    if system == "Darwin":
+        suppression_file = data_dir / "lsan_suppressions_darwin.txt"
+    elif system == "Linux":
+        suppression_file = data_dir / "lsan_suppressions_linux.txt"
+    else:
+        return None  # No suppressions for Windows (no LSan support)
+
+    return suppression_file if suppression_file.exists() else None
+
+
 def prepare_sanitizer_environment(
     base_env: dict[str, str] | None = None,
     compiler_flags: list[str] | None = None,
+    suppression_file: str | Path | None = None,
 ) -> dict[str, str]:
     """
     Prepare environment with optimal sanitizer options and symbolizer path.
@@ -122,11 +152,18 @@ def prepare_sanitizer_environment(
     installation, enabling proper address-to-symbol resolution (function names,
     file paths, line numbers) without manual configuration.
 
+    On macOS and Linux, platform-specific LSan suppression files are automatically
+    applied to filter out false positive leaks from system 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).
+        suppression_file: Optional path to additional custom LSan suppression file.
+            If provided, this file is merged with built-in platform-specific
+            suppressions (built-in applied first, then custom).
+            Set to empty string "" to disable built-in suppressions entirely.
 
     Returns:
         Environment dictionary with sanitizer options injected as appropriate.
@@ -141,9 +178,14 @@ def prepare_sanitizer_environment(
 
     Example:
         >>> env = prepare_sanitizer_environment(compiler_flags=["-fsanitize=address"])
-        >>> # env now contains ASAN_OPTIONS, LSAN_OPTIONS, and ASAN_SYMBOLIZER_PATH
+        >>> # env now contains ASAN_OPTIONS, LSAN_OPTIONS, ASAN_SYMBOLIZER_PATH, and suppressions
         >>> env = prepare_sanitizer_environment(compiler_flags=["-O2"])
         >>> # env unchanged - no sanitizers enabled
+        >>> env = prepare_sanitizer_environment(
+        ...     compiler_flags=["-fsanitize=address"],
+        ...     suppression_file="/path/to/custom.txt"
+        ... )
+        >>> # Uses BOTH built-in AND custom suppression files (merged)
     """
     env = base_env.copy() if base_env is not None else os.environ.copy()
 
@@ -182,4 +224,35 @@ def prepare_sanitizer_environment(
                 "or ensure clang-tool-chain is properly installed."
             )
 
+    # Add platform-specific LSan suppressions if LSAN is enabled
+    if lsan_enabled:
+        # Check if user explicitly disabled built-in suppressions with ""
+        disable_builtin = suppression_file == ""
+
+        # Helper to append suppression file to LSAN_OPTIONS
+        def _append_suppression(file_path: Path) -> None:
+            current_lsan = env.get("LSAN_OPTIONS", "")
+            suppression_opt = f"suppressions={file_path.absolute()}"
+
+            if current_lsan:
+                env["LSAN_OPTIONS"] = f"{current_lsan}:{suppression_opt}"
+            else:
+                env["LSAN_OPTIONS"] = suppression_opt
+
+            logger.info(f"Injecting LSan suppression file: {file_path}")
+
+        # First, apply built-in platform-specific suppressions (unless disabled)
+        if not disable_builtin:
+            builtin_file = _get_builtin_suppression_file()
+            if builtin_file and builtin_file.exists():
+                _append_suppression(builtin_file)
+
+        # Then, also apply custom suppression file if provided (merge behavior)
+        if suppression_file and suppression_file != "":
+            custom_path = Path(suppression_file)
+            if custom_path.exists():
+                _append_suppression(custom_path)
+            else:
+                logger.warning(f"Custom suppression file not found: {suppression_file}")
+
     return env

clang_tool_chain/symbolizer/unwind_windows.c

@@ -0,0 +1,461 @@
+/**
+ * unwind_windows.c - Windows symbol resolution for libunwind
+ *
+ * This file implements symbol resolution for libunwind on Windows using
+ * COFF symbol table parsing for MinGW executables.
+ *
+ * The MinGW libunwind library does not implement unw_get_proc_name(),
+ * returning UNW_ENOINFO (-6549). This implementation provides working
+ * symbol resolution by reading the COFF symbol table embedded in the PE
+ * executable.
+ *
+ * Compile: clang-tool-chain-c unwind_windows.c -c -o unwind_windows.o
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) 2026 clang-tool-chain contributors
+ */
+
+#ifdef _WIN32
+
+#include "unwind_windows.h"
+
+#include <windows.h>
+#include <string.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/* Thread-safe initialization flag */
+static volatile LONG g_initialized = 0;
+static CRITICAL_SECTION g_sym_lock;
+static volatile LONG g_lock_initialized = 0;
+
+/* Symbol table structure */
+typedef struct {
+    DWORD64 address;
+    char name[256];
+} symbol_entry_t;
+
+/* Global symbol table (sorted by address for binary search) */
+static symbol_entry_t *g_symbol_table = NULL;
+static size_t g_symbol_count = 0;
+static DWORD64 g_image_base = 0;
+static DWORD64 g_runtime_base = 0;
+
+/* Initialize the critical section for thread safety */
+static void init_lock(void) {
+    if (InterlockedCompareExchange(&g_lock_initialized, 1, 0) == 0) {
+        InitializeCriticalSection(&g_sym_lock);
+    }
+}
+
+/* COFF symbol table entry (18 bytes) */
+#pragma pack(push, 1)
+typedef struct {
+    union {
+        char ShortName[8];
+        struct {
+            DWORD Zeros;
+            DWORD Offset;
+        } LongName;
+    } Name;
+    DWORD Value;
+    SHORT SectionNumber;
+    WORD Type;
+    BYTE StorageClass;
+    BYTE NumberOfAuxSymbols;
+} COFF_SYMBOL;
+#pragma pack(pop)
+
+/* Comparison function for qsort */
+static int compare_symbols(const void *a, const void *b) {
+    const symbol_entry_t *sa = (const symbol_entry_t *)a;
+    const symbol_entry_t *sb = (const symbol_entry_t *)b;
+    if (sa->address < sb->address) return -1;
+    if (sa->address > sb->address) return 1;
+    return 0;
+}
+
+/* Check if section is executable */
+static BOOL is_executable_section(IMAGE_SECTION_HEADER *section) {
+    return (section->Characteristics & IMAGE_SCN_CNT_CODE) != 0 ||
+           (section->Characteristics & IMAGE_SCN_MEM_EXECUTE) != 0;
+}
+
+/* Check if this is a text symbol (function) */
+static BOOL is_text_symbol(COFF_SYMBOL *sym, IMAGE_SECTION_HEADER *sections, WORD num_sections) {
+    /* Must have a valid section number */
+    if (sym->SectionNumber <= 0 || sym->SectionNumber > num_sections) {
+        return FALSE;
+    }
+
+    /* Check if symbol is in an executable section */
+    IMAGE_SECTION_HEADER *section = &sections[sym->SectionNumber - 1];
+    if (!is_executable_section(section)) {
+        return FALSE;
+    }
+
+    /* Check storage class and type */
+    BYTE storage = sym->StorageClass;
+    WORD derived_type = (sym->Type >> 4) & 0x3;
+
+    /* Function type in COFF is 0x20 (function derived type) */
+    if (derived_type == 2) {  /* IMAGE_SYM_DTYPE_FUNCTION */
+        return TRUE;
+    }
+
+    /* External or static symbols in code sections are likely functions */
+    if (storage == 2 || storage == 3) {  /* EXTERNAL or STATIC */
+        return TRUE;
+    }
+
+    return FALSE;
+}
+
+/* Parse COFF symbol table from the current executable */
+static int parse_coff_symbols(void) {
+    char exe_path[MAX_PATH];
+    DWORD path_len = GetModuleFileNameA(NULL, exe_path, MAX_PATH);
+    if (path_len == 0 || path_len >= MAX_PATH) {
+        return -1;
+    }
+
+    /* Get runtime base address */
+    HMODULE exe_module = GetModuleHandleA(NULL);
+    g_runtime_base = (DWORD64)exe_module;
+
+    /* Open the executable file */
+    HANDLE file = CreateFileA(exe_path, GENERIC_READ, FILE_SHARE_READ,
+                               NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
+    if (file == INVALID_HANDLE_VALUE) {
+        return -1;
+    }
+
+    /* Map the file into memory */
+    HANDLE mapping = CreateFileMappingA(file, NULL, PAGE_READONLY, 0, 0, NULL);
+    if (mapping == NULL) {
+        CloseHandle(file);
+        return -1;
+    }
+
+    LPVOID base = MapViewOfFile(mapping, FILE_MAP_READ, 0, 0, 0);
+    if (base == NULL) {
+        CloseHandle(mapping);
+        CloseHandle(file);
+        return -1;
+    }
+
+    /* Parse PE header */
+    IMAGE_DOS_HEADER *dos = (IMAGE_DOS_HEADER *)base;
+    if (dos->e_magic != IMAGE_DOS_SIGNATURE) {
+        UnmapViewOfFile(base);
+        CloseHandle(mapping);
+        CloseHandle(file);
+        return -1;
+    }
+
+    IMAGE_NT_HEADERS64 *nt = (IMAGE_NT_HEADERS64 *)((BYTE *)base + dos->e_lfanew);
+    if (nt->Signature != IMAGE_NT_SIGNATURE) {
+        UnmapViewOfFile(base);
+        CloseHandle(mapping);
+        CloseHandle(file);
+        return -1;
+    }
+
+    /* Get image base for address calculation */
+    g_image_base = nt->OptionalHeader.ImageBase;
+
+    /* Get COFF symbol table info */
+    DWORD symbol_table_offset = nt->FileHeader.PointerToSymbolTable;
+    DWORD symbol_count = nt->FileHeader.NumberOfSymbols;
+
+    if (symbol_table_offset == 0 || symbol_count == 0) {
+        /* No COFF symbols - this is normal for release builds */
+        UnmapViewOfFile(base);
+        CloseHandle(mapping);
+        CloseHandle(file);
+        return 0;
+    }
+
+    /* Get section headers for address calculation */
+    IMAGE_SECTION_HEADER *sections = (IMAGE_SECTION_HEADER *)((BYTE *)&nt->OptionalHeader +
+                                                                nt->FileHeader.SizeOfOptionalHeader);
+    WORD num_sections = nt->FileHeader.NumberOfSections;
+
+    /* Get pointer to COFF symbol table */
+    COFF_SYMBOL *symbols = (COFF_SYMBOL *)((BYTE *)base + symbol_table_offset);
+
+    /* String table immediately follows symbol table */
+    char *string_table = (char *)((BYTE *)symbols + symbol_count * sizeof(COFF_SYMBOL));
+
+    /* Count text symbols first */
+    size_t func_count = 0;
+    for (DWORD i = 0; i < symbol_count; i++) {
+        COFF_SYMBOL *sym = &symbols[i];
+
+        if (is_text_symbol(sym, sections, num_sections)) {
+            func_count++;
+        }
+
+        i += sym->NumberOfAuxSymbols;
+    }
+
+    if (func_count == 0) {
+        UnmapViewOfFile(base);
+        CloseHandle(mapping);
+        CloseHandle(file);
+        return 0;
+    }
+
+    /* Allocate symbol table */
+    g_symbol_table = (symbol_entry_t *)malloc(func_count * sizeof(symbol_entry_t));
+    if (!g_symbol_table) {
+        UnmapViewOfFile(base);
+        CloseHandle(mapping);
+        CloseHandle(file);
+        return -1;
+    }
+
+    /* Fill symbol table */
+    size_t idx = 0;
+    for (DWORD i = 0; i < symbol_count && idx < func_count; i++) {
+        COFF_SYMBOL *sym = &symbols[i];
+
+        if (!is_text_symbol(sym, sections, num_sections)) {
+            i += sym->NumberOfAuxSymbols;
+            continue;
+        }
+
+        /* Get symbol name */
+        char name[256];
+        if (sym->Name.LongName.Zeros == 0) {
+            /* Long name - offset into string table */
+            strncpy(name, string_table + sym->Name.LongName.Offset, 255);
+            name[255] = '\0';
+        } else {
+            /* Short name - directly in entry */
+            memcpy(name, sym->Name.ShortName, 8);
+            name[8] = '\0';
+        }
+
+        /* Skip internal symbols */
+        if (name[0] == '.') {
+            i += sym->NumberOfAuxSymbols;
+            continue;
+        }
+
+        /* Calculate virtual address (relative to image base) */
+        WORD section_idx = sym->SectionNumber - 1;
+        DWORD64 rva = sections[section_idx].VirtualAddress + sym->Value;
+
+        /* Store runtime address (with ASLR) */
+        g_symbol_table[idx].address = g_runtime_base + rva;
+        strncpy(g_symbol_table[idx].name, name, 255);
+        g_symbol_table[idx].name[255] = '\0';
+        idx++;
+
+        i += sym->NumberOfAuxSymbols;
+    }
+
+    g_symbol_count = idx;
+
+    /* Sort by address for binary search */
+    qsort(g_symbol_table, g_symbol_count, sizeof(symbol_entry_t), compare_symbols);
+
+    UnmapViewOfFile(base);
+    CloseHandle(mapping);
+    CloseHandle(file);
+
+    return 0;
+}
+
+/* Ensure symbols are loaded */
+static int ensure_initialized(void) {
+    init_lock();
+
+    if (g_initialized) {
+        return 0;
+    }
+
+    EnterCriticalSection(&g_sym_lock);
+
+    if (g_initialized) {
+        LeaveCriticalSection(&g_sym_lock);
+        return 0;
+    }
+
+    int result = parse_coff_symbols();
+    g_initialized = 1;
+
+    LeaveCriticalSection(&g_sym_lock);
+    return result;
+}
+
+int unw_windows_sym_init(void) {
+    return ensure_initialized();
+}
+
+void unw_windows_sym_cleanup(void) {
+    if (g_initialized) {
+        EnterCriticalSection(&g_sym_lock);
+        if (g_initialized) {
+            if (g_symbol_table) {
+                free(g_symbol_table);
+                g_symbol_table = NULL;
+            }
+            g_symbol_count = 0;
+            g_initialized = 0;
+        }
+        LeaveCriticalSection(&g_sym_lock);
+    }
+}
+
+/* Find symbol by address using binary search */
+static symbol_entry_t *find_symbol(DWORD64 address) {
+    if (!g_symbol_table || g_symbol_count == 0) {
+        return NULL;
+    }
+
+    /* Binary search for the largest address <= target */
+    size_t low = 0;
+    size_t high = g_symbol_count;
+    symbol_entry_t *best = NULL;
+
+    while (low < high) {
+        size_t mid = low + (high - low) / 2;
+        if (g_symbol_table[mid].address <= address) {
+            best = &g_symbol_table[mid];
+            low = mid + 1;
+        } else {
+            high = mid;
+        }
+    }
+
+    /* Validate that the symbol is reasonable (offset < 1MB) */
+    if (best && (address - best->address) < 0x100000) {
+        return best;
+    }
+
+    return NULL;
+}
+
+int unw_get_proc_name_windows(unw_cursor_t *cursor, char *buf, size_t buf_len,
+                               unw_word_t *offp) {
+    if (!cursor || !buf || buf_len == 0) {
+        return UNW_EUNSPEC;
+    }
+
+    /* Initialize symbol table if not already done */
+    if (ensure_initialized() != 0) {
+        return UNW_EUNSPEC;
+    }
+
+    /* Get instruction pointer from cursor */
+    unw_word_t ip = 0;
+    if (unw_get_reg(cursor, UNW_REG_IP, &ip) != 0) {
+        return UNW_EUNSPEC;
+    }
+
+    if (ip == 0) {
+        return UNW_ENOINFO;
+    }
+
+    /* Find symbol containing this address */
+    symbol_entry_t *sym = find_symbol((DWORD64)ip);
+    if (!sym) {
+        return UNW_ENOINFO;
+    }
+
+    /* Copy symbol name to output buffer */
+    size_t name_len = strlen(sym->name);
+    if (name_len >= buf_len) {
+        name_len = buf_len - 1;
+    }
+    memcpy(buf, sym->name, name_len);
+    buf[name_len] = '\0';
+
+    /* Set offset if requested */
+    if (offp) {
+        *offp = (unw_word_t)(ip - sym->address);
+    }
+
+    return 0;
+}
+
+/**
+ * _Ux86_64_get_proc_name - Internal libunwind function for symbol resolution
+ *
+ * This is the internal function that MinGW libunwind calls from unw_get_proc_name().
+ * By providing this implementation, we make libunwind's symbol resolution work on Windows.
+ *
+ * The MinGW libunwind declares this as a weak symbol that returns UNW_ENOINFO.
+ * By linking with this library (or compiling this file with your program),
+ * our implementation takes precedence and provides actual symbol resolution
+ * using the COFF symbol table embedded in the PE executable.
+ *
+ * Usage:
+ *   Option 1: Link the pre-built DLL:
+ *     clang-tool-chain-c your_program.c -lunwind -lunwind_proc_name -o program.exe
+ *
+ *   Option 2: Compile this file with your program:
+ *     clang-tool-chain-c unwind_windows.c your_program.c -lunwind -o program.exe
+ *
+ * After linking, unw_get_proc_name() will return function names instead of UNW_ENOINFO.
+ */
+int _Ux86_64_get_proc_name(unw_cursor_t *cursor, char *buf, size_t buf_len,
+                            unw_word_t *offp) {
+    return unw_get_proc_name_windows(cursor, buf, buf_len, offp);
+}
+
+/**
+ * __wrap__Ux86_64_get_proc_name - For use with -Wl,--wrap linker option
+ *
+ * This provides an alternative linking method using --wrap:
+ *   clang-tool-chain-c your_program.c -lunwind -Wl,--wrap=_Ux86_64_get_proc_name -o program.exe
+ *
+ * When using --wrap, the linker redirects calls to _Ux86_64_get_proc_name
+ * to __wrap__Ux86_64_get_proc_name.
+ */
+int __wrap__Ux86_64_get_proc_name(unw_cursor_t *cursor, char *buf, size_t buf_len,
+                                   unw_word_t *offp) {
+    return unw_get_proc_name_windows(cursor, buf, buf_len, offp);
+}
+
+/**
+ * Override functions for LLVM libunwind.
+ *
+ * These are defined when compiling directly (not as shared library).
+ * They override the LLVM libunwind functions to use our implementation.
+ *
+ * When building as shared library (-DBUILDING_DLL), these are not defined
+ * to avoid duplicate symbol errors with libunwind.a.
+ */
+#ifndef BUILDING_DLL
+
+/**
+ * __unw_get_proc_name - LLVM libunwind internal function
+ *
+ * This provides the LLVM libunwind internal function that unw_get_proc_name() aliases to.
+ * When this file is linked BEFORE libunwind.a, this definition takes precedence.
+ *
+ * IMPORTANT: Link order matters! This file must be linked BEFORE -lunwind:
+ *   clang-tool-chain-c unwind_windows.c your_program.c -lunwind -o program.exe
+ */
+int __unw_get_proc_name(unw_cursor_t *cursor, char *buf, size_t buf_len,
+                         unw_word_t *offp) {
+    return unw_get_proc_name_windows(cursor, buf, buf_len, offp);
+}
+
+/**
+ * unw_get_proc_name - Standard libunwind API function
+ *
+ * This directly provides the user-facing API function.
+ * When this file is linked BEFORE libunwind.a, this definition takes precedence.
+ */
+int unw_get_proc_name(unw_cursor_t *cursor, char *buf, size_t buf_len,
+                       unw_word_t *offp) {
+    return unw_get_proc_name_windows(cursor, buf, buf_len, offp);
+}
+
+#endif /* BUILDING_DLL */
+
+#endif /* _WIN32 */

clang_tool_chain/symbolizer/unwind_windows.h

@@ -0,0 +1,112 @@
+/**
+ * unwind_windows.h - Windows symbol resolution for libunwind
+ *
+ * This header provides symbol resolution for libunwind on Windows.
+ * MinGW libunwind does not implement symbol resolution, returning UNW_ENOINFO.
+ * This implementation reads the COFF symbol table embedded in the PE
+ * executable for symbol resolution.
+ *
+ * AUTOMATIC INTEGRATION:
+ *   When you link with this library, the internal _Ux86_64_get_proc_name()
+ *   function is provided, making libunwind's unw_get_proc_name() work
+ *   automatically. No code changes needed!
+ *
+ *   Example:
+ *     clang-tool-chain-c your_program.c -lunwind -lunwind_proc_name -o program.exe
+ *
+ *   Or compile unwind_windows.c directly:
+ *     clang-tool-chain-c unwind_windows.c your_program.c -lunwind -o program.exe
+ *
+ * MANUAL USAGE (alternative):
+ *   #ifdef _WIN32
+ *   #include <unwind_windows.h>
+ *   #define unw_get_proc_name unw_get_proc_name_windows
+ *   #endif
+ *
+ * No additional libraries required for linking (uses Windows API only).
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright (c) 2026 clang-tool-chain contributors
+ */
+
+#ifndef UNWIND_WINDOWS_H
+#define UNWIND_WINDOWS_H
+
+#ifdef _WIN32
+
+#include <libunwind.h>
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Resolve function name for the current cursor position.
+ *
+ * This is a Windows-specific replacement for unw_get_proc_name() that uses
+ * DbgHelp for symbol resolution instead of returning UNW_ENOINFO.
+ *
+ * @param cursor    libunwind cursor pointing to a stack frame
+ * @param buf       Buffer to store the function name
+ * @param buf_len   Size of the buffer
+ * @param offp      Pointer to store the offset from function start (can be NULL)
+ *
+ * @return 0 on success, UNW_ENOINFO if symbol not found, UNW_EUNSPEC on error
+ */
+int unw_get_proc_name_windows(unw_cursor_t *cursor, char *buf, size_t buf_len,
+                               unw_word_t *offp);
+
+/**
+ * Initialize Windows symbol resolution.
+ *
+ * This function initializes the DbgHelp library for the current process.
+ * It is called automatically by unw_get_proc_name_windows() on first use,
+ * but can be called explicitly for earlier initialization.
+ *
+ * @return 0 on success, non-zero on error
+ */
+int unw_windows_sym_init(void);
+
+/**
+ * Cleanup Windows symbol resolution.
+ *
+ * Call this before program exit to free DbgHelp resources.
+ * Optional but recommended for clean shutdown.
+ */
+void unw_windows_sym_cleanup(void);
+
+/**
+ * Internal libunwind function for symbol resolution (nongnu libunwind).
+ *
+ * This function provides the internal implementation for nongnu libunwind.
+ * The MinGW libunwind declares this as a weak symbol that returns UNW_ENOINFO.
+ * Our implementation overrides the weak symbol and provides actual symbol
+ * resolution using the COFF symbol table.
+ *
+ * @param cursor    libunwind cursor pointing to a stack frame
+ * @param buf       Buffer to store the function name
+ * @param buf_len   Size of the buffer
+ * @param offp      Pointer to store the offset from function start (can be NULL)
+ *
+ * @return 0 on success, UNW_ENOINFO if symbol not found, UNW_EUNSPEC on error
+ */
+int _Ux86_64_get_proc_name(unw_cursor_t *cursor, char *buf, size_t buf_len,
+                            unw_word_t *offp);
+
+/*
+ * The following functions override LLVM libunwind functions.
+ * They are only defined when compiling unwind_windows.c directly with your
+ * program (not when building as a DLL).
+ *
+ * Compile order: unwind_windows.c must come BEFORE -lunwind in the command:
+ *   clang-tool-chain-c unwind_windows.c your_program.c -lunwind -o program.exe
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _WIN32 */
+
+#endif /* UNWIND_WINDOWS_H */

{clang_tool_chain-1.1.0.dist-info → clang_tool_chain-1.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clang-tool-chain
-Version: 1.1.0
+Version: 1.1.3
 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
@@ -117,7 +117,7 @@ Comprehensive test coverage across all platforms and tool categories ensures rel
 | **lldb** | [![lldb-win](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-win.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-win.yml) | [![lldb-linux-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-linux-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-linux-x86.yml) | [![lldb-linux-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-linux-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-linux-arm.yml) | [![lldb-macos-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-macos-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-macos-x86.yml) | [![lldb-macos-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-macos-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lldb-macos-arm.yml) |
 | **cosmocc** | [![cosmocc-win](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-win.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-win.yml) | [![cosmocc-linux-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-linux-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-linux-x86.yml) | [![cosmocc-linux-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-linux-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-linux-arm.yml) | [![cosmocc-macos-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-macos-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-macos-x86.yml) | [![cosmocc-macos-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-macos-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-cosmocc-macos-arm.yml) |
 | **lib-deploy** | [![lib-deploy-win](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-win.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-win.yml) | [![lib-deploy-linux-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-linux-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-linux-x86.yml) | [![lib-deploy-linux-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-linux-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-linux-arm.yml) | [![lib-deploy-macos-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-macos-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-macos-x86.yml) | [![lib-deploy-macos-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-macos-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-lib-deploy-macos-arm.yml) |
-| **libunwind** | N/A | [![libunwind-linux-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-x86.yml) | [![libunwind-linux-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-arm.yml) | N/A | N/A |
+| **libunwind** | [![libunwind-win](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-win.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-win.yml) | [![libunwind-linux-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-x86.yml) | [![libunwind-linux-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-linux-arm.yml) | [![libunwind-macos-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-macos-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-macos-x86.yml) | [![libunwind-macos-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-macos-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-libunwind-macos-arm.yml) |
 
 **📖 [Complete Test Matrix Documentation](docs/TEST_MATRIX.md)** - Tool category descriptions, test organization, running tests locally.
 
@@ -1009,19 +1009,52 @@ See: https://github.com/google/sanitizers/issues/899
 
 ---
 
-## 📚 Bundled libunwind (Linux)
+## 📚 libunwind Support (All Platforms)
 
-**Self-contained stack unwinding - no system packages required**
+**Cross-platform stack unwinding for debugging and profiling**
 
-On Linux, clang-tool-chain bundles libunwind headers and shared libraries, providing a complete solution for stack unwinding without requiring system packages like `libunwind-dev`.
+clang-tool-chain provides libunwind support on all platforms with platform-specific implementations:
+- **Linux**: Bundled libunwind (headers + shared libraries) - no system packages required
+- **Windows**: MinGW sysroot libunwind - included in toolchain
+- **macOS**: System libunwind from macOS SDK - no additional installation required
 
-### What's Bundled
+All platforms support `#include <libunwind.h>` and `-lunwind` out of the box.
+
+### What's Bundled (Linux)
 
 | Component | Files | Size |
 |-----------|-------|------|
 | Headers | `libunwind.h`, `libunwind-common.h`, `libunwind-x86_64.h`/`libunwind-aarch64.h`, `unwind.h` | ~20 KB |
 | Libraries | `libunwind.so.*`, `libunwind-x86_64.so.*` (or `aarch64`) | ~300 KB |
 
+### Platform-Specific Details
+
+| Platform | Source | Installation | Symbol Resolution | Notes |
+|----------|--------|--------------|-------------------|-------|
+| **Linux** | Bundled (from Debian packages) | Automatic with toolchain | ✅ Full support via `unw_get_proc_name()` | Includes headers + shared libraries |
+| **Windows** | MinGW sysroot | Automatic with toolchain | ⚠️ Limited - use `llvm-symbolizer` | Stack walking works; symbol resolution requires external tool |
+| **macOS** | System SDK | Pre-installed with macOS | ✅ Full support via `unw_get_proc_name()` | Uses system libunwind |
+
+**Windows Symbol Resolution:**
+
+MinGW libunwind on Windows doesn't support `unw_get_proc_name()`. While `llvm-symbolizer` is bundled, Windows ASLR makes runtime address resolution complex.
+
+**Recommended**: Use `clang-tool-chain-lldb` for debugging with symbols, or use Linux/macOS for built-in symbol resolution.
+
+**Verification** (llvm-symbolizer works with static addresses):
+```bash
+# Compile with debug symbols
+clang-tool-chain-c program.c -o program.exe -g
+
+# Get function addresses and resolve
+llvm-nm program.exe | grep main
+# Shows: 1400014d0 T main
+
+llvm-symbolizer -e program.exe -f -C 0x1400014d0
+# Shows: main
+#        C:\path\to\program.c:10:0
+```
+
 ### How It Works
 
 When compiling on Linux, clang-tool-chain **automatically**:
@@ -1068,11 +1101,13 @@ clang-tool-chain-c backtrace.c -lunwind -o backtrace
 
 ### Configuration
 
-**Disable bundled libunwind** (use system version instead):
+**Disable bundled libunwind on Linux** (use system version instead):
 ```bash
-export CLANG_TOOL_CHAIN_NO_BUNDLED_UNWIND=1
+export CLANG_TOOL_CHAIN_NO_BUNDLED_UNWIND=1  # Linux only
 ```
 
+**Note**: This environment variable only applies to Linux. Windows and macOS always use their respective platform sources (MinGW sysroot and system SDK).
+
 ### Platform Support
 
 | Platform | Headers | Libraries | Status |

{clang_tool_chain-1.1.0.dist-info → clang_tool_chain-1.1.3.dist-info}/RECORD

@@ -1,15 +1,15 @@
 clang_tool_chain/__init__.py,sha256=u-qgOuQxh5W2g7n8BgUtBnUWsK66rM4N6LJXY9PiEx0,880
-clang_tool_chain/__version__.py,sha256=6CB4WX5utk2VKYGwXj_5nRzglWK1ken81ARqHoarPF4,71
+clang_tool_chain/__version__.py,sha256=9aF3qsv8HoxAYFRckzQBjJmtctXtRBzyFxsX7lsktLc,71
 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
-clang_tool_chain/cli.py,sha256=Rz0i-o85dRtuFv-K7DYbsRcWuYDn6dRv8EdASB_kE2U,44225
+clang_tool_chain/cli.py,sha256=VLw7rulCBpiO9Ch2qXIyXnzagYg85-6DxFcKJVAInyo,44535
 clang_tool_chain/cli_args.py,sha256=oYAzjhpS9m_Vxr5Z1I97pv07BlxV22cnGaPmV6aON_g,949
 clang_tool_chain/cli_parsers.py,sha256=cHVDyW75N_Kao1VYeAgw_L-1K65DjyvWUigQScTFivY,6814
 clang_tool_chain/component_db.py,sha256=ohtlycsrEokui83iZyPsTyxmvXgkD7_OpVwAn1Cq8gI,9096
 clang_tool_chain/downloader.py,sha256=fqErxTaI3oEYbloLZnrWXJ26j2iGOngPnl4i8kqOWNs,6041
 clang_tool_chain/env_breadcrumbs.py,sha256=bvPTz8xABILhzrXTEBzdGrSbpEXLf2YVgcYEe-IdhNY,2335
-clang_tool_chain/env_utils.py,sha256=5ovnV9cQ_-g5yBlvG8OyaH0fJ-gYasCwvEn_nKYiw_4,4234
+clang_tool_chain/env_utils.py,sha256=DVyvoD2xqJwA2LYt7MqnvFSBJiTLOaicCDribFoHTg0,4380
 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
@@ -39,7 +39,7 @@ clang_tool_chain/deployment/so_deployer.py,sha256=eAygmGojioi1iz5cHeqmKjJ5fI-5Xo
 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=fFQEW9VejCdbBvt4quNJ2X8udh_PKgewTfzUXHmXzyc,940
-clang_tool_chain/execution/arg_transformers.py,sha256=j73CZg8jen7bSymAoiNgqvAQka-e-RMyKkYbh28qy0o,23899
+clang_tool_chain/execution/arg_transformers.py,sha256=NOuU3WheufJA2MVS79kWtStiL_db-LmdHXPm7GFKEqA,25773
 clang_tool_chain/execution/build.py,sha256=YHS1BJTZg5pBS9czVko41mBdfswSPad5hxfitMoLvsI,13275
 clang_tool_chain/execution/build_pipeline.py,sha256=ORJEJ8WYp8c7bhWAa-e3w_ySXwenpUczlmXgoGByToY,17823
 clang_tool_chain/execution/core.py,sha256=7CJ0azznC5lq5bw8amk2kwCIN2I_OnDiKytpapkvrdY,25273
@@ -49,7 +49,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=g07hDdicGI2QqHzahLm8CKm6c-SthLAkR8kANbPxBIU,7583
+clang_tool_chain/execution/sanitizer_env.py,sha256=bLGUATKNnuB8WxWt1eopVgEh6bsZzkmpcpGxYOeRcHk,10642
 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
@@ -66,11 +66,13 @@ clang_tool_chain/platform/paths.py,sha256=K0IjeVwbmgPlAWQO8mS3r1WS4C2dN6IYrSqPpc
 clang_tool_chain/sdk/__init__.py,sha256=G8Zt5N5bkOviX76lTX38YMVX_wESJUTk1a0GKEowWb4,521
 clang_tool_chain/sdk/macos.py,sha256=b7eshUH5h2TIfYeiS1ROReGfeOVTGf6I3HswEF9Z5r8,6600
 clang_tool_chain/sdk/windows.py,sha256=8zMLAoFz2OKMz-w6Kqxr3A-6Cofto2VWZvCvRi7knd8,6286
+clang_tool_chain/symbolizer/unwind_windows.c,sha256=kycjNPB9yU-by50OQAd5oVmxg3WjTUYyAsYdTnlKTZU,13802
+clang_tool_chain/symbolizer/unwind_windows.h,sha256=XTWhJDv13AAMUPAzWCfRN7tO6EbNhv1-0ys0VbXET58,3684
 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.1.0.dist-info/METADATA,sha256=FU9mvPYq7qfmEGqYBb6ucjrrX3jCDIbJoKb1c9BSIic,57944
-clang_tool_chain-1.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-clang_tool_chain-1.1.0.dist-info/entry_points.txt,sha256=N0a0OVPkCFbf6BisRkHj-m2TcZ-f1mqxfXxAHQxfrQg,2800
-clang_tool_chain-1.1.0.dist-info/licenses/LICENSE,sha256=51FO1oc2pZbQNI0v0_THnznnZIF4iFgawG1xnQ58kKo,10997
-clang_tool_chain-1.1.0.dist-info/RECORD,,
+clang_tool_chain-1.1.3.dist-info/METADATA,sha256=enxAhFiBH36eUVqcz_ljHgQDSU9KFV8h23kVYAnAcKk,60267
+clang_tool_chain-1.1.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clang_tool_chain-1.1.3.dist-info/entry_points.txt,sha256=N0a0OVPkCFbf6BisRkHj-m2TcZ-f1mqxfXxAHQxfrQg,2800
+clang_tool_chain-1.1.3.dist-info/licenses/LICENSE,sha256=51FO1oc2pZbQNI0v0_THnznnZIF4iFgawG1xnQ58kKo,10997
+clang_tool_chain-1.1.3.dist-info/RECORD,,