Boost C++ 库在 HarmonyOS PC 上的交叉编译实践

摘要

本文记录了将 Boost C++ 库（版本 1.83.0）成功交叉编译到 HarmonyOS PC 平台的完整过程。Boost 使用其独特的 Boost.Build（b2/bjam）构建系统，在交叉编译场景下遇到了多个挑战，包括工具链配置、子模块初始化、项目依赖等问题。通过系统性的问题排查和解决，最终成功构建并打包为 HNP（HarmonyOS Native Package）格式。

1. 背景

1.1 项目需求

目标平台: HarmonyOS PC（ARM64 架构）
构建平台: macOS（ARM64）
Boost 版本: 1.83.0
构建系统: Boost.Build (b2/bjam)
输出格式: HNP 包

1.2 技术挑战

Boost 使用自定义的构建系统 Boost.Build，而不是标准的 Makefile 或 CMake。在交叉编译场景下，主要挑战包括：

工具链配置: 需要正确配置 HarmonyOS SDK 提供的 LLVM 工具链
子模块依赖: Boost 使用 git submodules，需要正确初始化多个子模块
项目依赖: Boost.Build 的项目依赖关系复杂，需要正确处理
构建顺序: headers 和 libraries 的构建顺序有严格要求

2. 环境准备

2.1 工具链信息

HarmonyOS SDK 提供的交叉编译工具链位于：

复制代码

/Users/jianguo/Desktop/ohosdk/native/llvm/bin/

关键工具：

clang++: C++ 编译器
ld.lld: 链接器
llvm-ar: 归档工具
llvm-ranlib: 索引工具

2.2 编译标志

bash 复制代码

CXXFLAGS="-fPIC -D__MUSL__=1 -D__OHOS__ -fstack-protector-strong \
          --target=aarch64-linux-ohos \
          --ld-path=/path/to/ld.lld \
          --sysroot=/path/to/sysroot"

LDFLAGS="--ld-path=/path/to/ld.lld \
         --target=aarch64-linux-ohos \
         --sysroot=/path/to/sysroot"

3. 问题排查与解决

3.1 问题一：工具集版本错误

错误信息:

复制代码

error: arm64 in arm64 is not a number

原因分析 :

在 user-config.jam 中，工具集版本被错误地设置为 arm64，而 Boost.Build 期望的是数字版本号。

解决方案 :

使用空版本号，让 Boost.Build 使用我们指定的完整编译器路径：

jam 复制代码

# user-config.jam
using clang : : /path/to/clang++ 
    : <cxxflags>"${CXXFLAGS}"
      <linkflags>"${LDFLAGS}"
      <archiver>${AR}
      <ranlib>${RANLIB}
    ;

对应的构建选项：

bash 复制代码

BJAM_OPTIONS="toolset=clang"

3.2 问题二：编译器查找失败

错误信息:

复制代码

error: toolset clang-darwin initialization: version '1.0' requested but 
'clang++-1.0' not found and version '16.0.0' of default 'clang++' does not match.

原因分析 :

Boost.Build 尝试查找版本化的编译器（如 clang++-1.0），但我们的交叉编译器是完整路径，不存在版本化的可执行文件。

解决方案 :

在 user-config.jam 中使用空版本号（冒号后直接跟编译器路径），这样 Boost.Build 会使用我们指定的完整路径，而不是尝试查找版本化的编译器。

3.3 问题三：boost-install.jam 缺失

错误信息:

复制代码

[errno 2] boost-install.jam (No such file or directory)

原因分析 :
tools/boost_install 子模块未初始化，导致 boost-install.jam 文件不存在。

解决方案 :

在构建脚本中添加子模块初始化逻辑：

bash 复制代码

# 检查并初始化 git 子模块
if [ ! -f "tools/build/src/engine/build.sh" ] || \
   [ ! -d "libs/config/checks/architecture" ] || \
   [ ! -f "tools/boost_install/boost-install.jam" ]; then
    echo "Initializing git submodules..."
    if [ -d ".git" ]; then
        git submodule update --init --recursive \
            tools/build libs/config tools/boost_install 2>/dev/null || {
            # 如果 git submodule 失败，尝试直接克隆官方仓库
            if [ ! -d "tools/build" ]; then
                git clone https://github.com/boostorg/build.git tools/build
            fi
            if [ ! -d "libs/config" ]; then
                git clone https://github.com/boostorg/config.git libs/config
            fi
            if [ ! -d "tools/boost_install" ]; then
                git clone https://github.com/boostorg/boost_install.git tools/boost_install
            fi
        }
    fi
fi

3.4 问题四：libs/config 子模块缺失

错误信息:

复制代码

error: Unable to load Jamfile. Could not find a Jamfile in directory 
'libs/config/checks/architecture'.

原因分析 :
libs/config 子模块未正确初始化，导致 libs/config/checks/architecture 目录不存在。

解决方案 :

在子模块初始化逻辑中确保 libs/config 被正确克隆和初始化。

3.5 问题五：/boost/headers 项目未定义

错误信息:

复制代码

error: Unable to find file or target named '/boost/headers' referred to 
from project at 'libs/config'.

原因分析 :
libs/config/checks/architecture/Jamfile.jam 中定义了隐式依赖：

jam 复制代码

project /boost/architecture
    : requirements
      -<conditional>@boostcpp.deduce-address-model
      -<conditional>@boostcpp.deduce-architecture
      -<implicit-dependency>/boost//headers
    ;

但 Jamroot 中没有定义 /boost/headers 项目。

解决方案 :

在 Jamroot 中添加 /boost/headers 项目定义：

bash 复制代码

# 在 build_ohos.sh 中添加
if ! grep -q "use-project /boost/headers" Jamroot 2>/dev/null; then
    echo "Adding /boost/headers project definition to Jamroot..."
    sed -i.bak '/use-project \/boost\/architecture : libs\/config\/checks\/architecture ;/a\
\
# Temporary fix: define /boost/headers project required by libs/config\
use-project /boost/headers : . ;\
' Jamroot || {
        # 备用方法：在文件末尾添加
        cat >> Jamroot << 'EOF'

# Temporary fix: define /boost/headers project required by libs/config
use-project /boost/headers : . ;
EOF
    }
fi

对应的 Jamroot 修改：

jam 复制代码

use-project /boost/architecture : libs/config/checks/architecture ;

# Temporary fix: define /boost/headers project required by libs/config
use-project /boost/headers : . ;

3.6 问题六：构建顺序问题

问题描述 :

即使添加了 /boost/headers 项目定义，仍然出现找不到该目标的错误。

原因分析 :
/boost/headers 目标需要先被构建才能被其他项目引用。虽然 Jamroot 中定义了 headers 目标：

jam 复制代码

generate headers : $(all-headers)-headers : 
    <generating-rule>@generate-alias <action>@do-nothing : : <include>.  ;
explicit headers ;

但这个目标需要在构建过程中被显式调用才能创建。

解决方案 :

在构建 install 目标之前，先使用交叉编译工具链构建 headers 目标：

bash 复制代码

# 先使用默认工具链生成 headers（配置检查）
if [ -z "${CC}" ]; then
    ./b2 headers || echo "Warning: b2 headers failed"
else
    # 临时取消交叉编译环境变量
    SAVE_CC="${CC}"
    SAVE_CXX="${CXX}"
    unset CC CXX CFLAGS CXXFLAGS LDFLAGS
    ./b2 headers || echo "Warning: b2 headers failed"
    export CC="${SAVE_CC}"
    export CXX="${SAVE_CXX}"
fi

# 修复 Jamroot 添加 /boost/headers 项目定义
# ... (见问题五的解决方案)

# 使用交叉编译工具链构建 headers
echo "Building Boost headers with cross-compilation toolchain..."
./b2 ${BJAM_OPTIONS} headers -j$(sysctl -n hw.ncpu 2>/dev/null || echo 4) || {
    echo "Warning: b2 headers failed, continuing anyway..."
}

# 然后构建和安装所有库
echo "Building and installing Boost libraries..."
./b2 ${BJAM_OPTIONS} install -j$(sysctl -n hw.ncpu 2>/dev/null || echo 4)

4. 最终构建脚本

完整的构建脚本 build_ohos.sh 包含以下关键步骤：

4.1 子模块初始化

bash 复制代码

# 检查并初始化必要的子模块
if [ ! -f "tools/build/src/engine/build.sh" ] || \
   [ ! -d "libs/config/checks/architecture" ] || \
   [ ! -f "tools/boost_install/boost-install.jam" ]; then
    # 初始化子模块逻辑
fi

4.2 Bootstrap b2 工具

bash 复制代码

if [ ! -f "./b2" ]; then
    ./bootstrap.sh --with-toolset=clang || exit 1
fi

4.3 生成 Headers

bash 复制代码

# 使用默认工具链生成 headers（配置检查）
./b2 headers || echo "Warning: b2 headers failed"

4.4 修复 Jamroot

bash 复制代码

# 添加 /boost/headers 项目定义
if ! grep -q "use-project /boost/headers" Jamroot 2>/dev/null; then
    sed -i.bak '/use-project \/boost\/architecture/a\
use-project /boost/headers : . ;\
' Jamroot
fi

4.5 配置交叉编译工具链

bash 复制代码

# 创建 user-config.jam
cat > user-config.jam << EOF
using clang : : ${CXX} 
    : <cxxflags>"${CXXFLAGS}"
      <linkflags>"${LDFLAGS}"
      <archiver>${AR}
      <ranlib>${RANLIB}
    ;
EOF

BJAM_OPTIONS="--prefix=${PREFIX}"
BJAM_OPTIONS="${BJAM_OPTIONS} --libdir=${PREFIX}/lib"
BJAM_OPTIONS="${BJAM_OPTIONS} --includedir=${PREFIX}/include"
BJAM_OPTIONS="${BJAM_OPTIONS} link=static"
BJAM_OPTIONS="${BJAM_OPTIONS} variant=release"
BJAM_OPTIONS="${BJAM_OPTIONS} threading=multi"
BJAM_OPTIONS="${BJAM_OPTIONS} runtime-link=static"
BJAM_OPTIONS="${BJAM_OPTIONS} architecture=arm"
BJAM_OPTIONS="${BJAM_OPTIONS} address-model=64"
BJAM_OPTIONS="${BJAM_OPTIONS} toolset=clang"

4.6 构建和安装

bash 复制代码

# 使用交叉编译工具链构建 headers
./b2 ${BJAM_OPTIONS} headers -j$(sysctl -n hw.ncpu 2>/dev/null || echo 4)

# 构建和安装所有库
./b2 ${BJAM_OPTIONS} install -j$(sysctl -n hw.ncpu 2>/dev/null || echo 4)

5. HNP 包配置

创建 hnp.json 配置文件：

json 复制代码

{
    "type": "hnp-config",
    "name": "boost",
    "version": "1.83.0",
    "install": {}
}

6. 构建结果

成功构建后，生成以下内容：

复制代码

boost_1.83.0/
├── include/
│   └── boost/          # 所有 Boost 头文件
├── lib/
│   ├── cmake/          # CMake 配置文件
│   └── *.a             # 静态库文件（如需要）
└── hnp.json            # HNP 包配置

7. 关键要点总结

7.1 Boost.Build 工具链配置

使用空版本号 : 在 user-config.jam 中使用空版本号，让 Boost.Build 使用完整路径
工具集名称 : 使用 toolset=clang 而不是 toolset=clang-1.0
编译器路径 : 在 user-config.jam 中指定完整的交叉编译器路径

7.2 子模块管理

必需子模块 : tools/build, libs/config, tools/boost_install
初始化顺序: 在 bootstrap 之前初始化子模块
备用方案 : 如果 git submodule 失败，直接从官方仓库克隆

7.3 项目依赖处理

/boost/headers 项目 : 需要在 Jamroot 中显式定义
构建顺序 : 先构建 headers 目标，再构建 install 目标
工具链一致性 : 使用交叉编译工具链构建 headers，确保依赖关系正确

7.4 构建选项

静态链接 : link=static, runtime-link=static
架构设置 : architecture=arm, address-model=64
变体 : variant=release, threading=multi
并行构建 : 使用 -j 选项加速构建

8. 常见问题

Q1: 为什么需要先构建 headers？

A: libs/config 等子项目依赖 /boost/headers 项目，该项目需要在构建过程中被创建。先构建 headers 目标可以确保这个依赖关系被正确建立。

Q2: 为什么要在 Jamroot 中添加 /boost/headers 项目定义？

A: libs/config/checks/architecture/Jamfile.jam 中定义了隐式依赖 -<implicit-dependency>/boost//headers，但 Jamroot 中没有定义这个项目。添加项目定义可以让 Boost.Build 正确解析这个依赖。

Q3: 为什么使用空版本号？

A: Boost.Build 会尝试查找版本化的编译器（如 clang++-1.0），但我们的交叉编译器是完整路径，不存在版本化的可执行文件。使用空版本号可以让 Boost.Build 直接使用我们指定的完整路径。

Q4: 如何处理子模块初始化失败？

A: 如果 git submodule update 失败，脚本会尝试直接从 GitHub 官方仓库克隆所需的子模块。这确保了即使子模块配置有问题，也能正常构建。

9. 参考资源

10. 版本信息

Boost 版本: 1.83.0
构建日期: 2026年
目标平台: HarmonyOS PC (ARM64)
构建平台: macOS (ARM64)
工具链: HarmonyOS SDK LLVM