waveterm/homebrew-cask
0
0
Fork 0
mirror of https://github.com/wavetermdev/homebrew-cask.git synced 2026-08-05 13:43:24 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: move language reference to docs.brew.sh (#104628)

Browse Source 
* doc: move language reference to docs.brew.sh

* doc: reference Cask Cookbook instead of language reference
This commit is contained in:
Sean Molenaar
2021-05-04 11:30:14 +08:00
committed by GitHub
parent a90f74e998
commit 7be05ad740
36 changed files with 43 additions and 1482 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+3 -3
View File
@@ -51,9 +51,9 @@ With a bit of work, you can create a Cask for it. The document [Adding A Cask](d
Some style guidelines:
* All Casks and code should be indented using two spaces (never tabs). When `brew style` contradicts this, `style` must be followed.
* There should not be any extraneous comments - the only comments that should be used are the ones explicitly defined in the [Cask Language Reference](doc/cask_language_reference).
* The stanza order and position of newlines is important to make things easier (See [Stanza order](doc/cask_language_reference/#stanza-order)).
* Use string manipulations to improve the maintainability of your Cask (See [`version` methods](doc/cask_language_reference/stanzas/version.md#version-methods)).
* There should not be any extraneous comments - the only comments that should be used are the ones explicitly defined in the [Cask Cookbook](https://docs.brew.sh/Cask-Cookbook.md).
* The stanza order and position of newlines is important to make things easier (See [Stanza order](https://docs.brew.sh/Cask-Cookbook.md#stanza-order)).
* Use string manipulations to improve the maintainability of your Cask (See [`version` methods](https://docs.brew.sh/Cask-Cookbook.md#version-methods)).
* Test your cask using `brew audit/style` (See [testing](doc/development/adding_a_cask.md#testing-your-new-cask)).
* Make one Pull Request per Cask change.
* Do not squash commits after updating a Pull Request.
README.md
+1 -1
View File
@@ -57,7 +57,7 @@ If the issue is still not solved, see the guides for common problems:
## Requests
* Issues requesting new casks will be closed. If you want a cask added to the main repositories, [submit a pull request](https://github.com/Homebrew/homebrew-cask/blob/master/CONTRIBUTING.md#adding-a-cask).
* Issues requesting new casks will be closed. If you want a cask added to the main repositories, [submit a pull request](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#adding-a-cask).
* For a feature request, [use this template](https://github.com/Homebrew/homebrew-cask/issues/new?template=02_feature_request.md).
## Questions? Wanna chat?
USAGE.md
+2 -2
View File
@@ -94,7 +94,7 @@ atom google-chrome 1password
With `--full-name` the Tap name will also be included, _e.g._: `purple/monkey/dishwasher` for the Cask `dishwasher` installed from the Tap `purple/monkey`.
Given an installed Cask, `brew list --casks {{cask_name}}` lists the staged files.
Given an installed Cask, `brew list --casks <cask_name>` lists the staged files.
Show details about a specific Cask:
@@ -155,7 +155,7 @@ $ brew install homebrew/cask-fonts/font-symbola
* `--debug`: output debug information
* `--no-binaries`: skip symlinking executable binaries into `/usr/local/bin`
* `--require-sha`: abort installation of Cask if no checksum is defined
* `--no-quarantine`: [disable Apple’s quarantining](https://github.com/Homebrew/homebrew-cask/blob/master/doc/faq/app_cant_be_opened.md) for the specific app
* `--no-quarantine`: [disable Apple’s quarantining](https://github.com/Homebrew/homebrew-cask/blob/HEAD/doc/faq/app_cant_be_opened.md) for the specific app
* `--language=<iso-language>[,<iso-language> ... ]`: changes the language of the Cask to be installed. The first matching language is used, otherwise it uses the default language of the Cask.
You can also modify the default installation locations used when issuing `brew install`:
doc/cask_language_reference/all_stanzas.md
-62
View File
@@ -1,62 +0,0 @@
# All stanzas
## Required Stanzas
Each of the following stanzas is required for every Cask.
| name | multiple occurrences allowed? | value |
| ---------- |------------------------------ | ------------------------------- |
| `version` | no | Application version.<br />See [Version Stanza Details](stanzas/version.md) for more information.
| `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`.<br />See [Checksum Stanza Details](stanzas/sha256.md) for more information.
| `url` | no | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.<br />A [comment](stanzas/url.md#when-url-and-homepage-hostnames-differ-add-a-comment) should be added if the hostnames in the `url` and `homepage` stanzas differ. Block syntax should be used for URLs that change on every visit.<br />See [URL Stanza Details](stanzas/url.md) for more information.
| `name` | yes | String providing the full and proper name defined by the vendor.<br />See [Name Stanza Details](stanzas/name.md) for more information.
| `desc` | no | One-line description of the Cask. Shows when running `brew info`.<br />See [Desc Stanza Details](stanzas/desc.md) for more information.
| `homepage` | no | Application homepage; used for the `brew home` command.
## At Least One Artifact Stanza Is Also Required
Each Cask must declare one or more *artifacts* (i.e. something to install).
| name | multiple occurrences allowed? | value |
| ------------------- |------------------------------ | ---------------------- |
| `app` | yes | Relative path to an `.app` that should be moved into the `/Applications` folder on installation.<br />See [App Stanza Details](stanzas/app.md) for more information.
| `pkg` | yes | Relative path to a `.pkg` file containing the distribution.<br />See [Pkg Stanza Details](stanzas/pkg.md) for more information.
| `binary` | yes | Relative path to a Binary that should be linked into the `$(brew --prefix)/bin` folder (typically `/usr/local/bin`) on installation.<br />See [Binary Stanza Details](stanzas/binary.md) for more information.
| `colorpicker` | yes | Relative path to a ColorPicker plugin that should be moved into the `~/Library/ColorPickers` folder on installation.
| `dictionary` | yes | Relative path to a Dictionary that should be moved into the `~/Library/Dictionaries` folder on installation.
| `font` | yes | Relative path to a Font that should be moved into the `~/Library/Fonts` folder on installation.
| `input_method` | yes | Relative path to a Input Method that should be moved into the `~/Library/Input Methods` folder on installation.
| `internet_plugin` | yes | Relative path to a Service that should be moved into the `~/Library/Internet Plug-Ins` folder on installation.
| `manpage` | yes | Relative path to a Man Page that should be linked into the respective man page folder on installation, e.g. `/usr/local/share/man/man3` for `my_app.3`.
| `prefpane` | yes | Relative path to a Preference Pane that should be moved into the `~/Library/PreferencePanes` folder on installation.
| `qlplugin` | yes | Relative path to a QuickLook Plugin that should be moved into the `~/Library/QuickLook` folder on installation.
| `mdimporter` | yes | Relative path to a Spotlight metadata importer that should be moved into the `~/Library/Spotlight` folder on installation.
| `screen_saver` | yes | Relative path to a Screen Saver that should be moved into the `~/Library/Screen Savers` folder on installation.
| `service` | yes | Relative path to a Service that should be moved into the `~/Library/Services` folder on installation.
| `audio_unit_plugin` | yes | Relative path to an Audio Unit plugin that should be moved into the `~/Library/Audio/Components` folder on installation.
| `vst_plugin` | yes | Relative path to a VST Plugin that should be moved into the `~/Library/Audio/VST` folder on installation.
| `vst3_plugin` | yes | Relative path to a VST3 Plugin that should be moved into the `~/Library/Audio/VST3` folder on installation.
| `suite` | yes | Relative path to a containing directory that should be moved into the `/Applications` folder on installation.<br />See [Suite Stanza Details](stanzas/suite.md) for more information.
| `artifact` | yes | Relative path to an arbitrary path that should be moved on installation. Must provide an absolute path as a `target` (example [alcatraz.rb](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/alcatraz.rb#L12)). This is only for unusual cases. The `app` stanza is strongly preferred when moving `.app` bundles.
| `installer` | yes | Describes an executable which must be run to complete the installation.<br />See [Installer Stanza Details](stanzas/installer.md) for more information.
| `stage_only` | no | `true`. Assert that the Cask contains no activatable artifacts.
## Optional Stanzas
| name | multiple occurrences allowed? | value |
| ---------------------- |------------------------------ | ------------------- |
| `uninstall` | yes | Procedures to uninstall a Cask. Optional unless the `pkg` stanza is used.<br />See [Uninstall Stanza Details](stanzas/uninstall.md) for more information.
| `zap` | yes | Additional procedures for a more complete uninstall, including user files and shared resources.<br />See [Zap Stanza Details](stanzas/zap.md) for more information.
| `appcast` | no | URL providing an appcast feed to find updates for this Cask.<br />See [Appcast Stanza Details](stanzas/appcast.md) for more information.
| `depends_on` | yes | List of dependencies and requirements for this Cask.<br />See [Depends_on Stanza Details](stanzas/depends_on.md) for more information.
| `conflicts_with` | yes | List of conflicts with this Cask (*not yet functional*).<br />See [Conflicts_with Stanza Details](stanzas/conflicts_with.md) for more information.
| `caveats` | yes | String or Ruby block providing the user with Cask-specific information at install time.<br />See [Caveats Stanza Details](stanzas/caveats.md) for more information.
| `livecheck` | no | Ruby block describing how to find updates for this Cask.<br />See [Livecheck Stanza Details](stanzas/livecheck.md) for more information.
| `preflight` | yes | Ruby block containing preflight install operations (needed only in very rare cases).
| `postflight` | yes | Ruby block containing postflight install operations.<br />See [Postflight Stanza Details](stanzas/flight.md) for more information.
| `uninstall_preflight` | yes | Ruby block containing preflight uninstall operations (needed only in very rare cases).
| `uninstall_postflight` | yes | Ruby block containing postflight uninstall operations.
| `language` | required | Ruby block, called with language code parameters, containing other stanzas and/or a return value.<br />See [Language Stanza Details](stanzas/language.md) for more information.
| `container nested:` | no | 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.
| `container type:` | no | Symbol to override container-type autodetect. May be one of: `:air`, `:bz2`, `:cab`, `:dmg`, `:generic_unar`, `:gzip`, `:otf`, `:pkg`, `:rar`, `:seven_zip`, `:sit`, `:tar`, `:ttf`, `:xar`, `:zip`, `:naked`. (Example: [parse.rb](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/parse.rb#L11))
| `auto_updates` | no | `true`. Assert the Cask artifacts auto-update. Use if `Check for Updates…` or similar is present in app menu, but not if it only opens a webpage and does not do the download and installation for you.
doc/cask_language_reference/readme.md
-175
View File
@@ -1,175 +0,0 @@
# Synopsis
## Casks Are Ruby Blocks
Each Cask is a Ruby block, beginning with a special header line. The Cask definition itself is always enclosed in a `do … end` block. Example:
```ruby
cask "alfred" do
version "2.7.1_387"
sha256 "a3738d0513d736918a6d71535ef3d85dd184af267c05698e49ac4c6b48f38e17"
url "https://cachefly.alfredapp.com/Alfred_#{version}.zip"
name "Alfred"
desc "Application launcher and productivity software"
homepage "https://www.alfredapp.com/"
app "Alfred 2.app"
app "Alfred 2.app/Contents/Preferences/Alfred Preferences.app"
end
```
## The Cask Language Is Declarative
Each Cask contains a series of stanzas (or “fields”) which *declare* how the software is to be obtained and installed. In a declarative language, the author does not need to worry about **order**. As long as all the needed fields are present, Homebrew Cask will figure out what needs to be done at install time.
To make maintenance easier, the most-frequently-updated stanzas are usually placed at the top. But that’s a convention, not a rule.
Exception: `do` blocks such as `postflight` may enclose a block of pure Ruby code. Lines within that block follow a procedural (order-dependent) paradigm.
## Conditional Statements
### Efficiency
Conditional statements are permitted, but only if they are very efficient.
Tests on the following values are known to be acceptable:
| value | examples
| ----------------------------|--------------------------------------
| `MacOS.version` | [coconutbattery.rb](https://github.com/Homebrew/homebrew-cask/blob/a11ee55e8ed8255f7dab77120dfb1fb955789559/Casks/coconutbattery.rb#L2-L16), [yasu.rb](https://github.com/Homebrew/homebrew-cask/blob/21d3f7ac8a4adac0fe474b3d4b020d284eeef88d/Casks/yasu.rb#L2-L23)
### Version Comparisons
Tests against `MacOS.version` may use either symbolic names or version
strings with numeric comparison operators:
```ruby
if MacOS.version <= :mojave # symbolic name
```
```ruby
if MacOS.version <= "10.14" # version string
```
The available symbols for macOS versions are: `:yosemite`, `:el_capitan`, `:sierra`, `:high_sierra`, `:mojave`, `:catalina` and `:big_sur`. The corresponding numeric version strings should be given as major releases containing a single dot.
Note that in the official Homebrew Cask repositories only the symbolic names are allowed. The numeric comparison may only be used for third-party taps.
### Always Fall Through to the Newest Case
Conditionals should be constructed so that the default is the newest OS version. When using an `if` statement, test for older versions, and then let the `else` statement hold the latest and greatest. This makes it more likely that the Cask will work without alteration when a new OS is released. Example (from [coconutbattery.rb](https://github.com/Homebrew/homebrew-cask/blob/2c801af44be29fff7f3cb2996455fce5dd95d1cc/Casks/coconutbattery.rb)):
```ruby
if MacOS.version <= :sierra
# ...
elsif MacOS.version <= :mojave
# ...
else
# ...
end
```
### Switch Between Languages or Regions
If a cask is available in multiple languages, you can use the `language` stanza to switch between languages or regions based on the system locale.
## Arbitrary Ruby Methods
In the exceptional case that the Cask DSL is insufficient, it is possible to define arbitrary Ruby variables and methods inside the Cask by creating a `Utils` namespace. Example:
```ruby
cask "myapp" do
module Utils
def self.arbitrary_method
...
end
end
name "MyApp"
version "1.0"
sha256 "a32565cdb1673f4071593d4cc9e1c26bc884218b62fef8abc450daa47ba8fa92"
url "https://#{Utils.arbitrary_method}"
homepage "https://www.example.com/"
...
end
```
This should be used sparingly: any method which is needed by two or more Casks should instead be rolled into the core. Care must also be taken that such methods be very efficient.
Variables and methods should not be defined outside the `Utils` namespace, as they may collide with Homebrew Cask internals.
## Header Line Details
The first non-comment line in a Cask follows the form:
```ruby
cask "<cask-token>" do
```
[`<cask-token>`](token_reference.md) should match the Cask filename, without the `.rb` extension,
enclosed in single quotes.
There are currently some arbitrary limitations on Cask tokens which are in the process of being removed. The Travis bot will catch any errors during the transition.
## Stanza order
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 delineate information.
```
version
sha256
language
url
appcast
name
desc
homepage
livecheck
auto_updates
conflicts_with
depends_on
container
suite
app
pkg
installer
binary
manpage
colorpicker
dictionary
font
input_method
internet_plugin
prefpane
qlplugin
mdimporter
screen_saver
service
audio_unit_plugin
vst_plugin
vst3_plugin
artifact, target: # target: shown here as is required with `artifact`
stage_only
preflight
postflight
uninstall_preflight
uninstall_postflight
uninstall
zap
caveats
```
Note that every stanza that has additional parameters (`:symbols` after a `,`) shall have them on separate lines, one per line, in alphabetical order. An exception is `target:` which typically consists of short lines.
doc/cask_language_reference/stanzas/app.md
-37
View File
@@ -1,37 +0,0 @@
# app
In the simple case of a string argument to `app`, the source file is moved to the target `/Applications` directory. For example:
```ruby
app "Alfred 2.app"
```
by default moves the source to:
```bash
/Applications/Alfred 2.app
```
## Renaming the Target
You can rename the target which appears in your `/Applications` directory by adding a `target:` key to `app`. Example (from [scala-ide.rb](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/scala-ide.rb#L21)):
```ruby
app "eclipse/Eclipse.app", target: "Scala IDE.app"
```
## target: May Contain an Absolute Path
If `target:` has a leading slash, it is interpreted as an absolute path. The containing directory for the absolute path will be created if it does not already exist. Example (from [manopen.rb](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/manopen.rb#L12)):
```ruby
artifact "openman.1", target: "/usr/local/share/man/man1/openman.1"
```
## target: Works on Most Artifact Types
The `target:` key works similarly for most Cask artifacts, such as `app`, `binary`, `colorpicker`, `dictionary`, `font`, `input_method`, `prefpane`, `qlplugin`, `mdimporter`, `service`, `suite`, and `artifact`.
## target: Should Only Be Used in Select Cases
Don’t use `target:` for aesthetic reasons, like removing version numbers (`app "Slack #{version}.app", target: "Slack.app"`). Use it when it makes sense functionally and document your reason clearly in the Cask, using one of the templates: [for clarity](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/imagemin.rb#L12); [for consistency](https://github.com/Homebrew/homebrew-cask/blob/d2a6b26df69fc28c4d84d6f5198b2b652c2f414d/Casks/devonthink-pro-office.rb#L16); [to prevent conflicts](https://github.com/Homebrew/homebrew-cask/blob/bd6dc1a64e0bdd35ba0e20789045ea023b0b6aed/Casks/flash-player-debugger.rb#L11); [due to developer suggestion](https://github.com/Homebrew/homebrew-cask/blob/ff3e9c4a6623af44b8a071027e8dcf3f4edfc6d9/Casks/kivy.rb#L12).
doc/cask_language_reference/stanzas/appcast.md
-35
View File
@@ -1,35 +0,0 @@
# appcast
The value of the `appcast` stanza is a string, holding the URL for an appcast which provides information on future updates.
Note: The [`livecheck` stanza](livecheck.md) should be preferred in most cases, as it allows casks to be updated automatically.
The main casks repo only accepts submissions for stable versions of software (and [documented exceptions](https://github.com/Homebrew/homebrew-cask/blob/master/doc/development/adding_a_cask.md#but-there-is-no-stable-version)), but it still gets pull requests for unstable versions. By checking the submitted `version` against the contents of an appcast, we can better detect these invalid cases.
Example: [`atom.rb`](https://github.com/Homebrew/homebrew-cask/blob/645dbb8228ec2f1f217ed1431e188687aac13ca5/Casks/atom.rb#L7)
There are a few different ways the `appcast` can be determined:
* If the app is distributed via GitHub releases, the `appcast` will be of the form `https://github.com/{{user}}/{{project_name}}/releases.atom`. Example: [`electron.rb`](https://github.com/Homebrew/homebrew-cask/blob/645dbb8228ec2f1f217ed1431e188687aac13ca5/Casks/electron.rb#L7)
* If the app is distributed via GitLab releases, the `appcast` will be of the form `https://gitlab.com/{{user}}/{{project_name}}/-/tags?format=atom`. Example: [`grafx.rb`](https://github.com/Homebrew/homebrew-cask/blob/b22381902f9da870bb07d21b496558f283dad612/Casks/grafx.rb#L6)
* The popular update framework [Sparkle](https://sparkle-project.org/) generally uses the `SUFeedURL` property in `Contents/Info.plist` inside `.app` bundles. Example: [`glyphs.rb`](https://github.com/Homebrew/homebrew-cask/blob/645dbb8228ec2f1f217ed1431e188687aac13ca5/Casks/glyphs.rb#L6)
* Sourceforge projects follow the form `https://sourceforge.net/projects/{{project_name}}/rss`. A more specific page can be used as needed, pointing to a specific directory structure: `https://sourceforge.net/projects/{{project_name}}/rss?path=/{{path_here}}`. Example: [`seashore.rb`](https://github.com/Homebrew/homebrew-cask/blob/645dbb8228ec2f1f217ed1431e188687aac13ca5/Casks/seashore.rb#L6)
* An appcast can be any URL hosted by the app’s developer that changes every time a new release is out or that contains the version number of the current release (e.g. a download HTML page). Webpages that only change on new version releases are preferred, as are sites that do not contain previous version strings (i.e. avoid changelog pages if the download page contains the current version number but not older ones). Example: [`razorsql.rb`](https://github.com/Homebrew/homebrew-cask/blob/645dbb8228ec2f1f217ed1431e188687aac13ca5/Casks/razorsql.rb#L6)
The [`find-appcast`](https://github.com/Homebrew/homebrew-cask/blob/master/developer/bin/find-appcast) script is able to identify some of these, as well as `electron-builder` appcasts which are trickier to find by hand. Run it with `"$(brew --repository)/Library/Taps/homebrew/homebrew-cask/developer/bin/find-appcast" '{{/path/to/software.app}}'`.
## Parameters
| key | value |
| --------------- | ----------- |
| `must_contain:` | a custom string for `brew audit --appcast {{cask_file}}` to check against. |
Sometimes a `version` doesn’t match a string on the webpage, in which case we tweak what to search for. Example: if `version` is `6.26.1440` and the appcast’s contents only show `6.24`, the check for “is `version` in the appcast feed” will fail. With `must_contain`, the check is told to “look for this string instead of `version`”. In the example, `must_contain: version.major_minor` is saying “look for `6.24`”, making the check succeed.
If no `must_contain` is given, the check considers from the beginning of the `version` string until the first character that isn’t alphanumeric or a period. Example: if `version` is `6.26b-14,40`, the check will see `6.26b`. This is so it covers most cases by default, while still allowing complex `version`s suitable for interpolation on the rest of the cask.
Example of using `must_contain`: [`hwsensors.rb`](https://github.com/Homebrew/homebrew-cask/blob/87bc3860f43d5b14d0c38ae8de469d24ee7f5b2f/Casks/hwsensors.rb#L6L7)
doc/cask_language_reference/stanzas/binary.md
-34
View File
@@ -1,34 +0,0 @@
# binary
In the simple case of a string argument to `binary`, the source file is linked into the `$(brew --prefix)/bin` directory (typically `/usr/local/bin`) on installation. For example (from [operadriver.rb](https://github.com/Homebrew/homebrew-cask/blob/60531a2812005dd5f17dc92f3ce7419af3c5d019/Casks/operadriver.rb#L11)):
```ruby
binary "operadriver"
```
creates a symlink to:
```bash
$(brew --prefix)/bin/operadriver
```
from a source file such as:
```bash
/usr/local/Caskroom/operadriver/0.2.2/operadriver
```
A binary (or multiple) can also be contained in an application bundle:
```ruby
app "Atom.app"
binary "#{appdir}/Atom.app/Contents/Resources/app/apm/bin/apm"
```
You can rename the target which appears in your binaries directory by adding a `target:` key to `binary`:
```ruby
binary "#{appdir}/Atom.app/Contents/Resources/app/atom.sh", target: "atom"
```
Behaviour and usage of `target:` is [the same as with `app`](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/stanzas/app.md#renaming-the-target). However, for `binary` the select cases don’t apply as rigidly. It’s fine to take extra liberties with `target:` to be consistent with other command-line tools, like [changing case](https://github.com/Homebrew/homebrew-cask/blob/9ad93b833961f1d969505bc6bdb1c2ad4e58a433/Casks/openscad.rb#L12), [removing an extension](https://github.com/Homebrew/homebrew-cask/blob/c443d4f5c6864538efe5bb1ecf662565a5ffb438/Casks/filebot.rb#L13), or [cleaning up the name](https://github.com/Homebrew/homebrew-cask/blob/146917cbcc679648de6b0bccff4e9b43fce0e6c8/Casks/minishift.rb#L13).
doc/cask_language_reference/stanzas/caveats.md
-55
View File
@@ -1,55 +0,0 @@
# caveats
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.
## caveats as a String
When `caveats` is a string, it is evaluated at compile time. The following methods are available for interpolation if `caveats` is placed in its customary position at the end of the Cask:
| method | description |
| ------------------ | ----------- |
| `token` | the Cask token
| `version` | the Cask version
| `homepage` | the Cask homepage
| `caskroom_path` | the containing directory for all staged Casks, typically `/usr/local/Caskroom` (only available with block form)
| `staged_path` | the staged location for this Cask, including version number: `/usr/local/Caskroom/{{token}}/{{version}}` (only available with block form)
Example:
```ruby
caveats "Using #{token} is hazardous to your health."
```
## caveats as a Block
When `caveats` is a Ruby block, evaluation is deferred until install time. Within a block you may refer to the `@cask` instance variable, and invoke any method available on `@cask`.
## 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 |
| ---------------------------------- | ----------- |
| `path_environment_variable "path"` | users should make sure `path` is in their `$PATH` environment variable.
| `zsh_path_helper "path"` | zsh users must take additional steps to make sure `path` is in their `$PATH` environment variable.
| `depends_on_java "version"` | users should make sure they have the specified version of java installed. `version` can be exact (e.g. `6`), a minimum (e.g. `7+`), or omitted (when any version works).
| `logout` | users should log out and log back in to complete installation.
| `reboot` | users should reboot to complete installation.
| `files_in_usr_local` | the Cask installs files to `/usr/local`, which may confuse Homebrew.
| `discontinued` | all software development has been officially discontinued upstream.
| `free_license "web_page"` | users may get an official license to use the software at `web_page`.
| `kext` | users may need to enable their kexts in System Preferences → Security & Privacy → General.
| `unsigned_accessibility` | users will need to re-enable the app on each update in System Preferences → Security & Privacy → Privacy as it is unsigned.
| `license "web_page"` | software has a usage license at `web_page`.
Example:
```ruby
caveats do
path_environment_variable "/usr/texbin"
end
```
doc/cask_language_reference/stanzas/conflicts_with.md
-25
View File
@@ -1,25 +0,0 @@
# conflicts_with
`conflicts_with` is used to declare conflicts that keep a Cask from installing or working correctly.
## conflicts_with cask:
The value should be another Cask token.
Example use: [`wireshark`](https://github.com/Homebrew/homebrew-cask/blob/903493e09cf33b845e7cf497ecf9cfc9709087ee/Casks/wireshark.rb#L10), which conflicts with `wireshark-chmodbpf`.
```ruby
conflicts_with cask: "wireshark-chmodbpf"
```
## conflicts_with formula:
Note: `conflicts_with formula:` is a stub and is not yet functional.
The value should be another formula name.
Example use: [`macvim`](https://github.com/Homebrew/homebrew-cask/blob/84b90afd7b571e581f8a48d4bdf9c7bb24ebff3b/Casks/macvim.rb#L10), which conflicts with the `macvim` formula.
```ruby
conflicts_with formula: "macvim"
```
doc/cask_language_reference/stanzas/depends_on.md
-93
View File
@@ -1,93 +0,0 @@
# depends_on
`depends_on` is used to declare dependencies and requirements for a Cask.
`depends_on` is not consulted until `install` is attempted.
## depends_on cask:
The value should be another Cask token, needed by the current Cask.
Example use: [`cellery`](https://github.com/Homebrew/homebrew-cask/blob/4002df8f6bca93ed6eb40494995fcfa038cf99bf/Casks/cellery.rb#L11) depends on OSXFUSE:
```ruby
depends_on cask: "osxfuse"
```
## depends_on formula:
The value should name a Homebrew Formula needed by the Cask.
Example use: 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 Homebrew Formula `unar`:
```ruby
depends_on formula: "unar"
```
## depends_on macos:
### 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:
| symbol | corresponding release
| -------------------|----------------------
| `:yosemite` | `10.10`
| `:el_capitan` | `10.11`
| `:sierra` | `10.12`
| `:high_sierra` | `10.13`
| `:mojave` | `10.14`
| `:catalina` | `10.15`
| `:big_sur` | `11.0`
Only major releases are covered (version numbers containing a single dot). The symbol form is used for readability. The following are all valid ways to enumerate the exact macOS release requirements for a Cask:
```ruby
depends_on macos: :big_sur
depends_on macos: [
:catalina,
:big_sur,
]
```
### 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)”:
```ruby
depends_on macos: ">= :big_sur"
```
A comparison expression cannot be combined with any other form of `depends_on macos:`.
## 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:` value matches the user’s hardware.
The available symbols for hardware are:
| symbol | meaning |
| ---------- | -------------- |
| `:x86_64` | 64-bit Intel |
| `:intel` | 64-bit Intel |
The following are all valid expressions:
```ruby
depends_on arch: :intel
depends_on arch: :x86_64 # same meaning as above
depends_on arch: [:x86_64] # same meaning as above
```
Since as of now all the macOS versions we support only run on 64-bit Intel, `depends_on arch:` is never necessary.
## All depends_on Keys
| key | description |
| ---------- | ----------- |
| `formula:` | a Homebrew Formula
| `cask:` | a Cask token
| `macos:` | a symbol, string, array, or comparison expression defining macOS release requirements
| `arch:` | a symbol or array defining hardware requirements
| `java:` | *stub - not yet functional*
doc/cask_language_reference/stanzas/desc.md
-64
View File
@@ -1,64 +0,0 @@
# 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` 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 the 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.
## Dos and Don'ts
- **Do** start with an uppercase letter.
```diff
- desc "sound and music editor"
+ desc "Sound and music editor"
```
- **Do** be brief, i.e. use less than 80 characters.
```diff
- desc "Sound and music editor which comes with effects, instruments, sounds and all kinds of creative features"
+ desc "Sound and music editor"
```
- **Do** describe what the software does or is:
```diff
- desc "Development of musical ideas made easy"
+ desc "Sound and music editor"
```
- **Do not** include the platform. Casks only work on macOS, so this is redundant information.
```diff
- desc "Sound and music editor for macOS"
+ desc "Sound and music editor"
```
- **Do not** include the Cask’s [name](name.md).
```diff
- desc "Ableton Live is a sound and music editor"
+ desc "Sound and music editor"
```
- **Do not** include the vendor. This should be added to the Cask’s [name](name.md) instead.
```diff
- desc "Sound and music editor made by Ableton"
+ desc "Sound and music editor"
```
- **Do not** add user pronouns.
```diff
- desc "Edit your music files"
+ desc "Sound and music editor"
```
- **Do not** use empty marketing jargon.
```diff
- desc "Beautiful and powerful modern sound and music editor"
+ desc "Sound and music editor"
```
doc/cask_language_reference/stanzas/flight.md
-18
View File
@@ -1,18 +0,0 @@
# \*flight
## Evaluation of Blocks is Always Deferred
The Ruby blocks defined by `preflight`, `postflight`, `uninstall_preflight`, and `uninstall_postflight` are not evaluated until install time or uninstall time. Within a block, you may refer to the `@cask` instance variable, and invoke any method available on `@cask`.
## \*flight Mini-DSL
There is a mini-DSL available within these blocks.
The following methods may be called to perform standard tasks:
| method | availability | description |
| ----------------------------------------- | ------------------------------------------------ | ----------- |
| `set_ownership(paths)` | `preflight`, `postflight`, `uninstall_preflight` | set user and group ownership of `paths`. Example: [`unifi-controller.rb`](https://github.com/Homebrew/homebrew-cask/blob/8a452a41707af6a661049da6254571090fac5418/Casks/unifi-controller.rb#L13)
| `set_permissions(paths, permissions_str)` | `preflight`, `postflight`, `uninstall_preflight` | set permissions in `paths` to `permissions_str`. Example: [`docker-machine.rb`](https://github.com/Homebrew/homebrew-cask/blob/8a452a41707af6a661049da6254571090fac5418/Casks/docker-machine.rb#L16)
`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')`.
doc/cask_language_reference/stanzas/installer.md
-40
View File
@@ -1,40 +0,0 @@
# installer
This stanza must always be accompanied by [`uninstall`](uninstall.md).
The `installer` stanza takes a series of key-value pairs, the first key of which must be `manual:` or `script:`.
## 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 [nutstore.rb](https://github.com/Homebrew/homebrew-cask/blob/249ec31048591308e63e50f79dae01d2f933cccf/Casks/nutstore.rb#L9)):
```ruby
installer manual: "Nutstore 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:`:
| key | value
| ----------------|------------------------------
| `executable:` | path to an install script to be run
| `args:` | array of arguments to the install 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
| `sudo:` | set to `true` if the script needs `sudo`
The path may be absolute, or relative to the Cask. Example (from [miniforge.rb](https://github.com/Homebrew/homebrew-cask/blob/ed2033fb3578376c3ee58a2cb459ef96fa6eb37d/Casks/miniforge.rb#L15L18)):
```ruby
installer script: {
executable: "Miniforge3-#{version}-MacOSX-x86_64.sh",
args: ["-b", "-p", "#{caskroom_path}/base"],
}
```
If the `installer script:` does not require any of the key-values it can point directly to the path of the install script:
```ruby
installer script: "#{staged_path}/install.sh"
```
doc/cask_language_reference/stanzas/language.md
-52
View File
@@ -1,52 +0,0 @@
# language
The `language` stanza can match [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) language codes, regional identifiers ([ISO 3166-1 Alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)) and script codes ([ISO 15924](https://en.wikipedia.org/wiki/ISO_15924)), or a combination thereof.
US English should always be used as the default language:
```ruby
language "zh", "CN" do
"zh_CN"
end
language "de" do
"de_DE"
end
language "en-GB" do
"en_GB"
end
language "en", default: true do
"en_US"
end
```
Note that the following are not the same:
```ruby
language "en", "GB" do
# matches all locales containing "en" or "GB"
end
language "en-GB" do
# matches only locales containing "en" and "GB"
end
```
The return value of the matching `language` block can be accessed by simply calling `language`.
```ruby
homepage "https://example.org/#{language}"
```
Examples: [Firefox](https://github.com/Homebrew/homebrew-cask/blob/306b8fbd9502036f1ca742f70c569d8677b62403/Casks/firefox.rb#L4L74), [Battle.net](https://github.com/Homebrew/homebrew-cask/blob/306b8fbd9502036f1ca742f70c569d8677b62403/Casks/battle-net.rb#L5L17)
## Installation
To install a cask in a specific language, you can pass the `--language=` option to `brew install`:
```
brew install firefox --language=it
```
doc/cask_language_reference/stanzas/livecheck.md
-60
View File
@@ -1,60 +0,0 @@
# `livecheck`
The `livecheck` stanza is used to automatically fetch the latest version of a cask from changelogs, release notes, appcasts, etc.
Every `livecheck` block must contain a `url`, which can either be a string or a symbol pointing to other URLs in the cask (`:url` or `:homepage`).
Additionally, a `livecheck` should specify which `strategy` should be used to extract the version:
| `strategy` | Description |
|-----------------|-----------|
| `:header_match` | extract version from HTTP headers (e.g. `Location` or `Content-Disposition`) |
| `:page_match` | extract version from page contents |
| `:sparkle` | extract version from Sparkle appcast contents |
Here is a basic example, extracting a simple version from a page:
```ruby
livecheck do
url "https://example.org/my-app/download"
strategy :page_match
regex(%r{href=.*?/MyApp-(\d+(?:\.\d+)*)\.zip}i)
end
```
If the download URL is present on the homepage, we can use a symbol instead of a string:
```ruby
livecheck do
url :homepage
strategy :page_match
regex(%r{href=.*?/MyApp-(\d+(?:\.\d+)*)\.zip}i)
end
```
The `header_match` strategy will try parsing a version from the filename (in the `Content-Disposition` header) and the final URL (in the `Location` header). If that doesn't work, a `regex` can be specified, e.g.:
```ruby
strategy :header_match
regex(/MyApp-(\d+(?:\.\d+)*)\.zip/i)
```
If the version depends on multiple header fields, a block can be specified, e.g.
```ruby
strategy :header_match do |headers|
v = headers["content-disposition"][/MyApp-(\d+(?:\.\d+)*)\.zip/i, 1]
id = headers["location"][%r{/(\d+)/download$}i, 1]
"#{v},#{id}"
end
```
Similarly, the `:page_match` strategy can also be used for more complex versions by specifying a block:
```ruby
strategy :page_match do |page|
match = page.match(%r{href=.*?/(\d+)/MyApp-(\d+(?:\.\d+)*)\.zip}i)
"#{match[2]},#{match[1]}"
end
```
doc/cask_language_reference/stanzas/name.md
-9
View File
@@ -1,9 +0,0 @@
# name
`name` accepts a UTF-8 string defining the name of the software, including capitalization and punctuation. It is used to help with searchability and disambiguation.
Unlike the [token](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/token_reference.md), which is simplified and reduced to a limited set of characters, the `name` stanza can include the proper capitalization, spacing and punctuation to match the official name of the software. For disambiguation purposes, it is recommended to spell out the name of the application, and including the vendor name if necessary. A good example is [`pycharm-ce`](https://github.com/Homebrew/homebrew-cask/blob/fc05c0353aebb28e40db72faba04b82ca832d11a/Casks/pycharm-ce.rb#L6-L7), whose name is spelled out as `Jetbrains PyCharm Community Edition`, even though it is likely never referenced as such anywhere.
Additional details about the software can be provided in the [desc](desc.md) stanza.
The `name` stanza can be repeated multiple times if there are useful alternative names. The first instance should use the Latin alphabet. For example, see the [`cave-story`](https://github.com/Homebrew/homebrew-cask/blob/0fe48607f5656e4f1de58c6884945378b7e6f960/Casks/cave-story.rb#L7-L9) cask, whose original name does not use the Latin alphabet.
doc/cask_language_reference/stanzas/pkg.md
-71
View File
@@ -1,71 +0,0 @@
# pkg
This stanza must always be accompanied by [`uninstall`](uninstall.md)
The first argument to the `pkg` stanza should be a relative path to the `.pkg` file to be installed. For example:
```ruby
pkg "Unity.pkg"
```
Subsequent arguments to `pkg` are key/value pairs which modify the install process. Currently supported keys are `allow_untrusted:` and `choices:`.
## `pkg allow_untrusted:`
`pkg allow_untrusted: true` can be used to install the `.pkg` with an untrusted certificate passing `-allowUntrusted` to `/usr/sbin/installer`.
This option is not permitted in official Homebrew Cask taps, it is only provided for use in third-party taps or local Casks.
Example ([alinof-timer.rb](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/alinof-timer.rb#L10)):
```ruby
pkg "AlinofTimer.pkg", allow_untrusted: true
```
## `pkg choices:`
`pkg choices:` can be used to override `.pkg`’s default install options via `-applyChoiceChangesXML`. It uses a deserialized version of the `choiceChanges` property list (refer to the `CHOICE CHANGES FILE` section of the `installer` manual page by running `man -P 'less --pattern "^CHOICE CHANGES FILE"' installer`).
Running the macOS command:
```bash
$ installer -showChoicesXML -pkg '/path/to/my.pkg'
```
will output an XML which you can use to extract the `choices:` values, as well as their equivalents to the GUI options.
See [this pull request for wireshark-chmodbpf](https://github.com/Homebrew/homebrew-cask/pull/26997) and [this one for wine-staging](https://github.com/Homebrew/homebrew-cask/pull/27937) for some examples of the procedure.
Example ([wireshark-chmodbpf.rb](https://github.com/Homebrew/homebrew-cask/blob/f95b8a8306b91fe9da7908b842f4a5fa80f7afe0/Casks/wireshark-chmodbpf.rb#L9-L26)):
```ruby
pkg "Wireshark #{version} Intel 64.pkg",
choices: [
{
"choiceIdentifier" => "wireshark",
"choiceAttribute" => "selected",
"attributeSetting" => 0,
},
{
"choiceIdentifier" => "chmodbpf",
"choiceAttribute" => "selected",
"attributeSetting" => 1,
},
{
"choiceIdentifier" => "cli",
"choiceAttribute" => "selected",
"attributeSetting" => 0,
},
]
```
Example ([wine-staging.rb](https://github.com/Homebrew/homebrew-cask/blob/51b65f6a5a25a7f79af4d372e1a0bf1dc3849251/Casks/wine-staging.rb#L11-L18)):
```ruby
pkg "winehq-staging-#{version}.pkg",
choices: [
{
"choiceIdentifier" => "choice3",
"choiceAttribute" => "selected",
"attributeSetting" => 1,
},
]
```
doc/cask_language_reference/stanzas/sha256.md
-17
View File
@@ -1,17 +0,0 @@
# sha256
## Calculating the SHA256
The `sha256` value is usually calculated by the command:
```bash
$ 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.
`version :latest` requires `sha256 :no_check`, and this pairing is common. However, `sha256 :no_check` does not require `version :latest`.
We use a checksum whenever possible.
doc/cask_language_reference/stanzas/suite.md
-11
View File
@@ -1,11 +0,0 @@
# suite
Some distributions provide a suite of multiple applications, or an application with required data, to be installed together in a subdirectory of `/Applications`.
For these Casks, use the `suite` stanza to define the directory containing the application suite. Example (from [sketchup.rb](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/sketchup.rb#L12)):
```ruby
suite "SketchUp 2016"
```
The value of `suite` is never an `.app` bundle, but a plain directory.

Some files were not shown because too many files have changed in this diff Show More