Merge branch 'master' into native-window-open

docs/api/browser-window.md

@@ -35,9 +35,9 @@ without visual flash, there are two solutions for different situations.
 
 ### Using `ready-to-show` event
 
-While loading the page, the `ready-to-show` event will be emitted when renderer
-process has done drawing for the first time, showing window after this event
-will have no visual flash:
+While loading the page, the `ready-to-show` event will be emitted when the renderer
+process has rendered the page for the first time if the window has not been shown yet. Showing
+the window after this event will have no visual flash:
 
 ```javascript
 const {BrowserWindow} = require('electron')
@@ -215,6 +215,9 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     * `devTools` Boolean (optional) - Whether to enable DevTools. If it is set to `false`, can not use `BrowserWindow.webContents.openDevTools()` to open DevTools. Default is `true`.
     * `nodeIntegration` Boolean (optional) - Whether node integration is enabled. Default
       is `true`.
+    * `nodeIntegrationInWorker` Boolean (optional) - Whether node integration is
+      enabled in web workers. Default is `false`. More about this can be found
+      in [Multithreading](../tutorial/multithreading.md).
     * `preload` String (optional) - Specifies a script that will be loaded before other
       scripts run in the page. This script will always have access to node APIs
       no matter whether node integration is turned on or off. The value should
@@ -391,7 +394,7 @@ Emitted when the window is hidden.
 
 #### Event: 'ready-to-show'
 
-Emitted when the web page has been rendered and window can be displayed without
+Emitted when the web page has been rendered (while not being shown) and window can be displayed without
 a visual flash.
 
 #### Event: 'maximize'
@@ -633,7 +636,8 @@ Returns `Boolean` - Whether current window is a modal window.
 
 #### `win.maximize()`
 
-Maximizes the window.
+Maximizes the window. This will also show (but not focus) the window if it
+isn't being displayed already.
 
 #### `win.unmaximize()`
 

docs/development/build-instructions-linux.md

@@ -117,6 +117,14 @@ To clean the build files:
 $ npm run clean
 ```
 
+To clean only `out` and `dist` directories:
+
+```bash
+$ npm run clean-build
+```
+
+**Note:** Both clean commands require running `bootstrap` again before building.
+
 ## Troubleshooting
 
 ### Error While Loading Shared Libraries: libtinfo.so.5

docs/development/build-instructions-osx.md

@@ -85,6 +85,14 @@ To clean the build files:
 $ npm run clean
 ```
 
+To clean only `out` and `dist` directories:
+
+```bash
+$ npm run clean-build
+```
+
+**Note:** Both clean commands require running `bootstrap` again before building.
+
 ## Tests
 
 See [Build System Overview: Tests](build-system-overview.md#tests)

docs/development/build-instructions-windows.md

@@ -83,6 +83,14 @@ To clean the build files:
 $ npm run clean
 ```
 
+To clean only `out` and `dist` directories:
+
+```bash
+$ npm run clean-build
+```
+
+**Note:** Both clean commands require running `bootstrap` again before building.
+
 ## Tests
 
 See [Build System Overview: Tests](build-system-overview.md#tests)

docs/tutorial/multithreading.md

@@ -0,0 +1,50 @@
+# Multithreading
+
+With [Web Workers][web-workers], it is possible to run JavaScript in OS-level
+threads.
+
+## Multi-threaded Node.js
+
+It is possible to use Node.js features in Electron's Web Workers, to do
+so the `nodeIntegrationInWorker` option should be set to `true` in
+`webPreferences`.
+
+```javascript
+let win = new BrowserWindow({
+  webPreferences: {
+    nodeIntegrationInWorker: true
+  }
+})
+```
+
+The `nodeIntegrationInWorker` can be used independent of `nodeIntegration`, but
+`sandbox` must not be set to `true`.
+
+## Available APIs
+
+All built-in modules of Node.js are supported in Web Workers, and `asar`
+archives can still be read with Node.js APIs. However none of Electron's
+built-in modules can be used in a multi-threaded environment.
+
+## Native Node.js modules
+
+Any native Node.js module can be loaded directly in Web Workers, but it is
+strongly recommended not to do so. Most existing native modules have been
+written assuming single-threaded environment, using them in Web Workers will
+lead to crashes and memory corruptions.
+
+Note that even if a native Node.js module is thread-safe it's still not safe to
+load it in a Web Worker because the `process.dlopen` function is not thread
+safe.
+
+The only way to load a native module safely for now, is to make sure the app
+loads no native modules after the Web Workers get started.
+
+```javascript
+process.dlopen = () => {
+  throw new Error('Load native module is not safe')
+}
+let worker = new Worker('script.js')
+```
+
+[web-workers]: https://developer.mozilla.org/en/docs/Web/API/Web_Workers_API/Using_web_workers