From 223b440bc870e3218c9a4eddc2fe1b7365c13a66 Mon Sep 17 00:00:00 2001 From: fbukevin Date: Thu, 28 Jan 2016 18:20:39 +0800 Subject: [PATCH] prepare for retaining "Guides" pages --- .../zh-TW/tutorial/debugging-main-process.md | 76 ++++++++++ .../zh-TW/tutorial/devtools-extension.md | 62 ++++++++ .../mac-app-store-submission-guide.md | 120 ++++++++++++++++ .../tutorial/using-native-node-modules.md | 67 +++++++++ .../tutorial/using-pepper-flash-plugin.md | 50 +++++++ .../tutorial/using-selenium-and-webdriver.md | 132 ++++++++++++++++++ 6 files changed, 507 insertions(+) create mode 100644 docs-translations/zh-TW/tutorial/debugging-main-process.md create mode 100644 docs-translations/zh-TW/tutorial/devtools-extension.md create mode 100644 docs-translations/zh-TW/tutorial/mac-app-store-submission-guide.md create mode 100644 docs-translations/zh-TW/tutorial/using-native-node-modules.md create mode 100644 docs-translations/zh-TW/tutorial/using-pepper-flash-plugin.md create mode 100644 docs-translations/zh-TW/tutorial/using-selenium-and-webdriver.md diff --git a/docs-translations/zh-TW/tutorial/debugging-main-process.md b/docs-translations/zh-TW/tutorial/debugging-main-process.md new file mode 100644 index 000000000000..6fbb858bc281 --- /dev/null +++ b/docs-translations/zh-TW/tutorial/debugging-main-process.md @@ -0,0 +1,76 @@ +# Debugging the Main Process + +The browser window DevTools can only debug the renderer process scripts (i.e. +the web pages). In order to provide a way to debug the scripts from the main +process, Electron has provided the `--debug` and `--debug-brk` switches. + +## Command Line Switches + +Use the following command line switches to debug Electron's main process: + +### `--debug=[port]` + +When this switch is used Electron will listen for V8 debugger protocol +messages on `port`. The default `port` is `5858`. + +### `--debug-brk=[port]` + +Like `--debug` but pauses the script on the first line. + +## Use node-inspector for Debugging + +__Note:__ Electron doesn't currently work very well +with node-inspector, and the main process will crash if you inspect the +`process` object under node-inspector's console. + +### 1. Make sure you have [node-gyp required tools][node-gyp-required-tools] installed + +### 2. Install [node-inspector][node-inspector] + +```bash +$ npm install node-inspector +``` + +### 3. Install a patched version of `node-pre-gyp` + +```bash +$ npm install git+https://git@github.com/enlight/node-pre-gyp.git#detect-electron-runtime-in-find +``` + +### 4. Recompile the `node-inspector` `v8` modules for electron (change the target to your electron version number) + +```bash +$ node_modules/.bin/node-pre-gyp --target=0.36.2 --runtime=electron --fallback-to-build --directory node_modules/v8-debug/ --dist-url=https://atom.io/download/atom-shell reinstall +$ node_modules/.bin/node-pre-gyp --target=0.36.2 --runtime=electron --fallback-to-build --directory node_modules/v8-profiler/ --dist-url=https://atom.io/download/atom-shell reinstall +``` + +See also [How to install native modules](how-to-install-native-modules). + +### 5. Enable debug mode for Electron + +You can either start Electron with a debug flag like: + +```bash +$ electron --debug=5858 your/app +``` + +or, to pause your script on the first line: + +```bash +$ electron --debug-brk=5858 your/app +``` + +### 6. Start the [node-inspector][node-inspector] server using electron + +```bash +$ ELECTRON_RUN_AS_NODE=true path/to/electron.exe node_modules/node-inspector/bin/inspector.js +``` + +### 7. Load the debugger UI + +Open http://127.0.0.1:8080/debug?ws=127.0.0.1:8080&port=5858 in the Chrome browser. You may have to click pause if starting with debug-brk to see the entry line. + +[node-inspector]: https://github.com/node-inspector/node-inspector +[node-gyp-required-tools]: https://github.com/nodejs/node-gyp#installation +[how-to-install-native-modules]: using-native-node-modules.md#how-to-install-native-modules + diff --git a/docs-translations/zh-TW/tutorial/devtools-extension.md b/docs-translations/zh-TW/tutorial/devtools-extension.md new file mode 100644 index 000000000000..7c7ea7d64a24 --- /dev/null +++ b/docs-translations/zh-TW/tutorial/devtools-extension.md @@ -0,0 +1,62 @@ +# DevTools Extension + +To make debugging easier, Electron has basic support for the +[Chrome DevTools Extension][devtools-extension]. + +For most DevTools extensions you can simply download the source code and use +the `BrowserWindow.addDevToolsExtension` API to load them. The loaded extensions +will be remembered so you don't need to call the API every time when creating +a window. + +** NOTE: React DevTools does not work, follow the issue here https://github.com/atom/electron/issues/915 ** + +For example, to use the [React DevTools Extension](https://github.com/facebook/react-devtools) +, first you need to download its source code: + +```bash +$ cd /some-directory +$ git clone --recursive https://github.com/facebook/react-devtools.git +``` + +Follow the instructions in [`react-devtools/shells/chrome/Readme.md`](https://github.com/facebook/react-devtools/blob/master/shells/chrome/Readme.md) to build the extension. + +Then you can load the extension in Electron by opening DevTools in any window, +and running the following code in the DevTools console: + +```javascript +const BrowserWindow = require('electron').remote.BrowserWindow; +BrowserWindow.addDevToolsExtension('/some-directory/react-devtools/shells/chrome'); +``` + +To unload the extension, you can call the `BrowserWindow.removeDevToolsExtension` +API with its name and it will not load the next time you open the DevTools: + +```javascript +BrowserWindow.removeDevToolsExtension('React Developer Tools'); +``` + +## Format of DevTools Extension + +Ideally all DevTools extensions written for the Chrome browser can be loaded by +Electron, but they have to be in a plain directory. For those packaged with +`crx` extensions, there is no way for Electron to load them unless you find a +way to extract them into a directory. + +## Background Pages + +Currently Electron doesn't support the background pages feature in Chrome +extensions, so some DevTools extensions that rely on this feature may +not work in Electron. + +## `chrome.*` APIs + +Some Chrome extensions may use `chrome.*` APIs for features and while there has +been some effort to implement those APIs in Electron, not all have been +implemented. + +Given that not all `chrome.*` APIs are implemented if the DevTools extension is +using APIs other than `chrome.devtools.*`, the extension is very likely not to +work. You can report failing extensions in the issue tracker so that we can add +support for those APIs. + +[devtools-extension]: https://developer.chrome.com/extensions/devtools diff --git a/docs-translations/zh-TW/tutorial/mac-app-store-submission-guide.md b/docs-translations/zh-TW/tutorial/mac-app-store-submission-guide.md new file mode 100644 index 000000000000..036676fe853a --- /dev/null +++ b/docs-translations/zh-TW/tutorial/mac-app-store-submission-guide.md @@ -0,0 +1,120 @@ +# Mac App Store Submission Guide + +Since v0.34.0, Electron allows submitting packaged apps to the Mac App Store +(MAS). This guide provides information on: how to submit your app and the +limitations of the MAS build. + +__Note:__ Submitting an app to Mac App Store requires enrolling [Apple Developer +Program][developer-program], which costs money. + +## How to Submit Your App + +The following steps introduce a simple way to submit your app to Mac App Store. +However, these steps do not ensure your app will be approved by Apple; you +still need to read Apple's [Submitting Your App][submitting-your-app] guide on +how to meet the Mac App Store requirements. + +### Get Certificate + +To submit your app to the Mac App Store, you first must get a certificate from +Apple. You can follow these [existing guides][nwjs-guide] on web. + +### Sign Your App + +After getting the certificate from Apple, you can package your app by following +[Application Distribution](application-distribution.md), and then proceed to +signing your app. This step is basically the same with other programs, but the +key is to sign every dependency of Electron one by one. + +First, you need to prepare two entitlements files. + +`child.plist`: + +```xml + + + + + com.apple.security.app-sandbox + + com.apple.security.inherit + + + +``` + +`parent.plist`: + +```xml + + + + + com.apple.security.app-sandbox + + + +``` + +And then sign your app with the following script: + +```bash +#!/bin/bash + +# Name of your app. +APP="YourApp" +# The path of you app to sign. +APP_PATH="/path/to/YouApp.app" +# The path to the location you want to put the signed package. +RESULT_PATH="~/Desktop/$APP.pkg" +# The name of certificates you requested. +APP_KEY="3rd Party Mac Developer Application: Company Name (APPIDENTITY)" +INSTALLER_KEY="3rd Party Mac Developer Installer: Company Name (APPIDENTITY)" + +FRAMEWORKS_PATH="$APP_PATH/Contents/Frameworks" + +codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/Libraries/libnode.dylib" +codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/Electron Framework" +codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/" +codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper.app/" +codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper EH.app/" +codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper NP.app/" +codesign -fs "$APP_KEY" --entitlements parent.plist "$APP_PATH" +productbuild --component "$APP_PATH" /Applications --sign "$INSTALLER_KEY" "$RESULT_PATH" +``` + +If you are new to app sandboxing under OS X, you should also read through +Apple's [Enabling App Sandbox][enable-app-sandbox] to have a basic idea, then +add keys for the permissions needed by your app to the entitlements files. + +### Upload Your App and Submit for Review + +After signing your app, you can use Application Loader to upload it to iTunes +Connect for processing, making sure you have [created a record][create-record] +before uploading. Then you can [submit your app for review][submit-for-review]. + +## Limitations of MAS Build + +In order to satisfy all requirements for app sandboxing, the following modules +have been disabled in the MAS build: + +* `crash-reporter` +* `auto-updater` + +and the following behaviors have been changed: + +* Video capture may not work for some machines. +* Certain accessibility features may not work. +* Apps will not be aware of DNS changes. + +Also, due to the usage of app sandboxing, the resources which can be accessed by + the app are strictly limited; you can read [App Sandboxing][app-sandboxing] for + more information. + +[developer-program]: https://developer.apple.com/support/compare-memberships/ +[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html +[nwjs-guide]: https://github.com/nwjs/nw.js/wiki/Mac-App-Store-%28MAS%29-Submission-Guideline#first-steps +[enable-app-sandbox]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html +[create-record]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/CreatingiTunesConnectRecord.html +[submit-for-review]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html +[app-sandboxing]: https://developer.apple.com/app-sandboxing/ diff --git a/docs-translations/zh-TW/tutorial/using-native-node-modules.md b/docs-translations/zh-TW/tutorial/using-native-node-modules.md new file mode 100644 index 000000000000..2defedd74183 --- /dev/null +++ b/docs-translations/zh-TW/tutorial/using-native-node-modules.md @@ -0,0 +1,67 @@ +# Using Native Node Modules + +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 Electron's headers when building native modules. + +## Native Node Module Compatibility + +Native modules might break when Node starts using a new version of V8. +To make sure the module you're interested in will work with Electron, you should +check if it supports the internal Node version used by Electron. +You can check what version of Node is used in Electron by looking it up in +the [releases](https://github.com/atom/electron/releases) page or by using +`process.version` (see [Quick Start](https://github.com/atom/electron/blob/master/docs/tutorial/quick-start.md) +for example). + +Consider using [NAN](https://github.com/nodejs/nan/) for your own modules, since +it makes it easier to support multiple versions of Node. It's also helpful for +porting old modules to newer versions of Node so they can work with Electron. + +## How to Install Native Modules + +Three ways to install native modules: + +### The Easy Way + +The most straightforward way to rebuild native modules is via the +[`electron-rebuild`](https://github.com/paulcbetts/electron-rebuild) package, +which handles the manual steps of downloading headers and building native modules: + +```sh +npm install --save-dev electron-rebuild + +# Every time you run "npm install", run this +./node_modules/.bin/electron-rebuild + +# On Windows if you have trouble, try: +.\node_modules\.bin\electron-rebuild.cmd +``` + +### The npm Way + +You can also use `npm` to install modules. The steps are exactly the same with +Node modules, except that you need to setup some environment variables: + +```bash +export npm_config_disturl=https://atom.io/download/atom-shell +export npm_config_target=0.33.1 +export npm_config_arch=x64 +export npm_config_runtime=electron +HOME=~/.electron-gyp npm install module-name +``` + +### The node-gyp Way + +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=~/.electron-gyp node-gyp rebuild --target=0.29.1 --arch=x64 --dist-url=https://atom.io/download/atom-shell +``` + +The `HOME=~/.electron-gyp` changes where to find development headers. The +`--target=0.29.1` is version of Electron. The `--dist-url=...` specifies +where to download the headers. The `--arch=x64` says the module is built for +64bit system. diff --git a/docs-translations/zh-TW/tutorial/using-pepper-flash-plugin.md b/docs-translations/zh-TW/tutorial/using-pepper-flash-plugin.md new file mode 100644 index 000000000000..a9918b220ac0 --- /dev/null +++ b/docs-translations/zh-TW/tutorial/using-pepper-flash-plugin.md @@ -0,0 +1,50 @@ +# Using Pepper Flash Plugin + +Electron now supports the Pepper Flash plugin. To use the Pepper Flash plugin in +Electron, you should manually specify the location of the Pepper Flash plugin +and then enable it in your application. + +## Prepare a Copy of Flash Plugin + +On OS X and Linux, the details of the Pepper Flash plugin can be found by +navigating to `chrome://plugins` in the Chrome browser. Its location and version +are useful for Electron's Pepper Flash support. You can also copy it to another +location. + +## Add Electron Switch + +You can directly add `--ppapi-flash-path` and `ppapi-flash-version` to the +Electron command line or by using the `app.commandLine.appendSwitch` method +before the app ready event. Also, add the `plugins` switch of `browser-window`. +For example: + +```javascript +// Specify flash path. +// On Windows, it might be /path/to/pepflashplayer.dll +// On OS X, /path/to/PepperFlashPlayer.plugin +// On Linux, /path/to/libpepflashplayer.so +app.commandLine.appendSwitch('ppapi-flash-path', '/path/to/libpepflashplayer.so'); + +// Specify flash version, for example, v17.0.0.169 +app.commandLine.appendSwitch('ppapi-flash-version', '17.0.0.169'); + +app.on('ready', function() { + mainWindow = new BrowserWindow({ + 'width': 800, + 'height': 600, + 'web-preferences': { + 'plugins': true + } + }); + mainWindow.loadURL('file://' + __dirname + '/index.html'); + // Something else +}); +``` + +## Enable Flash Plugin in a `` Tag + +Add `plugins` attribute to `` tag. + +```html + +``` diff --git a/docs-translations/zh-TW/tutorial/using-selenium-and-webdriver.md b/docs-translations/zh-TW/tutorial/using-selenium-and-webdriver.md new file mode 100644 index 000000000000..035dabdfe79f --- /dev/null +++ b/docs-translations/zh-TW/tutorial/using-selenium-and-webdriver.md @@ -0,0 +1,132 @@ +# Using Selenium and WebDriver + +From [ChromeDriver - WebDriver for Chrome][chrome-driver]: + +> WebDriver is an open source tool for automated testing of web apps across many +> browsers. It provides capabilities for navigating to web pages, user input, +> JavaScript execution, and more. ChromeDriver is a standalone server which +> implements WebDriver's wire protocol for Chromium. It is being developed by +> members of the Chromium and WebDriver teams. + +In order to use `chromedriver` with Electron you have to tell it where to +find Electron and make it think Electron is the Chrome browser. + +## Setting up with WebDriverJs + +[WebDriverJs](https://code.google.com/p/selenium/wiki/WebDriverJs) provides +a Node package for testing with web driver, we will use it as an example. + +### 1. Start ChromeDriver + +First you need to download the `chromedriver` binary, and run it: + +```bash +$ ./chromedriver +Starting ChromeDriver (v2.10.291558) on port 9515 +Only local connections are allowed. +``` + +Remember the port number `9515`, which will be used later + +### 2. Install WebDriverJS + +```bash +$ npm install selenium-webdriver +``` + +### 3. Connect to ChromeDriver + +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 Electron's binary: + +```javascript +const webdriver = require('selenium-webdriver'); + +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 Electron binary. + binary: '/Path-to-Your-App.app/Contents/MacOS/Atom', + } + }) + .forBrowser('electron') + .build(); + +driver.get('http://www.google.com'); +driver.findElement(webdriver.By.name('q')).sendKeys('webdriver'); +driver.findElement(webdriver.By.name('btnG')).click(); +driver.wait(function() { + return driver.getTitle().then(function(title) { + return title === 'webdriver - Google Search'; + }); +}, 1000); + +driver.quit(); +``` + +## Setting up with WebdriverIO + +[WebdriverIO](http://webdriver.io/) provides a Node package for testing with web +driver. + +### 1. Start ChromeDriver + +First you need to download the `chromedriver` binary, and run it: + +```bash +$ chromedriver --url-base=wd/hub --port=9515 +Starting ChromeDriver (v2.10.291558) on port 9515 +Only local connections are allowed. +``` + +Remember the port number `9515`, which will be used later + +### 2. Install WebdriverIO + +```bash +$ npm install webdriverio +``` + +### 3. Connect to chrome driver + +```javascript +const webdriverio = require('webdriverio'); +var options = { + host: "localhost", // Use localhost as chrome driver server + port: 9515, // "9515" is the port opened by chrome driver. + desiredCapabilities: { + browserName: 'chrome', + chromeOptions: { + binary: '/Path-to-Your-App/electron', // Path to your Electron binary. + args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/ + } + } +}; + +var client = webdriverio.remote(options); + +client + .init() + .url('http://google.com') + .setValue('#q', 'webdriverio') + .click('#btnG') + .getTitle().then(function(title) { + console.log('Title was: ' + title); + }) + .end(); +``` + +## Workflow + +To test your application without rebuilding Electron, simply +[place](https://github.com/atom/electron/blob/master/docs/tutorial/application-distribution.md) +your app source into Electron's resource directory. + +Alternatively, pass an argument to run with your electron binary that points to +your app's folder. This eliminates the need to copy-paste your app into +Electron's resource directory. + +[chrome-driver]: https://sites.google.com/a/chromium.org/chromedriver/