From 44a43f1a46bbb9520caa51b747332cd7a409a5c3 Mon Sep 17 00:00:00 2001 From: Jacob Ford Date: Mon, 20 Feb 2023 19:52:38 -0500 Subject: [PATCH] Formulae-Cookbook: update for Homebrew v4 --- docs/Formula-Cookbook.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 7ba28e4717..e716e66adb 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -21,16 +21,20 @@ A *formula* is a package definition written in Ruby. It can be created with `bre ## An introduction -Homebrew uses Git for downloading updates and contributing to the project. +Homebrew uses Git as its source of truth for formulae versions, and for tracking contributions to the project. -Homebrew installs to the `Cellar` and then symlinks some of the installation into `/usr/local` 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. +Forumulae were traditionally pulled directly to users using Git, but starting with [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded using from `https://formulae.brew.sh/api/formula.json`, which is [automatically generated](https://github.com/Homebrew/brew/blob/cacd7194f6c4818644629842415f9d752d63bd3e/Library/Homebrew/formula.rb#L2076-L2265) from the `master` branch of the `homebrew-core` Git repository. -Packages are installed according to their formulae, which live in `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula`. Read over a simple one, e.g. `brew edit etl` (or [etl.rb](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/etl.rb)) or a more advanced one, e.g. `brew edit git` (or [git.rb](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/git.rb)). +Homebrew installs formulae to the `Cellar` and then symlinks some of the installation into `/usr/local` 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. + +Packages are installed according to their formulae. Read over a simple one, e.g. `brew edit etl` (or [etl.rb](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/etl.rb)) or a more advanced one, e.g. `brew edit git` (or [git.rb](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/git.rb)). ## Basic instructions Make sure you run `brew update` before you start. This ensures your Homebrew installation is a Git repository. +To create or edit formulae locally, you'll need to `brew tap homebrew/core` if you haven't previously. This clones the `homebrew-core` Git repository where Homebrew expects it to be, which is `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula`. As you are developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=0` before any `install` commands, to force `brew` to use the local repository instead of the API. + Before submitting a new formula make sure your package: * meets all our [Acceptable Formulae](Acceptable-Formulae.md) requirements @@ -102,7 +106,7 @@ Check out the [License Guidelines](License-Guidelines.md) for examples of comple ### Check the build system ```sh -brew install --interactive foo +HOMEBREW_NO_INSTALL_FROM_API=0 brew install --interactive foo ``` You’re now at a new prompt with the tarball extracted to a temporary sandbox. @@ -261,7 +265,7 @@ For Python formulae, running `brew update-python-resources ` will autom ### Install the formula ```sh -brew install --build-from-source --verbose --debug foo +HOMEBREW_NO_INSTALL_FROM_API=0 brew install --build-from-source --verbose --debug foo ``` `--debug` will ask you to open an interactive shell if the build fails so you can try to figure out what went wrong. @@ -533,7 +537,7 @@ In embedded patches, the string "HOMEBREW\_PREFIX" is replaced with the value of ### Creating the diff ```sh -brew install --interactive --git foo +HOMEBREW_NO_INSTALL_FROM_API=0 brew install --interactive --git foo # (make some edits) git diff | pbcopy brew edit foo