Skip to content

Commit

Permalink
docs: update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@razvanazamfirei
razvanazamfirei committed Dec 15, 2023
1 parent ae1c058 commit cbe2c1d
Show file tree
Hide file tree
Showing 3 changed files with 96 additions and 54 deletions.
26 changes: 13 additions & 13 deletions docs/Acceptable-Casks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 don鈥檛 get stuck using an old version, wrongly thinking they鈥檙e 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. It鈥檚 better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users don鈥檛 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 doesn鈥檛 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 can鈥檛 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 don鈥檛 get stuck using an old version, wrongly thinking they鈥檙e 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 can鈥檛 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 doesn鈥檛 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. It鈥檚 better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users don鈥檛 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:

Expand Down
112 changes: 74 additions & 38 deletions docs/Adding-Software-to-Homebrew.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,70 +51,97 @@ Making a new cask is easy. Follow the directions in [How to Open a Homebrew Pull

#### Examples

Here鈥檚 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).
Here鈥檚 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

app "Dixa.app"

zap trash: "~/.shuttle.json"
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/"

livecheck do
url :url
strategy :header_match
end

app "Noisy.app"
app "Pomello.app"

zap trash: "~/Library/Preferences/com.rathertremendous.noisy.plist"
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 don鈥檛 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
```

Expand Down Expand Up @@ -156,7 +183,16 @@ cask "my-new-cask" do
desc ""
homepage ""

livecheck do
url ""
strategy ""
end

depends_on macos: ""

app ""

zap trash: ""
end
```

Expand All @@ -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).

Expand Down
12 changes: 9 additions & 3 deletions docs/Cask-Cookbook.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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). |
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit cbe2c1d

Please sign in to comment.