docs: Atom Shell => Electron

This commit is contained in:
Cheng Zhao 2015-04-16 11:31:12 +08:00
parent d878bd33d7
commit d2682233fd
29 changed files with 132 additions and 130 deletions

View file

@ -1,48 +1,50 @@
# Technical differences to NW.js (formerly node-webkit)
Like NW.js, atom-shell provides a platform to write desktop applications
__Note: Electron was previously named Atom Shell.__
Like NW.js, Electron provides a platform to write desktop applications
with JavaScript and HTML, and has Node integration to grant access to low level
system in web pages.
But there are also fundamental differences between the two projects that make
atom-shell a completely separate product from NW.js:
Electron a completely separate product from NW.js:
**1. Entry of application**
__1. Entry of application__
In NW.js, the main entry of an application is a web page, you specify a
main page in the `package.json` and it would be opened in a browser window as
the application's main window.
While in atom-shell, the entry point is a JavaScript script, instead of
While in Electron, the entry point is a JavaScript script, instead of
providing a URL directly, you need to manually create a browser window and load
html file in it with corresponding API. You also need to listen to window events
to decide when to quit the application.
So atom-shell works more like the Node.js runtime, and APIs are more low level,
you can also use atom-shell for web testing purpose like
So Electron works more like the Node.js runtime, and APIs are more low level,
you can also use Electron for web testing purpose like
[phantomjs](http://phantomjs.org/).
**2. Build system**
__2. Build system__
In order to avoid the complexity of building the whole Chromium, atom-shell uses
In order to avoid the complexity of building the whole Chromium, Electron uses
[libchromiumcontent](https://github.com/brightray/libchromiumcontent) to access
Chromium's Content API, libchromiumcontent is a single, shared library that
includes the Chromium Content module and all its dependencies. So users don't
need a powerful machine to build atom-shell.
need a powerful machine to build Electron.
**3. Node integration**
__3. Node integration__
In NW.js, the Node integration in web pages requires patching Chromium to
work, while in atom-shell we chose a different way to integrate libuv loop to
work, while in Electron we chose a different way to integrate libuv loop to
each platform's message loop to avoid hacking Chromium, see the
[`node_bindings`](../../atom/common/) code for how that was done.
**4. Multi-context**
__4. Multi-context__
If you are an experienced NW.js user, you should be familiar with the
concept of Node context and web context, these concepts were invented because
of how the NW.js was implemented.
By using the [multi-context](http://strongloop.com/strongblog/whats-new-node-js-v0-12-multiple-context-execution/)
feature of Node, atom-shell doesn't introduce a new JavaScript context in web
feature of Node, Electron doesn't introduce a new JavaScript context in web
pages.

View file

@ -30,17 +30,17 @@ $ sudo npm install npm -g
## Getting the code
```bash
$ git clone https://github.com/atom/atom-shell.git
$ git clone https://github.com/atom/electron.git
```
## Bootstrapping
The bootstrap script will download all necessary build dependencies and create
build project files. Notice that we're using `ninja` to build `atom-shell` so
build project files. Notice that we're using `ninja` to build Electron so
there is no `Makefile` generated.
```bash
$ cd atom-shell
$ cd electron
$ ./script/bootstrap.py -v
```
@ -98,7 +98,7 @@ versions of clang. Try using clang 3.0, default version in Ubuntu 12.04.
If you get an error like:
````
/usr/bin/ld: warning: libudev.so.0, needed by /home/suyash/projects/atom-shell/vendor/brightray/vendor/download/libchromiumcontent/Release/libchromiumcontent.so, not found (try using -rpath or -rpath-link)
/usr/bin/ld: warning: libudev.so.0, needed by .../vendor/brightray/vendor/download/libchromiumcontent/Release/libchromiumcontent.so, not found (try using -rpath or -rpath-link)
````
and you are on Ubuntu 13.04+, 64 bit system, try doing

View file

@ -14,17 +14,17 @@ following python modules:
## Getting the code
```bash
$ git clone https://github.com/atom/atom-shell.git
$ git clone https://github.com/atom/electron.git
```
## Bootstrapping
The bootstrap script will download all necessary build dependencies and create
build project files. Notice that we're using `ninja` to build `atom-shell` so
build project files. Notice that we're using `ninja` to build Electron so
there is no Xcode project generated.
```bash
$ cd atom-shell
$ cd electron
$ ./script/bootstrap.py -v
```
@ -42,12 +42,12 @@ You can also only build the `Debug` target:
$ ./script/build.py -c D
```
After building is done, you can find `Atom.app` under `out/D`.
After building is done, you can find `Electron.app` under `out/D`.
## 32bit support
Currently atom-shell can only be built for 64bit target on OS X, and there is no
plan to support 32bit on OS X in future.
Electron can only be built for 64bit target on OS X, and there is no plan to
support 32bit OS X in future.
## Tests

View file

@ -13,8 +13,8 @@ If you don't have a Windows installation at the moment,
[modern.ie](https://www.modern.ie/en-us/virtualization-tools#downloads) has
timebombed versions of Windows that you can use to build Electron.
The building of atom-shell is done entirely with command-line scripts, so you
can use any editor you like to develop atom-shell, but it also means you can
The building of Electron is done entirely with command-line scripts, so you
can use any editor you like to develop Electron, but it also means you can
not use Visual Studio for the development. Support of building with Visual
Studio will come in the future.
@ -24,17 +24,17 @@ Studio will come in the future.
## Getting the code
```powershell
git clone https://github.com/atom/atom-shell.git
git clone https://github.com/atom/electron.git
```
## Bootstrapping
The bootstrap script will download all necessary build dependencies and create
build project files. Notice that we're using `ninja` to build atom-shell so
build project files. Notice that we're using `ninja` to build Electron so
there is no Visual Studio project generated.
```powershell
cd atom-shell
cd electron
python script\bootstrap.py -v
```
@ -56,7 +56,7 @@ After building is done, you can find `atom.exe` under `out\D`.
## 64bit support
Currently atom-shell can only be built for 32bit target on Windows, support for
Currently Electron can only be built for 32bit target on Windows, support for
64bit will come in future.
## Tests

View file

@ -1,13 +1,13 @@
# Build system overview
Atom Shell uses `gyp` for project generation, and `ninja` for building, project
Electron uses `gyp` for project generation, and `ninja` for building, project
configurations can be found in `.gyp` and `.gypi` files.
## Gyp files
Following `gyp` files contain the main rules of building Atom Shell:
Following `gyp` files contain the main rules of building Electron:
* `atom.gyp` defines how Atom Shell itself is built.
* `atom.gyp` defines how Electron itself is built.
* `common.gypi` adjusts the build configurations of Node to make it build
together with Chromium.
* `vendor/brightray/brightray.gyp` defines how `brightray` is built, and
@ -23,7 +23,7 @@ Chromium introduced the "component build", which builds each component as a
separate shared library, making linking very quick but sacrificing file size
and performance.
In Atom Shell we took a very similar approach: for `Debug` builds, the binary
In Electron we took a very similar approach: for `Debug` builds, the binary
will be linked to shared library version of Chromium's components to achieve
fast linking time; for `Release` builds, the binary will be linked to the static
library versions, so we can have the best possible binary size and performance.
@ -35,7 +35,7 @@ script. By default both static libraries and shared libraries will be
downloaded and the final size should be between 800MB and 2GB according to the
platform.
If you only want to build Atom Shell quickly for testing or development, you
If you only want to build Electron quickly for testing or development, you
can only download the shared library versions by passing the `--dev` parameter:
```bash
@ -45,20 +45,20 @@ $ ./script/build.py -c D
## Two-phrase project generation
Atom Shell links with different sets of libraries in `Release` and `Debug`
Electron links with different sets of libraries in `Release` and `Debug`
builds, however `gyp` doesn't support configuring different link settings for
different configurations.
To work around this Atom Shell uses a `gyp` variable
To work around this Electron uses a `gyp` variable
`libchromiumcontent_component` to control which link settings to use, and only
generates one target when running `gyp`.
## Target names
Unlike most projects that use `Release` and `Debug` as target names, Atom Shell
Unlike most projects that use `Release` and `Debug` as target names, Electron
uses `R` and `D` instead. This is because `gyp` randomly crashes if there is
only one `Release` or `Debug` build configuration is defined, and Atom Shell has
only one `Release` or `Debug` build configuration is defined, and Electron has
to only generate one target for one time as stated above.
This only affects developers, if you are only building Atom Shell for rebranding
This only affects developers, if you are only building Electron for rebranding
you are not affected.

View file

@ -25,4 +25,4 @@ Guide](https://github.com/styleguide/javascript), and also following rules:
When creating a new API, we should prefer getters and setters instead of
jQuery's one-function style, for example, `.getText()` and `.setText(text)`
are preferred to `.text([text])`. There is a
[discussion](https://github.com/atom/atom-shell/issues/46) of this.
[discussion](https://github.com/atom/electron/issues/46) of this.

View file

@ -8,13 +8,13 @@ forcing users to download large debugging files. The server functions like
[Microsoft's symbol server](http://support.microsoft.com/kb/311503) so the
documentation there can be useful.
Note that because released atom-shell builds are heavily optimized, debugging is
Note that because released Electron builds are heavily optimized, debugging is
not always easy. The debugger will not be able to show you the content of all
variables and the execution path can seem strange because of inlining, tail
calls, and other compiler optimizations. The only workaround is to build an
unoptimized local build.
The official symbol server URL for atom-shell is
The official symbol server URL for Electron is
http://54.249.141.255:8086/atom-shell/symbols.
You cannot visit this URL directly: you must add it to the symbol path of your
debugging tool. In the examples below, a local cache directory is used to avoid
@ -24,7 +24,7 @@ appropriate cache directory on your machine.
## Using the symbol server in Windbg
The Windbg symbol path is configured with a string value delimited with asterisk
characters. To use only the atom-shell symbol server, add the following entry to
characters. To use only the Electron symbol server, add the following entry to
your symbol path (__note:__ you can replace `c:\code\symbols` with any writable
directory on your computer, if you'd prefer a different location for downloaded
symbols):

View file

@ -2,7 +2,7 @@
## Overview
The source code of atom-shell is separated into a few parts, and we are mostly
The source code of Electron is separated into a few parts, and we are mostly
following Chromium on the separation conventions.
You may need to become familiar with [Chromium's multi-process
@ -11,7 +11,7 @@ to understand the source code better.
## Structure of source code
* **atom** - Source code of atom-shell.
* **atom** - Source code of Electron.
* **app** - System entry code.
* **browser** - The frontend including the main window, UI, and all of the
main process things. This talks to the renderer to manage web pages.
@ -20,7 +20,7 @@ to understand the source code better.
* **cocoa** - Cocoa specific source code.
* **gtk** - GTK+ specific source code.
* **win** - Windows GUI specific source code.
* **default_app** - The default page to show when atom-shell is started
* **default_app** - The default page to show when Electron is started
without providing an app.
* **api** - The implementation of the main process APIs.
* **lib** - Javascript part of the API implementation.
@ -36,12 +36,12 @@ to understand the source code better.
loop into Chromium's message loop.
* **lib** - Common Javascript initialization code.
* **api** - The implementation of common APIs, and foundations of
atom-shell's built-in modules.
Electron's built-in modules.
* **lib** - Javascript part of the API implementation.
* **chromium_src** - Source code that copied from Chromium.
* **docs** - Documentations.
* **spec** - Automatic tests.
* **atom.gyp** - Building rules of atom-shell.
* **atom.gyp** - Building rules of Electron.
* **common.gypi** - Compiler specific settings and building rules for other
components like `node` and `breakpad`.