Merge pull request #14740 from unitof/update-docs-v4

Formula-Cookbook: update for Homebrew v4

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 for storing formulae and contributing 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.
+As-of [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded from `https://formulae.brew.sh/api/formula.json`, which is automatically regenerated by a scheduled formulae.brew.sh job from the `master` branch of the homebrew-core 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 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.
+
+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 taps homebrew-core, creating a Git repository in `$(brew --repository homebrew/core)`. As you are developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=1` before any `install`, `reinstall` or `upgrade` 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=1 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 <formula>` will autom
 ### Install the formula
 
 ```sh
-brew install --build-from-source --verbose --debug foo
+HOMEBREW_NO_INSTALL_FROM_API=1 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=1 brew install --interactive --git foo
 # (make some edits)
 git diff | pbcopy
 brew edit foo