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
git checkout -f --detach <tag-number>
Then, one can run
gclient sync -f in
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
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
depot_tools into your
PATH and then run the following within the
vpython goma_auth.py login vpython goma_ctl.py ensure_start
Make sure the
args.gn file contains the following:
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.
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
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
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
into the code. One can also use WinDbg to understand the program flow better, but these days, I’ve been
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
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
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
Go back to Articles