2018-05-18 20:04:46 +00:00
|
|
|
# Build Instructions (experimental GN build)
|
|
|
|
|
|
|
|
Follow the guidelines below for building Electron with the experimental GN
|
|
|
|
build.
|
|
|
|
|
2018-08-11 17:20:19 +00:00
|
|
|
> **NOTE**: The GN build system is in _experimental_ status.
|
2018-05-18 20:04:46 +00:00
|
|
|
|
|
|
|
## Prerequisites
|
|
|
|
|
2018-07-25 14:45:52 +00:00
|
|
|
Check the build prerequisites for your platform before proceeding
|
|
|
|
|
|
|
|
* [macOS](build-instructions-osx.md#prerequisites)
|
|
|
|
* [Linux](build-instructions-linux.md#prerequisites)
|
|
|
|
* [Windows](build-instructions-windows.md#prerequisites)
|
|
|
|
|
|
|
|
## Install `depot_tools`
|
|
|
|
|
|
|
|
You'll need to install [`depot_tools`][depot-tools], the toolset
|
|
|
|
used for fetching Chromium and its dependencies.
|
|
|
|
|
2018-08-11 17:20:19 +00:00
|
|
|
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).
|
2018-05-18 20:04:46 +00:00
|
|
|
|
|
|
|
[depot-tools]: http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up
|
|
|
|
|
|
|
|
## Getting the Code
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ mkdir electron-gn && cd electron-gn
|
2018-08-11 17:20:19 +00:00
|
|
|
$ gclient config \
|
|
|
|
--name "src/electron" \
|
|
|
|
--unmanaged \
|
|
|
|
https://github.com/electron/electron
|
2018-05-18 20:04:46 +00:00
|
|
|
$ gclient sync --with_branch_heads --with_tags
|
|
|
|
# This will take a while, go get a coffee.
|
|
|
|
```
|
|
|
|
|
|
|
|
## Building
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ cd src
|
|
|
|
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools
|
2018-07-25 20:39:37 +00:00
|
|
|
$ gn gen out/Default --args='import("//electron/build/args/debug.gn")'
|
2018-05-18 20:04:46 +00:00
|
|
|
```
|
|
|
|
|
2018-07-25 14:45:52 +00:00
|
|
|
This will generate a build directory `out/Default` under `src/` with
|
|
|
|
debug build configuration. You can replace `Default` with another name,
|
2018-08-11 17:20:19 +00:00
|
|
|
but it should be a subdirectory of `out`.
|
2018-07-25 14:45:52 +00:00
|
|
|
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.
|
|
|
|
|
2018-08-11 17:20:19 +00:00
|
|
|
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:**
|
2018-07-25 14:45:52 +00:00
|
|
|
|
|
|
|
```sh
|
|
|
|
$ gn gen out/Default --args='import("//electron/build/args/debug.gn")'
|
|
|
|
```
|
|
|
|
|
2018-08-11 17:20:19 +00:00
|
|
|
**For generating Release (aka "non-component" or "static") build config of
|
|
|
|
Electron:**
|
2018-07-25 14:45:52 +00:00
|
|
|
|
|
|
|
```sh
|
|
|
|
$ gn gen out/Default --args='import("//electron/build/args/release.gn")'
|
|
|
|
```
|
2018-05-18 20:04:46 +00:00
|
|
|
|
2018-07-25 14:45:52 +00:00
|
|
|
**To build, run `ninja` with the `electron:electron_app` target:**
|
2018-05-18 20:04:46 +00:00
|
|
|
|
|
|
|
```sh
|
|
|
|
$ 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][sccache]. Add the GN arg
|
2018-08-11 17:20:19 +00:00
|
|
|
`cc_wrapper = "sccache"` by running `gn args out/Default` to bring up an
|
|
|
|
editor and adding a line to the end of the file.
|
2018-05-18 20:04:46 +00:00
|
|
|
|
|
|
|
[sccache]: https://github.com/mozilla/sccache
|
|
|
|
|
|
|
|
The built executable will be under `./out/Default`:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ ./out/Default/Electron.app/Contents/MacOS/Electron
|
2018-08-11 17:20:19 +00:00
|
|
|
# or, on Windows
|
|
|
|
$ ./out/Default/electron.exe
|
2018-05-18 20:04:46 +00:00
|
|
|
# or, on Linux
|
|
|
|
$ ./out/Default/electron
|
|
|
|
```
|
|
|
|
|
2018-07-19 23:57:54 +00:00
|
|
|
### Cross-compiling
|
|
|
|
|
|
|
|
To compile for a platform that isn't the same as the one you're building on,
|
2018-08-11 17:20:19 +00:00
|
|
|
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`.
|
2018-07-19 23:57:54 +00:00
|
|
|
|
|
|
|
```sh
|
|
|
|
$ gn gen out/Default-x86 --args='... target_cpu = "x86"'
|
|
|
|
```
|
|
|
|
|
|
|
|
Not all combinations of source and target CPU/OS are supported by Chromium.
|
2018-08-11 17:20:19 +00:00
|
|
|
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`][target_os values]
|
|
|
|
and [`target_cpu`][target_cpu values]
|
|
|
|
|
|
|
|
[target_os values]: https://gn.googlesource.com/gn/+/master/docs/reference.md#built_in-predefined-variables-target_os_the-desired-operating-system-for-the-build-possible-values
|
|
|
|
[target_cpu values]: https://gn.googlesource.com/gn/+/master/docs/reference.md#built_in-predefined-variables-target_cpu_the-desired-cpu-architecture-for-the-build-possible-values
|
2018-07-19 23:57:54 +00:00
|
|
|
|
2018-05-18 20:04:46 +00:00
|
|
|
## Tests
|
|
|
|
|
|
|
|
To run the tests, you'll first need to build the test modules against the
|
2018-07-25 14:45:52 +00:00
|
|
|
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.
|
2018-05-18 20:04:46 +00:00
|
|
|
|
|
|
|
```sh
|
2018-07-25 14:45:52 +00:00
|
|
|
$ ninja -C out/Default electron/build/node:headers
|
|
|
|
# Install the test modules with the generated headers
|
|
|
|
$ (cd electron/spec && npm i --nodedir=../../out/Default/gen/node_headers)
|
2018-05-18 20:04:46 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Then, run Electron with `electron/spec` as the argument:
|
|
|
|
|
|
|
|
```sh
|
2018-08-11 17:20:19 +00:00
|
|
|
# on Mac:
|
2018-05-18 20:04:46 +00:00
|
|
|
$ ./out/Default/Electron.app/Contents/MacOS/Electron electron/spec
|
2018-08-11 17:20:19 +00:00
|
|
|
# on Windows:
|
|
|
|
$ ./out/Default/electron.exe electron/spec
|
|
|
|
# on Linux:
|
|
|
|
$ ./out/Default/electron electron/spec
|
2018-05-18 20:04:46 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
If you're debugging something, it can be helpful to pass some extra flags to
|
|
|
|
the Electron binary:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
$ ./out/Default/Electron.app/Contents/MacOS/Electron electron/spec \
|
|
|
|
--ci --enable-logging -g 'BrowserWindow module'
|
|
|
|
```
|