From 43dbd1bdf8a48d798f4e392f921bde81a3430f4b Mon Sep 17 00:00:00 2001 From: David Sanders Date: Thu, 5 Nov 2020 14:12:43 -0800 Subject: [PATCH] chore: cleanup whitespace in docs (#26356) --- docs/api/app.md | 9 +++++--- docs/api/browser-window.md | 5 +++-- docs/api/client-request.md | 2 +- docs/api/command-line-switches.md | 2 ++ docs/api/context-bridge.md | 1 - docs/api/dialog.md | 12 +++++----- docs/api/environment-variables.md | 2 +- docs/api/frameless-window.md | 1 - docs/api/ipc-renderer.md | 2 ++ docs/api/menu-item.md | 1 + docs/api/message-channel-main.md | 1 + docs/api/native-theme.md | 3 +++ docs/api/process.md | 2 ++ docs/api/remote.md | 2 +- docs/api/session.md | 7 +++--- .../new-window-web-contents-event.md | 1 - docs/api/tray.md | 2 +- docs/api/web-contents.md | 2 ++ docs/api/web-frame.md | 1 + docs/api/window-open.md | 1 + docs/breaking-changes.md | 8 +++++++ docs/development/build-instructions-gn.md | 16 ++++++++++---- docs/development/clang-format.md | 6 ++--- .../debugging-instructions-macos-xcode.md | 3 +++ .../debugging-instructions-macos.md | 2 ++ docs/development/patches.md | 4 ++++ docs/development/pull-requests.md | 22 +++++++++---------- .../source-code-directory-structure.md | 3 ++- docs/development/testing.md | 5 +++++ docs/tutorial/application-distribution.md | 21 +++++++++--------- docs/tutorial/application-packaging.md | 1 - docs/tutorial/context-isolation.md | 1 - docs/tutorial/dark-mode.md | 1 + .../tutorial/debugging-main-process-vscode.md | 1 - docs/tutorial/devtools-extension.md | 1 + docs/tutorial/electron-versioning.md | 3 ++- docs/tutorial/in-app-purchases.md | 2 ++ docs/tutorial/installation.md | 5 +++++ docs/tutorial/online-offline-events.md | 1 + docs/tutorial/performance.md | 7 ++---- docs/tutorial/repl.md | 1 + docs/tutorial/security.md | 16 +++----------- docs/tutorial/support.md | 2 ++ docs/tutorial/windows-arm.md | 9 +++++++- docs/tutorial/windows-store-guide.md | 1 + 45 files changed, 129 insertions(+), 72 deletions(-) diff --git a/docs/api/app.md b/docs/api/app.md index 4b88e9b568..34ffbeba40 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -859,9 +859,10 @@ This method returns the application name of the default handler for the protocol minimum (e.g. `https://`). Returns `Promise` - Resolve with an object containing the following: - * `icon` NativeImage - the display icon of the app handling the protocol. - * `path` String - installation path of the app handling the protocol. - * `name` String - display name of the app handling the protocol. + +* `icon` NativeImage - the display icon of the app handling the protocol. +* `path` String - installation path of the app handling the protocol. +* `name` String - display name of the app handling the protocol. This method returns a promise that contains the application name, icon and path of the default handler for the protocol (aka URI scheme) of a URL. @@ -1091,6 +1092,7 @@ Changes the [Application User Model ID][app-user-model-id] to `id`. Sets the activation policy for a given app. Activation policy types: + * 'regular' - The application is an ordinary app that appears in the Dock and may have a user interface. * 'accessory' - The application doesn’t appear in the Dock and doesn’t have a menu bar, but it may be activated programmatically or by clicking on one of its windows. * 'prohibited' - The application doesn’t appear in the Dock and may not create windows or be activated. @@ -1142,6 +1144,7 @@ For `infoType` equal to `complete`: For `infoType` equal to `basic`: Promise is fulfilled with `Object` containing fewer attributes than when requested with `complete`. Here's an example of basic response: + ```js { auxAttributes: diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 3519bff93f..d0cdc2d13c 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -468,6 +468,7 @@ window.onbeforeunload = (e) => { e.returnValue = false // equivalent to `return false` but not recommended } ``` + _**Note**: There is a subtle difference between the behaviors of `window.onbeforeunload = handler` and `window.addEventListener('beforeunload', handler)`. It is recommended to always set the `event.returnValue` explicitly, instead of only returning a value, as the former works more consistently within Electron._ #### Event: 'closed' @@ -859,7 +860,7 @@ A `Boolean` property that determines whether the menu bar should be visible. **Note:** If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single `Alt` key. -#### `win.kiosk` +#### `win.kiosk` A `Boolean` property that determines whether the window is in kiosk mode. @@ -1049,7 +1050,7 @@ Returns `Boolean` - Whether the window is in normal state (not maximized, not mi * `aspectRatio` Float - The aspect ratio to maintain for some portion of the content view. - * `extraSize` [Size](structures/size.md) (optional) _macOS_ - The extra size not to be included while +* `extraSize` [Size](structures/size.md) (optional) _macOS_ - The extra size not to be included while maintaining the aspect ratio. This will make a window maintain an aspect ratio. The extra size allows a diff --git a/docs/api/client-request.md b/docs/api/client-request.md index 0bbfc89d64..786d690421 100644 --- a/docs/api/client-request.md +++ b/docs/api/client-request.md @@ -98,6 +98,7 @@ request.on('login', (authInfo, callback) => { callback('username', 'password') }) ``` + Providing empty credentials will cancel the request and report an authentication error on the response object: @@ -139,7 +140,6 @@ Emitted as the last event in the HTTP request-response transaction. The `close` event indicates that no more events will be emitted on either the `request` or `response` objects. - #### Event: 'redirect' Returns: diff --git a/docs/api/command-line-switches.md b/docs/api/command-line-switches.md index 6570758cd2..4d9deec609 100644 --- a/docs/api/command-line-switches.md +++ b/docs/api/command-line-switches.md @@ -64,6 +64,7 @@ Forces the maximum disk space to be used by the disk cache, in bytes. ### --enable-api-filtering-logging Enables caller stack logging for the following APIs (filtering events): + - `desktopCapturer.getSources()` / `desktop-capturer-get-sources` - `remote.require()` / `remote-require` - `remote.getGlobal()` / `remote-get-builtin` @@ -227,6 +228,7 @@ See the [Debugging the Main Process][debugging-main-process] guide for more deta Aliased to `--debug[=[host:]port`. ### --inspect-publish-uid=stderr,http + Specify ways of the inspector web socket url exposure. By default inspector websocket url is available in stderr and under /json/list endpoint on http://host:port/json/list. diff --git a/docs/api/context-bridge.md b/docs/api/context-bridge.md index cd5eb578c1..c87f3a4291 100644 --- a/docs/api/context-bridge.md +++ b/docs/api/context-bridge.md @@ -108,5 +108,4 @@ has been included below for completeness: | [Cloneable Types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) | Simple | ✅ | ✅ | See the linked document on cloneable types | | `Symbol` | N/A | ❌ | ❌ | Symbols cannot be copied across contexts so they are dropped | - If the type you care about is not in the above table, it is probably not supported. diff --git a/docs/api/dialog.md b/docs/api/dialog.md index d1386a6b29..483ff271d2 100644 --- a/docs/api/dialog.md +++ b/docs/api/dialog.md @@ -205,9 +205,10 @@ The `filters` specifies an array of file types that can be displayed, see * `securityScopedBookmarks` Boolean (optional) _macOS_ _mas_ - Create a [security scoped bookmark](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) when packaged for the Mac App Store. If this option is enabled and the file doesn't already exist a blank file will be created at the chosen path. Returns `Promise` - Resolve with an object containing the following: - * `canceled` Boolean - whether or not the dialog was canceled. - * `filePath` String (optional) - If the dialog is canceled, this will be `undefined`. - * `bookmark` String (optional) _macOS_ _mas_ - Base64 encoded string which contains the security scoped bookmark data for the saved file. `securityScopedBookmarks` must be enabled for this to be present. (For return values, see [table here](#bookmarks-array).) + +* `canceled` Boolean - whether or not the dialog was canceled. +* `filePath` String (optional) - If the dialog is canceled, this will be `undefined`. +* `bookmark` String (optional) _macOS_ _mas_ - Base64 encoded string which contains the security scoped bookmark data for the saved file. `securityScopedBookmarks` must be enabled for this to be present. (For return values, see [table here](#bookmarks-array).) The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. @@ -302,8 +303,9 @@ If `browserWindow` is not shown dialog will not be attached to it. In such case via `Alt-W` on Windows and Linux. Returns `Promise` - resolves with a promise containing the following properties: - * `response` Number - The index of the clicked button. - * `checkboxChecked` Boolean - The checked state of the checkbox if + +* `response` Number - The index of the clicked button. +* `checkboxChecked` Boolean - The checked state of the checkbox if `checkboxLabel` was set. Otherwise `false`. Shows a message box. diff --git a/docs/api/environment-variables.md b/docs/api/environment-variables.md index 943f44b499..12103f8eb0 100644 --- a/docs/api/environment-variables.md +++ b/docs/api/environment-variables.md @@ -105,6 +105,7 @@ Don't use the global menu bar on Linux. Set the trash implementation on Linux. Default is `gio`. Options: + * `gvfs-trash` * `trash-cli` * `kioclient5` @@ -115,7 +116,6 @@ Options: The following environment variables are intended primarily for development and debugging purposes. - ### `ELECTRON_ENABLE_LOGGING` Prints Chrome's internal logging to the console. diff --git a/docs/api/frameless-window.md b/docs/api/frameless-window.md index 0c84ec3eb1..b7d893d4b2 100644 --- a/docs/api/frameless-window.md +++ b/docs/api/frameless-window.md @@ -12,7 +12,6 @@ options on the [`BrowserWindow`](browser-window.md) class. To create a frameless window, you need to set `frame` to `false` in [BrowserWindow](browser-window.md)'s `options`: - ```javascript const { BrowserWindow } = require('electron') const win = new BrowserWindow({ width: 800, height: 600, frame: false }) diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md index 4925e05a73..b14152d6ef 100644 --- a/docs/api/ipc-renderer.md +++ b/docs/api/ipc-renderer.md @@ -93,6 +93,7 @@ The main process should listen for `channel` with [`ipcMain.handle()`](ipc-main.md#ipcmainhandlechannel-listener). For example: + ```javascript // Renderer process ipcRenderer.invoke('some-name', someArgument).then((result) => { @@ -149,6 +150,7 @@ The transferred `MessagePort` objects will be available in the main process as property of the emitted event. For example: + ```js // Renderer process const { port1, port2 } = new MessageChannel() diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md index fe5bc12c18..2041d76a6a 100644 --- a/docs/api/menu-item.md +++ b/docs/api/menu-item.md @@ -138,6 +138,7 @@ A `String` indicating the item's visible label. A `Function` that is fired when the MenuItem receives a click event. It can be called with `menuItem.click(event, focusedWindow, focusedWebContents)`. + * `event` [KeyboardEvent](structures/keyboard-event.md) * `focusedWindow` [BrowserWindow](browser-window.md) * `focusedWebContents` [WebContents](web-contents.md) diff --git a/docs/api/message-channel-main.md b/docs/api/message-channel-main.md index 3d354bcc02..86cdce4e50 100644 --- a/docs/api/message-channel-main.md +++ b/docs/api/message-channel-main.md @@ -12,6 +12,7 @@ channel messaging. Process: [Main](../glossary.md#main-process) Example: + ```js // Main process const { port1, port2 } = new MessageChannelMain() diff --git a/docs/api/native-theme.md b/docs/api/native-theme.md index 166e0125a8..f7df167cbc 100644 --- a/docs/api/native-theme.md +++ b/docs/api/native-theme.md @@ -34,6 +34,7 @@ Setting this property to `system` will remove the override and everything will be reset to the OS default. By default `themeSource` is `system`. Settings this property to `dark` will have the following effects: + * `nativeTheme.shouldUseDarkColors` will be `true` when accessed * Any UI Electron renders on Linux and Windows including context menus, devtools, etc. will use the dark UI. * Any UI the OS renders on macOS including menus, window frames, etc. will use the dark UI. @@ -41,6 +42,7 @@ Settings this property to `dark` will have the following effects: * The `updated` event will be emitted Settings this property to `light` will have the following effects: + * `nativeTheme.shouldUseDarkColors` will be `false` when accessed * Any UI Electron renders on Linux and Windows including context menus, devtools, etc. will use the light UI. * Any UI the OS renders on macOS including menus, window frames, etc. will use the light UI. @@ -49,6 +51,7 @@ Settings this property to `light` will have the following effects: The usage of this property should align with a classic "dark mode" state machine in your application where the user has three options. + * `Follow OS` --> `themeSource = 'system'` * `Dark Mode` --> `themeSource = 'dark'` * `Light Mode` --> `themeSource = 'light'` diff --git a/docs/api/process.md b/docs/api/process.md index db15496916..d3de0264c4 100644 --- a/docs/api/process.md +++ b/docs/api/process.md @@ -11,6 +11,7 @@ It adds the following events, properties, and methods: ## Sandbox In sandboxed renderers the `process` object contains only a subset of the APIs: + - `crash()` - `hang()` - `getCreationTime()` @@ -104,6 +105,7 @@ A `Boolean` that controls whether or not deprecations printed to `stderr` includ This property is instead of the `--trace-deprecation` command line flag. ### `process.traceProcessWarnings` + A `Boolean` that controls whether or not process warnings printed to `stderr` include their stack trace. Setting this to `true` will print stack traces for process warnings (including deprecations). This property is instead of the `--trace-warnings` command diff --git a/docs/api/remote.md b/docs/api/remote.md index 62b9499f49..01f9636735 100644 --- a/docs/api/remote.md +++ b/docs/api/remote.md @@ -35,6 +35,7 @@ win.loadURL('https://github.com') you can use [webContents.executeJavaScript](web-contents.md#contentsexecutejavascriptcode-usergesture). **Note:** The remote module can be disabled for security reasons in the following contexts: + - [`BrowserWindow`](browser-window.md) - by setting the `enableRemoteModule` option to `false`. - [``](webview-tag.md) - by setting the `enableremotemodule` attribute to `false`. @@ -207,7 +208,6 @@ module.exports = 'bar' const foo = require('electron').remote.require('./foo') // bar ``` - ### `remote.process` _Readonly_ A `NodeJS.Process` object. The `process` object in the main process. This is the same as diff --git a/docs/api/session.md b/docs/api/session.md index 53a451600d..2edb3620ce 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -100,10 +100,11 @@ Returns: Emitted after an extension is loaded. This occurs whenever an extension is added to the "enabled" set of extensions. This includes: + - Extensions being loaded from `Session.loadExtension`. - Extensions being reloaded: - * from a crash. - * if the extension requested it ([`chrome.runtime.reload()`](https://developer.chrome.com/extensions/runtime#method-reload)). + * from a crash. + * if the extension requested it ([`chrome.runtime.reload()`](https://developer.chrome.com/extensions/runtime#method-reload)). #### Event: 'extension-unloaded' @@ -354,7 +355,7 @@ The `proxyBypassRules` is a comma separated list of rules described below: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99" - * `"." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]` +* `"." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]` Match a particular domain suffix. diff --git a/docs/api/structures/new-window-web-contents-event.md b/docs/api/structures/new-window-web-contents-event.md index 23f9679a57..b56da02603 100644 --- a/docs/api/structures/new-window-web-contents-event.md +++ b/docs/api/structures/new-window-web-contents-event.md @@ -1,4 +1,3 @@ # NewWindowWebContentsEvent Object extends `Event` * `newGuest` BrowserWindow (optional) - diff --git a/docs/api/tray.md b/docs/api/tray.md index ce63c3e7d5..1a6b9cf9a5 100644 --- a/docs/api/tray.md +++ b/docs/api/tray.md @@ -52,12 +52,12 @@ app.whenReady().then(() => { appIcon.setContextMenu(contextMenu) }) ``` + * On Windows it is recommended to use `ICO` icons to get best visual effects. If you want to keep exact same behaviors on all platforms, you should not rely on the `click` event and always attach a context menu to the tray icon. - ### `new Tray(image, [guid])` * `image` ([NativeImage](native-image.md) | String) diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 28202256c9..89f3555673 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -438,6 +438,7 @@ Emitted when the window leaves a full-screen state triggered by HTML API. #### Event: 'zoom-changed' Returns: + * `event` Event * `zoomDirection` String - Can be `in` or `out`. @@ -1690,6 +1691,7 @@ process by accessing the `ports` property of the emitted event. When they arrive in the renderer, they will be native DOM `MessagePort` objects. For example: + ```js // Main process const { port1, port2 } = new MessageChannelMain() diff --git a/docs/api/web-frame.md b/docs/api/web-frame.md index 2cf00b71f7..9891c5d09a 100644 --- a/docs/api/web-frame.md +++ b/docs/api/web-frame.md @@ -175,6 +175,7 @@ reject and the `result` would be `undefined`. This is because Chromium does not dispatch errors of isolated worlds to foreign worlds. ### `webFrame.setIsolatedWorldInfo(worldId, info)` + * `worldId` Integer - The ID of the world to run the javascript in, `0` is the default world, `999` is the world used by Electrons `contextIsolation` feature. Chrome extensions reserve the range of IDs in `[1 << 20, 1 << 29)`. You can provide any integer here. * `info` Object * `securityOrigin` String (optional) - Security origin for the isolated world. diff --git a/docs/api/window-open.md b/docs/api/window-open.md index 1cc0982e91..35bd0cffd2 100644 --- a/docs/api/window-open.md +++ b/docs/api/window-open.md @@ -27,6 +27,7 @@ The `features` string follows the format of standard browser, but each feature has to be a field of `BrowserWindow`'s options. These are the features you can set via `features` string: `zoomFactor`, `nodeIntegration`, `preload`, `javascript`, `contextIsolation`, `webviewTag`. For example: + ```js window.open('https://github.com', '_blank', 'nodeIntegration=no') ``` diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index 6e325d1a49..7b1bfb592e 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -301,6 +301,7 @@ messages, but also brings some breaking changes in behavior. - Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any such values, over IPC will now throw an exception, instead of silently converting the functions to `undefined`. + ```js // Previously: ipcRenderer.send('channel', { value: 3, someFunction: () => {} }) @@ -310,6 +311,7 @@ ipcRenderer.send('channel', { value: 3, someFunction: () => {} }) ipcRenderer.send('channel', { value: 3, someFunction: () => {} }) // => throws Error("() => {} could not be cloned.") ``` + - `NaN`, `Infinity` and `-Infinity` will now be correctly serialized, instead of being converted to `null`. - Objects containing cyclic references will now be correctly serialized, @@ -327,6 +329,7 @@ ipcRenderer.send('channel', { value: 3, someFunction: () => {} }) - Node.js `Buffer` objects will be transferred as `Uint8Array`s. You can convert a `Uint8Array` back to a Node.js `Buffer` by wrapping the underlying `ArrayBuffer`: + ```js Buffer.from(value.buffer, value.byteOffset, value.byteLength) ``` @@ -462,6 +465,7 @@ the folder, similarly to Chrome, Firefox, and Edge ([link to MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory)). As an illustration, take a folder with this structure: + ```console folder ├── file1 @@ -470,11 +474,13 @@ folder ``` In Electron <=6, this would return a `FileList` with a `File` object for: + ```console path/to/folder ``` In Electron 7, this now returns a `FileList` with a `File` object for: + ```console /path/to/folder/file3 /path/to/folder/file2 @@ -629,7 +635,9 @@ webFrame.setIsolatedWorldInfo( ``` ### API Changed: `webFrame.setSpellCheckProvider` now takes an asynchronous callback + The `spellCheck` callback is now asynchronous, and `autoCorrectWord` parameter has been removed. + ```js // Deprecated webFrame.setSpellCheckProvider('en-US', true, { diff --git a/docs/development/build-instructions-gn.md b/docs/development/build-instructions-gn.md index d8fb0ef234..49d603e471 100644 --- a/docs/development/build-instructions-gn.md +++ b/docs/development/build-instructions-gn.md @@ -6,9 +6,9 @@ Follow the guidelines below for building Electron. Check the build prerequisites for your platform before proceeding - * [macOS](build-instructions-macos.md#prerequisites) - * [Linux](build-instructions-linux.md#prerequisites) - * [Windows](build-instructions-windows.md#prerequisites) +* [macOS](build-instructions-macos.md#prerequisites) +* [Linux](build-instructions-linux.md#prerequisites) +* [Windows](build-instructions-windows.md#prerequisites) ## Build Tools @@ -74,6 +74,7 @@ Running `gclient sync -f` ensures that all dependencies required to build Electron match that file. So, in order to pull, you'd run the following commands: + ```sh $ cd src/electron $ git pull @@ -91,6 +92,7 @@ $ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\") $GN_EX ``` Or on Windows (without the optional argument): + ```sh $ cd src $ set CHROMIUM_BUILDTOOLS_PATH=%cd%\buildtools @@ -124,11 +126,13 @@ $ gn gen out/Release --args="import(\"//electron/build/args/release.gn\") $GN_EX Nota Bene: This will also take a while and probably heat up your lap. For the testing configuration: + ```sh $ ninja -C out/Testing electron ``` For the release configuration: + ```sh $ ninja -C out/Release electron ``` @@ -156,11 +160,13 @@ $ ./out/Testing/electron ### Packaging On linux, first strip the debugging and symbol information: + ```sh electron/script/strip-binaries.py -d out/Release ``` To package the electron build as a distributable zip file: + ```sh ninja -C out/Release electron:electron_dist_zip ``` @@ -193,6 +199,7 @@ and [`target_cpu`][target_cpu values]. [target_cpu values]: https://gn.googlesource.com/gn/+/master/docs/reference.md#built_in-predefined-variables-target_cpu_the-desired-cpu-architecture-for-the-build-possible-values #### Windows on Arm (experimental) + To cross-compile for Windows on Arm, [follow Chromium's guide](https://chromium.googlesource.com/chromium/src/+/refs/heads/master/docs/windows_build_instructions.md#Visual-Studio) to get the necessary dependencies, SDK and libraries, then build with `ELECTRON_BUILDING_WOA=1` in your environment before running `gclient sync`. ```bat @@ -201,6 +208,7 @@ gclient sync -f --with_branch_heads --with_tags ``` Or (if using PowerShell): + ```powershell $env:ELECTRON_BUILDING_WOA=1 gclient sync -f --with_branch_heads --with_tags @@ -208,7 +216,6 @@ gclient sync -f --with_branch_heads --with_tags Next, run `gn gen` as above with `target_cpu="arm64"`. - ## Tests To run the tests, you'll first need to build the test modules against the @@ -274,6 +281,7 @@ $ gclient sync -f ``` ### 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 diff --git a/docs/development/clang-format.md b/docs/development/clang-format.md index a769e7aed9..410a721bd5 100644 --- a/docs/development/clang-format.md +++ b/docs/development/clang-format.md @@ -30,6 +30,6 @@ run `git-clang-format HEAD~1`. See `git-clang-format -h` for more details. You can also integrate `clang-format` directly into your favorite editors. For further guidance on setting up editor integration, see these pages: - * [Atom](https://atom.io/packages/clang-format) - * [Vim & Emacs](https://clang.llvm.org/docs/ClangFormat.html#vim-integration) - * [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format) +* [Atom](https://atom.io/packages/clang-format) +* [Vim & Emacs](https://clang.llvm.org/docs/ClangFormat.html#vim-integration) +* [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format) diff --git a/docs/development/debugging-instructions-macos-xcode.md b/docs/development/debugging-instructions-macos-xcode.md index ac08f3dfd5..7e88a92bba 100644 --- a/docs/development/debugging-instructions-macos-xcode.md +++ b/docs/development/debugging-instructions-macos-xcode.md @@ -1,10 +1,13 @@ ## Debugging with XCode ### Generate xcode project for debugging sources (cannot build code from xcode) + Run `gn gen` with the --ide=xcode argument. + ```sh $ gn gen out/Testing --ide=xcode ``` + This will generate the electron.ninja.xcworkspace. You will have to open this workspace to set breakpoints and inspect. diff --git a/docs/development/debugging-instructions-macos.md b/docs/development/debugging-instructions-macos.md index 454988b78b..d3af2d2a1a 100644 --- a/docs/development/debugging-instructions-macos.md +++ b/docs/development/debugging-instructions-macos.md @@ -24,6 +24,7 @@ you prefer a graphical interface. debugging C, Objective-C and C++ on the desktop and iOS devices and simulator. * **.lldbinit**: Create or edit `~/.lldbinit` to allow Chromium code to be properly source-mapped. + ```text command script import ~/electron/src/tools/lldb/lldbinit.py ``` @@ -120,6 +121,7 @@ Now, if you open up Electron's developer tools and call `setName`, you will once breakpoint. ### Further Reading + LLDB is a powerful tool with a great documentation. To learn more about it, consider Apple's debugging documentation, for instance the [LLDB Command Structure Reference][lldb-command-structure] or the introduction to [Using LLDB as a Standalone Debugger][lldb-standalone]. diff --git a/docs/development/patches.md b/docs/development/patches.md index 60c272d4b2..634a35c355 100644 --- a/docs/development/patches.md +++ b/docs/development/patches.md @@ -41,6 +41,7 @@ To help manage these patch sets, we provide two tools: `git-import-patches` and ### Usage #### Adding a new patch + ```bash $ cd src/third_party/electron_node $ vim some/code/file.cc @@ -53,6 +54,7 @@ $ ../../electron/script/git-export-patches -o ../../electron/patches/node Re-exporting patches will sometimes cause shasums in unrelated patches to change. This is generally harmless and can be ignored (but go ahead and add those changes to your PR, it'll stop them from showing up for other people). #### Editing an existing patch + ```bash $ cd src/v8 $ vim some/code/file.cc @@ -64,6 +66,7 @@ $ ../electron/script/git-export-patches -o ../electron/patches/v8 ``` #### Removing a patch + ```bash $ vim src/electron/patches/node/.patches # Delete the line with the name of the patch you want to remove @@ -76,6 +79,7 @@ $ ../../electron/script/git-export-patches -o ../../electron/patches/node Note that `git-import-patches` will mark the commit that was `HEAD` when it was run as `refs/patches/upstream-head`. This lets you keep track of which commits are from Electron patches (those that come after `refs/patches/upstream-head`) and which commits are in upstream (those before `refs/patches/upstream-head`). #### Resolving conflicts + When updating an upstream dependency, patches may fail to apply cleanly. Often, the conflict can be resolved automatically by git with a 3-way merge. You can instruct `git-import-patches` to use the 3-way merge algorithm by passing the `-3` argument: ```bash diff --git a/docs/development/pull-requests.md b/docs/development/pull-requests.md index b48dea4ce0..b3f8350ead 100644 --- a/docs/development/pull-requests.md +++ b/docs/development/pull-requests.md @@ -35,6 +35,7 @@ $ git fetch upstream Build steps and dependencies differ slightly depending on your operating system. See these detailed guides on building Electron locally: + * [Building on macOS](https://electronjs.org/docs/development/build-instructions-macos) * [Building on Linux](https://electronjs.org/docs/development/build-instructions-linux) * [Building on Windows](https://electronjs.org/docs/development/build-instructions-windows) @@ -96,16 +97,16 @@ Examples of commit messages with semantic prefixes: Common prefixes: - - fix: A bug fix - - feat: A new feature - - docs: Documentation changes - - test: Adding missing tests or correcting existing tests - - build: Changes that affect the build system - - ci: Changes to our CI configuration files and scripts - - perf: A code change that improves performance - - refactor: A code change that neither fixes a bug nor adds a feature - - style: Changes that do not affect the meaning of the code (linting) - - vendor: Bumping a dependency like libchromiumcontent or node +- fix: A bug fix +- feat: A new feature +- docs: Documentation changes +- test: Adding missing tests or correcting existing tests +- build: Changes that affect the build system +- ci: Changes to our CI configuration files and scripts +- perf: A code change that improves performance +- refactor: A code change that neither fixes a bug nor adds a feature +- style: Changes that do not affect the meaning of the code (linting) +- vendor: Bumping a dependency like libchromiumcontent or node Other things to keep in mind when writing a commit message: @@ -257,4 +258,3 @@ failure must be manually inspected to determine the cause. CI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests. - diff --git a/docs/development/source-code-directory-structure.md b/docs/development/source-code-directory-structure.md index f73f31312d..fffab3d525 100644 --- a/docs/development/source-code-directory-structure.md +++ b/docs/development/source-code-directory-structure.md @@ -90,6 +90,7 @@ Electron * **out** - Temporary output directory of `ninja`. * **script** - Scripts used for development purpose like building, packaging, testing, etc. + ```diff script/ - The set of all scripts Electron runs for a variety of purposes. ├── codesign/ - Fakes codesigning for Electron apps; used for testing. @@ -98,8 +99,8 @@ script/ - The set of all scripts Electron runs for a variety of purposes. ├── notes/ - Generates release notes for new Electron versions. └── uploaders/ - Uploads various release-related files during release. ``` + * **tools** - Helper scripts used by GN files. * Scripts put here should never be invoked by users directly, unlike those in `script`. * **typings** - TypeScript typings for Electron's internal code. * **vendor** - Source code for some third party dependencies. - diff --git a/docs/development/testing.md b/docs/development/testing.md index 73b24c415d..aae9f9c76f 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -56,10 +56,13 @@ would run `npm run test -- -g ipc`. 1. Visual Studio 2019 must be installed. 2. Node headers have to be compiled for your configuration. + ```powershell ninja -C out\Testing third_party\electron_node:headers ``` + 3. The electron.lib has to be copied as node.lib. + ```powershell cd out\Testing mkdir gen\node_headers\Release @@ -69,6 +72,7 @@ would run `npm run test -- -g ipc`. #### Missing fonts [Some Windows 10 devices](https://docs.microsoft.com/en-us/typography/fonts/windows_10_font_list) do not ship with the Meiryo font installed, which may cause a font fallback test to fail. To install Meiryo: + 1. Push the Windows key and search for _Manage optional features_. 2. Click _Add a feature_. 3. Select _Japanese Supplemental Fonts_ and click _Install_. @@ -80,5 +84,6 @@ devices with Hi-DPI screen settings due to floating point precision errors. To run these tests correctly, make sure the device is set to 100% scaling. To configure display scaling: + 1. Push the Windows key and search for _Display settings_. 2. Under _Scale and layout_, make sure that the device is set to 100%. diff --git a/docs/tutorial/application-distribution.md b/docs/tutorial/application-distribution.md index 9a49076b9c..b74f6a1956 100644 --- a/docs/tutorial/application-distribution.md +++ b/docs/tutorial/application-distribution.md @@ -9,6 +9,7 @@ To distribute your app with Electron, you need to package and rebrand it. The ea These tools will take care of all the steps you need to take to end up with a distributable Electron applications, such as packaging your application, rebranding the executable, setting the right icons and optionally creating installers. ## Manual distribution + You can also choose to manually get your app ready for distribution. The steps needed to do this are outlined below. To distribute your app with Electron, you need to download Electron's [prebuilt @@ -143,16 +144,16 @@ we appreciate your help. 3. Set the following Environment Variables: - * `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub - * `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` - - the place where you'll upload Node.js headers as well as symbols - * `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset - and `surf-build` will do CI-type checks, appropriate to run for every - pull request. - * `CI` - Set to `true` or else it will fail - * `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN` - * `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues - * `TARGET_ARCH` - set to `ia32` or `x64` + * `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub + * `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` - + the place where you'll upload Node.js headers as well as symbols + * `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset + and `surf-build` will do CI-type checks, appropriate to run for every + pull request. + * `CI` - Set to `true` or else it will fail + * `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN` + * `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues + * `TARGET_ARCH` - set to `ia32` or `x64` 4. In `script/upload.py`, you _must_ set `ELECTRON_REPO` to your fork (`MYORG/electron`), especially if you are a contributor to Electron proper. diff --git a/docs/tutorial/application-packaging.md b/docs/tutorial/application-packaging.md index c4dced7ece..e0c782fe7d 100644 --- a/docs/tutorial/application-packaging.md +++ b/docs/tutorial/application-packaging.md @@ -192,4 +192,3 @@ and should be shipped together with the `app.asar` archive. [electron-packager]: https://github.com/electron/electron-packager [electron-forge]: https://github.com/electron-userland/electron-forge [electron-builder]: https://github.com/electron-userland/electron-builder - diff --git a/docs/tutorial/context-isolation.md b/docs/tutorial/context-isolation.md index 20d14a6428..1320c1affd 100644 --- a/docs/tutorial/context-isolation.md +++ b/docs/tutorial/context-isolation.md @@ -67,4 +67,3 @@ contextBridge.exposeInMainWorld('myAPI', { loadPreferences: () => ipcRenderer.invoke('load-prefs') }) ``` - diff --git a/docs/tutorial/dark-mode.md b/docs/tutorial/dark-mode.md index d75680e02b..e27d3f2d26 100644 --- a/docs/tutorial/dark-mode.md +++ b/docs/tutorial/dark-mode.md @@ -124,6 +124,7 @@ Depending on the received event, we update the property to apply the desired theme on the system's native UI elements (e.g. context menus) and propagate the preferred color scheme to the Renderer process: + * Upon receiving `dark-mode:toggle`, we check if the dark theme is currently active using the `nativeTheme.shouldUseDarkColors` property, and set the `themeSource` to the opposite theme. diff --git a/docs/tutorial/debugging-main-process-vscode.md b/docs/tutorial/debugging-main-process-vscode.md index 75bc603f3b..b13d79ddf5 100644 --- a/docs/tutorial/debugging-main-process-vscode.md +++ b/docs/tutorial/debugging-main-process-vscode.md @@ -29,7 +29,6 @@ $ code electron-quick-start } ``` - ### 3. Debugging Set some breakpoints in `main.js`, and start debugging in the [Debug View](https://code.visualstudio.com/docs/editor/debugging). You should be able to hit the breakpoints. diff --git a/docs/tutorial/devtools-extension.md b/docs/tutorial/devtools-extension.md index 135f8e0f82..6adea0c38c 100644 --- a/docs/tutorial/devtools-extension.md +++ b/docs/tutorial/devtools-extension.md @@ -29,6 +29,7 @@ Using the [React Developer Tools][react-devtools] as example: * on macOS it is `~/Library/Application Support/Google/Chrome/Default/Extensions`. 1. Pass the location of the extension to `BrowserWindow.addDevToolsExtension` API, for the React Developer Tools, it is something like: + ```javascript const path = require('path') const os = require('os') diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index a847714f04..decd85f5d0 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -48,7 +48,6 @@ Below is a table explicitly mapping types of changes to their corresponding cate | Node.js major version updates | Node.js minor version updates | Node.js patch version updates | | Chromium version updates | | fix-related chromium patches | - Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches. # Stabilization Branches @@ -118,6 +117,7 @@ A few examples of how various semver ranges will pick up new releases: ![](../images/versioning-sketch-7.png) # Missing Features: Alphas + Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself. As a future consideration, we may introduce one or both of the following: @@ -125,6 +125,7 @@ As a future consideration, we may introduce one or both of the following: * alpha releases that have looser stability constraints to betas; for example it would be allowable to admit new features while a stability channel is in _alpha_ # Feature Flags + Feature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or **soft branch** must have the following properties: * it is enabled/disabled either at runtime, or build-time; we do not support the concept of a request-scoped feature flag diff --git a/docs/tutorial/in-app-purchases.md b/docs/tutorial/in-app-purchases.md index 848ea6560c..f9c2e9381e 100644 --- a/docs/tutorial/in-app-purchases.md +++ b/docs/tutorial/in-app-purchases.md @@ -3,11 +3,13 @@ ## Preparing ### Paid Applications Agreement + If you haven't already, you’ll need to sign the Paid Applications Agreement and set up your banking and tax information in iTunes Connect. [iTunes Connect Developer Help: Agreements, tax, and banking overview](https://help.apple.com/itunes-connect/developer/#/devb6df5ee51) ### Create Your In-App Purchases + Then, you'll need to configure your in-app purchases in iTunes Connect, and include details such as name, pricing, and description that highlights the features and functionality of your in-app purchase. [iTunes Connect Developer Help: Create an in-app purchase](https://help.apple.com/itunes-connect/developer/#/devae49fb316) diff --git a/docs/tutorial/installation.md b/docs/tutorial/installation.md index 1292593621..c308ccf2be 100644 --- a/docs/tutorial/installation.md +++ b/docs/tutorial/installation.md @@ -45,6 +45,7 @@ value, plus additional environment variables depending on your host system's Nod * [Before Node 10][proxy-env] ## Custom Mirrors and Caches + During installation, the `electron` module will call out to [`@electron/get`][electron-get] to download prebuilt binaries of Electron for your platform. It will do so by contacting GitHub's @@ -55,6 +56,7 @@ If you are unable to access GitHub or you need to provide a custom build, you can do so by either providing a mirror or an existing cache directory. #### Mirror + You can use environment variables to override the base URL, the path at which to look for Electron binaries, and the binary filename. The URL used by `@electron/get` is composed as follows: @@ -84,6 +86,7 @@ The above configuration will download from URLs such as `https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip`. #### Cache + Alternatively, you can override the local cache. `@electron/get` will cache downloaded binaries in a local directory to not stress your network. You can use that cache folder to provide custom builds of Electron or to avoid making contact @@ -126,12 +129,14 @@ a text file. A typical cache might look like this: ``` ## Skip binary download + When installing the `electron` NPM package, it automatically downloads the electron binary. This can sometimes be unnecessary, e.g. in a CI environment, when testing another component. To prevent the binary from being downloaded when you install all npm dependencies you can set the environment variable `ELECTRON_SKIP_BINARY_DOWNLOAD`. E.g.: + ```sh ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install ``` diff --git a/docs/tutorial/online-offline-events.md b/docs/tutorial/online-offline-events.md index 26be09892b..c63e90ff9e 100644 --- a/docs/tutorial/online-offline-events.md +++ b/docs/tutorial/online-offline-events.md @@ -8,6 +8,7 @@ detection can be implemented in the Renderer process using the attribute, part of standard HTML5 API. The `navigator.onLine` attribute returns: + * `false` if all network requests are guaranteed to fail (e.g. when disconnected from the network). * `true` in all other cases. diff --git a/docs/tutorial/performance.md b/docs/tutorial/performance.md index f90bd99b9e..c920f2e8dc 100644 --- a/docs/tutorial/performance.md +++ b/docs/tutorial/performance.md @@ -46,8 +46,8 @@ at once, consider the [Chrome Tracing](https://www.chromium.org/developers/how-t ### Recommended Reading - * [Get Started With Analyzing Runtime Performance][chrome-devtools-tutorial] - * [Talk: "Visual Studio Code - The First Second"][vscode-first-second] +* [Get Started With Analyzing Runtime Performance][chrome-devtools-tutorial] +* [Talk: "Visual Studio Code - The First Second"][vscode-first-second] ## Checklist @@ -264,7 +264,6 @@ core Node.js modules (like `fs` or `child_process`) offer a synchronous or an asynchronous version, you should prefer the asynchronous and non-blocking variant. - ## 4) Blocking the renderer process Since Electron ships with a current version of Chrome, you can make use of the @@ -301,7 +300,6 @@ some caveats to consider – consult Electron's for any operation that requires a lot of CPU power for an extended period of time. - ## 5) Unnecessary polyfills One of Electron's great benefits is that you know exactly which engine will @@ -340,7 +338,6 @@ If you're using a transpiler/compiler like TypeScript, examine its configuration and ensure that you're targeting the latest ECMAScript version supported by Electron. - ## 6) Unnecessary or blocking network requests Avoid fetching rarely changing resources from the internet if they could easily diff --git a/docs/tutorial/repl.md b/docs/tutorial/repl.md index 4f37c3a625..a07df7f949 100644 --- a/docs/tutorial/repl.md +++ b/docs/tutorial/repl.md @@ -12,6 +12,7 @@ The `repl` module provides a REPL implementation that can be accessed using: ```sh ./node_modules/.bin/electron --interactive ``` + * Assuming you have `electron` or `electron-prebuilt` installed globally: ```sh diff --git a/docs/tutorial/security.md b/docs/tutorial/security.md index 3887a789a3..b67ce2e266 100644 --- a/docs/tutorial/security.md +++ b/docs/tutorial/security.md @@ -56,7 +56,6 @@ is your own code. Common web vulnerabilities, such as Cross-Site Scripting (XSS) have a higher security impact on Electron applications hence it is highly recommended to adopt secure software development best practices and perform security testing. - ## Isolation For Untrusted Content A security issue exists whenever you receive code from an untrusted source (e.g. @@ -150,7 +149,6 @@ browserWindow.loadURL('https://example.com') ``` - ## 2) Do not enable Node.js Integration for Remote Content _This recommendation is the default behavior in Electron since 5.0.0._ @@ -225,7 +223,6 @@ window.readConfig = function () { } ``` - ## 3) Enable Context Isolation for Remote Content Context isolation is an Electron feature that allows developers to run code @@ -244,7 +241,6 @@ prevent the use of Node primitives, `contextIsolation` must also be used. For more information on what `contextIsolation` is and how to enable it please see our dedicated [Context Isolation](context-isolation.md) document. - ## 4) Handle Session Permission Requests From Remote Content You may have seen permission requests while using Chrome: They pop up whenever @@ -283,7 +279,6 @@ session }) ``` - ## 5) Do Not Disable WebSecurity _Recommendation is Electron's default_ @@ -302,6 +297,7 @@ Disabling `webSecurity` will disable the same-origin policy and set the execution of insecure code from different domains. ### How? + ```js // Bad const mainWindow = new BrowserWindow({ @@ -324,7 +320,6 @@ const mainWindow = new BrowserWindow() ``` - ## 6) Define a Content Security Policy A Content Security Policy (CSP) is an additional layer of protection against @@ -381,7 +376,6 @@ on a page directly in the markup using a `` tag: ``` - ## 7) Do Not Set `allowRunningInsecureContent` to `true` _Recommendation is Electron's default_ @@ -415,7 +409,6 @@ const mainWindow = new BrowserWindow({ const mainWindow = new BrowserWindow({}) ``` - ## 8) Do Not Enable Experimental Features _Recommendation is Electron's default_ @@ -448,7 +441,6 @@ const mainWindow = new BrowserWindow({ const mainWindow = new BrowserWindow({}) ``` - ## 9) Do Not Use `enableBlinkFeatures` _Recommendation is Electron's default_ @@ -466,6 +458,7 @@ ramifications are, and how it impacts the security of your application. Under no circumstances should you enable features speculatively. ### How? + ```js // Bad const mainWindow = new BrowserWindow({ @@ -480,7 +473,6 @@ const mainWindow = new BrowserWindow({ const mainWindow = new BrowserWindow() ``` - ## 10) Do Not Use `allowpopups` _Recommendation is Electron's default_ @@ -508,7 +500,6 @@ you know it needs that feature. ``` - ## 11) Verify WebView Options Before Creation A WebView created in a renderer process that does not have Node.js integration @@ -660,6 +651,7 @@ leveraged to execute arbitrary commands. const { shell } = require('electron') shell.openExternal(USER_CONTROLLED_DATA_HERE) ``` + ```js // Good const { shell } = require('electron') @@ -730,7 +722,6 @@ const mainWindow = new BrowserWindow({ > from Electron 10. For prior versions, you need to explicitly disable > the `remote` module by the means above. - ## 16) Filter the `remote` module If you cannot disable the `remote` module, you should filter the globals, @@ -816,7 +807,6 @@ to fix issues before publishing them. Your application will be more secure if it is running a recent version of Electron (and thus, Chromium and Node.js) for which potential security issues are not as widely known. - [browser-window]: ../api/browser-window.md [browser-view]: ../api/browser-view.md [webview-tag]: ../api/webview-tag.md diff --git a/docs/tutorial/support.md b/docs/tutorial/support.md index 360397f82e..5da297f0b7 100644 --- a/docs/tutorial/support.md +++ b/docs/tutorial/support.md @@ -9,6 +9,7 @@ If you're looking for programming help, for answers to questions, or to join in discussion with other developers who use Electron, you can interact with the community in these locations: + - [`Electron's Discord`](https://discord.com/invite/electron) has channels for: - Getting help - Ecosystem apps like [Electron Forge](https://github.com/electron-userland/electron-forge) and [Electron Fiddle](https://github.com/electron/fiddle) @@ -62,6 +63,7 @@ threshold, we will attempt to support backwards compatibility beyond two version until the maintainers feel the maintenance burden is too high to continue doing so. ### Currently supported versions + - 10.x.y - 9.x.y - 8.x.y diff --git a/docs/tutorial/windows-arm.md b/docs/tutorial/windows-arm.md index f7895c5af6..93886d2515 100644 --- a/docs/tutorial/windows-arm.md +++ b/docs/tutorial/windows-arm.md @@ -3,6 +3,7 @@ If your app runs with Electron 6.0.8 or later, you can now build it for Windows 10 on Arm. This considerably improves performance, but requires recompilation of any native modules used in your app. It may also require small fixups to your build and packaging scripts. ## Running a basic app + If your app doesn't use any native modules, then it's really easy to create an Arm version of your app. 1. Make sure that your app's `node_modules` directory is empty. @@ -26,17 +27,21 @@ if (process.arch === 'x64') { If you want to target arm64, logic like this will typically select the wrong architecture, so carefully check your application and build scripts for conditions like this. In custom build and packaging scripts, you should always check the value of `npm_config_arch` in the environment, rather than relying on the current process arch. ### Native modules + If you use native modules, you must make sure that they compile against v142 of the MSVC compiler (provided in Visual Studio 2017). You must also check that any pre-built `.dll` or `.lib` files provided or referenced by the native module are available for Windows on Arm. ### Testing your app + To test your app, use a Windows on Arm device running Windows 10 (version 1903 or later). Make sure that you copy your application over to the target device - Chromium's sandbox will not work correctly when loading your application assets from a network location. ## Development prerequisites + ### Node.js/node-gyp [Node.js v12.9.0 or later is recommended.](https://nodejs.org/en/) If updating to a new version of Node is undesirable, you can instead [update npm's copy of node-gyp manually](https://github.com/nodejs/node-gyp/wiki/Updating-npm's-bundled-node-gyp) to version 5.0.2 or later, which contains the required changes to compile native modules for Arm. ### Visual Studio 2017 + Visual Studio 2017 (any edition) is required for cross-compiling native modules. You can download Visual Studio Community 2017 via Microsoft's [Visual Studio Dev Essentials program](https://visualstudio.microsoft.com/dev-essentials/). After installation, you can add the Arm-specific components by running the following from a _Command Prompt_: ```powershell @@ -49,6 +54,7 @@ vs_installer.exe ^ ``` #### Creating a cross-compilation command prompt + Setting `npm_config_arch=arm64` in the environment creates the correct arm64 `.obj` files, but the standard _Developer Command Prompt for VS 2017_ will use the x64 linker. To fix this: 1. Duplicate the _x64_x86 Cross Tools Command Prompt for VS 2017_ shortcut (e.g. by locating it in the start menu, right clicking, selecting _Open File Location_, copying and pasting) to somewhere convenient. @@ -76,8 +82,8 @@ By default, `node-gyp` unpacks Electron's node headers and downloads the x86 and Substitute `6.0.9` for the version you're using. - ## Cross-compiling native modules + After completing all of the above, open your cross-compilation command prompt and run `set npm_config_arch=arm64`. Then use `npm install` to build your project as normal. As with cross-compiling x86 modules, you may need to remove `node_modules` to force recompilation of native modules if they were previously compiled for another architecture. ## Debugging native modules @@ -92,4 +98,5 @@ Debugging native modules can be done with Visual Studio 2017 (running on your de 6. Once attached, set any appropriate breakpoints and resume JavaScript execution using Chrome's [remote tools for Node](debugging-main-process.md). ## Getting additional help + If you encounter a problem with this documentation, or if your app works when compiled for x86 but not for arm64, please [file an issue](../development/issues.md) with "Windows on Arm" in the title. diff --git a/docs/tutorial/windows-store-guide.md b/docs/tutorial/windows-store-guide.md index 326bcbdadf..e3720f5b72 100644 --- a/docs/tutorial/windows-store-guide.md +++ b/docs/tutorial/windows-store-guide.md @@ -114,6 +114,7 @@ Another important limitation is that the compiled AppX package still contains a win32 executable - and will therefore not run on Xbox, HoloLens, or Phones. ## Optional: Add UWP Features using a BackgroundTask + You can pair your Electron app up with an invisible UWP background task that gets to make full use of Windows 10 features - like push notifications, Cortana integration, or live tiles.