From e15e66f2297c9fa51e82a4cd352e394676302c07 Mon Sep 17 00:00:00 2001 From: George Xu <33054982+georgexu99@users.noreply.github.com> Date: Wed, 17 Aug 2022 10:54:49 -0700 Subject: [PATCH] docs: add dependencies and troubleshooting section to build-instructions (#35345) * docs: add dependencies and troubleshooting section to build-instructions * docs: update certifi description --- docs/development/build-instructions-gn.md | 13 +++++++ docs/development/build-instructions-macos.md | 40 ++++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/docs/development/build-instructions-gn.md b/docs/development/build-instructions-gn.md index cd955743df3b..e066fd6780f3 100644 --- a/docs/development/build-instructions-gn.md +++ b/docs/development/build-instructions-gn.md @@ -281,9 +281,22 @@ $ cd electron $ gclient sync -f ``` +This may also happen if you have checked out a branch (as opposed to having a detached head) in `electron/src/` +or some other dependency’s repository. If that is the case, a `git checkout --detach HEAD` in the appropriate repository should do the trick. + ### I'm being asked for a username/password for chromium-internal.googlesource.com If you see a prompt for `Username for 'https://chrome-internal.googlesource.com':` when running `gclient sync` on Windows, it's probably because the `DEPOT_TOOLS_WIN_TOOLCHAIN` environment variable is not set to 0. Open `Control Panel` → `System and Security` → `System` → `Advanced system settings` and add a system variable `DEPOT_TOOLS_WIN_TOOLCHAIN` with value `0`. This tells `depot_tools` to use your locally installed version of Visual Studio (by default, `depot_tools` will try to download a Google-internal version that only Googlers have access to). + +### `e` Module not found + +If `e` is not recognized despite running `npm i -g @electron/build-tools`, ie: + +```sh +Error: Cannot find module '/Users//.electron_build_tools/src/e' +``` + +We recommend installing Node through [nvm](https://github.com/nvm-sh/nvm). This allows for easier Node version management, and is often a fix for missing `e` modules. diff --git a/docs/development/build-instructions-macos.md b/docs/development/build-instructions-macos.md index fb4ef3049772..8ab4670d1971 100644 --- a/docs/development/build-instructions-macos.md +++ b/docs/development/build-instructions-macos.md @@ -13,6 +13,46 @@ Follow the guidelines below for building **Electron itself** on macOS, for the p * [node.js](https://nodejs.org) (external) * Python >= 3.7 +### Arm64-specific prerequisites + +* Rosetta 2 + * We recommend installing Rosetta if using dependencies that need to cross-compile on x64 and arm64 machines. Rosetta can be installed by using the softwareupdate command line tool. + * `$ softwareupdate --install-rosetta` + ## Building Electron See [Build Instructions: GN](build-instructions-gn.md). + +## Troubleshooting + +### Xcode "incompatible architecture" errors (MacOS arm64-specific) + +If both Xcode and Xcode command line tools are installed (`$ xcode -select --install`, or directly download the correct version [here](https://developer.apple.com/download/all/?q=command%20line%20tools)), but the stack trace says otherwise like so: + +```sh +xcrun: error: unable to load libxcrun +(dlopen(/Users//.electron_build_tools/third_party/Xcode/Xcode.app/Contents/Developer/usr/lib/libxcrun.dylib (http://xcode.app/Contents/Developer/usr/lib/libxcrun.dylib), 0x0005): + tried: '/Users//.electron_build_tools/third_party/Xcode/Xcode.app/Contents/Developer/usr/lib/libxcrun.dylib (http://xcode.app/Contents/Developer/usr/lib/libxcrun.dylib)' + (mach-o file, but is an incompatible architecture (have (x86_64), need (arm64e))), '/Users//.electron_build_tools/third_party/Xcode/Xcode-11.1.0.app/Contents/Developer/usr/lib/libxcrun.dylib (http://xcode-11.1.0.app/Contents/Developer/usr/lib/libxcrun.dylib)' (mach-o file, but is an incompatible architecture (have (x86_64), need (arm64e)))).` +``` + +If you are on arm64 architecture, the build script may be pointing to the wrong Xcode version (11.x.y doesn't support arm64). Navigate to `/Users//.electron_build_tools/third_party/Xcode/` and rename `Xcode-13.3.0.app` to `Xcode.app` to ensure the right Xcode version is used. + +### Certificates fail to verify + +installing [`certifi`](https://pypi.org/project/certifi/) will fix the following error: + +```sh +________ running 'python3 src/tools/clang/scripts/update.py' in '/Users//electron' +Downloading https://commondatastorage.googleapis.com/chromium-browser-clang/Mac_arm64/clang-llvmorg-15-init-15652-g89a99ec9-1.tgz + +Retrying in 5 s ... +Downloading https://commondatastorage.googleapis.com/chromium-browser-clang/Mac_arm64/clang-llvmorg-15-init-15652-g89a99ec9-1.tgz + +Retrying in 10 s ... +Downloading https://commondatastorage.googleapis.com/chromium-browser-clang/Mac_arm64/clang-llvmorg-15-init-15652-g89a99ec9-1.tgz + +Retrying in 20 s ... +``` + +This issue has to do with Python 3.6 using its [own](https://github.com/python/cpython/blob/560ea272b01acaa6c531cc7d94331b2ef0854be6/Mac/BuildScript/resources/ReadMe.rtf#L35) copy of OpenSSL in lieu of the deprecated Apple-supplied OpenSSL libraries. `certifi` adds a curated bundle of default root certificates. This issue is documented in the Electron repo [here](https://github.com/electron/build-tools/issues/55). Further information about this issue can be found [here](https://stackoverflow.com/questions/27835619/urllib-and-ssl-certificate-verify-failed-error) and [here](https://stackoverflow.com/questions/40684543/how-to-make-python-use-ca-certificates-from-mac-os-truststore).