Notes on Developing Electron

Last modified October 14, 2022.

I work with the Electron codebase on Windows and macOS, and have run into some problems in the past that took me a while to figure out. I don’t use Build Tools. These notes assume that one has set up their Electron checkout using the official guide on building Electron.

Fixing sync failures

The patches can sometimes fail to apply during a sync. In that case, one can first look in the src/electron/DEPS file to see what Chromium tag (version number) to use, and then run in the src directory

git checkout -f --detach <tag-number>

Then, one can run gclient sync -f in src/electron again.

Setting up Goma

Goma is a distributed compiler service that can compile Electron in a few hours rather than half a day. Goma is only needed for building, and is not used during gclient sync.

One can obtain the Goma archive file by looking through the Build Tools goma script implementation and piecing together various parts of the link, and then pasting the link into a new browser tab.

To authenticate into Goma, I prefer using vpython from depot_tools directly. Place depot_tools into your PATH and then run the following within the goma directory:

vpython goma_auth.py login
vpython goma_ctl.py ensure_start

Make sure the args.gn file contains the following:

use_goma=true
goma_dir=<absolute-path-to-goma-dir>

Then, add the -j parameter while compiling:

ninja -C out/Testing -j 200 electron:electron_app

For more information on the -j parameter, see the Electron documentation on building with Goma.

Disabling Goma

Even though my args.gn has Goma enabled, there are times when I make a small change and don’t feel like authenticating into Goma just to compile it. In that case, one can type $env:GOMA_DISABLED=1 and then compile without the -j parameter.

Cleaning the output directory

The TypeScript files can sometimes fail to transpile even after syncing, such as when switching from a nightly v21 build to the 14-x-y branch without cleaning the output directory in between. In this case, running gn clean out/Testing can fix the issue.

Enabling logging and writing debug logs

In the case that logging is not enabled, one can write $env:ELECTRON_ENABLE_LOGGING=1 and run the program.

To add debug logs to a file, include base/logging.h and write

DLOG(ERROR) << variable_to_log_here;

DLOG(ERROR) is an output stream and from what I’ve seen, it works like std::cout, but prepends some additional data and appends a newline to the logged contents. There are other Chromium logging macros as well.

When I want to purposely crash the program, such as to get a stack trace, I write a DCHECK(false); line into the code. One can also use WinDbg to understand the program flow better, but these days, I’ve been mostly using DLOG along with Chromium Code Search instead.

To write logs in Blink, running Electron with --enable-logging=file --log-file=<absolute-path-for-log-file> works.

Working with callbacks

BindRepeating() and BindOnce() confused me when I saw them for the first time in the Electron codebase. The Chromium repository has an excellent explanation of various callback functions that they use. What’s cool about them is that the bind functions actually represent partial function application, making it easier to pass around functions and arguments without having to use function pointers everywhere.

One important thing to remember with the bind functions is that the this argument must be passed in as the first argument if the function to be run is an instance function rather than a class function. Also worth looking into is the Unretained() function, which often shows up with the bind calls.

Exporting Chromium patches

I don’t think pwsh can figure out that the patch export script is a Python file, so to export Chromium patches, I run from the src directory

python electron/script/git-export-patches -o electron/patches/chromium

Sometimes, creating a commit fails due to patches being out of sync even after an export. In that case, re-syncing and re-exporting should fix the issue.

Reinstalling XCode command-line tools

When updating from Big Sur to Monterey, my build broke completely. Running a clean build didn’t completely resolve the issue, and the remaining issues seemed to be caused by XCode.

It turns out one can reinstall the XCode command-line tools by running the following in a terminal:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install
xcodebuild -runFirstLaunch

More references


Go back to Articles