Aller au contenu principal

Instructions pour compiler Electron

Suivez les instructions ci-dessous pour compiler Electron, afin d'ontenir une version personnalisée d'Electron. Pour regrouper et distribuer le code de votre application avec les binaires précompilés d'Electron, reportez-vous au guide de la distribution d'applications.

Prérequis de la plateforme​

Vérifiez les prérequis de build pour votre plateforme avant de continuer:

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).

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​

Les fichiers gn suivants contiennent les règles principales pour la construction d'Electron :

Prérequis GN​

Vous devrez installer depot_tools, l'ensemble d'outils utilisé pour récupérer Chromium et ses dépendances.

De plus, sous Windows, vous devrez définir la variable d'environnement DEPOT_TOOLS_WIN_TOOLCHAIN=0. Pour ce faire, ouvrez Panneau de configuration → Système et Sécurité → Système → Paramètres système avancés et ajouter une variable système DEPOT_TOOLS_WIN_TOOLCHAIN avec la valeur 0. Cela indique au depot_tools d’utiliser votre version locale de Visual Studio (par défaut, depot_tools essaiera de télécharger une version interne de Google uniquement accessible à ses utilisateurs).

Mise en place du cache git​

Si vous prévoyez de vérifier Electron plus d'une fois (par exemple, d'avoir plusieurs répertoires parallèles vérifiés sur différentes branches), l'utilisation de du cache git accélérera les appels suivants à gclient. Pour cela, définissez une variable d'environnement GIT_CACHE_PATH:

$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# Cela utilisera environ 16G.

Obtenir le code​

$ mkdir electron && cd electron
$ gclient config --name "src/electron" --unmanaged https://github. om/electron/electron
$ gclient sync --with_branch_heads --with_tags
# Cela prendra un certain temps, allez prendre un café.

Au lieu de https://github.com/electron/electron, vous pouvez utiliser votre propre fork ici (quelque chose comme https://github.com/<username>/electron).

Une note lors du tirage/poussage​

Si vous avez l'intention d'effectuer un git pull ou un git push du dépôt officiel electron dans le futur, vous devez maintenant mettre à jour les URL d'origine des répertoires respectifs.

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

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

Compilation​

Définir la variable d'environnement pour les outils de construction de chromium

Sous Linux & MacOS

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

Sur Windows :

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

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

Pour générer la configuration de la version Testing d'Electron:

Sous Linux & MacOS

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

Sur 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\`")"

Pour générer la configuration de Release build d'Electron:

Sous Linux & MacOS

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

Sur 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] This will generate a out/Testing or out/Release build directory under ${root}/src/ with the testing or release build depending upon the configuration passed above. Vous pouvez remplacer Testing|Release par un autre nom, mais ce doit être un sous-répertoire de out.

Vous ne devriez pas non plus avoir à exécuter gn gen à nouveau. Si vous voulez modifier les arguments de compilation, vous pouvez exécuter gn args out/Testing pour faire apparaître un éditeur. Pour voir la liste des options de configuration de compilation disponibles, exécutez gn args out/Testing --list.

Pour compiler, exécutez ninja avec la cible electron : Remarque : Cela prendra assurement un certain temps.

Pour la configuration de test :

$ ninja -C out/Testing electron

Pour la configuration de la version :

$ ninja -C out/Release electron

Cela compilera tout ce qui était précédemment 'libchromiumcontent' (c'est-à-dire le répertoire content/ de chromium et ses dépendances, incl. Blink et V8), donc cela prendra un certain temps.

L'exécutable produit sera dans ./out/Testing:

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

Empaquetage​

Pour empaqueter la compilation d'electron en tant que fichier zip distribuable:

$ ninja -C out/Release electron:electron_dist_zip

Compilation croisée​

Pour compiler une plate-forme qui n'est pas la même que celle sur laquelle vous compilez, définissez les arguments GN target_cpu et target_os. Par exemple, pour compiler une cible x86 à partir d'un hôte x64, spécifiez target_cpu = "x86" dans gn args.

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

Toutes les combinaisons de source et de cible CPU/OS ne sont pas supportées par Chromium.

HostCibleNotice
Windows x64Windows arm64Expérimental
Windows x64Windows x86Testé automatiquement
Linux x64Linux x86Testé automatiquement

Si vous testez d'autres combinaisons et trouvez qu'elles fonctionnent, veuillez mettre à jour ce document :)

See the GN reference for allowable values of target_os and target_cpu.

Windows on Arm​

To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.

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

Ou (si vous utilisez PowerShell) :

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

Ensuite, exécutez gn gen comme ci-dessus avec target_cpu="arm64".

Tests​

Pour exécuter les tests, vous devez d'abord construire les modules de test avec la même version de Node.js qui a été compilée dans le cadre du processus de compilation. Pour générer des en-têtes de compilation pour les modules à compiler, exécutez la commande suivante dans le répertoire ${root}/src/.

$ ninja -C out/Testing electron:node_headers

You can now run the tests.

Si vous déboguez quelque chose, il peut être utile de passer quelques options supplémentaires au binaire d'Electron :

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

Partage du cache git entre plusieurs machines​

Il est possible de partager le cache git gclient avec d'autres machines en l'exportant en tant que SMB sur linux, mais seul un processus/machine peut utiliser le cache à un moment donné. Les verrous créés par le script git-cache essaieront de prévenir cela, mais cela peut ne pas fonctionner parfaitement dans un réseau.

Sous Windows, SMBv2 a un cache de répertoire qui va causer des problèmes avec le script de cache git, donc il est nécessaire de le désactiver en définissant la clé de registre

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

à 0. Plus d'informations : https://stackoverflow.com/a/9935126

Cela peut être défini rapidement dans powershell (exécuté en tant qu'administrateur) :

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

Résolution de problème​

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> Conflit en rebasant cette branche.
2> Corriger le conflit et exécuter gclient à nouveau.
2> Voir man git-rebase pour plus de détails.

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

Cela peut également se produire si vous avez vérifié une branche (par opposition à avoir une tête détachée) dans ${root}/src/ ou un autre dépôt de dépendances. If that is the case, a git checkout --detach HEAD in the appropriate repository should do the trick.

On me demande de saisir mes nom d'utilisateur et mot de passe pour chromium-internal.googlesource.com​

Si vous voyez une invite pour nom d'utilisateur pour 'https://chrome-internal.googlesource. om': lorsque vous exécutez gclient sync sous Windows, c'est probablement parce que la variable d'environnement DEPOT_TOOLS_WIN_TOOLCHAIN n'est pas définie à 0. Ouvrez Control Panel → System and Security → System → Advanced system settings et ajoutez une variable système DEPOT_TOOLS_WIN_TOOLCHAIN avec comme valeur 0. Cela indique au depot_tools d’utiliser votre version locale de Visual Studio (par défaut, depot_tools essaiera de télécharger une version interne de Google uniquement accessible à ses utilisateurs).

RBE authentication randomly fails with "Token not valid"​

This could be caused by the local clock time on the machine being off by a small amount. Use time.is to check.