diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md index 24dd7a7c4c..d9606aa28c 100644 --- a/docs/Acceptable-Formulae.md +++ b/docs/Acceptable-Formulae.md @@ -53,19 +53,19 @@ Because that circumvents our hash-checks, makes finding/fixing bugs harder, often breaks patches and disables the caching. Almost always you can add a resource to the formula file to handle the separate download and then the installer script will not attempt to load -that stuff on demand. Or there is a command line switch where you can +that stuff on demand. Or there is a command-line switch where you can point it to the downloaded archive in order to avoid loading. ### We don’t like binary formulae Our policy is that formulae in the core repository ([homebrew/core](https://github.com/Homebrew/homebrew-core)) must be open-source -and either built from source or produce cross-platform binaries (like e.g. Java). +and either built from source or produce cross-platform binaries (e.g. Java). Binary-only formulae should go to [Homebrew Cask](https://github.com/caskroom/homebrew-cask). ### Stable versions Formulae in the core repository must have a stable version tagged by -the upstream project. Tarballs are preferred to git checkouts, and +the upstream project. Tarballs are preferred to Git checkouts, and tarballs should include the version in the filename whenever possible. We don’t accept software without a tagged version because they regularly break @@ -78,9 +78,9 @@ etc. If not, then put bindings in the formula they bind to. This is more useful to people. Just install the stuff! Having to faff around with -foo-ruby foo-perl etc. sucks. +foo-ruby, foo-perl etc. sucks. -### Niche (or self-submitted) Stuff +### Niche (or self-submitted) stuff The software in question must be: * maintained (e.g. upstream is still making new releases) @@ -94,9 +94,9 @@ get maintained and partly because we have to draw the line somewhere. We frown on authors submitting their own work unless it is very popular. -Don’t forget Homebrew is all `git` underneath! Maintain your tap if you have to! +Don’t forget Homebrew is all Git underneath! Maintain your own tap if you have to! -There may be exceptions to these rules in the main repository, we may +There may be exceptions to these rules in the main repository; we may include things that don't meet these criteria or reject things that do. Please trust that we need to use our discretion based on our experience running a package manager. @@ -110,5 +110,5 @@ Make it build a command-line tool or a library. ### Sometimes there are exceptions Even if all criteria are met we may not accept the formula. Documentation tends to lag behind current decision-making. Although some -rejections may seem arbitrary or strange they are based from years of +rejections may seem arbitrary or strange they are based on years of experience making Homebrew work acceptably for our users. diff --git a/docs/Analytics.md b/docs/Analytics.md index 40902403b0..69ab0b58f5 100644 --- a/docs/Analytics.md +++ b/docs/Analytics.md @@ -5,29 +5,29 @@ Homebrew has begun gathering anonymous aggregate user behaviour analytics and re ## Why? Homebrew is provided free of charge and run entirely by volunteers in their spare time. As a result, we do not have the resources to do detailed user studies of Homebrew users to decide on how best to design future features and prioritise current work. Anonymous aggregate user analytics allow us to prioritise fixes and features based on how, where and when people use Homebrew. For example: -- if a formula is widely used and is failing often it will enable us to prioritise fixing that formula over others. -- collecting the OS version allows us to decide what versions of macOS to prioritise and support and identify build failures that occur only on single versions. +- If a formula is widely used and is failing often it will enable us to prioritise fixing that formula over others. +- Collecting the OS version allows us to decide what versions of macOS to prioritise and support and identify build failures that occur only on single versions. ## What? Homebrew's analytics record some shared information for every event: -- The Homebrew user agent e.g. `Homebrew/0.9.9 (Macintosh; Intel macOS 10.12.0) curl/7.43.0` -- The Google Analytics version i.e. `1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#v) -- The Homebrew analytics tracking ID e.g. `UA-75654628-1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#tid) -- A Homebrew analytics user ID e.g. `1BAB65CC-FE7F-4D8C-AB45-B7DB5A6BA9CB`. This is generated by `uuidgen` and stored in the repository-specific Git configuration variable `homebrew.analyticsuuid` within `$(brew --repository)/.git/config`. This does not allow us to track individual users but does enable us to accurately measure user counts vs. event counts (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#cid) -- The Google Analytics anonymous IP setting is enabled i.e. `1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#aip) -- The Homebrew application name e.g. `Homebrew` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an) -- The Homebrew application version e.g. `0.9.9` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#av) -- The Homebrew analytics hit type e.g. `screenview` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#t) +- The Homebrew user agent, e.g. `Homebrew/0.9.9 (Macintosh; Intel macOS 10.12.0) curl/7.43.0` +- The Google Analytics version, i.e. `1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#v) +- The Homebrew analytics tracking ID, e.g. `UA-75654628-1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#tid) +- A Homebrew analytics user ID, e.g. `1BAB65CC-FE7F-4D8C-AB45-B7DB5A6BA9CB`. This is generated by `uuidgen` and stored in the repository-specific Git configuration variable `homebrew.analyticsuuid` within `$(brew --repository)/.git/config`. This does not allow us to track individual users but does enable us to accurately measure user counts vs. event counts (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#cid) +- If the Google Analytics anonymous IP setting is enabled, i.e. `1` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#aip) +- The Homebrew application name, e.g. `Homebrew` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an) +- The Homebrew application version, e.g. `0.9.9` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#av) +- The Homebrew analytics hit type, e.g. `screenview` (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#t) Homebrew's analytics records the following different events: -- a `screenview` hit type with the official Homebrew command you have run (with arguments stripped) e.g. `brew list` (not `brew list foo` or any external commands except `bundle` and `services`) -- an `event` hit type with the `install` event category, the Homebrew formula from a non-private GitHub tap you have requested to install and any used options e.g. `wget --with-pcre` as the action and an event label e.g. `macOS 10.12, non-/usr/local, CI` to indicate the OS version, non-standard installation location and invocation as part of CI. This allows us to identify formulae that need fixed and where more easily. -- an `event` hit type with the `BuildError` event category, the Homebrew formula that failed to install e.g. `wget` as the action and an event label e.g. `macOS 10.12` -- an `exception` hit type with the `exception` event category, exception description of the exception name e.g. `FormulaUnavailableError` and whether the exception was fatal e.g. `1` +- a `screenview` hit type with the official Homebrew command you have run (with arguments stripped), e.g. `brew list` (not `brew list foo` or any external commands except `bundle` and `services`) +- an `event` hit type with the `install` event category and the Homebrew formula from a non-private GitHub tap you have requested to install plus any used options, e.g. `wget --with-pcre` as the action and an event label e.g. `macOS 10.12, non-/usr/local, CI` to indicate the OS version, non-standard installation location and invocation as part of CI. This allows us to identify the formulae that need fixing and where more easily. +- an `event` hit type with the `BuildError` event category and the Homebrew formula that failed to install, e.g. `wget` as the action and an event label e.g. `macOS 10.12` +- an `exception` hit type with the `exception` event category and exception description of the exception name, e.g. `FormulaUnavailableError` and whether the exception was fatal e.g. `1` -You can also view all the information that is sent by Homebrew's analytics by setting `HOMEBREW_ANALYTICS_DEBUG=1` in your environment. Please note this will also stop any analytics being sent. +You can also view all the information that is sent by Homebrew's analytics by setting `HOMEBREW_ANALYTICS_DEBUG=1` in your environment. Please note this will also stop any analytics from being sent. It is impossible for the Homebrew developers to match any particular event to any particular user, even if we had access to the Homebrew analytics user ID (which we do not). An example of the most user-specific information we can see from Google Analytics: @@ -39,7 +39,7 @@ As far as we can tell it would be impossible for Google to match the randomly ge Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS. ## Who? -Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @mikemcquaid if you are a maintainer and need access. +Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @MikeMcQuaid if you are a maintainer and need access. ## How? The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection. diff --git a/docs/Bottles.md b/docs/Bottles.md index 2752ebe032..983fbc5372 100644 --- a/docs/Bottles.md +++ b/docs/Bottles.md @@ -3,9 +3,9 @@ Bottles are produced by installing a formula with `brew install --build-bottle $FORMULA` and then bottling it with `brew bottle $FORMULA`. This outputs the bottle DSL which should be inserted into the formula file. ## Usage -If a bottle is available and usable it will be downloaded and poured automatically when you `brew install `. If you wish to disable this you can do it by specifying `--build-from-source`. +If a bottle is available and usable it will be downloaded and poured automatically when you `brew install `. If you wish to disable this you can do so by specifying `--build-from-source`. -Bottles will not be used if the user requests it (see above), if the formula requests it (with `pour_bottle?`), if any options are specified on installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or the bottle's `cellar` is not `:any` or equal to the current `HOMEBREW_CELLAR`. +Bottles will not be used if the user requests it (see above), if the formula requests it (with `pour_bottle?`), if any options are specified during installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or if the bottle's `cellar` is not `:any` nor equal to the current `HOMEBREW_CELLAR`. ## Creation Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pull --bottle` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew). @@ -13,7 +13,7 @@ Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mo By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for. (That's Core 2 for 64-bit OSs, Core for 32-bit.) This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimized for something else, you can pass the `--bottle-arch=` option to build for another architecture - for example, `brew install foo --bottle-arch=penryn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad! ## Format -Bottles are simple gzipped tarballs of compiled binaries. Any metadata is stored in a formula's bottle DSL and in the bottle filename (i.e. MacOS version, revision). +Bottles are simple gzipped tarballs of compiled binaries. Any metadata is stored in a formula's bottle DSL and in the bottle filename (i.e. macOS version, revision). ## Bottle DSL (Domain Specific Language) Bottles have a DSL to be used in formulae which is contained in the `bottle do ... end` block. @@ -48,25 +48,25 @@ By default this is omitted and the Homebrew default bottle URL root is used. Thi ### Cellar (`cellar`) Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built. -Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` or `:any_skip_relocation` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar` +Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` or `:any_skip_relocation` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar`. ### Prefix (`prefix`) Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built. -See description of `cellar`. When `cellar` is `:any` or `:any_skip_relocation` prefix should be omitted. +See description of `cellar`. When `cellar` is `:any` or `:any_skip_relocation` the prefix should be omitted. ### Rebuild version (`rebuild`) Optionally contains the rebuild version of the bottle. -Sometimes bottles may need be updated without bumping the version of the formula e.g. a new patch was applied. In that case the rebuild will have a value of 1 or more. +Sometimes bottles may need be updated without bumping the version of the formula, e.g. a new patch was applied. In that case the rebuild will have a value of 1 or more. ### Checksum (`sha256`) -Contains the SHA-256 of bottle for a particular version of macOS. +Contains the SHA-256 hash of a bottle for a particular version of macOS. ## Formula DSL Additionally there is a method available in the formula DSL. -### Pour Bottle (`pour_bottle?`) +### Pour bottle (`pour_bottle?`) Optionally returns a boolean to decide whether a bottle should be used for this formula. -For example a bottle may break if another formula has been compiled with non-default options so this method could check for that case and return `false`. +For example a bottle may break if another formula has been compiled with non-default options, so this method could check for that case and return `false`. A full example: @@ -77,5 +77,5 @@ pour_bottle? do end ``` -## Planned Improvements +## Planned improvements Most bottle features have been (and planned improvements will be) implemented by @MikeMcQuaid. Contact him directly with questions. diff --git a/docs/Brew-Test-Bot-For-Core-Contributors.md b/docs/Brew-Test-Bot-For-Core-Contributors.md index 3ed86c7066..eff5ecab37 100644 --- a/docs/Brew-Test-Bot-For-Core-Contributors.md +++ b/docs/Brew-Test-Bot-For-Core-Contributors.md @@ -10,7 +10,7 @@ This job automatically builds any pull requests submitted to Homebrew/homebrew-c ## [Homebrew Testing](https://bot.brew.sh/job/Homebrew%20Testing/) This job is manually triggered to run [`brew test-bot`](https://github.com/Homebrew/homebrew-test-bot/blob/master/cmd/brew-test-bot.rb) with user-specified parameters. On a successful build it automatically uploads bottles. -You can manually start this job with parameters to run [`brew test-bot`](https://github.com/Homebrew/homebrew-test-bot/blob/master/cmd/brew-test-bot.rb) with the same parameters. It's often useful to pass a pull request URL, a commit URL, a commit SHA-1 and/or formula names to have `brew-test-bot` test them, report the results and produce bottles. +You can manually start this job with parameters to run [`brew test-bot`](https://github.com/Homebrew/homebrew-test-bot/blob/master/cmd/brew-test-bot.rb) with the same parameters. It's often useful to pass a pull request URL, a commit URL, a commit SHA-1 and/or formula names to have the Brew Test Bot test them, report the results and produce bottles. ## Bottling To pull and bottle a pull request with `brew pull`: @@ -19,7 +19,7 @@ To pull and bottle a pull request with `brew pull`: 2. Run `brew pull --bottle 12345` where `12345` is the pull request number (or URL). If it complains about a missing URL with `BrewTestBot` in it then the bottles have not finished uploading yet; wait and try again later. 3. Run `git push` to push the commits. -To bottle a test build : +To bottle a test build: 1. Ensure the job has already completed successfully. 2. Run `brew pull --bottle https://bot.brew.sh/job/Homebrew%20Testing/1234/` where `https://bot.brew.sh/job/Homebrew%20Testing/1234/` is the testing build URL in Jenkins. diff --git a/docs/Common-Issues.md b/docs/Common-Issues.md index e8b48751d3..4ebd029c82 100644 --- a/docs/Common-Issues.md +++ b/docs/Common-Issues.md @@ -6,14 +6,14 @@ This is a list of commonly encountered problems, known issues, and their solutio You need to have the Xcode Command Line Utilities installed (and updated): run `xcode-select --install` in the terminal. (In OS X prior to 10.9, the "Command Line Tools" package can alternatively be installed from within Xcode. `⌘,` will get you to preferences. Visit the "Downloads" tab and hit the install button next to "Command Line Tools".) -### Ruby `bad interpreter: /usr/bin/ruby^M: no such file or directory` -You cloned with git, and your git configuration is set to use Windows line endings. See this page: +### Ruby: `bad interpreter: /usr/bin/ruby^M: no such file or directory` +You cloned with `git`, and your Git configuration is set to use Windows line endings. See this page: -### Ruby `bad interpreter: /usr/bin/ruby` -You don't have a `/usr/bin/ruby` or it is not executable. It's not recommended to let this persist, you'd be surprised how many .apps, tools and scripts expect your macOS provided files and directories to be *unmodified* since macOS was installed. +### Ruby: `bad interpreter: /usr/bin/ruby` +You don't have a `/usr/bin/ruby` or it is not executable. It's not recommended to let this persist; you'd be surprised how many `.app`s, tools and scripts expect your macOS-provided files and directories to be *unmodified* since macOS was installed. ### `brew update` complains about untracked working tree files -After running `brew update`, you receive a git error warning about untracked files or local changes that would be overwritten by a checkout or merge, followed by a list of files inside your Homebrew installation. +After running `brew update`, you receive a Git error warning about untracked files or local changes that would be overwritten by a checkout or merge, followed by a list of files inside your Homebrew installation. This is caused by an old bug in in the `update` code that has long since been fixed. However, the nature of the bug requires that you do the following: @@ -27,7 +27,7 @@ cd $(brew --repository)/Library git clean -fd ``` -### invalid multibyte escape: /^\037\213/ +### Ruby: `invalid multibyte escape: /^\037\213/` You see an error similar to: @@ -38,7 +38,7 @@ invalid multibyte escape: /^\037\235/ In the past, Homebrew assumed that `/usr/bin/ruby` was Ruby 1.8. On OS X 10.9, it is now Ruby 2.0. There are various incompatibilities between the two versions, so if you upgrade to OS X 10.9 while using a sufficiently old version of Homebrew, you will encounter errors. -The incompatibilities have been addressed in more recent versions of Homebrew, and it does not make assumptions about `/usr/bin/ruby`, instead it uses the executable inside MacOS's Ruby framework or a vendored Ruby. +The incompatibilities have been addressed in more recent versions of Homebrew, and instead of making assumptions about `/usr/bin/ruby`, it uses the executable inside macOS's Ruby framework or a vendored Ruby. To recover from this situation, do the following: @@ -125,7 +125,7 @@ Upgrading macOS can cause errors like the following: - `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib` - `configure: error: Cannot find libz` -Following an macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula: +Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula: ```bash xcode-select --install diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md index 08a8b2b194..628ab739ff 100644 --- a/docs/Custom-GCC-and-cross-compilers.md +++ b/docs/Custom-GCC-and-cross-compilers.md @@ -1,10 +1,10 @@ # 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`. +specific versions of build tools, e.g. `clang`. Installing a custom version of GCC or `autotools` into the `$PATH` has the -potential to break lots of compiles so we prefer the Apple or Homebrew provided +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 @@ -16,6 +16,6 @@ GCC or cross-compiler suite, please link it in here. * Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing C++11 support on earlier versions. -* Homebrew provides older GCC formulae e.g. `gcc@4.8` and `gcc@6` +* Homebrew provides older GCC formulae, e.g. `gcc@4.8` and `gcc@6`. * [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 e2dafdce88..d3a590f166 100644 --- a/docs/External-Commands.md +++ b/docs/External-Commands.md @@ -8,31 +8,30 @@ $ brew mycommand --option1 --option3 formula without modifying Homebrew's internals. -## Command Types +## Command types External commands come in two flavors: Ruby commands and shell scripts. In both cases, the command file should be executable (`chmod +x`) and live somewhere in `$PATH`. -### Ruby Commands +### Ruby commands An external command `extcmd` implemented as a Ruby command should be named `brew-extcmd.rb`. The command is executed by doing a `require` on the full pathname. As the command is `require`d, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to. The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return 0. -### Shell Scripts -A shell script for an command named `extcmd` should be named `brew-extcmd`. This file will be run via `exec` with some Homebrew variables set as environmental variables, and passed any additional command-line arguments. - -| Variable | Description | -|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| HOMEBREW_CACHE | Where Homebrew caches downloaded tarballs to, by default ~/Library/Caches/Homebrew. | -| 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_PREFIX | Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, /usr/local by default. | -| HOMEBREW_REPOSITORY | If installed from a Git clone, the repo directory (i.e., where Homebrew’s .git directory lives). | +### Shell scripts +A shell script for a command named `extcmd` should be named `brew-extcmd`. This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments. +| Variable | Description | +|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `HOMEBREW_CACHE` | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`. | +| `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_PREFIX` | Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, `/usr/local` by default. | +| `HOMEBREW_REPOSITORY` | If installed from a Git clone, the repository directory (i.e. where Homebrew’s .git directory lives). | Note that the script itself can use any suitable shebang (`#!`) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else. -## User-submitted Commands +## User-submitted commands These commands have been contributed by Homebrew users but are not included in the main Homebrew repository, nor are they installed by the installer script. You can install them manually, as outlined above. Note they are largely untested, and as always, be careful about running untested code on your machine. @@ -55,7 +54,7 @@ Note this can also be installed with `brew install brew-gem`. Get Growl notifications for Homebrew: ### brew-services -Simple support to start formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): +Simple support for starting formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): Install using: ```sh diff --git a/docs/FAQ.md b/docs/FAQ.md index 7527289dc9..5656d1e349 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -17,8 +17,6 @@ Or upgrade a specific formula with: brew upgrade $FORMULA - - ## How do I stop certain formulae from being updated? To stop something from being updated/upgraded: @@ -38,12 +36,10 @@ or clean up everything at once: brew cleanup -to see what would be cleaned up: +or to see what would be cleaned up: brew cleanup -n - - ## How do I uninstall Homebrew? To uninstall Homebrew, paste the command below in a terminal prompt. @@ -53,15 +49,12 @@ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/ Download the [uninstall script](https://raw.githubusercontent.com/Homebrew/install/master/uninstall) and run `./uninstall --help` to view more uninstall options. - - ## How do I uninstall a formula? If you do not uninstall all of the versions that Homebrew has installed, Homebrew will continue to attempt to install the newest version it knows -about when you do (`brew upgrade --all`). This can be surprising. +about when you run `brew upgrade --all`. This can be surprising. -To remove a formula entirely, you may do -(`brew uninstall formula_name --force`). +To remove a formula entirely, you may run `brew uninstall formula_name --force`. Be careful as this is a destructive operation. @@ -85,13 +78,13 @@ Read [CONTRIBUTING.md](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING ## Why do you compile everything? Homebrew provides pre-compiled versions for many formulae. These -pre-compiled versions are referred to as **bottles** and are available +pre-compiled versions are referred to as [bottles](Bottles.md) and are available at . If available, bottled binaries will be used by default except under the following conditions: -* Options were passed to the install command i.e. `brew install $FORMULA` +* Options were passed to the install command, i.e. `brew install $FORMULA` will use a bottled version of $FORMULA, but `brew install $FORMULA --enable-bar` will trigger a source build. * The `--build-from-source` option is invoked. @@ -99,7 +92,7 @@ will use a bottled version of $FORMULA, but * The machine is not running a supported version of macOS as all bottled builds are generated only for supported macOS versions. * Homebrew is installed to a prefix other than the standard -`/usr/local` (although some bottles support this) +`/usr/local` (although some bottles support this). In order to completely disable bottled builds, simply add a value for the environment variable `HOMEBREW_BUILD_FROM_SOURCE` to @@ -123,7 +116,6 @@ Or: `brew pull https://github.com/Homebrew/homebrew-core/pull/1234` ## Why does Homebrew prefer I install to `/usr/local`? - 1. **It’s easier**
`/usr/local/bin` is already in your `PATH`. @@ -142,13 +134,13 @@ brews then save yourself a bunch of hassle and install to It is not always straightforward to tell `gem` to look in non-standard directories for headers and libraries. If you choose `/usr/local`, many things will "just work". -## Why does Homebrew say sudo is bad? +## Why does Homebrew say sudo is bad? **tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo anyway. Homebrew is designed to work without using sudo. You can decide to use it but we strongly recommend not to do so. If you have used sudo and run -into a bug then it is likely to be the cause. Please don’t file a bug +into a bug then this is likely to be the cause. Please don’t file a bug report unless you can reproduce it after reinstalling Homebrew from scratch without using sudo. @@ -179,7 +171,7 @@ If it’s been a while, bump it with a “bump” comment. Sometimes we miss req Yes! It’s easy! Just `brew edit $FORMULA`. You don’t have to submit modifications back to *Homebrew/homebrew-core*, just edit the formula as you personally need it and `brew install`. As a bonus `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications! ## Can I make new formulae? -Yes! It’s easy! Just `brew create URL` Homebrew will then open the +Yes! It’s easy! Just `brew create URL`. Homebrew will then open the formula in `$EDITOR` so you can edit it, but it probably already installs; try it: `brew install $FORMULA`. If you come up with any issues, run the command with the `-d` switch like so: `brew install -d $FORMULA`, @@ -193,7 +185,7 @@ Yes, brew is designed to not get in your way so you can use it how you like. Install your own stuff, but be aware that if you install common -libraries, like libexpat yourself, it may cause trouble when trying to +libraries like libexpat yourself, it may cause trouble when trying to build certain Homebrew formula. As a result `brew doctor` will warn you about this. @@ -215,13 +207,13 @@ Linking /usr/local/Cellar/foo/0.1… 17 symlinks created Use `brew log $FORMULA` to find out! Likely because it had unresolved issues or our analytics identified it was not widely used. -## Homebrew is a poor name, it is generic, why was it chosen? +## Homebrew is a poor name, it's too generic, why was it chosen? @mxcl was too concerned with the beer theme and didn’t consider that the -project may actually prove popular. By the time he realized it was too -late. However, today, the first google hit for “homebrew” is not beer +project may actually prove popular. By the time he realized it was, it was too +late. However, today, the first Google hit for “homebrew” is not beer related ;-) -## What does *keg-only* mean? +## What does "keg-only" mean? It means the formula is installed only into the Cellar; it is not linked into `/usr/local`. This means most tools will not find it. We don’t do this for stupid reasons. You can still link in the formula if you need diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md index 6b4678f90b..84a472e0d3 100644 --- a/docs/Formula-Cookbook.md +++ b/docs/Formula-Cookbook.md @@ -2,7 +2,7 @@ A formula is a package definition written in Ruby. It can be created with `brew create $URL` where `$URL` is a zip or tarball, installed with `brew install $FORMULA`, and debugged with `brew install --debug --verbose $FORMULA`. Formulae use the [Formula API](http://www.rubydoc.info/github/Homebrew/brew/master/Formula) which provides various Homebrew-specific helpers. -## Homebrew Terminology +## Homebrew terminology | Term | Description | Example | |----------------|------------------------------------------------------------|-----------------------------------------------------------------| @@ -15,15 +15,15 @@ A formula is a package definition written in Ruby. It can be created with `brew | **Cask** | An [extension of homebrew](https://github.com/caskroom/homebrew-cask) to install macOS native apps | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown` | | **Brew Bundle**| An [extension of homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` | -## An Introduction +## An introduction Homebrew uses Git for downloading updates and contributing to the project. -Homebrew installs to the `Cellar` it then symlinks some of the installation into `/usr/local` so that other programs can see what's going on. We suggest you `brew ls` a few of the kegs in your Cellar to see how it is all arranged. +Homebrew installs to the `Cellar` and then symlinks some of the installation into `/usr/local` so that other programs can see what's going on. We suggest you `brew ls` a few of the kegs in your Cellar to see how it is all arranged. -Packages are installed according to their formulae, which live in `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula`. Check one out a simple one e.g. `brew edit etl` (or [etl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/etl.rb)) or a more advanced one e.g. `brew edit git` or [Git](https://github.com/Homebrew/homebrew-core/blob/master/Formula/git.rb). +Packages are installed according to their formulae, which live in `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula`. Check one out a simple one e.g. `brew edit etl` (or [etl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/etl.rb)) or a more advanced one e.g. `brew edit git` (or [Git](https://github.com/Homebrew/homebrew-core/blob/master/Formula/git.rb)). -# Basic Instructions +## Basic instructions Make sure you run `brew update` before you start. This turns your Homebrew installation into a Git repository. @@ -34,12 +34,12 @@ Before submitting a new formula make sure your package: * isn't in another official [Homebrew tap](https://github.com/Homebrew) * isn't already waiting to be merged (check the [issue tracker](https://github.com/Homebrew/homebrew-core/pulls)) * is still supported by upstream (i.e. doesn't require extensive patching) -* has a stable, tagged version (i.e. not just a GitHub repository with no versions). +* has a stable, tagged version (i.e. not just a GitHub repository with no versions) * passes all `brew audit --new-formula $FORMULA` tests. Before submitting a new formula make sure you read over our [contribution guidelines](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING.md). -## Grab the URL +### Grab the URL Run `brew create` with a URL to the source tarball: @@ -71,25 +71,25 @@ If `brew` said `Warning: Version cannot be determined from URL` when doing the ` Homebrew will try to guess the formula’s name from its URL. If it fails to do so you can override this with `brew create --set-name `. -## Fill in the [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) +### Fill in the [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) **We don’t accept formulae without a [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method)!** -A SSL/TLS (https) [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) is preferred, if one is available. +An SSL/TLS (https) [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) is preferred, if one is available. Try to summarize from the [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method) what the formula does in the [`desc`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#desc%3D-class_method)ription. Note that the [`desc`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#desc%3D-class_method)ription is automatically prepended with the formula name. -## Check the build system +### Check the build system ```shell brew install -i foo ``` -You’re now at new prompt with the tarball extracted to a temporary sandbox. +You’re now at a new prompt with the tarball extracted to a temporary sandbox. Check the package’s `README`. Does the package install with `./configure`, `cmake`, or something else? Delete the commented out `cmake` lines if the package uses `./configure`. -## Check for dependencies +### Check for dependencies The `README` probably tells you about dependencies and Homebrew or macOS probably already has them. You can check for Homebrew dependencies with `brew search`. Some common dependencies that macOS comes with: @@ -103,7 +103,7 @@ The `README` probably tells you about dependencies and Homebrew or macOS probabl There are plenty of others; check `/usr/lib` for them. -We generally try to not duplicate system libraries and complicated tools in core Homebrew but we do duplicate some commonly used tools. +We generally try not to duplicate system libraries and complicated tools in core Homebrew but we do duplicate some commonly used tools. Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be built using Homebrew’s shipped equivalent and our test bot's post-install `audit` will warn if it detects you haven't done this. @@ -120,7 +120,7 @@ Homebrew maintains a special [tap that provides other useful system duplicates]( *Important:* `$(brew --prefix)/bin` is NOT on the `$PATH` during formula installation. If you have dependencies at build time, you must specify them and brew will add them to the `$PATH` or create a [`Requirement`](http://www.rubydoc.info/github/Homebrew/brew/master/Requirement). -## Specifying other formulae as dependencies +### Specifying other formulae as dependencies ```ruby class Foo < Formula @@ -139,16 +139,16 @@ A Symbol (e.g. `:x11`) specifies a [`Requirement`](http://www.rubydoc.info/githu A Hash (e.g. `=>`) specifies a formula dependency with some additional information. Given a single string key, the value can take several forms: -* a Symbol (currently one of `:build`, `:optional`, `:run` or `:recommended`). +* a Symbol (currently one of `:build`, `:optional`, `:run` or `:recommended`) - `:build` means that dependency is a build-time only dependency so it can be skipped when installing from a bottle or when listing missing dependencies using `brew missing`. - `:optional` generates an implicit `with-foo` option for the formula. This means that, given `depends_on "foo" => :optional`, the user must pass `--with-foo` in order to use the dependency. - - `:run` can mean the dependency is only required at run, or it can be used - to declare build dependencies such as `pkg-config` are needed at + - `:run` can mean the dependency is only required at runtime, or it can be used + to declare build dependencies such as `pkg-config` that are needed at runtime as well, which will silence the audit warning. `:run` dependencies - are currently available at build-time. + are currently available at build time. - `:recommended` generates an implicit `without-foo` option, meaning that the dependency is enabled by default and the user must pass `--without-foo` to disable this dependency. The default @@ -160,6 +160,7 @@ A Hash (e.g. `=>`) specifies a formula dependency with some additional informati ``` * a String or an Array + String values are interpreted as options to be passed to the dependency. You can also pass an array of strings, or an array of symbols and strings, in which case the symbols are interpreted as described above, and the @@ -171,42 +172,40 @@ A Hash (e.g. `=>`) specifies a formula dependency with some additional informati depends_on "foo" => [:optional, "with-bar"] ``` -## Specifying conflicts with other formulae +### Specifying conflicts with other formulae Sometimes there’s hard conflict between formulae, and it can’t be avoided or circumvented with [`keg_only`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method). -`mbedtls` is a good [example](https://github.com/Homebrew/homebrew-core/blob/master/Formula/mbedtls.rb) formula for minor conflict. - -`mbedtls` ships and compiles a "Hello World" executable. This is obviously non-essential to `mbedtls`’s functionality, and conflict with the popular GNU `hello` formula would be overkill, so we just [remove it](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/mbedtls.rb#L27-L28) during the installation process. +A good example formula for minor conflict is [mbedtls](https://github.com/Homebrew/homebrew-core/blob/master/Formula/mbedtls.rb), which ships and compiles a "Hello World" executable. This is obviously non-essential to `mbedtls`’s functionality, and conflict with the popular GNU `hello` formula would be overkill, so we just [remove it](https://github.com/Homebrew/homebrew-core/blob/ae2206f3e5bb2a7c0065ae1b164d2d011b85858b/Formula/mbedtls.rb#L27-L28) during the installation process. [pdftohtml](https://github.com/Homebrew/homebrew-core/blob/master/Formula/pdftohtml.rb) provides an example of a serious conflict, where both formula ship an identically-named binary that is essential to functionality, so a [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#conflicts_with-class_method) is preferable. As a general rule, [`conflicts_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#conflicts_with-class_method) should be a last-resort option. It’s a fairly blunt instrument. -The syntax for conflict that can’t be worked around is: +The syntax for a conflict that can’t be worked around is: ```ruby conflicts_with "blueduck", :because => "yellowduck also ships a duck binary" ``` -## Formulae Revisions +### Formulae revisions In Homebrew we sometimes accept formulae updates that don’t include a version bump. These include resource updates, new patches or fixing a security issue with a formula. -Occasionally, these updates require a forced-recompile of the formula itself or its dependents to either ensure formulae continue to function as expected or to close a security issue. This forced-recompile is known as a [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method) and inserted underneath the `homepage`/`url`/`sha` block. +Occasionally, these updates require a forced-recompile of the formula itself or its dependents to either ensure formulae continue to function as expected or to close a security issue. This forced-recompile is known as a [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method) and is inserted underneath the `homepage`/`url`/`sha256` block. -Where a dependent of a formula fails against a new version of that dependency it must receive a [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method). An example of such failure can be seen [here](https://github.com/Homebrew/legacy-homebrew/issues/31195) and the fix [here](https://github.com/Homebrew/legacy-homebrew/pull/31207). +When a dependent of a formula fails against a new version of that dependency it must receive a [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method). An example of such failure can be seen [here](https://github.com/Homebrew/legacy-homebrew/issues/31195) and the fix [here](https://github.com/Homebrew/legacy-homebrew/pull/31207). [`revision`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#revision%3D-class_method)s are also used for formulae that move from the system OpenSSL to the Homebrew-shipped OpenSSL without any other changes to that formula. This ensures users aren’t left exposed to the potential security issues of the outdated OpenSSL. An example of this can be seen in [this commit](https://github.com/Homebrew/legacy-homebrew/commit/6b9d60d474d72b1848304297d91adc6120ea6f96). -## Version Scheme Changes +### Version scheme changes Sometimes formulae have version schemes that change such that a direct comparison between two versions no longer produces the correct result. For example, a project might be version `13` and then decide to become `1.0.0`. As `13` is translated to `13.0.0` by our versioning system by default this requires intervention. -Where a version scheme of a formula fails to recognise a new version as newer it must receive a [`version_scheme`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version_scheme%3D-class_method). An example of this can be seen [here](https://github.com/Homebrew/homebrew-core/pull/4006). +When a version scheme of a formula fails to recognise a new version as newer it must receive a [`version_scheme`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version_scheme%3D-class_method). An example of this can be seen [here](https://github.com/Homebrew/homebrew-core/pull/4006). -## Double-check for dependencies +### Double-check for dependencies When you already have a lot of formulae installed, it's easy to miss a common dependency. You can double-check which libraries a binary links to with the `otool` command (perhaps you need to use `xcrun otool`): @@ -225,11 +224,11 @@ $ otool -L /usr/local/bin/ldapvi /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0) ``` -## Specifying gems, Python modules, Go projects, etc. as dependencies +### Specifying gems, Python modules, Go projects, etc. as dependencies Homebrew doesn’t package already packaged language-specific libraries. These should be installed directly from `gem`/`cpan`/`pip` etc. -If you're installing an application then please use [`resource`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#resource-class_method)s for all the language-specific dependencies: +If you're installing an application then use [`resource`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#resource-class_method)s for all language-specific dependencies: ```ruby class Foo < Formula @@ -244,11 +243,11 @@ class Foo < Formula end ``` -[jrnl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have use `pip` or Python and can just run `jrnl`. +[jrnl](https://github.com/Homebrew/homebrew-core/blob/master/Formula/jrnl.rb) is an example of a formula that does this well. The end result means the user doesn't have to use `pip` or Python and can just run `jrnl`. -[homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) can help you generate resource stanzas for the dependencies of your Python application and [gdm](https://github.com/sparrc/gdm#homebrew) can help you generate go\_resource stanzas for the dependencies of your go application. +[homebrew-pypi-poet](https://github.com/tdsmith/homebrew-pypi-poet) can help you generate `resource` stanzas for the dependencies of your Python application and [gdm](https://github.com/sparrc/gdm#homebrew) can help you generate `go_resource` stanzas for the dependencies of your Go application. -## Install the formula +### Install the formula ```shell brew install --verbose --debug foo @@ -258,7 +257,7 @@ brew install --verbose --debug foo Check the top of the e.g. `./configure` output. Some configure scripts do not recognize e.g. `--disable-debug`. If you see a warning about it, remove the option from the formula. -## Add a test to the formula +### Add a test to the formula Please add a [`test do`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#test-class_method) block to the formula. This will be run by `brew test foo` and the [Brew Test Bot](Brew-Test-Bot.md). @@ -276,21 +275,21 @@ We want tests that don't require any user input and test the basic functionality See [cmake](https://github.com/Homebrew/homebrew-core/blob/master/Formula/cmake.rb) for an example of a formula with a good test. The formula 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. Another good example is [tinyxml2](https://github.com/Homebrew/homebrew-core/blob/master/Formula/tinyxml2.rb), which writes a small C++ source file into the test directory, compiles and links it against the tinyxml2 library and finally checks that the resulting program runs successfully. -## Manuals +### Manuals Homebrew expects to find manual pages in `#{prefix}/share/man/...`, and not in `#{prefix}/man/...`. Some software installs to `man` instead of `share/man`, so check the output and add a `"--mandir=#{man}"` to the `./configure` line if needed. -## A Quick Word on Naming +### A quick word on naming Name the formula like the project markets the product. So it’s `pkg-config`, not `pkgconfig`; `sdl_mixer`, not `sdl-mixer` or `sdlmixer`. -The only exception is stuff like “Apache Ant”. Apache sticks “Apache” in front of everything, but we use the formula name `ant`. We only include the prefix in cases like *GNUplot* (because it’s part of the name) and *GNU Go* (because everyone calls it “GNU go”—nobody just calls it “Go”). The word “Go” is too common and there are too many implementations of it. +The only exception is stuff like “Apache Ant”. Apache sticks “Apache” in front of everything, but we use the formula name `ant`. We only include the prefix in cases like *GNUplot* (because it’s part of the name) and *GNU Go* (because everyone calls it “GNU Go”—nobody just calls it “Go”). The word “Go” is too common and there are too many implementations of it. If you’re not sure about the name check the homepage, and check the Wikipedia page and [what Debian calls it](https://www.debian.org/distrib/packages). -Where Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising users’ expectations. +When Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising users’ expectations. When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula. @@ -305,7 +304,7 @@ Thus, if you change the name of the class, you must also rename the file. Filena Add aliases by creating symlinks in an `Aliases` directory in the tap root. -## Audit the formula +### Audit the formula You can run `brew audit --strict --online` to test formulae for adherence to Homebrew house style. The `audit` command includes warnings for trailing whitespace, preferred URLs for certain source hosts, and a lot of other style issues. Fixing these warnings before committing will make the process a lot quicker for everyone. @@ -314,7 +313,7 @@ New formulae being submitted to Homebrew should run `brew audit --new-formula fo Use `brew info` and check if the version guessed by Homebrew from the URL is correct. Add an explicit [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) if not. -## Commit +### Commit Everything is built on Git, so contribution is easy: @@ -339,13 +338,13 @@ This may seem crazy short, but you’ll find that forcing yourself to summarise The preferred commit message format for simple version updates is `foobar 7.3` and for fixes is `foobar: fix flibble matrix.`. -Ensure you reference any relevant GitHub issue e.g. `Closes #12345` in the commit message. Homebrew’s history is the first thing future contributors will look to when trying to understand the current state of formulae they’re interested in. +Ensure you reference any relevant GitHub issue, e.g. `Closes #12345` in the commit message. Homebrew’s history is the first thing future contributors will look to when trying to understand the current state of formulae they’re interested in. -## Push +### Push Now you just need to push your commit to GitHub. -If you haven’t forked Homebrew yet, [go to the `homebrew-core` repository and hit the fork button](https://github.com/Homebrew/homebrew-core). +If you haven’t forked Homebrew yet, [go to the `homebrew-core` repository and hit the Fork button](https://github.com/Homebrew/homebrew-core). If you have already forked Homebrew on GitHub, then you can manually push (just make sure you have been pulling from the `Homebrew/homebrew-core` master): @@ -353,14 +352,14 @@ If you have already forked Homebrew on GitHub, then you can manually push (just git push https://github.com/myname/homebrew-core/ ``` -Now, please [open a pull request](http://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request.html) for your changes. +Now, [open a pull request](http://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request.html) for your changes. * One formula per commit; one commit per formula * Keep merge commits out of the pull request -# Convenience Tools +## Convenience tools -## Messaging +### Messaging Three commands are provided for displaying informational messages to the user: @@ -377,11 +376,11 @@ end system "make", "install" ``` -## `bin.install "foo"` +### `bin.install "foo"` -You’ll see stuff like that in other formulae. This moves the file `foo` into the Formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod 0555 foo`). +You’ll see stuff like this in some formulae. This moves the file `foo` into the formula’s `bin` directory (`/usr/local/Cellar/pkg/0.1/bin`) and makes it executable (`chmod 0555 foo`). -## [`inreplace`](http://www.rubydoc.info/github/Homebrew/brew/master/Utils/Inreplace) +### [`inreplace`](http://www.rubydoc.info/github/Homebrew/brew/master/Utils/Inreplace) A convenience function that can edit files in-place. For example: @@ -398,7 +397,7 @@ end Make sure you modify `s`! This block ignores the returned value. -`inreplace` should be used instead of patches when it is patching something that will never be accepted upstream e.g. make 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. +`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 modify variables in a `Makefile`, rather than using `inreplace`, pass them as arguments to `make`: @@ -482,7 +481,7 @@ patch :p0, "..." In embedded patches, the string `HOMEBREW_PREFIX` is replaced with the value of the constant `HOMEBREW_PREFIX` before the patch is applied. -## Creating the diff +### Creating the diff ```shell brew install --interactive --git foo @@ -494,15 +493,15 @@ brew edit foo Now just paste into the formula after `__END__`. Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formula/foo.rb` might help you ensure that the patch is not touched (e.g. white space removal, indentation, etc.) -# Advanced Formula Tricks +## Advanced formula tricks If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repo homebrew/core)` directory. Please submit a pull request to amend this document if you think it will help! -## Unstable versions (`devel`, `head`) +### Unstable versions (`devel`, `head`) Formulae can specify alternate downloads for the upstream project’s [`devel`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#devel-class_method) release (unstable but not `master`/`trunk`) or [`head`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) (`master`/`trunk`). -### `devel` +#### `devel` The [`devel`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#devel-class_method) spec (activated by passing `--devel`) is used for a project’s unstable releases. It is specified in a block: @@ -515,7 +514,7 @@ end You can test if the `devel` spec is in use with `build.devel?`. -### `head` +#### `head` [`head`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) URLs (activated by passing `--HEAD`) build the development cutting edge. Specifying it is easy: @@ -538,9 +537,9 @@ class Foo < Formula end ``` -## Compiler selection +### Compiler selection -Sometimes a package fails to build when using a certain compiler. Since recent Xcodes no longer include a GCC compiler we cannot simply force the use of GCC. Instead, the correct way to declare this is the [`fails_with` DSL method](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method). A properly constructed [`fails_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method) block documents the latest compiler build version known to cause compilation to fail, and the cause of the failure. For example: +Sometimes a package fails to build when using a certain compiler. Since recent [Xcode versions](Xcode.md) no longer include a GCC compiler we cannot simply force the use of GCC. Instead, the correct way to declare this is the [`fails_with` DSL method](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method). A properly constructed [`fails_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method) block documents the latest compiler build version known to cause compilation to fail, and the cause of the failure. For example: ```ruby fails_with :llvm do @@ -558,7 +557,7 @@ end [`fails_with`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#fails_with-class_method) declarations can be used with any of `:gcc`, `:llvm`, and `:clang`. Homebrew will use this information to select a working compiler (if one is available). -## Specifying the Download Strategy explicitly +### Specifying the download strategy explicitly To use one of Homebrew’s built-in download strategies, specify the `:using =>` flag on a `url` or `head`. For example: @@ -596,7 +595,7 @@ class Foo < Formula end ``` -## Just moving some files +### Just moving some files When your code in the install function is run, the current working directory is set to the extracted tarball. @@ -614,104 +613,27 @@ prefix.install Dir["output/*"] Generally we'd rather you were specific about what files or directories need to be installed rather than installing everything. -### Variables for directory locations +#### Variables for directory locations - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameDefaultExample
HOMEBREW_PREFIX/usr/local
prefix#{HOMEBREW_PREFIX}/Cellar/#{name}/#{version}/usr/local/Cellar/foo/0.1
opt_prefix#{HOMEBREW_PREFIX}/opt/#{name}/usr/local/opt/foo
bin#{prefix}/bin/usr/local/Cellar/foo/0.1/bin
doc#{prefix}/share/doc/foo/usr/local/Cellar/foo/0.1/share/doc/foo
include#{prefix}/include/usr/local/Cellar/foo/0.1/include
info#{prefix}/share/info/usr/local/Cellar/foo/0.1/share/info
lib#{prefix}/lib/usr/local/Cellar/foo/0.1/lib
libexec#{prefix}/libexec/usr/local/Cellar/foo/0.1/libexec
man#{prefix}/share/man/usr/local/Cellar/foo/0.1/share/man
man[1-8]#{prefix}/share/man/man[1-8]/usr/local/Cellar/foo/0.1/share/man/man[1-8]
sbin#{prefix}/sbin/usr/local/Cellar/foo/0.1/sbin
share#{prefix}/share/usr/local/Cellar/foo/0.1/share
pkgshare#{prefix}/share/foo/usr/local/Cellar/foo/0.1/share/foo
etc#{HOMEBREW_PREFIX}/etc/usr/local/etc
var#{HOMEBREW_PREFIX}/var/usr/local/var
buildpathA temporary directory somewhere on your system/private/tmp/[formula-name]-0q2b/[formula-name]
+| Name | Default | Example | +|-----------------------|------------------------------------------------|---------------------------------------------------| +| **`HOMEBREW_PREFIX`** | `/usr/local` | | +| **`prefix`** | `#{HOMEBREW_PREFIX}/Cellar/#{name}/#{version}` | `/usr/local/Cellar/foo/0.1` | +| **`opt_prefix`** | `#{HOMEBREW_PREFIX}/opt/#{name}` | `/usr/local/opt/foo` | +| **`bin`** | `#{prefix}/bin` | `/usr/local/Cellar/foo/0.1/bin` | +| **`doc`** | `#{prefix}/share/doc/foo` | `/usr/local/Cellar/foo/0.1/share/doc/foo` | +| **`include`** | `#{prefix}/include` | `/usr/local/Cellar/foo/0.1/include` | +| **`info`** | `#{prefix}/share/info` | `/usr/local/Cellar/foo/0.1/share/info` | +| **`lib`** | `#{prefix}/lib` | `/usr/local/Cellar/foo/0.1/lib` | +| **`libexec`** | `#{prefix}/libexec` | `/usr/local/Cellar/foo/0.1/libexec` | +| **`man`** | `#{prefix}/share/man` | `/usr/local/Cellar/foo/0.1/share/man` | +| **`man[1-8]`** | `#{prefix}/share/man/man[1-8]` | `/usr/local/Cellar/foo/0.1/share/man/man[1-8]` | +| **`sbin`** | `#{prefix}/sbin` | `/usr/local/Cellar/foo/0.1/sbin` | +| **`share`** | `#{prefix}/share` | `/usr/local/Cellar/foo/0.1/share` | +| **`pkgshare`** | `#{prefix}/share/foo` | `/usr/local/Cellar/foo/0.1/share/foo` | +| **`etc`** | `#{HOMEBREW_PREFIX}/etc` | `/usr/local/etc` | +| **`var`** | `#{HOMEBREW_PREFIX}/var` | `/usr/local/var` | +| **`buildpath`** | A temporary directory somewhere on your system | `/private/tmp/[formula-name]-0q2b/[formula-name]` | These can be used, for instance, in code such as @@ -725,13 +647,13 @@ to move binaries into their correct location into the cellar, and man.mkpath ``` -to create the directory structure to the manual page location. +to create the directory structure for the manual page location. To install man pages into specific locations, use `man1.install "foo.1", "bar.1"`, `man2.install "foo.2"`, etc. Note that in the context of Homebrew, [`libexec`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#libexec-instance_method) is reserved for private use by the formula and therefore is not symlinked into `HOMEBREW_PREFIX`. -## Adding optional steps +### Adding optional steps If you want to add an [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method): @@ -761,8 +683,7 @@ end Note that [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s that aren’t `build.with? ` or `build.without?` should be deprecated with [`deprecated_option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#deprecated_option-class_method). See [wget](https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb#L27-L31) for an example. - -## File level operations +### File level operations You can use the file utilities provided by Ruby's [`FileUtils`](http://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them. @@ -780,7 +701,7 @@ ln_s libexec/"name", bin The symlinks created by `install_symlink` are guaranteed to be relative. `ln_s` will only produce a relative symlink when given a relative path. -## Handling files that should persist over formula upgrades +### Handling files that should persist over formula upgrades For example, Ruby 1.9’s gems should be installed to `var/lib/ruby/` so that gems don’t need to be reinstalled when upgrading Ruby. You can usually do this with symlink trickery, or *better* a configure option. @@ -794,24 +715,24 @@ Homebrew provides two Formula methods for launchd plist files. [`plist_name`](ht Eventually a new version of the software will be released. In this case you should update the `url` and `sha256`. If a `revision` line exists outside any `bottle do` block *and* the new release is stable rather than devel, it should be removed. -Please leave the `bottle do ... end` block as-is; our CI system will update it when we pull your change. +Leave the `bottle do ... end` block as-is; our CI system will update it when we pull your change. -Check if the formula you are updating is a dependency for any other formulae by running `brew uses UPDATED_FORMULA`. If it is a dependency please `brew reinstall` all the dependencies after it is installed and verify they work correctly. +Check if the formula you are updating is a dependency for any other formulae by running `brew uses UPDATED_FORMULA`. If it is a dependency, run `brew reinstall` for all the dependencies after it is installed and verify they work correctly. -# Style guide +## Style guide Homebrew wants to maintain a consistent Ruby style across all formulae based on [Ruby Style Guide](https://github.com/styleguide/ruby). Other formulae may not have been updated to match this guide yet but all new ones should. Also: * The order of methods in a formula should be consistent with other formulae (e.g.: `def install` goes before `def post_install`) * An empty line is required before the `__END__` line -# Troubleshooting for people writing new formulae +## Troubleshooting for people writing new formulae ### Version detection fails Homebrew tries to automatically determine the [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) from the [`url`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#url-class_method) to avoid duplication. If the tarball has an unusual name you may need to manually assign the [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method). -## Bad Makefiles +### Bad makefiles Not all projects have makefiles that will run in parallel so try to deparallelize by adding these lines to the `install` method: @@ -823,7 +744,7 @@ system "make", "install" If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew-core/issues) so that we can fix it for everyone. -## Still won’t work? +### Still won’t work? Check out what MacPorts and Fink do: @@ -832,11 +753,11 @@ brew -S --macports foo brew -S --fink foo ``` -# Superenv Notes +## Superenv notes -`superenv` is our "super environment" that isolates builds by removing `/usr/local/bin` and all user `PATH`s that are not essential for the build. It does this because user `PATH`s are often full of stuff that breaks builds. `superenv` also removes bad flags from the commands passed to `clang`/`gcc` and injects others (for example all `keg_only` dependencies are added to the `-I` and `-L` flags. +`superenv` is our "super environment" that isolates builds by removing `/usr/local/bin` and all user `PATH`s that are not essential for the build. It does this because user `PATH`s are often full of stuff that breaks builds. `superenv` also removes bad flags from the commands passed to `clang`/`gcc` and injects others (for example all `keg_only` dependencies are added to the `-I` and `-L` flags). -# Fortran +## Fortran Some software requires a Fortran compiler. This can be declared by adding `depends_on :fortran` to a formula. `:fortran` is a `Requirement` that does several things. @@ -846,9 +767,9 @@ If you have set `FC` to a custom Fortran compiler, you may additionally set `FCF When using Homebrew's `gfortran` compiler, the standard `CFLAGS` are used and user-supplied values of `FCFLAGS` and `FFLAGS` are ignored for consistency and reproducibility reasons. -# How to start over (reset to upstream `master`) +## How to start over (reset to upstream `master`) -Have you created a real mess in git which stops you from creating a commit you want to submit to us? You might want to consider starting again from scratch. Your changes can be reset to the Homebrew's `master` branch by running: +Have you created a real mess in Git which stops you from creating a commit you want to submit to us? You might want to consider starting again from scratch. Your changes can be reset to the Homebrew `master` branch by running: ```shell git checkout -f master diff --git a/docs/Gems,-Eggs-and-Perl-Modules.md b/docs/Gems,-Eggs-and-Perl-Modules.md index 07d810c77e..19dbb4fb86 100644 --- a/docs/Gems,-Eggs-and-Perl-Modules.md +++ b/docs/Gems,-Eggs-and-Perl-Modules.md @@ -21,19 +21,19 @@ Habit maybe? One reason is executables go in `/usr/local/bin`. Usually this isn’t a writable location. But if you installed Homebrew as we recommend, `/usr/local` will be writable without sudo. So now you are good to -install the development tools you need without risking a sudo. +install the development tools you need without risking the use of sudo. -### Python packages (eggs) without sudo Rather than changing the rights on /Library/Python, we recommend the +## Python packages (eggs) without sudo following options: -### With a brewed Python - you don’t need sudo +### With a brewed Python Note, `easy_install` is deprecated. We install `pip` (or `pip3` for python3) along with python/python3. We set up distutils such that `pip install` will always put modules in `$(brew --prefix)/lib/pythonX.Y/site-packages` and scripts in -`$(brew --prefix)/share/python`. Therefore, you won’t need `sudo`! +`$(brew --prefix)/share/python`. Therefore, you won’t need sudo! Do `brew info python` or `brew info python3` for precise information about the paths. Note, a brewed Python still searches for modules in @@ -50,7 +50,7 @@ That dir might not yet exist, but you can create it: `mkdir -p ~/Library/Python/2.7/lib/python/site-packages` To teach `easy_install` and `pip` to install there, either use the -`—user` switch or create a `~/.pydistutils.cfg` file with the +`--user` switch or create a `~/.pydistutils.cfg` file with the following content: [install] @@ -60,10 +60,9 @@ following content: [Virtualenv](http://www.virtualenv.org/en/latest/) ships `pip` and creates isolated Python environments with separate site-packages, -therefore you won’t need `sudo`. +therefore you won’t need sudo. -Rubygems without sudo ---------------------- +## Rubygems without sudo **If you use rbenv or RVM then you should ignore this stuff** @@ -74,19 +73,19 @@ without sudo. You should add this to your path. See the caveats in the ### With system’s 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 +`gem: -n/usr/local/bin` to your `~/.gemrc`. It’s YAML, so do it manually or use this: echo "gem: -n/usr/local/bin" >> ~/.gemrc -**However all versions of RubyGems before 1.3.6 are buggy** and ignore +**However, all versions of RubyGems before 1.3.6 are buggy** and ignore the above setting. Sadly a fresh install of Snow Leopard comes with 1.3.5. Currently the only known way to get around this is to upgrade rubygems as root: `sudo gem update --system` -### An Alternative +### An alternative Just install everything into the Homebrew prefix like this: @@ -94,16 +93,15 @@ Just install everything into the Homebrew prefix like this: ### 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 have decided it +*Note, maybe you shouldn’t do this on Lion, 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 chown root. Fix with: +been created owned by root. Fix with: `sudo chown -R $USER /Library/Ruby /Library/Perl /Library/Python` -Perl CPAN Modules without sudo ------------------------------- +## 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 @@ -112,7 +110,7 @@ pollutes your /Library/Perl a little is to install `sudo cpan local::lib` -Note that will install some other dependencies like `Module::Install`. +Note that this will install some other dependencies like `Module::Install`. Then put the appropriate incantation in your shell’s startup, e.g. for `.bash_profile` you insert the below, for others see the [local::lib](https://metacpan.org/pod/local::lib) docs. @@ -126,11 +124,11 @@ subdirectories will be in your `PATH` and `PERL5LIB` etc. ### Avoiding sudo altogether for Perl If you don’t even want (or can’t) use sudo for bootstrapping -`local::lib` just manually install `local::lib` in ~/perl5 and add the relevant path to `PERL5LIB` before the .bashrc eval incantation. +`local::lib`, just manually install `local::lib` in -Another alternative is to use `perlbrew` to install a separate copy of Perl in your home directory, or wherever you like : ```bash +Another alternative is to use `perlbrew` to install a separate copy of Perl in your home directory, or wherever you like: curl -L https://install.perlbrew.pl | bash perlbrew install perl-5.16.2 echo ".~/perl5/perlbrew/etc/bashrc" >> ~/.bashrc diff --git a/docs/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md index 2e9e643b5f..d3b94d1a43 100644 --- a/docs/Homebrew-and-Python.md +++ b/docs/Homebrew-and-Python.md @@ -4,7 +4,7 @@ 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 a more up-to-date Python 2.7.x (and 3.x). +Homebrew provides formulae to brew a more up-to-date Python 2.7.x and 3.x. **Important:** If you choose to install a Python which isn't either of these two (system Python or brewed Python), the Homebrew team can only provide limited support. @@ -62,9 +62,9 @@ These should be installed via `pip install `. To discover, you can use `pip s ## Brewed Python modules -For brewed Python, modules installed with `pip` or `python setup.py install` will be installed to `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable python scripts will be in `$(brew --prefix)/bin`. +For brewed Python, modules installed with `pip` or `python 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: +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: `CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install `. diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request.md b/docs/How-To-Open-a-Homebrew-Pull-Request.md index d3ee6539ec..7d6af1698f 100644 --- a/docs/How-To-Open-a-Homebrew-Pull-Request.md +++ b/docs/How-To-Open-a-Homebrew-Pull-Request.md @@ -35,7 +35,7 @@ To make a new branch and submit it for review, create a GitHub pull request with 2. Retrieve new changes to the `master` branch with `brew update`. 3. Create a new branch from the latest `master` branch with `git checkout -b origin/master`. 4. Make your changes. For formulae, use `brew edit` or your favorite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md). - * If there's a `bottle do` block in the formula: don't remove or change it; we'll update it when we pull your PR. + * If there's a `bottle do` block in the formula, don't remove or change it; we'll update it when we pull your PR. 5. Test your changes by doing the following, and ensure they all pass without issue. For changed formulae, make sure you do the `brew audit` step while your changed formula is installed. * `brew tests` * `brew install --build-from-source ` @@ -44,7 +44,7 @@ To make a new branch and submit it for review, create a GitHub pull request with 6. Make a separate commit for each changed formula with `git add` and `git commit`. 7. Upload your new commits to the branch on your fork with `git push --set-upstream `. 8. Go to the relevant repository (e.g. , , etc.) and create a pull request to request review and merging of the commits in your pushed branch. Explain why the change is needed and, if fixing a bug, how to reproduce the bug. Make sure you have done each step in the checklist that appears in your new PR. - * Please note that our preferred commit message format for simple version updates is "` `", e.g. "`source-highlight 3.1.8`". `devel` version updates should have the commit message suffixed with `(devel)`, e.g. "`nginx 1.9.1 (devel)`". If updating both stable and `devel`, the format should be a concatenation of these two forms, e.g. "`x264 r2699, r2705 (devel)`". + * Please note that our preferred commit message format for simple version updates is "` `", e.g. "`source-highlight 3.1.8`". `devel` version updates should have the commit message suffixed with `(devel)`, e.g. "`nginx 1.9.1 (devel)`". If updating both `stable` and `devel`, the format should be a concatenation of these two forms, e.g. "`x264 r2699, r2705 (devel)`". 9. Await feedback or a merge from Homebrew's maintainers. We typically respond to all PRs within a couple days, but it may take up to a week, depending on the maintainers' workload. Thank you! diff --git a/docs/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md index f4624ba124..9084fae6b8 100644 --- a/docs/How-to-Create-and-Maintain-a-Tap.md +++ b/docs/How-to-Create-and-Maintain-a-Tap.md @@ -5,8 +5,8 @@ can be created by anyone to provide their own formulae and/or external commands to any Homebrew user. ## Creating a tap -A tap is usually a git repository available online, but you can use anything as -long as it’s a protocol that git understands, or even just a directory with +A tap is usually a Git repository available online, but you can use anything as +long as it’s a protocol that Git understands, or even just a directory with files in it. If hosted on GitHub, we recommend that the repository’s name start with `homebrew-`. @@ -41,7 +41,7 @@ no core formula with the same name, or with `brew install user/repo/foo` to avoid conflicts. ## Maintaining a tap -A tap is just a git repository so you don’t have to do anything specific when +A tap is just a Git repository so you don’t have to do anything specific when making modifications, apart from committing and pushing your changes. ### Updating 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 f71c75164e..59d488baac 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 @@ -1,6 +1,6 @@ -# How to build software outside Homebrew with Homebrew `keg-only` dependencies +# How to build software outside Homebrew with Homebrew `keg_only` dependencies -## What does `keg-only` mean? +## What does "keg-only" mean? The [FAQ](FAQ.md) briefly explains this. @@ -10,20 +10,19 @@ As an example: This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location, usually `/usr/local`. -## Advice on potential workarounds. +## 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. *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. -`brew link --force` creates a warning in `brew doctor` to let both you and maintainers know that link exists and could be causing issues. If you’ve linked something and there’s no problems at all? Feel free to ignore the `brew doctor` error. +`brew link --force` creates a warning in `brew doctor` to let both you and maintainers know that a link exists that could be causing issues. If you’ve linked something and there’s no problems at all? Feel free to ignore the `brew doctor` error. ## How do I use those tools outside of Homebrew? Useful, reliable alternatives exist should you wish to use `keg_only` tools outside of Homebrew. -### Build flags: - +### Build flags You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting: @@ -37,7 +36,7 @@ An example using `pip`: CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c/lib pip install pyicu ``` -### `$PATH` modification: +### `$PATH` modification You can temporarily prepend your `$PATH` with the tool’s bin directory, such as: @@ -49,11 +48,11 @@ This will prepend that folder to your `$PATH`, ensuring any build script that se 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. -### `pkg-config` detection: +### `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. -An example of that is: +An example of this is: ```shell export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig diff --git a/docs/Installation.md b/docs/Installation.md index 4780e76efc..6eb222714e 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -5,7 +5,7 @@ The suggested and easiest way to install Homebrew is on the The standard script installs Homebrew to `/usr/local` so that [you don’t need sudo](FAQ.md) when you -`brew install`. It is a careful script, it can be run even if you have stuff +`brew install`. It is a careful script; it can be run even if you have stuff installed to `/usr/local` already. It tells you exactly what it will do before it does it too. And you have to confirm everything it will do before it starts. @@ -44,7 +44,7 @@ you can assume you will have trouble if you don’t conform. Also, you can find PowerPC and Tiger branches from other users in the fork network. See [Interesting Taps & Forks](Interesting-Taps-&-Forks.md). -2 10.10 or higher is recommended. 10.5 - 10.9 are +2 10.10 or higher is recommended. 10.5–10.9 are supported on a best-effort basis. For 10.4 and 10.5, see [Tigerbrew](https://github.com/mistydemeo/tigerbrew). diff --git a/docs/Interesting-Taps-&-Forks.md b/docs/Interesting-Taps-&-Forks.md index de9b8809e0..af9309271a 100644 --- a/docs/Interesting-Taps-&-Forks.md +++ b/docs/Interesting-Taps-&-Forks.md @@ -1,9 +1,9 @@ # Interesting Taps & Forks -A Tap is homebrew-speak for a git repository containing extra formulae. -Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` command. Type `man brew` in your Terminal. The main repository , often called `homebrew/core`, is always built-in. +A _tap_ is homebrew-speak for a Git repository containing extra formulae. +Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` commands. Type `man brew` in your Terminal. The main repository , often called `homebrew/core`, is always built-in. -## Main Taps +## Main taps * [homebrew/apache](https://github.com/Homebrew/homebrew-apache): A tap for Apache modules, extending macOS's built-in Apache. These brews may require unconventional additional setup, as explained in the caveats. @@ -35,7 +35,7 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst You can be added as a maintainer for one of the Homebrew organization taps and aid the project! If you are interested write to our list: homebrew-discuss@googlegroups.com. We want your help! -## Other Interesting Taps +## Other interesting taps * [InstantClientTap/instantclient](https://github.com/InstantClientTap/homebrew-instantclient): A tap for Oracle Instant Client. The packages need to be downloaded manually. @@ -47,12 +47,12 @@ You can be added as a maintainer for one of the Homebrew organization taps and a * [titanous/gnuradio](https://github.com/titanous/homebrew-gnuradio): GNU Radio and friends running on macOS. -## Interesting Forks +## Interesting forks * [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version * [Linuxbrew/brew](https://github.com/Linuxbrew/brew): Experimental Linux version -## Technical Details +## Technical details -Your taps are git repositories located at `$(brew --repository)/Library/Taps`. +Your taps are Git repositories located at `$(brew --repository)/Library/Taps`. diff --git a/docs/Kickstarter-Supporters.md b/docs/Kickstarter-Supporters.md index 3f39b435c0..84ba662b47 100644 --- a/docs/Kickstarter-Supporters.md +++ b/docs/Kickstarter-Supporters.md @@ -173,7 +173,7 @@ These brilliant people supported our Kickstarter by giving us £15 or more: * [Nick Rogers](https://twitter.com/zikolas) * [Abe Estrada](https://abeestrada.com) * [Mattias Larsson](https://www.yahoo.com/) -* [Dave Ross](http://davidmichaelross.com) +* [Dave Ross](http://davidmichaelross.com) * [Andrian Budantsov](http://andrian.io/) * [Jason Smith](https://twitter.com/waitingallday) * [Martin Coxall](https://twitter.com/grabcocque) diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index fdb7e88f9c..f796e2e96d 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -7,7 +7,7 @@ definitely not a beginner’s guide. Maybe you were looking for the [Formula Cookbook](Formula-Cookbook.md)? -## Quick Checklist +## Quick checklist This is all that really matters: - Ensure the name seems reasonable. @@ -20,7 +20,7 @@ This is all that really matters: - Ensure that any dependencies are accurate and minimal. We don't need to support every possible optional feature for the software. - Use the GitHub squash & merge workflow where bottles aren't required. -- Use `brew pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by BrewTestBot. +- Use `brew pull` otherwise, which adds messages to auto-close pull requests and pull bottles built by the Brew Test Bot. - Thank people for contributing. Checking dependencies is important, because they will probably stick around @@ -53,23 +53,23 @@ For now, if someone submits a formula like this, we’ll leave them in their own tree. ### Merging, rebasing, cherry-picking -Merging should be done in the brew repo to preserve history & GPG commit signing, +Merging should be done in the `Homebrew/brew` repository to preserve history & GPG commit signing, and squash/merge via GitHub should be used for formulae where those formulae don't need bottles or the change does not require new bottles to be pulled. Otherwise, you should use `brew pull` (or `rebase`/`cherry-pick` contributions). Don’t `rebase` until you finally `push`. Once `master` is pushed, you can’t -`rebase` : **you’re a maintainer now!** +`rebase`: **you’re a maintainer now!** Cherry-picking changes the date of the commit, which kind of sucks. -Don’t `merge` unclean branches. So if someone is still learning `git` +Don’t `merge` unclean branches. So if someone is still learning `git` and their branch is filled with nonsensical merges, then `rebase` and squash the commits. Our main branch history should be useful to other people, not confusing. ### Testing -We need to at least check it builds. Use [Brew Test Bot](Brew-Test-Bot.md) for this. +We need to at least check that it builds. Use the [Brew Test Bot](Brew-Test-Bot.md) for this. Verify the formula works if possible. If you can’t tell (e.g. if it’s a library) trust the original contributor, it worked for them, so chances are it @@ -80,14 +80,14 @@ open source works. Ideally, request a `test do` block to test that functionality is consistently available. If the formula uses a repository, then the `url` parameter should have a -tag or revision. `url` s have versions and are stable (not yet +tag or revision. `url`s have versions and are stable (not yet implemented!). -## Common “Gotchas” +## Common “gotchas” 1. [Ensure you have set your username and email address properly](https://help.github.com/articles/setting-your-email-in-git/) -2. Sign off cherry-picks if you amended them, [GitX-dev](https://github.com/rowanj/gitx) can do this, - otherwise there is a command line flag for it) +2. Sign off cherry-picks if you amended them ([GitX-dev](https://github.com/rowanj/gitx) + can do this, otherwise there is a command-line flag for it) 3. If the commit fixes a bug, use “Fixes \#104” syntax to close the bug report and link to the commit @@ -97,7 +97,7 @@ libraries that macOS provides but have bugs, and the bugs are fixed in a newer version. Or libraries that macOS provides, but they are too old for some other formula. The rest should be in the `homebrew/dupes` tap. -Still determine if it possible to avoid the duplicate. Be thorough. Duped +Still determine if it's possible to avoid the duplicate. Be thorough. Duped libraries and tools cause bugs that are tricky to solve. Once the formula is pulled, we can’t go back on that willy-nilly. @@ -108,9 +108,9 @@ Dupes we have allowed: - `libxml` \<— macOS version is old and buggy - `libpng` \<— Ditto -#### Add comments -It may be enough to refer to an issue ticket, but make sure changes that -if you came to them unaware of the surrounding issues would make sense +### Add comments +It may be enough to refer to an issue ticket, but make sure changes are clear so that +if you came to them unaware of the surrounding issues they would make sense to you. Many times on other projects I’ve seen code removed because the new guy didn’t know why it was there. Regressions suck. diff --git a/docs/Maintainers-Avoiding-Burnout.md b/docs/Maintainers-Avoiding-Burnout.md index 99353d946b..a10a79cdfc 100644 --- a/docs/Maintainers-Avoiding-Burnout.md +++ b/docs/Maintainers-Avoiding-Burnout.md @@ -5,14 +5,14 @@ access** to Homebrew’s repository and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone. -# 1. Use Homebrew +## 1. Use Homebrew Maintainers of Homebrew should be using it regularly. This is partly because you won't be a good maintainer unless you can put yourself in the shoes of our -users but also because you may decide to stop using Homebrew and at that point +users, but also because you may decide to stop using Homebrew and at that point you should also decide not to be a maintainer and find other things to work on. -# 2. No Guilt About Leaving +## 2. No Guilt About Leaving All maintainers can stop working on Homebrew at any time without any guilt or explanation (like a job). We may still ask for your help with questions after @@ -23,10 +23,10 @@ Like a job, you should probably take a break from Homebrew at least a few times a year. This also means contributors should be consumers. If an owner finds they are -not using a project in the real-world, they should reconsider their involvement +not using a project in the real world, they should reconsider their involvement with the project. -# 3. Prioritise Maintainers Over Users +## 3. Prioritise Maintainers Over Users It's important to be user-focused but ultimately, as long as you follow #1 above, Homebrew's minimum number of users will be the number of maintainers. @@ -36,7 +36,7 @@ need takes priority over the burnout of maintainers. If users do not like the direction of the project, the easiest way to influence it is to make significant, high-quality code contributions and become a maintainer. -# 4. Learn To Say No +## 4. Learn To Say No Homebrew gets a lot of feature requests, non-reproducible bug reports, usage questions and PRs we won't accept. These should be closed out as soon as we @@ -46,4 +46,4 @@ work to be done. --- -Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document +_Thanks to https://gist.github.com/ryanflorence/124070e7c4b3839d4573 which influenced this document_ diff --git a/docs/Node-for-Formula-Authors.md b/docs/Node-for-Formula-Authors.md index 83516da93a..63a85fdf10 100644 --- a/docs/Node-for-Formula-Authors.md +++ b/docs/Node-for-Formula-Authors.md @@ -1,10 +1,10 @@ -# Node for formula authors +# Node for Formula Authors This document explains how to successfully use Node and npm in a Node module based Homebrew formula. -# Running `npm install` +## Running `npm install` -Homebrew provides two helper methods in a `Language::Node` module, `std_npm_install_args` and `local_npm_install_args`. They both set up the correct environment for npm and return arguments for `npm install` for their specific use cases. Please use them instead of invoking `npm install` explicitly. The syntax for a standard Node module installation is: +Homebrew provides two helper methods in a `Language::Node` module: `std_npm_install_args` and `local_npm_install_args`. They both set up the correct environment for npm and return arguments for `npm install` for their specific use cases. Your formula should use these instead of invoking `npm install` explicitly. The syntax for a standard Node module installation is: ```ruby system "npm", "install", *Language::Node.std_npm_install_args(libexec) @@ -12,7 +12,7 @@ system "npm", "install", *Language::Node.std_npm_install_args(libexec) where `libexec` is the destination prefix (usually the `libexec` variable). -# Download URL +## Download URL If the Node module is also available on the npm registry, we prefer npm hosted release tarballs over GitHub (or elsewhere) hosted source tarballs. The advantages of these tarballs are that they don't include the files from the `.npmignore` (such as tests) resulting in a smaller download size and that any possible transpilation step is already done (e.g. no need to compile CoffeeScript files as a build step). @@ -24,7 +24,7 @@ https://registry.npmjs.org//-/-.tgz Alternatively you could curl the JSON at `https://registry.npmjs.org/` and look for the value of `versions[].dist.tarball` for the correct tarball URL. -# Dependencies +## Dependencies Node modules which are compatible with the latest Node version should declare a dependency on the `node` formula. @@ -36,15 +36,15 @@ If your formula requires being executed with an older Node version you must vend ### Special requirements for native addons -If your node module is a native addon or has a native addon somewhere in its dependency tree you have to declare an additional dependency. Since the compilation of the native addon results in a invocation of `node-gyp` we need an additional build time dependency on `:python` (because gyp depends on Python 2.7). +If your Node module is a native addon or has a native addon somewhere in its dependency tree you have to declare an additional dependency. Since the compilation of the native addon results in an invocation of `node-gyp` we need an additional build time dependency on `:python` (because gyp depends on Python 2.7). ```ruby depends_on :python => :build ``` -Please also note that such a formula would only be compatible with the same Node major version it originally was compiled with. This means that we need to revision every formula with a Node native addon with every major version bump of the `node` formula. To make sure we don't overlook your formula on a Node major version bump, write a meaningful test which would fail in such a case (invoked with an ABI incompatible Node version). +Also note that such a formula would only be compatible with the same Node major version it originally was compiled with. This means that we need to revision every formula with a Node native addon with every major version bump of the `node` formula. To make sure we don't overlook your formula on a Node major version bump, write a meaningful test which would fail in such a case (invoked with an ABI-incompatible Node version). -# Installation +## Installation Node modules should be installed to `libexec`. This prevents the Node modules from contaminating the global `node_modules`, which is important so that npm doesn't try to manage Homebrew-installed Node modules. @@ -82,9 +82,9 @@ In your formula's `install` method, do any installation steps which need to be d system "npm", "install", *Language::Node.local_npm_install_args ``` -This will install all of your Node modules dependencies to your local build path. You can now continue with your build steps and take care of the installation into the Homebrew `prefix` on your own, following the [general Homebrew formula instructions](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md). +This will install all of your Node modules dependencies to your local build path. You can now continue with your build steps and take care of the installation into the Homebrew `prefix` on your own, following the [general Homebrew formula instructions](Formula-Cookbook.md). -# Example +## Example Installing a standard Node module based formula would look like this: @@ -112,4 +112,4 @@ class Foo < Formula end ``` -For examples using the `local_npm_install_args` method look at the [`elixirscript`](https://github.com/Homebrew/homebrew-core/blob/ec1e40d37e81af63122a354f0101c377f6a4e66d/Formula/elixirscript.rb) or [`kibana`](https://github.com/Homebrew/homebrew-core/blob/c6202f91a129e2f994d904f299a308cc6fbd58e5/Formula/kibana.rb) formula. +For examples using the `local_npm_install_args` method look at the [`elixirscript`](https://github.com/Homebrew/homebrew-core/blob/ec1e40d37e81af63122a354f0101c377f6a4e66d/Formula/elixirscript.rb) or [`kibana`](https://github.com/Homebrew/homebrew-core/blob/c6202f91a129e2f994d904f299a308cc6fbd58e5/Formula/kibana.rb) formulae. diff --git a/docs/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md index 0291156994..232ccb1bea 100644 --- a/docs/Prose-Style-Guidelines.md +++ b/docs/Prose-Style-Guidelines.md @@ -1,6 +1,6 @@ # Prose Style Guidelines -This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `docs` in the `Homebrew/brew` repo, announcement emails, and other communications with the Homebrew community. +This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `docs` in the `Homebrew/brew` repository, announcement emails, and other communications with the Homebrew community. This does not apply to any Ruby or other computer code. You can use it to inform technical documentation extracted from computer code, like embedded man pages, but it's just a suggestion there. diff --git a/docs/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md index 7f650f967f..1d36c3c7a8 100644 --- a/docs/Python-for-Formula-Authors.md +++ b/docs/Python-for-Formula-Authors.md @@ -1,4 +1,4 @@ -# Introduction +# Python for Formula Authors This document explains how to successfully use Python in a Homebrew formula. @@ -10,9 +10,9 @@ Bindings are a special case of libraries that allow Python code to interact with Homebrew is happy to accept applications that are built in Python, whether the apps are available from PyPI or not. Homebrew generally won't accept libraries that can be installed correctly with `pip install foo`. Libraries that can be pip-installed but have several Homebrew dependencies may be appropriate for the [homebrew/python](https://github.com/Homebrew/homebrew-python) tap. Bindings may be installed for packages that provide them, especially if equivalent functionality isn't available through pip. -# Running setup.py +## Running setup.py -Homebrew provides a helper method, `Language::Python.setup_install_args`, which returns arguments for invoking setup.py. Please use it instead of invoking `setup.py` explicitly. The syntax is: +Homebrew provides a helper method, `Language::Python.setup_install_args`, which returns arguments for invoking setup.py. Your formula should use this instead of invoking `setup.py` explicitly. The syntax is: ```ruby system "python", *Language::Python.setup_install_args(prefix) @@ -20,11 +20,11 @@ system "python", *Language::Python.setup_install_args(prefix) where `prefix` is the destination prefix (usually `libexec` or `prefix`). -# Python module dependencies +## Python module dependencies In general, applications should unconditionally bundle all of their dependencies and libraries and should install any unsatisfied dependencies; these strategies are discussed in depth in the following sections. -In the rare instance that this proves impractical, you can specify a Python module as an external dependency using the syntax: +In the rare instance that this proves impractical, you can specify a Python module as an external dependency using this syntax: ```ruby depends_on "numpy" => :python @@ -38,11 +38,11 @@ depends_on "MacFSEvents" => [:python, "fsevents"] If you submit a formula with this syntax to core, you may be asked to rewrite it as a `Requirement`. -# Applications +## Applications `ansible.rb` and `jrnl.rb` are good examples of applications that follow this advice. -## Python declarations +### Python declarations Applications that are compatible with Python 2 **should** use the Apple-provided system Python in /usr/bin on systems that provide Python 2.7. To do this, declare: @@ -53,7 +53,7 @@ No explicit Python dependency is needed on recent OS versions since /usr/bin is Formulae for apps that require Python 3 **should** declare an unconditional dependency on `:python3`, which will cause the formula to use the first python3 discovered in `PATH` at install time (or install Homebrew's if there isn't one). These apps **must** work with the current Homebrew python3 formula. -## Installing +### Installing Applications should be installed into a Python [virtualenv](https://virtualenv.pypa.io/en/stable/) environment rooted in `libexec`. This prevents the app's Python modules from contaminating the system site-packages and vice versa. @@ -108,7 +108,7 @@ def install end ``` -## Example +### Example Installing a formula with dependencies will look like this: @@ -134,7 +134,7 @@ class Foo < Formula end ``` -You can also use the more verbose form and request that specific resources are installed: +You can also use the more verbose form and request that specific resources be installed: ```ruby def install @@ -147,17 +147,17 @@ end ``` in case you need to do different things for different resources. -# Bindings +## Bindings To add an option to a formula to build Python bindings, use `depends_on :python => :recommended` and install the bindings conditionally on `build.with? "python"` in your `install` method. Python bindings should be optional because if the formula is bottled, any `:recommended` or mandatory dependencies on `:python` are always resolved by installing the Homebrew `python` formula, which will upset users that prefer to use the system Python. This is because we cannot generally create a binary package that works against both versions of Python. -## Dependencies +### Dependencies Bindings should follow the same advice for Python module dependencies as libraries; see below for more. -## Installing bindings +### Installing bindings If the bindings are installed by invoking a `setup.py`, do something like: @@ -177,31 +177,31 @@ If the `configure` and `make` scripts do not want to install into the Cellar, so Sometimes we have to `inreplace` a `Makefile` to use our prefix for the python bindings. (`inreplace` is one of Homebrew's helper methods, which greps and edits text files on-the-fly.) -# Libraries +## Libraries -## Python declarations +### Python declarations Libraries **should** declare a dependency on `:python` or `:python3` as appropriate, which will respectively cause the formula to use the first python or python3 discovered in `PATH` at install time. If a library supports both Python 2.x and Python 3.x, the `:python` dependency **should** be `:recommended` (i.e. built by default) and the :python3 dependency should be `:optional`. Python 2.x libraries **must** function when they are installed against either the system Python or Homebrew Python. Formulae that declare a dependency on `:python` will always be bottled against Homebrew's python, since we cannot in general build binary packages that can be imported from both Pythons. Users can add `--build-from-source` after `brew install` to compile against whichever python is in `PATH`. -## Installing +### Installing Libraries may be installed to `libexec` and added to `sys.path` by writing a .pth file (named like "homebrew-foo.pth") to the `prefix` site-packages. This simplifies the ensuing drama if pip is accidentally used to upgrade a Homebrew-installed package and prevents the accumulation of stale .pyc files in Homebrew's site-packages. Most formulae presently just install to `prefix`. -## Dependencies +### Dependencies The dependencies of libraries must be installed so that they are importable. The principle of minimum surprise suggests that installing a Homebrew library should not alter the other libraries in a user's sys.path. The best way to achieve this is to only install dependencies if they are not already installed. To minimize the potential for linking conflicts, dependencies should be installed to `libexec/"vendor"` and added to `sys.path` by writing a second .pth file (named like "homebrew-foo-dependencies.pth") to the `prefix` site-packages. -The `matplotlib.rb` formula in homebrew-python deploys this strategy. +The [matplotlib](https://github.com/Homebrew/homebrew-science/blob/master/matplotlib.rb) formula in [homebrew/science](https://github.com/Homebrew/homebrew-science) deploys this strategy. -# Further down the rabbit hole +## Further down the rabbit hole Additional commentary that explains why Homebrew does some of the things it does. -## setuptools vs. distutils vs. pip +### setuptools vs. distutils vs. pip Distutils is a module in the Python standard library that provides developers a basic package management API. Setuptools is a module distributed outside the standard library that extends distutils. It is a convention that Python packages provide a setup.py that calls the `setup()` function from either distutils or setuptools. @@ -211,7 +211,7 @@ Distutils and pip use a "flat" installation hierarchy that installs modules as i Distribute (not to be confused with distutils) is an obsolete fork of setuptools. Distlib is a package maintained outside the standard library which is used by pip for some low-level packaging operations and is not relevant to most setup.py users. -## What is `--single-version-externally-managed`? +### What is `--single-version-externally-managed`? `--single-version-externally-managed` ("SVEM") is a setuptools-only [argument to setup.py install](https://setuptools.readthedocs.io/en/latest/setuptools.html?#install-run-easy-install-or-old-style-installation). The primary effect of SVEM is to use distutils to perform the install instead of using setuptools' `easy_install`. @@ -226,7 +226,7 @@ setuptools requires that SVEM is used in conjunction with `--record`, which prov Detecting whether a `setup.py` uses `setup()` from setuptools or distutils is difficult, but we always need to pass this flag to setuptools-based scripts. `pip` faces the same problem that we do and forces `setup()` to use the setuptools version by loading a shim around `setup.py` that imports setuptools before doing anything else. Since setuptools monkey-patches distutils and replaces its `setup` function, this provides a single, consistent interface. We have borrowed this code and use it in `Language::Python.setup_install_args`. -## `--prefix` vs `--root` +### `--prefix` vs `--root` setup.py accepts a slightly bewildering array of installation options. The correct switch for Homebrew is `--prefix`, which automatically sets the `--install-foo` family of options using sane POSIX-y values. @@ -234,6 +234,6 @@ setup.py accepts a slightly bewildering array of installation options. The corre It is probably safe to use `--prefix` with `--root=/`, which should work with either setuptools or distutils-based setup.py's but is kinda ugly. -## pip vs. setup.py +### pip vs. setup.py [PEP 453](http://legacy.python.org/dev/peps/pep-0453/#recommendations-for-downstream-distributors) makes a recommendation to downstream distributors (us) that sdist tarballs should be installed with pip instead of by invoking setup.py directly. We do not do this because Apple's Python distribution does not include pip, so we can't assume that pip is available. We could do something clever to work around Apple's piplessness but the value proposition is not yet clear. diff --git a/docs/Querying-Brew.md b/docs/Querying-Brew.md index 0e059486b2..f6a05a065d 100644 --- a/docs/Querying-Brew.md +++ b/docs/Querying-Brew.md @@ -4,7 +4,7 @@ _In this document we will be using [jq](https://stedolan.github.io/jq/) to parse ## Overview -`brew` provides commands for getting common types of information out of the system. `brew list` showed installed formulae. `brew deps foo` shows the dependencies that `foo` needs. +`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. @@ -16,9 +16,9 @@ To enable users to do rich queries without the problems above, Homebrew provides From the manpage: - * `info --json= (--all|--installed|)`: - Print a JSON representation of ``. Currently the only accepted value - for is `v1`. + * `info --json= (--all|--installed|)`: + Print a JSON representation of ``. Currently the only accepted value + for `` is `v1`. Pass `--all` to get information on all formulae, or `--installed` to get information on all installed formulae. diff --git a/docs/README.md b/docs/README.md index ec75647330..0c8dac7b9d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,7 +38,7 @@ ## Maintainers - [New Maintainer Checklist](New-Maintainer-Checklist.md) -- [Maintainers Avoiding Burnout](Maintainers-Avoiding-Burnout.md) +- [Maintainers: Avoiding Burnout](Maintainers-Avoiding-Burnout.md) - [Maintainer Guidelines](Maintainer-Guidelines.md) - [Brew Test Bot For Maintainers](Brew-Test-Bot-For-Core-Contributors.md) - [Common Issues for Maintainers](Common-Issues-for-Core-Contributors.md) diff --git a/docs/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md index e6e18ca9e9..66fe1a7094 100644 --- a/docs/Tips-N'-Tricks.md +++ b/docs/Tips-N'-Tricks.md @@ -3,11 +3,11 @@ ## Installing previous versions of formulae The supported method of installing specific versions of -some formulae is to see if there is a versions formula like e.g. `gcc@6` available. If the version you’re looking for isn’t available, consider [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md)! +some formulae is to see if there is a versioned formula (e.g. `gcc@6`) available. If the version you’re looking for isn’t available, consider [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md)! ### Installing directly from pull requests You can [browse pull requests](https://github.com/Homebrew/homebrew-core/pulls) -and install through the direct link. For example Python 3.3.0 pull request [Homebrew/homebrew#15199](https://github.com/Homebrew/homebrew/pull/15199) +and install through the direct link. For example, Python 3.3.0 from pull request [Homebrew/homebrew#15199](https://github.com/Homebrew/homebrew/pull/15199): ```sh brew install https://raw.github.com/dsr/homebrew/9b22d42f50fcbc5e52c764448b3ac002bc153bd7/Library/Formula/python3.rb @@ -50,7 +50,7 @@ renaming the file from otp_src_R13B03 to download. This means instead of manually renaming a formula, you can run `mv the_tarball $(brew --cache -s $FORMULA)`. -You can also pre-cache the download by using the command `brew fetch formula` which also displays the SHA256 value. This can be useful for updating formulae to new versions. +You can also pre-cache the download by using the command `brew fetch formula` which also displays the SHA-256 hash. This can be useful for updating formulae to new versions. ## Using Homebrew behind a proxy Behind the scenes, Homebrew uses several commands for downloading files (e.g. curl, git, svn). Many of these tools can download via a proxy. It's a common (though not universal) convention for these command-line tools to observe getting the proxy parameters from environment variables (e.g. `http_proxy`). Unfortunately, most tools are inconsistent in their use of these environment parameters (e.g. curl supports `http_proxy`, `HTTPS_PROXY`, `FTP_PROXY`, `GOPHER_PROXY`, `ALL_PROXY`, `NO_PROXY`). @@ -63,12 +63,13 @@ internet for details), including at runtime: http_proxy=http://: brew install $FORMULA ``` -### Proxy Authentication +To use proxy authentication: + ```sh http_proxy=http://:@: brew install $FORMULA ``` -## Installing stuff without the Xcode-CLT +## Installing stuff without the Xcode CLT ```sh $ brew sh # or: eval $(brew --env) $ gem install ronn # or c-programs diff --git a/docs/Versions.md b/docs/Versions.md index 6c64381443..c6ebd6570d 100644 --- a/docs/Versions.md +++ b/docs/Versions.md @@ -2,15 +2,15 @@ Now that [Homebrew/versions](https://github.com/homebrew/homebrew-versions) has been deprecated, [Homebrew/core](https://github.com/homebrew/homebrew-core) supports multiple versions of formulae with a new naming format. -In [Homebrew/versions](https://github.com/homebrew/homebrew-versions) the formula for GCC 6 was named `gcc6.rb` and began `class Gcc6 < Formula`. In [Homebrew/core](https://github.com/homebrew/homebrew-core) this same formula is named `gcc@6.rb` and begins `class GccAT6 < Formula`. +In [Homebrew/versions](https://github.com/homebrew/homebrew-versions) the formula for GCC 6 was named `gcc6.rb` and began with `class Gcc6 < Formula`. In [Homebrew/core](https://github.com/homebrew/homebrew-core) this same formula is named `gcc@6.rb` and begins with `class GccAT6 < Formula`. -## Acceptable Versioned Formulae +## Acceptable versioned formulae Homebrew's versions are not intended to be used for any old versions you personally require for your project; formulae submitted should be expected to be used by a large number of people and still supported by their upstream projects. Versioned formulae we include must meet the following standards: * Versioned formulae should differ in major/minor (not patch) versions from the current stable release. This is because patch versions indicate bug or security updates and we want to ensure you apply security updates. * Formulae that depend on versioned formulae must not depend on the same formulae at two different versions twice in their recursive dependencies. For example, if you depend on `openssl@1.0` and `foo`, and `foo` depends on `openssl` then you must instead use `openssl`. -* Versioned formulae should only be linkable at the same time as their non-versioned counterpart if the upstream project provides support for e.g. suffixed binaries. If this is not possible, use `keg_only :versioned_formula` to allow users to have multiple versions installed at once. +* Versioned formulae should only be linkable at the same time as their non-versioned counterpart if the upstream project provides support for it, e.g. using suffixed binaries. If this is not possible, use `keg_only :versioned_formula` to allow users to have multiple versions installed at once. -You should create your own [tap](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md) for formulae you or your organisation wishes to control the versioning of or those that do not meet the above standards. +You should create your own [tap](How-to-Create-and-Maintain-a-Tap.md) for formulae you or your organisation wishes to control the versioning of or those that do not meet the above standards. diff --git a/docs/Xcode.md b/docs/Xcode.md index 025cee9d7f..c5a0a15000 100644 --- a/docs/Xcode.md +++ b/docs/Xcode.md @@ -1,6 +1,6 @@ # Xcode -## Supported Xcode Versions +## Supported Xcode versions Homebrew supports and recommends the latest Xcode and/or Command Line Tools available for your platform: @@ -14,58 +14,58 @@ Tools available for your platform: | 10.11 | 8.0 | 7.3 | | 10.12 | 8.0 | 8.0 | -## Compiler Version Database +## Compiler version database - | Xcode | GCC 4.0 | GCC 4.2 | LLVM-GCC 4.2 | LLVM | Clang | LLVM (SVN) | - |-------|---------|---------|--------------|------------|-----------------|------------| - | 2.5.0 | 5370 | — | — | — | — | — | - | 3.1.4 | 5493 | 5577 | 5555 | 2064.3 | — | — | - | 3.2.0 | 5493 | 5646 | 5646 | 2118 | — | — | - | 3.2.1 | 5493 | 5646 | 5646 | 2206 | — | — | - | 3.2.2 | 5493 | 5659 | 5646 | 2207.5 | 1.0.2 | — | - | 3.2.3 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — | - | 3.2.4 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — | - | 3.2.5 | 5494 | 5664 | 5658 | 2333.4 | 1.6 (70) | — | - | 3.2.6 | 5494 | 5666 | 5658 | 2335.6 | 1.7 (77) | 2.9 | - | 4.0.0 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 | - | 4.0.2 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 | - | 4.1.0 | — | 5666 | 5658 | 2335.15.00 | 2.1 (163.7.1) | 3.0 | - | 4.2.0 | — | — | 5658 | 2336.1.00 | 3.0 (211.10.1) | 3.0 | - | 4.3.0 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.45) | 3.1 | - | 4.3.1 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.54) | 3.1 | - | 4.3.2 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.58) | 3.1 | - | 4.3.3 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.61) | 3.1 | - | 4.4.0 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.57) | 3.1 | - | 4.4.1 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.60) | 3.1 | - | 4.5.0 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.65) | 3.1 | - | 4.5.1 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 | - | 4.5.2 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 | - | 4.6.0 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.24) | 3.2 | - | 4.6.1 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.27) | 3.2 | - | 4.6.2 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 | - | 4.6.3 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 | - | 5.0.0 | — | — | — | — | 5.0 (500.2.76) | 3.3 | - | 5.0.1 | — | — | — | — | 5.0 (500.2.78) | 3.3 | - | 5.0.1 | — | — | — | — | 5.0 (500.2.79) | 3.3 | - | 5.1 | — | — | — | — | 5.1 (503.0.38) | 3.4 | - | 5.1.1 | — | — | — | — | 5.1 (503.0.40) | 3.4 | - | 6.0 | — | — | — | — | 6.0 (600.0.51) | 3.5 | - | 6.0.1 | — | — | — | — | 6.0 (600.0.51) | 3.5 | - | 6.1 | — | — | — | — | 6.0 (600.0.54) | 3.5 | - | 6.2 | — | — | — | — | 6.0 (600.0.57) | 3.5 | - | 6.3 | — | — | — | — | 6.1 (602.0.49) | 3.6 | - | 6.3.1 | — | — | — | — | 6.1 (602.0.49) | 3.6 | - | 6.3.2 | — | — | — | — | 6.1 (602.0.53) | 3.6 | - | 6.4 | — | — | — | — | 6.1 (602.0.53) | 3.6 | - | 7.0 | — | — | — | — | 7.0 (700.0.72) | - | - | 7.0.1 | — | — | — | — | 7.0 (700.0.72) | - | - | 7.1 | — | — | — | — | 7.0 (700.1.76) | - | - | 7.1.1 | — | — | — | — | 7.0 (700.1.76) | - | - | 7.2 | — | — | — | — | 7.0 (700.1.81) | - | - | 7.2.1 | — | — | — | — | 7.0 (700.1.81) | - | - | 7.3 | — | — | — | — | 7.3 (703.0.29) | - | - | 7.3.1 | — | — | — | — | 7.3 (703.0.31) | - | - | 8.0 | — | — | — | — | 8.0 (800.0.38) | - | +| Xcode | GCC 4.0 | GCC 4.2 | LLVM-GCC 4.2 | LLVM | Clang | LLVM (SVN) | +|-------|---------|---------|--------------|------------|-----------------|------------| +| 2.5.0 | 5370 | — | — | — | — | — | +| 3.1.4 | 5493 | 5577 | 5555 | 2064.3 | — | — | +| 3.2.0 | 5493 | 5646 | 5646 | 2118 | — | — | +| 3.2.1 | 5493 | 5646 | 5646 | 2206 | — | — | +| 3.2.2 | 5493 | 5659 | 5646 | 2207.5 | 1.0.2 | — | +| 3.2.3 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — | +| 3.2.4 | 5494 | 5664 | 5658 | 2326.10 | 1.5 (60) | — | +| 3.2.5 | 5494 | 5664 | 5658 | 2333.4 | 1.6 (70) | — | +| 3.2.6 | 5494 | 5666 | 5658 | 2335.6 | 1.7 (77) | 2.9 | +| 4.0.0 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 | +| 4.0.2 | 5494 | 5666 | 5658 | 2335.9 | 2.0 (137) | 2.9 | +| 4.1.0 | — | 5666 | 5658 | 2335.15.00 | 2.1 (163.7.1) | 3.0 | +| 4.2.0 | — | — | 5658 | 2336.1.00 | 3.0 (211.10.1) | 3.0 | +| 4.3.0 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.45) | 3.1 | +| 4.3.1 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.54) | 3.1 | +| 4.3.2 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.58) | 3.1 | +| 4.3.3 | — | — | 5658 | 2336.9.00 | 3.1 (318.0.61) | 3.1 | +| 4.4.0 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.57) | 3.1 | +| 4.4.1 | — | — | 5658 | 2336.11.00 | 4.0 (421.0.60) | 3.1 | +| 4.5.0 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.65) | 3.1 | +| 4.5.1 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 | +| 4.5.2 | — | — | 5658 | 2336.11.00 | 4.1 (421.11.66) | 3.1 | +| 4.6.0 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.24) | 3.2 | +| 4.6.1 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.27) | 3.2 | +| 4.6.2 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 | +| 4.6.3 | — | — | 5658 | 2336.11.00 | 4.2 (425.0.28) | 3.2 | +| 5.0.0 | — | — | — | — | 5.0 (500.2.76) | 3.3 | +| 5.0.1 | — | — | — | — | 5.0 (500.2.78) | 3.3 | +| 5.0.1 | — | — | — | — | 5.0 (500.2.79) | 3.3 | +| 5.1 | — | — | — | — | 5.1 (503.0.38) | 3.4 | +| 5.1.1 | — | — | — | — | 5.1 (503.0.40) | 3.4 | +| 6.0 | — | — | — | — | 6.0 (600.0.51) | 3.5 | +| 6.0.1 | — | — | — | — | 6.0 (600.0.51) | 3.5 | +| 6.1 | — | — | — | — | 6.0 (600.0.54) | 3.5 | +| 6.2 | — | — | — | — | 6.0 (600.0.57) | 3.5 | +| 6.3 | — | — | — | — | 6.1 (602.0.49) | 3.6 | +| 6.3.1 | — | — | — | — | 6.1 (602.0.49) | 3.6 | +| 6.3.2 | — | — | — | — | 6.1 (602.0.53) | 3.6 | +| 6.4 | — | — | — | — | 6.1 (602.0.53) | 3.6 | +| 7.0 | — | — | — | — | 7.0 (700.0.72) | — | +| 7.0.1 | — | — | — | — | 7.0 (700.0.72) | — | +| 7.1 | — | — | — | — | 7.0 (700.1.76) | — | +| 7.1.1 | — | — | — | — | 7.0 (700.1.76) | — | +| 7.2 | — | — | — | — | 7.0 (700.1.81) | — | +| 7.2.1 | — | — | — | — | 7.0 (700.1.81) | — | +| 7.3 | — | — | — | — | 7.3 (703.0.29) | — | +| 7.3.1 | — | — | — | — | 7.3 (703.0.31) | — | +| 8.0 | — | — | — | — | 8.0 (800.0.38) | — | ## References to Xcode and compiler versions in code When a new Xcode release is made, the following things need to be diff --git a/docs/brew-tap.md b/docs/brew-tap.md index cfa0870d85..6a537428f2 100644 --- a/docs/brew-tap.md +++ b/docs/brew-tap.md @@ -1,7 +1,7 @@ # Taps (third-party repositories) -`brew tap` adds more repos to the list of formulae that `brew` tracks, updates, -and installs from. By default, `tap` assumes that the repos come from GitHub, +`brew tap` adds more repositories to the list of formulae that `brew` tracks, updates, +and installs from. By default, `tap` assumes that the repositories come from GitHub, but the command isn't limited to any one location. ## The command (`brew tap`) @@ -18,26 +18,26 @@ edavis/emacs * `brew tap ` makes a shallow clone of the repository at https://github.com/user/repo. After that, `brew` will be able to work on - those formulae as if there were in Homebrew's canonical repository. You can + those formulae as if they were in Homebrew's canonical repository. You can install and uninstall them with `brew [un]install`, and the formulae are automatically updated when you run `brew update`. (See below for details about how `brew tap` handles the names of repositories.) * `brew tap ` makes a shallow clone of the repository at URL. Unlike the one-argument version, URL is not assumed to be GitHub, and it - doesn't have to be HTTP. Any location and any protocol that git can handle is + doesn't have to be HTTP. Any location and any protocol that Git can handle is fine. -* Add `--full` to either the one- or two-argument invocations above, and git +* Add `--full` to either the one- or two-argument invocations above, and Git will make a complete clone rather than a shallow one. Full is the default for Homebrew developers. -* `brew tap --repair` migrates tapped formulae from symlink-based to +* `brew tap --repair` migrates tapped formulae from a symlink-based to directory-based structure. (This should only need to be run once.) * `brew untap user/repo [user/repo user/repo ...]` removes the given taps. The - repos are deleted and `brew` will no longer be aware of its formulae. `brew - untap` can handle multiple removals at once. + repositories are deleted and `brew` will no longer be aware of their formulae. + `brew untap` can handle multiple removals at once. ## Repository naming conventions and assumptions @@ -65,9 +65,9 @@ and use `brew tap-unpin username/repo` to revert the pin. Whenever a `brew install foo` command is issued, brew will find which formula to use by searching in the following order: -* Pinned taps -* Core formulae -* Other taps +* pinned taps +* core formulae +* other taps If you need a formula to be installed from a particular tap, you can use fully qualified names to refer to them. @@ -89,5 +89,5 @@ brew install homebrew/core/vim # installs from homebrew/core ``` Do note that pinned taps are prioritized only when the formula name is directly -given by you. i.e., it will not influence formulae automatically installed as +given by you, i.e. it will not influence formulae automatically installed as dependencies.