企业官网建设流程全解析

dotnet/runtime Linux 构建环境搭建指南：依赖清单、交叉编译工具与 Docker 方案详解

【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime

导读

本文基于 dotnet/runtime 仓库的 linux-requirements.md，系统梳理在 Linux 上搭建 .NET 运行时（Runtime）构建环境的完整方案：包括 Debian/Ubuntu、Fedora、Gentoo 等主流发行版的依赖安装清单、CMake 版本兼容性处理、WASM 交叉构建所需的 Clang 版本要求、跨架构/跨平台交叉编译的额外工具，以及使用官方 Docker 镜像直接构建的替代路径。读完本文，你将能够在自己的 Linux 机器上从零配置好 dotnet/runtime 的构建环境，并理解各依赖项在仓库构建流程中的实际作用。

两种构建环境方案概述

在 Linux 上构建 dotnet/runtime 仓库（即dotnet/runtime源码树，本仓库的根目录即为其工作区），官方文档给出了两条路线：

1. 在自己的 Linux 机器上直接搭建环境：适合需要灵活控制工具链、需要在同一环境中使用其他开发工具的开发者；
2. 使用官方构建所用的 Docker 镜像：利用微软官方预先配置好的构建镜像，免去手动安装依赖的繁琐步骤。

两种方式各有优劣：Docker 方案开箱即用、环境与 CI 一致，但灵活性受限；自建环境则可自由组合工具链。若你使用的是WSL（Windows Subsystem for Linux），则直接按照其中所装发行版（distro）对应的章节操作即可，Docker 桌面版在 Windows 上的 Linux 容器同样依托 WSL 运行。

硬件底线：官方要求最低 1GB 内存（已知在 512MB 的虚拟机上构建会失败，相关记录见仓库 issues 讨论），且建议配置更高，否则构建耗时极长。

使用辅助脚本一键安装依赖

仓库在 eng/common/native/install-dependencies.sh 提供了一个跨发行版的依赖安装脚本，可用于 CI 与本地环境：

# 非 root 用户需要加 sudo eng/common/native/install-dependencies.sh

该脚本的核心逻辑如下（eng/common/native/install-dependencies.sh）：

• 若未显式传入 OS 参数，会先通过 init-os-and-arch.sh 用uname -s自动探测系统类型与 CPU 架构（x64、arm64、riscv64、ppc64le 等）；
• 读取/etc/os-release中的ID/ID_LIKE字段，按发行版分支执行对应的包管理器命令：
  • Debian 系（debian/ubuntu）：apt install build-essential gettext locales cmake llvm clang lld lldb liblldb-dev libunwind8-dev libicu-dev liblttng-ust-dev libssl-dev libkrb5-dev pigz cpio ninja-build file，并额外调用localedef生成en_US.UTF-8locale；
  • Fedora/RHEL/Azure Linux/CentOS：优先使用tdnf，否则退回dnf，安装cmake llvm lld lldb clang python curl libicu-devel openssl-devel krb5-devel lttng-ust-devel pigz cpio ninja-build file；
  • Amazon Linux（amzn）：与 RHEL 系包列表基本一致；
  • Alpine：使用apk add安装build-base cmake bash curl clang llvm llvm-dev lld lldb-dev krb5-dev lttng-ust-dev icu-dev openssl-dev pigz cpio ninja file。

脚本以set -e运行，遇到不支持的发行版会直接报错退出。官方建议：即使使用脚本，也最好手动核对关键依赖（尤其是 cmake、clang 版本）是否真正满足要求。

Debian 与 Ubuntu 的依赖清单

以下说明以当前Ubuntu LTS版本为基准撰写。需要安装的包如下：

一次性安装命令（非 root 用户加sudo）：

apt install -y cmake llvm lld clang build-essential \ python-is-python3 curl git lldb libicu-dev liblttng-ust-dev \ libssl-dev libkrb5-dev ninja-build pigz cpio

版本红线：如果你运行的是早于 Ubuntu 22.04 LTS的 Ubuntu，或早于 Debian 12的 Debian，不要直接用 apt 安装 cmake，请按下一节处理。

老版本 Ubuntu/Debian 上的 CMake 安装

截至文档撰写时，Ubuntu 22.04 LTS 的 apt 源中 CMake 只到 3.22（更老的 Ubuntu 更低），Debian 12 中是 3.25.1，均低于仓库要求的3.26，无法直接兼容 dotnet/runtime 的构建系统（仓库中 native 组件的 CMakeLists.txt 即声明了cmake_minimum_required(VERSION 3.26)，eng/native/configurecompiler.cmake 中也有基于CMAKE_VERSION的版本分支逻辑）。两条替代安装路径：

方案一：通过 snap 安装新版 CMake

# 非 root 用户需要加 sudo snap install cmake

snap 渠道提供比系统源更新的 CMake 版本，安装后cmake命令即指向新版。

方案二：使用 Kitware 官方 APT 源

按 Kitware 官方指引添加其 APT feed（源地址包含apt.kitware.com），随后即可通过apt安装满足 3.26 及以上版本的 CMake。由于仓库无法直接依赖系统源中的旧版本，建议优先采用此方案以获得更贴近发行版习惯的包管理体验。

WASM 构建所需的 Clang

WASM（WebAssembly）构建对 Clang 的最低要求是 16，文档撰写时最新为 18。若使用 Ubuntu 22.04 LTS 或更老版本，系统源中的 Clang 版本不足，需要额外添加 LLVM 官方仓库：

# 非 root 用户需要加 sudo add-apt-repository -y "deb http://apt.llvm.org/$(lsb_release -s -c)/ llvm-toolchain-$(lsb_release -s -c)-18 main" apt update -y apt install -y clang-18

命令中的$(lsb_release -s -c)会自动展开为当前发行版代号，从而匹配对应的llvm-toolchain-<codename>-18软件源。另一个现成的环境示例是仓库中的 .devcontainer/Dockerfile：它基于mcr.microsoft.com/devcontainers/dotnet镜像，并在构建阶段下载执行install-dependencies.sh与init-os-and-arch.sh来完成同样的依赖装配。

交叉编译（Cross Building）的额外工具

如果你的目标是从 Linux 交叉编译到其他 CPU 架构（如 Arm32、Arm64）或其他操作系统（如 Alpine、FreeBSD），还需要额外安装以下软件包：

• binfmt-support：内核 binfmt 机制支持，用于执行不同格式的二进制（配合 qemu-user）；
• debootstrap：构建最小化 rootfs（crossrootfs）的工具；
• qemu：QEMU 模拟器；
• qemu-user-static：用户态静态 QEMU，用于在 x64 主机上运行 Arm 等架构的二进制。

apt install binfmt-support debootstrap qemu qemu-user-static

需要强调的是，这些包用于构建crossrootfs（交叉编译所需的根文件系统），而非构建 runtime 本身。仓库在 eng/common/cross/ 目录下提供了build-rootfs.sh、build-android-rootfs.sh、tizen-build-rootfs.sh等脚本以及 arm64、armel、riscv64、x64 等架构子目录，配合 toolchain.cmake 完成 crossrootfs 的生成与工具链切换。构建时通过ROOTFS_DIR环境变量指向生成的 rootfs（详见本文 Docker 一节），从而完成跨架构编译。

Fedora 上的依赖安装

以下说明以Fedora 40为基准。需要安装的工具链包：

• clang
• cmake
• cpio
• curl
• git
• krb5-devel
• libicu-devel
• lld
• lldb
• llvm
• lttng-ust-devel
• ninja-build
• openssl-devel
• pigz（可选，为packssubset 的 tarball 启用并行 gzip 压缩）
• python

一次性安装命令（非 root 用户加sudo）：

dnf install -y cmake llvm lld lldb clang python curl git \ libicu-devel openssl-devel krb5-devel lttng-ust-devel ninja-build pigz cpio

与 Debian 系相比，Fedora 的头文件包命名使用-devel后缀（如libicu-devel、openssl-devel、krb5-devel、lttng-ust-devel），Python 直接提供python包名，无需python-is-python3这类别名包。

Gentoo 上的依赖安装

Gentoo 用户可执行如下命令安装核心依赖：

emerge --ask clang dev-util/lttng-ust app-crypt/mit-krb5

即安装 Clang 编译器、LTTng 用户态跟踪库（dev-util/lttng-ust）与 MIT Kerberos 库（app-crypt/mit-krb5）。由于 Gentoo 采用源码式包管理（Portage），其余依赖（cmake、ninja、ICU 等）通常已在系统中就绪或可通过 USE flag 组合满足，仓库官方文档也欢迎社区提交其他发行版/环境的需求说明文档（Pull Request）。

使用 Docker 镜像构建

准备 Docker Engine

使用 Docker 方案前，需先安装 Docker Engine（安装二进制与指引见 Docker 官方站点）。安装完成后即可按照仓库的 docs/workflow/using-docker.md 文档操作。Docker 方案的优势在于：宿主机的操作系统种类不再重要——例如在 Ubuntu 22.04 上可以毫无障碍地使用 Ubuntu 18.04 镜像；Windows 上启用 WSL 后同样可运行 Linux 容器。需要注意的是：

• 同一个 Docker Daemon 无法同时运行多个不同内核体系的容器（如 Linux 容器与 Windows 容器需切换并重启 Docker）；
• 镜像架构必须与宿主机支持的平台匹配：例如 Apple Silicon Mac 可通过 Rosetta 模拟运行 x64 与 Arm64 镜像；Linux Arm64 主机可运行 Arm32 镜像；
• Windows 上虽然 Docker 依赖 WSL 运行 Linux 容器，但无需进入 WSL 终端，任何装有docker命令的 cmd/powershell 终端都可直接操作。

官方构建镜像一览

以下镜像（mcr.microsoft.com/dotnet-buildtools/prereqs前缀）是官方 CI 使用的预构建环境，其中crossrootfs dir一列对应容器内ROOTFS_DIR应指向的路径：

主要镜像（覆盖绝大多数常规构建场景）

扩展镜像（针对 Android、RISC-V 等特殊场景）

用 docker run 构建仓库

选定镜像后，即可通过docker run挂载仓库源码并执行构建脚本。官方示例（以 Azure Linux 镜像交叉编译 x64 目标为例）：

docker run --rm \ -v <RUNTIME_REPO_PATH>:/runtime \ -w /runtime \ -e ROOTFS_DIR=/crossrootfs/x64/ \ mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-net11.0-cross-amd64 \ ./build.sh -s clr --cross -c Checked

逐项拆解各参数的含义：

• --rm：容器运行结束后自动删除；
• -v <RUNTIME_REPO_PATH>:/runtime：将本机仓库克隆目录挂载到容器内/runtime路径；
• -w /runtime：容器工作目录设为/runtime；
• -e ROOTFS_DIR=/crossrootfs/x64/：设置交叉构建所需的环境变量，指向容器内预置的 crossrootfs；
• mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux-3.0-net11.0-cross-amd64：要拉取的镜像全名，此处即使用 Azure Linux 镜像构建 x64 目标；
• ./build.sh -s clr --cross -c Checked：在仓库内执行的构建命令——构建Clrsubset、Checked配置，并开启交叉编译选项。

如果需要进入容器交互式操作（例如在同一路径下执行多次不同配置的构建），可将末尾的构建命令替换为-it标志，即可获得容器内的小型 shell。不过容器内置 shell 的工具非常有限（仅够执行基本操作），不适合作为日常完整开发环境。

构建入口与后续指引

完成环境搭建后，仓库根目录下的 build.sh（Linux/macOS）与 dotnet.cmd（Windows）即为统一构建入口，-s参数可指定 subset（如clr、libraries、mono）。更细致的构建、调试与测试工作流可参考：

• docs/workflow/using-docker.md：Docker 工作流完整说明；
• docs/workflow/building/：coreclr、libraries、mono 等各 subset 的专项构建文档；
• docs/workflow/debugging/：构建产物的调试指南；
• eng/common/native/install-dependencies.sh：依赖安装脚本源码，可直接阅读确认各发行版的精确包列表。

总结：无论选择“自建环境”还是“Docker 镜像”，关键都在于满足三条硬性要求——CMake ≥ 3.26、WASM 场景下 Clang ≥ 16、交叉构建场景下准备好 binfmt/debootstrap/qemu 与对应的 crossrootfs。对照本文的包清单逐项核对，即可快速获得一个可用的 dotnet/runtime 构建环境。

【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime