ビルド手順

カスタム Electron バイナリの作成にあたって Electron そのもの をビルドするには、以下のガイドラインに従ってください。 アプリのコードをビルド済み Electron バイナリにバンドルして頒布する場合は、アプリケーション頒布 のガイドを参照してください。

プラットフォーム要件

Check the build prerequisites for your platform before proceeding:

• macOS
• Linux
• Windows

Setting up @electron/build-tools (recommended)

Electron Build Tools automate much of the setup for compiling Electron from source with different configurations and build targets. Most of the manual setup instructions can be replaced by simpler Build Tools commands.

[!TIP] Build Tools also gives you access to remote execution and caching of build actions, which will dramatically improve build times.

Electron Build Tools can be installed globally from npm:

npm install -g @electron/build-tools

Once installed, the e command should be globally available in your command line. The e init command bootstraps a local checkout of Electron:

# The 'Hello, World!' of build-tools: get and build `main`
# Choose the directory where Electron's source and build files will reside.
# You can specify any path you like; this command defaults to `$PWD/electron`.
# If you're going to use multiple branches, you may want something like:
# `--root=~/electron/branch` (e.g. `~/electron-gn/main`)
e init --root=~/electron --bootstrap testing

The --bootstrap flag also runs e sync (synchronizes source code branches from DEPS using gclient) and e build (compiles the Electron binary into the ${root}/src/out folder).

info

Sometime after the initial e sync phase, you will be asked to run e d rbe login to auth into remote build execution and proceed into the build. This may take about 20-30 minutes!

Once the build is done compiling, you can test it by running e start (or by loading it into Electron Fiddle).

Navigating the project

Some quick tips on building once your checkout is set up:

• Directory structure: Within the project, Chromium code is synced to ${root}/src/ while Electron's code (i.e. code in https://github.com/electron/electron) lives in ${root}/src/electron/. Note that both directories have their own git repositories.
• Updating your checkout: Run git commands such as git checkout <branch> and git pull from ${root}/src/electron. Whenever you update your commit HEAD, make sure to e sync before e build to sync dependencies such as Chromium and Node.js. This is especially relevant because the Chromium version in DEPS changes frequently.
• Rebuilding: When making changes to code in ${root}/src/electron/ in a local branch, you only need to re-run e build.
• Adding patches: When contributing changes in ${root}/src/ outside of ${root}/src/electron/, you need to do so via Electron's patch system. The e patches command can export all relevant patches to ${root}/src/electron/patches/ once your code change is ready.

[!IMPORTANT] Unless you're applying upstream patches, you should treat ${root}/src/ as a read-only folder and spend most of your development time in ${root}/src/electron/. You should not need to make any changes or run git commands in ${root}/src/.

[!TIP] Detailed documentation for all available e commands can be found in the repository's README.md. You can also run e --help to list all commands and use the --help flag on any command to get more usage info.

[!TIP] For more information on project structure, see the Source Code Directory Structure guide.

Manual setup (advanced)

Manual setup (advanced)

Electron uses GN for project generation and siso for building. Project configurations can be found in the .gn and .gni files in the electron/electron repo.

GN files

以下のgnファイルにはElectronのビルトのメインルールを含んでいます：

• BUILD.gn defines how Electron itself is built and includes the default configurations for linking with Chromium.
• build/args/{testing,release,all}.gn contain the default build arguments for building Electron.

GN 要件

depot_tools をインストールする必要があります。このツールセットは Chromium とその依存関係のダウンロードに使用されます。

更に Windows では、DEPOT_TOOLS_WIN_TOOLCHAIN=0 と環境変数を設定する必要があります。 これを行うには、コントロール パネル → システムとセキュリティ → システム → システムの詳細設定 を開き、DEPOT_TOOLS_WIN_TOOLCHAIN 環境変数を追加して値を 0 にします。 これはローカルにインストールされているバージョンの Visual Studio を使用するように depot_tools に知らせます (デフォルトで depot_tools は Google 社員のみがアクセスできる Google 内部のバージョンをダウンロードしようとします) 。

git キャッシュのセットアップ

Electron を複数回チェックアウトする予定がある場合 (例えば複数の並列ディレクトリを異なるブランチにチェックアウトさせるなど)、git キャッシュを使用することでその後の gclient 呼び出しを高速化できます。 これをするには GIT_CACHE_PATH 環境変数を以下のように設定する必要があります。

$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# 16G ほどあります。

コードを取得

$ mkdir electron-gn && cd electron-gn
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# これはしばらくかかります。コーヒーでも飲みに行きましょう。

https://github.com/electron/electron の代わりに、https://github.com/<username>/electron のような自分のフォークを使うこともできます。

プル/プッシュ時の注意

もし将来公式の electron レポジトリから git pull や git push をする予定であれば、現在はそれぞれのフォルダの origin URL を更新する必要があります。

$ cd src/electron
$ git remote remove origin
$ git remote add origin https://github.com/electron/electron
$ git checkout main
$ git branch --set-upstream-to=origin/main
$ cd -

ヒント

gclient works by checking a file called DEPS inside the ${root}/src/electron folder for dependencies (like Chromium or Node.js). Running gclient sync -f ensures that all dependencies required to build Electron match that file.

In order to pull, you'd run the following commands:

$ cd src/electron
$ git pull
$ gclient sync -f

ビルド

Chromium ビルドツール用の環境変数を設定します。

Linux と macOS の場合

$ cd src
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools

Windowsの場合:

# cmd
$ cd src
$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\buildtools

# PowerShell
$ cd src
$ $env:CHROMIUM_BUILDTOOLS_PATH = "$(Get-Location)\buildtools"

Electron の Testing ビルド設定は以下のようにして生成します。

Linux と macOS の場合

$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"

Windowsの場合:

# cmd
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"

# PowerShell
gn gen out/Testing --args="import(\`"//electron/build/args/testing.gn\`")"

Electron の Release ビルド設定は以下のようにして生成します。

Linux と macOS の場合

$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"

Windowsの場合:

# cmd
$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\")"

# PowerShell
$ gn gen out/Release --args="import(\`"//electron/build/args/release.gn\`")"

[!NOTE] これにより ${root}/src/ の配下に、上記で渡したテストまたはリリースビルドの構成に応じて out/Testing または out/Release ビルドのディレクトリが生成されます。 Testing|Release は他の名前に置換できますが、out のサブディレクトリである必要があります。

更に gn gen を再び実行してはいけません。ビルド引数を変更したい場合、gn args out/Testing を実行してエディタを呼び出します。 利用可能なビルド設定を一覧するには、gn args out/Testing --list を実行してください。

ビルドするには、ninja を electron ターゲットで実行します。 注意: これはさらなる時間を要し、パソコンも熱くなります。

テスト構成は以下のとおりです。

$ ninja -C out/Testing electron

リリース構成は以下のとおりです。

$ ninja -C out/Release electron

これは、先に "libchromiumcontent" ( chromium の content/ ディレクトリと Blink や V8 を含む依存関係) のすべてをビルドします。そのため時間がかかります。

実行形式は ./out/Testing 下に置かれます。

$ ./out/Testing/Electron.app/Contents/MacOS/Electron
# Windowsの場合
$ ./out/Testing/electron.exe
# Linuxの場合
$ ./out/Testing/electron

パッケージ化

配布可能なzipファイルとしてこのエレクトロンビルドをパッケージするには、次のようにする。

$ ninja -C out/Release electron:electron_dist_zip

クロスコンパイル

構築しているプラットフォームと同じでないプラットフォーム用にコンパイルするには、target_cpu 及び target_os GN 引数を設定します。 例えば、x64 ホストから x86 ターゲットをコンパイルするには、gn args で target_cpu = "x86" と指定します。

$ gn gen out/Testing-x86 --args='... target_cpu = "x86"'

ソースコードとターゲット CPU/OS のすべての組み合わせが Chromium でサポートされているわけではありません。

Host	ターゲット	状況
Windows x64	Windows arm64	実験中
Windows x64	Windows x86	自動テスト済み
Linux x64	Linux x86	自動テスト済み

他の組み合わせをテストしてうまく動作することがわかれば、このドキュメントを更新してください :)

target_os と target_cpu の許容値については、GN のリファレンスを参照してください。

Windows on Arm

Arm 上の Windows 用にクロスコンパイルするには、Chromium のガイドに従って必要な依存関係、SDK、ライブラリを取得し、ELECTRON_BUILDING_WOA=1 を使用してその環境でビルドしてから、gclient sync を実行します。

set ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

もしくは (PowerShell を用いる場合) こうします。

$env:ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

それから、上記のように target_cpu="arm64" で gn gen を実行します。

テスト

このテストを実行するために、あなたは最初に、このビルドプロセスの一部としてビルドする Node.js と同じバージョンに対してテストモジュールをビルドする必要があります。 再びコンパイルするモジュールのためのビルドヘッダを生成するために、${root}/src/ディレクトリの下で以下のように実行します。

$ ninja -C out/Testing electron:node_headers

これで テストを実行 できます。

もし何かをデバッグ中であれば、以下のフラグを Electron バイナリに渡すと役に立つかもしれません。

$ npm run test -- \
  --enable-logging -g 'BrowserWindow module'

複数マシン間での gitのキャッシュの共有

gclient git キャッシュを Linux 上で SMB 共有としてエクスポートすることで、他のマシンと共有することは可能ですが、一度に一つのプロセス/マシンだけがキャッシュを使用できます。 git-cache スクリプトによって作成されたロックはこれを防止しようとしますが、ネットワーク内で完璧には動作しない可能性があります。

Windows では、SMBv2 にはディレクトリキャッシュがあり、git キャッシュスクリプトに問題が発生するため、レジストリキー

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime

を0に設定して無効にする必要があります。 詳細: https://stackoverflow.com/a/9935126

これは PowerShell 内ですぐに設定できます (管理者権限で実行します)。

New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Services\Lanmanworkstation\Parameters" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force

トラブルシューティング

sync complains about rebase

If e sync (or gclient sync) is interrupted, the git tree may be left in a bad state, leading to a cryptic message when running sync in the future:

2> Conflict while rebasing this branch.
2> Fix the conflict and run gclient again.
2> See man git-rebase for details.

If there are no git conflicts or rebases in ${root}/src/electron, you may need to abort a git am in ${root}/src:

$ cd ../
$ git am --abort
$ cd electron
$ e sync -f

これは、${root}/src/ や他の依存関係のリポジトリにあるブランチをチェックアウトした場合に (detached HEAD でなくとも) 発生する可能性もあります。 If that is the case, a git checkout --detach HEAD in the appropriate repository should do the trick.

chromium-internal.googlesource.com のユーザー名/パスワードを聞かれる

Windows 上で gclient sync を実行しているときに Username for 'https://chrome-internal.googlesource.com': のプロンプトが表示された場合、おそらく DEPOT_TOOLS_WIN_TOOLCHAIN 環境変数が 0 に設定されていないからです。 コントロール パネル → システムとセキュリティ → システム → システムの詳細設定 を開き、DEPOT_TOOLS_WIN_TOOLCHAIN 環境変数を追加して値を 0 にします。 これはローカルにインストールされているバージョンの Visual Studio を使用するように depot_tools に知らせます (デフォルトで depot_tools は Google 社員のみがアクセスできる Google 内部のバージョンをダウンロードしようとします) 。

RBE 認証が "Token not valid" というエラーでランダムに失敗する

これは、マシン上のローカルのクロック時間がわずかにずれていることが原因である可能性があります。 time.is を使ってご確認ください。