From de3cebf45ce19e315a2266adce7624692c4bdc56 Mon Sep 17 00:00:00 2001 From: Eric Knibbe Date: Sat, 16 Aug 2025 23:12:22 -0400 Subject: [PATCH] docs: edit various URLs --- docs/Acceptable-Casks.md | 4 ++-- docs/Adding-Software-to-Homebrew.md | 16 +++++++-------- docs/Autobump.md | 2 +- docs/Cask-Cookbook.md | 14 ++++++------- docs/Common-Issues.md | 2 +- docs/FAQ.md | 2 +- docs/Formula-Cookbook.md | 20 +++++++++---------- docs/Homebrew-brew-Maintainer-Guide.md | 2 +- ...Homebrew-homebrew-core-Maintainer-Guide.md | 2 +- docs/Homebrew-on-Linux.md | 4 ++-- docs/How-To-Organize-AGM.md | 4 ++-- docs/How-to-Create-and-Maintain-a-Tap.md | 4 ++-- docs/Installation.md | 14 ++++++------- docs/Python-for-Formula-Authors.md | 2 +- docs/Querying-Brew.md | 2 +- docs/Reproducible-Builds.md | 2 +- docs/Troubleshooting.md | 2 +- docs/index.md | 2 +- docs/vale-styles/Homebrew/Abbreviations.yml | 2 +- 19 files changed, 50 insertions(+), 52 deletions(-) diff --git a/docs/Acceptable-Casks.md b/docs/Acceptable-Casks.md index 5813f17c49..d2a2f2ff6e 100644 --- a/docs/Acceptable-Casks.md +++ b/docs/Acceptable-Casks.md @@ -61,9 +61,9 @@ Unfortunately, in the world of software there are bad actors that bundle malware But we’d still like for users to enjoy some kind of protection while minimising occurrences of legitimate developers being branded as malware carriers. To do so, we evaluate casks on a case-by-case basis and any user is free to bring a potential malware case to our attention. However, it is important to never forget the last line of defence is *always* the user. -If an app that bundles malware was not signed with an Apple Developer ID and you purposefully disabled or bypassed Gatekeeper, no action will be taken on our part. When you disable security features, you do so at your own risk. If, however, an app that bundles malware is signed, Apple can revoke its permissions and it will no longer run on the computers of users that keep security features on—we all benefit, Homebrew Cask users or not. To report a signed app that bundles malware, use [Apple’s Feedback Assistant](https://feedbackassistant.apple.com). +If an app that bundles malware was not signed with an Apple Developer ID and you purposefully disabled or bypassed Gatekeeper, no action will be taken on our part. When you disable security features, you do so at your own risk. If, however, an app that bundles malware is signed, Apple can revoke its permissions and it will no longer run on the computers of users that keep security features on—we all benefit, Homebrew Cask users or not. To report a signed app that bundles malware, use [Apple’s Feedback Assistant](https://feedbackassistant.apple.com/). -We are also open to removing casks where we feel there is enough evidence that the app is malicious. To suggest a cask for removal, submit a pull request to delete it along with your reasoning. Typically, this will mean presenting a [VirusTotal](https://www.virustotal.com) scan of the app showing it is malicious, ideally with some other reporting indicating it’s not a false positive. +We are also open to removing casks where we feel there is enough evidence that the app is malicious. To suggest a cask for removal, submit a pull request to delete it along with your reasoning. Typically, this will mean presenting a [VirusTotal](https://www.virustotal.com/) scan of the app showing it is malicious, ideally with some other reporting indicating it’s not a false positive. Likewise, software which provides both “clean” and malware-infested versions might be removed from the repository; even if we could have access to the *good* version—if its developers push for users to install the *bad* version. We do so because in these cases there’s a higher than normal risk that both versions are (or will soon become) compromised in some manner. diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index 306a25926c..6fc335694f 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/docs/Adding-Software-to-Homebrew.md @@ -6,7 +6,7 @@ last_review_date: "1970-01-01" Is your favourite software missing from Homebrew? Then you're the perfect person to resolve this problem. -If you want to add software that is either closed source or a GUI-only program, you will want to follow the guide for [Casks](#casks). Otherwise follow the guide for [Formulae](#formulae) (see also: [Homebrew Terminology](Formula-Cookbook.md#homebrew-terminology)). +If you want to add software that is either closed source or a GUI-only program, you will want to follow the guide for [Casks](#casks). Otherwise follow the guide for [Formulae](#formulae) (see also: [Homebrew terminology](Formula-Cookbook.md#homebrew-terminology)). Before you start, please check the open pull requests for [Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/pulls) or [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask/pulls) to make sure no one else beat you to the punch. @@ -55,7 +55,7 @@ Making a new cask is easy. Follow the directions in [How to Open a Homebrew Pull #### Examples -Here’s a cask for `dixa` as an example. Note the `verified` parameter below the `url`, which is needed when [the url and homepage hostnames differ](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified). +Here’s a cask for `dixa` as an example. Note the `verified` parameter below the `url`, which is needed when [the URL and homepage hostnames differ](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified). ```ruby cask "dixa" do @@ -115,9 +115,9 @@ cask "pomello" do end ``` -Here is a last example for `fabfilter-one`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](Cask-Cookbook.md#uninstall-pkgutil), which is needed to uninstall all files that were installed using the installer. +Here is a last example for `fabfilter-one`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil:`](Cask-Cookbook.md#uninstall-pkgutil) stanza, which is needed to uninstall all files that were installed using the installer. -You will also see how to adapt `version` to the download `url`. Use [our custom `version` methods](Cask-Cookbook.md#version-methods) to do so, resorting to the standard [Ruby String methods](https://ruby-doc.org/core/String.html) when they don’t suffice. +You will also see how to adapt `version` to the download `url`. Use [our custom `version` methods](Cask-Cookbook.md#version-methods) to do so, resorting to the standard [Ruby `String` methods](https://ruby-doc.org/core/String.html) when they don’t suffice. ```ruby cask "fabfilter-one" do @@ -201,7 +201,7 @@ Other commonly used stanzas are: | `caveats` | string or Ruby block providing the user with cask-specific information at install time (see [`caveats` Stanza Details](Cask-Cookbook.md#stanza-caveats)) | | `uninstall` | procedures to uninstall a cask; optional unless the `pkg` stanza is used (see [`uninstall` Stanza Details](Cask-Cookbook.md#stanza-uninstall)) | -Additional [`artifact` stanzas](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required) may be needed for special use cases. Even more special-use stanzas are listed at [Optional Stanzas](Cask-Cookbook.md#optional-stanzas). +Additional [artifact stanzas](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required) may be needed for special use cases. Even more special-use stanzas are listed at [Optional stanzas](Cask-Cookbook.md#optional-stanzas). #### Cask token details @@ -209,7 +209,7 @@ If a token conflicts with an already-existing cask, authors should manually make If possible, avoid creating tokens that differ only by the placement of hyphens. -To generate a token manually, or to learn about exceptions for unusual cases, see the [Token Reference](Cask-Cookbook.md#token-reference). +To generate a token manually, or to learn about exceptions for unusual cases, see the [Token reference](Cask-Cookbook.md#token-reference). #### Archives with subfolders @@ -264,7 +264,7 @@ If your application and Homebrew Cask do not work well together, feel free to [f #### Finding a home for your cask -See the [Acceptable Casks documentation](Acceptable-Casks.md#finding-a-home-for-your-cask). +See the [Acceptable Casks](Acceptable-Casks.md#finding-a-home-for-your-cask) documentation. Hop into your tap and check to make sure your new cask is there: @@ -355,7 +355,7 @@ Now go to the [`homebrew-cask` GitHub repository](https://github.com/Homebrew/ho Otherwise, click the `Contribute > Open pull request` button and choose to `compare across forks`. The base fork should be `Homebrew/homebrew-cask @ main`, and the head fork should be `my-github-username/homebrew-cask @ my-new-cask-branch`. You can also add any further comments to your pull request at this stage. -##### Congratulations +#### Congratulations You are done now, and your cask should be pulled in or otherwise noticed in a while. If a maintainer suggests some changes, just make them on the `my-new-cask-branch` branch locally and [push](#pushing). diff --git a/docs/Autobump.md b/docs/Autobump.md index 81ccefcba2..f578223ba2 100644 --- a/docs/Autobump.md +++ b/docs/Autobump.md @@ -20,7 +20,7 @@ Other formula and cask specific reasons for why a package is not autobumped are When using `no_autobump!`, a reason for exclusion must be provided. -There are two ways to indicate the reason. The preferred way is to use a pre-existing symbol, which can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant), for example: +There are two ways to indicate the reason. The preferred way is to use a pre-existing symbol, which can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace#NO_AUTOBUMP_REASONS_LIST-constant), for example: ```ruby no_autobump! because: :bumped_by_upstream diff --git a/docs/Cask-Cookbook.md b/docs/Cask-Cookbook.md index 93257df86a..84929c3139 100644 --- a/docs/Cask-Cookbook.md +++ b/docs/Cask-Cookbook.md @@ -669,7 +669,7 @@ The `no_autobump!` stanza excludes a cask from the autobump list. This means all no_autobump! because: :incompatible_version_format ``` -A complete list of allowed symbols can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant). +A complete list of allowed symbols can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace#NO_AUTOBUMP_REASONS_LIST-constant). Casks that use `strategy :extract_plist` in their `livecheck` block or have `version :latest` are always excluded from the autobump list and do not require `no_autobump!` to be declared. @@ -681,7 +681,7 @@ Refer to the [Autobump](Autobump.md) page for more information about the autobum Unlike the [token](#token-reference), which is simplified and reduced to a limited set of characters, the `name` stanza can include the proper capitalization, spacing and punctuation to match the official name of the software. For disambiguation purposes, it is recommended to spell out the name of the application, including the vendor name if necessary. A good example is the [`pycharm-ce`](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/p/pycharm-ce.rb#L9-L10) cask, whose name is spelled out as `Jetbrains PyCharm Community Edition`, even though it is likely never referenced as such anywhere. -Additional details about the software can be provided in the [`desc` stanza](#stanza-desc). +Additional details about the software can be provided in the [`desc`](#stanza-desc) stanza. The `name` stanza can be repeated multiple times if there are useful alternative names. The first instance should use the Latin alphabet. For example, see the [`cave-story`](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/c/cave-story.rb#L58-L60) cask, whose original name does not use the Latin alphabet. @@ -968,7 +968,7 @@ Arguments to `uninstall delete:` should use the following basic rules: * Paths must be absolute. * Glob expansion is performed using the [standard set of characters](https://en.wikipedia.org/wiki/Glob_(programming)). -To remove user-specific files, use the [`zap` stanza](#stanza-zap). +To remove user-specific files, use the [`zap`](#stanza-zap) stanza. #### `uninstall` *trash* @@ -1212,7 +1212,7 @@ brew uninstall --zap --force firefox #### `zap` syntax -The form of the `zap` stanza follows the [`uninstall` stanza](#stanza-uninstall). All the same directives are available. The `trash:` key is preferred over `delete:`. +The form of the `zap` stanza follows the [`uninstall`](#stanza-uninstall) stanza. All the same directives are available. The `trash:` key is preferred over `delete:`. Example: [dropbox.rb](https://github.com/Homebrew/homebrew-cask/blob/974a55ade77bb4edc8bbb80ef72eec83ae0e76c0/Casks/d/dropbox.rb#L30-L68) @@ -1304,11 +1304,11 @@ cask "calibre" do end ``` -Such `on_` blocks can be nested and contain other stanzas not listed here. However, they should not contain `depends_on macos:` stanzas, which should occur once below the `on_` blocks and encompass all releases listed in the cask. Examples: [calhash.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/calhash.rb), [openzfs.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/o/openzfs.rb), [r.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/r/r.rb), [wireshark.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/wireshark.rb) +Such `on_` blocks can be nested and contain other stanzas not listed here. However, they should not contain `depends_on macos:` stanzas, which should occur once below the `on_` blocks and encompass all releases listed in the cask. Examples: [calhash.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/calhash.rb), [r.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/r/r.rb), [wireshark.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/wireshark.rb) ### Switch between languages or regions -If a cask is available in multiple languages, you can use the [`language` stanza](#stanza-language) to switch between languages or regions based on the system locale. +If a cask is available in multiple languages, you can use the [`language`](#stanza-language) stanza to switch between languages or regions based on the system locale. ## Arbitrary Ruby methods @@ -1448,7 +1448,7 @@ To convert the App’s simplified name (above) to a token: #### Casks pinned to specific versions -Casks pinned to a specific version of the application (i.e. [`carbon-copy-cloner@5`](https://github.com/Homebrew/homebrew-cask/blob/1b8f44198e5e184c597ee07454a1e10f97f36b15/Casks/c/carbon-copy-cloner%405.rb)) should use the same token as the standard cask with a suffix of `@`. For Carbon Copy Cloner (`carbon-copy-cloner`), pinned to version 5, the token should be `carbon-copy-cloner@5`. +Casks pinned to a specific version of the application (e.g. [`carbon-copy-cloner@5`](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/carbon-copy-cloner%405.rb)) should use the same token as the standard cask with a suffix of `@`. For Carbon Copy Cloner (`carbon-copy-cloner`), pinned to version 6, the token is `carbon-copy-cloner@6`. #### Casks pinned to development channels diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md index cc4d2c122a..6d8c75f622 100644 --- a/docs/Common-Issues.md +++ b/docs/Common-Issues.md @@ -167,7 +167,7 @@ for replacements for deprecated, disabled, or removed formulae. Once you are satisfied with the state of your new `/opt/homebrew` Homebrew installation, you can uninstall the old `/usr/local` installation. -Download and run [the uninstaller](https://github.com/Homebrew/install/#uninstall-homebrew) script: +Download and run the [uninstaller script](https://github.com/Homebrew/install/#uninstall-homebrew): ```sh /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)" -- --path=/usr/local diff --git a/docs/FAQ.md b/docs/FAQ.md index 6dca0305e5..cc1fdbabc5 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -73,7 +73,7 @@ Which is usually: `~/Library/Caches/Homebrew` ## My Mac `.app`s don’t find Homebrew utilities! -GUI apps on macOS don’t have Homebrew's prefix in their `PATH` by default. If you're on Mountain Lion or later, you can fix this by running `sudo launchctl config user path "$(brew --prefix)/bin:${PATH}"` and then rebooting, as documented in `man launchctl`. Note that this sets the `launchctl` `PATH` for *all users*. For earlier versions of macOS, see [this page](https://developer.apple.com/legacy/library/qa/qa1067/_index.html). +GUI apps on macOS don’t have Homebrew's prefix in their `PATH` by default. If you're on Mountain Lion or later, you can fix this by running `sudo launchctl config user path "$(brew --prefix)/bin:${PATH}"` and then rebooting, as documented in `man launchctl`. Note that this sets the `launchctl` `PATH` for *all users*. For earlier versions of macOS, see [this page](https://developer.apple.com/library/archive/qa/qa1067/_index.html). ## How do I contribute to Homebrew? diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index cc2f2feb88..f42e72d859 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -4,7 +4,7 @@ last_review_date: "1970-01-01" # Formula Cookbook -A *formula* is a package definition written in Ruby. It can be created with `brew create ` where `` is a zip or tarball, installed with `brew install `, and debugged with `brew install --debug --verbose `. Formulae use the [Formula API](https://rubydoc.brew.sh/Formula) which provides various Homebrew-specific helpers. +A *formula* is a package definition written in Ruby. It can be created with `brew create ` where `` is a zip or tarball, installed with `brew install `, and debugged with `brew install --debug --verbose `. Formulae use the [`Formula` class API](https://rubydoc.brew.sh/Formula) which provides various Homebrew-specific helpers. * Table of Contents {:toc} @@ -22,7 +22,7 @@ A *formula* is a package definition written in Ruby. It can be created with `bre | **opt prefix** | a symlink to the active version of a **keg** | `/opt/homebrew/opt/foo` | | **Cellar** | directory containing one or more named **racks** | `/opt/homebrew/Cellar` | | **Caskroom** | directory containing one or more named **casks** | `/opt/homebrew/Caskroom` | -| **external command** | `brew` subcommand defined outside of the Homebrew/brew GitHub repository | [`brew alias`](https://github.com/Homebrew/homebrew-aliases) | +| **external command** | `brew` subcommand defined outside of the Homebrew/brew GitHub repository | [`brew test-bot`](https://github.com/Homebrew/homebrew-test-bot) | | **tap** | directory (and usually Git repository) of **formulae**, **casks** and/or **external commands** | `/opt/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 | `/opt/homebrew/Cellar/foo/0.1/INSTALL_RECEIPT.json` | @@ -305,7 +305,7 @@ We want tests that don't require any user input and test the basic functionality See the [`cmake`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/c/cmake.rb) formula for an example of a good test. It writes a basic `CMakeLists.txt` file into the test directory then calls CMake to generate Makefiles. This test checks that CMake doesn't e.g. segfault during basic operation. -You can check that the output is as expected with `assert_equal` or `assert_match` on the output of the [Formula assertions](https://rubydoc.brew.sh/Homebrew/Assertions) such as in this example from the [`envv`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/e/envv.rb) formula: +You can check that the output is as expected with `assert_equal` or `assert_match` on the output of the formula's [assertions](https://rubydoc.brew.sh/Homebrew/Assertions) such as in this example from the [`envv`](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/e/envv.rb) formula: ```ruby assert_equal "mylist=A:C; export mylist", shell_output("#{bin}/envv del mylist B").strip @@ -460,7 +460,7 @@ end ### Standard arguments -For any formula using certain well-known build systems, there will be arguments that should be passed during compilation so that the build conforms to Homebrew standards. These have been collected into a set of `std_*_args` methods. Detailed information about each of those methods can be found in [Rubydoc](https://rubydoc.brew.sh/Formula). +For any formula using certain well-known build systems, there will be arguments that should be passed during compilation so that the build conforms to Homebrew standards. These have been collected into a set of `std_*_args` methods. Detailed information about each of those methods can be found in the [`Formula` class API](https://rubydoc.brew.sh/Formula) documentation. Most of these methods accept parameters to customize their output. For example, to set the install prefix to [**`libexec`**](#variables-for-directory-locations) for `configure` or `cmake`: @@ -592,7 +592,7 @@ Make sure you modify `s`! This block ignores the returned value. [`inreplace`](https://rubydoc.brew.sh/Utils/Inreplace) should be used instead of patches when patching something that will never be accepted upstream, e.g. making the software’s build system respect Homebrew’s installation hierarchy. If it's something that affects both Homebrew and MacPorts (i.e. macOS specific) it should be turned into an upstream submitted patch instead. -If you need to modify variables in a `Makefile`, rather than using [`change_make_var!`](https://rubydoc.brew.sh/StringInreplaceExtension.html#change_make_var!-instance_method) within an [`inreplace`](https://rubydoc.brew.sh/Utils/Inreplace), try passing them as arguments to `make`: +If you need to modify variables in a `Makefile`, rather than using [`change_make_var!`](https://rubydoc.brew.sh/StringInreplaceExtension#change_make_var!-instance_method) within an [`inreplace`](https://rubydoc.brew.sh/Utils/Inreplace), try passing them as arguments to `make`: ```ruby system "make", "target", "VAR2=value1", "VAR2=value2", "VAR3=values can have spaces" @@ -685,7 +685,7 @@ Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formu ## Advanced formula tricks -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! +See the [`Formula` class API](https://rubydoc.brew.sh/Formula) documentation 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 @@ -744,7 +744,7 @@ livecheck do end ``` -For `url`/`regex` guidelines and additional `livecheck` block examples, refer to the [`brew livecheck` documentation](Brew-Livecheck.md). For more technical information on the methods used in a `livecheck` block, please refer to the [`Livecheck` class documentation](https://rubydoc.brew.sh/Livecheck). +For `url`/`regex` guidelines and additional `livecheck` block examples, refer to the [`brew livecheck`](Brew-Livecheck.md) documentation. For more technical information on the methods used in a `livecheck` block, please refer to the [`Livecheck` class](https://rubydoc.brew.sh/Livecheck) documentation. ### Excluding formula from autobumping @@ -756,7 +756,7 @@ Sometimes, we want to exclude a formula from this list, for one reason or anothe no_autobump! because: :bumped_by_upstream ``` -A complete list of allowed symbols can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace.html#NO_AUTOBUMP_REASONS_LIST-constant). +A complete list of allowed symbols can be found in [`NO_AUTOBUMP_REASONS_LIST`](https://rubydoc.brew.sh/top-level-namespace#NO_AUTOBUMP_REASONS_LIST-constant). See our [Autobump](Autobump.md) documentation for more information about the autobump process. @@ -975,7 +975,7 @@ Note that in the context of Homebrew, [`libexec`](https://rubydoc.brew.sh/Formul ### File-level operations -You can use the file utilities provided by Ruby's [`FileUtils`](https://ruby-doc.org/stdlib-2.7.0/libdoc/fileutils/rdoc/FileUtils.html). These are included in the [`Formula`](https://rubydoc.brew.sh/Formula) class, so you do not need the `FileUtils.` prefix to use them. +You can use the file utilities provided by Ruby's [`FileUtils`](https://ruby-doc.org/current/stdlibs/fileutils/FileUtils.html). These are included in the [`Formula` class](https://rubydoc.brew.sh/Formula), so you do not need the `FileUtils.` prefix to use them. When creating symlinks, take special care to ensure they are *relative* symlinks. This makes it easier to create a relocatable bottle. For example, to create a symlink in `bin` to an executable in `libexec`, use: @@ -1286,7 +1286,7 @@ There are also `ENV` helper methods available for many common environment variab * `ENV.remove` - remove a string from an environment variable value * `ENV.delete` - unset an environment variable -The full list can be found in the [SharedEnvExtension](https://rubydoc.brew.sh/SharedEnvExtension.html) and [Superenv](https://rubydoc.brew.sh/Superenv.html) module documentation. +The full list can be found in the [`SharedEnvExtension` module](https://rubydoc.brew.sh/SharedEnvExtension) and [`Superenv` module](https://rubydoc.brew.sh/Superenv) documentation. ### Deprecating and disabling a formula diff --git a/docs/Homebrew-brew-Maintainer-Guide.md b/docs/Homebrew-brew-Maintainer-Guide.md index b02389f256..8d8e7cd54a 100644 --- a/docs/Homebrew-brew-Maintainer-Guide.md +++ b/docs/Homebrew-brew-Maintainer-Guide.md @@ -36,7 +36,7 @@ There are many checks that run on every PR. The following is a quick list of the - `CI / docker`: This builds and deploys a new Homebrew Docker image to GitHub Packages and Docker Hub. - `CI / test everything (macOS)`: This runs several checks on macOS including `brew tests`, `brew update-tests`, `brew test-bot --only-formulae --test-default-formula`, `brew readall` and `brew doctor`. - `CI / tests (generic OS)` and `CI / tests (Linux)`: These run `brew tests` with various options on Linux. -- `Documentation CI / linting` and `rubydoc`: These check the prose and formatting of the written documentation, and verify the [rubydoc API documentation](https://rubydoc.brew.sh) can be built without issue. +- `Documentation CI / linting` and `rubydoc`: These check the prose and formatting of the written documentation, and verify the [Homebrew Ruby API documentation](https://rubydoc.brew.sh/) can be built without issue. _Note that this list is non-exhaustive and can change over time._ diff --git a/docs/Homebrew-homebrew-core-Maintainer-Guide.md b/docs/Homebrew-homebrew-core-Maintainer-Guide.md index 69d797ec48..43b0c26c15 100644 --- a/docs/Homebrew-homebrew-core-Maintainer-Guide.md +++ b/docs/Homebrew-homebrew-core-Maintainer-Guide.md @@ -74,7 +74,7 @@ Don't merge any formula updates with failing `brew test`s. If a `test do` block ## Duplicates -We now accept stuff that comes with macOS as long as it uses `keg_only :provided_by_macos` to be keg-only by default. +We now accept stuff that comes with macOS as long as it uses `keg_only :provided_by_macos` to be [keg-only](FAQ.md#what-does-keg-only-mean) by default. ## Removing formulae diff --git a/docs/Homebrew-on-Linux.md b/docs/Homebrew-on-Linux.md index 1b55fbebea..ba190ab807 100644 --- a/docs/Homebrew-on-Linux.md +++ b/docs/Homebrew-on-Linux.md @@ -22,7 +22,7 @@ The Homebrew package manager may be used on Linux and [Windows Subsystem for Lin ## Install -Instructions for the best, supported install of Homebrew on Linux are on the [homepage](https://brew.sh). +Instructions for the best, supported install of Homebrew on Linux are on the [homepage](https://brew.sh/). The installation script installs Homebrew to `/home/linuxbrew/.linuxbrew` using *sudo*. Homebrew does not use *sudo* after installation. Using `/home/linuxbrew/.linuxbrew` allows the use of most binary packages (bottles) which will not work when installing in e.g. your personal home directory. @@ -51,7 +51,7 @@ If you're using an older distribution of Linux, installing your first package wi ## Requirements -See [Support Tiers](Support-Tiers.md) +See [Support Tiers](Support-Tiers.md#linux) for the full list of Linux requirements. To install build tools, paste at a terminal prompt: diff --git a/docs/How-To-Organize-AGM.md b/docs/How-To-Organize-AGM.md index e27bdc90f3..f8b2b08086 100644 --- a/docs/How-To-Organize-AGM.md +++ b/docs/How-To-Organize-AGM.md @@ -54,7 +54,7 @@ PLC members' roles of responsibility for planning and execution: ## Logistics Timeline -Past practice and future intent is for AGM to coincide with [FOSDEM](https://fosdem.org "Free and Open Source Developers European Meeting"), which is held in Brussels, Belgium annually typically on the Saturday and Sunday of the fifth ISO-8601 week of the calendar year, calculable with: +Past practice and future intent is for AGM to coincide with [FOSDEM](https://fosdem.org "Free and Open Source Developers European Meeting"), which is held in Brussels, Belgium annually typically on the Saturday and Sunday of the fifth ISO 8601 week of the calendar year, calculable with: ruby -rdate -e "s=ARGV[0].to_i;s.upto(s+4).map{|y|Date.commercial(y,5,6)}.each{|y|puts [y,y+1].join(' - ')}" 2024 @@ -156,7 +156,7 @@ It is important that all attendees expecting reimbursement stay in-policy. ### Meeting enhancements -* Captioning or transcription, or both - [White Coat Captioning](https://whitecoatcaptioning.com) could handle the live captioning and provide us that for a transcript. +* Captioning or transcription, or both - [White Coat Captioning](https://whitecoatcaptioning.com/) could handle the live captioning and provide us that for a transcript. * Separate meeting runner * Keep PL ideally focused on content and not agenda or tracking who's asked to speak * Should be a PLC member who is not the AC, LC, or TC diff --git a/docs/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md index 2f3342a4d8..a06a508ced 100644 --- a/docs/How-to-Create-and-Maintain-a-Tap.md +++ b/docs/How-to-Create-and-Maintain-a-Tap.md @@ -18,7 +18,7 @@ See [homebrew/core](https://github.com/Homebrew/homebrew-core) for an example of ### Naming your formulae to avoid clashes -If a formula in your tap has the same name as a Homebrew/homebrew-core formula they cannot be installed side-by-side. If you wish to create a different version of a formula that's in Homebrew/homebrew-core (e.g. with `option`s) consider giving it a different name; e.g. `nginx-full` for a more full-featured `nginx` formula. This will allow both `nginx` and `nginx-full` to be installed at the same time (assuming one is [`keg_only`](https://rubydoc.brew.sh/Formula#keg_only-class_method) or the linked files do not clash). +If a formula in your tap has the same name as a Homebrew/homebrew-core formula they cannot be installed side-by-side. If you wish to create a different version of a formula that's in Homebrew/homebrew-core (e.g. with `option`s) consider giving it a different name; e.g. `nginx-full` for a more full-featured `nginx` formula. This will allow both `nginx` and `nginx-full` to be installed at the same time (assuming one is [keg-only](FAQ.md#what-does-keg-only-mean) or the linked files do not clash). ## Installing @@ -54,7 +54,7 @@ See [Homebrew/test-bot](https://github.com/Homebrew/homebrew-test-bot) for an ex ## Upstream taps -Some upstream software providers like to package their software in their own Homebrew tap. When their software is [eligible for Homebrew/homebrew-core](Acceptable-Formulae.md) we prefer to maintain software there for ease of updates, improved discoverability and use of tools such as [formulae.brew.sh](https://formulae.brew.sh). +Some upstream software providers like to package their software in their own Homebrew tap. When their software is [eligible for Homebrew/homebrew-core](Acceptable-Formulae.md) we prefer to maintain software there for ease of updates, improved discoverability and use of tools such as [formulae.brew.sh](https://formulae.brew.sh/). We are not willing to remove software packaged in Homebrew/homebrew-core in favour of an upstream tap. We are not willing to instruct users of our formulae to use an upstream tap instead. If upstream projects have issues with how Homebrew packages your software: please file issues (or, ideally, pull requests) to address these problems. diff --git a/docs/Installation.md b/docs/Installation.md index 32d1c285e9..dbad1bebfa 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -4,7 +4,7 @@ last_review_date: "2025-04-12" # Installation -Instructions for a supported install of Homebrew are on the [homepage](https://brew.sh). +Instructions for a supported install of Homebrew are on the [homepage](https://brew.sh/). The script installs Homebrew to its default, supported, best prefix (`/opt/homebrew` for Apple Silicon, `/usr/local` for macOS Intel and `/home/linuxbrew/.linuxbrew` for Linux) so that [you don’t need *sudo* after Homebrew's initial installation](FAQ.md#why-does-homebrew-say-sudo-is-bad) when you `brew install`. This prefix is required for most bottles (binary packages) to be used. It is a careful script; it can be run even if you have stuff installed in the preferred prefix already. It tells you exactly what it will do before it does it too. You have to confirm everything it will do before it starts. @@ -21,7 +21,7 @@ The macOS `.pkg` installer also installs Homebrew to its default prefix (`/opt/h ## Advanced Configuration -The Homebrew installer offers various advanced configuration settings. **Most users can skip this section and instead follow the instructions on the [homepage](https://brew.sh)!** +The Homebrew installer offers various advanced configuration settings. **Most users can skip this section and instead follow the instructions on the [homepage](https://brew.sh/)!** ### Git Remote Mirroring @@ -56,7 +56,7 @@ If you want a non-interactive run of the Homebrew installer that doesn't prompt ### Linux or Windows 10 Subsystem for Linux -Check out [the Homebrew on Linux installation documentation](Homebrew-on-Linux.md). +Check out the documentation for installing [Homebrew on Linux](Homebrew-on-Linux.md). ### Untar anywhere (unsupported) @@ -106,11 +106,9 @@ eval "$(/bin/brew shellenv)" Replace `` with the directory where Homebrew is installed on your system. You can find Homebrew's default install location in [this FAQ entry](FAQ.md#why-should-i-install-homebrew-in-the-default-location). -For more insight, re-run the installer or inspect [the installer's source](https://github.com/Homebrew/install/blob/956abfa01f0d1dba285e6d3da86587ed428f19fe/install.sh#L1075-L1091) -to see how the installer constructs the path it recommends. +For more insight, re-run the installer or inspect the [installer's source](https://github.com/Homebrew/install/blob/700c9a145d37a3f0f3bd3b7c208d7adab31bd278/install.sh#L1104-L1120) to see how the installer constructs the path it recommends. -See [this tip in Tips and Tricks](Tips-and-Tricks.md#load-homebrew-from-the-same-dotfiles-on-different-operating-systems) -for another way to handle this across multiple operating systems. +See [this tip in Tips and Tricks](Tips-and-Tricks.md#load-homebrew-from-the-same-dotfiles-on-different-operating-systems) for another way to handle this across multiple operating systems. ## Uninstallation @@ -122,4 +120,4 @@ Uninstallation is documented in the [FAQ](FAQ.md#how-do-i-uninstall-homebrew). 3 You may need to install Xcode, the CLT, or both depending on the formula, to install a bottle (binary package) which is the only supported configuration. Downloading Xcode may require an Apple Developer account on older versions of Mac OS X. Sign up for free at [Apple's website](https://developer.apple.com/account/). -4 The one-liner installation method found on [brew.sh](https://brew.sh) uses the Bourne-again shell at `/bin/bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work. +4 The one-liner installation method found on [brew.sh](https://brew.sh/) uses the Bourne-again shell at `/bin/bash`. Notably, `zsh`, `fish`, `tcsh` and `csh` will not work. diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md index b5aa833df2..e60b2619bb 100644 --- a/docs/Python-for-Formula-Authors.md +++ b/docs/Python-for-Formula-Authors.md @@ -26,7 +26,7 @@ Formulae for apps that require Python 3 **must** declare an unconditional depend Starting with Python@3.12, Homebrew follows [PEP 668](https://peps.python.org/pep-0668/#marking-an-interpreter-as-using-an-external-package-manager). Applications must be installed into a Python [virtual environment](https://docs.python.org/3/library/venv.html) rooted in `libexec`. This prevents the app's Python modules from contaminating the system `site-packages` and vice versa. -All the Python module dependencies of the application (and their dependencies, recursively) should be declared as [`resource`](https://rubydoc.brew.sh/Formula#resource-class_method)s in the formula and installed into the virtual environment as well. Each dependency should be explicitly specified; please do not rely on `setup.py` or `pip` to perform automatic dependency resolution, for the [reasons described here](Acceptable-Formulae.md#we-dont-like-install-scripts-that-download-unversioned-things). +All the Python module dependencies of the application (and their dependencies, recursively) should be [declared as `resource`s](Formula-Cookbook.md#python-dependencies) in the formula and installed into the virtual environment as well. Each dependency should be explicitly specified; please do not rely on `setup.py` or `pip` to perform automatic dependency resolution, for the [reasons described here](Acceptable-Formulae.md#we-dont-like-install-scripts-that-download-unversioned-things). You can use `brew update-python-resources` to help you write resource stanzas. To use it, simply run `brew update-python-resources `. Sometimes, `brew update-python-resources` won't be able to automatically update the resources. If this happens, try running `brew update-python-resources --print-only ` to print the resource stanzas instead of applying the changes directly to the file. You can then copy and paste resources as needed. diff --git a/docs/Querying-Brew.md b/docs/Querying-Brew.md index 2322112133..6e30b06c4f 100644 --- a/docs/Querying-Brew.md +++ b/docs/Querying-Brew.md @@ -60,7 +60,7 @@ brew info --json=v1 --installed | jq "map(select(.keg_only == false and .linked_ ## formulae.brew.sh -[formulae.brew.sh](https://formulae.brew.sh) has a [documented JSON API](https://formulae.brew.sh/docs/api/) which provides access to the `brew info --json=v1` output without needing access to Homebrew. +[formulae.brew.sh](https://formulae.brew.sh/) has a [documented JSON API](https://formulae.brew.sh/docs/api/) which provides access to the `brew info --json=v1` output without needing access to Homebrew. ## Concluding remarks diff --git a/docs/Reproducible-Builds.md b/docs/Reproducible-Builds.md index 200ac5693c..d7a6f2f5fa 100644 --- a/docs/Reproducible-Builds.md +++ b/docs/Reproducible-Builds.md @@ -4,7 +4,7 @@ last_review_date: "1970-01-01" # Reproducible Builds -The Homebrew build environment is designed with [reproducible builds](https://reproducible-builds.org) as a goal where possible. Some convenience tools are also available to formula authors to help achieve deterministic builds. +The Homebrew build environment is designed with [reproducible builds](https://reproducible-builds.org/) as a goal where possible. Some convenience tools are also available to formula authors to help achieve deterministic builds. ## Build time diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md index 838b0fb69a..602947a8f8 100644 --- a/docs/Troubleshooting.md +++ b/docs/Troubleshooting.md @@ -26,7 +26,7 @@ This document will help you check for common issues and make sure your issue has If your problem hasn't been solved or reported, then create an issue: 1. Collect debugging information: - * If you have a problem with installing a formula: run `brew gist-logs ` (where `` is the name of the formula) to upload the logs to a new [Gist](https://gist.github.com). + * If you have a problem with installing a formula: run `brew gist-logs ` (where `` is the name of the formula) to upload the logs to a new [Gist](https://gist.github.com/). * 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: diff --git a/docs/index.md b/docs/index.md index 038c9691a8..b3e37f9ebf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -63,7 +63,7 @@ last_review_date: "2025-02-08" - [Type Checking with Sorbet](Typechecking.md) - [Reproducible Builds](Reproducible-Builds.md) -- [Ruby API Documentation](https://rubydoc.brew.sh) (e.g. for `Formula` etc.) +- [Ruby API Documentation](https://rubydoc.brew.sh/) (e.g. for `Formula` etc.) ## Maintainers diff --git a/docs/vale-styles/Homebrew/Abbreviations.yml b/docs/vale-styles/Homebrew/Abbreviations.yml index f51c2dd53f..2e817a4deb 100644 --- a/docs/vale-styles/Homebrew/Abbreviations.yml +++ b/docs/vale-styles/Homebrew/Abbreviations.yml @@ -12,7 +12,7 @@ swap: 'i\.e\.,': i.e. '(?