mirror of
https://github.com/Homebrew/brew.git
synced 2025-07-14 16:09:03 +08:00
docs: add Table of Contents to selected pages
This commit is contained in:
parent
e76c55e184
commit
42e91e8668
@ -2,23 +2,26 @@
|
||||
|
||||
Some casks should not go in [homebrew/cask](https://github.com/Homebrew/homebrew-cask). But there are additional [Interesting Taps and Forks](Interesting-Taps-and-Forks.md) and anyone can [start their own](How-to-Create-and-Maintain-a-Tap.md)!
|
||||
|
||||
* Table of Contents
|
||||
{:toc}
|
||||
|
||||
## Finding a Home For Your Cask
|
||||
|
||||
We maintain separate taps for different types of binaries. Our nomenclature is:
|
||||
|
||||
+ **Stable**: The latest version provided by the developer defined by them as such.
|
||||
+ **Beta, Development, Unstable**: Subsequent versions to **stable**, yet incomplete and under development, aiming to eventually become the new **stable**. Also includes alternate versions specifically targeted at developers.
|
||||
+ **Nightly**: Constantly up-to-date versions of the current development state.
|
||||
+ **Legacy**: Any **stable** version that is not the most recent.
|
||||
+ **Regional, Localized**: Any version that isn’t the US English one, when that exists.
|
||||
+ **Trial**: Time-limited version that stops working entirely after it expires, requiring payment to lift the limitation.
|
||||
+ **Freemium**: Gratis version that works indefinitely but with limitations that can be removed by paying.
|
||||
+ **Fork**: An alternate version of an existing project, with a based-on but modified source and binary.
|
||||
+ **Unofficial**: An *allegedly* unmodified compiled binary, by a third-party, of a binary that has no existing build by the owner of the source code.
|
||||
+ **Vendorless**: A binary distributed via means other than an official website, like a forum posting.
|
||||
+ **Walled**: When the download URL is both behind a login/registration form and from a host that differs from the homepage.
|
||||
+ **Font**: Data file containing a set of glyphs, characters, or symbols, that changes typed text.
|
||||
+ **Driver**: Software to make a hardware peripheral recognisable and usable by the system. If the software is useless without the peripheral, it’s considered a driver.
|
||||
* **Stable**: The latest version provided by the developer defined by them as such.
|
||||
* **Beta, Development, Unstable**: Subsequent versions to **stable**, yet incomplete and under development, aiming to eventually become the new **stable**. Also includes alternate versions specifically targeted at developers.
|
||||
* **Nightly**: Constantly up-to-date versions of the current development state.
|
||||
* **Legacy**: Any **stable** version that is not the most recent.
|
||||
* **Regional, Localized**: Any version that isn’t the US English one, when that exists.
|
||||
* **Trial**: Time-limited version that stops working entirely after it expires, requiring payment to lift the limitation.
|
||||
* **Freemium**: Gratis version that works indefinitely but with limitations that can be removed by paying.
|
||||
* **Fork**: An alternate version of an existing project, with a based-on but modified source and binary.
|
||||
* **Unofficial**: An *allegedly* unmodified compiled binary, by a third-party, of a binary that has no existing build by the owner of the source code.
|
||||
* **Vendorless**: A binary distributed via means other than an official website, like a forum posting.
|
||||
* **Walled**: When the download URL is both behind a login/registration form and from a host that differs from the homepage.
|
||||
* **Font**: Data file containing a set of glyphs, characters, or symbols, that changes typed text.
|
||||
* **Driver**: Software to make a hardware peripheral recognisable and usable by the system. If the software is useless without the peripheral, it’s considered a driver.
|
||||
|
||||
### Stable versions
|
||||
|
||||
@ -101,28 +104,28 @@ Before submitting a cask to any of our repos, you must read our [documentation o
|
||||
|
||||
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 repos so users don’t get stuck using an old version, wrongly thinking they’re 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’s better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users don’t 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’t 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’t 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 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).
|
||||
* 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 repos so users don’t get stuck using an old version, wrongly thinking they’re 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’s better to have them in [homebrew/core](https://github.com/Homebrew/homebrew-core) so users don’t 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’t 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’t 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 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).
|
||||
|
||||
Common reasons to reject a cask from the main repo:
|
||||
|
||||
+ Cask was submitted to the wrong repo. When drafting a cask, consult [Finding a Home For Your Cask](#finding-a-home-for-your-cask) to see where it belongs.
|
||||
* Cask was submitted to the wrong repo. When drafting a cask, consult [Finding a Home For Your Cask](#finding-a-home-for-your-cask) to see where it belongs.
|
||||
|
||||
### No cask is guaranteed to be accepted
|
||||
|
||||
|
@ -2,6 +2,9 @@
|
||||
|
||||
Some formulae should not go in [homebrew/core](https://github.com/Homebrew/homebrew-core). But there are additional [Interesting Taps and Forks](Interesting-Taps-and-Forks.md) and anyone can [start their own](How-to-Create-and-Maintain-a-Tap.md)!
|
||||
|
||||
* Table of Contents
|
||||
{:toc}
|
||||
|
||||
## Requirements for `homebrew/core`
|
||||
|
||||
### Supported platforms
|
||||
|
@ -17,6 +17,9 @@ cask "alfred" do
|
||||
end
|
||||
```
|
||||
|
||||
* Table of Contents
|
||||
{:toc}
|
||||
|
||||
## 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.
|
||||
|
@ -2,6 +2,9 @@
|
||||
|
||||
This is a list of commonly encountered problems, known issues, and their solutions.
|
||||
|
||||
* Table of Contents
|
||||
{:toc}
|
||||
|
||||
## Running `brew`
|
||||
|
||||
### `brew` complains about absence of "Command Line Tools"
|
||||
@ -120,8 +123,8 @@ This is an issue in the connection between your machine and GitHub, rather than
|
||||
|
||||
Upgrading macOS can cause errors like the following:
|
||||
|
||||
- `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib`
|
||||
- `configure: error: Cannot find libz`
|
||||
* `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib`
|
||||
* `configure: error: Cannot find libz`
|
||||
|
||||
Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and then `brew upgrade` all installed formulae:
|
||||
|
||||
|
@ -1,5 +1,8 @@
|
||||
# FAQ (Frequently Asked Questions)
|
||||
|
||||
* Table of Contents
|
||||
{:toc}
|
||||
|
||||
## Is there a glossary of terms around?
|
||||
|
||||
The Formula Cookbook has a list of [Homebrew terminology](Formula-Cookbook.md#homebrew-terminology).
|
||||
|
@ -2,6 +2,9 @@
|
||||
|
||||
A *formula* is a package definition written in Ruby. It can be created with `brew create <URL>` where `<URL>` is a zip or tarball, installed with `brew install <formula>`, and debugged with `brew install --debug --verbose <formula>`. Formulae use the [Formula API](https://rubydoc.brew.sh/Formula) which provides various Homebrew-specific helpers.
|
||||
|
||||
* Table of Contents
|
||||
{:toc}
|
||||
|
||||
## Homebrew terminology
|
||||
|
||||
| term | description | example |
|
||||
|
@ -31,6 +31,9 @@ defaults:
|
||||
values:
|
||||
category: governance-archives
|
||||
|
||||
kramdown:
|
||||
toc_levels: 2..3
|
||||
|
||||
logo: /assets/img/homebrew-256x256.png
|
||||
|
||||
twitter:
|
||||
|
Loading…
x
Reference in New Issue
Block a user