Build Instructions
请遵循以下指南来构建Electron。
Follow the guidelines below for building Electron.
平台要求
各个平台所对应的构建要求如下:
- macOS
- Linux
- Windows
Platform prerequisites
Check the build prerequisites for your platform before proceeding
- macOS
- Linux
- Windows
前置知识
此外,你还需要安装depot_tools
,这是一个用于获取Chromium,及其相关依赖工具。
另外,如果使用Windows系统, 你需要设置环境变量DEPOT_TOOLS_WIN_TOOLCHAIN=0
。 依次打开 Control Panel
→ System and Security
→ System
→ Advanced system settings
,然后添加系统变量 DEPOT_TOOLS_WIN_TOOLCHAIN
,并设置默认值为 0
. 这将促使depot_tools
使用本地已安装的Visual Studio(默认状态下,depot_tools
将会下载一个只有谷歌内部员工有权限使用的内部版本)。
GN prerequisites
You'll need to install depot_tools
, the toolset used for fetching Chromium and its dependencies.
Also, on Windows, you'll need to set the environment variable DEPOT_TOOLS_WIN_TOOLCHAIN=0
. To do so, open Control Panel
→ System and Security
→ System
→ Advanced system settings
and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN
with value 0
. This tells depot_tools
to use your locally installed version of Visual Studio (by default, depot_tools
will try to download a Google-internal version that only Googlers have access to).
Cached builds (optional step)
Cached builds (optional step)
GIT_CACHE_PATH
If you plan on building Electron more than once, adding a git cache will speed up subsequent calls to gclient
. To do this, set a GIT_CACHE_PATH
environment variable:
$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# This will use about 16G.
GIT_CACHE_PATH
If you plan on building Electron more than once, adding a git cache will speed up subsequent calls to gclient
. To do this, set a GIT_CACHE_PATH
environment variable:
$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# This will use about 16G.
sccache
Thousands of files must be compiled to build Chromium and Electron. You can avoid much of the wait by reusing Electron CI's build output via sccache. This requires some optional steps (listed below) and these two environment variables:
export SCCACHE_BUCKET="electronjs-sccache"
export SCCACHE_TWO_TIER=true
sccache
Thousands of files must be compiled to build Chromium and Electron. You can avoid much of the wait by reusing Electron CI's build output via sccache. This requires some optional steps (listed below) and these two environment variables:
export SCCACHE_BUCKET="electronjs-sccache"
export SCCACHE_TWO_TIER=true
Getting the code
$ mkdir electron-gn && cd electron-gn
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# This will take a while, go get a coffee.
Instead of
https://github.com/electron/electron
, you can use your own fork here (something likehttps://github.com/<username>/electron
).
Getting the code
$ mkdir electron-gn && cd electron-gn
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# This will take a while, go get a coffee.
Instead of
https://github.com/electron/electron
, you can use your own fork here (something likehttps://github.com/<username>/electron
).
A note on pulling/pushing
If you intend to git pull
or git push
from the official electron
repository in the future, you now need to update the respective folder's origin URLs.
$ cd src/electron
$ git remote remove origin
$ git remote add origin https://github.com/electron/electron
$ git branch --set-upstream-to=origin/master
$ cd -
gclient
works by checking a file called DEPS
inside the src/electron
folder for dependencies (like Chromium or Node.js). Running gclient sync -f
ensures that all dependencies required to build Electron match that file.
So, in order to pull, you'd run the following commands:
$ cd src/electron
$ git pull
$ gclient sync -f
A note on pulling/pushing
If you intend to git pull
or git push
from the official electron
repository in the future, you now need to update the respective folder's origin URLs.
$ cd src/electron
$ git remote remove origin
$ git remote add origin https://github.com/electron/electron
$ git branch --set-upstream-to=origin/master
$ cd -
gclient
works by checking a file called DEPS
inside the src/electron
folder for dependencies (like Chromium or Node.js). Running gclient sync -f
ensures that all dependencies required to build Electron match that file.
So, in order to pull, you'd run the following commands:
$ cd src/electron
$ git pull
$ gclient sync -f
构建
$ cd src
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools
# this next line is needed only if building with sccache
$ export GN_EXTRA_ARGS="${GN_EXTRA_ARGS} cc_wrapper="${PWD}/electron/external_binaries/sccache""
$ gn gen out/Debug --args="import("//electron/build/args/debug.gn") $GN_EXTRA_ARGS"
Or on Windows (without the optional argument):
$ cd src
$ set CHROMIUM_BUILDTOOLS_PATH=%cd%buildtools
$ gn gen out/Debug --args="import("//electron/build/args/debug.gn")"
This will generate a build directory out/Debug
under src/
with debug build configuration. You can replace Debug
with another name, but it should be a subdirectory of out
. Also you shouldn't have to run gn gen
again—if you want to change the build arguments, you can run gn args out/Debug
to bring up an editor.
To see the list of available build configuration options, run gn args out/Debug --list
.
For generating Debug (aka "component" or "shared") build config of Electron:
$ gn gen out/Debug --args="import("//electron/build/args/debug.gn") $GN_EXTRA_ARGS"
For generating Release (aka "non-component" or "static") build config of Electron:
$ gn gen out/Release --args="import("//electron/build/args/release.gn") $GN_EXTRA_ARGS"
To build, run ninja
with the electron
target: Nota Bene: This will also take a while and probably heat up your lap.
For the debug configuration:
$ ninja -C out/Debug electron
For the release configuration:
$ ninja -C out/Release electron
这个过程会构建 'libchromiumcontent' 里的所有内容,(如chromium
中的content
,及其依赖(包括Webkit 和 V8))。因此,这个构建过程会比较费时。
你可以使用sccache命令来提高后面的构建过程。 Add the GN arg cc_wrapper = "sccache"
by running gn args out/Debug
to bring up an editor and adding a line to the end of the file.
The built executable will be under ./out/Debug
:
$ ./out/Debug/Electron.app/Contents/MacOS/Electron
# or, on Windows
$ ./out/Debug/electron.exe
# or, on Linux
$ ./out/Debug/electron
Building
$ cd src
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools
# this next line is needed only if building with sccache
$ export GN_EXTRA_ARGS="${GN_EXTRA_ARGS} cc_wrapper="${PWD}/electron/external_binaries/sccache""
$ gn gen out/Debug --args="import("//electron/build/args/debug.gn") $GN_EXTRA_ARGS"
Or on Windows (without the optional argument):
$ cd src
$ set CHROMIUM_BUILDTOOLS_PATH=%cd%buildtools
$ gn gen out/Debug --args="import("//electron/build/args/debug.gn")"
This will generate a build directory out/Debug
under src/
with debug build configuration. You can replace Debug
with another name, but it should be a subdirectory of out
. Also you shouldn't have to run gn gen
again—if you want to change the build arguments, you can run gn args out/Debug
to bring up an editor.
To see the list of available build configuration options, run gn args out/Debug --list
.
For generating Debug (aka "component" or "shared") build config of Electron:
$ gn gen out/Debug --args="import("//electron/build/args/debug.gn") $GN_EXTRA_ARGS"
For generating Release (aka "non-component" or "static") build config of Electron:
$ gn gen out/Release --args="import("//electron/build/args/release.gn") $GN_EXTRA_ARGS"
To build, run ninja
with the electron
target: Nota Bene: This will also take a while and probably heat up your lap.
For the debug configuration:
$ ninja -C out/Debug electron
For the release configuration:
$ ninja -C out/Release electron
This will build all of what was previously 'libchromiumcontent' (i.e. the content/
directory of chromium
and its dependencies, incl. WebKit and V8), so it will take a while.
To speed up subsequent builds, you can use sccache. Add the GN arg cc_wrapper = "sccache"
by running gn args out/Debug
to bring up an editor and adding a line to the end of the file.
The built executable will be under ./out/Debug
:
$ ./out/Debug/Electron.app/Contents/MacOS/Electron
# or, on Windows
$ ./out/Debug/electron.exe
# or, on Linux
$ ./out/Debug/electron
打包
On linux, first strip the debugging and symbol information:
electron/script/strip-binaries.py -d out/Release
To package the electron build as a distributable zip file:
ninja -C out/Release electron:electron_dist_zip
Packaging
On linux, first strip the debugging and symbol information:
electron/script/strip-binaries.py -d out/Release
To package the electron build as a distributable zip file:
ninja -C out/Release electron:electron_dist_zip
交叉编译
To compile for a platform that isn't the same as the one you're building on, set the target_cpu
and target_os
GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = "x86"
in gn args
.
$ gn gen out/Debug-x86 --args='... target_cpu = "x86"'
Not all combinations of source and target CPU/OS are supported by Chromium.
Host | Target | 状态 |
---|---|---|
Windows x64 | Windows arm64 | 实验功能 |
Windows x64 | Windows x86 | Automatically tested |
Linux x64 | Linux x86 | Automatically tested |
If you test other combinations and find them to work, please update this document :)
See the GN reference for allowable values of target_os
and target_cpu
.
Windows on Arm (experimental)
To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1
in your environment before running gclient sync
.
set ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags
Or (if using PowerShell):
$env:ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags
Next, run gn gen
as above with target_cpu="arm64"
.
测试
To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under src/
directory.
$ ninja -C out/Debug third_party/electron_node:headers
Cross-compiling
To compile for a platform that isn't the same as the one you're building on, set the target_cpu
and target_os
GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = "x86"
in gn args
.
$ gn gen out/Debug-x86 --args='... target_cpu = "x86"'
Not all combinations of source and target CPU/OS are supported by Chromium.
Host | Target | Status |
---|---|---|
Windows x64 | Windows arm64 | Experimental |
Windows x64 | Windows x86 | Automatically tested |
Linux x64 | Linux x86 | Automatically tested |
If you test other combinations and find them to work, please update this document :)
See the GN reference for allowable values of target_os
and target_cpu
.
Install the test modules with the generated headers
$ (cd electron/spec && npm i --nodedir=../../out/Debug/gen/node_headers)
<p>
接着,通过<code>electron/spec</code>命令来运行Electron:
</p>
<pre><code class="sh"># on Mac:
$ ./out/Debug/Electron.app/Contents/MacOS/Electron electron/spec
Windows on Arm (experimental)
To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1
in your environment before running gclient sync
.
set ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags
Or (if using PowerShell):
$env:ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags
Next, run gn gen
as above with target_cpu="arm64"
.
on Windows:
$ ./out/Debug/electron.exe electron/spec
Tests
To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under src/
directory.
$ ninja -C out/Debug third_party/electron_node:headers
# Install the test modules with the generated headers
$ (cd electron/spec && npm i --nodedir=../../out/Debug/gen/node_headers)
Then, run Electron with electron/spec
as the argument:
# on Mac:
$ ./out/Debug/Electron.app/Contents/MacOS/Electron electron/spec
# on Windows:
$ ./out/Debug/electron.exe electron/spec
# on Linux:
$ ./out/Debug/electron electron/spec
If you're debugging something, it can be helpful to pass some extra flags to the Electron binary:
$ ./out/Debug/Electron.app/Contents/MacOS/Electron electron/spec
--ci --enable-logging -g 'BrowserWindow module'
on Linux:
$ ./out/Debug/electron electron/spec
<p>
可以通过增加其它标记来调试程序,例如:
</p>
<pre><code class="sh">$ ./out/Debug/Electron.app/Contents/MacOS/Electron electron/spec
--ci --enable-logging -g 'BrowserWindow module'
<h2>
Sharing the git cache between multiple machines
</h2>
<p>
It is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.
</p>
<p>
On Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key
</p>
<pre><code class="sh">HKEY_LOCAL_MACHINESystemCurrentControlSetServicesLanmanworkstationParametersDirectoryCacheLifetime
<p>
to 0. More information: https://stackoverflow.com/a/9935126
</p>
<p>
This can be set quickly in powershell (ran as administrator):
</p>
<pre><code class="powershell">New-ItemProperty -Path "HKLM:SystemCurrentControlSetServicesLanmanworkstationParameters" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force
<h2>
故障排查
</h2>
<h3>
Stale locks in the git cache
</h3>
<p>
If <code>gclient sync</code> is interrupted while using the git cache, it will leave the cache locked. To remove the lock, pass the <code>--break_repo_locks</code> argument to <code>gclient sync</code>.
</p>
<h3>
I'm being asked for a username/password for chromium-internal.googlesource.com
</h3>
<p>
If you see a prompt for <code>Username for 'https://chrome-internal.googlesource.com':</code> when running <code>gclient sync</code> on Windows, it's probably because the <code>DEPOT_TOOLS_WIN_TOOLCHAIN</code> environment variable is not set to 0. Open <code>Control Panel</code> → <code>System and Security</code> → <code>System</code> → <code>Advanced system settings</code> and add a system variable <code>DEPOT_TOOLS_WIN_TOOLCHAIN</code> with value <code>0</code>. 这将促使<code>depot_tools</code> 使用本地已安装的Visual Studio(默认状态下,<code>depot_tools</code>将会下载一个只有谷歌内部员工有权限使用的内部版本)。
</p>
Sharing the git cache between multiple machines
It is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.
On Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key
HKEY_LOCAL_MACHINESystemCurrentControlSetServicesLanmanworkstationParametersDirectoryCacheLifetime
to 0. More information: https://stackoverflow.com/a/9935126
This can be set quickly in powershell (ran as administrator):
New-ItemProperty -Path "HKLM:SystemCurrentControlSetServicesLanmanworkstationParameters" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force