docs: build -> electron-builder, npm -> yarn

electron-userland · Jun 20, 2017 · d96cacc · d96cacc
1 parent f24c389
commit d96cacc
Show file tree

Hide file tree

Showing 4 changed files with 48 additions and 37 deletions.
diff --git a/.idea/dictionaries/develar.xml b/.idea/dictionaries/develar.xml
diff --git a/README.md b/README.md
@@ -28,12 +28,24 @@ A complete solution to package and build a ready for distribution Electron app f
 
 Real project example — [onshape-desktop-shell](https://github.com/develar/onshape-desktop-shell).
 
+## Installation
 [Yarn](http://yarnpkg.com/) is [strongly](https://github.com/electron-userland/electron-builder/issues/1147#issuecomment-276284477) recommended instead of npm.
 
-_Note: Platform specific `7zip-bin-*` packages are `optionalDependencies`, which may require manual install if you have npm configured to [not install optional deps by default](https://docs.npmjs.com/misc/config#optional)._
+`yarn add electron-builder --dev`
+
+Platform specific `7zip-bin-*` packages are `optionalDependencies`, which may require manual install if you have npm configured to [not install optional deps by default](https://docs.npmjs.com/misc/config#optional).
+
+## Boilerplates
+
+* [electron-react-boilerplate](https://github.com/chentsulin/electron-react-boilerplate) A boilerplate for scalable cross-platform desktop apps.
+* [electron-react-redux-boilerplate](https://github.com/jschr/electron-react-redux-boilerplate) A minimal boilerplate to get started with Electron, React and Redux.
+* [electron-boilerplate](https://github.com/szwacz/electron-boilerplate) A minimalistic yet comprehensive boilerplate application.
+* [electron-vue](https://github.com/SimulatedGREG/electron-vue) A boilerplate for making electron applications built with vue.
 
 ## Quick Setup Guide
 
+Maybe some [boilerplate](#boilerplates) will suite you?
+
 1. Specify the standard fields in the application `package.json` — [name](https://github.com/electron-userland/electron-builder/wiki/Options#Metadata-name), `description`, `version` and [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors).
 
 2. Specify the [build](https://github.com/electron-userland/electron-builder/wiki/Options#build) configuration in the `package.json` as follows:
@@ -54,41 +66,26 @@ _Note: Platform specific `7zip-bin-*` packages are `optionalDependencies`, which
 4. Add the [scripts](https://docs.npmjs.com/cli/run-script) key to the development `package.json`:
     ```json
     "scripts": {
-      "pack": "build --dir",
-      "dist": "build"
+      "pack": "electron-builder --dir",
+      "dist": "electron-builder"
     }
     ```
-    Then you can run `npm run dist` (to package in a distributable format (e.g. dmg, windows installer, deb package)) or `npm run pack` (only generates the package directory without really packaging it. This is useful for testing purposes).
+    Then you can run `yarn dist` (to package in a distributable format (e.g. dmg, windows installer, deb package)) or `yarn pack` (only generates the package directory without really packaging it. This is useful for testing purposes).
 
     To ensure your native dependencies are always matched electron version, simply add script `"postinstall": "electron-builder install-app-deps"` to your `package.json`.
 
 5. If you have native addons of your own that are part of the application (not as a dependency), add `"nodeGypRebuild": true` to the `build` section of your development `package.json`.  
    :bulb: Don't [use](https://github.com/electron-userland/electron-builder/issues/683#issuecomment-241214075) [npm](http://electron.atom.io/docs/tutorial/using-native-node-modules/#using-npm) (neither `.npmrc`) for configuring electron headers. Use [node-gyp-rebuild](https://github.com/electron-userland/electron-builder/issues/683#issuecomment-241488783) bin instead.
 
 
-6. Installing the [required system packages](https://github.com/electron-userland/electron-builder/wiki/Multi-Platform-Build).
+6. Install the [required system packages](https://github.com/electron-userland/electron-builder/wiki/Multi-Platform-Build) if you are not on macOS 10.12+.
 
 Please note that everything is packaged into an asar archive [by default](https://github.com/electron-userland/electron-builder/wiki/Options#Config-asar).
 
 For an app that will be shipped to production, you should sign your application. See [Where to buy code signing certificates](https://github.com/electron-userland/electron-builder/wiki/Code-Signing#where-to-buy-code-signing-certificate).
 
-## Auto Update
-`electron-builder` produces all required artifacts, for example, for macOS:
-
-* `.dmg`: macOS installer, required for the initial installation process on macOS.
-* `-mac.zip`: required for Squirrel.Mac.
-
-See the [Auto Update](https://github.com/electron-userland/electron-builder/wiki/Auto-Update) section of the [Wiki](https://github.com/electron-userland/electron-builder/wiki).
-
-## Boilerplates
-
-* [electron-react-boilerplate](https://github.com/chentsulin/electron-react-boilerplate)
-* [electron-react-redux-boilerplate](https://github.com/jschr/electron-react-redux-boilerplate)
-* [electron-boilerplate](https://github.com/szwacz/electron-boilerplate)
-* [electron-vue](https://github.com/SimulatedGREG/electron-vue)
-
 ## CLI Usage
-Execute `node_modules/.bin/build --help` to get the actual CLI usage guide.
+Execute `node_modules/.bin/electron-builder --help` (`node_modules/.bin/electron-builder build --help` for `build subcommand) to get the actual CLI usage guide.
 ```
 Building:
   --mac, -m, -o, --macos   Build for macOS, accepts target list (see
@@ -101,6 +98,7 @@ Building:
   --ia32                   Build for ia32                              [boolean]
   --armv7l                 Build for armv7l                            [boolean]
   --dir                    Build unpacked dir. Useful to test.         [boolean]
+  --extraMetadata, --em    Deprecated. Use -c.extraMetadata.
   --prepackaged, --pd      The path to prepackaged app (to pack in a
                            distributable format)
   --projectDir, --project  The path to project directory. Defaults to current
@@ -112,26 +110,29 @@ Building:
 Publishing:
   --publish, -p  Publish artifacts (to GitHub Releases), see
                  https://goo.gl/WMlr4n
-                           [choices: "onTag", "onTagOrDraft", "always", "never"]
+                [choices: "onTag", "onTagOrDraft", "always", "never", undefined]
   --draft        Create a draft (unpublished) release                  [boolean]
   --prerelease   Identify the release as a prerelease                  [boolean]
 
 Deprecated:
   --platform  The target platform (preferred to use --mac, --win or --linux)
-                      [choices: "mac", "win", "linux", "darwin", "win32", "all"]
+           [choices: "mac", "win", "linux", "darwin", "win32", "all", undefined]
   --arch      The target arch (preferred to use --x64 or --ia32)
-                                                 [choices: "ia32", "x64", "all"]
+                                      [choices: "ia32", "x64", "all", undefined]
 
 Other:
   --help     Show help                                                 [boolean]
-  --version  Show version number                                       [boolean]
+  --version
 
 Examples:
-  build -mwl                    build for macOS, Windows and Linux
-  build --linux deb tar.xz      build deb and tar.xz for Linux
-  build --win --ia32            build for Windows ia32
-  build --em.foo=bar            set package.json property `foo` to `bar`
-  build --config.nsis.unicode=false  configure unicode options for NSIS
+  electron-builder -mwl                     build for macOS, Windows and Linux
+  electron-builder --linux deb tar.xz       build deb and tar.xz for Linux
+  electron-builder --win --ia32             build for Windows ia32
+  electron-builder --em.foo=bar             set package.json property `foo` to
+                                            `bar`
+  electron-builder                          configure unicode options for NSIS
+  --config.nsis.unicode=false
+
 ```
 
 ## Programmatic Usage

diff --git a/docs/Docker.md b/docs/Docker.md
@@ -6,11 +6,11 @@ To build Linux or Windows (only if you don't have native dependencies) on any pl
    docker run --rm -ti -v ${PWD}:/project -v ${PWD##*/}-node-modules:/project/node_modules -v ~/.electron:/root/.electron electronuserland/electron-builder:wine
    ```
 
-2. Type in `npm install && npm prune && npm run dist`
+2. Type in `yarn && yarn dist`
 
-   If you don't have `dist` npm script in your `package.json`, call `./node_modules/.bin/build` directly.
+   If you don't have `dist` npm script in your `package.json`, call `./node_modules/.bin/electron-builder` directly.
 
-Or to avoid second step, append to first command `/bin/bash -c "npm install && npm prune && npm run dist"`
+Or to avoid second step, append to first command `/bin/bash -c "yarn && yarn dist"`
 
 If you don't need to build Windows, use image `electronuserland/electron-builder:latest` (wine is not installed in this image).
 

diff --git a/docs/Multi Platform Build.md b/docs/Multi Platform Build.md
@@ -14,7 +14,7 @@ By default build for current platform and current arch. Use CLI flags `--mac`, `
 
 For example, to build app for MacOS, Windows and Linux:
 ```
-build -mwl
+electron-builder -mwl
 ```
 
 Build performed in parallel, so, it is highly recommended to not use npm task per platform (e.g. `npm run dist:mac && npm run dist:win32`), but specify multiple platforms/targets in one build command.
@@ -28,6 +28,8 @@ To build rpm: `brew install rpm` ([brew](https://brew.sh)).
 
 ## Linux
 
+You can use [Docker](https://github.com/electron-userland/electron-builder/wiki/Docker) to avoid installing system dependencies.
+
 To build app in distributable format for Linux:
 ```
 sudo apt-get install --no-install-recommends -y icnsutils graphicsmagick xz-utils
@@ -48,7 +50,7 @@ To build snap: `sudo apt-get install --no-install-recommends -y snapcraft`.
   sudo apt-get install --no-install-recommends -y wine1.8
   ```
 
-* Install [Mono](http://www.mono-project.com/docs/getting-started/install/linux/#usage) (4.2+ is required):
+* Install [Mono](http://www.mono-project.com/docs/getting-started/install/linux/#usage) (4.2+ is required) if you want to use Squirrel.Windows (NSIS, default target, doesn't require mono):
 
   ```
   sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
@@ -57,19 +59,25 @@ To build snap: `sudo apt-get install --no-install-recommends -y snapcraft`.
   sudo apt-get install --no-install-recommends -y mono-devel ca-certificates-mono
   ```
 
-### To build app in 32 bit from a machine with 64 bit:
+## To build app in 32 bit from a machine with 64 bit:
 
 ```
 sudo apt-get install --no-install-recommends -y gcc-multilib g++-multilib
 ```
 
-### Travis Linux
+## Travis Linux
 [Trusty](https://docs.travis-ci.com/user/trusty-ci-environment/) is required — default Travis Linux dist is outdated and `icnsutils` version is non-functional.
 ```yaml
 sudo: required
 dist: trusty
 ```
 
+### Travis macOS
+[macOS 10.12+](https://docs.travis-ci.com/user/osx-ci-environment/#OS-X-Version) is required.
+```yaml
+osx_image: xcode8.3
+```
+
 ## Windows
 
 Please use [Docker](https://github.com/electron-userland/electron-builder/wiki/Docker).