当前位置：首页 > news >正文

dockcross社区贡献指南：如何添加新的目标架构

news 2026/5/12 17:49:21

dockcross社区贡献指南：如何添加新的目标架构

【免费下载链接】dockcross项目地址: https://gitcode.com/gh_mirrors/do/dockcross

dockcross是一个强大的跨平台编译工具链项目，它通过Docker镜像提供了预配置的交叉编译环境，让开发者能够轻松为不同架构和操作系统构建应用程序。本指南将详细介绍如何为dockcross添加新的目标架构，帮助社区扩展这一工具的能力。

为什么要添加新的目标架构？

随着嵌入式系统和边缘计算的发展，新的硬件架构不断涌现。为dockcross添加对新架构的支持，不仅能满足特定硬件平台的开发需求，还能让更多开发者受益于dockcross的便捷交叉编译环境。无论是为物联网设备、嵌入式系统还是新兴的处理器架构添加支持，都能为社区带来价值。

准备工作：环境与工具

在开始添加新的目标架构之前，确保你的开发环境满足以下要求：

安装Docker并确保其正常运行
熟悉Docker镜像构建和Dockerfile编写
了解交叉编译的基本概念
安装Git和基本的开发工具链

首先，克隆dockcross仓库到本地：

git clone https://gitcode.com/gh_mirrors/do/dockcross cd dockcross

步骤一：创建架构专用目录

dockcross采用模块化结构，每个目标架构都有自己的专用目录。在项目根目录下创建一个新目录，命名格式为<操作系统>-<架构>，例如linux-riscv64或windows-arm64。

mkdir -p new-architecture

步骤二：配置交叉编译工具链

使用crosstool-ng配置工具链

大多数Linux目标架构使用crosstool-ng来配置交叉编译工具链。以下是基本步骤：

下载并构建crosstool-ng：

git clone --recurse-submodules --remote-submodules https://github.com/crosstool-ng/crosstool-ng.git cd crosstool-ng git checkout crosstool-ng-1.27.0 ./bootstrap ./configure --enable-local make -j$(nproc)

选择一个基础配置并进行定制：

./ct-ng list-samples ./ct-ng <sample-name> ./ct-ng menuconfig

生成工具链配置文件：

./ct-ng show-tuple cp .config ../dockcross/new-architecture/crosstool-ng.config

创建CMake工具链文件

在新架构目录中创建Toolchain.cmake文件，配置CMake交叉编译参数。以下是一个通用模板：

set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_VERSION 1) set(CMAKE_SYSTEM_PROCESSOR <ARCHITECTURE>) set(cross_triple $ENV{CROSS_TRIPLE}) set(cross_root $ENV{CROSS_ROOT}) set(CMAKE_C_COMPILER $ENV{CC}) set(CMAKE_CXX_COMPILER $ENV{CXX}) set(CMAKE_Fortran_COMPILER $ENV{FC}) set(CMAKE_CXX_FLAGS "-I ${cross_root}/include/") list(APPEND CMAKE_FIND_ROOT_PATH ${CMAKE_PREFIX_PATH} ${cross_root} ${cross_root}/${cross_triple}) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) set(CMAKE_SYSROOT ${cross_root}/${cross_triple}/sysroot) set(CMAKE_CROSSCOMPILING_EMULATOR /usr/bin/qemu-<architecture>)

根据目标架构修改CMAKE_SYSTEM_PROCESSOR和CMAKE_CROSSCOMPILING_EMULATOR等参数。

步骤三：编写Dockerfile.in

在新架构目录中创建Dockerfile.in，定义如何构建包含新目标架构工具链的Docker镜像。以下是一个基本模板：

ARG ORG=dockcross FROM ${ORG}/base:latest LABEL maintainer="Your Name <your.email@example.com>" # Crosstool-ng version ENV CT_VERSION=crosstool-ng-1.25.0 #include "common.crosstool" # Install QEMU emulator RUN apt-get update \ && apt-get install -y \ qemu-user \ qemu-user-static \ && apt-get clean --yes # Set cross compiler triple ENV CROSS_TRIPLE=<cross-triple> ENV CROSS_ROOT=${XCC_PREFIX}/${CROSS_TRIPLE} ENV AS=${CROSS_ROOT}/bin/${CROSS_TRIPLE}-as \ AR=${CROSS_ROOT}/bin/${CROSS_TRIPLE}-ar \ CC=${CROSS_ROOT}/bin/${CROSS_TRIPLE}-gcc \ CPP=${CROSS_ROOT}/bin/${CROSS_TRIPLE}-cpp \ CXX=${CROSS_ROOT}/bin/${CROSS_TRIPLE}-g++ \ LD=${CROSS_ROOT}/bin/${CROSS_TRIPLE}-ld \ FC=${CROSS_ROOT}/bin/${CROSS_TRIPLE}-gfortran ENV QEMU_LD_PREFIX="${CROSS_ROOT}/${CROSS_TRIPLE}/sysroot" ENV QEMU_SET_ENV="LD_LIBRARY_PATH=${CROSS_ROOT}/lib:${QEMU_LD_PREFIX}" COPY Toolchain.cmake ${CROSS_ROOT}/ ENV CMAKE_TOOLCHAIN_FILE=${CROSS_ROOT}/Toolchain.cmake ENV PKG_CONFIG_PATH=/usr/lib/<architecture>-linux-gnu/pkgconfig # Linux kernel cross compilation variables ENV PATH=${PATH}:${CROSS_ROOT}/bin ENV CROSS_COMPILE=${CROSS_TRIPLE}- ENV ARCH=<architecture> #include "common.label-and-env"

根据新架构的具体需求，调整CROSS_TRIPLE、PKG_CONFIG_PATH和ARCH等环境变量。

步骤四：更新项目配置

修改Makefile

将新架构添加到项目根目录的Makefile中的STANDARD_IMAGES和GEN_IMAGES变量：

STANDARD_IMAGES = ... new-architecture ... GEN_IMAGES = ... new-architecture ...

添加测试配置

在.github/workflows/main.yml中添加新架构的测试配置，确保新架构能够通过CI测试：

- { image: "new-architecture", stockfish: "yes", stockfish_arg: "ARCH=<architecture>", ninja: "yes", ninja_arg: "", openssl: "yes", openssl_arg: "<openssl-target>", C: "yes", C_arg: "", C-Plus-Plus: "yes", C-Plus-Plus_arg: "", fmt: "yes", fmt_arg: "", cpython: "yes", cpython_arg: "--host=<cross-triple> --target=<cross-triple>", }

步骤五：构建和测试新架构

构建镜像

使用Makefile构建新架构的Docker镜像：

make new-architecture

运行测试

运行自动化测试确保新架构正常工作：

make new-architecture.test

手动测试

生成dockcross脚本并测试交叉编译功能：

docker run --rm dockcross/new-architecture > ./dockcross-new-architecture chmod +x ./dockcross-new-architecture # 测试C程序编译 ./dockcross-new-architecture bash -c '$CC test/C/hello.c -o hello' # 测试CMake项目 ./dockcross-new-architecture cmake -Bbuild -S. -GNinja ./dockcross-new-architecture ninja -Cbuild