From 819bef620c88be5a9980a0ddccaf25a54968fe94 Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Sat, 15 Apr 2023 13:38:45 -0400 Subject: [PATCH] docs: deprecate `appcast` --- docs/Cask-Cookbook.md | 61 ++++++++++++++----------------------------- 1 file changed, 19 insertions(+), 42 deletions(-) diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md index ffc1fdacf8..51ea27192d 100644 --- a/docs/Cask-Cookbook.md +++ b/docs/Cask-Cookbook.md @@ -118,7 +118,6 @@ Having a common order for stanzas makes casks easier to update and parse. Below language url - appcast name desc homepage @@ -219,11 +218,10 @@ Each cask must declare one or more *artifacts* (i.e. something to install). | ------------------------------------------ | :---------------------------: | ----- | | [`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. -| [`appcast`](#stanza-appcast) | no | URL providing an appcast feed to find updates for this cask. | [`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. +| [`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). @@ -273,42 +271,6 @@ The `target:` key works similarly for most cask artifacts, such as `app`, `binar 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/0661430a4b0143671459260e5c8affc2f8e50413/Casks/imagemin.rb#L10); [for consistency](https://github.com/Homebrew/homebrew-cask/blob/8be96e3658ff7ab66ca40723c3018fc5e35e3735/Casks/x-moto.rb#L16); [to prevent conflicts](https://github.com/Homebrew/homebrew-cask/blob/f34503e7b5f5d018a65f4c726e1c57e15b8111ae/Casks/telegram-desktop.rb#L20); [due to developer suggestion](https://github.com/Homebrew/homebrew-cask/blob/ff3e9c4a6623af44b8a071027e8dcf3f4edfc6d9/Casks/kivy.rb#L12). -### Stanza: `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](#stanza-livecheck) is usually preferred, as it allows casks to be updated automatically. - -The main [homebrew/cask](https://github.com/Homebrew/homebrew-cask) repository only accepts submissions for stable versions of software (and [documented exceptions](https://docs.brew.sh/Acceptable-Casks#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. - -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///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///-/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: [fstream.rb](https://github.com/Homebrew/homebrew-cask/blob/519999d874792f3ad7cc0fffd0520a8fdf468880/Casks/fstream.rb#L6) - -* SourceForge projects follow the form `https://sourceforge.net/projects//rss`. A more specific page can be used as needed, pointing to a specific directory structure: `https://sourceforge.net/projects//rss?path=/path/here`. Example: [displaycal.rb](https://github.com/Homebrew/homebrew-cask/blob/347dc92405889488ea72c47f7d50b1afaf348909/Casks/displaycal.rb#L7) - -* 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: [securityspy.rb](https://github.com/Homebrew/homebrew-cask/blob/e3495e32b7fb3ed1929b6082a4e3eb6a94d9494f/Casks/securityspy.rb#L6) - -The [`find-appcast`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/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: - -```bash -"$(brew --repository homebrew/cask)/developer/bin/find-appcast" '/path/to/application.app' -``` - -#### `appcast` Parameters - -| key | value | -| --------------- | ----------- | -| `must_contain:` | Custom string for `brew audit --appcast ` to check against. (Example: [icollections.rb](https://github.com/Homebrew/homebrew-cask/blob/705ed8ddc23a0e7719348dfb278046f031495938/Casks/icollections.rb#L6-L7)) - -Sometimes a `version` doesn’t match a string on the webpage, in which case we tweak what to search for. 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. For example, if `version` is `6.26b-14,40`, the check will look for `6.26b`. This is so it covers most cases by default, while still allowing complex `version`s suitable for interpolation in the rest of the cask. - ### Stanza: `binary` In the simple case of a string argument to `binary`, the source file is linked into the `$(brew --prefix)/bin` directory on installation. For example (from [operadriver.rb](https://github.com/Homebrew/homebrew-cask/blob/8145c76101534aabcfc419488578455e636d6330/Casks/operadriver.rb#L15)): @@ -701,7 +663,7 @@ brew install firefox --language=it ### Stanza: `livecheck` -The `livecheck` stanza is used to automatically fetch the latest version of a cask from changelogs, release notes, appcasts, etc. See also: [`brew livecheck` reference](Brew-Livecheck.md) +The `livecheck` stanza is used to automatically fetch the latest version of a cask from changelogs, release notes, appcasts, etc. Since the main [homebrew/cask](https://github.com/Homebrew/homebrew-cask) repository only accepts submissions for stable versions of software (and [documented exceptions](https://docs.brew.sh/Acceptable-Casks#but-there-is-no-stable-version)), this allows for verifying that the submitted version is the latest, and alerting when a newer version is available using [`brew livecheck`](Brew-Livecheck.md). 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`). @@ -734,7 +696,7 @@ livecheck do end ``` -The `header_match` strategy will try to parse 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.: +The `:header_match` strategy will try to parse 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 @@ -764,6 +726,21 @@ strategy :page_match do |page| end ``` +The `:sparkle` strategy takes a URL for an XML feed providing release information to an app that self-updates using the Sparkle framework. This URL can be found within the app bundle as the `SUFeedURL` property in `Contents/Info.plist` or by using the [`find-appcast`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/developer/bin/find-appcast) script. Run it with: + +```bash +"$(brew --repository homebrew/cask)/developer/bin/find-appcast" '/path/to/application.app' +``` + +Both the `sparkle:version` and `sparkle:shortVersionString` attributes are checked by default; if only one is needed, specify `&:version` or `&:short_version`: + +```ruby +url "https://manytricks.com/butler/appcast/" +strategy :sparkle, &:short_version +``` + +If no means are available online for checking which version is current, as a last resort the `:extract_plist` strategy will have `brew livecheck` download the artifact and retrieve its version string from `Contents/Info.plist`. + ### Stanza: `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. @@ -1118,7 +1095,7 @@ 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 an [`appcast`](#stanza-appcast) 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](https://docs.brew.sh/Acceptable-Casks#unofficial-vendorless-and-walled-builds). #### Difficulty Finding a URL