在 Windows 上构建 Chromium 浏览器

本文是自己编译构建 Chromium 的一个记录,流程参考 Chromium 文档 Checking out and Building Chromium for Windows

准备工作

  • 24GB 内存(官方推荐 16GB 以上)
  • 100GB 以上磁盘空间,NTFS 格式
  • Visual Studio(官方推荐 Visual Studio 2019 v16.0.0+)
  • Python 3
  • Git for Windows
  • Windows 11(官方推荐 Windows 10 以上版本)
  • 良好的网络,需要能流畅访问如下域名:
    • *.appspot.com
    • *.googleapis.com
    • *.googlesource.com

代理配置可以参考《日常开发中用到的一些代理配置方式》

安装 Visual Studio 和 Python

之前《Windows 构建工具》已经安装过 Python 和 Microsoft Build Tools。如果不使用 Visual Studio 开发调试 Chromium,只安装 Build Tools 足够了。

Chromium 要求的 Desktop development with C++MFC/ATL support 组件包含在以下两个 Workload 中:

  • Desktop development with C++: Build modern C++ apps for Windows using tools of your choice, including MSVC, Clang, CMake, or MSBuild.
  • Universal Windows Platform build tools: Provides the tools required to build Universal Windows Platform applications.

Visual Studio Installer 运行时会显示为当前操作系统的语言,如果希望展示为英文,可以增加 --locale=En-us 参数,即 "C:\Program Files (x86)\Microsoft Visual Studio\Installer\setup.exe" --locale=En-us

两个 Workload 安装完后,默认包含 Windows 10 SDK (>=10.0.19041),但缺少构建 Chromium 必需的 Debug 工具。可以手动在控制面版的程序列表中找到 Windows Software Development Kit,勾选安装 Debugging Tools For Windows

安装 Git

Git for Windows 的安装过程,此处省略。安装完后进行以下配置:

$ git config --global core.autocrlf false
$ git config --global core.filemode false
$ git config --global branch.autosetuprebase always

安装 depot_tools

depot_tools 是一套用于 Chromium 开发的工具集。主要涉及以下命令:

  • fetch: 用于检出项目代码,是对 gclient 的封装。
  • gclient: 代码检出工具,类似 Android 的 repo 命令或者 git submodule
  • roll-dep: gclient 依赖管理工具。
  • git 相关命令
    • git cl: 代码评审。
    • git map: 显示 git 提交历史。
    • git rebase-update 更新所有分支代码。
    • git new-branch 创建新分支。
    • ...

depot_tools 的大部分代码使用 Python 编写,如 fetch.py,为了简化在 Linux/Windows 上的调用方式,提供同名的 Shell 脚本 fetch、Batch 脚本 fetch.bat

depot_tools 文档

depot_tools 提供了 manpages 文件,可以通过 man depot_tools 查看使用文档。对于 Windows 之类的平台,可以查看 HTML 版本:

大多数命令支持通过 help 参数查看帮助。

$ fetch --help
$ gclient help
$ git cl help

下载 depot_tools

方式一:通过 Git

$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

方式二:通过 https://storage.googleapis.com/chrome-infra/depot_tools.zip 下载代码仓库快照

depot_tools 环境变量配置

depot_tools 加到系统环境变量 PATH 中,必须要在 Python、Git 之前。

$ export PATH=/path/to/depot_tools:$PATH

配置完成后进行验证:

$ which gclient

Windows 上运行:

PS C:\> where.exe gclient

depot_tools 会尝试安装 Google 内部使用的 Visual Studio 版本,如果希望使用本机已有的 Visual Studio 工具链,可以新建 DEPOT_TOOLS_WIN_TOOLCHAIN=0 环境变量。

Chromuim 文档还推荐设置 vs2019_install 环境变量指向 Visual Studio 2019 安装路径(如 C:\Program Files (x86)\Microsoft Visual Studio\2019\Community),这里由于只安装了 Microsoft Build Tools,所以忽略。

depot_tools 使用

无论是运行 fetch 还是 gclient,都会先执行 update_depot_tools 脚本,从 https://chromium.googlesource.com/chromium/tools/depot_tools.git 更新 depot_tools,所以请确保能正常访问 chromium.googlesource.com

fetch 命令

fetch 用于拉取 Chromium 相关项目代码:

# 拉取 chromium 代码
$ fetch chromium
# 拉取 v8 代码
$ fetch v8

可拉取的项目对应 depot_tools/fetch_configs/ 下的 Python 脚本。

fetch 支持以下参数:

  • --nohooks 检出代码后不运行 hooks 脚本
  • --no-history 执行 shallow clone,不获取完整 git 提交历史

fetch chromium 为例,fetch 除了会获取 chromium 的代码,还会获取 chromium 依赖的代码。这些依赖见 DEPS 文件,如果是 CIPD 依赖,则请求 https://chrome-infra-packages.appspot.com/client 下载 CIPD 客户端,然后通过 CIPD 进行后续下载。如果无法访问会报错:

Downloading CIPD client for windows-amd64 from https://chrome-infra-packages.appspot.com/client?platform=windows-amd64&version=git_revision:8e9b0c80860d00dfe951f7ea37d74e210d376c13...
Failed to download the file, check your network connection
Retrying after a short nap...
Failed to download the file, check your network connection
Retrying after a short nap...
Failed to bootstrap or update CIPD client
Downloading CIPD client for windows-amd64 from https://chrome-infra-packages.appspot.com/client?platform=windows-amd64&version=git_revision:8e9b0c80860d00dfe951f7ea37d74e210d376c13...
Failed to download the file, check your network connection

CIPD 是什么?看官方的描述:

CIPD (Chrome Infrastructure Package Deployment) is package deployment infrastructure. It consists of a package registry and a CLI client to create, upload, download, and install packages.

翻译一下 CIPD 是 Chrome 的包部署基础设施,它由 registry 和命令行客户端组成,类似 npm registry 和 npm 命令行工具。

gclient 命令

fetch 用于检出新代码,如果因为网络问题被打断,可以使用 gclient sync 更新已有的代码库(依赖于 fetch 执行后在项目中生成的 .gclient 文件)。

这也是为什么 Chromium 的 README 写明检出源码不要用使用 git clone 的原因:

To check out the source code locally, don't use git clone! Instead, follow the instructions on how to get the code.

因为和 git clone 相比 gclient 支持断点续传、检出子模块、执行预编译 hooks。

获取 Chromium 代码

  1. 创建 chromium 目录
$ mkdir chromium && cd chromium
  1. 获取 Chromium 代码
$ fetch --no-history chromium

这样只是浅克隆,如果希望获取完整提交历史,可以后期执行 git fetch --unshallow。当然,网络和磁盘空间允许的话,也可以一次性拉取完整代码库:

$ fetch chromium

如果重复执行 fetch chromium 会给出提示:

Your current directory appears to already contain, or be part of, a checkout. "fetch" is used only to get new checkouts. Use "gclient sync" to update existing checkouts.

目前 Chromium 源码大约 22.4GB,如果中断可以执行 gclient sync 恢复。

$ gclient sync

最终 Chromium 的源码位于 chromium/src 目录下:

$ tree -a -L 1
.
├── .cipd
├── .gclient
├── .gclient_entries
└── src

编译构建 Chromium

Chromium 使用 Ninja 作为构建工具,并使用 GN 生成 .ninja 文件。GN 和 Ninja 包含在 depot_tools 中。

$ cd src
$ gn gen out/Default
$ autoninja -C out/Default chrome

Chromium 构建过程需要花费数小时,产生5万多个文件。

  • chromium 71.7 GB
  • chromium/src 22.4 GB
  • chromium/src/out 49.3 GB

编译完成后可以打开 out/Default/chrome.exe 运行预览。

chromium.png

总结

构建 Chromium 实际只需要执行如下5行命令:

$ mkdir chromium && cd chromium
$ fetch chromium
$ cd src
$ gn gen out/Default
$ autoninja -C out/Default chrome

简单的命令背后隐藏着大量的工具,有待进一步挖掘。

附录

需要代理的域名

chrome-infra-packages.appspot.com
commondatastorage.googleapis.com
android.googlesource.com
aomedia.googlesource.com
boringssl.googlesource.com
chrome-internal.googlesource.com
chromium.googlesource.com
dawn.googlesource.com
pdfium.googlesource.com
quiche.googlesource.com
skia.googlesource.com
swiftshader.googlesource.com
webrtc.googlesource.com
gn.googlesource.com
fuchsia.googlesource.com
gerrit.googlesource.com

fetch --help

$ fetch --help
usage: fetch.py [options] <config> [--property=value [--property2=value2 ...]]

This script can be used to download the Chromium sources. See
http://www.chromium.org/developers/how-tos/get-the-code
for full usage instructions.

Valid options:
   -h, --help, help   Print this message.
   --nohooks          Don\'t run hooks after checkout.
   --force            (dangerous) Don\'t look for existing .gclient file.
   -n, --dry-run      Don\'t run commands, only print them.
   --no-history       Perform shallow clones, don\'t fetch the full git history.

Valid fetch configs:
  android
  android_internal
  breakpad
  chromium
  config_util
  crashpad
  dart
  depot_tools
  devtools-frontend
  flutter
  goma_client
  gyp
  infra
  infra_internal
  inspector_protocol
  ios
  ios_internal
  nacl
  naclports
  node-ci
  pdfium
  skia
  skia_buildbot
  syzygy
  v8
  webrtc
  webrtc_android
  webrtc_ios
  website

gclient help

$ gclient help
Usage: gclient.py <command> [options]

Meta checkout dependency manager for Git.

Commands are:
  config   creates a .gclient file in the current directory
  diff     displays local diff for every dependencies
  fetch    fetches upstream commits for all modules
  flatten  flattens the solutions into a single DEPS file
  getdep   gets revision information and variable values from a DEPS file
  grep     greps through git repos managed by gclient
  help     prints list of commands or help for a specific command
  metrics  reports, and optionally modifies, the status of metric collection
  pack     generates a patch which can be applied at the root of the tree
  recurse  operates [command args ...] on all the dependencies
  revert   reverts all modifications in every dependencies
  revinfo  outputs revision info mapping for the client and its dependencies
  root     outputs the solution root (or current dir if there isn\'t one)
  runhooks runs hooks for files that have been modified in the local working copy
  setdep   modifies dependency revisions and variable values in a DEPS file
  status   shows modification status for every dependencies
  sync     checkout/update all modules
  validate validates the .gclient and DEPS syntax
  verify   verifies the DEPS file deps are only from allowed_hosts

Options:
  --version             show program\'s version number and exit
  -h, --help            show this help message and exit
  -j JOBS, --jobs=JOBS  Specify how many SCM commands can run in parallel;
                        defaults to 8 on this machine
  -v, --verbose         Produces additional output for diagnostics. Can be
                        used up to three times for more logging info.
  --gclientfile=CONFIG_FILENAME
                        Specify an alternate .gclient file
  --spec=SPEC           create a gclient file containing the provided string.
                        Due to Cygwin/Python brokenness, it can\'t contain any
                        newlines.
  --no-nag-max          Ignored for backwards compatibility.

相关链接