Skip to content

Commit

Permalink
docs: various additions & changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@EricFromCanada
EricFromCanada committed Sep 5, 2023
1 parent 7718c5a commit 484efe2
Show file tree
Hide file tree
Showing 6 changed files with 48 additions and 29 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
22 changes: 12 additions & 10 deletions docs/Adding-Software-to-Homebrew.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand All @@ -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"
Expand All @@ -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"
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion docs/Brew-Livecheck.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
39 changes: 28 additions & 11 deletions docs/Formula-Cookbook.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -21,14 +21,15 @@ 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`

## An introduction

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.

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

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

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

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

Expand All @@ -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
Expand Down
10 changes: 5 additions & 5 deletions docs/How-To-Open-a-Homebrew-Pull-Request.md
View file
Original file line number Diff line number Diff line change
@@ -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

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

0 comments on commit 484efe2

Please sign in to comment.