mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: various additions & changes

Browse Source
This commit is contained in:
Eric Knibbe 2023-09-05 00:58:57 -04:00
parent 7718c5ad61
commit 484efe2911
No known key found for this signature in database
GPG Key ID: 179D9CDDDB814168
6 changed files with 48 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -39,7 +39,7 @@ We'd love you to contribute to Homebrew. First, please read our [Contribution Gu
We explicitly welcome contributions from people who have never contributed to open-source before: we were all beginners once! We can help build on a partially working pull request with the aim of getting it merged. We are also actively seeking to diversify our contributors and especially welcome contributions from women from all backgrounds and people of colour.
A good starting point for contributing is to first [tap Homebrew/homebrew-core](https://docs.brew.sh/FAQ#can-i-edit-formulae-myself), run `brew audit --strict` with some of the packages you use (e.g. `brew audit --strict wget` if you use `wget`) and then read through the warnings, try to fix them until `brew audit --strict` shows no results and [submit a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request). If no formulae you use have warnings you can run `brew audit --strict` without arguments to have it run on all packages and pick one.
A good starting point for contributing is to first [tap `homebrew/core`](https://docs.brew.sh/FAQ#can-i-edit-formulae-myself), then run `brew audit --strict` with some of the packages you use (e.g. `brew audit --strict wget` if you use `wget`) and read through the warnings. Try to fix them until `brew audit --strict` shows no results and [submit a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request). If no formulae you use have warnings you can run `brew audit --strict` without arguments to have it run on all packages and pick one.
Alternatively, for something more substantial, check out one of the issues labeled `help wanted` in [Homebrew/brew](https://github.com/homebrew/brew/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or [Homebrew/homebrew-core](https://github.com/homebrew/homebrew-core/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).

22
docs/Adding-Software-to-Homebrew.md
View File

@ -83,6 +83,8 @@ cask "noisy" do
homepage "https://github.com/jonshea/Noisy"
app "Noisy.app"
zap trash: "~/Library/Preferences/com.rathertremendous.noisy.plist"
end
```
@ -92,17 +94,17 @@ You will also see how to adapt `version` to the download `url`. Use [our custom
```ruby
cask "airdisplay" do
version "3.4.2,26581"
version "3.4.2"
sha256 "272d14f33b3a4a16e5e0e1ebb2d519db4e0e3da17f95f77c91455b354bee7ee7"
url "https://www.avatron.com/updates/software/airdisplay/ad#{version.before_comma.no_dots}.zip"
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/"
livecheck do
url "https://www.avatron.com/updates/software/airdisplay/appcast.xml"
strategy :sparkle
strategy :sparkle, &:short_version
end
depends_on macos: ">= :mojave"
@ -120,7 +122,7 @@ end
The cask **token** is the mnemonic string people will use to interact with the cask via `brew install`, etc. The name of the cask **file** is simply the token with the extension `.rb` appended.
The easiest way to generate a token for a cask is to run this command:
The easiest way to generate a token for a cask is to run `generate_cask_token`:
```bash
$(brew --repository homebrew/cask)/developer/bin/generate_cask_token "/full/path/to/new/software.app"
@ -198,13 +200,13 @@ When a downloaded archive expands to a subfolder, the subfolder name must be inc
Example:
1. Texmaker is downloaded to the file `TexmakerMacosxLion.zip`.
1. `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion`.
1. The folder `TexmakerMacosxLion` contains the application `texmaker.app`.
1. Simple Floating Clock is downloaded to the file `sfc.zip`.
1. `sfc.zip` unzips to a folder called `Simple Floating Clock`.
1. The folder `Simple Floating Clock` contains the application `SimpleFloatingClock.app`.
1. So, the `app` stanza should include the subfolder as a relative path:
```ruby
app "TexmakerMacosxLion/texmaker.app"
app "Simple Floating Clock/SimpleFloatingClock.app"
```
### Testing and auditing the cask
@ -246,7 +248,7 @@ If your application and Homebrew Cask do not work well together, feel free to [f
See the [Acceptable Casks documentation](Acceptable-Casks.md#finding-a-home-for-your-cask).
Hop into your Tap and check to make sure your new cask is there:
Hop into your tap and check to make sure your new cask is there:
```bash
$ cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask
@ -268,7 +270,7 @@ Switched to a new branch 'my-new-cask-branch'
Stage your cask with:
```bash
git add Casks/my-new-cask.rb
git add Casks/m/my-new-cask.rb
```
You can view the changes that are to be committed with:

2
docs/Brew-Livecheck.md
View File

@ -27,7 +27,7 @@ This can be accomplished by adding a `livecheck` block to the formula/cask/resou
* **Only use `strategy` when it's necessary**. For example, if livecheck is already using the `Git` strategy for a URL, it's not necessary to use `strategy :git`. However, if `Git` applies to a URL but we need to use `PageMatch`, it's necessary to specify `strategy :page_match`.
* **Only use the `GithubLatest` and `GithubReleases` strategies when they are necessary and correct**. GitHub rate limits API requests, so we only use these strategies when `Git` isn't sufficient or appropriate. `GithubLatest` should only be used if the upstream repository has a "latest" release for a suitable version and either the formula/cask uses a release asset or the `Git` strategy can't correctly identify the latest release version. `GithubReleases` should only be used if the upstream repository uses releases and both the `Git` and `GithubLatest` strategies aren't suitable.
* **Only use the `GithubLatest` and `GithubReleases` strategies when they are necessary and correct**. GitHub rate-limits API requests, so we only use these strategies when `Git` isn't sufficient or appropriate. `GithubLatest` should only be used if the upstream repository has a "latest" release for a suitable version and either the formula/cask uses a release asset or the `Git` strategy can't correctly identify the latest release version. `GithubReleases` should only be used if the upstream repository uses releases and both the `Git` and `GithubLatest` strategies aren't suitable.
### URL guidelines

39
docs/Formula-Cookbook.md
View File

@ -9,8 +9,8 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
| term | description | example |
| -------------------- | ------------------------------------------------------------------------- | ------- |
| **formula** | Homebrew package definition that builds from upstream sources | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb`
| **cask** | Homebrew package definition that installs macOS native applications | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/bar.rb`
| **formula** | Homebrew package definition that builds from upstream sources | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb`
| **cask** | Homebrew package definition that installs macOS native applications | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/b/bar.rb`
| **prefix** | path in which Homebrew is installed | `/usr/local`
| **keg** | installation destination directory of a given **formula** version | `/usr/local/Cellar/foo/0.1`
| **rack** | directory containing one or more versioned **kegs** | `/usr/local/Cellar/foo`
@ -21,6 +21,7 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
| **external command** | `brew` subcommand defined outside of the Homebrew/brew GitHub repository | [`brew alias`](https://github.com/Homebrew/homebrew-aliases)
| **tap** | directory (and usually Git repository) of **formulae**, **casks** and/or **external commands** | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core`
| **bottle** | pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources | `qt--6.5.1.ventura.bottle.tar.gz`
| **tab** | information about a **keg**, e.g. whether it was poured from a **bottle** or built from source | `/usr/local/Cellar/foo/0.1/INSTALL_RECEIPT.json`
| **Brew Bundle** | an [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true`
| **Brew Services** | an [extension of Homebrew](https://github.com/Homebrew/homebrew-services) to manage services | `brew services start myservice`
@ -28,7 +29,7 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
Homebrew uses Git for storing formulae and contributing to the project.
As of [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded as JSON from <https://formulae.brew.sh> which is automatically regenerated by a scheduled [Homebrew/formulae.brew.sh](https://github.com/Homebrew/formulae.brew.sh) job from the `master` branch of the `homebrew/core` repository.
As of [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded as JSON from <https://formulae.brew.sh> which is automatically regenerated by a scheduled [Homebrew/formulae.brew.sh](https://github.com/Homebrew/formulae.brew.sh) job from the `master` branch of the Homebrew/homebrew-core repository.
Homebrew installs formulae to the Cellar at `$(brew --cellar)` and then symlinks some of the installation into the prefix at `$(brew --prefix)` (e.g. `/opt/homebrew`) so that other programs can see what's going on. We suggest running `brew ls` on a few of the kegs in your Cellar to see how it is all arranged.
@ -59,7 +60,7 @@ Run `brew create` with a URL to the source tarball:
brew create https://example.com/foo-0.1.tar.gz
```
This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` and opens it in your `EDITOR`. If run without any options to customize the output for specific build systems (check `brew create --help` to see which are available) it'll look something like:
This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb` and opens it in your `EDITOR`. If run without any options to customize the output for specific build systems (check `brew create --help` to see which are available) it'll look something like:
```ruby
class Foo < Formula
@ -171,6 +172,8 @@ A `Hash` (e.g. `=>`) adds information to a dependency. Given a string or symbol,
depends_on "foo" => :optional # Generated description would otherwise be "Build with foo support"
```
* `"<option-name>"` (not allowed in `Homebrew/homebrew-core`) requires a dependency to have been built with the specified option.
### Specifying conflicts with other formulae
Sometimes there’s a hard conflict between formulae that can’t be avoided or circumvented with [`keg_only`](https://rubydoc.brew.sh/Formula#keg_only-class_method).
@ -372,12 +375,12 @@ Use `brew info` and check if the version guessed by Homebrew from the URL is cor
Everything is built on Git, so contribution is easy:
```sh
brew update # required in more ways than you think (initialises the brew git repository if you don't already have it)
brew update # required in more ways than you think (initialises the Homebrew/brew Git repository if you don't already have it)
cd "$(brew --repository homebrew/core)"
# Create a new git branch for your formula so your pull request is easy to
# modify if any changes come up during review.
git checkout -b <some-descriptive-name> origin/master
git add Formula/foo.rb
git add Formula/f/foo.rb
git commit
```
@ -399,7 +402,7 @@ Ensure you reference any relevant GitHub issue, e.g. `Closes #12345` in the comm
Now you just need to push your commit to GitHub.
If you haven’t forked Homebrew yet, [go to the `homebrew/core` repository and hit the Fork button](https://github.com/Homebrew/homebrew-core).
If you haven’t forked Homebrew yet, [go to the Homebrew/homebrew-core repository and hit the Fork button](https://github.com/Homebrew/homebrew-core).
If you have already forked Homebrew on GitHub, then you can manually push (just make sure you have been pulling from the `Homebrew/homebrew-core` master):
@ -554,7 +557,7 @@ Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formu
## Advanced formula tricks
If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repository homebrew/core)` directory for examples. Please submit a pull request to amend this document if you think it will help!
See the [Formula API](https://rubydoc.brew.sh/Formula) for the full list of methods available within a formula. If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repository homebrew/core)` directory for examples. Please submit a pull request to amend this document if you think it will help!
### Handling different system configurations
@ -661,7 +664,7 @@ class Nginx < Formula
head "https://hg.nginx.org/nginx/", using: :hg
```
Homebrew offers anonymous download strategies.
Homebrew offers these anonymous download strategies.
| `:using` value | download strategy |
| ---------------- | ----------------------------- |
@ -853,7 +856,8 @@ class Yourformula < Formula
option "with-ham", "Description of the option"
option "without-spam", "Another description"
depends_on "foo" => :optional # will automatically add a with-foo option
depends_on "foo" => :optional # automatically adds a with-foo option
depends_on "bar" => :recommended # automatically adds a without-bar option
...
```
@ -871,7 +875,20 @@ end
[`option`](https://rubydoc.brew.sh/Formula#option-class_method) names should be prefixed with the words `with` or `without`. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library `--with-shared` rather than `--shared` or `--enable-shared`. See the [alternative `ffmpeg`](https://github.com/homebrew-ffmpeg/homebrew-ffmpeg/blob/HEAD/Formula/ffmpeg.rb) formula for examples.
[`option`](https://rubydoc.brew.sh/Formula#option-class_method)s that aren’t `build.with?` or `build.without?` should be deprecated with [`deprecated_option`](https://rubydoc.brew.sh/Formula#deprecated_option-class_method). See the [`wget`](https://github.com/Homebrew/homebrew-core/blob/3f762b63c6fbbd49191ffdf58574d7e18937d93f/Formula/wget.rb#L27-L31) formula for an example.
[`option`](https://rubydoc.brew.sh/Formula#option-class_method)s that aren’t `build.with?` or `build.without?` should be deprecated with [`deprecated_option`](https://rubydoc.brew.sh/Formula#deprecated_option-class_method). See the [`wget`](https://github.com/Homebrew/homebrew-core/blob/3f762b63c6fbbd49191ffdf58574d7e18937d93f/Formula/wget.rb#L27-L31) formula for a historical example.
### Running commands after installation
Any initialization steps that aren't necessarily part of the install process can be located in a `post_install` block, such as setup commands or data directory creation. This block can be re-run separately with `brew postinstall <formula>`.
```ruby
def post_install
rm_f pkgetc/"cert.pem"
pkgetc.install_symlink Formula["ca-certificates"].pkgetc/"cert.pem"
end
```
In the above example, the [`libressl`](https://github.com/Homebrew/homebrew-core/blob/442f9cc511ce6dfe75b96b2c83749d90dde914d2/Formula/lib/libressl.rb#L53-L56) formula replaces its stock list of certificates with a symlink to that of the `ca-certificates` formula.
### Handling files that should persist over formula upgrades

10
docs/How-To-Open-a-Homebrew-Pull-Request.md
View File

@ -1,8 +1,8 @@
# How to Open a Homebrew Pull Request
The following commands are used by Homebrew contributors to set up a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request ("PR") of the changes in that branch.
The following commands are used by Homebrew contributors to set up a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request ("PR") for the changes in that branch.
The type of change you want to make influences which of Homebrew's main repositories you'll need to send your pull request to. If you want to submit a change to Homebrew's core code (the `brew` implementation), you should open a pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open a pull request on the [homebrew/core](https://github.com/Homebrew/homebrew-core) tap, while for casks you should open the pull request on the [homebrew/cask](https://github.com/Homebrew/homebrew-cask) tap or another [official tap](https://github.com/Homebrew), based on the formula type.
The type of change you want to make influences which of Homebrew's main repositories you'll need to send your pull request to. If you want to submit a change to Homebrew's core code (the `brew` implementation), you should open a pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open a pull request on the [homebrew/core](https://github.com/Homebrew/homebrew-core) tap, while for casks you should open the pull request on the [homebrew/cask](https://github.com/Homebrew/homebrew-cask) tap or another [official tap](https://github.com/Homebrew), depending on the formula type.
## Submit a new version of an existing formula
@ -14,7 +14,7 @@ The type of change you want to make influences which of Homebrew's main reposito
## Set up your own fork of the Homebrew repository
### Core `brew` code related pull request
### Core `brew` code pull request
1. [Fork the Homebrew/brew repository on GitHub](https://github.com/Homebrew/brew/fork).
* This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
@ -32,7 +32,7 @@ The type of change you want to make influences which of Homebrew's main reposito
* `<YOUR_USERNAME>` is your GitHub username, not your local machine username.
### Formulae related pull request
### Formulae-related pull request
1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork).
* This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
@ -56,7 +56,7 @@ The type of change you want to make influences which of Homebrew's main reposito
* `<YOUR_USERNAME>` is your GitHub username, not your local machine username.
### Cask related pull request
### Cask-related pull request
1. [Fork the Homebrew/homebrew-cask repository on GitHub](https://github.com/Homebrew/homebrew-cask/fork).
* This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.

2
docs/Troubleshooting.md
View File

@ -26,6 +26,6 @@ If your problem hasn't been solved or reported, then create an issue:
* If your have a non-formula problem: collect the output of `brew config` and `brew doctor`.
1. Create a new issue on the issue tracker for [Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/issues/new/choose), [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask/issues/new/choose) or [Homebrew/brew](https://github.com/Homebrew/brew/issues/new/choose) and follow the instructions:
* Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<platform>", where "\<formula>" is the name of the formula that failed to build, and "\<platform>" is the name and version of macOS or Linux you are using.
* Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<platform>", where *\<formula>* is the name of the formula that failed to build, and *\<platform>* is the name and version of macOS or Linux you are using.
* Include the URL provided by `brew gist-logs <formula>` (if applicable) plus links to any additional Gists you may have created.
* Include the output of `brew config` and `brew doctor`.