docs: update documentation

This commit is contained in:
Razvan Azamfirei 2023-12-15 15:34:58 -05:00
parent ae1c058f9b
commit cbe2c1d5c5
No known key found for this signature in database
GPG Key ID: 62E97BFCB12046BD
3 changed files with 96 additions and 54 deletions

View File

@ -99,24 +99,24 @@ Before submitting a cask to any of our repositories, you must read our [document
Common reasons to reject a cask entirely:
* We have strong reasons to believe including the cask can put the whole project at risk. Happened only once so far, [with Popcorn Time](https://github.com/Homebrew/homebrew-cask/pull/3954).
* Cask is unreasonably difficult to maintain. Examples have included [Audacity](https://github.com/Homebrew/homebrew-cask/pull/27517) and [older Java development casks](https://github.com/Homebrew/homebrew-cask/issues/57387).
* App is a trial version, and the only way to acquire the full version is through the Mac App Store.
* Similarly (and trickier to spot), the app has moved to the Mac App Store but still provides old versions via direct download. We reject these in all official repositories so users dont get stuck using an old version, wrongly thinking theyre using the most up-to-date one (which, amongst other things, might be a security risk).
* App is both open-source and CLI-only (i.e. it only uses the `binary` artifact). In that case, and [in the spirit of deduplication](https://github.com/Homebrew/homebrew-cask/issues/15603), submit it first to [homebrew/core](https://github.com/Homebrew/homebrew-core) as a formula that builds from source. If it is rejected, you may then try again as a cask (link to the issue from your pull request so we can see the discussion and reasoning for rejection).
* App is open-source and has a GUI but no compiled versions (or only old ones) are provided. Its better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users dont get perpetually outdated versions. See [`gedit`](https://github.com/Homebrew/homebrew-cask/pull/23360) for example.
* Cask has been rejected before due to an issue we cannot fix, and the new submission doesnt fix that. An example would be the [first submission of `soapui`](https://github.com/Homebrew/homebrew-cask/pull/4939), whose installation problems were not fixed in the two [subsequent](https://github.com/Homebrew/homebrew-cask/pull/9969) [submissions](https://github.com/Homebrew/homebrew-cask/pull/10606).
* Cask is a duplicate. These submissions mostly occur when the [token reference](https://docs.brew.sh/Cask-Cookbook#token-reference) was not followed.
* Cask has a download URL that is both behind a login/registration form and from a host that differs from the homepage, meaning users cant easily verify its authenticity.
* App is unmaintained, i.e. no releases in the last year, or [explicitly discontinued](https://github.com/Homebrew/homebrew-cask/pull/22699).
* App fails with GateKeeper enabled on Homebrew supported macOS versions and platforms (e.g. unsigned apps fail on Macs with Apple silicon/ARM).
* App is too obscure. Examples:
* An app from a code repository that is not notable enough (under 30 forks, 30 watchers, 75 stars).
* [Electronic Identification (eID) software](https://github.com/Homebrew/homebrew-cask/issues/59021).
* App has no information on its homepage (example: a GitHub repository without a README).
* The author has [specifically asked us not to include it](https://github.com/Homebrew/homebrew-cask/pull/5342).
* App requires [SIP to be disabled](https://github.com/Homebrew/homebrew-cask/pull/41890) to be installed and/or used.
* App installer is a `pkg` that requires [`allow_untrusted: true`](https://docs.brew.sh/Cask-Cookbook#pkg-allow_untrusted).
* App fails with GateKeeper enabled on Homebrew supported macOS versions and platforms (e.g. unsigned apps fail on Macs with Apple silicon/ARM).
* App is a trial version, and the only way to acquire the full version is through the Mac App Store.
* Similarly (and trickier to spot), the app has moved to the Mac App Store but still provides old versions via direct download. We reject these in all official repositories so users dont get stuck using an old version, wrongly thinking theyre using the most up-to-date one (which, amongst other things, might be a security risk).
* App is unmaintained, i.e. no releases in the last year, or [explicitly discontinued](https://github.com/Homebrew/homebrew-cask/pull/22699).
* App has no information on its homepage (example: a GitHub repository without a README).
* Cask has a download URL that is both behind a login/registration form and from a host that differs from the homepage, meaning users cant easily verify its authenticity.
* Cask is unreasonably difficult to maintain. Examples have included [Audacity](https://github.com/Homebrew/homebrew-cask/pull/27517) and [older Java development casks](https://github.com/Homebrew/homebrew-cask/issues/57387).
* Cask has been rejected before due to an issue we cannot fix, and the new submission doesnt fix that. An example would be the [first submission of `soapui`](https://github.com/Homebrew/homebrew-cask/pull/4939), whose installation problems were not fixed in the two [subsequent](https://github.com/Homebrew/homebrew-cask/pull/9969) [submissions](https://github.com/Homebrew/homebrew-cask/pull/10606).
* Cask is a duplicate. These submissions mostly occur when the [token reference](https://docs.brew.sh/Cask-Cookbook#token-reference) was not followed.
* The author has [specifically asked us not to include it](https://github.com/Homebrew/homebrew-cask/pull/5342).
* App is both open-source and CLI-only (i.e. it only uses the `binary` artifact). In that case, and [in the spirit of deduplication](https://github.com/Homebrew/homebrew-cask/issues/15603), submit it first to [homebrew/core](https://github.com/Homebrew/homebrew-core) as a formula that builds from source. If it is rejected, you may then try again as a cask (link to the issue from your pull request so we can see the discussion and reasoning for rejection).
* App is open-source and has a GUI but no compiled versions (or only old ones) are provided. Its better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users dont get perpetually outdated versions. See [`gedit`](https://github.com/Homebrew/homebrew-cask/pull/23360) for example.
* We have strong reasons to believe including the cask can put the whole project at risk. Happened only once so far, [with Popcorn Time](https://github.com/Homebrew/homebrew-cask/pull/3954).
Common reasons to reject a cask from the main `homebrew/cask` repository:

View File

@ -51,70 +51,97 @@ Making a new cask is easy. Follow the directions in [How to Open a Homebrew Pull
#### Examples
Heres a cask for `shuttle` as an example. Note the `verified` parameter below the `url`, which is needed when [the url and homepage hostnames differ](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified).
Heres a cask for `dixa` as an example. Note the `verified` parameter below the `url`, which is needed when [the url and homepage hostnames differ](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified).
```ruby
cask "shuttle" do
version "1.2.9"
sha256 "0b80bf62922291da391098f979683e69cc7b65c4bdb986a431e3f1d9175fba20"
cask "dixa" do
version "4.0.12"
sha256 "a4e1a30d074e724ba24e9e2674a72bc4050f00161fb7dc23295a2c189ecda5bb"
url "https://github.com/fitztrev/shuttle/releases/download/v#{version}/Shuttle.zip",
verified: "github.com/fitztrev/shuttle/"
name "Shuttle"
desc "Simple shortcut menu"
homepage "https://fitztrev.github.io/shuttle/"
url "https://github.com/dixahq/dixa-desktop-app-release/releases/download/v#{version}/dixa-#{version}.dmg",
verified: "github.com/dixahq/dixa-desktop-app-release/"
name "Dixa"
desc "Customer service platform"
homepage "https://dixa.com/"
app "Shuttle.app"
livecheck do
url :url
strategy :github_latest
end
zap trash: "~/.shuttle.json"
app "Dixa.app"
zap trash: [
"~/Library/Application Support/Dixa",
"~/Library/Logs/Dixa",
"~/Library/Preferences/dixa.plist",
"~/Library/Saved Application State/dixa.savedState",
]
end
```
And here is one for `noisy`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check`, which is necessary because since the download `url` does not contain the version number, its checksum will change when a new version is made available.
And here is one for `pomello`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check`, which is necessary because since the download `url` does not contain the version number, its checksum will change when a new version is made available.
```ruby
cask "noisy" do
version "1.3"
cask "pomello" do
version "0.10.17"
sha256 :no_check
url "https://github.com/downloads/jonshea/Noisy/Noisy.zip"
name "Noisy"
desc "White noise generator"
homepage "https://github.com/jonshea/Noisy"
url "https://pomelloapp.com/download/mac/latest"
name "Pomello"
desc "Turns your Trello cards into Pomodoro tasks"
homepage "https://pomelloapp.com/"
app "Noisy.app"
livecheck do
url :url
strategy :header_match
end
zap trash: "~/Library/Preferences/com.rathertremendous.noisy.plist"
app "Pomello.app"
zap trash: [
"~/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.ApplicationRecentDocuments/com.tinynudge.pomello.*",
"~/Library/Application Support/Pomello",
"~/Library/Caches/com.tinynudge.pomello",
"~/Library/Caches/com.tinynudge.pomello.ShipIt",
"~/Library/HTTPStorages/com.tinynudge.pomello",
"~/Library/Preferences/com.tinynudge.pomello.plist",
"~/Library/Saved Application State/com.tinynudge.pomello.savedState",
]
end
```
Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](Cask-Cookbook.md#uninstall-pkgutil), which is needed to uninstall all files that were installed using the installer.
Here is a last example for `fabfilter-one`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](Cask-Cookbook.md#uninstall-pkgutil), which is needed to uninstall all files that were installed using the installer.
You will also see how to adapt `version` to the download `url`. Use [our custom `version` methods](Cask-Cookbook.md#version-methods) to do so, resorting to the standard [Ruby String methods](https://ruby-doc.org/core/String.html) when they dont suffice.
```ruby
cask "airdisplay" do
version "3.4.2"
sha256 "272d14f33b3a4a16e5e0e1ebb2d519db4e0e3da17f95f77c91455b354bee7ee7"
cask "fabfilter-one" do
version "3.37"
sha256 "4059594580e365237ded16a213d8d549cbb01c4b8bad80895c61f44bcff7eb68"
url "https://www.avatron.com/updates/software/airdisplay/ad#{version.no_dots}.zip"
name "Air Display"
desc "Utility for using a tablet as a second monitor"
homepage "https://avatron.com/applications/air-display/"
url "https://download.fabfilter.com/ffone#{version.no_dots}.dmg"
name "FabFilter One"
desc "Synthesizer plug-in"
homepage "https://www.fabfilter.com/products/volcano-2-powerful-filter-plug-in"
livecheck do
url "https://www.avatron.com/updates/software/airdisplay/appcast.xml"
strategy :sparkle, &:short_version
url "https://www.fabfilter.com/download"
strategy :page_match do |page|
match = page.match(/ffone(\d)(\d+)\.dmg/i)
next if match.blank?
"#{match[1]}.#{match[2]}"
end
end
depends_on macos: ">= :mojave"
depends_on macos: ">= :sierra"
pkg "Air Display Installer.pkg"
pkg "FabFilter One #{version} Installer.pkg"
uninstall pkgutil: [
"com.avatron.pkg.AirDisplay",
"com.avatron.pkg.AirDisplayHost2",
]
uninstall pkgutil: "com.fabfilter.One.#{version.major}"
# No zap stanza required
end
```
@ -156,7 +183,16 @@ cask "my-new-cask" do
desc ""
homepage ""
livecheck do
url ""
strategy ""
end
depends_on macos: ""
app ""
zap trash: ""
end
```
@ -172,17 +208,17 @@ Fill in the following stanzas for your cask:
| `name` | the full and proper name defined by the vendor, and any useful alternate names (see [`name` Stanza Details](Cask-Cookbook.md#stanza-name)) |
| `desc` | one-line description of the software (see [`desc` Stanza Details](Cask-Cookbook.md#stanza-desc)) |
| `homepage` | application homepage; used for the `brew home` command |
| `livecheck` | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck)) |
| `app` | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [`app` Stanza Details](Cask-Cookbook.md#stanza-app)) |
| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap)) |
Other commonly used stanzas are:
| name | value |
| ------------------ | ----------- |
| `livecheck` | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck)) |
| `pkg` | relative path to a `.pkg` file containing the distribution (see [`pkg` Stanza Details](Cask-Cookbook.md#stanza-pkg)) |
| `caveats` | string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats)) |
| `uninstall` | procedures to uninstall a cask; optional unless the `pkg` stanza is used (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall)) |
| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap)) |
Additional [`artifact` stanzas](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required) may be needed for special use cases. Even more special-use stanzas are listed at [Optional Stanzas](Cask-Cookbook.md#optional-stanzas).

View File

@ -113,6 +113,9 @@ Each of the following stanzas is required for every cask.
| [`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
@ -148,11 +151,8 @@ 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. |
| [`zap`](#stanza-zap) | yes | Additional procedures for a more complete uninstall, including user files and shared resources. |
| [`depends_on`](#stanza-depends_on) | yes | List of dependencies and requirements for this cask. |
| [`conflicts_with`](#stanza-conflicts_with) | yes | List of conflicts with this cask (*not yet functional*). |
| [`caveats`](#stanza-caveats) | yes | String or Ruby block providing the user with cask-specific information at install time. |
| [`livecheck`](#stanza-livecheck) | no | Ruby block describing how to find updates for this cask. Supersedes `appcast`. |
| `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). |
@ -1131,6 +1131,12 @@ Manual creation can be facilitated with:
* 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'}`.
If no additional files are discovered, instead of a zap stanza, include the following comment:
```ruby
# No zap stanza required
```
## Conditional statements
### Handling different system configurations