mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

Cask-Cookbook: review and update

Browse Source 
with suggestions from code review

Co-Authored-By: Klaus Hipp <khipp@users.noreply.github.com>
Co-Authored-By: Bevan Kay <email@bevankay.me>
This commit is contained in:
Eric Knibbe 2025-05-18 00:23:17 -04:00
parent 2b25f34e85
commit e8a0142150
No known key found for this signature in database
1 changed files with 133 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

254
docs/Cask-Cookbook.md
View File

@ -1,5 +1,5 @@
---
last_review_date: "1970-01-01"
last_review_date: 2025-05-18
---
# Cask Cookbook
@ -33,7 +33,7 @@ Exception: `do` blocks such as `postflight` may enclose a block of pure Ruby cod
## Header line details
The Cask name ([`<cask-token>`](#token-reference)) on the header line `cask <cask-token> do` should match the cask filename, without the `.rb` extension, enclosed in double quotes.
The cask name ([`<cask-token>`](#token-reference)) on the header line `cask <cask-token> do` should match the cask filename, without the `.rb` extension, enclosed in double quotes.
There are currently some arbitrary limitations on cask tokens which are in the process of being removed. GitHub Actions will catch any errors during the transition.
@ -41,6 +41,9 @@ There are currently some arbitrary limitations on cask tokens which are in the p
Having a common order for stanzas makes casks easier to update and parse. Below is the complete stanza sequence (no cask will have all stanzas). The empty lines shown here are also important, as they help to visually delimit information.
arch
os
version
sha256
@ -109,21 +112,21 @@ Note that every stanza that has additional parameters (`:symbols` after a `,`) s
Each of the following stanzas is required for every cask.
| name | multiple occurrences allowed? | value |
| ---------------------------- | :---------------------------: | ----- |
| [`version`](#stanza-version) | no | Application version. |
| [`sha256`](#stanza-sha256) | no | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 <file>`. Can be suppressed by using the special value `:no_check`. |
| [`url`](#stanza-url) | no | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application. A [comment](#when-url-and-homepage-domains-differ-add-verified) should be added if the domains in the `url` and `homepage` stanzas differ. Block syntax should be used for URLs that change on every visit. |
| [`name`](#stanza-name) | yes | String providing the full and proper name defined by the vendor. |
| [`desc`](#stanza-desc) | no | One-line description of the cask. Shown when running `brew info`. |
| `homepage` | no | Application homepage; used for the `brew home` command. |
| [`livecheck`](#stanza-livecheck) | no | Ruby block describing how to find updates for this cask. Supersedes `appcast`. |
| [`depends_on`](#stanza-depends_on) | yes | List of dependencies and requirements for this cask. |
| [`zap`](#stanza-zap) | yes | Additional procedures for a more complete uninstall, including user files and shared resources. |
| name | multiple occurrences allowed? | value |
| ---------------------------------- | :---------------------------: | ----- |
| [`version`](#stanza-version) | no | Application version, or the special value `:latest`. |
| [`sha256`](#stanza-sha256) | no | SHA-256 checksum of the file downloaded from `url` as calculated by the command `shasum -a 256 <file>`, or the special value `:no_check`. |
| [`url`](#stanza-url) | no | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application. A [comment](#when-url-and-homepage-domains-differ-add-verified) should be added if the domains in the `url` and `homepage` stanzas differ. |
| [`name`](#stanza-name) | yes | String providing the full and proper name defined by the vendor. |
| [`desc`](#stanza-desc) | no | One-line description of the cask. Shown when running `brew info`. |
| `homepage` | no | Application homepage; used for the `brew home` command. |
| [`livecheck`](#stanza-livecheck) | no | Ruby block describing how to find updates for this cask. Supersedes `appcast`. |
| [`depends_on`](#stanza-depends_on) | yes | List of dependencies and requirements for this cask. |
| [`zap`](#stanza-zap) | yes | Additional procedures for a more complete uninstall, including user files and shared resources. |
### At least one artifact stanza is also required
Each cask must declare one or more *artifacts* (i.e. something to install).
Each cask must declare one or more [artifacts](https://rubydoc.brew.sh/Cask/Artifact) (i.e. something to install).
| name | multiple occurrences allowed? | value |
| -------------------------------- | :---------------------------: | ----- |
@ -157,11 +160,11 @@ Each cask must declare one or more *artifacts* (i.e. something to install).
| name | multiple occurrences allowed? | value |
| ------------------------------------------ | :---------------------------: | ----- |
| [`uninstall`](#stanza-uninstall) | yes | Procedures to uninstall a cask. Optional unless the `pkg` stanza is used. |
| [`conflicts_with`](#stanza-conflicts_with) | yes | List of conflicts with this cask (*not yet functional*). |
| [`uninstall`](#stanza-uninstall) | yes | Procedures to uninstall a cask. Optional unless a `pkg` or `installer` artifact stanza is used. |
| [`conflicts_with`](#stanza-conflicts_with) | yes | List of conflicts with this cask. |
| [`caveats`](#stanza-caveats) | yes | String or Ruby block providing the user with cask-specific information at install time. |
| [`deprecate!`](#stanza-deprecate--disable) | no | Date as a String in `YYYY-MM-DD` format and a String or Symbol providing a reason. |
| [`disable!`](#stanza-deprecate--disable) | no | Date as a String in `YYYY-MM-DD` format and a String or Symbol providing a reason. |
| [`deprecate!`](#stanza-deprecate--disable) | no | Date as a string in `YYYY-MM-DD` format and a string or symbol providing a reason. |
| [`disable!`](#stanza-deprecate--disable) | no | Date as a string in `YYYY-MM-DD` format and a string or symbol providing a reason. |
| `preflight` | yes | Ruby block containing preflight install operations (needed only in very rare cases). |
| [`postflight`](#stanza-flight) | yes | Ruby block containing postflight install operations. |
| `uninstall_preflight` | yes | Ruby block containing preflight uninstall operations (needed only in very rare cases). |
@ -250,7 +253,7 @@ Behaviour and usage of `target:` is [the same as with `app`](#renaming-the-targe
Sometimes there are particularities with the installation of a piece of software that cannot or should not be handled programmatically by Homebrew Cask. In those instances, `caveats` is the way to inform the user. Information in `caveats` is displayed when a cask is invoked with either `install` or `info`.
To avoid flooding users with too many messages (thus desensitising them to the important ones), `caveats` should be used sparingly and exclusively for installation-related matters. If you’re not sure a `caveat` you find pertinent is installation-related or not, ask a maintainer. As a general rule, if your case isn’t already covered in our comprehensive [`caveats Mini-DSL`](#caveats-mini-dsl), it’s unlikely to be accepted.
To avoid flooding users with too many messages (thus desensitising them to the important ones), `caveats` should be used sparingly and exclusively for installation-related matters. If you’re not sure whether a `caveat` you find pertinent is installation-related or not, ask a maintainer. As a general rule, if your case isn’t already covered in our comprehensive [`caveats mini-DSL`](#caveats-mini-dsl), it’s unlikely to be accepted.
#### `caveats` as a string
@ -347,13 +350,13 @@ Refer to [Deprecating, Disabling and Removing Casks](Deprecating-Disabling-and-R
### Stanza: `conflicts_with`
`conflicts_with` is used to declare conflicts that keep a cask from installing or working correctly.
`conflicts_with` is used to declare conflicts that prevent a cask from installing or working correctly.
#### `conflicts_with` *cask*
The value should be another cask token.
Example: the [macFUSE](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/m/macfuse.rb#L17) cask, which conflicts with `macfuse-dev`.
Example: [macFUSE](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/m/macfuse.rb#L17), which conflicts with `macfuse-dev`.
```ruby
conflicts_with cask: "macfuse-dev"
@ -377,7 +380,7 @@ conflicts_with formula: "macvim"
#### `depends_on` *cask*
The value should be another cask token, needed by the current cask.
The value should be one or more tokens of casks needed by the current cask, as a string or array of strings.
Example: [NTFSTool](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/n/ntfstool.rb#L11), which depends on macFUSE.
@ -387,7 +390,7 @@ depends_on cask: "macfuse"
#### `depends_on` *formula*
The value should name a Homebrew formula needed by the cask.
The value should be one or more names of formulae needed by the current cask, as a string or array of strings.
Example: some distributions are contained in archive formats such as `7z` which are not supported by stock Apple tools. For these cases, a more capable archive reader may be pulled in at install time by declaring a dependency on the `unar` formula:
@ -399,7 +402,7 @@ depends_on formula: "unar"
##### Requiring an exact macOS release
The value for `depends_on macos:` may be a symbol or an array of symbols, listing the exact compatible macOS releases. The available values for macOS releases are defined in the [MacOSVersion class](https://rubydoc.brew.sh/MacOSVersion.html).
The value for `depends_on macos:` may be a symbol or an array of symbols, listing the exact compatible macOS releases. The values for supported macOS releases can be found in the [`MacOSVersion` class](https://rubydoc.brew.sh/MacOSVersion) documentation.
Only major releases are covered (10.x numbers containing a single dot or whole numbers since macOS 11). The symbol form is used for readability. The following are all valid ways to enumerate the exact macOS release requirements for a cask:
@ -413,7 +416,7 @@ depends_on macos: [
##### Setting a minimum macOS release
`depends_on macos:` can also accept a string starting with a comparison operator such as `>=`, followed by an macOS release in the form above. The following is a valid expression meaning “at least macOS Big Sur (11.0)”:
`depends_on macos:` can also accept a string starting with a comparison operator such as `>=`, followed by a macOS release in the form above. The following is a valid expression meaning “at least macOS Big Sur (11.0)”:
```ruby
depends_on macos: ">= :big_sur"
@ -423,12 +426,12 @@ A comparison expression cannot be combined with any other form of `depends_on ma
#### `depends_on` *arch*
The value for `depends_on arch:` may be a symbol or an array of symbols, listing the hardware compatibility requirements for a cask. The requirement is satisfied at install time if any one of multiple `arch:` values matches the user’s hardware.
The value for `depends_on arch:` may be a symbol or an array of symbols, listing the hardware compatibility requirements for a cask. The requirement is satisfied at install time if any one of the provided `arch:` values matches the user’s hardware.
The available symbols for hardware are:
| symbol | meaning |
| ---------- | -------------- |
| symbol | meaning |
| ---------- | ------- |
| `:arm64` | Apple Silicon |
| `:x86_64` | 64-bit Intel |
| `:intel` | 64-bit Intel |
@ -446,15 +449,15 @@ depends_on arch: [:x86_64] # same meaning as above
| key | description |
| ---------- | ----------- |
| `formula:` | Homebrew formula |
| `cask:` | cask token |
| `macos:` | symbol, array, or string comparison expression defining macOS release requirements |
| `arch:` | symbol or array defining hardware requirements |
| `formula:` | required Homebrew formula names as string or array |
| `cask:` | required Homebrew cask tokens as string or array |
| `macos:` | macOS release requirements as symbol, array or string comparison expression |
| `arch:` | hardware requirements as symbol or array |
| `java:` | *stub - not yet functional* |
### Stanza: `desc`
`desc` accepts a single-line UTF-8 string containing a short description of the software. It’s used to help with searchability and disambiguation, thus it must concisely describe what the software does (or what you can accomplish with it).
`desc` accepts a single-line UTF-8 string containing a short description of the software. As it’s used to help with searchability and disambiguation, it must concisely describe what the software does (or what you can accomplish with it).
`desc` is not for app slogans! Vendors’ descriptions tend to be filled with generic adjectives such as “modern” and “lightweight”. Those are meaningless marketing fluff (do you ever see apps proudly describing themselves as outdated and bulky?) which must be deleted. It’s fine to use the information on the software’s website as a starting point, but it will require editing in almost all cases.
@ -481,7 +484,7 @@ depends_on arch: [:x86_64] # same meaning as above
+ desc "Sound and music editor"
```
* **Do not** include the platform. Casks only work on macOS, so this is redundant information.
* **Do not** include the platform. Casks always work on macOS, so this is redundant information.
```diff
- desc "Sound and music editor for macOS"
@ -535,7 +538,7 @@ The following methods may be called to perform standard tasks:
| `set_ownership(paths)` | `preflight`, `postflight`, `uninstall_preflight` | Set user and group ownership of `paths`. (Example: [docker-toolbox.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/d/docker-toolbox.rb#L42)) |
| `set_permissions(paths, permissions_str)` | `preflight`, `postflight`, `uninstall_preflight` | Set permissions in `paths` to `permissions_str`. (Example: [ngrok.rb](https://github.com/Homebrew/homebrew-cask/blob/41d91ff669d85343175202adf568e2328486205f/Casks/n/ngrok.rb#L30)) |
`set_ownership(paths)` defaults user ownership to the current user and group ownership to `staff`. These can be changed by passing in extra options: `set_ownership(paths, user: "user", group: "group")`. (Example: [hummingbird.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/h/hummingbird.rb#L24))
`set_ownership(paths)` defaults to setting user and group ownership to the current user and `staff`. These can be changed by passing in extra options: `set_ownership(paths, user: "user", group: "group")`. (Example: [hummingbird.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/h/hummingbird.rb#L24))
### Stanza: `installer`
@ -545,7 +548,7 @@ The `installer` stanza takes a series of key-value pairs, the first key of which
#### `installer` *manual*
`installer manual:` takes a single string value, describing a GUI installer which must be run by the user at a later time. The path may be absolute, or relative to the cask. Example (from [rubymotion.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/r/rubymotion.rb#L15)):
`installer manual:` takes a single string value for the path to an interactive installer which must be run by the user at a later time. The path may be absolute, or relative to the cask. Example (from [rubymotion.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/r/rubymotion.rb#L15)):
```ruby
installer manual: "RubyMotion Installer.app"
@ -553,7 +556,7 @@ installer manual: "RubyMotion Installer.app"
#### `installer` *script*
`installer script:` introduces a series of key-value pairs describing a command which will automate completion of the install. **It should never be used for interactive installations.** The form is similar to [`uninstall script:`](#uninstall-script):
`installer script:` takes a series of key-value pairs describing a command which will automate completion of the install. **It should never be used for interactive installations.** The form is similar to [`uninstall script:`](#uninstall-script):
| key | value |
| --------------- | ----- |
@ -574,7 +577,7 @@ installer script: {
}
```
If the `installer script:` does not require any of the key-values it can point directly to the path of the install script:
If the `installer script:` does not require any of the key-value pairs, it can be given just the path to the install script:
```ruby
installer script: "#{staged_path}/install.sh"
@ -638,7 +641,7 @@ The `livecheck` stanza is used to automatically fetch the latest version of a ca
Every `livecheck` block must contain a `url`, which can be either a string or a symbol pointing to other URLs in the cask (`:url` or `:homepage`).
Refer to the [`brew livecheck` documentation](Brew-Livecheck.md) for how to write a `livecheck` block.
Refer to the [`brew livecheck`](Brew-Livecheck.md) documentation for how to write a `livecheck` block.
### Stanza: `name`
@ -660,7 +663,7 @@ The first argument to the `pkg` stanza should be a relative path to the `.pkg` f
pkg "Unity.pkg"
```
Subsequent arguments to `pkg` are key/value pairs which modify the install process. Currently supported keys are `allow_untrusted:` and `choices:`.
Subsequent arguments to `pkg` are key-value pairs which modify the install process. Currently supported keys are `allow_untrusted:` and `choices:`.
#### `pkg` *allow_untrusted*
@ -731,9 +734,9 @@ shasum --algorithm 256 <file>
#### Special value `:no_check`
The special value `sha256 :no_check` is used to turn off SHA checking whenever checksumming is impractical due to the upstream configuration.
The special value `sha256 :no_check` is used to turn off SHA checking whenever checksumming is impractical due to the upstream configuration, e.g. when `url` does not change between releases.
`version :latest` requires `sha256 :no_check`, and this pairing is common. However, `sha256 :no_check` does not require `version :latest`.
`sha256 :no_check` is required by [`version :latest`](#special-value-latest), and this pairing is common. However, `sha256 :no_check` does not require `version :latest`.
We use a checksum whenever possible.
@ -757,37 +760,37 @@ The value of `suite` is never an `.app` bundle, but a plain directory.
The easiest and most useful `uninstall` directive is [`pkgutil:`](#uninstall-pkgutil). It should cover most use cases.
#### `uninstall` is required for casks that install using `pkg` or `installer manual:`
#### `uninstall` is required for casks that install using `pkg` or `installer`
For most casks, uninstall actions are determined automatically, and an explicit `uninstall` stanza is not needed. However, a cask which uses the `pkg` or `installer manual:` stanzas will **not** know how to uninstall correctly unless an `uninstall` stanza is given.
For most casks, uninstall actions are determined automatically, and an explicit `uninstall` stanza is not needed. However, a cask which uses the [`pkg`](#stanza-pkg) or [`installer`](#stanza-installer) stanzas will **not** know how to uninstall correctly unless an `uninstall` stanza is given.
So, while the [cask DSL](#required-stanzas) does not enforce the requirement, it is much better for users if every `pkg` and `installer manual:` has a corresponding `uninstall`.
So, while the [cask DSL](#required-stanzas) does not enforce the requirement, it is much better for users if every `pkg` and `installer` has a corresponding `uninstall`.
The `uninstall` stanza is available for non-`pkg` casks, and is useful for a few corner cases. However, the documentation below concerns the typical case of using `uninstall` to define procedures for a `pkg`.
The `uninstall` stanza is available for other artifact types, and is useful for a few corner cases. However, the documentation below concerns the typical case of using `uninstall` to define procedures for a `pkg`.
#### There are multiple uninstall techniques
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`.
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`.
#### Summary of keys
* **`early_script:`** (string or hash) - like [`script:`](#uninstall-script), but runs early (for special cases, best avoided)
* [`launchctl:`](#uninstall-launchctl) (string or array) - IDs of `launchd` jobs to remove
* [`quit:`](#uninstall-quit) (string or array) - bundle IDs of running applications to quit (does not run when uninstall is initiated by `brew upgrade` or `brew reinstall`)
* [`signal:`](#uninstall-signal) (array of arrays) - signal numbers and bundle IDs of running applications to send a Unix signal to - for when `quit:` does not work (does not run when uninstall is initiated by `brew upgrade` or `brew reinstall`)
* [`signal:`](#uninstall-signal) (array of arrays) - signal numbers and bundle IDs of running applications to send a Unix signal to, for when `quit:` does not work (does not run when uninstall is initiated by `brew upgrade` or `brew reinstall`)
* [`login_item:`](#uninstall-login_item) (string or array) - names of login items to remove
* [`kext:`](#uninstall-kext) (string or array) - bundle IDs of kexts to unload from the system
* [`script:`](#uninstall-script) (string or hash) - relative path to an uninstall script to be run via sudo; use hash if args are needed
* [`script:`](#uninstall-script) (string or hash) - relative path to an uninstall script to be run via *sudo*; use hash if args are needed
* [`pkgutil:`](#uninstall-pkgutil) (string, regexp or array of strings and regexps) - strings or regexps matching bundle IDs of packages to uninstall using `pkgutil`
* [`delete:`](#uninstall-delete) (string or array) - double-quoted, absolute paths of files or directory trees to remove. Should only be used as a last resort; `pkgutil:` is strongly preferred.
* **`rmdir:`** (string or array) - double-quoted, absolute paths of directories to remove if empty. Works recursively.
* **`rmdir:`** (string or array) - double-quoted, absolute paths of directories to remove if empty; works recursively
* [`trash:`](#uninstall-trash) (string or array) - double-quoted, absolute paths of files or directory trees to move to Trash
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.
For assistance filling in the right values for `uninstall` keys, there are several [helper scripts found under `developer/bin`](https://github.com/Homebrew/homebrew-cask/tree/HEAD/developer/bin) in the Homebrew Cask repository. Each of these scripts responds to the `-help` option with additional documentation.
Working out an `uninstall` stanza is easiest when done on a system where the package 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.
Working out an `uninstall` stanza is easiest when done on a system where the package 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` *pkgutil*
@ -799,7 +802,7 @@ IDs for the most recently installed packages can be listed using [`list_recent_p
"$(brew --repository homebrew/cask)/developer/bin/list_recent_pkg_ids"
```
`pkgutil:` also accepts a regular expression match against multiple package IDs. The regular expressions are somewhat nonstandard. To test a `pkgutil:` regular expression against currently installed packages, use [`list_pkg_ids_by_regexp`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/developer/bin/list_pkg_ids_by_regexp):
`pkgutil:` also accepts a regular expression to match against multiple package IDs. The regular expressions are somewhat nonstandard. To test a `pkgutil:` regular expression against currently installed packages, use [`list_pkg_ids_by_regexp`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/developer/bin/list_pkg_ids_by_regexp):
```bash
"$(brew --repository homebrew/cask)/developer/bin/list_pkg_ids_by_regexp" <regular-expression>
@ -847,7 +850,7 @@ Bundle IDs inside an application bundle on disk can be listed using [`list_ids_i
`signal:` should only be needed in the rare case that a process does not respond to `quit:`.
Bundle IDs for `signal:` targets may be obtained in the same way as for `quit:`. The value for `signal:` is an array-of-arrays, with each cell containing two elements: the desired Unix signal followed by the corresponding bundle ID.
Bundle IDs for `signal:` targets may be obtained in the same way as for `quit:`. The value for `signal:` is an array of arrays, with each cell containing two elements: the desired Unix signal followed by the corresponding bundle ID.
The Unix signal may be given in numeric or string form (see the `kill`(1) man page for more details).
@ -869,7 +872,7 @@ uninstall signal: [
Note that when multiple running processes match the given bundle ID, all matching processes will be signaled.
Unlike `quit:` directives, Unix signals originate from the current user, not from the superuser. This is construed as a safety feature, since the superuser is capable of bringing down the system via signals. However, this inconsistency may also be considered a bug, and should be addressed in some fashion in a future version.
Unlike `quit:` directives, Unix signals originate from the current user, not from the superuser. This is construed as a safety feature, since the superuser is capable of bringing down the system via signals. However, this inconsistency could also be considered a bug, and may be addressed in some fashion in a future version.
#### `uninstall` *login_item*
@ -965,7 +968,7 @@ 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 `<pkg-info>` tags that look like `<pkg-info ... identifier="com.oracle.jdk7u51" ... >`, where extraneous attributes have been snipped out and replaced with ellipses.
3. `PackageInfo` files are XML files, and bundle IDs are found within the `identifier` attributes of `<pkg-info>` tags that look like `<pkg-info ... identifier="com.oracle.jdk7u51" ... >` (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 `<bundle id>` tag with a `path` attribute that contains a `.kext` extension, for example `<bundle id="com.wavtap.driver.WavTap" ... path="./WavTap.kext" ... />`.
5. Once bundle IDs have been identified, the unpacked package directory can be deleted.
@ -977,17 +980,17 @@ If available, an HTTPS URL is preferred. A plain HTTP URL should only be used in
#### Additional `url` parameters
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`:
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 |
| ------------------ | ----------- |
| key | value |
| ------------------ | ----- |
| `verified:` | string repeating the beginning of `url`, for [verification purposes](#when-url-and-homepage-domains-differ-add-verified) |
| `using:` | the symbols `:post` and `:homebrew_curl` are the only legal values |
| `cookies:` | hash of cookies to be set in the download request (Example: [oracle-jdk-javadoc.rb](https://github.com/Homebrew/homebrew-cask/blob/326c44e93aeb8d4dd73acea14a99ae215c75fdd6/Casks/o/oracle-jdk-javadoc.rb#L5-L8)) |
| `referer:` | string holding the URL to set as referer in the download request (Example: [firealpaca.rb](https://github.com/Homebrew/homebrew-cask/blob/c4b3f0742e044ae2a6e114eb6b90068763d0d12b/Casks/f/firealpaca.rb#L5-L6)) |
| `cookies:` | hash of cookies to be set for the download request (Example: [oracle-jdk-javadoc.rb](https://github.com/Homebrew/homebrew-cask/blob/326c44e93aeb8d4dd73acea14a99ae215c75fdd6/Casks/o/oracle-jdk-javadoc.rb#L5-L8)) |
| `referer:` | string holding the URL to set as referer for the download request (Example: [firealpaca.rb](https://github.com/Homebrew/homebrew-cask/blob/c4b3f0742e044ae2a6e114eb6b90068763d0d12b/Casks/f/firealpaca.rb#L5-L6)) |
| `header:` | string or array of strings holding the header(s) to set for the download request (Example: [pull-6545](https://github.com/Homebrew/brew/pull/6545#issue-503302353), [issue-15590](https://github.com/Homebrew/brew/issues/15590#issue-1774825542)) |
| `user_agent:` | 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. |
| `data:` | hash of parameters to be set in the POST request (Example: [segger-jlink.rb](https://github.com/Homebrew/homebrew-cask/blob/38ac55614f146d68ae317594f0c119e9acbd7c9e/Casks/s/segger-jlink.rb#L6-L11)) |
| `data:` | hash of parameters to be set for a POST request (Example: [segger-jlink.rb](https://github.com/Homebrew/homebrew-cask/blob/38ac55614f146d68ae317594f0c119e9acbd7c9e/Casks/s/segger-jlink.rb#L6-L11)) |
#### When URL and homepage domains differ, add `verified:`
@ -995,11 +998,11 @@ When the domains of `url` and `homepage` differ, the discrepancy should be docum
This must be added so a user auditing the cask knows the URL was verified by the Homebrew Cask team as the one provided by the vendor, even though it may look unofficial. It is our responsibility as Homebrew Cask maintainers to verify both the `url` and `homepage` information when first added (or subsequently modified, apart from versioning).
The parameter doesn’t mean you should trust the source blindly, but we only approve casks in which users can easily verify its authenticity with basic means, such as checking the official homepage or public repository. Occasionally, slightly more elaborate techniques may be used, such as inspecting a [`livecheck`](#stanza-livecheck) URL we established as official. Cases where such quick verifications aren’t possible (e.g. when the download URL is behind a registration wall) are [treated in a stricter manner](https://docs.brew.sh/Acceptable-Casks#unofficial-vendorless-and-walled-builds).
The parameter doesn’t mean you should trust the source blindly, but we only approve casks in which users can easily verify its authenticity with basic means, such as checking the official homepage or public repository. Occasionally, slightly more elaborate techniques may be used, such as inspecting a [`livecheck`](#stanza-livecheck) URL we established as official. Cases where such quick verifications aren’t possible (e.g. when the download URL is behind a registration wall) are [treated in a stricter manner](Acceptable-Casks.md#unofficial-vendorless-and-walled-builds).
#### Difficulty finding a URL
Web browsers may obscure the direct `url` download location for a variety of reasons. Homebrew Cask supplies a [`list_url_attributes_on_file`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/developer/bin/list_url_attributes_on_file) script which can read extended file attributes to extract the actual source URL of most files downloaded by a browser on macOS. The script usually emits multiple candidate URLs; you may have to test each of them:
Web browsers may obscure the direct `url` of a download for a variety of reasons. Homebrew Cask supplies a [`list_url_attributes_on_file`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/developer/bin/list_url_attributes_on_file) script which can read extended file attributes to extract the actual source URL of most files downloaded by a browser on macOS. The script usually emits multiple candidate URLs; you may have to test each of them:
```bash
$(brew --repository homebrew/cask)/developer/bin/list_url_attributes_on_file <file>
@ -1007,25 +1010,25 @@ $(brew --repository homebrew/cask)/developer/bin/list_url_attributes_on_file <fi
#### Subversion URLs
In rare cases, a distribution may not be available over ordinary HTTP/S. Subversion URLs are also supported, and can be specified by appending the following key/value pairs to `url`:
In rare cases, a distribution may not be available over ordinary HTTP(S). Subversion URLs are also supported, and can be specified by appending the following key-value pairs to `url`:
| key | value |
| ------------------ | ----------- |
| key | value |
| ------------------ | ----- |
| `using:` | the symbol `:svn` is the only legal value |
| `revision:` | 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) |
#### Git URLs
Artifacts also may be distributed via Git repositories. URLs that end in `.git` are automatically assumed to be Git repositories, and the following key/value pairs may be appended to `url`:
Artifacts may also be distributed via Git repositories. URLs that end in `.git` are automatically assumed to be Git repositories, and the following key-value pairs may be appended to `url`:
| key | value |
| ------------------ | ----------- |
| key | value |
| ------------------ | ----- |
| `using:` | the symbol `:git` is the only legal value |
| `tag:` | string identifying the Git tag to download |
| `revision:` | string identifying the Git revision to download |
| `branch:` | string identifying the Git branch to download |
| `only_path:` | path within the repository to limit the checkout to. If only a single directory of a large repository is required, using this option can significantly speed up downloads. If provided, artifact paths are relative to this path. (Example: [font-geo.rb](https://github.com/Homebrew/homebrew-cask-fonts/blob/bac691e1d7b5bd7372e7e0befae989a3ff7ad449/Casks/font-geo.rb#L5-L8)) |
| `only_path:` | path within the repository to limit the checkout to. If only a single directory of a large repository is required, using this option can significantly speed up downloads. If provided, artifact paths are relative to this path. (Example: [font-geo.rb](https://github.com/Homebrew/homebrew-cask/blob/a6348a1710928bf43510098725c2068ffe3adc69/Casks/font/font-g/font-geo.rb#L5-L8)) |
#### SourceForge/OSDN URLs
@ -1051,7 +1054,9 @@ Other providers may use URLs that change periodically, or even on each visit (ex
#### Using a block to defer code execution
Some casks—notably nightlies—have versioned download URLs but are updated so often that they become impractical to keep current with the usual process. For those, we want to dynamically determine `url`.
Some applications—notably nightlies—have versioned download URLs that are updated so often that they become impractical to keep current with the usual process. For those, we want to dynamically determine `url`.
**Note:** Casks with a dynamically-determined `url` are not allowed in Homebrew/homebrew-cask as they interfere with API generation.
##### The Problem
@ -1061,7 +1066,7 @@ However, this typically involves an HTTP round trip to a landing site, which may
##### Writing the block
Similar to the `preflight`, `postflight`, `uninstall_preflight`, and `uninstall_postflight` blocks, the `url` stanza offers an optional *block syntax*:
Similar to the `preflight`, `postflight`, `uninstall_preflight` and `uninstall_postflight` blocks, the `url` stanza offers an optional *block syntax*:
```ruby
url "https://handbrake.fr/nightly.php" do |page|
@ -1072,23 +1077,23 @@ end
You can also nest `url do` blocks inside `url do` blocks to follow a chain of URLs.
The block is only evaluated when needed, for example at download time or when auditing a cask. Inside a block, you may safely do things such as HTTP/S requests that may take a long time to execute. You may also refer to the `@cask` instance variable, and invoke [any method available on `@cask`](https://rubydoc.brew.sh/Cask/Cask).
The block is only evaluated when needed, for example at download time or when auditing a cask. Inside a block, you may safely do things such as HTTP(S) requests that may take a long time to execute. You may also refer to the `@cask` instance variable, and invoke [any method available on `@cask`](https://rubydoc.brew.sh/Cask/Cask).
The block will be called immediately before downloading; its result value will be assumed to be a `String` (or a pair of a `String` and `Hash` containing parameters) and subsequently used as a download URL.
The block will be called immediately before downloading; its resulting value is assumed to be a `String` (or a pair of a `String` and `Hash` containing parameters) and subsequently used as a download URL.
You can use the `url` stanza with either a direct argument or a block but not with both.
Example of using the block syntax: [vlc@nightly.rb](https://github.com/Homebrew/homebrew-cask/blob/0b2b76ad8c3fbf4e1ee2f5e758640c4963ad6aaf/Casks/v/vlc%40nightly.rb#L7-L12)
Historical example of using block syntax: [vlc@nightly.rb](https://github.com/Homebrew/homebrew-cask/blob/0b2b76ad8c3fbf4e1ee2f5e758640c4963ad6aaf/Casks/v/vlc%40nightly.rb#L7-L12)
##### Mixing additional URL parameters with the block syntax
##### Mixing additional URL parameters with block syntax
In rare cases, you might need to set URL parameters like `cookies` or `referer` while also using the block syntax.
In rare cases, you might need to set URL parameters like `cookies` or `referer` while also using block syntax.
This is possible by returning a two-element array as a block result. The first element of the array must be the download URL; the second element must be a `Hash` containing the parameters.
### Stanza: `version`
`version`, while related to the app’s own versioning, doesn’t have to follow it exactly. It is common to change it slightly so it can be [interpolated](https://en.wikipedia.org/wiki/String_interpolation#Ruby_/_Crystal) in other stanzas, usually in `url` to create a cask that only needs `version` and `sha256` changes when updated. This can be taken further, when needed, with [Ruby String methods](https://ruby-doc.org/core/String.html).
`version`, while related to the app’s own versioning, doesn’t have to follow it exactly. It is common to change it slightly so it can be [interpolated](https://en.wikipedia.org/wiki/String_interpolation#Ruby_/_Crystal) in other stanzas, usually in `url` to create a cask that only needs `version` and `sha256` changes when updated. This can be taken further, when needed, with [Ruby `String` methods](https://ruby-doc.org/core/String.html).
For example, instead of:
@ -1122,8 +1127,8 @@ url "https://example.com/#{version.sub(/build\d+/, "")}/file-version-#{version}.
The examples above can become hard to read, however. Since many of these changes are common, we provide a number of helpers to clearly interpret otherwise obtuse cases:
| method | input | output |
| ------------------------ | ------------------ | ------------------ |
| method | input | output |
| ------------------------ | ------------------ | ------ |
| `major` | `1.2.3-a45,ccdd88` | `1` |
| `minor` | `1.2.3-a45,ccdd88` | `2` |
| `patch` | `1.2.3-a45,ccdd88` | `3-a45` |
@ -1139,15 +1144,14 @@ Similar to `dots_to_hyphens`, we provide methods for all logical permutations of
Finally, there is `csv` which returns an array of comma-separated values, which replaces the deprecated `before_comma` and `after_comma` methods. Comma-separated versions should only be used for otherwise complex cases; ideally, there should be no more than two instances of `,` per `version`, although methods up to `csv.fifth` are available.
#### `version :latest`
#### Special value `:latest`
The special value `:latest` is used when:
The special value `version :latest` is used when:
* `url` does not contain any version information and there is no way to retrieve
the version using a `livecheck`, or
* having a correct value for `version` is too difficult or impractical, even with our automated systems. For example,
[chromium.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/c/chromium.rb#L4)
releases multiple versions a day.
* `url` does not contain any version information and there is no way to retrieve the version using a `livecheck`, or
* having a correct value for `version` is too difficult or impractical, even with our automated systems. For example, [chromium.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/c/chromium.rb#L4) which releases multiple versions per day.
In both cases, using the special value [`sha256 :no_check`](#special-value-no_check) is also required.
### Stanza: `zap`
@ -1186,10 +1190,10 @@ The simplest method is to use [@nrlquaker's CreateZap](https://github.com/nrlqua
Manual creation can be facilitated with:
* Some of the developer tools which are already available in Homebrew Cask.
* Some of the [helper scripts found under `developer/bin`](https://github.com/Homebrew/homebrew-cask/tree/HEAD/developer/bin)
* `sudo find / -iname "*<search item>*"`
* An uninstaller tool such as [AppCleaner](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/a/appcleaner.rb).
* Inspection of the usual paths, i.e. `/Library/{'Application Support',LaunchAgents,LaunchDaemons,Frameworks,Logs,Preferences,PrivilegedHelperTools}` and `~/Library/{'Application Support',Caches,Containers,LaunchAgents,Logs,Preferences,'Saved Application State'}`.
* An uninstaller tool such as [AppCleaner](https://formulae.brew.sh/cask/appcleaner)
* Inspection of the usual paths, i.e. `/Library/{'Application Support',LaunchAgents,LaunchDaemons,Frameworks,Logs,Preferences,PrivilegedHelperTools}` and `~/Library/{'Application Support',Caches,Containers,LaunchAgents,Logs,Preferences,'Saved Application State'}`
If no additional files are discovered, instead of a zap stanza, include the following comment:
@ -1201,7 +1205,7 @@ If no additional files are discovered, instead of a zap stanza, include the foll
### Handling different system configurations
Casks can deliver specific versions of artifacts depending on the current macOS release or CPU architecture by either tailoring the URL / SHA-256 hash / version, using the [`on_<system>` syntax](Formula-Cookbook.md#handling-different-system-configurations) (which replaces conditional statements using `MacOS.version` or `Hardware::CPU`), or both.
Casks can deliver specific versions of artifacts depending on the current macOS release or CPU architecture by either tailoring the `url` / `sha256` / `version` stanzas, using the [`on_<system>` syntax](Formula-Cookbook.md#handling-different-system-configurations) (which replaces conditional statements using `MacOS.version` or `Hardware::CPU`), or both.
If your cask's artifact is offered as separate downloads for Apple Silicon and Intel architectures, they'll presumably be downloadable at distinct URLs that differ only slightly. To adjust the URL depending on the current CPU architecture, supply a hash for each to the `arm:` and `intel:` parameters of `sha256`, and use the special `arch` stanza to define the unique components of the respective URLs for substitution in the `url`. Additional substitutions can be defined by calling `on_arch_conditional` directly. Example (from [libreoffice.rb](https://github.com/Homebrew/homebrew-cask/blob/a4164b8f5084fdaefb6e2e2f4f699270690b7845/Casks/l/libreoffice.rb#L1-L10)):
@ -1268,7 +1272,7 @@ cask "calibre" do
end
```
Such `on_<system>` blocks can be nested and contain other stanzas not listed here. Examples: [calhash.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/calhash.rb), [openzfs.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/o/openzfs.rb), [r.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/r/r.rb), [wireshark.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/wireshark.rb)
Such `on_<system>` blocks can be nested and contain other stanzas not listed here. However, they should not contain `depends_on macos:` stanzas, which should occur once below the `on_<system>` blocks and encompass all releases listed in the cask. Examples: [calhash.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/calhash.rb), [openzfs.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/o/openzfs.rb), [r.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/r/r.rb), [wireshark.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/wireshark.rb)
### Switch between languages or regions
@ -1305,12 +1309,12 @@ Variables and methods should not be defined outside the `Utils` namespace, as th
This section describes the algorithm implemented in the `generate_cask_token` script, and covers detailed rules and exceptions which are not needed in most cases.
* [Purpose](#purpose)
* [Finding the Simplified Name of the Vendor’s Distribution](#finding-the-simplified-name-of-the-vendors-distribution)
* [Converting the Simplified Name To a Token](#converting-the-simplified-name-to-a-token)
* [Cask Filenames](#cask-filenames)
* [Cask Headers](#cask-headers)
* [Cask Token Examples](#cask-token-examples)
* [Special Affixes](#special-affixes)
* [Finding the simplified name of the vendor’s distribution](#finding-the-simplified-name-of-the-vendors-distribution)
* [Converting the simplified name to a token](#converting-the-simplified-name-to-a-token)
* [Cask filenames](#cask-filenames)
* [Cask headers](#cask-headers)
* [Cask token examples](#cask-token-examples)
* [Special affixes](#special-affixes)
### Purpose
@ -1320,7 +1324,7 @@ Software vendors are often inconsistent with their naming. By enforcing strict n
* Minimize renaming events
* Unambiguously boil down the name of the software into a unique identifier
Details of software names and brands will inevitably be lost in the conversion to a minimal token. To capture the vendor’s full name for a distribution, use the [`name`](#stanza-name) within a cask. `name` accepts an unrestricted UTF-8 string.
Details of software names and brands will inevitably be lost in the conversion to a minimal token. To capture the vendor’s full name for a distribution, use the [`name`](#stanza-name) within a cask, which accepts an unrestricted UTF-8 string.
### Finding the simplified name of the vendor’s distribution
@ -1332,9 +1336,13 @@ Details of software names and brands will inevitably be lost in the conversion t
* Remove `.app` from the end.
* Remove from the end: the string “app”, if the vendor styles the name like “Software App.app”. Exception: when “app” is an inseparable part of the name, without which the name would be inherently nonsensical, as in [whatsapp.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/whatsapp.rb).
* Remove from the end: the string “app”, if the vendor styles the name like “Software App.app”.
* Remove from the end: version numbers or incremental release designations such as “alpha”, “beta”, or “release candidate”. Strings which distinguish different capabilities or codebases such as “Community Edition” are currently accepted. Exception: when a number is not an incremental release counter, but a differentiator for a different product from a different vendor, as in [kdiff3.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/k/kdiff3.rb).
* Exception: when “app” is an inseparable part of the name, without which the name would be inherently nonsensical, as in [whatsapp.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/whatsapp.rb).
* Remove from the end: version numbers or incremental release designations such as “alpha”, “beta”, or “release candidate”. Strings which distinguish different capabilities or codebases such as “Community Edition” are currently accepted.
* Exception: when a number is not an incremental release counter, but a differentiator for a different product from a different vendor, as in [kdiff3.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/k/kdiff3.rb).
* If the version number is arranged to occur in the middle of the App name, it should also be removed.
@ -1342,15 +1350,19 @@ Details of software names and brands will inevitably be lost in the conversion t
* Remove from the end: strings such as “Desktop”, “for Desktop”.
* Remove from the end: strings such as “Mac”, “for Mac”, “for OS X”, “macOS”, “for macOS”. These terms are generally added to ported software such as “MAME OS X.app”. Exception: when the software is not a port, and “Mac” is an inseparable part of the name, without which the name would be inherently nonsensical, as in [PlayOnMac.app](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/p/playonmac.rb).
* Remove from the end: strings such as “Mac”, “for Mac”, “for OS X”, “macOS”, “for macOS”. These terms are generally added to ported software such as “MAME OS X.app”.
* Exception: when the software is not a port, and “Mac” is an inseparable part of the name, without which the name would be inherently nonsensical, as in [PlayOnMac.app](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/p/playonmac.rb).
* Remove from the end: hardware designations such as “for x86”, “32-bit”, “ARM”.
* Remove from the end: software framework names such as “Cocoa”, “Qt”, “Gtk”, “Wx”, “Java”, “Oracle JVM”, etc. Exception: the framework is the product being casked.
* Remove from the end: software framework names such as “Cocoa”, “Qt”, “Gtk”, “Wx”, “Java”, “Oracle JVM”, etc.
* Exception: the framework is the product being casked.
* Remove from the end: localization strings such as “en-US”.
* If the result of that process is a generic term, such as “Macintosh Installer”, try prepending the name of the vendor or developer, followed by a hyphen. If that doesn’t work, then just create the best name you can, based on the vendor’s web page.
* If the result of this process is a generic term, such as “Macintosh Installer”, try prepending the name of the vendor or developer, followed by a hyphen. If that doesn’t work, then just create the best name you can, based on the vendor’s web page.
* If the result conflicts with the name of an existing cask, make yours unique by prepending the name of the vendor or developer, followed by a hyphen. Example: [unison.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/u/unison.rb) and [panic-unison.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/p/panic-unison.rb).
@ -1373,7 +1385,7 @@ Details of software names and brands will inevitably be lost in the conversion t
#### Simplified names of `pkg`-based installers
* The Simplified Name of a `pkg` may be more tricky to determine than that of an App. If a `pkg` installs an App, then use that App name with the rules above. If not, just create the best name you can, based on the vendor’s web page.
* The simplified name of a `pkg` may be more tricky to determine than that of an App. If a `pkg` installs an App, then use that App name with the rules above. If not, just create the best name you can, based on the vendor’s web page.
#### Simplified names of non-App software
@ -1383,9 +1395,9 @@ Details of software names and brands will inevitably be lost in the conversion t
### Converting the simplified name to a token
The token is the primary identifier for a package in this project. It’s the unique string users refer to when operating on the cask.
As the token is the primary identifier for casks, it’s the unique string users refer to when operating on them.
To convert the App’s Simplified Name (above) to a token:
To convert the App’s simplified name (above) to a token:
* Convert all letters to lower case.
* Expand the `+` symbol into a separated English word: `-plus-`.
@ -1397,19 +1409,19 @@ To convert the App’s Simplified Name (above) to a token:
* Digits stay digits.
* Delete any character which is not alphanumeric or a hyphen.
* Collapse a series of multiple hyphens into one hyphen.
* Delete a leading or trailing hyphen.
* Delete any leading or trailing hyphens.
### Casks pinned to specific versions
#### Casks pinned to specific versions
Casks pinned to a specific version of the application (i.e. [`carbon-copy-cloner@5`](https://github.com/Homebrew/homebrew-cask/blob/1b8f44198e5e184c597ee07454a1e10f97f36b15/Casks/c/carbon-copy-cloner%405.rb)) should use the same token as the standard cask with a suffix of `@<version-number`. For Carbon Copy Cloner (`carbon-copy-cloner`), pinned to version 5, the token should be `carbon-copy-cloner@5`.
Casks pinned to a specific version of the application (i.e. [`carbon-copy-cloner@5`](https://github.com/Homebrew/homebrew-cask/blob/1b8f44198e5e184c597ee07454a1e10f97f36b15/Casks/c/carbon-copy-cloner%405.rb)) should use the same token as the standard cask with a suffix of `@<version-number>`. For Carbon Copy Cloner (`carbon-copy-cloner`), pinned to version 5, the token should be `carbon-copy-cloner@5`.
### Casks pinned to development channels
#### Casks pinned to development channels
Casks that use an development "channel", such as betas, should use the same token as the standard cask with a suffix of `@<channel>`. For Google Chrome (`google-chrome`), using the "beta" channel, the token should be `google-chrome@beta`.
Casks that use a development "channel", such as betas, should use the same token as the standard cask with a suffix of `@<channel>`. For Google Chrome (`google-chrome`), using the "beta" channel, the token should be `google-chrome@beta`.
### Cask filenames
Casks are stored in a Ruby file named after the token, with the file extension `.rb`.
Casks are defined in a Ruby file named after the token, with the file extension `.rb`.
### Cask headers
@ -1420,7 +1432,7 @@ The token is also given in the header line for each cask.
These illustrate most of the rules for generating a token:
| App Name on Disk | Simplified App Name | Cask Token | Filename |
|------------------------|---------------------|------------------|----------------------|
| ---------------------- | ------------------- | ---------------- | -------- |
| `Audio Hijack Pro.app` | Audio Hijack Pro | audio-hijack-pro | `audio-hijack-pro.rb` |
| `VLC.app` | VLC | vlc | `vlc.rb` |
| `BetterTouchTool.app` | BetterTouchTool | bettertouchtool | `bettertouchtool.rb` |
@ -1429,11 +1441,11 @@ These illustrate most of the rules for generating a token:
For versioned/development channel casks:
| Standard Cask Token | Derivative | Cask Token | Filename |
|------------------------|---------------------|-----------------------|----------------------|
| `google-chrome` | Beta Channel | `google-chrome@beta` | `google-chrome@beta.rb` |
| `vlc` | Nightly Channel | `vlc@nightly` | `vlc@nightly.rb` |
| `carbon-copy-cloner` | Pinned to version 5 | `carbon-copy-cloner@5`| `carbon-copy-cloner@5.rb` |
| Standard Cask Token | Derivative | Cask Token | Filename |
| -------------------- | ------------------- | ---------------------- | -------- |
| `google-chrome` | Beta channel | `google-chrome@beta` | `google-chrome@beta.rb` |
| `vlc` | Nightly channel | `vlc@nightly` | `vlc@nightly.rb` |
| `carbon-copy-cloner` | Pinned to version 5 | `carbon-copy-cloner@5` | `carbon-copy-cloner@5.rb` |
### Special affixes
@ -1441,7 +1453,7 @@ A few situations require a prefix or suffix to be added to the token.
#### Token overlap
When the token for a new cask would otherwise conflict with the token of an already existing cask, the nature of that overlap dictates the token, potentially for both casks. See [Forks and Apps with Conflicting Names](Acceptable-Casks.md#forks-and-apps-with-conflicting-names) for information on how to proceed.
When the token for a new cask would otherwise conflict with the token of an already existing cask, the nature of that overlap dictates the token, potentially for both casks. See [Forks and apps with conflicting names](Acceptable-Casks.md#forks-and-apps-with-conflicting-names) for information on how to proceed.
#### Potentially misleading name