From 569c833924abeaa7944b0b25d780a4ecb2939227 Mon Sep 17 00:00:00 2001 From: Eric Knibbe Date: Sat, 12 Aug 2023 09:29:30 -0400 Subject: [PATCH] Formula-Cookbook: expand terminology table --- Library/Homebrew/manpages/brew.1.md.erb | 18 ++++++++++------- docs/Formula-Cookbook.md | 27 +++++++++++++++---------- docs/Manpage.md | 18 ++++++++++------- manpages/brew.1 | 24 ++++++++++++++-------- 4 files changed, 54 insertions(+), 33 deletions(-) diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb index ab3cabebe3cb1..68ec0a1912a04 100644 --- a/Library/Homebrew/manpages/brew.1.md.erb +++ b/Library/Homebrew/manpages/brew.1.md.erb @@ -30,25 +30,29 @@ Linux distribution without requiring `sudo`. ## TERMINOLOGY -**formula**: Homebrew package definition built from upstream sources +**formula**: Homebrew package definition that builds from upstream sources **cask**: Homebrew package definition that installs macOS native applications -**keg**: installation destination directory of a given **formula** version e.g. `/usr/local/Cellar/foo/0.1` +**prefix**: path in which Homebrew is installed, e.g. `/usr/local` -**rack**: directory containing one or more versioned kegs e.g. `/usr/local/Cellar/foo` +**keg**: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1` -**keg-only**: a **formula** is **keg-only** if it is not symlinked into Homebrew's prefix (e.g. `/usr/local`) +**rack**: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo` -**cellar**: directory containing one or more named **racks** e.g. `/usr/local/Cellar` +**keg-only**: a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix -**Caskroom**: directory containing one or more named **casks** e.g. `/usr/local/Caskroom` +**opt prefix**: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo` + +**Cellar**: directory containing one or more named **racks**, e.g. `/usr/local/Cellar` + +**Caskroom**: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom` **external command**: `brew` subcommand defined outside of the Homebrew/brew GitHub repository **tap**: directory (and usually Git repository) of **formulae**, **casks** and/or **external commands** -**bottle**: pre-built **keg** poured into the **cellar**/**rack** instead of building from upstream sources +**bottle**: pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources ## ESSENTIAL COMMANDS diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index d8411a27ac2b6..5ee4c3c083808 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -7,17 +7,22 @@ A *formula* is a package definition written in Ruby. It can be created with `bre ## Homebrew terminology -| term | description | example | -| -------------- | ---------------------------------------------------------- | ------- | -| **Formula** | the package definition | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` -| **Keg** | the installation prefix of a **Formula** | `/usr/local/Cellar/foo/0.1` -| **Keg-only** | a **Formula** is **Keg-only** if it is not linked into the Homebrew prefix | the [`openjdk`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/openjdk.rb) formula -| **opt prefix** | a symlink to the active version of a **Keg** | `/usr/local/opt/foo` -| **Cellar** | all **Kegs** are installed here | `/usr/local/Cellar` -| **Tap** | a Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` -| **Bottle** | pre-built **Keg** used instead of building from source | `qt-4.8.4.catalina.bottle.tar.gz` -| **Cask** | an [extension of Homebrew](https://github.com/Homebrew/homebrew-cask) to install macOS native apps | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown` -| **Brew Bundle**| an [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` +| 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` +| **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` +| **keg-only** | a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix | the [`openjdk`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/openjdk.rb) formula +| **opt prefix** | a symlink to the active version of a **keg** | `/usr/local/opt/foo` +| **Cellar** | directory containing one or more named **racks** | `/usr/local/Cellar` +| **Caskroom** | directory containing one or more named **casks** | `/usr/local/Caskroom` +| **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` +| **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 diff --git a/docs/Manpage.md b/docs/Manpage.md index 84c7bb0c8e148..8ebbe03535fe1 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -14,25 +14,29 @@ Linux distribution without requiring `sudo`. ## TERMINOLOGY -**formula**: Homebrew package definition built from upstream sources +**formula**: Homebrew package definition that builds from upstream sources **cask**: Homebrew package definition that installs macOS native applications -**keg**: installation destination directory of a given **formula** version e.g. `/usr/local/Cellar/foo/0.1` +**prefix**: path in which Homebrew is installed, e.g. `/usr/local` -**rack**: directory containing one or more versioned kegs e.g. `/usr/local/Cellar/foo` +**keg**: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1` -**keg-only**: a **formula** is **keg-only** if it is not symlinked into Homebrew's prefix (e.g. `/usr/local`) +**rack**: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo` -**cellar**: directory containing one or more named **racks** e.g. `/usr/local/Cellar` +**keg-only**: a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix -**Caskroom**: directory containing one or more named **casks** e.g. `/usr/local/Caskroom` +**opt prefix**: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo` + +**Cellar**: directory containing one or more named **racks**, e.g. `/usr/local/Cellar` + +**Caskroom**: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom` **external command**: `brew` subcommand defined outside of the Homebrew/brew GitHub repository **tap**: directory (and usually Git repository) of **formulae**, **casks** and/or **external commands** -**bottle**: pre-built **keg** poured into the **cellar**/**rack** instead of building from upstream sources +**bottle**: pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources ## ESSENTIAL COMMANDS diff --git a/manpages/brew.1 b/manpages/brew.1 index 08c6ec6643169..9025aad9aee31 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -17,31 +17,39 @@ Homebrew is the easiest and most flexible way to install the UNIX tools Apple di . .SH "TERMINOLOGY" \fBformula\fR - Homebrew package definition built from upstream sources + Homebrew package definition that builds from upstream sources . .P \fBcask\fR Homebrew package definition that installs macOS native applications . .P +\fBprefix\fR + path in which Homebrew is installed, e\.g\. \fB/usr/local\fR +. +.P \fBkeg\fR - installation destination directory of a given \fBformula\fR version e\.g\. \fB/usr/local/Cellar/foo/0\.1\fR + installation destination directory of a given \fBformula\fR version, e\.g\. \fB/usr/local/Cellar/foo/0\.1\fR . .P \fBrack\fR - directory containing one or more versioned kegs e\.g\. \fB/usr/local/Cellar/foo\fR + directory containing one or more versioned \fBkegs\fR, e\.g\. \fB/usr/local/Cellar/foo\fR . .P \fBkeg\-only\fR - a \fBformula\fR is \fBkeg\-only\fR if it is not symlinked into Homebrew\'s prefix (e\.g\. \fB/usr/local\fR) + a \fBformula\fR is \fIkeg\-only\fR if it is not symlinked into Homebrew\'s prefix +. +.P +\fBopt prefix\fR + a symlink to the active version of a \fBkeg\fR, e\.g\. \fB/usr/local/opt/foo\fR . .P -\fBcellar\fR - directory containing one or more named \fBracks\fR e\.g\. \fB/usr/local/Cellar\fR +\fBCellar\fR + directory containing one or more named \fBracks\fR, e\.g\. \fB/usr/local/Cellar\fR . .P \fBCaskroom\fR - directory containing one or more named \fBcasks\fR e\.g\. \fB/usr/local/Caskroom\fR + directory containing one or more named \fBcasks\fR, e\.g\. \fB/usr/local/Caskroom\fR . .P \fBexternal command\fR @@ -53,7 +61,7 @@ Homebrew is the easiest and most flexible way to install the UNIX tools Apple di . .P \fBbottle\fR - pre\-built \fBkeg\fR poured into the \fBcellar\fR/\fBrack\fR instead of building from upstream sources + pre\-built \fBkeg\fR poured into a \fBrack\fR of the \fBCellar\fR instead of building from upstream sources . .SH "ESSENTIAL COMMANDS" For the full command list, see the \fICOMMANDS\fR section\.