{"id":13602421,"url":"https://github.com/electron/build-tools","last_synced_at":"2025-04-08T14:03:17.546Z","repository":{"id":37498268,"uuid":"152825976","full_name":"electron/build-tools","owner":"electron","description":"The GN scripts to use for Electron dev-flows","archived":false,"fork":false,"pushed_at":"2024-10-29T16:19:09.000Z","size":1404,"stargazers_count":262,"open_issues_count":18,"forks_count":77,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-10-29T17:15:44.583Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/electron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-13T02:05:10.000Z","updated_at":"2024-10-28T12:27:23.000Z","dependencies_parsed_at":"2024-02-19T19:16:29.190Z","dependency_job_id":"a9abf7c2-5c47-46cd-9c45-0bf05a72c0aa","html_url":"https://github.com/electron/build-tools","commit_stats":{"total_commits":528,"total_committers":38,"mean_commits":"13.894736842105264","dds":0.7329545454545454,"last_synced_commit":"714ee8e616bb2e0184039645dbd93e93674dfede"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fbuild-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fbuild-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fbuild-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electron%2Fbuild-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/electron","download_url":"https://codeload.github.com/electron/build-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595946,"owners_count":20964032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T18:01:22.748Z","updated_at":"2025-04-08T14:03:17.516Z","avatar_url":"https://github.com/electron.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Electron Build Tools\n\nThis repository contains helper/wrapper scripts to make building Electron easier.\n\n## Installation\n\nA handful of prerequisites, such as git, python, and npm, are\nrequired for building Electron itself; these can be found in\n[Platform Prerequisites][platform-prerequisites]. `npm` can be used\nwith `build-tools` itself as well, but we've configured it to run\nwith `yarn`, so we also recommend you [install it to your system](https://yarnpkg.com/lang/en/docs/install/).\n\nFrom here, you'll need a command-line prompt. On Mac and Linux, this will\nbe a terminal with a shell, e.g. bash or zsh. You can also use these on\nWindows if you install them, or use built-in tools like Windows'\n[Command Prompt](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands#command-shell-overview).\n\nPlease note that `build-tools` (due to nested dependencies) might not work properly in powershell, please use `cmd` on Windows for optimum results.\n\n```sh\n# Install build-tools package globally:\nnpm i -g @electron/build-tools\n```\n\n## Getting the Code and Building Electron\n\nYou can run a new Electron build with this command:\n\n```sh\n# The 'Hello, World!' of build-tools: get and build `main`\n# Choose the directory where Electron's source and build files will reside.\n# You can specify any path you like; this command defaults to `$PWD/electron`.\n# If you're going to use multiple branches, you may want something like:\n# `--root=~/electron/branch` (e.g. `~/electron-gn/main`)\ne init --root=~/electron --bootstrap testing\n```\n\nThat command's going to run for awhile. While you're waiting, grab a\ncup of hot caffeine and read about what your computer is doing:\n\n### Concepts\n\nElectron's build-tools command is named `e`. Like [nvm][nvm] and git,\nyou'll invoke `e` with commands and subcommands. See `e --help` or `e help \u003ccmd\u003e`\nfor many more details.\n\n`e` also borrows another inspiration from nvm: having multiple configurations\nthat you can switch between so that one is the current, active configuration.\nMany choices go into an Electron build:\n\n* Which [Electron branch](https://github.com/electron/electron/branches)\n  is used (e.g. `main`, `13-x-y`)\n* Which [.gn config file][gn-configs] is imported (e.g.\n  [testing](https://github.com/electron/electron/blob/main/build/args/testing.gn) or\n  [release](https://github.com/electron/electron/blob/main/build/args/release.gn))\n* Any compile-time options (e.g. Clang's [asan or tsan][sanitizers])\n\n`e` holds all these variables together in a build configuration. You can\nhave multiple build configurations and manage them in a way similar to nvm:\n\n| nvm                  | e                  | Description                                    |\n|:---------------------|:-------------------|:-----------------------------------------------|\n| nvm ls               | e show configs     | Show the available configurations              |\n| nvm current          | e show current     | Show which configuration is currently in use   |\n| nvm use \u0026lt;name\u0026gt; | e use \u0026lt;name\u0026gt; | Change which configuration is currently in use |\n\nGetting the source code is a lot more than cloning `electron/electron`.\nElectron is built on top of Chromium (with Electron patches) and Node\n(with more Electron patches). A source tree needs to have all of the\nabove **and** for their versions to be in sync with each other. Electron\nuses Chromium's [Depot Tools][depot-tools] and [GN][gn] for wrangling\nand building the code. `e` wraps these tools:\n\n| Command | Description                                                    |\n|:--------|:---------------------------------------------------------------|\n| e init  | Create a new build config and initialize a GN directory        |\n| e sync  | Get / update / synchronize source code branches                |\n| e build | Build it!                                                      |\n\n### `e init`\n\n`e init` initializes a new local development environment for Electron.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e init --help\n```\n\nNew build configs are created with `e init`. It has several command-line\noptions to specify the build configuration, e.g. the path to the source\ncode, compile-time options, and so on. See `e init --help` for in-depth\ndetails.\n\nEach build config has a name, chosen by you to use as a mnemonic when\nswitching between build configs with `e use \u003cname\u003e`. This is the name's\nonly purpose, so choose whatever you find easiest to work with \u0026mdash;\nwhether it's `electron`, `6-1-x--testing`, or `chocolate-onion-popsicle`.\n\nEach build also needs a root directory. All the source code and built\nfiles will be stored somewhere beneath it. `e init` uses `$PWD/electron`\nby default, but you can choose your own with `--root=/some/path`. If you\nwant to make multiple build types of the same branch, you can reuse\nan existing root to share it between build configs.\n\nAs an example, let's say you're starting from scratch and want both\ntesting and release builds of the main branch in `electron/electron`.\nYou might do this:\n\n```sh\n# making 'release' and 'testing' builds from main\n\n$ e init main-testing -i testing --root=~/src/electron\nCreating '~/src/electron'\nNew build config 'main-testing' created\nNow using config 'main-testing'\n$ e show current\nmain-testing\n\n$ e init main-release -i release --root=~/src/electron\nINFO Root '~/src/electron' already exists.\nINFO (OK if you are sharing $root between multiple build configs)\nNew build config 'main-release' created\nNow using config 'main-release'\n\n$ e show configs\n* main-release\n  main-testing\n\n$ e show current\nmain-release\n$ e show root\n~/src/electron\n\n$ e use main-testing\nNow using config 'main-testing'\n$ e show current\nmain-testing\n$ e show root\n~/src/electron\n```\n\nAs a convenience, `e init --bootstrap` will run `e sync` and `e build`\nafter creating the build config. Let's see what those do:\n\n### `e sync`\n\nTo see all potential options for this command, run:\n\n```sh\n$ e sync --help\n```\n\n`e sync` is a wrapper around `gclient sync` from [Depot Tools][depot-tools].\nIf you're starting from scratch, this will (slowly) fetch all the source\ncode. It's also useful after switching Electron branches to synchronize\nthe rest of the sources to the versions needed by the new Electron branch.\n\n`e sync` is usually all you need. Any extra args are passed along to gclient itself.\n\n```sh\n$ e show current\nmain-testing\n\n$ e show root\n~/src/electron\n\n$ e sync\nRunning \"gclient sync --with_branch_heads --with_tags\" in '~/src/electron/src'\n[sync output omitted]\n```\n\nTo make your output more verbose, you can add an increasing number of `-v`s. For example,\n\n```sh\n# basic verbosity\n$ e sync -v\nRunning \"gclient sync --with_branch_heads --with_tags -v\" in '~/src/electron/src'\n[sync output omitted]\n\n# significant verbosity\n$ e sync -vvvv\nRunning \"gclient sync --with_branch_heads --with_tags -vvvv\" in '~/src/electron/src'\n[sync output omitted]\n```\n\n### `e build`\n\n`e build` builds an Electron executable.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e build --help\n```\n\nOnce you have the source, the next step is to build it with `e build [target]`.\nSome of the build targets you may want to build include:\n\n| Target        | Description                                              |\n|:--------------|:---------------------------------------------------------|\n| third_party/breakpad:dump_syms      | Builds the breakpad `dump_syms` binary                   |\n| electron:electron_chromedriver_zip  | Builds the `chromedriver` binary                         |\n| electron                            | Builds the Electron binary **(Default)**                 |\n| electron:electron_dist_zip          | Builds the Electron binary and generates a dist zip file |\n| electron:electron_mksnapshot_zip    | Builds the `mksnapshot` binary                           |\n| electron:node_headers               | Builds the node headers `.tar.gz` file                   |\n| electron:electron_symbols           | Generate the breakpad symbols in release builds          |\n\nTo build a specific ninja target, run `e build --target [target]`:\n\n```sh\n$ e build --target electron:node_headers\n```\n\nRunning `e build` with no target will build `electron` by default.\n\nAny extra args are passed along to [ninja][ninja], so for example\n`e build -v` runs a verbose build of `electron`.\n\nTo see an exhaustive list of all possible build targets, you can run `e d gn ls out/[TYPE]`,\nwhere `[TYPE]` is e.g. `Testing` or `Release` depending on your build type. This will log a long\nlist of targets to the console and also allow you to build some of Chromium's targets.\n\nFor example, running `e d gn ls out/Testing | grep \"//ui/views/\"` produces something like:\n\n```console\n//ui/views/controls/webview:test_support\n//ui/views/controls/webview:webview\n//ui/views/debug:views_debug\n//ui/views/examples:copy_content_resources\n//ui/views/examples:views_examples\n//ui/views/examples:views_examples_lib\n//ui/views/examples:views_examples_proc\n//ui/views/examples:views_examples_resources_grd\n//ui/views/examples:views_examples_resources_grd_grit\n//ui/views/examples:views_examples_resources_pak\n//ui/views/examples:views_examples_unittests\n//ui/views/examples:views_examples_unittests__runner\n//ui/views/examples:views_examples_with_content\n//ui/views/examples:views_examples_with_content_lib\n//ui/views/resources:resources\n//ui/views/resources:resources_grd\n//ui/views/resources:resources_grd_grit\n//ui/views/window/vector_icons:vector_icons\n//ui/views/window/vector_icons:window_control_vector_icons\n```\n\nYou could then run `e build --target ui/views/examples:views_examples_with_content` to produce Chrome's `//ui/views` example executable and run it with `./out/Testing/views_examples_with_content`.\n\nWhen first run, `e build` will try to set up reclient to speed up your builds. The permission prompt\ncan look scary because GitHub's UI is less than optimal\n([related discussion](https://github.com/orgs/community/discussions/37117)). However, Electron only\nobtains user profile access and `read:org` permission. No permission is granted to any of your\nrepositories or content.\n\n## Using Electron\n\nAfter you've built Electron, it's time to use it!\n\n| Command | Description                          |\n|:--------|:-------------------------------------|\n| e start | Run the Electron build               |\n| e node  | Run the Electron build as Node       |\n| e debug | Run the Electron build in a debugger |\n| e test  | Run Electron's spec runner           |\n\nAs usual, any extra args are passed along to the executable. For example,\n`e node --version` will print out Electron's node version.\n\n### `e debug`\n\n`e debug` runs your local Electron build inside of [lldb][lldb] or [gdb][gdb].\n\n```sh\n$ uname\nLinux\n$ e debug\nReading symbols from /home/yourname/electron/gn/main/src/out/Testing/electron...\n(gdb)\n```\n\n```sh\n$ uname\nDarwin\n\n$ e debug\ntarget create \"/Users/yourname/electron-gn/src/out/Testing/Electron.app/Contents/MacOS/Electron\"\n(lldb)\n```\n\n### `e d`\n\n`e d` runs [Depot Tools][depot-tools] commands.  Some useful commands:\n\n```sh\n# run gclient sync directly\ne d gclient sync\n\n# login to reclient\ne d rbe login\n\n# check reclient status\ne d rbe status\n\n# get the list of all build args \ne d gn args --list -C out/Testing\n```\n\n### `e test`\n\n`e test` starts the local Electron build's test runner. Any extra args are passed\nalong to the runner.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e test --help\n```\n\nExample:\n\n```sh\n# run all tests\ne test\n\n# run main process tests\ne test --runners=main\n```\n\nPossible extra arguments to pass:\n\n* `--node` - Run Node.js' own tests with Electron in `RUN_AS_NODE` mode.\n* `--runners=\u003cmain|native\u003e` - The set of tests to run, can be either `main` or `native`.\n\n### `e show`\n\n`e show` shows information about the current build config.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e show --help\n```\n\n| Command            | Description                                                    |\n|:-------------------|:---------------------------------------------------------------|\n| e show current     | The name of the active build config                            |\n| e show configs     | Lists all build configs                                        |\n| e show env         | Show environment variables injected by the active build config |\n| e show exe         | The path of the built Electron executable                      |\n| e show root        | The path of the root directory from `e init --root`.           |\n| e show src \\[name] | The path of the named (default: electron) source dir           |\n| e show stats       | Build statistics                                               |\n\nExample usage:\n\n```sh\n$ uname\nDarwin\n\n$ e show exe\n/Users/username/electron-gn-root/src/out/Testing/Electron.app/Contents/MacOS/Electron\n\n$ uname\nLinux\n\n$ e show exe\n/home/username/electron-gn-root/src/out/Testing/electron\n\n$ e show out\nTesting\n\n$ e show src\n/home/username/electron-gn-root/src/electron\n\n$ cd `e show src base` \u0026\u0026 pwd\n/home/username/electron-gn-root/src/base\n\n$ ripgrep --t h TakeHeapSnapshot `e show src`\n```\n\n### `e remove \u003cname\u003e`\n\n`e remove|rm \u003cname\u003e` removes a build config from the list.\n\n### `e open \u003ccommit | issue | PR\u003e`\n\n`e open` opens the GitHub page for the specified commit, pull request, or issue.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e open --help\n```\n\nFor example, `e open 0920d01` will find the commit with an abbreviated\nsha1 of `0920d01`, see that it's associated with pull request #23450,\nand open https://github.com/electron/electron/pull/23450 in your browser.\nSince you can pass in a pull request or issue number as well,\n`e open 23450` would have the same effect.\n\n### `e patches [patch-dir]`\n\n`e patches` exports patches to the specified patch directory in Electron source tree.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e patches --help\n```\n\nValid patch directories can include:\n\n* `node`\n* `v8`\n* `boringssl`\n* `chromium`\n* `perfetto`\n* `icu`\n\n| Command              | Source Directory                   | Patch Directory                   |\n|:---------------------|:-----------------------------------|:----------------------------------|\n| e patches node       | `src/third_party/electron_node`    | `src/electron/patches/node`       |\n| e patches chromium   | `src`                              | `src/electron/patches/chromium`   |\n| e patches boringssl  | `src/third_party/boringssl/src`    | `src/electron/patches/boringssl`  |\n| e patches v8         | `src/v8`                           | `src/electron/patches/v8`         |\n| e patches perfetto   | `src/third_party/perfetto`         | `src/electron/patches/perfetto`   |\n| e patches icu        | `src/third_party/icu`              | `src/electron/patches/icu`        |\n\n[depot-tools]: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up\n[gdb]: https://web.eecs.umich.edu/~sugih/pointers/summary.html\n[gn-configs]: https://github.com/electron/electron/tree/main/build/args\n[gn]: https://chromium.googlesource.com/chromium/src/tools/gn/+/48062805e19b4697c5fbd926dc649c78b6aaa138/README.md\n[lldb]: https://lldb.llvm.org/use/tutorial.html\n[ninja]: https://ninja-build.org\n[nvm]: https://github.com/nvm-sh/nvm\n[platform-prerequisites]: https://electronjs.org/docs/development/build-instructions-gn#platform-prerequisites\n[sanitizers]: https://github.com/google/sanitizers\n\n### `e sanitize-config \u003cname\u003e`\n\n`e sanitize-config` updates and/or overwrites an existing config to conform to latest `build-tools` updates.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e sanitize-config --help\n```\n\nSometimes `build-tools` will make updates to its config requirements. In these events warnings will be output to console to inform you that `build-tools` has temporarily handled the issues. You can make these warnings go away either by manually updating your config files or by running this command to automatically overwrite the existing configs to update formatting.\n\n### `e shell`\n\n`e shell` launches a shell environment populated with build-tools' environment variables and context.\n\nDevelopers may for example find themselves wishing to access `gn` and `ninja` directly - instead of using `e d gn` to access that this command can be used. This also enables bash completion and the ability to copy-paste commands from Chromium docs without modification.\n\n```sh\n$ e shell\n# Launching build-tools shell with \"/bin/zsh\"\n# Running \"/bin/zsh\"\n```\n\n### `e backport \u003cPR\u003e`\n\n`e backport \u003cPR\u003e` assists with manual backport processes on the specified pull request.\n\nTo see all potential options for this command, run:\n\n```sh\n$ e backport --help\n```\n\nExample:\n\n```sh\n# select the PR to backport\ne backport 1234\n\n# select branch you want to backport PR to\n30-x-y\n\n# resolve any merge conflicts\ngit cherry-pick --continue\n\n# push changes\ngit push\n\n# create pull request\ne pr open --backport 1234\n```\n\n## Common Usage\n\n### Building a Specific Electron Version\n\n`e init` checks out the HEAD of the main branch. To build against a specific version of Electron, checkout that version with these commands:\n\n```sh\n# Change working directory to the Electron source directory\ncd `e show src`\n\n# Checkout the desired Electron version (in this case, 11.0.0)\ngit checkout tags/v11.0.0 -b v11.0.0\n\n# Sync dependencies with the current branch\ne sync\n\n# Build Electron\ne build\n```\n\n## Advanced Usage\n\n### Per-Session Active Configs\n\nIf you want your shell sessions to each have different active configs, try this in your `~/.profile` or `~/.zshrc` or `~/.bashrc`:\n\n```sh\nexport EVM_CURRENT_FILE=\"$(mktemp --tmpdir evm-current.XXXXXXXX.txt)\"\n```\n\nThis will create per-shell temporary files in which the active config file can be changed with `e use`.\n\n### Disabling Automatic Updates\n\nWith the default configuration, build-tools will automatically check for updates every 4 hours.\n\nYou can enable and disable these automatic updates with the following commands:\n\n```sh\n$ e auto-update enable\n$ e auto-update disable\n```\n\nRegardless of whether automatic updates are enabled, you can manually call the following command to immediately trigger an update.\n\n```sh\n$ e auto-update check\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectron%2Fbuild-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felectron%2Fbuild-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectron%2Fbuild-tools/lists"}