Инструкции по сборке

Следуйте приведенным ниже рекомендациям для сборки самого Electron, для целей создания пользовательских библиотек Electron. Для сборки и распространения вашего кода приложения с предварительно собранными бинарными файлами Electron см. руководство по распространению приложений.

Предварительные требования к платформе​

Проверьте предварительные требования к сборке для вашей платформы перед продолжением

• macOS
• Linux
• Windows

Инструменты сборки​

Инструменты сборки Electron автоматизируют большую часть настройки для компиляции Electron из исходного кода с различными конфигурациями и целевыми платформами. Если вы хотите настроить среду вручную, инструкции приведены ниже.

Electron использует GN для генерации проекта и ninja для сборки. Конфигурации проекта можно найти в файлах .gn и .gni.

Файлы GN​

В следующих файлах gn содержатся основные правила сборки Electron:

• BUILD.gn определяет, как собирается сам Electron, и включает в себя стандартные конфигурации для связывания с Chromium.
• build/args/{testing,release,all}.gn содержат стандартные аргументы сборки для сборки Electron.

Предварительные требования к GN​

Вам потребуется установить depot_tools, набор инструментов, используемый для извлечения Chromium и его зависимостей.

Также на Windows вам необходимо установить переменную среды DEPOT_TOOLS_WIN_TOOLCHAIN=0. Для этого откройте Control Panel → System and Security → System → Advanced system settings и добавьте системную переменную DEPOT_TOOLS_WIN_TOOLCHAIN со значением 0. Это сообщит depot_tools использовать вашу локально установленную версию Visual Studio (по умолчанию depot_tools будет пытаться загрузить внутреннюю версию Google, доступную только сотрудникам Google).

Настройка кэша Git​

Если вы планируете извлекать Electron более одного раза (например, чтобы иметь несколько параллельных каталогов, извлеченных на разные ветки), использование кэша Git ускорит последующие вызовы gclient. Для этого установите переменную среды GIT_CACHE_PATH.

$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# This will use about 16G.

Получение кода​

$ mkdir electron && cd electron
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# This will take a while, go get a coffee.

Вместо https://github.com/electron/electron, вы можете использовать свою собственную вилку здесь (например, https://github.com/<username>/electron).

Примечание о pull/push​

Если в будущем вы планируете выполнять git pull или git push из официального репозитория electron, вам теперь необходимо обновить соответствующие URL-адреса origin папки.

$ 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 работает, проверяя файл под названием DEPS в папке src/electron на наличие зависимостей (например, Chromium или Node.js). Запуск gclient sync -f гарантирует, что все зависимости, необходимые для сборки Electron, соответствуют этому файлу.

Таким образом, для извлечения вы выполните следующие команды:

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

Сборка​

Установите переменную среды для инструментов сборки chromium

На Linux и MacOS

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

На Windows:

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

Для генерации тестовой конфигурации сборки Electron:

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

Для генерации конфигурации сборки Release Electron:

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

Примечание: Это создаст папку out/Testing или out/Release в src/, содержащую тестовую или релизную сборку в зависимости от переданной выше конфигурации. Вы можете заменить 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' (т. е. каталог content/ в chromium и его зависимости, включая WebKit и V8), поэтому это займет некоторое время.

Собранный исполняемый файл будет находиться по адресу ./out/Testing:

$ ./out/Testing/Electron.app/Contents/MacOS/Electron
# or, on Windows
$ ./out/Testing/electron.exe
# or, on Linux
$ ./out/Testing/electron

Упаковки​

В Linux сначала удалите информацию о отладке и символах:

$ electron/script/strip-binaries.py -d out/Release

Для упаковки сборки electron в zip-файл, готовый к распространению:

$ ninja -C out/Release electron:electron_dist_zip

Кросс-компиляция​

Чтобы скомпилировать для платформы, которая не совпадает с той, на которой вы собираете, задайте аргументы GN target_cpu и target_os. Например, чтобы скомпилировать x86-целевой компонент с x64-хоста, укажите target_cpu = "x86" в gn args.

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

Не все комбинации исходного и целевого процессора/ОС поддерживаются Chromium.

Если вы протестируете другие комбинации и обнаружите, что они работают, пожалуйста, обновите это руководство :)

См. справку GN для допустимых значений target_os и target_cpu.

Windows на ARM (экспериментально)​

Чтобы выполнить кросс-компиляцию для Windows на ARM, следуйте руководству 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

Далее, запустите gn gen как и выше, с target_cpu="arm64".

Тесты​

Для запуска тестов сначала необходимо создать модули тестов, используя ту же версию Node.js, которая была использована при сборке. Для генерации заголовков сборки для компиляции модулей выполните следующие команды в каталоге src/.

$ ninja -C out/Testing third_party/electron_node:headers

Теперь вы можете запустить тесты.

Если вы отлаживаете что-то, может быть полезно передать дополнительные флаги в бинарник Electron:

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

Обмен кэшем git между несколькими машинами​

Возможность обмена кэшем gclient git с другими машинами, экспортировав его в качестве SMB-разделяемого ресурса в Linux, но только один процесс/машина может использовать кэш за раз. Блокировки, созданные скриптом git-cache, пытаются предотвратить это, но в сети это может не работать идеально.

В Windows SMBv2 имеет кэш каталогов, который вызовет проблемы со скриптом git-cache, поэтому необходимо его отключить, установив ключ реестра

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

Устранение неполадок​

gclient sync жалуется на rebase​

Если gclient sync прервано, дерево git может оказаться в плохом состоянии, что приведёт к криптической ошибке при запуске gclient sync в будущем:

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

Если в src/electron нет конфликтов git или ребазов, возможно, потребуется прервать git am в src.

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

Мне запрашивается имя пользователя/пароль для chromium-internal.googlesource.com​

Если при запуске gclient sync в Windows вы видите запрос на Username for 'https://chrome-internal.googlesource.com':, скорее всего, переменная среды DEPOT_TOOLS_WIN_TOOLCHAIN не установлена в значение 0. Откройте Control Panel → System and Security → System → Advanced system settings и добавьте системную переменную DEPOT_TOOLS_WIN_TOOLCHAIN со значением 0. Это сообщает depot_tools использовать локальную установленную версию Visual Studio (по умолчанию depot_tools будет пытаться загрузить внутреннюю версию Google, к которой есть доступ только у сотрудников Google).