diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32bd97c90..847fb02d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,15 @@ # How To Contribute So you want to contribute to the project. **THIS IS GREAT NEWS!** Seriously. We're -all pretty happy about this. +all pretty happy about this. Here's how to get started: + + * [Getting Set Up To Contribute](#getting-set-up-to-contribute) + * [Adding a Cask](#adding-a-cask) + * [Testing Your New Cask](#testing-your-new-cask) + * [Finding a Home For Your Cask](#finding-a-home-for-your-cask) + * [Submitting Your Changes](#submitting-your-changes) + * [Cleaning up](#cleaning-up) + ## Getting Set Up To Contribute @@ -9,11 +17,12 @@ all pretty happy about this. 2. Add your GitHub fork as a remote for your homebrew-cask Tap ```bash -github_user='' -cd "$(brew --prefix)"/Library/Taps/phinze-cask -git remote add $github_user https://github.com/$github_user/homebrew-cask +$ github_user='' +$ cd "$(brew --prefix)"/Library/Taps/phinze-cask +$ git remote add "$github_user" "https://github.com/$github_user/homebrew-cask" ``` + ## Adding a Cask Making a Cask is easy: a Cask is a small Ruby file. @@ -30,7 +39,6 @@ class Alfred < Cask link 'Alfred 2.app' link 'Alfred 2.app/Contents/Preferences/Alfred Preferences.app' end - ``` Here is another Cask for `Vagrant.pkg`: @@ -44,13 +52,12 @@ class Vagrant < Cask install 'Vagrant.pkg' uninstall :script => { :executable => 'uninstall.tool', :input => %w[Yes] } end - ``` To get started, use the handy dandy `brew cask create` command. ```bash -brew cask create my-new-cask +$ brew cask create my-new-cask ``` This will open `$EDITOR` with a template for your new Cask. Note that the @@ -68,27 +75,23 @@ class MyNewCask < Cask end ``` -If you are submitting a non-stable version of an application that already has a -cask (e.g. beta or nightly), then the Cask should be submitted to the -[caskroom/versions](https://github.com/caskroom/homebrew-versions) repo. +Fill in the following stanzas for your Cask: -Fill in the following fields for your Cask: - -| field | description | +| field | value | | ------------------ | ----------- | | __cask metadata__ | information about the Cask (required) -| `url` | URL to the `.dmg`/`.zip`/`.tgz` file that contains the application (see __URL Details__ for more information) +| `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)) | `homepage` | application homepage; used for the `brew cask home` command -| `version` | application version; determines the directory structure in the Caskroom -| `sha256` | SHA-256 checksum of the file; checked when the file is downloaded to prevent any funny business (can be omitted with `no_checksum`) +| `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 `. Can be omitted on unversioned downloads with `no_checksum`. (see also [Checksum Stanza Details](doc/THE_CASK_LANGUAGE.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 __Link Details__ for more information) -| `install` | relative path to `pkg` that should be run to install the application (see __Install Details__ for more information) -| `uninstall` | indicates what commands/scripts must be run to uninstall a pkg-based application (see __Uninstall Details__ for more information) +| `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)) +| `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)) +| `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)) -Additional fields you might need for special use-cases: +Additional stanzas you might need for special use-cases: -| field | description | +| field | value | | ------------------ | ----------- | | `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 @@ -96,31 +99,20 @@ Additional fields you might need for special use-cases: | `font` | relative path to a font that should be linked into the `~/Library/Fonts` folder on installation | `widget` | relative path to a widget that should be linked into the `~/Library/Widgets` folder on installation (ALPHA: DOES NOT WORK YET) | `service` | relative path to a service that should be linked into the `~/Library/Services` folder on installation -| `binary` | relative path to a binary that should be linked into the `~/usr/local/bin` folder on installation +| `binary` | relative path to a binary that should be linked into the `/usr/local/bin` 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 | `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 __Caveats Details__ for more information) +| `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 | `after_uninstall` | a Ruby block containing postflight uninstall operations -### URL Details +### SourceForge URLs -#### HTTP URLs - -In most cases, a plain URL string is all you need to specify for a Cask. Sometimes, additional information is required for the `curl`-based downloader to successfully fetch the file. There are a few options to help in these cases, which can be given as key/value pairs appended to `url`: - -| key | value | -| ------------------ | ----------- | -| `:cookies` | a hash of cookies to be set 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. - -#### SourceForge URLs - -SourceForge projects are a common way to distribute binaries, but they provide many different styles of URLs to get to the goods. +SourceForge projects are a common way to distribute binaries, but they +provide many different styles of URLs to get to the goods. We prefer URLs of this format: @@ -130,26 +122,16 @@ http://sourceforge.net/projects/$PROJECTNAME/files/latest/download This lets the project maintainers choose the best URL for download. -If the "latest" URL does not point to a valid file for a Mac app, then we fall back this format: +If the "latest" URL does not point to a valid file for a Mac app, then we +fall back to this format: ``` http://downloads.sourceforge.net/sourceforge/$PROJECTNAME/$FILENAME.$EXT ``` -#### Subversion URLs - -In rare cases, a distribution may not be available over ordinary HTTP. Subversion URLs are also supported, and can be specified by appending the following key/value pairs to `url`: - -| key | value | -| ------------------ | ----------- | -| `:using` | the symbol `:svn` is the only legal value -| `:revision` | a string identifying the subversion revision to download -| `:trust_cert` | set to `true` to automatically trust the certificate presented by the server (avoiding an interactive prompt) - - ### Naming Casks -We try to maintain a consistent naming policy so everything stays clean and predictable. +We try to maintain consistent naming so everything stays clean and predictable. #### Find the Canonical Name of the Author's Distribution @@ -171,8 +153,8 @@ We try to maintain a consistent naming policy so everything stays clean and pred #### Cask Name -A "Cask name" is the primary identifier for a package in our project. It's the string -people will use to interact with this Cask on their system. +A "Cask name" is the primary identifier for a package in our project. It's +the string people will use to interact with this Cask on their system. To get from the App's canonical name to the Cask name: @@ -186,7 +168,8 @@ Casks are stored in a Ruby file matching their name. #### Cask Class -Casks are implemented as Ruby classes, so a Cask's "class" needs to be a valid Ruby class name. +Casks are implemented as Ruby classes, so a Cask's "class" needs to be a +valid Ruby class name. When going from a Cask's __name__ to its __class name__: @@ -197,7 +180,7 @@ When going from a Cask's __name__ to its __class name__: #### Cask Naming Examples -These illustrate most of the naming rules in our policy. +These illustrate most of the naming rules: Canonical App Name | Cask Name | Cask Class -------------------|---------------------|------------------------ @@ -207,279 +190,29 @@ BetterTouchTool | `bettertouchtool` | `Bettertouchtool` iTerm2 | `iterm2` | `Iterm2` Akai LPK25 Editor | `akai-lpk25-editor` | `AkaiLpk25Editor` Sublime Text 3 | `sublime-text3` | `SublimeText3` -1Password | `1password` | `Onepassword` (see __NAMING NOTE__) +1Password | `1password` | `Onepassword` +### Archives With Subfolders -#### NAMING NOTE - -When a Cask's _name_ does not map to a valid Ruby class (for example, when it starts with a number) there's an incoming feature to allow Cask _classes_ to indicate the proper name using a keyword. - -This feature is not yet complete, so you'll see some __Cask name__s that don't fully conform to the rules. For example, currently the Cask for 1Password is called `onepassword` instead of `1password`. - -When all this is sorted out, this message will go away. - - -### Font Casks - -Fonts are maintained separately. Please see [CONTRIBUTING.md](https://github.com/caskroom/homebrew-fonts/blob/master/CONTRIBUTING.md) in the [homebrew-fonts](https://github.com/caskroom/homebrew-fonts) repository. - -### Link Details - -In the simple case of a single string argument to `link`, a symlink is -created in the target `~/Applications` directory using the same name as -the source file. For example: - -```ruby -link 'Alfred 2.app' -``` - -causes the creation of this symlink - -```bash -~/Applications/Alfred 2.app -``` - -which points to a source file such as - -```bash -/opt/homebrew-cask/Caskroom/alfred/2.1.1_227/Alfred 2.app -``` - -#### Renaming the Target - -You can rename the target link which appears in your -`~/Applications` directory by adding a `:target` key to `link`, -like this: - -```ruby -link 'Alfred 2.app', :target => 'Jeeves.app' -``` - -The `:target` key works in a similar way for these Cask fields as well: `binary`, -`colorpicker`, `font`, `input_method`, `prefpane`, `qlplugin`, `service`, and -`widget`. - -#### Subfolders in .zip and .dmg - -When the application is in a subfolder within a downloaded .zip or .dmg, that folder's name must be included in the `link` field in order for the app to be installed. So, if the downloaded zip unzips to a folder 'TexmakerMacosxLion' containing texmaker.app, the link must be specified as: - -```ruby -link 'TexmakerMacosxLion/texmaker.app' -``` - -Linking to the .app file without reference to the containing folder will result in installation failing with a "symlink source is not there" error. - -### Install Details - -The first argument to `install` should be a relative path to the `pkg` file -to be installed. For example: - -```ruby -install 'Vagrant.pkg' -``` - -Subsequent arguments to `install` are key/value pairs which modify the -install process. Currently supported keys are - - * `:allow_untrusted` -- pass `-allowUntrusted` to `/usr/sbin/installer` +When a downloaded archive expands to a subfolder, the subfolder name must be +included in the `link` value. Example: -```ruby -install 'Soundflower.pkg', :allow_untrusted => true -``` + * Texmaker is downloaded to the file `TexmakerMacosxLion.zip`. + * `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion`. + * The folder `TexmakerMacosxLion` contains the application `texmaker.app`. + * So, the `link` stanza should include the subfolder as a relative path: -### Uninstall Details + ```ruby + link 'TexmakerMacosxLion/texmaker.app' + ``` -A `pkg`-based Cask using `install` will **not** know how to uninstall -correctly unless an `uninstall` stanza is given. +### Indenting -Since `pkg` installers can do arbitrary things, different techniques are -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` -is the most useful. +All Casks and code in the homebrew-cask project should be indented using two +spaces (never tabs). -* `:early_script` (string or hash) - like `:script`, but runs early (for special cases, best avoided) -* `:launchctl` (string or array) - ids of `launchctl` jobs to remove -* `:quit` (string or array) - bundle ids of running applications to quit -* `:kext` (string or array) - bundle ids of kexts to unload from the system -* `:pkgutil` (string or regexp) - regexp matching bundle ids of packages to uninstall using `pkgutil` -* `:script` (string or hash) - relative path to an uninstall script to be run via sudo; use hash if args are needed - - `:executable` - relative path to an uninstall script to be run via sudo (required for hash form) - - `:args` - array of arguments to the uninstall script - - `:input` - array of lines of input to be sent to `stdin` of the script - - `:must_succeed` - set to `false` if the script is allowed to fail -* `:files` (array) - absolute paths of files or directories to remove. `:files` should only be used as a last resort. `:pkgutil` is strongly preferred - -Each `uninstall` technique is applied according to the order above. The order -in which `uninstall` keys appear in the Cask file is ignored. - -For assistance filling in the right values for `uninstall` keys, there are -several helper scripts found under `developer/bin` in the homebrew-cask -repository. Each of these scripts responds to the `-help` option with -additional documentation. - -The easiest way to work out an `uninstall` stanza is on a system where the -`pkg` is currently installed and operational. To operate on an uninstalled -`pkg` file, see __Working With a pkg File Manually__, below. - -#### Uninstall Key :pkgutil - -This is the most important and useful uninstall key. `:pkgutil` is -often sufficient to completely uninstall a `pkg`. - -IDs for the most recently-installed packages can be listed using the -command -```bash -$ ./developer/bin/list_recent_pkg_ids -``` - -#### List Files Associated With a `pkg` - -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 -OS X command -```bash -$ pkgutil --files -``` -Listing the associated files can help you assess whether the package -included any launchctl jobs or kernel extensions (kexts). - -#### Uninstall Key :launchctl - -IDs for currently loaded launchctl jobs can be listed using the command -```bash -$ ./developer/bin/list_loaded_launchjob_ids -``` - -IDs for all installed launchctl jobs can be listed using the command -```bash -$ ./developer/bin/list_installed_launchjob_ids -``` - -#### Uninstall Key :quit - -Bundle IDs for currently running Applications can be listed using the command -```bash -$ ./developer/bin/list_running_app_ids -``` - -Bundle IDs inside an Application bundle on disk can be listed using the command -```bash -$ ./developer/bin/list_ids_in_app -``` - -#### Uninstall Key :kext - -IDs for currently loaded kernel extensions can be listed using the command -```bash -$ ./developer/bin/list_loaded_kext_ids -``` - -IDs inside a kext bundle you have located on disk can be listed using the command -```bash -$ ./developer/bin/list_id_in_kext -``` - -#### Working With a pkg File Manually - -Advanced users may wish to work with a `pkg` file manually, without having the -package installed. - -A list of files which may be installed from a `pkg` can be extracted using the -command -```bash -$ ./developer/bin/list_payload_in_pkg -``` - -Candidate application names helpful for determining the name of a Cask may be -extracted from a `pkg` file using the command -```bash -$ ./developer/bin/list_apps_in_pkg -``` - -Candidate package IDs which may be useful in a `:pkgutil` key may be -extracted from a `pkg` file using the command -```bash -$ ./developer/bin/list_ids_in_pkg -``` - -A fully manual method for finding bundle ids in a package file follows: - - 1. Unpack `/path/to/my.pkg` (replace with your package name) with `pkgutil --expand /path/to/my.pkg /tmp/expanded.unpkg`. - 2. The unpacked package is a folder. Bundle ids are contained within files named `PackageInfo`. These files can be found - with the command `find /tmp/expanded.unpkg -name PackageInfo`. - 3. `PackageInfo` files are XML files, and bundle ids are found within the `identifier` attributes of `` tags that look like - ``, where extraneous attributes have been snipped out and replaced with ellipses. - 4. Kexts inside packages are also described in `PackageInfo` files. If any kernel extensions are present, the command - `find /tmp/expanded.unpkg -name PackageInfo -print0 | xargs -0 grep -i kext` should return a `` tag with a `path` - attribute that contains a `.kext` extension, for example ``. - 5. Once bundle ids have been identified, the unpacked package directory can be deleted. - -### Caveats Details - -#### Caveats as a String - -When `caveats` is a string, it is evaluated at compile time. Use this only for a static -message in which you don't need to interpolate any runtime variables. Example: - - caveats 'Using this software is hazardous to your health.' - -#### Caveats as a Block - -When `caveats` is a Ruby block, evaluation is deferred until install time. Here you may -refer to the Cask instance in your message to the user: - -```ruby -caveats do - puts "Using #{@cask} is hazardous to your health." -end -``` - -#### Caveats Mini-DSL - -There is a mini-DSL available within `caveats` blocks. - -The following methods may be called to generate standard warning messages: - -| method | description | -| --------------------------------- | ----------- | -| `manual_installer(path)` | The user should execute an installer to complete the installation. `path` may be absolute, or relative to the Cask. -| `path_environment_variable(path)` | The user should make sure `path` is in their `$PATH` environment variable -| `logout` | The user should log out and log back in to complete installation -| `reboot` | The user should reboot to complete installation -| `files_in_usr_local` | The Cask installs files to `/usr/local`, which may confuse Homebrew -| `arch_only(list)` | The Cask only supports certain architectures. Currently valid elements of `list` are `intel-32` and `intel-64` -| `os_version_only(list)` | The Cask only supports certain OS X Versions. Currently valid elements of `list` are `10.5`, `10.6`, `10.7`, `10.8`, and `10.9` - -Example: - -```ruby -caveats do - manual_installer 'Little Snitch Installer.app' -end -``` - -And the following methods may be useful for interpolation: - -| method | description | -| ------------------ | ----------- | -| `title` | the Cask title -| `caskroom_path` | eg `/opt/homebrew-cask/Caskroom` -| `destination_path` | where this particular Cask is stored, including version number, eg `/opt/homebrew-cask/Caskroom/google-chrome/stable-channel` - -### Good Things To Know - -* In order to get the SHA-256 checksum for the file, the easiest way is to run - `shasum -a 256 `. - * Although new casks/cask updates should use SHA-256, old casks may still - use SHA-1 checksums instead of SHA-256 checksums: they have a - `sha1` field instead of a `sha256` field (calculated using `shasum `). -* If the application does not have versioned downloads, you can skip the - checksum by specifying `no_checksum`, which takes no arguments. -* We have some conventions for projects without version-specific URLs. `latest` - is a common version for those, but you can grep through the existing Casks for - other examples. ## Testing Your New Cask @@ -497,28 +230,48 @@ If your application and homebrew-cask do not work well together, feel free to [file an issue](https://github.com/phinze/homebrew-cask/issues) after checking out open issues. -## Indenting - -All Casks and code in the homebrew-cask project should be indented using two -spaces (never tabs). ## Finding a Home For Your Cask -The organization `caskroom` maintains other repositories that are to be used for certain types of Casks. Here's a quick checklist of them so that you can find the right one to house your Cask: +We maintain separate Taps for different types of binaries. -1. Does your Cask install an unstable, development, or legacy version of a Cask? Please place it in [caskroom/homebrew-versions](http://github.com/caskroom/homebrew-versions). Only the latest stable version (regardless of OS compatibility) should belong here, **unless no stable versions for the app exist yet, in which case beta or development versions are welcomed.** -2. Does your Cask install a font that is readily available as an installable font file (e.g. TTF, OTF…)? Please place it in [caskroom/homebrew-fonts](http://github.com/caskroom/homebrew-fonts). Also, be careful with licensing on font files before submission. -3. Does your Cask install an app that has no official app bundle download (in other words, any DMG/ZIP/TGZ/etc. downloads available are not those officially endorsed by the developer)? Please place it in [caskroom/homebrew-unofficial](http://github.com/caskroom/homebrew-unofficial). +### Latest Stable Versions + +Latest stable versions live in the main repository at [phinze/homebrew-cask](https://github.com/phinze/homebrew-cask). +Software in the main repo should run on the latest release of OS X or the previous +point release (currently: Mavericks and Mountain Lion). + +### But There Is No Stable Version! + +When an App is only available as a Beta, or in cases where a "Beta" has become +the general standard, then an "unstable" version can go into the main repo. + +### Unstable, Development, or Legacy Versions + +When an App already exists in the main repo, alternate versions can be Casked +and submitted to [caskroom/homebrew-versions](https://github.com/caskroom/homebrew-versions). +Nightly builds always go in [caskroom/homebrew-versions](https://github.com/caskroom/homebrew-versions). + +### Unofficial Builds + +When an App developer does not offer a binary download, please submit the +Cask to [caskroom/homebrew-unofficial](http://github.com/caskroom/homebrew-unofficial). +For a location to host unofficial builds, contact our sister project [alehouse](https://github.com/alehouse). + +### Fonts + +Font Casks live in the [caskroom/homebrew-fonts](https://github.com/caskroom/homebrew-fonts) +repository. See the font repo [CONTRIBUTING.md](https://github.com/caskroom/homebrew-fonts/blob/master/CONTRIBUTING.md) +for details. -If your Cask makes it past these three points, it is likely that your submission will be accepted. Please remember that there are always exceptions to these guidelines, so don't be afraid to ask where something goes if it falls into a gray area. ## Submitting Your Changes Hop into your Tap and check to make sure your new Cask is there: ```bash -cd "$(brew --prefix)"/Library/Taps/phinze-cask -git status +$ cd "$(brew --prefix)"/Library/Taps/phinze-cask +$ git status # On branch master # Untracked files: # (use "git add ..." to include in what will be committed) @@ -530,7 +283,7 @@ So far, so good. Now make a feature branch that you'll use in your pull request: ```bash -git checkout -b my-new-cask +$ git checkout -b my-new-cask Switched to a new branch 'my-new-cask' ``` @@ -575,8 +328,8 @@ Examples of difficult, unclear commit summaries: Push your changes to your GitHub account: ```bash -github_user='' -git push $github_user my-new-cask +$ github_user='' +$ git push "$github_user" my-new-cask ``` ### Filing a Pull Request on GitHub @@ -597,10 +350,11 @@ code, it is better to [squash](http://davidwalsh.name/squash-commits-git) those But you don't always have to squash -- it is fine for a pull request to contain multiple commits when there is a logical reason for the separation. + ## Cleaning up -After your Pull Request is away, you might want to get yourself back on master, -so that `brew update` will pull down new Casks properly. +After your Pull Request is away, you might want to get yourself back onto +`master`, so that `brew update` will pull down new Casks properly. ```bash cd "$(brew --prefix)"/Library/Taps/phinze-cask @@ -609,9 +363,10 @@ git checkout master Neat and tidy! + ## Working On homebrew-cask Itself If you'd like to hack on the Ruby code in the project itself, please -see [doc/HACKING.md](doc/HACKING.md). +see [HACKING.md](doc/HACKING.md). # <3 THANK YOU! <3 diff --git a/doc/THE_CASK_LANGUAGE.md b/doc/THE_CASK_LANGUAGE.md new file mode 100644 index 000000000..766f79be5 --- /dev/null +++ b/doc/THE_CASK_LANGUAGE.md @@ -0,0 +1,323 @@ +# The Cask DSL (Domain-Specific Language) + +This document acts as a complete reference, and covers aspects of the Cask +DSL which are not needed in most cases. + + * [Stanzas Which May Occur Only Once](#stanzas-which-may-occur-only-once) + * [Stanzas Which May Occur Multiple Times](#stanzas-which-may-occur-multiple-times) + * [Conditional Statements](#conditional-statements) + * [Caveats Stanza Details](#caveats-stanza-details) + * [Checksum Stanza Details](#checksum-stanza-details) + * [URL Stanza Details](#url-stanza-details) + * [Link Stanza Details](#link-stanza-details) + * [Install Stanza Details](#install-stanza-details) + * [Uninstall Stanza Details](#uninstall-stanza-details) + + +## Stanzas Which May Occur Only Once + + * url + * homepage + * version + * sha256 (or no_checksum) + + +## Stanzas Which May Occur Multiple Times + + * link + * install + * prefpane + * qlplugin + * font + * input_method + * screen_saver + * binary + * uninstall + * nested_container + * depends_on_formula + * caveats + * after_install + * after_uninstall + + +## Conditional Statements + +Conditional statements are permitted, but only if they are very efficient. +Tests on the following values are known to be acceptable: + + * `MacOS.version` (example: `macports.rb`) + + +## Caveats Stanza Details + +### Caveats as a String + +When `caveats` is a string, it is evaluated at compile time. Use this only for a static +message in which you don't need to interpolate any runtime variables. Example: + + caveats 'Using this software is hazardous to your health.' + +### Caveats as a Block + +When `caveats` is a Ruby block, evaluation is deferred until install time. Here you may +refer to the Cask instance in your message to the user: + +```ruby +caveats do + puts "Using #{@cask} is hazardous to your health." +end +``` + +### Caveats Mini-DSL + +There is a mini-DSL available within `caveats` blocks. + +The following methods may be called to generate standard warning messages: + +| method | description | +| --------------------------------- | ----------- | +| `manual_installer(path)` | The user should execute an installer to complete the installation. `path` may be absolute, or relative to the Cask. +| `path_environment_variable(path)` | The user should make sure `path` is in their `$PATH` environment variable +| `logout` | The user should log out and log back in to complete installation +| `reboot` | The user should reboot to complete installation +| `files_in_usr_local` | The Cask installs files to `/usr/local`, which may confuse Homebrew +| `arch_only(list)` | The Cask only supports certain architectures. Currently valid elements of `list` are `intel-32` and `intel-64` +| `os_version_only(list)` | The Cask only supports certain OS X Versions. Currently valid elements of `list` are `10.5`, `10.6`, `10.7`, `10.8`, and `10.9` + +Example: + +```ruby +caveats do + manual_installer 'Little Snitch Installer.app' +end +``` + +And the following methods may be useful for interpolation: + +| method | description | +| ------------------ | ----------- | +| `title` | the Cask title +| `caskroom_path` | eg `/opt/homebrew-cask/Caskroom` +| `destination_path` | where this particular Cask is stored, including version number, eg `/opt/homebrew-cask/Caskroom/google-chrome/stable-channel` + + +## Checksum Stanza Details + +Older Casks may still use `sha1` checksums. This is OK, but new +Casks and updates should adopt `sha256`. + + +## URL Stanza Details + +### HTTP URLs + +When a plain URL string is insufficient to fetch a file, additional +information may be provided to the `curl`-based downloader, in the form +of key/value pairs appended to `url`: + +| key | value | +| ------------------ | ----------- | +| `:cookies` | a hash of cookies to be set 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. + +Example: `java.rb` + +### Subversion URLs + +In rare cases, a distribution may not be available over ordinary HTTP. +Subversion URLs are also supported, and can be specified by appending the +following key/value pairs to `url`: + +| key | value | +| ------------------ | ----------- | +| `:using` | the symbol `:svn` is the only legal value +| `:revision` | a string identifying the subversion revision to download +| `:trust_cert` | set to `true` to automatically trust the certificate presented by the server (avoiding an interactive prompt) + + +## Link Stanza Details + +In the simple case of a string argument to `link`, a symlink is created in +the target `~/Applications` directory using the same basename as the source +file. For example: + +```ruby +link 'Alfred 2.app' +``` + +causes the creation of this symlink + +```bash +~/Applications/Alfred 2.app +``` + +which points to a source file such as + +```bash +/opt/homebrew-cask/Caskroom/alfred/2.1.1_227/Alfred 2.app +``` + +### Renaming the Target + +You can rename the target link which appears in your `~/Applications` +directory by adding a `:target` key to `link`, like this: + +```ruby +link 'Alfred 2.app', :target => 'Jeeves.app' +``` + +The `:target` key works similarly for other Cask artifacts, such as +`binary`, `colorpicker`, `font`, `input_method`, `prefpane`, `qlplugin`, +`service`, and `widget`. + + +## Install Stanza Details + +The first argument to `install` should be a relative path to the `pkg` file +to be installed. For example: + +```ruby +install 'Vagrant.pkg' +``` + +Subsequent arguments to `install` 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 +``` + + +## Uninstall Stanza Details + +A `pkg`-based Cask using `install` will **not** know how to uninstall +correctly unless an `uninstall` stanza is given. + +Since `pkg` installers can do arbitrary things, different techniques are +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` +is the most useful. + +* `:early_script` (string or hash) - like `:script`, but runs early (for special cases, best avoided) +* `:launchctl` (string or array) - ids of `launchctl` jobs to remove +* `:quit` (string or array) - bundle ids of running applications to quit +* `:kext` (string or array) - bundle ids of kexts to unload from the system +* `:pkgutil` (string or regexp) - regexp matching bundle ids of packages to uninstall using `pkgutil` +* `:script` (string or hash) - relative path to an uninstall script to be run via sudo; use hash if args are needed + - `:executable` - relative path to an uninstall script to be run via sudo (required for hash form) + - `:args` - array of arguments to the uninstall script + - `:input` - array of lines of input to be sent to `stdin` of the script + - `:must_succeed` - set to `false` if the script is allowed to fail +* `:files` (array) - absolute paths of files or directories to remove. `:files` should only be used as a last resort. `:pkgutil` is strongly preferred + +Each `uninstall` technique is applied according to the order above. The order +in which `uninstall` keys appear in the Cask file is ignored. + +For assistance filling in the right values for `uninstall` keys, there are +several helper scripts found under `developer/bin` in the homebrew-cask +repository. Each of these scripts responds to the `-help` option with +additional documentation. + +The easiest way to work out an `uninstall` stanza is on a system where the +`pkg` is currently installed and operational. To operate on an uninstalled +`pkg` file, see [Working With a pkg File Manually](#working-with-a-pkg-file-manually), below. + +### Uninstall Key :pkgutil + +This is the most important and useful uninstall key. `:pkgutil` is +often sufficient to completely uninstall a `pkg`. + +IDs for the most recently-installed packages can be listed using the +command +```bash +$ ./developer/bin/list_recent_pkg_ids +``` + +### List Files Associated With a `pkg` + +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 +OS X command +```bash +$ pkgutil --files +``` +Listing the associated files can help you assess whether the package +included any launchctl jobs or kernel extensions (kexts). + +### Uninstall Key :launchctl + +IDs for currently loaded launchctl jobs can be listed using the command +```bash +$ ./developer/bin/list_loaded_launchjob_ids +``` + +IDs for all installed launchctl jobs can be listed using the command +```bash +$ ./developer/bin/list_installed_launchjob_ids +``` + +### Uninstall Key :quit + +Bundle IDs for currently running Applications can be listed using the command +```bash +$ ./developer/bin/list_running_app_ids +``` + +Bundle IDs inside an Application bundle on disk can be listed using the command +```bash +$ ./developer/bin/list_ids_in_app +``` + +### Uninstall Key :kext + +IDs for currently loaded kernel extensions can be listed using the command +```bash +$ ./developer/bin/list_loaded_kext_ids +``` + +IDs inside a kext bundle you have located on disk can be listed using the command +```bash +$ ./developer/bin/list_id_in_kext +``` + +### Working With a pkg File Manually + +Advanced users may wish to work with a `pkg` file manually, without having the +package installed. + +A list of files which may be installed from a `pkg` can be extracted using the +command +```bash +$ ./developer/bin/list_payload_in_pkg +``` + +Candidate application names helpful for determining the name of a Cask may be +extracted from a `pkg` file using the command +```bash +$ ./developer/bin/list_apps_in_pkg +``` + +Candidate package IDs which may be useful in a `:pkgutil` key may be +extracted from a `pkg` file using the command +```bash +$ ./developer/bin/list_ids_in_pkg +``` + +A fully manual method for finding bundle ids in a package file follows: + + 1. Unpack `/path/to/my.pkg` (replace with your package name) with `pkgutil --expand /path/to/my.pkg /tmp/expanded.unpkg`. + 2. The unpacked package is a folder. Bundle ids are contained within files named `PackageInfo`. These files can be found + with the command `find /tmp/expanded.unpkg -name PackageInfo`. + 3. `PackageInfo` files are XML files, and bundle ids are found within the `identifier` attributes of `` tags that look like + ``, where extraneous attributes have been snipped out and replaced with ellipses. + 4. Kexts inside packages are also described in `PackageInfo` files. If any kernel extensions are present, the command + `find /tmp/expanded.unpkg -name PackageInfo -print0 | xargs -0 grep -i kext` should return a `` tag with a `path` + attribute that contains a `.kext` extension, for example ``. + 5. Once bundle ids have been identified, the unpacked package directory can be deleted. + +# <3 THANK YOU TO ALL CONTRIBUTORS! <3