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