* build: update-external-binaries fetches sccache * build: add util.add_exec_bit in scripts/ * build: use util.add_exec_bit in create-dist * build: use util.add_exec_bit in update-external-binaries this is needed to work around a bug in python's zipfile module that doesn't preserve the exec bit https://bugs.python.org/issue18262 * fix: linting errors * build: vsts, circleci use patched sccache * build: always look for the x64 sccache as it's the only arch we have it on * fix: windows-specific errors in updaste-external-binaries * fix: tyop * fix: set SCCACHE_BUCKET, SCCACHE_TWO_TIER on circleci * fix: syntax error in circleci yaml * fix: keep churning * chore: add tracer to file downloader * docs: add sccache instructions for GN builds * build: pull down the darwin sccache on mas builds * build: use gn sync verbosely on circleci and vsts * docs: copyediting * build: remove unnecessary cache-dir arg * docs: fix shell quoting in gn build instructions * fix: invoke gclient without -verbose in circleci * refactor: remove debug tracer * fix: invoke gclient without -verbose in appveyor * fix: invoke gclient without -verbose in vsts * fix: pull add_exec_bit from correct source * fix: remove 'SCCACHE_TWO_TIER' from CI scripts * refactor: remove SCCACHE_BUCKET from ci scripts this environment variable will be set via the CI UI instead * refactor: clarify log message * fix: set SCCACHE_PATH correctly for Windows CI
6 KiB
Build Instructions (experimental GN build)
Follow the guidelines below for building Electron with the experimental GN build.
NOTE: The GN build system is in experimental status.
Platform prerequisites
Check the build prerequisites for your platform before proceeding
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)
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
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.
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/Default --args="import(\"//electron/build/args/debug.gn\") $GN_EXTRA_ARGS"
This will generate a build directory out/Default
under src/
with
debug build configuration. You can replace Default
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/Default
to bring up an editor.
To see the list of available build configuration options, run gn args out/Default --list
.
For generating Debug (aka "component" or "shared") build config of Electron:
$ gn gen out/Default --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/Default --args="import(\"//electron/build/args/release.gn\") $GN_EXTRA_ARGS"
To build, run ninja
with the electron:electron_app
target:
$ ninja -C out/Default electron:electron_app
# This will also take a while and probably heat up your lap.
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/Default
to bring up an
editor and adding a line to the end of the file.
The built executable will be under ./out/Default
:
$ ./out/Default/Electron.app/Contents/MacOS/Electron
# or, on Windows
$ ./out/Default/electron.exe
# or, on Linux
$ ./out/Default/electron
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/Default-x86 --args='... target_cpu = "x86"'
Not all combinations of source and target CPU/OS are supported by Chromium. Only cross-compiling Windows 32-bit from Windows 64-bit and Linux 32-bit from Linux 64-bit have been tested in Electron. 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
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/Default third_party/electron_node:headers
# Install the test modules with the generated headers
$ (cd electron/spec && npm i --nodedir=../../out/Default/gen/node_headers)
Then, run Electron with electron/spec
as the argument:
# on Mac:
$ ./out/Default/Electron.app/Contents/MacOS/Electron electron/spec
# on Windows:
$ ./out/Default/electron.exe electron/spec
# on Linux:
$ ./out/Default/electron electron/spec
If you're debugging something, it can be helpful to pass some extra flags to the Electron binary:
$ ./out/Default/Electron.app/Contents/MacOS/Electron electron/spec \
--ci --enable-logging -g 'BrowserWindow module'