Unify asar options

NEWS.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+### Added
+
+* `asar` options can be specified as an `Object` (via the API) or with dot notation (via the CLI) -
+  see the respective docs for details (#353, #417)
+
+### Deprecated
+
+* `asar-unpack` is deprecated in favor of `asar.unpack` (#417)
+* `asar-unpack-dir` is deprecated in favor of `asar.unpackDir` (#417)
+
 ## [7.2.0] - 2016-07-03
 
 ### Added

common.js

@@ -15,7 +15,6 @@ function parseCLIArgs (argv) {
   var args = minimist(argv, {
     boolean: [
       'prune',
-      'asar',
       'all',
       'overwrite',
       'strict-ssl',
@@ -41,16 +40,23 @@ function parseCLIArgs (argv) {
     })
   }
 
-  // minimist doesn't support multiple types for a single argument (in this case, `String` or `false`)
-  if (args.tmpdir === 'false') {
-    args.tmpdir = false
+  // Overrides for multi-typed arguments, because minimist doesn't support it
+
+  // asar: `Object` or `true`
+  if (args.asar === 'true') {
+    args.asar = true
   }
 
-  // (in this case, `Object` or `true`)
+  // osx-sign: `Object` or `true`
   if (args['osx-sign'] === 'true') {
     args['osx-sign'] = true
   }
 
+  // tmpdir: `String` or `false`
+  if (args.tmpdir === 'false') {
+    args.tmpdir = false
+  }
+
   return args
 }
 
@@ -81,6 +87,15 @@ function subOptionWarning (properties, optionName, parameter, value) {
   properties[parameter] = value
 }
 
+function deprecatedParameter (properties, oldName, newName, extraCondition/* optional */) {
+  if (extraCondition === undefined) {
+    extraCondition = true
+  }
+  if (properties.hasOwnProperty(oldName) && extraCondition) {
+    console.warn(`The ${oldName} parameter is deprecated, use ${newName} instead`)
+  }
+}
+
 function userIgnoreFilter (opts) {
   var ignore = opts.ignore || []
   var ignoreFunc = null
@@ -129,6 +144,28 @@ function userIgnoreFilter (opts) {
   }
 }
 
+function createAsarOpts (opts) {
+  deprecatedParameter(opts, 'asar-unpack', 'asar.unpack')
+  deprecatedParameter(opts, 'asar-unpack-dir', 'asar.unpackDir')
+
+  let asarOptions
+  if (opts.asar === true) {
+    asarOptions = {}
+  } else if (typeof opts.asar === 'object') {
+    asarOptions = opts.asar
+  } else if (opts.asar === false || opts.asar === undefined) {
+    return false
+  } else {
+    console.warn(`asar parameter set to an invalid value (${opts.asar}), ignoring and disabling asar`)
+    return false
+  }
+
+  return Object.assign({
+    unpack: opts['asar-unpack'],
+    unpackDir: opts['asar-unpack-dir']
+  }, asarOptions)
+}
+
 module.exports = {
   archs: archs,
   platforms: platforms,
@@ -141,14 +178,11 @@ module.exports = {
 
   subOptionWarning: subOptionWarning,
 
-  createDownloadOpts: function createDownloadOpts (opts, platform, arch) {
-    if (opts.hasOwnProperty('cache')) {
-      console.warn('The cache parameter is deprecated, use download.cache instead')
-    }
+  createAsarOpts: createAsarOpts,
 
-    if (opts.hasOwnProperty('strict-ssl') && opts['strict-ssl'] === false) {
-      console.warn('The strict-ssl parameter is deprecated, use download.strictSSL instead')
-    }
+  createDownloadOpts: function createDownloadOpts (opts, platform, arch) {
+    deprecatedParameter(opts, 'cache', 'download.cache')
+    deprecatedParameter(opts, 'strict-ssl', 'download.strictSSL', opts['strict-ssl'] === false)
 
     var downloadOpts = Object.assign({
       cache: opts.cache,
@@ -215,15 +249,9 @@ module.exports = {
       })
     }
 
-    if (opts.asar) {
+    let asarOptions = createAsarOpts(opts)
+    if (asarOptions) {
       operations.push(function (cb) {
-        var asarOptions = {}
-        if (opts['asar-unpack']) {
-          asarOptions.unpack = opts['asar-unpack']
-        }
-        if (opts['asar-unpack-dir']) {
-          asarOptions.unpackDir = opts['asar-unpack-dir']
-        }
         asarApp(path.join(appPath), asarOptions, cb)
       })
     }

docs/api.md

@@ -77,19 +77,31 @@ The release version of the application. Maps to the `ProductVersion` metadata pr
 
 ##### `asar`
 
-*Boolean* (default: `false`)
+*Boolean* or *Object* (default: `false`)
+
+Whether to package the application's source code into an archive, using [Electron's archive format](https://github.com/electron/asar). Reasons why you may want to enable this feature are described in [an application packaging tutorial in Electron's documentation](http://electron.atom.io/docs/v0.36.0/tutorial/application-packaging/). When the value is `true`, pass default configuration to the `asar` module. The configuration values listed below can be customized when the value is an `Object`. Supported parameters include, but are not limited to:
+- `ordering` (*String*): A path to an ordering file for packing files. An explanation can be found on the [Atom issue tracker](https://github.com/atom/atom/issues/10163).
+- `unpack` (*String*): A [glob expression](https://github.com/isaacs/minimatch#features), when specified, unpacks the file with matching names to the `app.asar.unpacked` directory.
+- `unpackDir` (*String*): Unpacks the dir to the `app.asar.unpacked` directory whose names exactly or pattern match this string. The `asar.unpackDir` is relative to `dir`.
+
+  Some examples:
 
-Whether to package the application's source code into an archive, using [Electron's archive format](https://github.com/electron/asar). Reasons why you may want to enable this feature are described in [an application packaging tutorial in Electron's documentation](http://electron.atom.io/docs/v0.36.0/tutorial/application-packaging/).
+  - `asar.unpackDir = 'sub_dir'` will unpack the directory `/<dir>/sub_dir`
+  - `asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/*'` will unpack the directories `/<dir>/sub_dir1/sub_sub_dir` and `/<dir>/sub_dir2`, but it will not include their subdirectories.
+  - `asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/**'` will unpack the subdirectories of the directories `/<dir>/sub_dir1/sub_sub_dir` and `/<dir>/sub_dir2`.
+  - `asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/**/*'` will unpack the directories `/<dir>/sub_dir1/sub_sub_dir` and `/<dir>/sub_dir2` and their subdirectories.
 
 ##### `asar-unpack`
 
-*String*
+*String* (**deprecated** and will be removed in a future major version,
+please use the [`asar.unpack`](#asar) parameter instead)
 
 A [glob expression](https://github.com/isaacs/minimatch#features), when specified, unpacks the file with matching names to the `app.asar.unpacked` directory.
 
 ##### `asar-unpack-dir`
 
-*String*
+*String* (**deprecated** and will be removed in a future major version,
+please use the [`asar.unpackDir`](#asar) parameter instead)
 
 Unpacks the dir to `app.asar.unpacked` directory whose names exactly or pattern match this string. The `asar-unpack-dir` is relative to `dir`.
 

test/basic.js

@@ -146,9 +146,10 @@ function createAsarTest (opts) {
 
     opts.name = 'basicTest'
     opts.dir = path.join(__dirname, 'fixtures', 'basic')
-    opts.asar = true
-    opts['asar-unpack'] = '*.pac'
-    opts['asar-unpack-dir'] = 'dir_to_unpack'
+    opts.asar = {
+      'unpack': '*.pac',
+      'unpackDir': 'dir_to_unpack'
+    }
     var finalPath
     var resourcesPath
 
@@ -509,6 +510,82 @@ function createDisableSymlinkDereferencingTest (opts) {
   }
 }
 
+test('asar argument test: asar is not set', function (t) {
+  var opts = {}
+
+  var asarOpts = common.createAsarOpts(opts)
+  t.false(asarOpts, 'createAsarOpts returns false')
+  t.end()
+})
+
+test('asar argument test: asar is true', function (t) {
+  var opts = {
+    asar: true
+  }
+
+  var asarOpts = common.createAsarOpts(opts)
+  t.same(asarOpts, {unpack: undefined, unpackDir: undefined})
+  t.end()
+})
+
+test('asar argument test: asar is not an Object or a bool', function (t) {
+  var opts = {
+    asar: 'string'
+  }
+
+  var asarOpts = common.createAsarOpts(opts)
+  t.false(asarOpts, 'createAsarOpts returns false')
+  t.end()
+})
+
+test('asar argument test: asar-unpack still works albeit deprecated', function (t) {
+  var opts = {
+    asar: true,
+    'asar-unpack': 'deprecated'
+  }
+
+  var asarOpts = common.createAsarOpts(opts)
+  t.same(asarOpts, {unpack: 'deprecated', unpackDir: undefined})
+  t.end()
+})
+
+test('asar argument test: asar.unpack overwrites asar-unpack', function (t) {
+  var opts = {
+    asar: {
+      unpack: 'should exist'
+    },
+    'asar-unpack': 'should not exist'
+  }
+
+  var asarOpts = common.createAsarOpts(opts)
+  t.same(asarOpts, {unpack: 'should exist', unpackDir: undefined})
+  t.end()
+})
+
+test('asar argument test: asar-unpack-dir still works albeit deprecated', function (t) {
+  var opts = {
+    asar: true,
+    'asar-unpack-dir': 'deprecated'
+  }
+
+  var asarOpts = common.createAsarOpts(opts)
+  t.same(asarOpts, {unpack: undefined, unpackDir: 'deprecated'})
+  t.end()
+})
+
+test('asar argument test: asar.unpackDir overwrites asar-unpack-dir', function (t) {
+  var opts = {
+    asar: {
+      unpackDir: 'should exist'
+    },
+    'asar-unpack-dir': 'should not exist'
+  }
+
+  var asarOpts = common.createAsarOpts(opts)
+  t.same(asarOpts, {unpack: undefined, unpackDir: 'should exist'})
+  t.end()
+})
+
 test('download argument test: download.cache overwrites cache', function (t) {
   var opts = {
     cache: 'should not exist',
@@ -564,9 +641,9 @@ test('CLI argument test: --download.strictSSL default', function (t) {
   t.end()
 })
 
-test('CLI argument test: --tmpdir=false', function (t) {
-  var args = common.parseCLIArgs(['--tmpdir=false'])
-  t.equal(args.tmpdir, false)
+test('CLI argument test: --asar=true', function (t) {
+  var args = common.parseCLIArgs(['--asar=true'])
+  t.equal(args.asar, true)
   t.end()
 })
 
@@ -576,6 +653,12 @@ test('CLI argument test: --osx-sign=true', function (t) {
   t.end()
 })
 
+test('CLI argument test: --tmpdir=false', function (t) {
+  var args = common.parseCLIArgs(['--tmpdir=false'])
+  t.equal(args.tmpdir, false)
+  t.end()
+})
+
 test('CLI argument test: --deref-symlinks=false', function (t) {
   var args = common.parseCLIArgs(['--deref-symlinks=false'])
   t.equal(args['deref-symlinks'], false)

usage.txt

@@ -25,11 +25,22 @@ appname            the name of the app, if it needs to be different from the "pr
 
 app-copyright      human-readable copyright line for the app
 app-version        release version to set for the app
-asar               packages the source code within your app into an archive
-asar-unpack        unpacks the files to app.asar.unpacked directory whose filenames regex .match
+asar               whether to package the source code within your app into an archive. You can either
+                   pass --asar by itself to use the default configuration, or use dot notation to
+                   configure a list of sub-properties, e.g. --asar.unpackDir=sub_dir
+
+                   Properties supported:
+                   - ordering: path to an ordering file for file packing
+                   - unpack: unpacks the files to the app.asar.unpacked directory whose filenames
+                     regex .match this string
+                   - unpackDir: unpacks the dir to the app.asar.unpacked directory whose names glob
+                     pattern or exactly match this string. It's relative to the <sourcedir>.
+asar-unpack        unpacks the files to the app.asar.unpacked directory whose filenames regex .match
                    this string
-asar-unpack-dir    unpacks the dir to app.asar.unpacked directory whose names glob pattern or
+                   (Deprecated, use asar.unpack instead)
+asar-unpack-dir    unpacks the dir to the app.asar.unpacked directory whose names glob pattern or
                    exactly match this string. It's relative to the <sourcedir>.
+                   (Deprecated, use asar.unpackDir instead)
 build-version      build version to set for the app
 cache              directory of cached Electron downloads. Defaults to `$HOME/.electron`
                    (Deprecated, use --download.cache instead)