docs: app distribution page (#26239)
* docs: first draft of the app distribution page * docs: second iteration of the app distribution page. Fixed mentions * docs: third iteration of the app distribution page. Fixed mentions * docs: reworked app distribution page according to mentions * docs: minor fixes to the app distribution page according to mentions
This commit is contained in:
parent
cffb51e141
commit
6fc5ff77c1
3 changed files with 44 additions and 273 deletions
|
@ -1,25 +1,38 @@
|
|||
# Application Distribution
|
||||
|
||||
To distribute your app with Electron, you need to package and rebrand it. The easiest way to do this is to use one of the following third party packaging tools:
|
||||
## Overview
|
||||
|
||||
To distribute your app with Electron, you need to package and rebrand it.
|
||||
To do this, you can either use specialized tooling or manual approaches.
|
||||
|
||||
## With tooling
|
||||
|
||||
You can use the following tools to distribute your application:
|
||||
|
||||
* [electron-forge](https://github.com/electron-userland/electron-forge)
|
||||
* [electron-builder](https://github.com/electron-userland/electron-builder)
|
||||
* [electron-packager](https://github.com/electron/electron-packager)
|
||||
|
||||
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.
|
||||
These tools will take care of all the steps you need to take to end up with a
|
||||
distributable Electron application, such as bundling your application,
|
||||
rebranding the executable, and setting the right icons.
|
||||
|
||||
You can check the example of how to package your app with `electron-forge` in
|
||||
our [Quick Start Guide](quick-start.md#package-and-distribute-the-application).
|
||||
|
||||
## Manual distribution
|
||||
|
||||
You can also choose to manually get your app ready for distribution. The steps needed to do this are outlined below.
|
||||
### With prebuilt binaries
|
||||
|
||||
To distribute your app with Electron, you need to download Electron's [prebuilt
|
||||
To distribute your app manually, you need to download Electron's [prebuilt
|
||||
binaries](https://github.com/electron/electron/releases). Next, the folder
|
||||
containing your app should be named `app` and placed in Electron's resources
|
||||
directory as shown in the following examples. Note that the location of
|
||||
Electron's prebuilt binaries is indicated with `electron/` in the examples
|
||||
below.
|
||||
directory as shown in the following examples.
|
||||
|
||||
On macOS:
|
||||
> *NOTE:* the location of Electron's prebuilt binaries is indicated
|
||||
with `electron/` in the examples below.
|
||||
|
||||
*On macOS:*
|
||||
|
||||
```plaintext
|
||||
electron/Electron.app/Contents/Resources/app/
|
||||
|
@ -28,7 +41,7 @@ electron/Electron.app/Contents/Resources/app/
|
|||
└── index.html
|
||||
```
|
||||
|
||||
On Windows and Linux:
|
||||
*On Windows and Linux:*
|
||||
|
||||
```plaintext
|
||||
electron/resources/app
|
||||
|
@ -37,47 +50,44 @@ electron/resources/app
|
|||
└── index.html
|
||||
```
|
||||
|
||||
Then execute `Electron.app` (or `electron` on Linux, `electron.exe` on Windows),
|
||||
and Electron will start as your app. The `electron` directory will then be
|
||||
your distribution to deliver to final users.
|
||||
Then execute `Electron.app` on macOS, `electron` on Linux, or `electron.exe`
|
||||
on Windows, and Electron will start as your app. The `electron` directory
|
||||
will then be your distribution to deliver to users.
|
||||
|
||||
## Packaging Your App into a File
|
||||
### With an app source code archive
|
||||
|
||||
Apart from shipping your app by copying all of its source files, you can also
|
||||
package your app into an [asar](https://github.com/electron/asar) archive to avoid
|
||||
exposing your app's source code to users.
|
||||
Instead of from shipping your app by copying all of its source files, you can
|
||||
package your app into an [asar] archive to improve the performance of reading
|
||||
files on platforms like Windows, if you are not already using a bundler such
|
||||
as Parcel or Webpack.
|
||||
|
||||
To use an `asar` archive to replace the `app` folder, you need to rename the
|
||||
archive to `app.asar`, and put it under Electron's resources directory like
|
||||
below, and Electron will then try to read the archive and start from it.
|
||||
|
||||
On macOS:
|
||||
*On macOS:*
|
||||
|
||||
```plaintext
|
||||
electron/Electron.app/Contents/Resources/
|
||||
└── app.asar
|
||||
```
|
||||
|
||||
On Windows and Linux:
|
||||
*On Windows and Linux:*
|
||||
|
||||
```plaintext
|
||||
electron/resources/
|
||||
└── app.asar
|
||||
```
|
||||
|
||||
More details can be found in [Application packaging](application-packaging.md).
|
||||
You can find more details on how to use `asar` in the
|
||||
[`electron/asar` repository][asar].
|
||||
|
||||
## Rebranding with Downloaded Binaries
|
||||
### Rebranding with downloaded binaries
|
||||
|
||||
After bundling your app into Electron, you will want to rebrand Electron
|
||||
before distributing it to users.
|
||||
|
||||
### Windows
|
||||
|
||||
You can rename `electron.exe` to any name you like, and edit its icon and other
|
||||
information with tools like [rcedit](https://github.com/electron/rcedit).
|
||||
|
||||
### macOS
|
||||
#### macOS
|
||||
|
||||
You can rename `Electron.app` to any name you want, and you also have to rename
|
||||
the `CFBundleDisplayName`, `CFBundleIdentifier` and `CFBundleName` fields in the
|
||||
|
@ -104,60 +114,20 @@ MyApp.app/Contents
|
|||
└── MyApp Helper
|
||||
```
|
||||
|
||||
### Linux
|
||||
#### Windows
|
||||
|
||||
You can rename `electron.exe` to any name you like, and edit its icon and other
|
||||
information with tools like [rcedit](https://github.com/electron/rcedit).
|
||||
|
||||
#### Linux
|
||||
|
||||
You can rename the `electron` executable to any name you like.
|
||||
|
||||
## Rebranding by Rebuilding Electron from Source
|
||||
### Rebranding by rebuilding Electron from source
|
||||
|
||||
It is also possible to rebrand Electron by changing the product name and
|
||||
building it from source. To do this you need to set the build argument
|
||||
corresponding to the product name (`electron_product_name = "YourProductName"`)
|
||||
in the `args.gn` file and rebuild.
|
||||
|
||||
### Creating a Custom Electron Fork
|
||||
|
||||
Creating a custom fork of Electron is almost certainly not something you will
|
||||
need to do in order to build your app, even for "Production Level" applications.
|
||||
Using a tool such as `electron-packager` or `electron-forge` will allow you to
|
||||
"Rebrand" Electron without having to do these steps.
|
||||
|
||||
You need to fork Electron when you have custom C++ code that you have patched
|
||||
directly into Electron, that either cannot be upstreamed, or has been rejected
|
||||
from the official version. As maintainers of Electron, we very much would like
|
||||
to make your scenario work, so please try as hard as you can to get your changes
|
||||
into the official version of Electron, it will be much much easier on you, and
|
||||
we appreciate your help.
|
||||
|
||||
#### Creating a Custom Release with surf-build
|
||||
|
||||
1. Install [Surf](https://github.com/surf-build/surf), via npm:
|
||||
`npm install -g surf-build@latest`
|
||||
|
||||
2. Create a new S3 bucket and create the following empty directory structure:
|
||||
|
||||
```sh
|
||||
- electron/
|
||||
- symbols/
|
||||
- dist/
|
||||
```
|
||||
|
||||
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`
|
||||
|
||||
4. In `script/upload.py`, you _must_ set `ELECTRON_REPO` to your fork (`MYORG/electron`),
|
||||
especially if you are a contributor to Electron proper.
|
||||
|
||||
5. `surf-build -r https://github.com/MYORG/electron -s YOUR_COMMIT -n 'surf-PLATFORM-ARCH'`
|
||||
|
||||
6. Wait a very, very long time for the build to complete.
|
||||
[asar]: https://github.com/electron/asar
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue