From ab4f52a781fdb0a28dcd017b40e1d021a7159d4e Mon Sep 17 00:00:00 2001 From: Roland Walker Date: Wed, 10 Sep 2014 10:54:06 -0400 Subject: [PATCH] docs and error messages for new DSL stanza `pkg` transition from `install` to `pkg` --- CONTRIBUTING.md | 4 ++-- doc/CASK_LANGUAGE_REFERENCE.md | 25 +++++++++++++------------ doc/cask_language_deltas.md | 1 + lib/cask/artifact/pkg.rb | 2 +- 4 files changed, 17 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c84fa58d1dc9..58232f5f52dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,7 +55,7 @@ class Vagrant < Cask url 'https://dl.bintray.com/mitchellh/vagrant/Vagrant-1.4.3.dmg' homepage 'http://www.vagrantup.com' - install 'Vagrant.pkg' + pkg 'Vagrant.pkg' uninstall :script => { :executable => 'uninstall.tool', :input => %w[Yes] } end ``` @@ -123,7 +123,7 @@ Fill in the following stanzas for your Cask: | `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed for unversioned downloads by using the special value `:no_check`. (see also [Checksum Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#checksum-stanza-details)) | __artifact info__ | information about artifacts inside the Cask (can be specified multiple times) | `link` | relative path to a file that should be linked into the `Applications` folder on installation (see also [Link Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#link-stanza-details)) -| `install` | relative path to `pkg` that should be run to install the application (see also [Install Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#install-stanza-details)) +| `pkg` | relative path to a `.pkg` file containing the distribution (see also [Pkg Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#pkg-stanza-details)) | `uninstall` | indicates what commands/scripts must be run to uninstall a pkg-based application (see also [Uninstall Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#uninstall-stanza-details)) Additional stanzas you might need for special use-cases: diff --git a/doc/CASK_LANGUAGE_REFERENCE.md b/doc/CASK_LANGUAGE_REFERENCE.md index e66e5c4d7d9d..9c8467fc8b0e 100644 --- a/doc/CASK_LANGUAGE_REFERENCE.md +++ b/doc/CASK_LANGUAGE_REFERENCE.md @@ -14,7 +14,7 @@ Cask Domain-Specific Language (DSL) which are not needed in most cases. * [Checksum Stanza Details](#checksum-stanza-details) * [URL Stanza Details](#url-stanza-details) * [Link Stanza Details](#link-stanza-details) - * [Install Stanza Details](#install-stanza-details) + * [Pkg Stanza Details](#pkg-stanza-details) * [Uninstall Stanza Details](#uninstall-stanza-details) * [Arbitrary Ruby Methods](#arbitrary-ruby-methods) * [Revisions to the Cask DSL](#revisions-to-the-cask-dsl) @@ -74,7 +74,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install) | name | multiple occurrences allowed? | value | | ------------------ |------------------------------ | ----------- | | `link` | yes | relative path to a file that should be linked into the `Applications` folder on installation (see also [Link Stanza Details](#link-stanza-details)) -| `install` | yes | relative path to `pkg` that should be run to install the application (see also [Install Stanza Details](#install-stanza-details)) +| `pkg` | yes | relative path to a `.pkg` file containing the distribution (see also [Pkg Stanza Details](#pkg-stanza-details)) | `binary` | yes | relative path to a binary that should be linked into the `/usr/local/bin` folder on installation | `colorpicker` | yes | relative path to a ColorPicker plugin that should be linked into the `~/Library/ColorPickers` folder on installation | `font` | yes | relative path to a font that should be linked into the `~/Library/Fonts` folder on installation @@ -113,6 +113,7 @@ The following stanzas are no longer in use. | `after_install` | yes | an obsolete alternative to `postflight` | `before_uninstall` | yes | an obsolete alternative to `uninstall_preflight` | `after_uninstall` | yes | an obsolete alternative to `uninstall_postflight` +| `install` | yes | an obsolete alternative to `pkg` ## Conditional Statements @@ -334,24 +335,24 @@ The `:target` key works similarly for other Cask artifacts, such as `service`, and `widget`. -## Install Stanza Details +## Pkg Stanza Details -The first argument to `install` should be a relative path to the `pkg` file -to be installed. For example: +The first argument to the `pkg` stanza should be a relative path to the `.pkg` +file to be installed. For example: ```ruby -install 'Vagrant.pkg' +pkg 'Vagrant.pkg' ``` -Subsequent arguments to `install` are key/value pairs which modify the -install process. Currently supported keys are +Subsequent arguments to `pkg` are key/value pairs which modify the install +process. Currently supported keys are * `:allow_untrusted` -- pass `-allowUntrusted` to `/usr/sbin/installer` Example: ```ruby -install 'Soundflower.pkg', :allow_untrusted => true +pkg 'Soundflower.pkg', :allow_untrusted => true ``` @@ -361,11 +362,11 @@ IF YOU CANNOT DESIGN A WORKING `UNINSTALL` STANZA, PLEASE SUBMIT YOUR CASK ANYWAY. The maintainers will help you write an `uninstall` stanza: just ask! -A `pkg`-based Cask using `install` will **not** know how to uninstall +A Cask which uses the `pkg` stanza will **not** know how to uninstall correctly unless an `uninstall` stanza is given. So, while the `uninstall` stanza is technically optional in the Cask -language, it is much better for end-users if every `install` has a +language, it is much better for end-users if every `pkg` has a corresponding `uninstall`. Since `pkg` installers can do arbitrary things, different techniques are @@ -416,7 +417,7 @@ use the command $ ./developer/bin/list_pkg_ids_by_regexp ``` -### List Files Associated With a `pkg` +### List Files Associated With a `pkg` Id Once you know the ID for an installed package, (above), you can list all files on your system associated with that package ID using the diff --git a/doc/cask_language_deltas.md b/doc/cask_language_deltas.md index 82d9ab6edcec..2b1a243cf458 100644 --- a/doc/cask_language_deltas.md +++ b/doc/cask_language_deltas.md @@ -42,6 +42,7 @@ This notice will be removed for the final form.** | `after_install` | `postflight` | `before_uninstall` | `uninstall_preflight` | `after_uninstall` | `uninstall_postflight` +| `install` | `pkg` ## All Supported Stanzas (1.0) diff --git a/lib/cask/artifact/pkg.rb b/lib/cask/artifact/pkg.rb index e85be406a5d8..dadc8294a96c 100644 --- a/lib/cask/artifact/pkg.rb +++ b/lib/cask/artifact/pkg.rb @@ -14,7 +14,7 @@ def load_pkg_description(pkg_description) end raise if pkg_description.nil? rescue - raise CaskInvalidError.new(@cask, 'Bad install stanza') + raise CaskInvalidError.new(@cask, 'Bad pkg stanza') end end