dnrops
/
homebrew-cask
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #3137 from rolandwalker/doc_contributing_ref_followup 

doc: expand CASK_LANGUAGE_REFERENCE, shrink CONTRIBUTING
This commit is contained in:
Roland Walker 2014-02-25 06:06:54 -05:00
parent 516a9144d6 de7a8cdcc9
commit 619a82335e
4 changed files with 129 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
CONTRIBUTING.md
View File

@ -77,21 +77,21 @@ end
Fill in the following stanzas for your Cask: Fill in the following stanzas for your Cask:
| field | value | | name | value |
| ------------------ | ----------- | | ------------------ | ----------- |
| __cask metadata__ | information about the Cask (required) | __cask metadata__ | information about the Cask (required)
| `url` | URL to the `.dmg`/`.zip`/`.tgz` file that contains the application (see also [URL Stanza Details](doc/THE_CASK_LANGUAGE.md#url-stanza-details)) | `url` | URL to the `.dmg`/`.zip`/`.tgz` file that contains the application (see also [URL Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#url-stanza-details))
| `homepage` | application homepage; used for the `brew cask home` command | `homepage` | application homepage; used for the `brew cask home` command
| `version` | application version; give value of `'latest'` if versioned downloads are not offered | `version` | application version; give value of `'latest'` if versioned downloads are not offered
| `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be omitted on unversioned downloads with `no_checksum`. (see also [Checksum Stanza Details](doc/THE_CASK_LANGUAGE.md#checksum-stanza-details)) | `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be omitted on unversioned downloads by substituting `no_checksum`. (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) | __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/THE_CASK_LANGUAGE.md#link-stanza-details)) | `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/THE_CASK_LANGUAGE.md#install-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))
| `uninstall` | indicates what commands/scripts must be run to uninstall a pkg-based application (see also [Uninstall Stanza Details](doc/THE_CASK_LANGUAGE.md#uninstall-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: Additional stanzas you might need for special use-cases:
| field | value | | name | value |
| ------------------ | ----------- | | ------------------ | ----------- |
| `prefpane` | relative path to a preference pane that should be linked into the `~/Library/PreferencePanes` folder on installation | `prefpane` | relative path to a preference pane that should be linked into the `~/Library/PreferencePanes` folder on installation
| `colorpicker` | relative path to a ColorPicker plugin that should be linked into the `~/Library/ColorPickers` folder on installation | `colorpicker` | relative path to a ColorPicker plugin that should be linked into the `~/Library/ColorPickers` folder on installation
@ -103,10 +103,9 @@ Additional stanzas you might need for special use-cases:
| `input_method` | relative path to a input method that should be linked into the `~/Library/Input Methods` folder on installation | `input_method` | relative path to a input method that should be linked into the `~/Library/Input Methods` folder on installation
| `screen_saver` | relative path to a Screen Saver that should be linked into the `~/Library/Screen Savers` folder on installation | `screen_saver` | relative path to a Screen Saver that should be linked into the `~/Library/Screen Savers` folder on installation
| `nested_container` | relative path to an inner container that must be extracted before moving on with the installation; this allows us to support dmg inside tar, zip inside dmg, etc. | `nested_container` | relative path to an inner container that must be extracted before moving on with the installation; this allows us to support dmg inside tar, zip inside dmg, etc.
| `depends_on_formula` | a list of Homebrew Formulae upon which this Cask depends | `caveats` | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Details](doc/CASK_LANGUAGE_REFERENCE.md#caveats-details))
| `caveats` | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Details](doc/THE_CASK_LANGUAGE.md#caveats-details))
| `after_install` | a Ruby block containing postflight install operations Additional special-use stanzas are listed at [Optional Stanzas](doc/CASK_LANGUAGE_REFERENCE.md#optional-stanzas) and [Legacy Stanzas](doc/CASK_LANGUAGE_REFERENCE.md#legacy-stanzas).
| `after_uninstall` | a Ruby block containing postflight uninstall operations
### SourceForge URLs ### SourceForge URLs

28
FAQ.md
View File

@ -3,31 +3,9 @@
## What is a Cask? ## What is a Cask?
A `Cask` is like a `Formula` in Homebrew except it describes how to download A `Cask` is like a `Formula` in Homebrew except it describes how to download
and install a binary application. and install a binary application. To learn how to write a Cask, see
[CONTRIBUTING.md](CONTRIBUTING.md). For a complete reference, see
Casks currently have five required fields: [CASK_LANGUAGE_REFERENCE.md](doc/CASK_LANGUAGE_REFERENCE.md).
* __url__: (required) points to binary distribution of the application
* __homepage__: the same as Homebrew's - it doesn't do anything yet, but will be wired in
* __version__: (required) describes the version of the application available at the URL
* __sha256__: (required unless using no_checksum) SHA-256 checksum of the file
* __link__: (required for `.app`) indicates which file(s) should be linked into the Applications folder on installation
* __install__: (required for `.pkg`) indicates which package should be installed
* __prefpane__: (required for `.prefPane`) indicates which file(s) should be linked into the PreferencePanes folder on installation
* __qlplugin__: (required for `.qlgenerator`) indicates which file(s) should be linked into the QuickLook folder on installation
* __font__ : (required for fonts) indicates which file(s) should be linked into the Fonts folder on installation
* __input_method__: (required for input method) indicates which file(s) should be linked into the Input Methods folder on installation
* __screen_saver__: (required for `.saver`) indicates which file(s) should be linked into the Screen Saver folder on installation
and six optional fields:
* __binary__: relative path to a binary to be installed
* __uninstall__: (optional for `.pkg`) indicates how to uninstall a package
* __nested_container__: relative path to a nested inner container
* __depends_on_formula__: a list of Homebrew Formulae upon which this Cask depends
* __caveats__: a string or Ruby block providing the user with Cask-specific information at install time
* __after_install__: a Ruby block containing postflight install operations
* __after_uninstall__: a Ruby block containing postflight uninstall operations
## What's the status of this project? Where's it headed? ## What's the status of this project? Where's it headed?

2
README.md
View File

@ -33,7 +33,7 @@ open ~/Applications/"Google Chrome.app"
* Find basic documentation on using homebrew-cask in [USAGE.md](USAGE.md) * Find basic documentation on using homebrew-cask in [USAGE.md](USAGE.md)
* Want to contribute a Cask? Awesome! See [CONTRIBUTING.md](CONTRIBUTING.md) * Want to contribute a Cask? Awesome! See [CONTRIBUTING.md](CONTRIBUTING.md)
* Want to hack on our code? Also awesome! See [doc/HACKING.md](doc/HACKING.md) * Want to hack on our code? Also awesome! See [doc/HACKING.md](doc/HACKING.md)
* More project-related details and discussion are available in [FAQ.md](FAQ.md) * More project-related details and discussion are available in [FAQ.md](FAQ.md) and [doc/CASK_LANGUAGE_REFERENCE.md](doc/CASK_LANGUAGE_REFERENCE.md)
## Questions? Wanna chat? ## Questions? Wanna chat?

142
doc/THE_CASK_LANGUAGE.md → doc/CASK_LANGUAGE_REFERENCE.md
View File

@ -1,10 +1,14 @@
# The Cask DSL (Domain-Specific Language) # Cask Language Reference
This document acts as a complete reference, and covers aspects of the Cask This document acts as a complete reference, and covers aspects of the Cask
DSL which are not needed in most cases. Domain-Specific Language (DSL) which are not needed in most cases.
* [Stanzas Which May Occur Only Once](#stanzas-which-may-occur-only-once) * [Casks Are Ruby Classes](#casks-are-ruby-classes)
* [Stanzas Which May Occur Multiple Times](#stanzas-which-may-occur-multiple-times) * [The Cask Language Is Declarative](#the-cask-language-is-declarative)
* [Required Stanzas](#required-stanzas)
* [At Least One Artifact Stanza Is Also Required](#at-least-one-artifact-stanza-is-also-required)
* [Optional Stanzas](#optional-stanzas)
* [Legacy Stanzas](#legacy-stanzas)
* [Conditional Statements](#conditional-statements) * [Conditional Statements](#conditional-statements)
* [Caveats Stanza Details](#caveats-stanza-details) * [Caveats Stanza Details](#caveats-stanza-details)
* [Checksum Stanza Details](#checksum-stanza-details) * [Checksum Stanza Details](#checksum-stanza-details)
@ -14,30 +18,91 @@ DSL which are not needed in most cases.
* [Uninstall Stanza Details](#uninstall-stanza-details) * [Uninstall Stanza Details](#uninstall-stanza-details)
## Stanzas Which May Occur Only Once ## Casks Are Ruby Classes
* url Each Cask is a Ruby class, derived from class `Cask`. The Cask definition
* homepage is always enclosed in a `class ... end` block. Example:
* version
* sha256 (or no_checksum) ```ruby
class Alfred < Cask
url 'http://cachefly.alfredapp.com/Alfred_2.1.1_227.zip'
homepage 'http://www.alfredapp.com/'
version '2.1.1_227'
sha256 'd19fe7441c6741bf663521e561b842f35707b1e83de21ca195aa033cade66d1b'
link 'Alfred 2.app'
link 'Alfred 2.app/Contents/Preferences/Alfred Preferences.app'
end
```
## Stanzas Which May Occur Multiple Times ## The Cask Language Is Declarative
* link Each Cask contains a series of stanzas (or "fields") which *declare* how the
* install software is to be obtained and installed. In a declarative language, the
* prefpane author does not need to worry about order. As long as all the needed fields
* qlplugin are present, homebrew-cask will figure out what needs to be done.
* font
* input_method Exception: `do` blocks such as `after_install` may enclose a block of
* screen_saver pure Ruby code. Lines within that block follow a procedural (order-dependent)
* binary paradigm.
* uninstall
* nested_container
* depends_on_formula ## Required Stanzas
* caveats
* after_install Each of the following stanzas is required for every Cask.
* after_uninstall
Exception: currently `sha256` may be omitted if `no_checksum` is substituted.
| name | multiple occurrences allowed? | value |
| ------------------ |------------------------------ | ----------- |
| `url` | No | URL to the `.dmg`/`.zip`/`.tgz` file that contains the application (see also [URL Stanza Details](#url-stanza-details))
| `homepage` | No | application homepage; used for the `brew cask home` command
| `version` | No | application version; give value of `'latest'` if versioned downloads are not offered
| `sha256` | No | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be omitted on unversioned downloads by substituting `no_checksum`. (see also [Checksum Stanza Details](#checksum-stanza-details))
## At Least One Artifact Stanza Is Also Required
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))
| `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
| `input_method` | yes | relative path to a input method that should be linked into the `~/Library/Input Methods` folder on installation
| `prefpane` | yes | relative path to a preference pane that should be linked into the `~/Library/PreferencePanes` folder on installation
| `qlplugin` | yes | relative path to a QuickLook plugin that should be linked into the `~/Library/QuickLook` folder on installation
| `screen_saver` | yes | relative path to a Screen Saver that should be linked into the `~/Library/Screen Savers` folder on installation
| `service` | yes | relative path to a service that should be linked into the `~/Library/Services` folder on installation
| `widget` | yes | relative path to a widget that should be linked into the `~/Library/Widgets` folder on installation (ALPHA: DOES NOT WORK YET)
## Optional Stanzas
| name | multiple occurrences allowed? | value |
| -------------------- |------------------------------ | ----------- |
| `uninstall` | yes | indicates what commands/scripts must be run to uninstall a pkg-based application (see also [Uninstall Stanza Details](#uninstall-stanza-details))
| `nested_container` | yes | relative path to an inner container that must be extracted before moving on with the installation; this allows us to support dmg inside tar, zip inside dmg, etc.
| `depends_on_formula` | yes | a list of Homebrew Formulae upon which this Cask depends
| `caveats` | yes | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Details](#caveats-details))
| `after_install` | yes | a Ruby block containing postflight install operations
| `after_uninstall` | yes | a Ruby block containing postflight uninstall operations
| `before_install` | yes | a Ruby block containing preflight install operations (needed only in very rare cases)
| `before_uninstall` | yes | a Ruby block containing preflight uninstall operations (needed only in very rare cases)
## Legacy Stanzas
The following stanzas may be seen in current use but are deprecated
and slated for retirement.
| name | multiple occurrences allowed? | meaning |
| ------------------ |------------------------------ | ----------- |
| `md5` | No | an alternative to `sha256`
| `sha1` | No | an alternative to `sha256`
## Conditional Statements ## Conditional Statements
@ -45,8 +110,9 @@ DSL which are not needed in most cases.
Conditional statements are permitted, but only if they are very efficient. Conditional statements are permitted, but only if they are very efficient.
Tests on the following values are known to be acceptable: Tests on the following values are known to be acceptable:
* `MacOS.version` (example: `macports.rb`) * `MacOS.version` (example: see [macports.rb](../Casks/macports.rb))
* `Hardware::CPU.is_64_bit?`
* `Hardware::CPU.is_32_bit?`
## Caveats Stanza Details ## Caveats Stanza Details
@ -121,7 +187,8 @@ of key/value pairs appended to `url`:
| `:referer` | a string holding the URL to set as referrer in the download request | `:referer` | a string holding the URL to set as referrer in the download request
| `:user_agent` | a string holding the user agent to set for the download request. Can also be set to the symbol `:fake`, which will use a generic Browser-like user agent string. we prefer `:fake` when the server does not require a specific user agent. | `:user_agent` | a string holding the user agent to set for the download request. Can also be set to the symbol `:fake`, which will use a generic Browser-like user agent string. we prefer `:fake` when the server does not require a specific user agent.
Example: `java.rb` Example: [java.rb](../Casks/java.rb)
### Subversion URLs ### Subversion URLs
@ -167,6 +234,19 @@ directory by adding a `:target` key to `link`, like this:
link 'Alfred 2.app', :target => 'Jeeves.app' link 'Alfred 2.app', :target => 'Jeeves.app'
``` ```
### :target May Contain an Absolute Path
If `:target` has a leading slash, it is interpreted as an absolute path.
The containing directory for the absolute path will be created if it does
not already exist. Example (from [oclint.rb](../Casks/oclint.rb)).
```ruby
binary 'oclint-0.7-x86_64-apple-darwin-10/lib/oclint', :target => '/usr/local/lib/oclint'
```
### :target Works on Most Artifact Types
The `:target` key works similarly for other Cask artifacts, such as The `:target` key works similarly for other Cask artifacts, such as
`binary`, `colorpicker`, `font`, `input_method`, `prefpane`, `qlplugin`, `binary`, `colorpicker`, `font`, `input_method`, `prefpane`, `qlplugin`,
`service`, and `widget`. `service`, and `widget`.
@ -195,9 +275,17 @@ install 'Soundflower.pkg', :allow_untrusted => true
## Uninstall Stanza Details ## Uninstall Stanza Details
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 `pkg`-based Cask using `install` will **not** know how to uninstall
correctly unless an `uninstall` stanza is given. 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
corresponding `uninstall`.
Since `pkg` installers can do arbitrary things, different techniques are Since `pkg` installers can do arbitrary things, different techniques are
needed to uninstall in each case. You may need to specify one, or several, needed to uninstall in each case. You may need to specify one, or several,
of the following key/value pairs as arguments to `uninstall`. `:pkgutil` of the following key/value pairs as arguments to `uninstall`. `:pkgutil`