Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

document the postflight mini-DSL #7938

Merged
merged 1 commit into from
Dec 9, 2014
+39 −2
Merged

document the postflight mini-DSL #7938

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 31 additions & 2 deletions doc/CASK_LANGUAGE_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Cask Domain-Specific Language (DSL) which are not needed in most cases.
* [Depends_on Stanza Details](#depends_on-stanza-details)
* [Conflicts_with Stanza Details](#conflicts_with-stanza-details)
* [Uninstall Stanza Details](#uninstall-stanza-details)
* [Postflight Stanza Details](#postflight-stanza-details)
* [Zap Stanza Details](#zap-stanza-details)
* [Arbitrary Ruby Methods](#arbitrary-ruby-methods)
* [Revisions to the Cask DSL](#revisions-to-the-cask-dsl)
Expand Down Expand Up @@ -59,7 +60,7 @@ time.
To make maintenance easier, the most-frequently-updated stanzas are usually
placed at the top. But that's a convention, not a rule.

Exception: `do` blocks such as `preflight` may enclose a block of pure Ruby
Exception: `do` blocks such as `postflight` may enclose a block of pure Ruby
code. Lines within that block follow a procedural (order-dependent)
paradigm.

Expand Down Expand Up @@ -111,7 +112,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install)
| `conflicts_with` | yes | a list of conflicts with this Cask (*not yet functional* see also [Conflicts_with Stanza Details](#conflicts_with-stanza-details))
| `caveats` | yes | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Stanza Details](#caveats-stanza-details))
| `preflight` | yes | a Ruby block containing preflight install operations (needed only in very rare cases)
| `postflight` | yes | a Ruby block containing postflight install operations
| `postflight` | yes | a Ruby block containing postflight install operations (see also [Postflight Stanza Details](#postflight-stanza-details))
| `uninstall_preflight` | yes | a Ruby block containing preflight uninstall operations (needed only in very rare cases)
| `uninstall_postflight` | yes | a Ruby block containing postflight uninstall operations
| `accessibility_access` | no | `true` if the application should be granted accessibility access
Expand Down Expand Up @@ -892,6 +893,34 @@ A fully manual method for finding bundle ids in a package file follows:
5. Once bundle ids have been identified, the unpacked package directory can be deleted.


## Postflight Stanza Details

### Evaluation of Blocks is Always Deferred

The Ruby blocks defined by `preflight`, `postflight`, `uninstall_preflight`,
and `uninstall_postflight` are not evaluated until install time or uninstall
time. Within a block, you may refer to the `@cask` instance variable, and
invoke any method available on `@cask`.

### Postflight Mini-DSL

There is a mini-DSL available within `postflight` blocks.

The following methods may be called to perform standard postflight tasks:

| method | description |
| ------------------------------- | ----------- |
| `plist_set(key, value)` | set a value in the `Info.plist` file for the app bundle. Example: [`rubymine.rb`](https://github.com/caskroom/homebrew-cask/blob/c5dbc58b7c1b6290b611677882b205d702b29190/Casks/rubymine.rb#L12)
| `suppress_move_to_applications` | suppress a dialog asking the user to move the app to the `/Applications` folder. Example: [`github.rb`](https://github.com/caskroom/homebrew-cask/blob/c5dbc58b7c1b6290b611677882b205d702b29190/Casks/github.rb#L13).

`plist_set` currently has the limitation that it only operates on the
bundle indicated by the first `app` stanza (and the Cask must contain
an `app` stanza).

`suppress_move_to_applications` optionally accepts a `:key` parameter for
apps which use a nonstandard `defaults` key. Example: [`alfred.rb`](https://github.com/caskroom/homebrew-cask/blob/c5dbc58b7c1b6290b611677882b205d702b29190/Casks/alfred.rb).


## Zap Stanza Details

### Zap Stanza Purpose
Expand Down
8 changes: 8 additions & 0 deletions doc/cask_language_deltas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ features which are available for the current Cask.
* [`gpg`](CASK_LANGUAGE_REFERENCE.md#gpg-stanza-details) *stub: not yet functional.*
* [`installer :script`](CASK_LANGUAGE_REFERENCE.md#installer-script)
* [`license`](CASK_LANGUAGE_REFERENCE.md#license-stanza-details)
* [`postflight plist_set`](CASK_LANGUAGE_REFERENCE.md#postflight-stanza-details)
* [`postflight suppress_move_to_applications`](CASK_LANGUAGE_REFERENCE.md#postflight-stanza-details)
* [`stage_only`](CASK_LANGUAGE_REFERENCE.md#at-least-one-artifact-stanza-is-also-required)
* replaced undocumented `caskroom_only`
* [`suite`](CASK_LANGUAGE_REFERENCE.md#suite-stanza-details)
Expand Down Expand Up @@ -151,6 +153,12 @@ For use in *eg* interpolation:
* [`zsh_path_helper(path)`](CASK_LANGUAGE_REFERENCE.md#caveats-mini-dsl)


## Postflight Mini-DSL (1.0)

* [`plist_set`](CASK_LANGUAGE_REFERENCE.md#postflight-stanza-details)
* [`suppress_move_to_applications`](CASK_LANGUAGE_REFERENCE.md#postflight-stanza-details)


## References

* [DSL 1.0 transition notice](https://github.com/caskroom/homebrew-cask/issues/5890)
Expand Down