Add download parameter; deprecate cache & strict-ssl parameters

NEWS.md

@@ -2,10 +2,19 @@
 
 ## Unreleased
 
+### Added
+
+* Add `download` parameter (#320)
+
 ### Changed
 
 * **Dropped support for running on Node < 4.0.** (#319)
 
+### Deprecated
+
+* `cache` is deprecated in favor of `download.cache` (#320)
+* `strict-ssl` is deprecated in favor of `download.strictSSL` (#320)
+
 ## [6.0.2] - 2016-04-09
 
 ### Changed

cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 var fs = require('fs')
-var args = require('minimist')(process.argv.slice(2), {boolean: ['prune', 'asar', 'all', 'overwrite', 'strict-ssl']})
+var args = require('minimist')(process.argv.slice(2), {boolean: ['prune', 'asar', 'all', 'overwrite', 'strict-ssl', 'download.strictSSL']})
 var packager = require('./')
 var path = require('path')
 var usage = fs.readFileSync(path.join(__dirname, 'usage.txt')).toString()

common.js

@@ -28,6 +28,13 @@ function generateFinalPath (opts) {
   return path.join(opts.out || process.cwd(), generateFinalBasename(opts))
 }
 
+function subOptionWarning (properties, option_name, parameter, value) {
+  if (properties.hasOwnProperty(parameter)) {
+    console.warn(`WARNING: ${option_name}.${parameter} will be inferred from the main options`)
+  }
+  properties[parameter] = value
+}
+
 function userIgnoreFilter (opts) {
   var ignore = opts.ignore || []
   var ignoreFunc = null
@@ -84,6 +91,29 @@ module.exports = {
     return platform === 'darwin' || platform === 'mas'
   },
 
+  subOptionWarning: subOptionWarning,
+
+  createDownloadOpts: function createDownloadOpts (opts, platform, arch) {
+    if (opts.hasOwnProperty('cache')) {
+      console.warn('The cache parameter is deprecated, use download.cache instead')
+    }
+
+    if (opts.hasOwnProperty('strict-ssl')) {
+      console.warn('The strict-ssl parameter is deprecated, use download.strictSSL instead')
+    }
+
+    var downloadOpts = Object.assign({
+      cache: opts.cache,
+      strictSSL: opts['strict-ssl']
+    }, opts.download)
+
+    subOptionWarning(downloadOpts, 'download', 'platform', platform)
+    subOptionWarning(downloadOpts, 'download', 'arch', arch)
+    subOptionWarning(downloadOpts, 'download', 'version', opts.version)
+
+    return downloadOpts
+  },
+
   generateFinalBasename: generateFinalBasename,
   generateFinalPath: generateFinalPath,
 

docs/api.md

@@ -90,10 +90,23 @@ The build version of the application. Maps to the `FileVersion` metadata propert
 
 ##### `cache`
 
-*String* (default: `$HOME/.electron`)
+*String* (default: `$HOME/.electron`) (**deprecated** and will be removed in a future major version,
+please use the [`download.cache`](#download) parameter instead)
 
 The directory where prebuilt, pre-packaged Electron downloads are cached.
 
+##### `download`
+
+*Object*
+
+If present, passes custom options to [`electron-download`](https://www.npmjs.com/package/electron-download)
+(see the link for more detailed option descriptions and the defaults). Supported parameters include,
+but are not limited to:
+- `cache` (*String*): The directory where prebuilt, pre-packaged Electron downloads are cached.
+- `mirror` (*String*): The URL to override the default Electron download location.
+- `strictSSL` (*Boolean* - default: `true`): Whether SSL certificates are required to be valid when
+  downloading Electron.
+
 ##### `icon`
 
 *String*
@@ -138,7 +151,8 @@ Runs [`npm prune --production`](https://docs.npmjs.com/cli/prune) before startin
 
 ##### `strict-ssl`
 
-*Boolean* (**default: `true`**)
+*Boolean* (**default: `true`**) (**deprecated** and will be removed in a future major version,
+please use the [`download.strictSSL`](#download) parameter instead)
 
 Whether SSL certificates are required to be valid when downloading Electron.
 

index.js

@@ -91,13 +91,7 @@ function createSeries (opts, archs, platforms) {
     platforms.forEach(function (platform) {
       // Electron does not have 32-bit releases for Mac OS X, so skip that combination
       if (common.isPlatformMac(platform) && arch === 'ia32') return
-      combinations.push({
-        platform: platform,
-        arch: arch,
-        version: opts.version,
-        cache: opts.cache,
-        strictSSL: opts['strict-ssl']
-      })
+      combinations.push(common.createDownloadOpts(opts, platform, arch))
     })
   })
 

mac.js

@@ -30,26 +30,15 @@ function filterCFBundleIdentifier (identifier) {
   return identifier.replace(/ /g, '-').replace(/[^a-zA-Z0-9.-]/g, '')
 }
 
-function signOptsWarning (name) {
-  console.warn(`WARNING: osx-sign.${name} will be inferred from main options`)
-}
-
 function createSignOpts (properties, platform, app) {
   // use default sign opts if osx-sign is true, otherwise clone osx-sign object
   var signOpts = properties === true ? {identity: null} : Object.assign({}, properties)
 
   // osx-sign options are handed off to sign module, but
-  // with a few additions from main options
+  // with a few additions from the main options
   // user may think they can pass platform or app, but they will be ignored
-  if (signOpts.platform) {
-    signOptsWarning('platform')
-  }
-  signOpts.platform = platform
-
-  if (signOpts.app) {
-    signOptsWarning('app')
-  }
-  signOpts.app = app
+  common.subOptionWarning(signOpts, 'osx-sign', 'platform', platform)
+  common.subOptionWarning(signOpts, 'osx-sign', 'app', app)
 
   if (signOpts.binaries) {
     console.warn('WARNING: osx-sign.binaries signing will fail. Sign manually, or with electron-osx-sign.')

test/basic.js

@@ -466,6 +466,49 @@ function createIgnoreImplicitOutDirTest (opts) {
   }
 }
 
+test('download argument test: download.cache overwrites cache', function (t) {
+  var opts = {
+    cache: 'should not exist',
+    download: {
+      cache: 'should exist'
+    },
+    version: '0.36.0'
+  }
+
+  var downloadOpts = common.createDownloadOpts(opts, 'linux', 'x64')
+  t.same(downloadOpts, {arch: 'x64', platform: 'linux', version: '0.36.0', cache: opts.download.cache, strictSSL: undefined})
+  t.end()
+})
+
+test('download argument test: download.strictSSL overwrites strict-ssl', function (t) {
+  var opts = {
+    download: {
+      strictSSL: false
+    },
+    'strict-ssl': true,
+    version: '0.36.0'
+  }
+
+  var downloadOpts = common.createDownloadOpts(opts, 'linux', 'x64')
+  t.same(downloadOpts, {arch: 'x64', platform: 'linux', version: '0.36.0', cache: undefined, strictSSL: opts.download.strictSSL})
+  t.end()
+})
+
+test('download argument test: download.{arch,platform,version} does not overwrite {arch,platform,version}', function (t) {
+  var opts = {
+    download: {
+      arch: 'ia32',
+      platform: 'win32',
+      version: '0.30.0'
+    },
+    version: '0.36.0'
+  }
+
+  var downloadOpts = common.createDownloadOpts(opts, 'linux', 'x64')
+  t.same(downloadOpts, {arch: 'x64', platform: 'linux', version: '0.36.0', cache: undefined, strictSSL: undefined})
+  t.end()
+})
+
 util.testAllPlatforms('infer test', createInferTest)
 util.testAllPlatforms('defaults test', createDefaultsTest)
 util.testAllPlatforms('default_app.asar removal test', createDefaultAppAsarTest)

usage.txt

@@ -23,6 +23,14 @@ asar-unpack-dir    unpacks the dir to app.asar.unpacked directory whose names ma
                    For example, `--asar-unpack-dir=sub_dir` will unpack the directory `/<sourcedir>/sub_dir`.
 build-version      build version to set for the app
 cache              directory of cached Electron downloads. Defaults to '$HOME/.electron'
+                   (Deprecated, use --download.cache instead)
+download           a list of sub-options to pass to electron-download. They are specified via dot
+                   notation, e.g., --download.cache=/tmp/cache
+                   Properties supported:
+                   - cache: directory of cached Electron downloads. Defaults to '$HOME/.electron'
+                   - mirror: alternate URL to download Electron zips
+                   - strictSSL: whether SSL certs are required to be valid when downloading
+                     Electron. Defaults to true, use --download.strictSSL=false to disable checks.
 icon               the icon file to use as the icon for the app. Note: Format depends on platform.
 ignore             do not copy files into app whose filenames regex .match this string
 out                the dir to put the app into at the end. defaults to current working dir
@@ -30,6 +38,7 @@ overwrite          if output directory for a platform already exists, replaces i
 prune              runs `npm prune --production` on the app
 strict-ssl         whether SSL certificates are required to be valid when downloading Electron.
                    It defaults to true, use --strict-ssl=false to disable checks.
+                   (Deprecated, use --download.strictSSL instead)
 tmpdir             temp directory. Defaults to system temp directory, use --tmpdir=false to disable use of a temporary directory.
 version            the version of Electron that is being packaged, see https://github.com/electron/electron/releases