docs: Atom Shell => Electron
This commit is contained in:
Cheng Zhao
parent
d878bd33d7
commit
d2682233fd
29 changed files with 132 additions and 130 deletions
|
|
@ -1,14 +1,14 @@
|
|||
# Application distribution
|
||||
|
||||
To distribute your app with atom-shell, you should name the folder of your app
|
||||
as `app`, and put it under atom-shell's resources directory (on OS X it is
|
||||
`Atom.app/Contents/Resources/`, and on Linux and Windows it is `resources/`),
|
||||
To distribute your app with Electron, you should name the folder of your app
|
||||
as `app`, and put it under Electron's resources directory (on OS X it is
|
||||
`Electron.app/Contents/Resources/`, and on Linux and Windows it is `resources/`),
|
||||
like this:
|
||||
|
||||
On OS X:
|
||||
|
||||
```text
|
||||
atom-shell/Atom.app/Contents/Resources/app/
|
||||
electron/Electron.app/Contents/Resources/app/
|
||||
├── package.json
|
||||
├── main.js
|
||||
└── index.html
|
||||
|
|
@ -17,14 +17,14 @@ atom-shell/Atom.app/Contents/Resources/app/
|
|||
On Windows and Linux:
|
||||
|
||||
```text
|
||||
atom-shell/resources/app
|
||||
electron/resources/app
|
||||
├── package.json
|
||||
├── main.js
|
||||
└── index.html
|
||||
```
|
||||
|
||||
Then execute `Atom.app` (or `atom` on Linux, and `atom.exe` on Windows), and
|
||||
atom-shell will start as your app. The `atom-shell` directory would then be
|
||||
Then execute `Electron.app` (or `atom` on Linux, and `atom.exe` on Windows), and
|
||||
Electron will start as your app. The `electron` directory would then be
|
||||
your distribution that should be delivered to final users.
|
||||
|
||||
## Packaging your app into a file
|
||||
|
|
@ -34,20 +34,20 @@ package your app into an [asar](https://github.com/atom/asar) archive to avoid
|
|||
exposing your app's source code to users.
|
||||
|
||||
To use an `asar` archive to replace the `app` folder, you need to rename the
|
||||
archive to `app.asar`, and put it under atom-shell's resources directory like
|
||||
bellow, and atom-shell will then try read the archive and start from it.
|
||||
archive to `app.asar`, and put it under Electron's resources directory like
|
||||
bellow, and Electron will then try read the archive and start from it.
|
||||
|
||||
On OS X:
|
||||
|
||||
```text
|
||||
atom-shell/Atom.app/Contents/Resources/
|
||||
electron/Electron.app/Contents/Resources/
|
||||
└── app.asar
|
||||
```
|
||||
|
||||
On Windows and Linux:
|
||||
|
||||
```text
|
||||
atom-shell/resources/
|
||||
electron/resources/
|
||||
└── app.asar
|
||||
```
|
||||
|
||||
|
|
@ -55,12 +55,12 @@ More details can be found in [Application packaging](application-packaging.md).
|
|||
|
||||
## Rebranding with downloaded binaries
|
||||
|
||||
After bundling your app into atom-shell, you will want to rebrand atom-shell
|
||||
After bundling your app into Electron, you will want to rebrand Electron
|
||||
before distributing it to users.
|
||||
|
||||
If you don't care about the executable name on Windows or the helper process
|
||||
name on OS X, you can simply rename the downloaded binaries, and there is also a
|
||||
grunt task that can download prebuilt atom-shell binaries for your current
|
||||
grunt task that can download prebuilt Electron binaries for your current
|
||||
platform automatically:
|
||||
[grunt-download-atom-shell](https://github.com/atom/grunt-download-atom-shell).
|
||||
|
||||
|
|
@ -75,20 +75,20 @@ name you want.
|
|||
|
||||
### OS X
|
||||
|
||||
You can rename `Atom.app` to whatever you want, and you also have to rename the
|
||||
You can rename `Electron.app` to whatever you want, and you also have to rename the
|
||||
`CFBundleDisplayName`, `CFBundleIdentifier` and `CFBundleName` fields in
|
||||
following manifest files if they have these keys:
|
||||
|
||||
* `Atom.app/Contents/Info.plist`
|
||||
* `Atom.app/Contents/Frameworks/Atom Helper.app/Contents/Info.plist`
|
||||
* `Electron.app/Contents/Info.plist`
|
||||
* `Electron.app/Contents/Frameworks/Atom Helper.app/Contents/Info.plist`
|
||||
|
||||
### Linux
|
||||
|
||||
You can rename the `atom` executable to whatever you want.
|
||||
|
||||
## Rebranding by rebuilding atom-shell from source
|
||||
## Rebranding by rebuilding Electron from source
|
||||
|
||||
The best way to rename atom-shell is to change the product name and then build
|
||||
The best way to rename Electron is to change the product name and then build
|
||||
from source. To do this you need to override the `GYP_DEFINES` environment
|
||||
variable and have a clean rebuild:
|
||||
|
||||
|
|
@ -110,7 +110,7 @@ $ script/build.py -c Release -t myapp
|
|||
|
||||
### grunt-build-atom-shell
|
||||
|
||||
Manually checking out atom-shell's code and rebuilding could be complicated, so
|
||||
Manually checking out Electron's code and rebuilding could be complicated, so
|
||||
a Grunt task has been created that will handle this automatically:
|
||||
[grunt-build-atom-shell](https://github.com/paulcbetts/grunt-build-atom-shell).
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ source code.
|
|||
## Generating `asar` archive
|
||||
|
||||
An [asar][asar] archive is a simple tar-like format that concatenates files
|
||||
into a single file, atom-shell can read arbitrary files from it without unpacking
|
||||
into a single file, Electron can read arbitrary files from it without unpacking
|
||||
the whole file.
|
||||
|
||||
Following is the steps to package your app into an `asar` archive:
|
||||
|
|
@ -26,12 +26,12 @@ $ asar pack your-app app.asar
|
|||
|
||||
## Using `asar` archives
|
||||
|
||||
In atom-shell there are two sets of APIs: Node APIs provided by Node.js, and Web
|
||||
In Electron there are two sets of APIs: Node APIs provided by Node.js, and Web
|
||||
APIs provided by Chromium. Both APIs support reading files from `asar` archives.
|
||||
|
||||
### Node API
|
||||
|
||||
With special patches in atom-shell, Node APIs like `fs.readFile` and `require`
|
||||
With special patches in Electron, Node APIs like `fs.readFile` and `require`
|
||||
treat `asar` archives as virtual directories, and the files in it as normal
|
||||
files in the filesystem.
|
||||
|
||||
|
|
@ -124,7 +124,7 @@ also cause errors.
|
|||
|
||||
Most `fs` APIs can read file or get file's information from `asar` archives
|
||||
without unpacking, but for some APIs that rely on passing the real file path to
|
||||
underlying system calls, atom-shell will extract the needed file into a
|
||||
underlying system calls, Electron will extract the needed file into a
|
||||
temporary file and pass the path of the temporary file to the APIs to make them
|
||||
work. This adds a little overhead for those APIs.
|
||||
|
||||
|
|
|
|||
|
|
@ -2,14 +2,14 @@
|
|||
|
||||
The devtools of browser window can only debug the renderer process scripts.
|
||||
(I.e. the web pages.) In order to provide a way to debug the scripts of
|
||||
the main process, atom-shell has provided the `--debug` and `--debug-brk`
|
||||
the main process, Electron has provided the `--debug` and `--debug-brk`
|
||||
switches.
|
||||
|
||||
## Command line switches
|
||||
|
||||
### `--debug=[port]`
|
||||
|
||||
When this switch is used atom-shell would listen for V8 debugger protocol
|
||||
When this switch is used Electron would listen for V8 debugger protocol
|
||||
messages on `port`, the `port` is `5858` by default.
|
||||
|
||||
### `--debug-brk=[port]`
|
||||
|
|
@ -28,18 +28,18 @@ with node-inspector, and the main process would crash if you inspect the
|
|||
$ node-inspector
|
||||
```
|
||||
|
||||
### 2. Enable debug mode for atom-shell
|
||||
### 2. Enable debug mode for Electron
|
||||
|
||||
You can either start atom-shell with a debug flag like:
|
||||
You can either start Electron with a debug flag like:
|
||||
|
||||
```bash
|
||||
$ atom-shell --debug=5858 your/app
|
||||
$ electron --debug=5858 your/app
|
||||
```
|
||||
|
||||
or, to pause your script on the first line:
|
||||
|
||||
```bash
|
||||
$ atom-shell --debug-brk=5858 your/app
|
||||
$ electron --debug-brk=5858 your/app
|
||||
```
|
||||
|
||||
### 3. Load the debugger UI
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ applications can put shortcuts in the JumpList of task bar, and on Mac
|
|||
applications can put a custom menu in the dock menu.
|
||||
|
||||
This guide introduces how to integrate your application into those desktop
|
||||
environments with atom-shell APIs.
|
||||
environments with Electron APIs.
|
||||
|
||||
## Recent documents (Windows & OS X)
|
||||
|
||||
|
|
@ -26,7 +26,7 @@ To add a file to recent documents, you can use
|
|||
|
||||
```javascript
|
||||
var app = require('app');
|
||||
app.addRecentDocument('/Users/aryastark/github/atom-shell/README.md');
|
||||
app.addRecentDocument('/Users/USERNAME/Desktop/work.type');
|
||||
```
|
||||
|
||||
And you can use [app.clearRecentDocuments](clearrecentdocuments) API to empty
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# DevTools extension
|
||||
|
||||
To make debugging more easy, atom-shell has added basic support for
|
||||
To make debugging more easy, Electron has added basic support for
|
||||
[Chrome DevTools Extension][devtools-extension].
|
||||
|
||||
For most devtools extensions, you can simply download their source codes and use
|
||||
|
|
@ -16,7 +16,7 @@ $ cd /some-directory
|
|||
$ git clone --recursive https://github.com/facebook/react-devtools.git
|
||||
```
|
||||
|
||||
Then you can load it in atom-shell by opening the devtools in arbitray window,
|
||||
Then you can load it in Electron by opening the devtools in arbitray window,
|
||||
and run this code in the console of devtools:
|
||||
|
||||
```javascript
|
||||
|
|
@ -33,20 +33,20 @@ require('remote').require('browser-window').removeDevToolsExtension('React Devel
|
|||
## Format of devtools extension
|
||||
|
||||
Ideally all devtools extension written for Chrome browser can be loaded by
|
||||
atom-shell, but they have to be in a plain directory, for those packaged `crx`
|
||||
extensions, there is no way in atom-shell to load them unless you find a way to
|
||||
Electron, but they have to be in a plain directory, for those packaged `crx`
|
||||
extensions, there is no way in Electron to load them unless you find a way to
|
||||
extract them into a directory.
|
||||
|
||||
## Background pages
|
||||
|
||||
Currently atom-shell doesn't support the background pages of chrome extensions,
|
||||
Currently Electron doesn't support the background pages of chrome extensions,
|
||||
so for some devtools extensions that rely on this feature, they may not work
|
||||
well in atom-shell
|
||||
well in Electron
|
||||
|
||||
## `chrome.*` APIs
|
||||
|
||||
Some chrome extensions use `chrome.*` APIs for some features, there is some
|
||||
effort to implement those APIs in atom-shell to make them work, but we have
|
||||
effort to implement those APIs in Electron to make them work, but we have
|
||||
only implemented few for now.
|
||||
|
||||
So if the devtools extension is using APIs other than `chrome.devtools.*`, it is
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ _online-status.html_
|
|||
There may be instances where one wants to respond to these events in the
|
||||
main process as well. The main process however does not have a
|
||||
`navigator` object and thus cannot detect these events directly. Using
|
||||
Atom-shell's inter-process communication utilities, the events can be forwarded
|
||||
Electron's inter-process communication utilities, the events can be forwarded
|
||||
to the main process and handled as needed, as shown in the following example.
|
||||
|
||||
_main.js_
|
||||
|
|
|
|||
|
|
@ -123,7 +123,7 @@ Finally the `index.html` is the web page you want to show:
|
|||
<body>
|
||||
<h1>Hello World!</h1>
|
||||
We are using node.js <script>document.write(process.version)</script>
|
||||
and atom-shell <script>document.write(process.versions['atom-shell'])</script>.
|
||||
and atom-shell <script>document.write(process.versions['electron'])</script>.
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
|
@ -150,8 +150,8 @@ $ ./atom-shell/atom your-app/
|
|||
On OS X:
|
||||
|
||||
```bash
|
||||
$ ./Atom.app/Contents/MacOS/Atom your-app/
|
||||
$ ./Electron.app/Contents/MacOS/Atom your-app/
|
||||
```
|
||||
|
||||
`Atom.app` here is part of the atom-shell's release package, you can download
|
||||
it from [here](https://github.com/atom/atom-shell/releases).
|
||||
`Electron.app` here is part of the atom-shell's release package, you can download
|
||||
it from [here](https://github.com/atom/electron/releases).
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
# Using native Node modules
|
||||
|
||||
The native Node modules are supported by atom-shell, but since atom-shell is
|
||||
The native Node modules are supported by Electron, but since Electron is
|
||||
using a different V8 version from official Node, you have to manually specify
|
||||
the location of atom-shell's headers when building native modules.
|
||||
the location of Electron's headers when building native modules.
|
||||
|
||||
## Native Node module compatibility
|
||||
|
||||
Since Node v0.11.x there were vital changes in the V8 API. So generally all
|
||||
native modules written for Node v0.10.x wouldn't work for Node v0.11.x. And
|
||||
because atom-shell internally uses Node v0.11.13, it carries with the same
|
||||
because Electron internally uses Node v0.11.13, it carries with the same
|
||||
problem.
|
||||
|
||||
To solve this, you should use modules that support Node v0.11.x,
|
||||
|
|
@ -20,16 +20,16 @@ For old modules that only support Node v0.10.x, you should use the
|
|||
|
||||
### The node-gyp way
|
||||
|
||||
To build Node modules with headers of atom-shell, you need to tell `node-gyp`
|
||||
To build Node modules with headers of Electron, you need to tell `node-gyp`
|
||||
where to download headers and which version to use:
|
||||
|
||||
```bash
|
||||
$ cd /path-to-module/
|
||||
$ HOME=~/.atom-shell-gyp node-gyp rebuild --target=0.16.0 --arch=ia32 --dist-url=https://atom.io/download/atom-shell
|
||||
$ HOME=~/.electron-gyp node-gyp rebuild --target=0.16.0 --arch=ia32 --dist-url=https://atom.io/download/atom-shell
|
||||
```
|
||||
|
||||
The `HOME=~/.atom-shell-gyp` changes where to find development headers. The
|
||||
`--target=0.16.0` is version of atom-shell. The `--dist-url=...` specifies
|
||||
The `HOME=~/.electron-gyp` changes where to find development headers. The
|
||||
`--target=0.16.0` is version of Electron. The `--dist-url=...` specifies
|
||||
where to download the headers. The `--arch=ia32` says the module is built for
|
||||
32bit system.
|
||||
|
||||
|
|
@ -42,5 +42,5 @@ Node modules, except that you need to setup some environment variables:
|
|||
export npm_config_disturl=https://atom.io/download/atom-shell
|
||||
export npm_config_target=0.23.0
|
||||
export npm_config_arch=x64
|
||||
HOME=~/.atom-shell-gyp npm install module-name
|
||||
HOME=~/.electron-gyp npm install module-name
|
||||
```
|
||||
|
|
|
|||
|
|
@ -8,14 +8,14 @@ From [ChromeDriver - WebDriver for Chrome][chrome-driver]:
|
|||
> implements WebDriver's wire protocol for Chromium. It is being developed by
|
||||
> members of the Chromium and WebDriver teams.
|
||||
|
||||
In atom-shell's [releases](https://github.com/atom/atom-shell/releases) page you
|
||||
can find archives of `chromedriver`, there is no difference between atom-shell's
|
||||
In Electron's [releases](https://github.com/atom/electron/releases) page you
|
||||
can find archives of `chromedriver`, there is no difference between Electron's
|
||||
distribution of `chromedriver` and upstream ones, so in order to use
|
||||
`chromedriver` together with atom-shell, you will need some special setup.
|
||||
`chromedriver` together with Electron, you will need some special setup.
|
||||
|
||||
Also notice that only minor version update releases (e.g. `vX.X.0` releases)
|
||||
include `chromedriver` archives, because `chromedriver` doesn't change as
|
||||
frequent as atom-shell itself.
|
||||
frequent as Electron itself.
|
||||
|
||||
## Setting up with WebDriverJs
|
||||
|
||||
|
|
@ -42,9 +42,9 @@ $ npm install selenium-webdriver
|
|||
|
||||
### 3. Connect to chrome driver
|
||||
|
||||
The usage of `selenium-webdriver` with atom-shell is basically the same with
|
||||
The usage of `selenium-webdriver` with Electron is basically the same with
|
||||
upstream, except that you have to manually specify how to connect chrome driver
|
||||
and where to find atom-shell's binary:
|
||||
and where to find Electron's binary:
|
||||
|
||||
```javascript
|
||||
var webdriver = require('selenium-webdriver');
|
||||
|
|
@ -53,9 +53,9 @@ var driver = new webdriver.Builder().
|
|||
// The "9515" is the port opened by chrome driver.
|
||||
usingServer('http://localhost:9515').
|
||||
withCapabilities({chromeOptions: {
|
||||
// Here is the path to your atom-shell binary.
|
||||
// Here is the path to your Electron binary.
|
||||
binary: '/Path-to-Your-App.app/Contents/MacOS/Atom'}}).
|
||||
forBrowser('atom-shell').
|
||||
forBrowser('electron').
|
||||
build();
|
||||
|
||||
driver.get('http://www.google.com');
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue