build_llvm.py

# SPDX-FileCopyrightText: Copyright (c) 2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Functions to build Clang/LLVM from source and to build the CPU-only Warp library."""

import hashlib
import io
import os
import shutil
import stat
import subprocess
import sys
import tarfile
import urllib.request

from warp._src.build_architecture import machine_architecture
from warp._src.build_dll import *

# set build output path off this file
base_path = os.path.dirname(os.path.realpath(__file__))
build_path = os.path.join(base_path, "warp")

llvm_project_path = os.path.join(base_path, "external", "llvm-project")
llvm_build_path = os.path.join(llvm_project_path, "out", "build")
llvm_install_path = os.path.join(llvm_project_path, "out", "install")


def prebuilt_library_path(arch: str) -> str:
    """Return the directory that the prebuilt Clang/LLVM SDK is linked into."""
    return os.path.join(base_path, "_build", "host-deps", "llvm-project", f"release-{packman_llvm_platform(arch)}")


def fetch_prebuilt_libraries(arch: str) -> None:
    """Download the checksum-pinned Clang/LLVM SDK and link it into ``prebuilt_library_path(arch)``.

    Args:
        arch: The *target* architecture, not necessarily the host's. Intel Mac runners
            cross-compile, so they pass ``"aarch64"``.

    Raises:
        RuntimeError: The Packman pull failed. Wraps the underlying
            :class:`subprocess.CalledProcessError` and names the two escape hatches,
            building LLVM from source and pointing at an existing SDK.
    """
    if os.name == "nt":
        packman = os.path.join(base_path, "tools", "packman", "packman.cmd")
    else:
        packman = os.path.join(base_path, "tools", "packman", "packman")

    # Reuse the current interpreter so packman skips downloading its bundled Python,
    # whose manylinux_2_35 build can't run on older-glibc CI images. Use it only as a
    # default: a pre-set PM_PYTHON_EXT wins, since cross-compilation (e.g. aarch64) needs
    # the build-platform Python instead of sys.executable's crossenv wrapper.
    packman_env = {"PM_PYTHON_EXT": sys.executable, **os.environ}

    # `pull` rather than `install`: packman verifies the checksum attribute only when walking a
    # project file, so the manifest is what makes the download tamper-evident.
    packman_cmd = [
        packman,
        "pull",
        "--platform",
        packman_llvm_platform(arch),
        os.path.join(base_path, "deps", "llvm-deps.packman.xml"),
    ]

    def _run_packman_pull():
        subprocess.check_output(packman_cmd, stderr=subprocess.STDOUT, text=True, env=packman_env)

    try:
        _run_packman_pull()
    except subprocess.CalledProcessError as e:
        output = e.output or ""
        is_intel_mac = sys.platform == "darwin" and machine_architecture() == "x86_64"
        # Intel Mac runners cross-compile to aarch64 but can't exec the aarch64-only
        # 7zz packman 8.2.2 installs. Compressed tar archives are decompressed through
        # that helper, so .tar.xz packages hit this too. Remove this branch and
        # _patch_packman_7zz_for_intel_mac once the internal Mac CI runners migrate
        # off Intel.
        if is_intel_mac and "Bad CPU type in executable" in output and "7zz" in output:
            _patch_packman_7zz_for_intel_mac()
            try:
                _run_packman_pull()
            except subprocess.CalledProcessError as retry_err:
                print(retry_err.output)
                raise RuntimeError(
                    "Failed to fetch the prebuilt Clang/LLVM SDK from GitHub Releases "
                    "after patching the packman 7zz binary for Intel Mac. "
                    "Build LLVM from source with `build_lib.py --build-llvm`, or point at an "
                    "existing SDK with `build_lib.py --llvm-path <dir>`."
                ) from retry_err
        else:
            print(output)
            raise RuntimeError(
                "Failed to fetch the prebuilt Clang/LLVM SDK from GitHub Releases. "
                "Build LLVM from source with `build_lib.py --build-llvm`, or point at an "
                "existing SDK with `build_lib.py --llvm-path <dir>`."
            ) from e


# ip7z 25.01 universal2 (arm64 + x86_64) Mac release, used to replace the
# aarch64-only 7zz that packman 8.2.2 installs. Pinned + hash-verified.
_IP7Z_MAC_URL = "https://github.com/ip7z/7zip/releases/download/25.01/7z2501-mac.tar.xz"
_IP7Z_MAC_SHA256 = "26aa75bc262bb10bf0805617b95569c3035c2c590a99f7db55c7e9607b2685e0"


def _patch_packman_7zz_for_intel_mac():
    """Overwrite packman's cached mac-arm/64/7zz with a universal2 binary.

    Packman 8.2.2 ships only an aarch64 7zz for macOS, so Intel Mac runners
    can't exec the 7z helper needed to decompress downstream .7z packages.
    Delete this function and the ``is_intel_mac`` branch in
    ``fetch_prebuilt_libraries`` once the internal Mac CI runners migrate
    off Intel.
    """
    pm_root = os.environ.get("PM_PACKAGES_ROOT") or os.path.expanduser("~/Library/Application Support/packman-cache")
    bad_7zz = os.path.join(pm_root, "chk", "7zz", "25.01", "mac-arm", "64", "7zz")
    if not os.path.exists(bad_7zz):
        raise RuntimeError(f"Expected packman to have extracted 7zz to {bad_7zz}, but it's missing.")

    print(f"Patching {bad_7zz} with universal2 7zz from {_IP7Z_MAC_URL}")
    with urllib.request.urlopen(_IP7Z_MAC_URL, timeout=30) as resp:
        tarball = resp.read()
    digest = hashlib.sha256(tarball).hexdigest()
    if digest != _IP7Z_MAC_SHA256:
        raise RuntimeError(f"SHA256 mismatch for {_IP7Z_MAC_URL}: expected {_IP7Z_MAC_SHA256}, got {digest}")

    with tarfile.open(fileobj=io.BytesIO(tarball), mode="r:xz") as tar:
        member = tar.getmember("7zz")
        extracted = tar.extractfile(member)
        if extracted is None:
            raise RuntimeError(f"Tarball at {_IP7Z_MAC_URL} does not contain a regular 7zz file")
        with open(bad_7zz, "wb") as f:
            shutil.copyfileobj(extracted, f)
    os.chmod(bad_7zz, stat.S_IRUSR | stat.S_IXUSR)


def check_build_dependencies(verbose: bool = False) -> None:
    """Check that required build dependencies are available in PATH.

    Args:
        verbose: If True, print location of found dependencies.

    Raises:
        RuntimeError: If any required dependencies (cmake, ninja, git) are missing.
    """
    missing = []

    for tool in ["cmake", "ninja", "git"]:
        tool_path = shutil.which(tool)
        if tool_path:
            if verbose:
                print(f"Found {tool}: {tool_path}")
        else:
            missing.append(tool)

    if missing:
        raise RuntimeError(
            "Missing required build dependencies:\n  "
            + "\n  ".join(missing)
            + "\n\nPlease install using your package manager."
        )


def build_llvm_clang_from_source_for_arch(args, arch: str, llvm_source: str) -> None:
    """Build Clang/LLVM from source for a given architecture.

    Args:
        args: Command line arguments
        arch: Architecture to build for ("aarch64" or "x86_64")
        llvm_source: Path to the LLVM source code
    """

    # Check out the LLVM project Git repository, unless it already exists
    if not os.path.exists(llvm_source):
        # Check that build dependencies are available
        check_build_dependencies(verbose=args.verbose)

        repo_url = "https://github.com/llvm/llvm-project.git"
        version = "22.1.8"
        print(f"Cloning LLVM project from {repo_url} (branch llvmorg-{version})...")

        # Use shallow clone for faster download (depth=1, single branch only)
        # See https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/
        # For full clone: Remove --depth and --single-branch, then add:
        #   subprocess.run(["git", "checkout", f"tags/llvmorg-{version}", "-b", f"llvm-{version}"],
        #                  cwd=llvm_source, check=True)
        subprocess.run(
            [
                "git",
                "clone",
                "--single-branch",
                "--branch",
                f"llvmorg-{version}",
                "--depth",
                "1",
                repo_url,
                llvm_source,
            ],
            check=True,
        )

    print(f"Using LLVM project source from {llvm_source}")

    # CMake supports Debug, Release, RelWithDebInfo, and MinSizeRel builds
    if args.mode == "release":
        msvc_runtime = "MultiThreaded"
        # prefer smaller size over aggressive speed
        cmake_build_type = "MinSizeRel"
    else:
        msvc_runtime = "MultiThreadedDebug"
        # When args.mode == "debug" we build a Debug version of warp.dll but
        # we generally don't want warp-clang.dll to be a slow Debug version.
        if args.debug_llvm:
            cmake_build_type = "Debug"
        else:
            # The GDB/LLDB debugger observes the __jit_debug_register_code symbol
            # defined by the LLVM JIT, for which it needs debug info.
            cmake_build_type = "RelWithDebInfo"

    # Location of cmake and ninja installed through pip (see build.bat / build.sh)
    python_dir = "Scripts" if sys.platform == "win32" else "bin"
    python_path = os.path.join(base_path, "_build", "target-deps", python_dir)
    os.environ["PATH"] = f"{python_path}{os.pathsep}{os.environ['PATH']}"

    if arch == "aarch64":
        target_backend = "AArch64"
    else:
        target_backend = "X86"

    if sys.platform == "darwin":
        host_triple = f"{arch}-apple-macos11"
        osx_architectures = arch  # build one architecture only
        abi_version = ""
    elif os.name == "nt":
        host_triple = f"{arch}-pc-windows"
        osx_architectures = ""
        abi_version = ""
    else:
        host_triple = f"{arch}-pc-linux"
        osx_architectures = ""
        abi_version = "-fabi-version=13"  # GCC 8.2+

    llvm_path = os.path.join(llvm_source, "llvm")
    build_path = os.path.join(llvm_build_path, f"{args.mode}-{arch}")
    install_path = os.path.join(llvm_install_path, f"{args.mode}-{arch}")

    # Build LLVM and Clang
    # fmt: off
    cmake_gen = [
        "cmake",
        "-S", llvm_path,
        "-B", build_path,
        "-G", "Ninja",
        "-D", f"CMAKE_BUILD_TYPE={cmake_build_type}",
        "-D", f"CMAKE_MSVC_RUNTIME_LIBRARY={msvc_runtime}",
        "-D", f"LLVM_TARGETS_TO_BUILD={target_backend};NVPTX",
        "-D", "LLVM_ENABLE_PROJECTS=clang",
        "-D", "LLVM_ENABLE_ZLIB=FALSE",
        "-D", "LLVM_ENABLE_ZSTD=FALSE",
        "-D", "LLVM_ENABLE_TERMINFO=FALSE",
        "-D", "LLVM_BUILD_LLVM_C_DYLIB=FALSE",
        "-D", "LLVM_BUILD_RUNTIME=FALSE",
        "-D", "LLVM_BUILD_RUNTIMES=FALSE",
        "-D", "LLVM_BUILD_TOOLS=FALSE",
        "-D", "LLVM_BUILD_UTILS=FALSE",
        "-D", "LLVM_INCLUDE_BENCHMARKS=FALSE",
        "-D", "LLVM_INCLUDE_DOCS=FALSE",
        "-D", "LLVM_INCLUDE_EXAMPLES=FALSE",
        "-D", "LLVM_INCLUDE_RUNTIMES=FALSE",
        "-D", "LLVM_INCLUDE_TESTS=FALSE",
        "-D", "LLVM_INCLUDE_TOOLS=TRUE",  # Needed by Clang
        "-D", "LLVM_INCLUDE_UTILS=FALSE",
        "-D", f"CMAKE_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=0 {abi_version}",  # The pre-C++11 ABI is still the default on the CentOS 7 toolchain
        "-D", f"CMAKE_INSTALL_PREFIX={install_path}",
        "-D", f"LLVM_HOST_TRIPLE={host_triple}",
        "-D", f"CMAKE_OSX_ARCHITECTURES={osx_architectures}",

        # Disable unused tools and features
        "-D", "CLANG_BUILD_TOOLS=FALSE",
        "-D", "LLVM_ENABLE_PLUGINS=FALSE",
        "-D", "CLANG_PLUGIN_SUPPORT=FALSE",
        "-D", "CLANG_ENABLE_ARCMT=FALSE",
        "-D", "CLANG_ENABLE_STATIC_ANALYZER=FALSE",
        "-D", "CLANG_TOOLING_BUILD_AST_INTROSPECTION=FALSE",
        "-D", "CLANG_TOOL_AMDGPU_ARCH_BUILD=FALSE",
        "-D", "CLANG_TOOL_APINOTES_TEST_BUILD=FALSE",
        "-D", "CLANG_TOOL_ARCMT_TEST_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_CHECK_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_DIFF_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_EXTDEF_MAPPING_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_FORMAT_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_FORMAT_VS_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_FUZZER_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_IMPORT_TEST_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_LINKER_WRAPPER_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_NVLINK_WRAPPER_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_OFFLOAD_BUNDLER_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_OFFLOAD_PACKAGER_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_OFFLOAD_WRAPPER_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_REFACTOR_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_RENAME_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_REPL_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_SCAN_DEPS_BUILD=FALSE",
        "-D", "CLANG_TOOL_CLANG_SHLIB_BUILD=FALSE",
        "-D", "CLANG_TOOL_C_ARCMT_TEST_BUILD=FALSE",
        "-D", "CLANG_TOOL_C_INDEX_TEST_BUILD=FALSE",
        "-D", "CLANG_TOOL_DIAGTOOL_BUILD=FALSE",
        "-D", "CLANG_TOOL_DRIVER_BUILD=FALSE",
        "-D", "CLANG_TOOL_LIBCLANG_BUILD=FALSE",
        "-D", "CLANG_TOOL_SCAN_BUILD_BUILD=FALSE",
        "-D", "CLANG_TOOL_SCAN_BUILD_PY_BUILD=FALSE",
        "-D", "CLANG_TOOL_SCAN_VIEW_BUILD=FALSE",
        "-D", "LLVM_ENABLE_BINDINGS=FALSE",
        "-D", "LLVM_ENABLE_OCAMLDOC=FALSE",
        "-D", "LLVM_TOOL_BUGPOINT_BUILD=FALSE",
        "-D", "LLVM_TOOL_BUGPOINT_PASSES_BUILD=FALSE",
        "-D", "LLVM_TOOL_CLANG_BUILD=FALSE",
        "-D", "LLVM_TOOL_DSYMUTIL_BUILD=FALSE",
        "-D", "LLVM_TOOL_DXIL_DIS_BUILD=FALSE",
        "-D", "LLVM_TOOL_GOLD_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLC_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLDB_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLI_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_AR_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_AS_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_AS_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_BCANALYZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_CAT_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_CFI_VERIFY_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_CONFIG_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_COV_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_CVTRES_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_CXXDUMP_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_CXXFILT_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_CXXMAP_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_C_TEST_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DEBUGINFOD_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DEBUGINFOD_FIND_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DIFF_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DIS_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DIS_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DLANG_DEMANGLE_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DWARFDUMP_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DWARFUTIL_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_DWP_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_EXEGESIS_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_EXTRACT_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_GO_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_GSYMUTIL_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_IFS_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_ISEL_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_ITANIUM_DEMANGLE_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_JITLINK_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_JITLISTENER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_LIBTOOL_DARWIN_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_LINK_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_LIPO_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_LTO2_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_LTO_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_MCA_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_MC_ASSEMBLE_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_MC_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_MC_DISASSEMBLE_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_MICROSOFT_DEMANGLE_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_ML_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_MODEXTRACT_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_MT_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_NM_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_OBJCOPY_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_OBJDUMP_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_OPT_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_OPT_REPORT_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_PDBUTIL_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_PROFDATA_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_PROFGEN_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_RC_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_READOBJ_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_REDUCE_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_REMARK_SIZE_DIFF_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_RTDYLD_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_RUST_DEMANGLE_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_SHLIB_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_SIM_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_SIZE_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_SPECIAL_CASE_LIST_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_SPLIT_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_STRESS_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_STRINGS_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_SYMBOLIZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_TAPI_DIFF_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_TLI_CHECKER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_UNDNAME_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_XRAY_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_YAML_NUMERIC_PARSER_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LLVM_YAML_PARSER_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_LTO_BUILD=FALSE",
        "-D", "LLVM_TOOL_OBJ2YAML_BUILD=FALSE",
        "-D", "LLVM_TOOL_OPT_BUILD=FALSE",
        "-D", "LLVM_TOOL_OPT_VIEWER_BUILD=FALSE",
        "-D", "LLVM_TOOL_REMARKS_SHLIB_BUILD=FALSE",
        "-D", "LLVM_TOOL_SANCOV_BUILD=FALSE",
        "-D", "LLVM_TOOL_SANSTATS_BUILD=FALSE",
        "-D", "LLVM_TOOL_SPLIT_FILE_BUILD=FALSE",
        "-D", "LLVM_TOOL_VERIFY_USELISTORDER_BUILD=FALSE",
        "-D", "LLVM_TOOL_VFABI_DEMANGLE_FUZZER_BUILD=FALSE",
        "-D", "LLVM_TOOL_XCODE_TOOLCHAIN_BUILD=FALSE",
        "-D", "LLVM_TOOL_YAML2OBJ_BUILD=FALSE",
    ]
    # fmt: on
    subprocess.check_call(cmake_gen, stderr=subprocess.STDOUT)

    cmake_build = ["cmake", "--build", build_path]
    subprocess.check_call(cmake_build, stderr=subprocess.STDOUT)

    cmake_install = ["cmake", "--install", build_path]
    subprocess.check_call(cmake_install, stderr=subprocess.STDOUT)


def build_llvm_clang_from_source(args) -> None:
    """Build Clang/LLVM from source."""

    print("Building Clang/LLVM from source...")

    if args.llvm_source_path is not None:
        llvm_source = args.llvm_source_path
    else:
        llvm_source = llvm_project_path

    # On macOS, always build for ARM64 (may be cross-compiled from Intel Mac)
    # On other platforms, build for the machine's architecture
    if sys.platform == "darwin":
        build_llvm_clang_from_source_for_arch(args, "aarch64", llvm_source)
    else:
        build_llvm_clang_from_source_for_arch(args, machine_architecture(), llvm_source)


# build warp-clang.dll
def build_warp_clang_for_arch(args, lib_name: str, arch: str) -> None:
    try:
        cpp_sources = [
            "native/clang/clang.cpp",
            "native/crt.cpp",
        ]
        clang_cpp_paths = [os.path.join(build_path, cpp) for cpp in cpp_sources]

        clang_dll_path = os.path.join(build_path, "bin", lib_name)

        if hasattr(args, "llvm_path") and args.llvm_path:
            # Use an LLVM installation supplied by the caller
            libpath = os.path.join(args.llvm_path, "lib")
            if not os.path.exists(libpath):
                raise FileNotFoundError(f"LLVM library directory not found at {libpath}")
        elif args.build_llvm:
            # obtain Clang and LLVM libraries from the local build
            install_path = os.path.join(llvm_install_path, f"{args.mode}-{arch}")
            libpath = os.path.join(install_path, "lib")
        else:
            # obtain Clang and LLVM libraries from packman
            fetch_prebuilt_libraries(arch)
            libpath = os.path.join(prebuilt_library_path(arch), "lib")
            # Guard against a no-op packman pull: it exits 0 but creates nothing
            # when the platform token is unmatched or a .user override redirects it.
            _lib_ext = ".lib" if os.name == "nt" else ".a"
            if not os.path.isdir(libpath) or not any(f.endswith(_lib_ext) for f in os.listdir(libpath)):
                raise RuntimeError(
                    f"Packman pull succeeded but no LLVM {_lib_ext} libraries were "
                    f"found under {libpath}. "
                    "Build LLVM from source with `build_lib.py --build-llvm`, or "
                    "point at an existing SDK with `build_lib.py --llvm-path <dir>`."
                )

        libs = []
        exported_symbols_file = None

        for _, _, libraries in os.walk(libpath):
            libs.extend(libraries)
            break  # just the top level contains library files

        if os.name == "nt":
            # skip non-library files, e.g. components.json in Conan-packaged LLVM
            libs = [lib for lib in libs if os.path.splitext(lib)[1].lower() == ".lib"]
            libs.append("Version.lib")
            libs.append("Ws2_32.lib")
            libs.append("ntdll.lib")
            libs.append(f'/LIBPATH:"{libpath}"')
        else:
            libs = [f"-l{lib[3:-2]}" for lib in libs if os.path.splitext(lib)[1] == ".a"]
            if sys.platform == "darwin":
                libs += libs  # prevents unresolved symbols due to link order
                exported_symbols_file = os.path.join(build_path, "native", "warp-clang.macos.exports")
            else:
                libs.insert(0, "-Wl,--start-group")
                libs.append("-Wl,--end-group")
            libs.append(f"-L{libpath}")
            libs.append("-lpthread")
            libs.append("-ldl")
            if sys.platform != "darwin":
                libs.append("-lrt")

        build_dll_for_arch(
            args,
            dll_path=clang_dll_path,
            cpp_paths=clang_cpp_paths,
            cu_paths=None,
            arch=arch,
            libs=libs,
            mode=args.mode if args.build_llvm else "release",
            exported_symbols_file=exported_symbols_file,
        )

    except Exception as e:
        # output build error
        print(f"Warp Clang/LLVM build error: {e}")
        raise


def build_warp_clang(args, lib_name: str) -> None:
    """Build the CPU-only Warp library using Clang/LLVM."""

    if sys.platform == "darwin":
        # build for ARM64 only (may be cross-compiled from Intel Mac)
        build_warp_clang_for_arch(args, lib_name, "aarch64")
    else:
        build_warp_clang_for_arch(args, lib_name, machine_architecture())