mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

docs: update tutorials for Forge 6 (#36313)

Browse source 
docs: update tutorial for Forge 6
This commit is contained in:
Erick Zhao 2022-11-11 11:42:27 -08:00 committed by GitHub
parent 75d2caf451
commit 46a74d1086
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 84 additions and 120 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
docs/tutorial/code-signing.md
View file

@ -52,15 +52,17 @@ ways to get your application signed and notarized.
If you're using Electron's favorite build tool, getting your application signed If you're using Electron's favorite build tool, getting your application signed
and notarized requires a few additions to your configuration. [Forge](https://electronforge.io) is a and notarized requires a few additions to your configuration. [Forge](https://electronforge.io) is a
collection of the official Electron tools, using [`electron-packager`], collection of the official Electron tools, using [`electron-packager`],
[`electron-osx-sign`], and [`electron-notarize`] under the hood. [`@electron/osx-sign`], and [`@electron/notarize`] under the hood.
Detailed instructions on how to configure your application can be found in the [Electron Forge Code Signing Tutorial](https://www.electronforge.io/guides/code-signing/code-signing-macos). Detailed instructions on how to configure your application can be found in the
[Signing macOS Apps](https://www.electronforge.io/guides/code-signing/code-signing-macos) guide in
the Electron Forge docs.
### Using Electron Packager ### Using Electron Packager
If you're not using an integrated build pipeline like Forge, you If you're not using an integrated build pipeline like Forge, you
are likely using [`electron-packager`], which includes [`electron-osx-sign`] and are likely using [`electron-packager`], which includes [`@electron/osx-sign`] and
[`electron-notarize`]. [`@electron/notarize`].
If you're using Packager's API, you can pass [in configuration that both signs If you're using Packager's API, you can pass [in configuration that both signs
and notarizes your application](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html). and notarizes your application](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html).
@ -70,13 +72,7 @@ const packager = require('electron-packager')
packager({ packager({
dir: '/path/to/my/app', dir: '/path/to/my/app',
osxSign: { osxSign: {},
identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',
'hardened-runtime': true,
entitlements: 'entitlements.plist',
'entitlements-inherit': 'entitlements.plist',
'signature-flags': 'library'
},
osxNotarize: { osxNotarize: {
appleId: 'felix@felix.fun', appleId: 'felix@felix.fun',
appleIdPassword: 'my-apple-id-password' appleIdPassword: 'my-apple-id-password'
@ -84,26 +80,6 @@ packager({
}) })
``` ```
The `entitlements.plist` file referenced here needs the following macOS-specific entitlements
to assure the Apple security mechanisms that your app is doing these things
without meaning any harm:
```xml title="entitlements.plist"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.cs.allow-jit</key>
<true/>
<key>com.apple.security.cs.debugger</key>
<true/>
</dict>
</plist>
```
Up until Electron 12, the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement was required
as well. However, it should not be used anymore if it can be avoided.
### Signing Mac App Store applications ### Signing Mac App Store applications
See the [Mac App Store Guide]. See the [Mac App Store Guide].
@ -213,15 +189,14 @@ can find [its documentation here](https://www.electron.build/code-signing).
See the [Windows Store Guide]. See the [Windows Store Guide].
[apple developer program]: https://developer.apple.com/programs/ [apple developer program]: https://developer.apple.com/programs/
[`electron-builder`]: https://github.com/electron-userland/electron-builder [`electron-forge`]: https://github.com/electron/forge
[`electron-forge`]: https://github.com/electron-userland/electron-forge [`@electron/osx-sign`]: https://github.com/electron/osx-sign
[`electron-osx-sign`]: https://github.com/electron-userland/electron-osx-sign
[`electron-packager`]: https://github.com/electron/electron-packager [`electron-packager`]: https://github.com/electron/electron-packager
[`electron-notarize`]: https://github.com/electron/electron-notarize [`@electron/notarize`]: https://github.com/electron/notarize
[`electron-winstaller`]: https://github.com/electron/windows-installer [`electron-winstaller`]: https://github.com/electron/windows-installer
[`electron-wix-msi`]: https://github.com/felixrieseberg/electron-wix-msi [`electron-wix-msi`]: https://github.com/electron-userland/electron-wix-msi
[xcode]: https://developer.apple.com/xcode [xcode]: https://developer.apple.com/xcode
[signing certificates]: https://github.com/electron/electron-osx-sign/wiki/1.-Getting-Started#certificates [signing certificates]: https://developer.apple.com/support/certificates/
[mac app store guide]: ./mac-app-store-submission-guide.md [mac app store guide]: ./mac-app-store-submission-guide.md
[windows store guide]: ./windows-store-guide.md [windows store guide]: ./windows-store-guide.md
[maker-squirrel]: https://www.electronforge.io/config/makers/squirrel.windows [maker-squirrel]: https://www.electronforge.io/config/makers/squirrel.windows

18
docs/tutorial/mac-app-store-submission-guide.md
View file

@ -11,7 +11,7 @@ This guide provides information on:
To sign Electron apps, the following tools must be installed first: To sign Electron apps, the following tools must be installed first:
* Xcode 11 or above. * Xcode 11 or above.
* The [electron-osx-sign][electron-osx-sign] npm module. * The [@electron/osx-sign] npm module.
You also have to register an Apple Developer account and join the You also have to register an Apple Developer account and join the
[Apple Developer Program][developer-program]. [Apple Developer Program][developer-program].
@ -103,7 +103,7 @@ Apps submitted to the Mac App Store must run under Apple's
the App Sandbox. The standard darwin build of Electron will fail to launch the App Sandbox. The standard darwin build of Electron will fail to launch
when run under App Sandbox. when run under App Sandbox.
When signing the app with `electron-osx-sign`, it will automatically add the When signing the app with `@electron/osx-sign`, it will automatically add the
necessary entitlements to your app's entitlements, but if you are using custom necessary entitlements to your app's entitlements, but if you are using custom
entitlements, you must ensure App Sandbox capacity is added: entitlements, you must ensure App Sandbox capacity is added:
@ -120,7 +120,7 @@ entitlements, you must ensure App Sandbox capacity is added:
#### Extra steps without `electron-osx-sign` #### Extra steps without `electron-osx-sign`
If you are signing your app without using `electron-osx-sign`, you must ensure If you are signing your app without using `@electron/osx-sign`, you must ensure
the app bundle's entitlements have at least following keys: the app bundle's entitlements have at least following keys:
```xml ```xml
@ -170,22 +170,22 @@ your Apple Developer account's Team ID as its value:
</plist> </plist>
``` ```
When using `electron-osx-sign` the `ElectronTeamID` key will be added When using `@electron/osx-sign` the `ElectronTeamID` key will be added
automatically by extracting the Team ID from the certificate's name. You may automatically by extracting the Team ID from the certificate's name. You may
need to manually add this key if `electron-osx-sign` could not find the correct need to manually add this key if `@electron/osx-sign` could not find the correct
Team ID. Team ID.
### Sign apps for development ### Sign apps for development
To sign an app that can run on your development machine, you must sign it with To sign an app that can run on your development machine, you must sign it with
the "Apple Development" certificate and pass the provisioning profile to the "Apple Development" certificate and pass the provisioning profile to
`electron-osx-sign`. `@electron/osx-sign`.
```bash ```bash
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile
``` ```
If you are signing without `electron-osx-sign`, you must place the provisioning If you are signing without `@electron/osx-sign`, you must place the provisioning
profile to `YourApp.app/Contents/embedded.provisionprofile`. profile to `YourApp.app/Contents/embedded.provisionprofile`.
The signed app can only run on the machines that registered by the provisioning The signed app can only run on the machines that registered by the provisioning
@ -213,7 +213,7 @@ use App Sandbox.
electron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess electron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess
``` ```
By passing `--no-gatekeeper-assess`, the `electron-osx-sign` will skip the macOS By passing `--no-gatekeeper-assess`, `@electron/osx-sign` will skip the macOS
GateKeeper check as your app usually has not been notarized yet by this step. GateKeeper check as your app usually has not been notarized yet by this step.
<!-- TODO(zcbenz): Add a chapter about App Notarization --> <!-- TODO(zcbenz): Add a chapter about App Notarization -->
@ -341,7 +341,7 @@ Electron uses following cryptographic algorithms:
* RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004) * RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004)
[developer-program]: https://developer.apple.com/support/compare-memberships/ [developer-program]: https://developer.apple.com/support/compare-memberships/
[electron-osx-sign]: https://github.com/electron/electron-osx-sign [@electron/osx-sign]: https://github.com/electron/electron-osx-sign
[app-sandboxing]: https://developer.apple.com/app-sandboxing/ [app-sandboxing]: https://developer.apple.com/app-sandboxing/
[app-notarization]: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution [app-notarization]: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution
[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html [submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html

9
docs/tutorial/tutorial-1-prerequisites.md
View file

@ -26,6 +26,15 @@ work on Windows, macOS, and Linux with a single JavaScript codebase.
This tutorial will guide you through the process of developing a desktop This tutorial will guide you through the process of developing a desktop
application with Electron and distributing it to end users. application with Electron and distributing it to end users.
## Goals
This tutorial starts by guiding you through the process of piecing together
a minimal Electron application from scratch, then teaches you how to
package and distribute it to users using Electron Forge.
If you prefer to get a project started with a single-command boilerplate, we recommend you start
with Electron Forge's [`create-electron-app`](https://www.electronforge.io/) command.
## Assumptions ## Assumptions
Electron is a native wrapper layer for web apps and is run in a Node.js environment. Electron is a native wrapper layer for web apps and is run in a Node.js environment.

88
docs/tutorial/tutorial-5-packaging.md
View file

@ -70,10 +70,9 @@ the [Electron Forge CLI documentation].
::: :::
You should also notice that your package.json now has a few more packages installed You should also notice that your package.json now has a few more packages installed
under your `devDependencies`, and contains an added `config.forge` field with an array under `devDependencies`, and a new `forge.config.js` file that exports a configuration
of makers configured. **Makers** are Forge plugins that create distributables from object. You should see multiple makers (packages that generate distributable app bundles) in the
your source code. You should see multiple makers in the pre-populated configuration, pre-populated configuration, one for each target platform.
one for each target platform.
### Creating a distributable ### Creating a distributable
@ -111,13 +110,14 @@ Electron Forge can be configured to create distributables in different OS-specif
::: :::
:::tip Creating and Adding Application Icons :::tip Creating and adding application icons
Setting custom application icons requires a few additions to your config. Check out [Forge's icon tutorial] for more information. Setting custom application icons requires a few additions to your config.
Check out [Forge's icon tutorial] for more information.
::: :::
:::note Packaging without Electron Forge :::info Packaging without Electron Forge
If you want to manually package your code, or if you're just interested understanding the If you want to manually package your code, or if you're just interested understanding the
mechanics behind packaging an Electron app, check out the full [Application Packaging] mechanics behind packaging an Electron app, check out the full [Application Packaging]
@ -136,64 +136,51 @@ Code signing is a security technology that you use to certify that a desktop app
created by a known source. Windows and macOS have their own OS-specific code signing created by a known source. Windows and macOS have their own OS-specific code signing
systems that will make it difficult for users to download or launch unsigned applications. systems that will make it difficult for users to download or launch unsigned applications.
If you already have code signing certificates for Windows and macOS, you can set your
credentials in your Forge configuration. Otherwise, please refer to the full
[Code Signing] documentation to learn how to purchase a certificate and for more information
on the desktop app code signing process.
On macOS, code signing is done at the app packaging level. On Windows, distributable installers On macOS, code signing is done at the app packaging level. On Windows, distributable installers
are signed instead. are signed instead. If you already have code signing certificates for Windows and macOS, you can set
your credentials in your Forge configuration.
:::info
For more information on code signing, check out the
[Signing macOS Apps](https://www.electronforge.io/guides/code-signing) guide in the Forge docs.
:::
<Tabs> <Tabs>
<TabItem value="macos" label="macOS" default> <TabItem value="macos" label="macOS" default>
```json title='package.json' {6-18} ```js title='forge.config.js'
{ module.exports = {
packagerConfig: {
osxSign: {},
//... //...
"config": { osxNotarize: {
"forge": { tool: 'notarytool',
//... appleId: process.env.APPLE_ID,
"packagerConfig": { appleIdPassword: process.env.APPLE_PASSWORD,
"osxSign": { teamId: process.env.APPLE_TEAM_ID,
"identity": "Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)",
"hardened-runtime": true,
"entitlements": "entitlements.plist",
"entitlements-inherit": "entitlements.plist",
"signature-flags": "library"
},
"osxNotarize": {
"appleId": "felix@felix.fun",
"appleIdPassword": "this-is-a-secret"
}
} }
//... //...
} }
} }
//...
}
``` ```
</TabItem> </TabItem>
<TabItem value="windows" label="Windows"> <TabItem value="windows" label="Windows">
```json title='package.json' {6-14} ```js title='forge.config.js'
module.exports = {
//...
makers: [
{ {
//... name: '@electron-forge/maker-squirrel',
"config": { config: {
"forge": { certificateFile: './cert.pfx',
//... certificatePassword: process.env.CERTIFICATE_PASSWORD,
"makers": [ },
{ },
"name": "@electron-forge/maker-squirrel", ],
"config": {
"certificateFile": "./cert.pfx",
"certificatePassword": "this-is-a-secret"
}
}
]
//...
}
}
//... //...
} }
``` ```
@ -214,13 +201,12 @@ information.
[`@electron/osx-sign`]: https://github.com/electron/osx-sign [`@electron/osx-sign`]: https://github.com/electron/osx-sign
[application packaging]: ./application-distribution.md [application packaging]: ./application-distribution.md
[code signing]: ./code-signing.md
[`electron-packager`]: https://github.com/electron/electron-packager [`electron-packager`]: https://github.com/electron/electron-packager
[`electron-winstaller`]: https://github.com/electron/windows-installer [`electron-winstaller`]: https://github.com/electron/windows-installer
[electron forge]: https://www.electronforge.io [electron forge]: https://www.electronforge.io
[electron forge cli documentation]: https://www.electronforge.io/cli#commands [electron forge cli documentation]: https://www.electronforge.io/cli#commands
[makers]: https://www.electronforge.io/config/makers [makers]: https://www.electronforge.io/config/makers
[Forge's icon tutorial]: https://www.electronforge.io/guides/create-and-add-icons [forge's icon tutorial]: https://www.electronforge.io/guides/create-and-add-icons
<!-- Tutorial links --> <!-- Tutorial links -->

32
docs/tutorial/tutorial-6-publishing-updating.md
View file

@ -78,27 +78,21 @@ Once you have it installed, you need to set it up in your Forge
configuration. A full list of options is documented in the Forge's configuration. A full list of options is documented in the Forge's
[`PublisherGitHubConfig`] API docs. [`PublisherGitHubConfig`] API docs.
```json title='package.json' {6-16} ```js title='forge.config.js'
module.exports = {
publishers: [
{ {
//... name: '@electron-forge/publisher-github',
"config": { config: {
"forge": { repository: {
"publishers": [ owner: 'github-user-name',
{ name: 'github-repo-name',
"name": "@electron-forge/publisher-github",
"config": {
"repository": {
"owner": "github-user-name",
"name": "github-repo-name"
}, },
"prerelease": false, prerelease: false,
"draft": true draft: true,
} },
} },
] ],
}
}
//...
} }
``` ```