Windows 使用 GCC/MinGW-w64 编译 Boost 小记

前言

本文记录在 Windows 下使用 GCC/MinGW-w64 编译 Boost 静态库的流程。示例以 Boost 1.88.0 为例，编译目标为 Windows x86_64 和 x86 两种架构。

1. 背景说明

Windows 下常见的 Boost 编译方式有两类：

编译器	典型产物	适用场景
MSVC / v142 / v143	.lib	Visual Studio/MSVC 工程
GCC / MinGW-w64	.a	MinGW、Qt MinGW、GCC 工具链工程

需要注意：

• MSVC 编译出来的 .lib 和 MinGW GCC 编译出来的 .a 不建议混用；
• C++ ABI、异常、运行库、标准库实现都不同；
• 如果你的最终工程使用 MinGW GCC 编译，那么 Boost 也应该使用 MinGW GCC 编译；
• 如果最终工程使用 MSVC 编译，则应该使用 MSVC 编译 Boost。

本文只讨论 Windows 目标平台，不是 Linux 交叉编译。

2. 准备 MinGW-w64 工具链

假设已经安装了 64 位 MinGW-w64，路径为：

D:\Installed_Files\mingw64\bin

其中应该至少包含：

g++.exe
gcc.exe
ar.exe
ranlib.exe
windres.exe

3. 准备 Boost

以 Boost 1.88.0 为例，解压后进入 Boost 根目录，例如：

cd D:\workspace\local\boost\boost_1_88_0\boost_1_88_0

生成 b2.exe：

切换到 Boost 根目录，运行引导脚本：

cd D:\workspace\boost_1_88_0
.\bootstrap.bat vc142

执行成功后，根目录下会出现 b2.exe。

注意：此处的 vc142 仅用于编译 b2.exe 本身（Windows 原生工具），与后续 macOS 交叉编译无关。

4. 编写 user-config.jam

在 Boost 根目录创建 user-config.jam：

import os ;

mingw64Root = D:/Installed_Files/mingw64 ;
mingw64Bin = $(mingw64Root)/bin ;

# Windows x86_64, MinGW-w64 GCC.
using gcc : mingw_x86_64 :
    $(mingw64Bin)/g++.exe
    :
    <compileflags>-m64
    <linkflags>-m64
    <define>_WIN32_WINNT=0x0601
    <archiver>$(mingw64Bin)/ar.exe
    <ranlib>$(mingw64Bin)/ranlib.exe
    <rc>$(mingw64Bin)/windres.exe
    ;

# Windows x86, MinGW-w64 GCC.
using gcc : mingw_x86 :
    $(mingw64Bin)/g++.exe
    :
    <compileflags>-m32
    <linkflags>-m32
    <define>_WIN32_WINNT=0x0601
    <archiver>$(mingw64Bin)/ar.exe
    <ranlib>$(mingw64Bin)/ranlib.exe
    <rc>$(mingw64Bin)/windres.exe
    ;

5. 编译 Windows x86_64 版本

管理员打开 PowerShell，切换到 Boost 根目录：

cd D:\workspace\local\boost\boost_1_88_0\boost_1_88_0

执行：

.\b2 -q -j8 -a -d+2 --debug-configuration `
  --user-config=.\user-config.jam `
  toolset=gcc-mingw_x86_64 `
  target-os=windows architecture=x86 address-model=64 abi=ms binary-format=pe `
  threadapi=win32 threading=multi link=static runtime-link=static variant=release cxxstd=14 `
  --without-python `
  --stagedir=stage/windows/mingw-gcc/x86_64/release stage `
  2>&1 | Tee-Object -FilePath build-mingw-gcc-x86_64-release.log

编译完成后，产物目录为：

stage\windows\mingw-gcc\x86_64\release\lib

6. 编译 Windows x86 版本

执行：

.\b2 -q -j8 -a -d+2 --debug-configuration `
  --user-config=.\user-config.jam `
  toolset=gcc-mingw_x86 `
  target-os=windows architecture=x86 address-model=32 abi=ms binary-format=pe `
  threadapi=win32 threading=multi link=static runtime-link=static variant=release cxxstd=14 `
  --without-python `
  --stagedir=stage/windows/mingw-gcc/x86/release stage `
  2>&1 | Tee-Object -FilePath .\build-mingw-gcc-x86-release.log

编译完成后，产物目录为：

stage\windows\mingw-gcc\x86\release\lib

7. 参数说明

7.1 toolset=gcc-mingw_x86_64

对应 user-config.jam 中的：

using gcc : mingw_x86_64 : ... ;

Boost.Build 的规则是：

toolset=gcc-版本名

所以 mingw_x86_64 对应 gcc-mingw_x86_64。

7.2 target-os=windows

表示目标系统是 Windows。

7.3 architecture=x86 address-model=64

Windows x64 使用：

architecture=x86 address-model=64

Windows x86 使用：

architecture=x86 address-model=32

这里的 architecture=x86 表示 x86 系列架构，不是只代表 32 位。真正区分 32/64 位的是 address-model。

7.4 abi=ms binary-format=pe

MinGW-w64 的目标也是 Windows PE 格式，所以使用：

abi=ms binary-format=pe

7.5 threadapi=win32

Windows 平台使用 Win32 线程 API：

threadapi=win32

不要写成 Linux/Android 常用的：

threadapi=pthread

7.6 link=static runtime-link=static

含义如下：

link=static          编译 Boost 静态库
runtime-link=static  尽量静态链接 GCC 运行库、C++ 运行库

这两个参数不是一回事。

如果你的项目希望依赖 MinGW 的动态运行库，也可以改成：

runtime-link=shared

但分发时需要同时带上对应的 MinGW runtime DLL。

7.7 --without-python

如果不需要 Boost.Python，建议跳过：

--without-python

原因是 Boost.Python 对 Python 头文件、库文件、ABI 都比较敏感。对于纯 C++ 静态库分发场景，通常没有必要编译它。

7.8 -d+2 --debug-configuration

这是可选的调试日志参数：

-d+2 --debug-configuration

建议首次配置工具链时保留。它可以帮助确认 Boost.Build 实际使用的是哪一个 g++.exe、ar.exe、ranlib.exe 和 windres.exe。

配置稳定后，如果嫌日志太多，可以去掉。

8. 只编译常用库

如果不想编译全部 Boost 库，可以用 --with-xxx 限定范围，例如：

.\b2 -q -j8 -a `
  --user-config=.\user-config.jam `
  toolset=gcc-mingw_x86_64 `
  target-os=windows architecture=x86 address-model=64 abi=ms binary-format=pe `
  threadapi=win32 threading=multi link=static runtime-link=static variant=release cxxstd=14 `
  --without-python `
  --with-atomic --with-chrono --with-container --with-date_time `
  --with-filesystem --with-system --with-thread --with-regex `
  --stagedir=stage/windows/mingw-gcc/x86_64/release stage

常用库一般包括：

atomic
chrono
container
date_time
filesystem
system
thread
regex

具体要不要编译 locale、iostreams、program_options 等库，取决于项目实际使用情况。

9. Debug 版本

如果需要 debug 版本，把：

variant=release

改成：

variant=debug

例如 x86_64 debug：

.\b2 -q -j8 -a -d+2 --debug-configuration `
  --user-config=.\user-config.jam `
  toolset=gcc-mingw_x86_64 `
  target-os=windows architecture=x86 address-model=64 abi=ms binary-format=pe `
  threadapi=win32 threading=multi link=static runtime-link=static variant=debug cxxstd=14 `
  --without-python `
  --stagedir=stage/windows/mingw-gcc/x86_64/debug stage `
  2>&1 | Tee-Object -FilePath .\build-mingw-gcc-x86_64-debug.log

建议 debug 和 release 放到不同目录：

stage\windows\mingw-gcc\x86_64\debug
stage\windows\mingw-gcc\x86_64\release

这样最清晰，也避免误链接。