Electron 源码学习（1）：从源码构建-五八三

想要了解 Electron 的运行原理，方法有很多，其中最有效的方法，就是读 Electron 的源码。在我们读源码的时候，可能会尝试通过修改或添加代码来验证代码的功能，这就需要我们掌握从源码构建 Electron 的能力。

具体地，我们需要掌握以下 2 个基础能力：

拉取、同步 Electron 所有源码的能力；
从源码本地构建 Electron 的能力。

对于一些中小型项目，要达成以上 2 个目标，通常只需要 1~2 条命令，而对于 Electron 这种大型项目显然不适合。

本文以 Windows 平台为例，介绍如何在本地搭建 Electron 开发环境。

准备开发环境

以下要求来自官方文档，本文可能不会及时同步官方文档，无法保证其时效性。关于最新的要求，最好直接查看官方文档

Windows 10 / Server 2012 R2 或更高版本
Visual Studio 2019 (>=16.0.0) 或更高版本，推荐 Visual Studio 2022 (>=17.0.0)
- 请参阅 Chromium 构建文档，以了解有哪些 Visual Studio 组件需要安装等详细信息。
- 如果你的 Visual Studio 安装在非默认目录中，你需要设置几个环境变量来将工具链指向你的安装路径。
  - vs2022_install = DRIVE:\path\to\Microsoft Visual Studio\2022\Community，用你当前已安装版本替换 2022 和 Community 以及用你当前安装 Visual Studio 的驱动器号替换 DRIVE: 一般情况下将会是 C:。
  - WINDOWSSDKDIR = DRIVE:\path\to\Windows Kits\10, replacing DRIVE: with the drive that Windows Kits is on. 一般情况下将会是 C:。
Node.js
Git

截至 2023/7/10，本文所使用的开发环境如下：

Windows 10 – 版本 22H2 专业版 64 位
Visual Studio Community 2022 (64 位) – 版本 17.6.4
Node.js – 版本 v16.17.1
Git – 版本 2.33.0.windows.2

拉取源码和构建

Electron 依赖 chromium 和 Node.js 两个项目，所以想构建 Electron 项目，除了拉取 Electron 本身的代码之外，还要拉取其依赖（以及依赖的依赖）的代码，而 chromium 本身就是一个极其复杂的大项目，有自己的一套拉取代码和构建项目的工具。

要学习这些工具的使用需要耗费不少的时间，这些对于 Electron 的源码学习前期是没有必要的。为了简化 Electron 的构建，官方把这些依赖的工具全部打包成另一个工具 @electron/build-tools，使用打包后的工具进行代码拉取和构建项目将会简单很多。

下面分别介绍使用和不使用 @electron/build-tools 两种方式进行构建的步骤。

方法1：使用自动化工具 @electron/build-tools

构建步骤

安装自动化工具 @electron/build-tools

npm i -g @electron/build-tools

初始化并生成配置

e init oh_my_electron -i testing --r D:\source\electron

其中，oh_my_electron 是自定义的配置名称，你可以使用任意你喜欢的名称，随后你可以在 C:\Users\<username>\.electron_build_tools\configs 找到与该名称对应的配置文件；-i testing 表示导入的构建配置，默认是 testing；-r D:\\electron_source 表示存放源码的根目录，必须指定空目录。

同步代码

e sync

开始构建

e build

`e` 命令的功能和参数简介

e 命令实际上整合了 gclient、git、ninja 等多个工具以简化了工作流，简化后的 e 命令的工作流：初始化配置（e init） -> 同步代码（e sync） -> 构建（e build）

e-init [options] <name>

参数	说明
`-r, --root <path>`	源码根目录路径，一定要使用空目录
`-i, --import <name>`	从 $root/src/electron/build/args/$import.gn 导入配置文件
`-o, --out <name>`	输出目录名称，即 $root/src/out/$out

想了解更多关于 @electron/build-tools 的使用方法，详见 Electron Build Tools

方法2：手动安装和构建

通常情况下，更推荐使用方法1，免去手动安装和学习使用各种工具的麻烦，除非：

你已经安装了相关的工具，并且非常熟悉这些工具的使用方式；
你本地有其它项目（例如 chromium）也在使用这些工具。

构建步骤：

下载 depot_tools，解压到 D:\tools\depot_tools；如果下载链接已失效，请前往官方站点查找最新的下载地址。
设置环境变量
1. 新增 DEPOT_TOOLS_WIN_TOOLCHAIN 环境变量，值为 0，以确保 depot_tools 使用本地版本的 Visual Studio；
2. 把 D:\tools\depot_tools 添加到 PATH 环境变量，以确保命令行能够访问 gn、gclient 等命令；
3. 新增 GIT_CACHE_PATH 环境变量，值为 D:\cache\.git_cache，以加速后续 gclient 的调用。
拉取代码
1. 创建一个空目录作为源码的根目录，例如：D:\source\electron
2. 从命令行进入你刚刚创建的目录，例如：cd D:\source\electron
3. 运行 gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
4. 继续运行 gclient sync --with_branch_heads --with_tags
生成配置文件以准备构建
1. 从命令行进入源码的 src 目录，例如 cd D:\source\electron\src
2. 命令行设置临时环境变量 set CHROMIUM_BUILDTOOLS_PATH=%cd%\buildtools
3. 运行 gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")" 以生成 gn 配置文件
  1. 注意 out/Testing 是自定义的输出目录，Testing 可以改为其它名称
  2. import(\"//electron/build/args/testing.gn\") 将会导入构建配置文件，你可以换成其它的配置文件，例如 import(\"//electron/build/args/release.gn\")，各个配置文件的差异请前往 D:\source\electron\src\electron\build\args 目录查看
构建
1. 从命令行进入源码的 src 目录，例如 cd D:\source\electron\src
2. 运行 ninja -C out/Testing electron

问题备忘录

1. git 全局配置被修改

运行 e init 的时候会提示修改 git 的全局设置（设置文件在 C:\Users\<username>\.gitconfig）：

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

这是 chromium 仓库要求的，如果不设置无法成功拉取 chromium 的源码。问题是我们本地的其它项目通常不需要这几个设置，而 e 命令并不会帮我们改回来，所以当我们在 Electron 和其它项目之间切换时，记得手动改回去。

详见：

2. invalid continuation byte

运行 e build 的时候报错 invalid continuation byte

这是编码问题，使用代码编辑器打开 C:\Users\<username>\.electron_build_tools\third_party\goma\goma_ctl.py 文件，把 return data.decode('utf-8') 改为 return data.decode('gb18030')

详见：