diff --git a/docs/Adding-Software-to-Homebrew.md b/docs/Adding-Software-to-Homebrew.md index 70665a3aaf..695d6670a2 100644 --- a/docs/Adding-Software-to-Homebrew.md +++ b/docs/Adding-Software-to-Homebrew.md @@ -1,13 +1,12 @@ # Adding Software To Homebrew -Are you missing your favorite software in Homebrew? Then you're the perfect person to resolve this problem. +Is your favorite 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](https://docs.brew.sh/Formula-Cookbook#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-core/pulls), to make sure no one else beat you to the punch. +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-core/pulls) to make sure no one else beat you to the punch. -Next, you will want to go through the [Acceptable Formulae](Acceptable-Formulae.md) or [Acceptable Casks](Acceptable-Casks.md) documentation to determine if the software is an appropriate addition to Homebrew. If you are creating a formula for an alternative version of software already in Homebrew (for example, a major/minor version that significantly differs from the existing version), be sure to read the [Versions](Versions.md) documentation to understand versioned formulae requirements. +Next, you will want to go through the [Acceptable Formulae](Acceptable-Formulae.md) or [Acceptable Casks](Acceptable-Casks.md) documentation to determine if the software is an appropriate addition to Homebrew. If you are creating a formula for an alternative version of software already in Homebrew (e.g. a major/minor version that differs significantly from the existing version), be sure to read the [Versions](Versions.md) documentation to understand versioned formulae requirements. If everything checks out, you're ready to get started on a new formula! @@ -17,21 +16,21 @@ If everything checks out, you're ready to get started on a new formula! 1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled. -1. If you're starting from scratch, the [`brew create` command](Manpage.md#create-options-url) can be used to produce a basic version of your formula. This command accepts a number of options and you may be able to save yourself some work by using an appropriate template option like `--python`. +1. If you're starting from scratch, you can use the [`brew create` command](Manpage.md#create-options-url) to produce a basic version of your formula. This command accepts a number of options and you may be able to save yourself some work by using an appropriate template option like `--python`. -1. You will now have to work to develop the boilerplate code from `brew create` into a fully-fledged formula. Your main references will be the [Formula Cookbook](Formula-Cookbook.md), similar formulae in Homebrew, and the upstream documentation for your chosen software. Be sure to also take note of the Homebrew documentation for writing [`Python`](Python-for-Formula-Authors.md) and [`Node`](Node-for-Formula-Authors.md) formulae, if applicable. +1. You will now have to develop the boilerplate code from `brew create` into a full-fledged formula. Your main references will be the [Formula Cookbook](Formula-Cookbook.md), similar formulae in Homebrew, and the upstream documentation for your chosen software. Be sure to also take note of the Homebrew documentation for writing [Python](Python-for-Formula-Authors.md) and [Node](Node-for-Formula-Authors.md) formulae, if applicable. -1. Make sure you write a good test as part of your formula. Refer to the "[Add a test to the formula](Formula-Cookbook.md#add-a-test-to-the-formula)" section of the Cookbook for help with this. +1. Make sure you write a good test as part of your formula. Refer to the [Add a test to the formula](Formula-Cookbook.md#add-a-test-to-the-formula) section of the Cookbook for help with this. -1. Try to install the formula using `brew install --build-from-source `, where \ is the name of your formula. If any errors occur, correct your formula and attempt to install it again. The formula should install without errors by the end of this step. +1. Try installing your formula using `brew install --build-from-source `, where \ is the name of your formula. If any errors occur, correct your formula and attempt to install it again. The formula installation should finish without errors by the end of this step. If you're stuck, ask for help on GitHub or [Homebrew/discussions](https://github.com/homebrew/discussions/discussions). The maintainers are very happy to help but we also like to see that you've put effort into trying to find a solution first. ### Testing and auditing the formula -1. Run `brew audit --strict --new-formula --online ` with your formula. If any errors occur, correct them in your formula and run the audit again. The audit should finish without any errors by the end of this step. +1. Run `brew audit --strict --new-formula --online ` with your formula. If any errors occur, correct your formula and run the audit again. The audit should finish without any errors by the end of this step. -1. Run your formula's test using `brew test ` with your formula. Your test should finish without any errors. +1. Run your formula's test using `brew test `. The test should finish without any errors. ### Submitting the formula @@ -41,19 +40,18 @@ If you've made it this far, congratulations on submitting a Homebrew formula! We ## Casks -**Note**: Before taking the time to craft a new cask, make sure -- it can be accepted by checking the [Rejected Casks FAQ](Acceptable-Casks.md#rejected-casks), -- check if the cask was not [already refused]. +**Note:** Before taking the time to craft a new cask: -[already refused]: https://github.com/Homebrew/homebrew-cask/search?q=is%3Aclosed&type=Issues +* make sure it can be accepted by checking the [Rejected Casks FAQ](Acceptable-Casks.md#rejected-casks), and +* check that the cask was not [already refused](https://github.com/Homebrew/homebrew-cask/search?q=is%3Aclosed&type=Issues). ### Writing the cask -Making a new Cask is easy. Follow the directions in [Getting Set Up To Contribute](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#getting-set-up-to-contribute) to begin. +Making a new cask is easy. Follow the directions in [Getting Set Up To Contribute](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#getting-set-up-to-contribute) to begin. #### Examples -Here’s a Cask for `shuttle` 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 `shuttle` 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 "shuttle" do @@ -72,7 +70,7 @@ cask "shuttle" do end ``` -And here is one for `noisy`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check`, which is necessary because the checksum will change on the same `url` when a new distribution is made available. +And here is one for `noisy`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check`, which is necessary because since the download `url` does not contain the version number, its checksum will change when a new version is made available. ```ruby cask "noisy" do @@ -88,7 +86,7 @@ cask "noisy" do end ``` -Here is a last example for `airdisplay`, 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-key-pkgutil), which is needed to uninstall all files which were installed using the installer. +Here is a last example for `airdisplay`, 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-key-pkgutil), 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. @@ -118,33 +116,33 @@ cask "airdisplay" do end ``` -#### Generating a Token for the Cask +#### Generating a token for the cask -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 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 this command: ```bash -$ "$(brew --repository homebrew/cask)/developer/bin/generate_cask_token" '/full/path/to/new/software.app' +$(brew --repository homebrew/cask)/developer/bin/generate_cask_token "/full/path/to/new/software.app" ``` -If the software you wish to Cask is not installed, or does not have an associated App bundle, just give the full proper name of the software instead of a pathname: +If the software you wish to create a cask for is not installed, or does not have an associated App bundle, just give the full proper name of the software instead of a pathname: ```bash -$ "$(brew --repository homebrew/cask)/developer/bin/generate_cask_token" 'Google Chrome' +$(brew --repository homebrew/cask)/developer/bin/generate_cask_token "Google Chrome" ``` If the `generate_cask_token` script does not work for you, see [Cask Token Details](#cask-token-details). -#### The `brew create --cask` Command +#### Creating the cask file -Once you know the token, create your Cask with the handy-dandy `brew create --cask` command: +Once you know the token, create your cask with the handy-dandy `brew create --cask` command: ```bash -$ brew create --cask download-url --set-name my-new-cask +brew create --cask download-url --set-name my-new-cask ``` -This will open `$EDITOR` with a template for your new Cask, to be stored in the file `my-new-cask.rb`. Running the `create` command above will get you a template that looks like this: +This will open `$EDITOR` with a template for your new cask, to be stored in the file `my-new-cask.rb`. Running the `create` command above will get you a template that looks like this: ```ruby cask "my-new-cask" do @@ -160,50 +158,50 @@ cask "my-new-cask" do end ``` -#### Cask Stanzas +#### Cask stanzas -Fill in the following stanzas for your Cask: +Fill in the following stanzas for your cask: | name | value | | ------------------ | ----------- | | `version` | application version -| `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. (see [sha256](Cask-Cookbook.md#stanza-sha256)) +| `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. (see [`sha256` Stanza Details](Cask-Cookbook.md#stanza-sha256)) | `url` | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.
A [`verified` parameter](Cask-Cookbook.md#when-url-and-homepage-domains-differ-add-verified) must be added if the hostnames in the `url` and `homepage` stanzas differ. [Block syntax](Cask-Cookbook.md#using-a-block-to-defer-code-execution) is available for URLs that change on every visit -| `name` | the full and proper name defined by the vendor, and any useful alternate names (see [Name Stanza Details](Cask-Cookbook.md#stanza-name)) -| `desc` | one-line description of the software (see [Desc Stanza Details](Cask-Cookbook.md#stanza-desc)) +| `name` | the full and proper name defined by the vendor, and any useful alternate names (see [`name` Stanza Details](Cask-Cookbook.md#stanza-name)) +| `desc` | one-line description of the software (see [`desc` Stanza Details](Cask-Cookbook.md#stanza-desc)) | `homepage` | application homepage; used for the `brew home` command -| `app` | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [App Stanza Details](Cask-Cookbook.md#stanza-app)) +| `app` | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [`app` Stanza Details](Cask-Cookbook.md#stanza-app)) -Other commonly-used stanzas are: +Other commonly used stanzas are: | name | value | | ------------------ | ----------- | -| `livecheck` | Ruby block describing how to find updates for this Cask (see [Livecheck Stanza Details](Cask-Cookbook.md#stanza-livecheck)) -| `pkg` | relative path to a `.pkg` file containing the distribution (see [Pkg Stanza Details](Cask-Cookbook.md#stanza-pkg)) -| `caveats` | a 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)) -| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [Zap Stanza Details](Cask-Cookbook.md#stanza-zap)) +| `livecheck` | Ruby block describing how to find updates for this cask (see [`livecheck` Stanza Details](Cask-Cookbook.md#stanza-livecheck)) +| `pkg` | relative path to a `.pkg` file containing the distribution (see [`pkg` Stanza Details](Cask-Cookbook.md#stanza-pkg)) +| `caveats` | a 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)) +| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [`zap` Stanza Details](Cask-Cookbook.md#stanza-zap)) -Additional `artifact` stanzas you might need for special use-cases can be found [here](Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required). 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 +#### Cask token details -If a token conflicts with an already-existing Cask, authors should manually make the new token unique by prepending the vendor name. Example: [unison.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/unison.rb) and [panic-unison.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/panic-unison.rb). +If a token conflicts with an already-existing cask, authors should manually make the new token unique by prepending the vendor name. Example: [unison.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/unison.rb) and [panic-unison.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/panic-unison.rb). -If possible, avoid creating tokens which differ only by the placement of hyphens. +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 [token_reference.md](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 +#### Archives with subfolders When a downloaded archive expands to a subfolder, the subfolder name must be included in the `app` value. Example: 1. Texmaker is downloaded to the file `TexmakerMacosxLion.zip`. -2. `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion`. -3. The folder `TexmakerMacosxLion` contains the application `texmaker.app`. -4. So, the `app` stanza should include the subfolder as a relative path: +1. `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion`. +1. The folder `TexmakerMacosxLion` contains the application `texmaker.app`. +1. So, the `app` stanza should include the subfolder as a relative path: ```ruby app "TexmakerMacosxLion/texmaker.app" @@ -218,7 +216,7 @@ export HOMEBREW_NO_AUTO_UPDATE=1 brew install my-new-cask ``` -Did it install? If something went wrong, edit your Cask with `brew edit my-new-cask` to fix it. +Did it install? If something went wrong, edit your cask with `brew edit my-new-cask` to fix it. Test also if the uninstall works successfully: @@ -226,7 +224,7 @@ Test also if the uninstall works successfully: brew uninstall my-new-cask ``` -If everything looks good, you’ll also want to make sure your Cask passes audit with: +If everything looks good, you’ll also want to make sure your cask passes audit with: ```bash brew audit --new-cask my-new-cask @@ -238,17 +236,17 @@ You should also check stylistic details with `brew style`: brew style --fix my-new-cask ``` -Keep in mind all of these checks will be made when you submit your PR, so by doing them in advance you’re saving everyone a lot of time and trouble. +Keep in mind that all these checks will be made when you submit your PR, so by doing them in advance you’re saving everyone a lot of time and trouble. If your application and Homebrew Cask do not work well together, feel free to [file an issue](https://github.com/Homebrew/homebrew-cask#reporting-bugs) after checking out open issues. ### Submitting the cask -#### Finding a Home For Your Cask +#### Finding a home for your cask 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 @@ -267,43 +265,43 @@ $ git checkout -b my-new-cask-branch Switched to a new branch 'my-new-cask-branch' ``` -Stage your Cask with: +Stage your cask with: ```bash -$ git add Casks/my-new-cask.rb +git add Casks/my-new-cask.rb ``` You can view the changes that are to be committed with: ```bash -$ git diff --cached +git diff --cached ``` Commit your changes with: ```bash -$ git commit -v +git commit -v ``` -#### Commit Messages +#### Commit messages -For any git project, some good rules for commit messages are: +For any Git project, some good rules for commit messages are: -* The first line is commit summary, 50 characters or less, +* The first line is the commit summary, 50 characters or less, * Followed by an empty line, * Followed by an explanation of the commit, wrapped to 72 characters. -See [a note about git commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) for more. +See [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) for more. -The first line of a commit message becomes the **title** of a pull request on GitHub, like the subject line of an email. Including the key info in the first line will help us respond faster to your pull. +The first line of a commit message becomes the **title** of a pull request on GitHub, like the subject line of an email. Including the key info in the first line will help us respond faster to your pull request. -For Cask commits in the Homebrew Cask project, we like to include the Application name, version number, and purpose of the commit in the first line. +For cask commits in the Homebrew Cask project, we like to include the application name, version number, and purpose of the commit in the first line. Examples of good, clear commit summaries: * `Add Transmission.app v1.0` * `Upgrade Transmission.app to v2.82` -* `Fix checksum in Transmission.app Cask` +* `Fix checksum in Transmission.app cask` * `Add CodeBox Latest` Examples of difficult, unclear commit summaries: @@ -313,47 +311,45 @@ Examples of difficult, unclear commit summaries: #### Pushing -Push your changes from the branch `my-new-cask-branch` to your GitHub account: +Push your changes on the branch `my-new-cask-branch` to your GitHub account: ```bash -$ git push {{my-github-username}} my-new-cask-branch +git push {{my-github-username}} my-new-cask-branch ``` -If you are using [GitHub two-factor authentication](https://help.github.com/articles/about-two-factor-authentication/) and set your remote repository as HTTPS you will need to set up a personal access token and use that instead of your password. Further information [here](https://help.github.com/articles/https-cloning-errors/#provide-access-token-if-2fa-enabled). +If you are using [GitHub two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa) and have set your remote repository as HTTPS you will need to [set up a personal access token](https://docs.github.com/en/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors#provide-an-access-token) and use that instead of your password. -#### Filing a Pull Request on GitHub +#### Filing a pull request on GitHub -##### a) suggestion from git push +##### a) use suggestion from `git push` -The `git push` command prints a suggestion to create a pull request: +The `git push` command prints a suggestion for how to create a pull request: -``` -remote: Create a pull request for 'new-cask-cask' on GitHub by visiting: -remote: https://github.com/{{my-github-username}}/homebrew-cask/pull/new/my-new-cask-branch -``` + remote: Create a pull request for 'new-cask-cask' on GitHub by visiting: + remote: https://github.com/{{my-github-username}}/homebrew-cask/pull/new/my-new-cask-branch -##### b) use suggestion at Github website +##### b) use suggestion from GitHub's website Now go to the [`homebrew-cask` GitHub repository](https://github.com/Homebrew/homebrew-cask). GitHub will often show your `my-new-cask-branch` branch with a handy button to `Compare & pull request`. -##### c) manually create a pull request at Github website +##### c) manually create a pull request on GitHub -Otherwise, click the `New pull request` button and choose to `compare across forks`. The base fork should be `Homebrew/homebrew-cask @ master`, 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. +Otherwise, click the `Contribute > Open pull request` button and choose to `compare across forks`. The base fork should be `Homebrew/homebrew-cask @ master`, 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! -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). +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). ### Cleaning up -After your Pull Request is submitted, you should get yourself back onto `master`, so that `brew update` will pull down new Casks properly: +After your pull request is submitted, you should get yourself back onto `master`, so that `brew update` will pull down new casks properly: ```bash cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask git checkout master ``` -if you set the variable `HOMEBREW_NO_AUTO_UPDATE` then clean it up with: +If earlier you set the variable `HOMEBREW_NO_AUTO_UPDATE` then clean it up with: ```bash unset HOMEBREW_NO_AUTO_UPDATE diff --git a/docs/Checksum_Deprecation.md b/docs/Checksum_Deprecation.md index a2e49e50ae..633a6d6498 100644 --- a/docs/Checksum_Deprecation.md +++ b/docs/Checksum_Deprecation.md @@ -2,7 +2,7 @@ In early 2015 Homebrew started the process of deprecating _SHA1_ for package integrity verification. Since then formulae under the Homebrew organisation -have been moved onto using _SHA256_ for verification; this includes both source +have been migrated to use _SHA256_ for verification; this includes both source packages and our precompiled packages (bottles). Homebrew has since stopped supporting _SHA1_ and _MD5_ entirely. @@ -14,5 +14,5 @@ We removed _SHA1_ support in **November 2016**, This is enforced in the same way _MD5_ is, by blocking the installation of that individual formula until the checksum is migrated. -This means custom taps, local custom formulae, etc need to be migrated to use +This means custom taps, local custom formulae, etc. need to be migrated to use _SHA256_ before you can install them. diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md index d86484a7f1..c925583965 100644 --- a/docs/Custom-GCC-and-cross-compilers.md +++ b/docs/Custom-GCC-and-cross-compilers.md @@ -1,11 +1,11 @@ # Custom GCC and Cross Compilers -Homebrew depends on having an up-to-date version of Xcode because it comes with specific versions of build tools, e.g. `clang`. Installing a custom version of GCC or Autotools into your `PATH` has the potential to break lots of compiles so we prefer the Apple or Homebrew-provided compilers. Cross-compilers based on GCC will typically be "keg-only" and therefore not linked into your `PATH` by default, or are prefixed with the target architecture, again to avoid conflicting with Apple or Homebrew compilers. +Homebrew depends on having an up-to-date version of Xcode because it comes with specific versions of build tools, e.g. `clang`. Installing a custom version of GCC or Autotools into your `PATH` has the potential to break lots of compiles so we prefer the Apple- or Homebrew-provided compilers. Cross compilers based on GCC will typically be "keg-only" and therefore not linked into your `PATH` by default, or be prefixed with the target architecture, again to avoid conflicting with Apple or Homebrew compilers. -Rather than merging formulae for either of these cases at this time, we're listing them on this page. If you come up with a formula for a new version of GCC or cross-compiler suite, please link it in here. +Rather than merging formulae for either of these cases at this time, we're listing them on this page. If you come up with a formula for a new version of GCC or cross-compiler suite, please link to it here. - Homebrew provides a `gcc` formula for use with Xcode 4.2+. -- Homebrew provides older GCC formulae, e.g. `gcc@7` -- Homebrew provides some cross-compilers and toolchains, but these are named to avoid clashing with the default tools, e.g. `x86_64-elf-gcc` -- Homebrew provides the LLVM Clang, which is bundled with the `llvm` formula. +- Homebrew provides older GCC formulae, e.g. `gcc@7`. +- Homebrew provides some cross-compilers and toolchains, but these are named to avoid clashing with the default tools, e.g. `i686-elf-gcc`, `x86_64-elf-gcc`. +- Homebrew provides LLVM's Clang, which is bundled with the `llvm` formula. - [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V toolchain including binutils and GCC. diff --git a/docs/External-Commands.md b/docs/External-Commands.md index 29b92702a5..46cc807476 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -12,7 +12,7 @@ without modifying Homebrew's internals. External commands come in two flavours: Ruby commands and shell scripts. -In both cases, the command file should be executable (`chmod +x`) and live somewhere in `PATH`. +In both cases, the command file should be executable (`chmod +x`) and live somewhere in your `PATH`. External commands can be added to a tap to allow easy distribution. See [below](#external-commands-in-taps) for more details. @@ -32,13 +32,11 @@ An executable script for a command named `extcmd` should be named `brew-extcmd`. | `HOMEBREW_PREFIX` | Where Homebrew installs software. `/usr/local` by default for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux. | | `HOMEBREW_CELLAR` | The location of the Homebrew Cellar, where software is staged. This will be `HOMEBREW_PREFIX/Cellar` if that directory exists, or `HOMEBREW_REPOSITORY/Cellar` otherwise. | | `HOMEBREW_LIBRARY_PATH`| The directory containing Homebrew’s own application code. | -| `HOMEBREW_REPOSITORY` | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory`. | +| `HOMEBREW_REPOSITORY` | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory. | ## Providing `--help` -All internal and external Homebrew commands can provide styled `--help` output by using lines starting with `#:` (a comment then `:` character in both Bash and Ruby) which are then output by `--help`. - -For example, see the [header of `brew-services.rb`](https://github.com/Homebrew/homebrew-services/blob/a58a1fe9145de4e50e1cbfb5b0e8a30087826393/cmd/brew-services.rb#L1-L23) which is output with `brew services --help`. +All internal and external Homebrew commands can provide styled `--help` output by using Homebrew’s [argument parser](https://rubydoc.brew.sh/Homebrew/CLI/Parser.html), as seen in the [`brew services` command](https://github.com/Homebrew/homebrew-services/blob/HEAD/cmd/services.rb); or by including lines starting with `#:` (a comment then `:` character in both Bash and Ruby), as seen in the [header of `update.sh`](https://github.com/Homebrew/brew/blob/cf7def0c68903814c6b4e04a55fe8f3cb3f5605e/Library/Homebrew/cmd/update.sh#L1-L10), which is printed with `brew update --help`. ## Unofficial external commands @@ -58,7 +56,7 @@ External commands can be hosted in a [tap](Taps.md) to allow users to easily ins External commands should be added to a `cmd` directory in the tap. An external command `extcmd` implemented as a Ruby command should live in `cmd/extcmd.rb` (don't forget to `chmod +x`). -To easily use Homebrew's argument parser, follow the following Ruby template for external commands (replacing all instances of `foo` with the name of the command): +To easily use Homebrew's argument parser, replicate the following Ruby template for external commands (replacing all instances of `foo` with the name of the command): ```ruby # frozen_string_literal: true @@ -111,7 +109,7 @@ Do something. Place a description here. The usage string is automatically generated based on the specified number and type of named arguments (see below for more details on specifying named arguments). The generated usage string can be overridden by passing the correct usage string to the `usage_banner` method (placed just before the `description` method). See the [`brew tap` command](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/cmd/tap.rb) for an example. -Use the `named_args` method to specify the type and number of named arguments that are expected. Pass either a symbol to indicate the type of argument expected, an array of symbols to indicate that multiple types should be expected, or an array of strings to specify which specific options should be expected (see the [`brew analytics`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/cmd/analytics.rb) command for an example of this). +Use the `named_args` method to specify the type and number of named arguments that are expected. Pass either a symbol to indicate the type of argument expected, an array of symbols to indicate that multiple types should be expected, or an array of strings to specify which specific options should be expected (see the [`brew analytics` command](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/cmd/analytics.rb) for an example of this). Pass an integer to the `number`, `min`, or `max` parameter of `named_args` to specify the number of named arguments that are expected. See the following examples: diff --git a/docs/Gems,-Eggs-and-Perl-Modules.md b/docs/Gems,-Eggs-and-Perl-Modules.md index 59ec3f6d5a..c187f90b73 100644 --- a/docs/Gems,-Eggs-and-Perl-Modules.md +++ b/docs/Gems,-Eggs-and-Perl-Modules.md @@ -7,9 +7,11 @@ add-ons available to all users: * `/Library/Python` * `/Library/Perl` -You need `sudo` to install to these like so: `sudo gem install`, +You need sudo to install to these like so: `sudo gem install`, `sudo easy_install` or `sudo cpan -i`. +## Python packages (eggs) without sudo using system Python + An option to avoid sudo is to use an access control list. For example: ```sh @@ -28,14 +30,14 @@ writable location. But if you installed Homebrew as we recommend on macOS Intel, `/usr/local` will be writable without sudo. So now you are good to install the development tools you need without risking the use of sudo. -### Python packages (eggs) without sudo using system’s Python +### An alternative package path _This is only recommended if you **don't** use a brewed Python._ -On macOS, any [Python version X.Y also searches in +On macOS, any Python version X.Y [also searches in `~/Library/Python/X.Y/lib/python/site-packages` for -modules](https://docs.python.org/2/install/index.html#inst-alt-install-user). -That dir might not yet exist, but you can create it: +modules](https://docs.python.org/2/install/index.html#alternate-installation-the-user-scheme). +That path might not yet exist, but you can create it: ```sh mkdir -p ~/Library/Python/2.7/lib/python/site-packages @@ -45,26 +47,24 @@ To teach `easy_install` and `pip` to install there, either use the `--user` switch or create a `~/.pydistutils.cfg` file with the following content: -``` -[install] -install_lib = ~/Library/Python/$py_version_short/lib/python/site-packages -``` + [install] + install_lib = ~/Library/Python/$py_version_short/lib/python/site-packages ### Using virtualenv (with system Python) [Virtualenv](https://virtualenv.pypa.io/) ships `pip` and -creates isolated Python environments with separate site-packages, -therefore you won’t need sudo. +creates isolated Python environments with separate `site-packages`, +which therefore don’t need sudo. ## Rubygems without sudo -**If you use rbenv or RVM then you should ignore this stuff** +_This is only recommended if you **don't** use rbenv or RVM._ Brewed Ruby installs executables to `$(brew --prefix)/opt/ruby/bin` without sudo. You should add this to your path. See the caveats in the `ruby` formula for up-to-date information. -### With system’s Ruby +### With system Ruby To make Ruby install to `/usr/local`, we need to add `gem: -n/usr/local/bin` to your `~/.gemrc`. It’s YAML, so do it manually @@ -83,7 +83,7 @@ rubygems as root: sudo gem update --system ``` -### An alternative +### An alternative gem path Just install everything into the Homebrew prefix like this: @@ -93,20 +93,20 @@ echo "export GEM_HOME=\"$(brew --prefix)\"" >> ~/.bashrc ### It doesn’t work! I get some “permissions” error when I try to install stuff! -*Note, maybe you shouldn’t do this on Lion, since Apple has decided it -is not a good default.* +_Note that you may not want to do this, since Apple has decided it +is not a good default._ If you ever did a `sudo gem`, etc. before then a lot of files will have been created owned by root. Fix with: ```sh -sudo chown -R $(whoami) /Library/Ruby /Library/Perl /Library/Python +sudo chown -R $(whoami) /Library/Ruby/* /Library/Perl/* /Library/Python/* ``` ## Perl CPAN modules without sudo The Perl module `local::lib` works similarly to rbenv/RVM (although for -modules only, not perl installations). A simple solution that only +modules only, not Perl installations). A simple solution that only pollutes your `/Library/Perl` a little is to install [`local::lib`](https://metacpan.org/pod/local::lib) with sudo: @@ -116,7 +116,7 @@ sudo cpan local::lib Note that this will install some other dependencies like `Module::Install`. Then put the appropriate incantation in your shell’s startup, e.g. for -`.profile` you insert the below, for others see the +`.profile` you'd insert the below; for others see the [`local::lib`](https://metacpan.org/pod/local::lib) docs. ```sh @@ -125,7 +125,7 @@ eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)" Now (after you restart your shell) `cpan` or `perl -MCPAN -eshell` etc. will install modules and binaries in `~/perl5` and the relevant -subdirectories will be in your `PATH` and `PERL5LIB` etc. +subdirectories will be in your `PATH` and `PERL5LIB`. ### Avoiding sudo altogether for Perl diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md index d2c117073c..c255cd8037 100644 --- a/docs/Homebrew-and-Python.md +++ b/docs/Homebrew-and-Python.md @@ -4,23 +4,21 @@ This page describes how Python is handled in Homebrew for users. See [Python for Homebrew should work with any [CPython](https://stackoverflow.com/questions/2324208/is-there-any-difference-between-cpython-and-python) and defaults to the macOS system Python. -Homebrew provides formulae to brew Python 3.x. - -Homebrew provided a `python@2` formula until the end of 2019, at which point it was removed due to the Python 2 deprecation. +Homebrew provides formulae to brew Python 3.y. A `python@2` formula was provided until the end of 2019, at which point it was removed due to the Python 2 deprecation. **Important:** If you choose to use a Python which isn't either of these two (system Python or brewed Python), the Homebrew team cannot support any breakage that may occur. -## Python 3.x +## Python 3.y -Homebrew provides a formula for Python 3.x (`python@3.x`). +Homebrew provides formulae for maintained releases of Python 3.y (`python@3.y`). -**Important**: Python may be upgraded to a newer version at any time. Consider using a version +**Important:** Python may be upgraded to a newer version at any time. Consider using a version manager such as `pyenv` if you require stability of minor or patch versions for virtual environments. The executables are organised as follows: -* `python3` points to Homebrew's Python 3.x (if installed) -* `pip3` points to Homebrew's Python 3.x's pip (if installed) +* `python3` points to Homebrew's Python 3.y (if installed) +* `pip3` points to Homebrew's Python 3.y's pip (if installed) Unversioned symlinks for `python`, `python-config`, `pip` etc. are installed here: @@ -30,7 +28,7 @@ $(brew --prefix)/opt/python/libexec/bin ## Setuptools, Pip, etc. -The Python formulae install [pip](https://pip.pypa.io/) (as `pip3`) and [Setuptools](https://pypi.python.org/pypi/setuptools). +The Python formulae install [pip](https://pip.pypa.io/) (as `pip3`) and [Setuptools](https://pypi.org/project/setuptools/). Setuptools can be updated via pip3, without having to re-brew Python: @@ -46,7 +44,7 @@ python3 -m pip install --upgrade pip ## `site-packages` and the `PYTHONPATH` -The `site-packages` is a directory that contains Python modules (especially bindings installed by other formulae). Homebrew creates it here: +The `site-packages` is a directory that contains Python modules, including bindings installed by other formulae. Homebrew creates it here: ```sh $(brew --prefix)/lib/pythonX.Y/site-packages @@ -59,7 +57,7 @@ Python 3.y also searches for modules in: * `/Library/Python/3.y/site-packages` * `~/Library/Python/3.y/lib/python/site-packages` -Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`. +Homebrew's `site-packages` directory is first created (1) once any Homebrew formulae with Python bindings are installed, or (2) upon `brew install python`. ### Why here? @@ -69,19 +67,19 @@ The reasoning for this location is to preserve your modules between (minor) upgr Some formulae provide Python bindings. -**Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import ` from a brewed Python if you ran `brew install ` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with Python bindings (e.g. `pyside`, `wxwidgets`, `pygtk`, `pygobject`, `opencv`, `vtk` and `boost-python`). +**Warning!** Python may crash (see [Common Issues](Common-Issues.md)) when you `import ` from a brewed Python if you ran `brew install ` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with Python bindings (e.g. `pyside`, `wxwidgets`, `pyqt`, `pygobject3`, `opencv`, `vtk` and `boost-python`). ## Policy for non-brewed Python bindings -These should be installed via `pip install `. To discover, you can use `pip search` or . +These should be installed via `pip install `. To discover, you can use `pip search` or . -**Note:** macOS's system Python does not provide `pip`. Follow the [pip documentation](https://pip.readthedocs.io/en/stable/installing/#install-pip) to install it for your system Python if you would like it. +**Note:** macOS's system Python does not provide `pip`. Follow the [pip documentation](https://pip.pypa.io/en/stable/installation/) to install it for your system Python if you would like it. ## Brewed Python modules For brewed Python, modules installed with `pip3` or `python3 setup.py install` will be installed to the `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable Python scripts will be in `$(brew --prefix)/bin`. -The system Python may not know which compiler flags to set in order to build bindings for software installed in Homebrew so you may need to run: +Since the system Python may not know which compiler flags to set when building bindings for software installed by Homebrew, you may need to run: ```sh CFLAGS="-I$(brew --prefix)/include" LDFLAGS="-L$(brew --prefix)/lib" pip install @@ -89,13 +87,13 @@ CFLAGS="-I$(brew --prefix)/include" LDFLAGS="-L$(brew --prefix)/lib" pip install ## Virtualenv -**WARNING:** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**. +**Warning!** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**. Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window. -Homebrew will still install Python modules into Homebrew's `site-packages` and *not* into the virtual environment's site-package. +This will ensure Python modules are installed into Homebrew's `site-packages` and *not* into that of the virtual environment. Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv. ## Why is Homebrew's Python being installed as a dependency? -Formulae that declare an unconditional dependency on the `"python"` formula are bottled against Homebrew's Python 3.x and require it to be installed. +Formulae that declare an unconditional dependency on the `python` formula are bottled against Homebrew's Python 3.y and require it to be installed. diff --git a/docs/Homebrew-on-Linux.md b/docs/Homebrew-on-Linux.md index e2a4c4eef9..f3a3e3f31b 100644 --- a/docs/Homebrew-on-Linux.md +++ b/docs/Homebrew-on-Linux.md @@ -33,8 +33,8 @@ Follow the *Next steps* instructions to add Homebrew to your `PATH` and to your ```sh test -d ~/.linuxbrew && eval "$(~/.linuxbrew/bin/brew shellenv)" test -d /home/linuxbrew/.linuxbrew && eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" -test -r ~/.bash_profile && echo "eval \"\$($(brew --prefix)/bin/brew shellenv)\"" >>~/.bash_profile -echo "eval \"\$($(brew --prefix)/bin/brew shellenv)\"" >>~/.profile +test -r ~/.bash_profile && echo "eval \"\$($(brew --prefix)/bin/brew shellenv)\"" >> ~/.bash_profile +echo "eval \"\$($(brew --prefix)/bin/brew shellenv)\"" >> ~/.profile ``` You're done! Try installing a package: diff --git a/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md b/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md index 7bbd82d94c..06ae20af9d 100644 --- a/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md +++ b/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md @@ -8,11 +8,11 @@ As an example: *OpenSSL isn’t symlinked into my `PATH` and non-Homebrew builds can’t find it!* -This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location. +This is because Homebrew isolates it within its individual prefix, rather than symlinking to the publicly available location. ## Advice on potential workarounds -A number of people in this situation are either forcefully linking `keg_only` tools with `brew link --force` or moving default system utilities out of the `PATH` and replacing them with manually-created symlinks to the Homebrew-provided tool. +A number of people in this situation are either forcefully linking keg-only tools with `brew link --force` or moving default system utilities out of the `PATH` and replacing them with manually created symlinks to the Homebrew-provided tool. *Please* do not remove macOS native tools and forcefully replace them with symlinks back to the Homebrew-provided tool. Doing so can and likely will cause significant breakage when attempting to build software. @@ -20,7 +20,7 @@ A number of people in this situation are either forcefully linking `keg_only` to ## How do I use those tools outside of Homebrew? -Useful, reliable alternatives exist should you wish to use `keg_only` tools outside of Homebrew. +Useful, reliable alternatives exist should you wish to use keg-only tools outside of Homebrew. ### Build flags @@ -44,13 +44,13 @@ You can temporarily prepend your `PATH` with the tool’s `bin` directory, such export PATH="$(brew --prefix)/opt/openssl/bin:${PATH}" ``` -This will prepend that folder to your `PATH`, ensuring any build script that searches the `PATH` will find it first. +This will prepend the directory to your `PATH`, ensuring any build script that searches the `PATH` will find it first. -Changing your `PATH` using that command ensures the change only exists for the duration of that shell session. Once you are no longer in that session, the `PATH` reverts to the prior state. +Changing your `PATH` using this command ensures the change only exists for the duration of the shell session. Once the current session ends, the `PATH` reverts to its prior state. ### `pkg-config` detection -If the tool you are attempting to build is [pkg-config](https://en.wikipedia.org/wiki/Pkg-config) aware, you can amend your `PKG_CONFIG_PATH` to find that `keg_only` utility’s `.pc` file, if it has them. Not all formulae ship with those files. +If the tool you are attempting to build is [pkg-config](https://en.wikipedia.org/wiki/Pkg-config) aware, you can amend your `PKG_CONFIG_PATH` to find a keg-only utility’s `.pc` files, if it has any. Not all formulae ship with these files. An example of this is: @@ -58,9 +58,9 @@ An example of this is: export PKG_CONFIG_PATH="$(brew --prefix)/opt/openssl/lib/pkgconfig" ``` -If you’re curious about the `PKG_CONFIG_PATH` variable `man pkg-config` goes into more detail. +If you’re curious about the `PKG_CONFIG_PATH` variable, `man pkg-config` goes into more detail. -You can get `pkg-config` to detail the default search path with: +You can get `pkg-config` to print the default search path with: ```sh pkg-config --variable pc_path pkg-config diff --git a/docs/Kickstarter-Supporters.md b/docs/Kickstarter-Supporters.md index 458cb83969..050a2ae258 100644 --- a/docs/Kickstarter-Supporters.md +++ b/docs/Kickstarter-Supporters.md @@ -1,12 +1,8 @@ # Kickstarter Supporters -This file contains a list of the awesome people who gave £5 or more to -[our Kickstarter](https://www.kickstarter.com/projects/homebrew/brew-test-bot). +This file contains a list of the awesome people who gave £5 or more to [our Kickstarter](https://www.kickstarter.com/projects/homebrew/brew-test-bot). -This list is still incomplete as we need addresses for everyone who receives -a physical reward. Kickstarter recommends asking only when we are ready to -ship (to avoid changes of address) so we can't ask for more names/URLs -until then. +This list is still incomplete as we need addresses for everyone who receives a physical reward. Kickstarter recommends asking only when we are ready to ship (to avoid changes of address) so we can't ask for more names/URLs until then. These mind-blowing people supported our Kickstarter by giving us £450 or more: diff --git a/docs/Querying-Brew.md b/docs/Querying-Brew.md index 625eaffdee..32ef43516d 100644 --- a/docs/Querying-Brew.md +++ b/docs/Querying-Brew.md @@ -6,17 +6,17 @@ _In this document we will be using [jq](https://stedolan.github.io/jq/) to parse `brew` provides commands for getting common types of information out of the system. `brew list` shows installed formulae. `brew deps foo` shows the dependencies that `foo` needs. -Additional commands, including external commands, can of course be written to provide more detailed information. There are a couple of disadvantages here. First, it means writing Ruby against a possibly changing Homebrew codebase. There will be more code to touch during refactors, and Homebrew can't guarantee that external commands will continue to work. Second, it means designing the commands themselves, specifying input parameters and output formats. +Additional commands, including external commands, can of course be written to provide more detailed information. There are a couple of disadvantages here. First, it requires writing Ruby against a possibly changing Homebrew codebase. There will be more code to touch during refactors, and Homebrew can't guarantee that external commands will continue to work. Second, it requires designing the commands themselves, specifying input parameters and output formats. To enable users to do rich queries without the problems above, Homebrew provides the `brew info` command. ## `brew info --json` -`brew info` outputs JSON-formatted information about formulae. This JSON can then be parsed using your tools of choice. See more details in `brew info --help`. +`brew info` can output JSON-formatted information about formulae. This JSON can then be parsed using your tools of choice. See more details in `brew info --help`. -The current schema version is `v1`. Note that fields may be added to the schema as needed without incrementing the schema. Any significant breaking changes will cause a change to the schema version. +The default schema version is `v1`, which returns info about formulae; specify `--json=v2` to include both formulae and casks. Note that fields may be added to the schema as needed without incrementing the schema. Any significant breaking changes will cause a change to the schema version. -The schema itself is not currently documented outside of the code in [`formula.rb`](https://github.com/Homebrew/brew/blob/e9b9ea49a16b7879731d01ff2842460d33257a06/Library/Homebrew/formula.rb#L1594-L1680) that generates it. +The schema itself is not currently documented outside of the code in [`formula.rb`](https://github.com/Homebrew/brew/blob/2e6b6ab3a20da503ba2a22a37fdd6bd936d818ed/Library/Homebrew/formula.rb#L1922-L2017) that generates it. ## Examples @@ -66,6 +66,6 @@ brew info --json=v1 --installed | jq "map(select(.keg_only == false and .linked_ ## Concluding remarks -Using the JSON output, queries can be made against Homebrew with less risk of being broken due to Homebrew code changes, and without needing to understand Homebrew's Ruby internals. +By using the JSON output, queries can be made against Homebrew with less risk of being broken due to Homebrew code changes, and without needing to understand Homebrew's Ruby internals. If the JSON output does not provide some information that it ought to, please submit a request, preferably with a patch to add the desired information. diff --git a/docs/Updating-Software-in-Homebrew.md b/docs/Updating-Software-in-Homebrew.md index 71bcca5fd7..43e067a42d 100644 --- a/docs/Updating-Software-in-Homebrew.md +++ b/docs/Updating-Software-in-Homebrew.md @@ -2,9 +2,9 @@ Did you find something in Homebrew that wasn't the latest version? You can help yourself and others by submitting a pull request to update the formula. -First, check the pull requests in the Homebrew tap repositories to make sure a PR isn't already open. If you're submitting a [formula](https://docs.brew.sh/Formula-Cookbook#homebrew-terminology), check [homebrew-core](https://github.com/Homebrew/homebrew-core/pulls). If you're submitting a [cask](https://docs.brew.sh/Formula-Cookbook#homebrew-terminology), check [homebrew-cask](https://github.com/Homebrew/homebrew-cask/pulls). You may also want to look through closed pull requests in the repositories, as sometimes packages run into problems preventing them from being updated and it's better to be aware of any issues before putting significant effort into an update. +First, check the pull requests in the Homebrew tap repositories to make sure a PR isn't already open. If you're submitting a [formula](Formula-Cookbook.md#homebrew-terminology), check [homebrew-core](https://github.com/Homebrew/homebrew-core/pulls). If you're submitting a [cask](Formula-Cookbook.md#homebrew-terminology), check [homebrew-cask](https://github.com/Homebrew/homebrew-cask/pulls). You may also want to look through closed pull requests in the repositories, as sometimes packages run into problems preventing them from being updated and it's better to be aware of any issues before putting significant effort into an update. -The [How To Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation should explain most everything you need to know about the process of creating a PR for a version update. For simple updates, this typically involves changing the URL and sha256. +The [How To Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation should explain most everything you need to know about the process of creating a PR for a version update. For simple updates, this typically involves changing the URL and SHA256 values. However, some updates require additional changes to the package. You can look back at previous pull requests to see how others have handled things in the past but be sure to look at a variety of PRs. Sometimes packages aren't updated properly, so you may need to use your judgment to determine how to best proceed. diff --git a/docs/Xcode.md b/docs/Xcode.md index d3a8f15eb0..4f12da1f6a 100644 --- a/docs/Xcode.md +++ b/docs/Xcode.md @@ -2,13 +2,11 @@ ## Supported Xcode versions -Homebrew supports and recommends the latest Xcode and/or Command Line -Tools available for your platform (see `OS::Mac::Xcode.latest_version` and `OS::Mac::CLT.latest_clang_version` in [`Library/Homebrew/os/mac/xcode.rb`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/os/mac/xcode.rb)). +Homebrew supports and recommends the latest Xcode and/or Command Line Tools available for your platform (see `OS::Mac::Xcode.latest_version` and `OS::Mac::CLT.latest_clang_version` in [`Library/Homebrew/os/mac/xcode.rb`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/os/mac/xcode.rb)). ## Updating for new Xcode releases -When a new Xcode release is made, the following things need to be -updated: +When a new Xcode release is made, the following things need to be updated: * In [`Library/Homebrew/os/mac/xcode.rb`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/os/mac/xcode.rb) * `OS::Mac::Xcode.latest_version`