feat: iconUrl git-lfs support, os x identity/installerIdentity options

Add Programmatic Usage example

Closes #332

README.md

@@ -1,10 +1,6 @@
-# electron-builder [![NPM version][npm-image]][npm-url]
+# electron-builder [![npm version](https://img.shields.io/npm/v/electron-builder.svg)](https://npmjs.org/package/electron-builder)
 Complete solution to build ready for distribution and "auto update" installers of your app for OS X, Windows and Linux.
 
-```sh
-npm install electron-builder --save-dev
-```
-
 * [Native application dependencies](http://electron.atom.io/docs/latest/tutorial/using-native-node-modules/) compilation (only if [two-package.json project structure](#two-packagejson-structure) used).
 * [Auto Update](#auto-update) ready application packaging.
 * [Code Signing](https://github.com/electron-userland/electron-builder/wiki/Code-Signing) on a CI server or development machine.
@@ -50,7 +46,9 @@ See [options](https://github.com/electron-userland/electron-builder/wiki/Options
     "build": {
       "app-bundle-id": "your.id",
       "app-category-type": "your.app.category.type",
-      "iconUrl": "(windows only)"
+      "win": {
+        "iconUrl": "(windows-only) https link to icon"
+      }
     }
     ```
    See [options](https://github.com/electron-userland/electron-builder/wiki/Options). This object will be used as a source of [electron-packager](https://www.npmjs.com/package/electron-packager#packageropts-callback) options. You can specify any other options here.
@@ -103,8 +101,26 @@ Want more — please file issue.
 # Programmatic Usage
 See `node_modules/electron-builder/out/electron-builder.d.ts`. [Typings](https://github.com/Microsoft/TypeScript/wiki/Typings-for-npm-packages) is supported.
 
-[npm-url]: https://npmjs.org/package/electron-builder
-[npm-image]: http://img.shields.io/npm/v/electron-builder.svg
+```js
+"use strict"
+
+const builder = require("electron-builder")
+
+// Promise is returned
+builder.build({
+  platform: [builder.Platform.OSX],
+  "//": "platform, arch and other properties, see PackagerOptions in the node_modules/electron-builder/out/electron-builder.d.ts",
+  devMetadata: {
+    "//": "build and other properties, see https://goo.gl/5jVxoO"
+  }
+})
+  .then(() => {
+    // handle result
+  })
+  .catch((error) => {
+    // handle error
+  })
+```
 
 # Further Reading
 See the [Wiki](https://github.com/electron-userland/electron-builder/wiki) for more documentation.

docs/Options.md

@@ -53,10 +53,10 @@ Here documented only `electron-builder` specific options:
 | app-bundle-id | <a name="BuildMetadata-app-bundle-id"></a>*OS X-only.* The app bundle ID. See [CFBundleIdentifier](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102070).
 | app-category-type | <a name="BuildMetadata-app-category-type"></a><p>*OS X-only.* The application category type, as shown in the Finder via *View -&gt; Arrange by Application Category* when viewing the Applications directory.</p> <p>For example, <code>app-category-type=public.app-category.developer-tools</code> will set the application category to *Developer Tools*.</p> <p>Valid values are listed in [Apple’s documentation](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/uid/TP40009250-SW8).</p>
 | asar | <a name="BuildMetadata-asar"></a><p>Whether to package the application’s source code into an archive, using [Electron’s archive format](https://github.com/electron/asar). Defaults to <code>true</code>. Reasons why you may want to disable this feature are described in [an application packaging tutorial in Electron’s documentation](http://electron.atom.io/docs/latest/tutorial/application-packaging/#limitations-on-node-api/).</p>
-| iconUrl | <a name="BuildMetadata-iconUrl"></a><p>*windows-only.* A URL to an ICO file to use as the application icon (displayed in Control Panel &gt; Programs and Features). Defaults to the Electron icon.</p> <p>Please note — [local icon file url is not accepted](https://github.com/atom/grunt-electron-installer/issues/73), must be https/http.</p> <ul> <li>If you don’t plan to build windows installer, you can omit it.</li> <li>If your project repository is public on GitHub, it will be <code>https://raw.githubusercontent.com/${u}/${p}/master/build/icon.ico</code> by default.</li> </ul>
 | productName | <a name="BuildMetadata-productName"></a>See [AppMetadata.productName](#AppMetadata-productName).
 | extraResources | <a name="BuildMetadata-extraResources"></a><p>A [glob expression](https://www.npmjs.com/package/glob#glob-primer), when specified, copy the file or directory with matching names directly into the app’s directory (<code>Contents/Resources</code> for OS X).</p> <p>You can use <code>${os}</code> (expanded to osx, linux or win according to current platform) and <code>${arch}</code> in the pattern.</p> <p>If directory matched, all contents are copied. So, you can just specify <code>foo</code> to copy <code>&lt;project_dir&gt;/foo</code> directory.</p> <p>May be specified in the platform options (i.e. in the <code>build.osx</code>).</p>
 | osx | <a name="BuildMetadata-osx"></a>See [.build.osx](#OsXBuildOptions).
+| mas | <a name="BuildMetadata-mas"></a>See [.build.mas](#MasBuildOptions).
 | win | <a name="BuildMetadata-win"></a>See [.build.win](#LinuxBuildOptions).
 | linux | <a name="BuildMetadata-linux"></a>See [.build.linux](#LinuxBuildOptions).
 | compression | <a name="BuildMetadata-compression"></a>The compression level, one of `store`, `normal`, `maximum` (default: `normal`). If you want to rapidly test build, `store` can reduce build time significantly.
@@ -70,7 +70,21 @@ See all [appdmg options](https://www.npmjs.com/package/appdmg#json-specification
 | --- | ---
 | icon | <a name="OsXBuildOptions-icon"></a>The path to icon, which will be shown when mounted (default: `build/icon.icns`).
 | background | <a name="OsXBuildOptions-background"></a>The path to background (default: `build/background.png`). The resolution of this file determines the resolution of the installer window.
-| target | <a name="OsXBuildOptions-target"></a>Target package type: list of `default`, `dmg`, `zip`, `mas`, `7z`.
+| target | <a name="OsXBuildOptions-target"></a>Target package type: list of `default`, `dmg`, `zip`, `mas`, `7z`. Defaults to `default` (dmg and zip for Squirrel.Mac).
+| identity | <a name="OsXBuildOptions-identity"></a><p>The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](https://github.com/electron-userland/electron-builder/wiki/Code-Signing). MAS installer identity is specified in the [.build.mas](#MasBuildOptions-identity).</p>
+| entitlements | <a name="OsXBuildOptions-entitlements"></a><p>The path to entitlements file for signing the app. <code>build/osx.entitlements</code> will be used if exists (it is a recommended way to set). MAS entitlements is specified in the [.build.mas](#MasBuildOptions-entitlements).</p>
+| entitlementsInherit | <a name="OsXBuildOptions-entitlementsInherit"></a><p>The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. <code>build/osx.inherit.entitlements</code> will be used if exists (it is a recommended way to set). Otherwise [default](https://github.com/electron-userland/electron-osx-sign/blob/master/default.darwin.inherit.entitlements).</p> <p>This option only applies when signing with <code>entitlements</code> provided.</p>
+
+<a name="MasBuildOptions"></a>
+### `.build.mas`
+
+MAS (Mac Application Store) specific options (in addition to `build.osx`).
+
+| Name | Description
+| --- | ---
+| identity | <a name="MasBuildOptions-identity"></a>The name of certificate to use when signing. Consider using environment variables [CSC_INSTALLER_LINK or CSC_INSTALLER_NAME](https://github.com/electron-userland/electron-builder/wiki/Code-Signing).
+| entitlements | <a name="MasBuildOptions-entitlements"></a><p>The path to entitlements file for signing the app. <code>build/mas.entitlements</code> will be used if exists (it is a recommended way to set). Otherwise [default](https://github.com/electron-userland/electron-osx-sign/blob/master/default.mas.entitlements).</p>
+| entitlementsInherit | <a name="MasBuildOptions-entitlementsInherit"></a><p>The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. <code>build/mas.inherit.entitlements</code> will be used if exists (it is a recommended way to set). Otherwise [default](https://github.com/electron-userland/electron-osx-sign/blob/master/default.mas.inherit.entitlements).</p>
 
 <a name="WinBuildOptions"></a>
 ### `.build.win`
@@ -79,7 +93,8 @@ See all [windows-installer options](https://github.com/electron/windows-installe
 
 | Name | Description
 | --- | ---
-| loadingGif | <a name="WinBuildOptions-loadingGif"></a><p>The path to a .gif file to display during install. <code>build/install-spinner.gif</code> will be used if exists (otherwise [default](https://github.com/electron/windows-installer/blob/master/resources/install-spinner.gif)).</p>
+| iconUrl | <a name="WinBuildOptions-iconUrl"></a><p>*windows-only.* A URL to an ICO file to use as the application icon (displayed in Control Panel &gt; Programs and Features). Defaults to the Electron icon.</p> <p>Please note — [local icon file url is not accepted](https://github.com/atom/grunt-electron-installer/issues/73), must be https/http.</p> <ul> <li>If you don’t plan to build windows installer, you can omit it.</li> <li>If your project repository is public on GitHub, it will be <code>https://github.com/${u}/${p}/blob/master/build/icon.ico?raw=true</code> by default.</li> </ul>
+| loadingGif | <a name="WinBuildOptions-loadingGif"></a><p>The path to a .gif file to display during install. <code>build/install-spinner.gif</code> will be used if exists (it is a recommended way to set) (otherwise [default](https://github.com/electron/windows-installer/blob/master/resources/install-spinner.gif)).</p>
 | noMsi | <a name="WinBuildOptions-noMsi"></a>Whether to create an MSI installer. Defaults to `true` (MSI is not created).
 
 <a name="LinuxBuildOptions"></a>

docs/programmaticUsage.js

@@ -0,0 +1,18 @@
+"use strict"
+
+const builder = require("electron-builder")
+
+// Promise is returned
+builder.build({
+  platform: [builder.Platform.OSX],
+  "//": "platform, arch and other properties, see PackagerOptions in the node_modules/electron-builder/out/electron-builder.d.ts",
+  devMetadata: {
+    "//": "build and other properties, see https://goo.gl/5jVxoO"
+  }
+})
+  .then(() => {
+    // handle result
+  })
+  .catch((error) => {
+    // handle error
+  })

package.json

@@ -60,9 +60,9 @@
     "command-line-args": "^2.1.6",
     "debug": "^2.2.0",
     "deep-assign": "^2.0.0",
-    "electron-osx-sign-tf": "^0.4.0-beta.0",
+    "electron-osx-sign-tf": "~0.5.0-beta.0",
     "electron-packager-tf": "^7.0.2-beta.0",
-    "electron-winstaller-fixed": "~2.4.0-beta.0",
+    "electron-winstaller-fixed": "~2.4.0-beta.1",
     "fs-extra-p": "^0.4.0",
     "globby": "^4.0.0",
     "hosted-git-info": "^2.1.4",
@@ -91,7 +91,7 @@
     "babel-plugin-transform-es2015-parameters": "^6.7.0",
     "babel-plugin-transform-es2015-spread": "^6.6.5",
     "decompress-zip": "^0.3.0",
-    "electron-download": "^2.1.1",
+    "electron-download": "^2.1.2",
     "json-parse-helpfulerror": "^1.0.3",
     "path-sort": "^0.1.0",
     "plist": "^1.2.0",

src/linuxPackager.ts

@@ -44,7 +44,7 @@ export class LinuxPackager extends PlatformPackager<LinuxBuildOptions> {
     const tempDir = await tempDirPromise
 
     const promises: Array<Promise<Array<string>>> = []
-    if (this.customBuildOptions == null || this.customBuildOptions.desktop == null) {
+    if (this.customBuildOptions.desktop == null) {
       promises.push(this.computeDesktopIconPath(tempDir))
     }
 

src/metadata.ts

@@ -94,14 +94,7 @@ export interface BuildMetadata {
    */
   readonly asar?: boolean
 
-  /*
-   *windows-only.* A URL to an ICO file to use as the application icon (displayed in Control Panel > Programs and Features). Defaults to the Electron icon.
-
-   Please note — [local icon file url is not accepted](https://github.com/atom/grunt-electron-installer/issues/73), must be https/http.
-
-   * If you don't plan to build windows installer, you can omit it.
-   * If your project repository is public on GitHub, it will be `https://raw.githubusercontent.com/${u}/${p}/master/build/icon.ico` by default.
-   */
+  // deprecated
   readonly iconUrl?: string
 
   /*
@@ -125,6 +118,11 @@ export interface BuildMetadata {
    */
   readonly osx?: OsXBuildOptions
 
+  /*
+   See [.build.mas](#MasBuildOptions).
+   */
+  readonly mas?: MasBuildOptions
+
   /**
    See [.build.win](#LinuxBuildOptions).
    */
@@ -160,9 +158,53 @@ export interface OsXBuildOptions extends PlatformSpecificBuildOptions {
   readonly background?: string
 
   /*
-   Target package type: list of `default`, `dmg`, `zip`, `mas`, `7z`.
+   Target package type: list of `default`, `dmg`, `zip`, `mas`, `7z`. Defaults to `default` (dmg and zip for Squirrel.Mac).
   */
   readonly target?: Array<string>
+
+  /*
+   The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](https://github.com/electron-userland/electron-builder/wiki/Code-Signing).
+   MAS installer identity is specified in the [.build.mas](#MasBuildOptions-identity).
+   */
+  readonly identity?: string
+
+  /*
+   The path to entitlements file for signing the app. `build/osx.entitlements` will be used if exists (it is a recommended way to set).
+   MAS entitlements is specified in the [.build.mas](#MasBuildOptions-entitlements).
+   */
+  readonly entitlements?: string
+
+  /*
+   The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. `build/osx.inherit.entitlements` will be used if exists (it is a recommended way to set).
+   Otherwise [default](https://github.com/electron-userland/electron-osx-sign/blob/master/default.darwin.inherit.entitlements).
+
+   This option only applies when signing with `entitlements` provided.
+   */
+  readonly entitlementsInherit?: string
+}
+
+/*
+ ### `.build.mas`
+
+ MAS (Mac Application Store) specific options (in addition to `build.osx`).
+ */
+export interface MasBuildOptions extends OsXBuildOptions {
+  /*
+   The name of certificate to use when signing. Consider using environment variables [CSC_INSTALLER_LINK or CSC_INSTALLER_NAME](https://github.com/electron-userland/electron-builder/wiki/Code-Signing).
+  */
+  readonly identity?: string
+
+  /*
+   The path to entitlements file for signing the app. `build/mas.entitlements` will be used if exists (it is a recommended way to set).
+   Otherwise [default](https://github.com/electron-userland/electron-osx-sign/blob/master/default.mas.entitlements).
+   */
+  readonly entitlements?: string
+
+  /*
+   The path to child entitlements which inherit the security settings for signing frameworks and bundles of a distribution. `build/mas.inherit.entitlements` will be used if exists (it is a recommended way to set).
+   Otherwise [default](https://github.com/electron-userland/electron-osx-sign/blob/master/default.mas.inherit.entitlements).
+   */
+  readonly entitlementsInherit?: string
 }
 
 /*
@@ -174,10 +216,18 @@ export interface WinBuildOptions extends PlatformSpecificBuildOptions {
   readonly certificateFile?: string
   readonly certificatePassword?: string
 
+  /*
+   *windows-only.* A URL to an ICO file to use as the application icon (displayed in Control Panel > Programs and Features). Defaults to the Electron icon.
+
+   Please note — [local icon file url is not accepted](https://github.com/atom/grunt-electron-installer/issues/73), must be https/http.
+
+   * If you don't plan to build windows installer, you can omit it.
+   * If your project repository is public on GitHub, it will be `https://github.com/${u}/${p}/blob/master/build/icon.ico?raw=true` by default.
+   */
   readonly iconUrl?: string
 
   /*
-   The path to a .gif file to display during install. `build/install-spinner.gif` will be used if exists
+   The path to a .gif file to display during install. `build/install-spinner.gif` will be used if exists (it is a recommended way to set)
    (otherwise [default](https://github.com/electron/windows-installer/blob/master/resources/install-spinner.gif)).
    */
   readonly loadingGif?: string