From f7cf3ad8674dc61acda985e4e18d54d68f72b13e Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Wed, 30 Apr 2014 14:52:58 +0800 Subject: [PATCH 1/5] Restructure the docs to put more tutorials. --- docs/README.md | 6 +++--- docs/api/browser/browser-window.md | 19 ++++++------------- docs/{ => tutorial}/quick-start.md | 0 .../use-native-node-module.md} | 2 +- 4 files changed, 10 insertions(+), 17 deletions(-) rename docs/{ => tutorial}/quick-start.md (100%) rename docs/{use-native-modules.md => tutorial/use-native-node-module.md} (98%) diff --git a/docs/README.md b/docs/README.md index 671e1fd4bcfd..8fa068516052 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,9 @@ # Atom-Shell Documentations -## Guides +## Tutorials -* [Quick start](quick-start.md) -* [Use native modules](use-native-modules.md) +* [Quick start](tutorial/quick-start.md) +* [Use native node modules](tutorial/use-native-node-modules.md) ## Development diff --git a/docs/api/browser/browser-window.md b/docs/api/browser/browser-window.md index 19fcb2591aa5..7768e0b86dc8 100644 --- a/docs/api/browser/browser-window.md +++ b/docs/api/browser/browser-window.md @@ -113,14 +113,8 @@ window.onbeforeunload = function(e) { ### Event: 'closed' -Emitted when the window is closed. At the time of this event, window is not -destroyed yet so you can still do some operations to the window (but you -shouldn't!). - -### Event: 'destroyed' - -Emitted when the memory taken by the native window is released. Usually you -should dereference the javascript object when received this event. +Emitted when the window is closed. After you have received this event you should +remove the reference to the window and avoid using it anymore. ### Event: 'unresponsive' @@ -159,12 +153,11 @@ Get the `WebContents` of devtools of this window. ### BrowserWindow.destroy() -Destroy the window and free the memory without closing it. +Force closing the window, the `unload` and `beforeunload` event won't be emitted +for the web page, and `close` event would also not be emitted for this window, +but it would gurrantee the `closed` event to be emitted. -**Note:** Usually you should always call `Window.close()` to close the window, -**which will emit `beforeunload` and `unload` events for DOM. Only use -**`Window.destroy()` when the window gets into a very bad state and you want -**to force closing it. +You should only use this method when the web page has crashed. ### BrowserWindow.close() diff --git a/docs/quick-start.md b/docs/tutorial/quick-start.md similarity index 100% rename from docs/quick-start.md rename to docs/tutorial/quick-start.md diff --git a/docs/use-native-modules.md b/docs/tutorial/use-native-node-module.md similarity index 98% rename from docs/use-native-modules.md rename to docs/tutorial/use-native-node-module.md index ae7481183d51..7caed97cf11d 100644 --- a/docs/use-native-modules.md +++ b/docs/tutorial/use-native-node-module.md @@ -1,4 +1,4 @@ -# Use native modules +# Use native node modules Since atom-shell is using a different V8 version from the official node, you need to build native module against atom-shell's headers to use them. From a9748f6cc6e79b763a0b668517abb96eb5e85227 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Wed, 30 Apr 2014 15:03:14 +0800 Subject: [PATCH 2/5] :memo: Say some more about native node modules. --- docs/tutorial/use-native-node-module.md | 28 ++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/tutorial/use-native-node-module.md b/docs/tutorial/use-native-node-module.md index 7caed97cf11d..41e1ef433424 100644 --- a/docs/tutorial/use-native-node-module.md +++ b/docs/tutorial/use-native-node-module.md @@ -1,10 +1,11 @@ # Use native node modules -Since atom-shell is using a different V8 version from the official node, you -need to build native module against atom-shell's headers to use them. +The native node modules are supported by atom-shell, but since atom-shell is +using a different V8 version from official node, you need to use `apm` instead +of `npm` to install node modules. -The [apm](https://github.com/atom/apm) provided a easy way to do this, after -installing it you could use it to install dependencies just like using `npm`: +The usage of [apm](https://github.com/atom/apm) is quite similar to `npm`, to +install dependencies from `package.json` of current project, just do: ```bash $ cd /path/to/atom-shell/project/ @@ -12,12 +13,25 @@ $ apm install . ``` But you should notice that `apm install module` wont' work because it will -install a user package for [Atom](https://github.com/atom/atom) instead. +install a user package for [Atom Editor](https://github.com/atom/atom) instead. + +## Native node module compability + +Since node v0.11.x, there were vital changes of V8 API, so generally all native +modules written for node v0.10.x wouldn't work for node v0.11.x, and since +atom-shell internally uses node v0.11.9, it carries with the same problem. + +To solve it, you should use modules that support both node v0.10.x and v0.11.x, +and [many modules](https://www.npmjs.org/browse/depended/nan) do support the +both now. For old modules that only support node v0.10.x, you should use the +[nan](https://github.com/rvagg/nan) module to port it to v0.11.x. + +## Other ways of installing native modules Apart from `apm`, you can also use `node-gyp` and `npm` to manually build the native modules. -## The node-gyp way +### The node-gyp way First you need to check which node release atom-shell is carrying via `process.version` (at the time of writing it is v0.10.5), then you can @@ -32,7 +46,7 @@ The `HOME=~/.atom-shell-gyp` changes where to find development headers. The `--target=0.10.5` is specifying node's version. The `--dist-url=...` specifies where to download the headers. -## The npm way +### The npm way ```bash export npm_config_disturl=https://gh-contractor-zcbenz.s3.amazonaws.com/atom-shell/dist From aa54df7e4407325822d6d00f0669d2116fa90628 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Wed, 30 Apr 2014 16:39:49 +0800 Subject: [PATCH 3/5] :memo: Simpler introduction in quick start. --- docs/tutorial/quick-start.md | 65 +++++++++++++++++++++--------------- 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index 82521071465c..8e3051786c26 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -2,27 +2,48 @@ ## Introduction -Generally, atom-shell lets you create a web-based desktop application in pure -javascript. Unlike CEF, which requires you to use C++ to write underlying -code, or node-webkit, which only allows you to write everything in the web -page, atom-shell gives you the power to use javascript to control the browser -side. +Generally, atom-shell enables you to create desktop applications with pure +JavaScript by providing a runtime with rich native APIs, you could see it as +an variant of node.js runtime that focused on desktop applications instead of +web server. -## Browser and renderer +But it doesn't mean atom-shell is a JavaScript binding to GUI libraries, instead +atom-shell uses web pages as GUI, so you could also see it as a minimal Chromium +browser, controlled by JavaScript. -Atom-shell is built upon Chromium's Content API, so it has the same -multi-processes architecture with the Chrome browser. In summary, things about -UI are done in the browser process, and each web page instance would start a -new renderer process. +### The browser side -In atom-shell, you can just put everything in a simpler way: when you are -executing javascript in browser side, you can control the application's life, -create UI widget, deal with system events, and create windows which contain -web pages; while on the renderer side, you can only control the web page you -are showing, if you want something more like creating a new window, you should -use IPC API to tell the browser to do that. +If you had experience with node.js web applications, you would notice that there +are types of JavaScript scripts: the server side scripts and the client side +scripts. The server side JavaScript, is the scrips that run on the node.js +runtime, and the client side JavaScript, is the ones that run on user's browser. -## The architecture of an app +In atom-shell we have similar concepts, since atom-shell displays GUI by showing +web pages, we would have scripts that run in the web page, and also have scripts +ran by the atom-shell runtime, which created those web pages. Like node.js, we +call the former ones client client scripts, and the latter one browser side +scripts. + +In traditional node.js applications, communication between server side and +client side are usually done by web sockets. In atom-shell, we have provided +the [ipc](../api/renderer/ipc-renderer.md) module for browser side to client +communication, and the [remote](../api/renderer/remote.md) module for easy RPC +support. + +### Web page and node.js + +Normal web pages are designed to not touch outside world, which makes them not +suitable for interacting with native systems, atom-shell provides node.js APIs +in web pages so you could access native resources in web pages, just like +[node-webkit](https://github.com/rogerwang/node-webkit). + +But unlike node-webkit, you could not do native GUI related operations in web +pages, instead you need to do them on the browser side by sending messages or +use the easy [remote](../api/renderer/remote.md) module. + +## Write your first atom-shell app + +### The architecture of an app Generally, an app of atom-shell should contains at least following files: @@ -95,7 +116,7 @@ Finally the `index.html` is the web page you want to show, in fact you actually don't need to provide it, you can just make the window load url of a remote page. -## Package your app in atom-shell +### Package your app in atom-shell To make atom-shell run your app, you should name the folder of your app as `app`, and put it under `Atom.app/Contents/Resources/`, like this: @@ -110,11 +131,3 @@ Atom.app/Contents/Resources/app/ Then atom-shell will automatically read your `package.json`. If there is no `Atom.app/Contents/Resources/app/`, atom-shell will load the default empty app, which is `Atom.app/Contents/Resources/browser/default_app/`. - -## IPC between browser and renderer - -Atom-shell provides a set of javascript APIs for developers to communicate -between browser and renderers. There are two types of message: asynchronous -messages and synchronous messages, the former one is quite similar with node's -IPC APIs, while the latter one is mainly used for implement the RPC API. -Details can be found in the `ipc` module reference. From 98a49fa1559f5e7a4e7c2a997fd8cf2e2c5272fa Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Wed, 30 Apr 2014 17:28:36 +0800 Subject: [PATCH 4/5] :memo: Update the quick start on writing the app. --- docs/tutorial/quick-start.md | 92 ++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 31 deletions(-) diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index 8e3051786c26..7cee03da4c23 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -41,11 +41,10 @@ But unlike node-webkit, you could not do native GUI related operations in web pages, instead you need to do them on the browser side by sending messages or use the easy [remote](../api/renderer/remote.md) module. + ## Write your first atom-shell app -### The architecture of an app - -Generally, an app of atom-shell should contains at least following files: +Generally, an atom-shell app would be like this: ```text app/ @@ -61,20 +60,21 @@ this: ```json { - "name" : "atom", + "name" : "your-app", "version" : "0.1.0", "main" : "main.js" } ``` -The `main.js` will be executed, and in which you should do the initialization -work. To give the developers more power, atom-shell works by exposing -necessary Content APIs in javascript, so developers can precisely control -every piece of the app. An example of `main.js` is: +The `main.js` should create windows and handle system events, and an typical +example is: ```javascript var app = require('app'); // Module to control application life. -var Window = require('window'); // Module to create native browser window. +var BrowserWindow = require('browser-window'); // Module to create native browser window. + +// Report crashes to our server. +require('crash-reporter').start(); // Keep a global reference of the window object, if you don't, the window will // be closed automatically when the javascript object is GCed. @@ -82,27 +82,20 @@ var mainWindow = null; // Quit when all windows are closed. app.on('window-all-closed', function() { - app.terminate(); + if (process.platform != 'darwin') + app.quit(); }); // This method will be called when atom-shell has done everything // initialization and ready for creating browser windows. app.on('ready', function() { - // Create the browser window, - mainWindow = new Window({ width: 800, height: 600 }); + // Create the browser window. + mainWindow = new BrowserWindow({width: 800, height: 600}); + // and load the index.html of the app. mainWindow.loadUrl('file://' + __dirname + '/index.html'); - // Catch the event when web page in the window changes its title. - mainWindow.on('page-title-updated', function(event, title) { - // Prevent the default behaviour of 'page-title-updated' event. - event.preventDefault(); - - // Add a prefix for the window's original title. - this.setTitle('Atom Shell - ' + title); - }); - - // Hook to when the window is closed. + // Emitted when the window is closed. mainWindow.on('closed', function() { // Dereference the window object, usually you would store windows // in an array if your app supports multi windows, this is the time @@ -112,14 +105,52 @@ app.on('ready', function() { }); ``` -Finally the `index.html` is the web page you want to show, in fact you -actually don't need to provide it, you can just make the window load url of a -remote page. +Finally the `index.html` is the web page you want to show: -### Package your app in atom-shell +```html + + + + Hello World! + + +

Hello World!

+ We are using node.js + and atom-shell . + + +``` -To make atom-shell run your app, you should name the folder of your app as -`app`, and put it under `Atom.app/Contents/Resources/`, like this: +## Run your app + +After done writing your app, you could create a distribution of your app by +following next section and then execute the packaged binary, or you can just +use the downloaded atom-shell binary to execute your app. + +On Window: + +```cmd +$ .\atom-shell\atom.exe app +``` + +On Linux: + +```bash +$ ./atom-shell/atom app +``` + +On Mac OS X: + +```bash +$ ./Atom.app/Contents/MacOS/Atom app +``` + +## Distribute your app + +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/`), +like this: ```text Atom.app/Contents/Resources/app/ @@ -128,6 +159,5 @@ Atom.app/Contents/Resources/app/ └── index.html ``` -Then atom-shell will automatically read your `package.json`. If there is no -`Atom.app/Contents/Resources/app/`, atom-shell will load the default empty -app, which is `Atom.app/Contents/Resources/browser/default_app/`. +Then execute `Atom.app` (or `atom` on Linux, and `atom.exe` on Window), and +atom-shell will start as your app. From 69821cdb96a88ab2f99ec848d886a93bf3785771 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Sun, 4 May 2014 18:32:12 +0800 Subject: [PATCH 5/5] :memo: Separate the application distribution chapter out. --- docs/README.md | 1 + docs/tutorial/application-distribution.md | 34 +++++++++++++++++++++++ docs/tutorial/quick-start.md | 22 ++------------- 3 files changed, 38 insertions(+), 19 deletions(-) create mode 100644 docs/tutorial/application-distribution.md diff --git a/docs/README.md b/docs/README.md index 8fa068516052..0a3d89b9b3bf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,7 @@ ## Tutorials * [Quick start](tutorial/quick-start.md) +* [Application distribution](tutorial/application-distribution.md) * [Use native node modules](tutorial/use-native-node-modules.md) ## Development diff --git a/docs/tutorial/application-distribution.md b/docs/tutorial/application-distribution.md new file mode 100644 index 000000000000..a3173cdea4b0 --- /dev/null +++ b/docs/tutorial/application-distribution.md @@ -0,0 +1,34 @@ +# 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/`), +like this: + +On Mac OS X: + +```text +atom-shell/Atom.app/Contents/Resources/app/ +├── package.json +├── main.js +└── index.html +``` + +On Windows and Linux: + +```text +atom-shell/resources/app +├── package.json +├── main.js +└── index.html +``` + +Then execute `Atom.app` (or `atom` on Linux, and `atom.exe` on Window), and +atom-shell will start as your app. The `atom-shell` directory would then be +your distribution that should be delivered to final users. + +## Build with grunt + +If you build your application with `grunt`, then there is a grunt task that can +download atom-shell for current platform automatically: +[grunt-download-atom-shell](https://github.com/atom/grunt-download-atom-shell). diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index 7cee03da4c23..3e7ce4f94874 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -124,8 +124,9 @@ Finally the `index.html` is the web page you want to show: ## Run your app After done writing your app, you could create a distribution of your app by -following next section and then execute the packaged binary, or you can just -use the downloaded atom-shell binary to execute your app. +following the [Application distribution](./application-distribution.md) guide +and then execute the packaged app, or you can just use the downloaded atom-shell +binary to execute your app directly. On Window: @@ -144,20 +145,3 @@ On Mac OS X: ```bash $ ./Atom.app/Contents/MacOS/Atom app ``` - -## Distribute your app - -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/`), -like this: - -```text -Atom.app/Contents/Resources/app/ -├── package.json -├── main.js -└── index.html -``` - -Then execute `Atom.app` (or `atom` on Linux, and `atom.exe` on Window), and -atom-shell will start as your app.