Merge pull request #12431 from EricFromCanada/docs-section-2
Updates for Docs section 2
This commit is contained in:
Mike McQuaid
GitHub
commit
d63c4d2761
@ -3,32 +3,35 @@
|
||||
Homebrew gathers anonymous aggregate user behaviour analytics using Google Analytics. You will be notified the first time you run `brew update` or install Homebrew. Analytics are not enabled until after this notice is shown, to ensure that you can [opt out](Analytics.md#opting-out) without ever sending analytics data.
|
||||
|
||||
## 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.
|
||||
- Collecting the OS version allows us to decide which versions of macOS to prioritise for support and identify build failures that occur only on single versions.
|
||||
|
||||
## How Long?
|
||||
|
||||
Homebrew's anonymous user and event data have a 14 month retention period. This is the [lowest possible value for Google Analytics](https://support.google.com/analytics/answer/7667196).
|
||||
|
||||
## What?
|
||||
|
||||
Homebrew's analytics record some shared information for every event:
|
||||
|
||||
- The Homebrew user agent, e.g. `Homebrew/2.5.0 (Macintosh; Intel Mac OS X 10.15.6) curl/7.64.1`.
|
||||
- The Homebrew user agent, e.g. `Homebrew/3.3.0 (Macintosh; Intel Mac OS X 10.15.6) curl/7.64.1`.
|
||||
- The [Google Analytics version](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#v), i.e. `1`.
|
||||
- The Homebrew [analytics tracking ID](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#tid), e.g. `UA-75654628-1`.
|
||||
- A Homebrew [analytics user ID](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#cid), 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 versus event counts. The ID is specific to the Homebrew package manager, and does not permit Homebrew maintainers to e.g. track you across websites you visit.
|
||||
- If the [Google Analytics anonymous IP setting](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#aip) is enabled, i.e. `1`.
|
||||
- Whether the [Google Analytics anonymous IP setting](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#aip) is enabled, i.e. `1`.
|
||||
- The Homebrew [application name](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an), e.g. `Homebrew`.
|
||||
- The Homebrew [application version](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#av), e.g. `2.5.0`.
|
||||
- The Homebrew [analytics hit type](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#t), e.g. `event`.
|
||||
|
||||
Homebrew's analytics records the following different events:
|
||||
|
||||
- An `event` hit type with the `install` event category and the Homebrew formula from a non-private GitHub tap you 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 `install_on_request` event category and the Homebrew formula from a non-private GitHub tap you have requested to install (e.g. explicitly named it with a `brew install`) plus options and an event label as above. This allows us to differentiate the formulae that users intend to install from those pulled in as dependencies.
|
||||
- An `event` hit type with the `cask_install` event category and the Homebrew cask from a non-private GitHub tap you install as the action and an event label as above. This allows us to identify the casks 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 `event` hit type with the `install` event category and the Homebrew formula from a non-private GitHub tap you install plus any used options (e.g. `wget --HEAD`) as the action, and an event label (e.g. `macOS 10.15, non-/usr/local, CI`) to indicate the OS version, non-standard installation location and invocation as part of CI. This allows us to identify which formulae need fixing and where more easily.
|
||||
- An `event` hit type with the `install_on_request` event category and the Homebrew formula from a non-private GitHub tap you have requested to install (e.g. when explicitly named with a `brew install`) plus options and an event label as above. This allows us to differentiate the formulae that users intend to install from those pulled in as dependencies.
|
||||
- An `event` hit type with the `cask_install` event category and the Homebrew cask from a non-private GitHub tap you install as the action and an event label as above. This allows us to identify which casks need fixing and where more easily.
|
||||
- An `event` hit type with the `BuildError` event category and the Homebrew formula plus options that failed to install as the action and an event label as above, e.g. `wget --HEAD` and `macOS 10.15`.
|
||||
|
||||
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.
|
||||
|
||||
@ -39,15 +42,19 @@ It is impossible for the Homebrew developers to match any particular event to an
|
||||
As far as we can tell it would be impossible for Google to match the randomly generated Homebrew-only analytics user ID to any other Google Analytics user ID. If Google turned evil the only thing they could do would be to lie about anonymising IP addresses and attempt to match users based on IP addresses.
|
||||
|
||||
## When/Where?
|
||||
|
||||
Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS.
|
||||
|
||||
## Who?
|
||||
Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). A JSON API is also available. The majority of Homebrew maintainers are not granted more detailed analytics data beyond these public resources.
|
||||
|
||||
Summaries of installation and error analytics are [publicly available](https://formulae.brew.sh/analytics/). A JSON API is also available. The majority of Homebrew maintainers are not granted more detailed analytics data beyond these public resources.
|
||||
|
||||
## How?
|
||||
|
||||
The code is viewable in [`analytics.rb`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/utils/analytics.rb) and [`analytics.sh`](https://github.com/Homebrew/brew/blob/HEAD/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.
|
||||
|
||||
## Opting out
|
||||
|
||||
Homebrew analytics helps us maintainers and leaving it on is appreciated. However, if you want to opt out of Homebrew's analytics, you can set this variable in your environment:
|
||||
|
||||
```sh
|
||||
|
||||
@ -1,22 +1,32 @@
|
||||
# Bottles (Binary Packages)
|
||||
|
||||
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.
|
||||
Bottles are produced by installing a formula with `brew install --build-bottle <formula>` and then bottling it with `brew bottle <formula>`. This generates a bottle file in the current directory and outputs the bottle DSL for insertion into the formula file.
|
||||
|
||||
## Usage
|
||||
If a bottle is available and usable it will be downloaded and poured automatically when you `brew install <formula>`. 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 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`.
|
||||
When the formula being installed defines a bottle matching your system, it will be downloaded and installed automatically when you run `brew install <formula>`.
|
||||
|
||||
Bottles will not be used if:
|
||||
|
||||
- the user requests it (by specifying `--build-from-source`),
|
||||
- the formula requests it (with `pour_bottle?`),
|
||||
- any options are specified during installation (bottles are all compiled with default options),
|
||||
- the bottle is not up to date (e.g. missing or mismatched checksum),
|
||||
- or the bottle's `cellar` is neither `:any` (it requires being installed to a specific Cellar path) nor equal to the current `HOMEBREW_CELLAR` (the required Cellar path does not match that of the current Homebrew installation).
|
||||
|
||||
## Creation
|
||||
Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md), usually when people submit pull requests to Homebrew. The `bottle do` block is updated by maintainers when they merge a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [GitHub Packages](https://github.com/orgs/Homebrew/packages).
|
||||
|
||||
By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for (Core 2 for 64-bit OSs). This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimised for something else, you can pass the `--bottle-arch=` option to build for another architecture; for example, `brew install foo --build-bottle --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!
|
||||
Bottles for `homebrew/core` formulae are created by [Brew Test Bot](Brew-Test-Bot.md) when a pull request is submitted. If the formula builds successfully on each supported platform and a maintainer approves the change, Brew Test Bot updates its `bottle do` block and uploads each bottle to [GitHub Packages](https://github.com/orgs/Homebrew/packages).
|
||||
|
||||
By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for (Core 2 for 64-bit x86 operating systems). This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimised for something else, you can pass the `--bottle-arch=` option to build for another architecture; for example, `brew install foo --build-bottle --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. The formula name, version, target operating system and rebuild version is stored in the filename, any other metadata is in the formula's bottle DSL, and the formula definition is located within the bottle at `<formula>/<version>/.brew/<formula>.rb`.
|
||||
|
||||
## Bottle DSL (Domain Specific Language)
|
||||
Bottles have a DSL to be used in formulae which is contained in the `bottle do ... end` block.
|
||||
|
||||
Bottles are specified in formula definitions by a DSL contained within a `bottle do ... end` block.
|
||||
|
||||
A simple (and typical) example:
|
||||
|
||||
@ -43,26 +53,36 @@ end
|
||||
```
|
||||
|
||||
### Root URL (`root_url`)
|
||||
Optionally contains the URL root used to calculate bottle URLs.
|
||||
By default this is omitted and the Homebrew default bottle URL root is used. This may be useful for taps which wish to provide bottles for their formulae or to cater for a non-default `HOMEBREW_CELLAR`.
|
||||
|
||||
Optionally contains the URL root used to determine bottle URLs.
|
||||
|
||||
By default this is omitted and Homebrew's default bottle URL root is used. This may be useful for taps that wish to provide bottles for their formulae or cater to a non-default `HOMEBREW_CELLAR`.
|
||||
|
||||
### 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`.
|
||||
|
||||
Most compiled software contains references to its compiled location, preventing it from being simply relocated anywhere on disk. A value of `:any` or `:any_skip_relocation` means that the bottle can be safely installed in any Cellar as it did not contain any references to the Cellar in which it was originally built. This can be omitted if the bottle was compiled for the given OS/architecture's default `HOMEBREW_CELLAR`, as is done for all bottles built by Brew Test Bot.
|
||||
|
||||
### 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 or revision of the formula, e.g. if a new patch was applied. In such cases `rebuild` will have a value of `1` or more.
|
||||
|
||||
### Checksum (`sha256`)
|
||||
Contains the SHA-256 hash of a bottle for a particular version of macOS.
|
||||
|
||||
Contains the SHA-256 hash of the bottle for the given OS/architecture.
|
||||
|
||||
## Formula DSL
|
||||
An additional method is available in the formula DSL.
|
||||
|
||||
An additional bottle-related method is available in the formula DSL.
|
||||
|
||||
### 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`.
|
||||
|
||||
Optionally returns a boolean to indicate whether a bottle should be used when installing this formula.
|
||||
|
||||
For example a bottle may break if a related formula has been compiled with non-default options, so this method could check for that case and return `false`.
|
||||
|
||||
A full example:
|
||||
|
||||
@ -76,5 +96,6 @@ end
|
||||
Commonly used `pour_bottle?` conditions can be added as preset symbols to the `pour_bottle?` method, allowing them to be specified like this:
|
||||
|
||||
```ruby
|
||||
pour_bottle? only_if: :default_prefix
|
||||
pour_bottle? only_if: :clt_installed
|
||||
```
|
||||
|
||||
@ -1,31 +1,33 @@
|
||||
# Interesting Taps & Forks
|
||||
|
||||
A [tap](Taps.md) 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 at <https://github.com/Homebrew/homebrew-core>, often called `homebrew/core`, is always built-in.
|
||||
A [tap](Taps.md) is Homebrew-speak for a Git repository containing additional formulae.
|
||||
|
||||
Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` commands; run `man brew` in your terminal for usage information. The main repository at <https://github.com/Homebrew/homebrew-core>, often called `homebrew/core`, is always built-in.
|
||||
|
||||
Your taps are Git repositories located at `$(brew --repository)/Library/Taps`.
|
||||
|
||||
## Unsupported interesting taps
|
||||
* [homebrew-ffmpeg/ffmpeg](https://github.com/homebrew-ffmpeg/homebrew-ffmpeg): A tap for FFmpeg with additional options, including nonfree additions.
|
||||
|
||||
* [denji/nginx](https://github.com/denji/homebrew-nginx): A tap for NGINX modules, intended for its `nginx-full` formula which includes more module options.
|
||||
* [homebrew-ffmpeg/ffmpeg](https://github.com/homebrew-ffmpeg/homebrew-ffmpeg): A tap for FFmpeg with additional options, including nonfree additions.
|
||||
|
||||
* [InstantClientTap/instantclient](https://github.com/InstantClientTap/homebrew-instantclient): A tap for Oracle Instant Client. The packages need to be downloaded manually.
|
||||
* [denji/nginx](https://github.com/denji/homebrew-nginx): A tap for NGINX modules, intended for its `nginx-full` formula which includes more module options.
|
||||
|
||||
* [osx-cross/avr](https://github.com/osx-cross/homebrew-avr): GNU AVR toolchain (Libc, compilers and other tools for Atmel MCUs, useful for Arduino hackers and AVR programmers).
|
||||
* [InstantClientTap/instantclient](https://github.com/InstantClientTap/homebrew-instantclient): A tap for Oracle Instant Client.
|
||||
|
||||
* [petere/postgresql](https://github.com/petere/homebrew-postgresql): Allows installing multiple PostgreSQL versions in parallel.
|
||||
* [osx-cross/avr](https://github.com/osx-cross/homebrew-avr): GNU AVR toolchain (Libc, compilers and other tools for Atmel MCUs), useful for Arduino hackers and AVR programmers.
|
||||
|
||||
* [osrf/simulation](https://github.com/osrf/homebrew-simulation): Tools for robotics simulation.
|
||||
* [petere/postgresql](https://github.com/petere/homebrew-postgresql): Allows installing multiple PostgreSQL versions in parallel.
|
||||
|
||||
* [brewsci/bio](https://github.com/brewsci/homebrew-bio): Bioinformatics formulae.
|
||||
* [osrf/simulation](https://github.com/osrf/homebrew-simulation): Tools for robotics simulation.
|
||||
|
||||
* [davidchall/hep](https://github.com/davidchall/homebrew-hep): High energy physics formulae.
|
||||
* [brewsci/bio](https://github.com/brewsci/homebrew-bio): Bioinformatics formulae.
|
||||
|
||||
* [lifepillar/appleii](https://github.com/lifepillar/homebrew-appleii): Formulae for vintage Apple emulation.
|
||||
* [davidchall/hep](https://github.com/davidchall/homebrew-hep): High energy physics formulae.
|
||||
|
||||
* [gromgit/fuse](https://github.com/gromgit/homebrew-fuse): macOS FUSE formulae that are no longer available in `homebrew/core`.
|
||||
* [lifepillar/appleii](https://github.com/lifepillar/homebrew-appleii): Formulae for vintage Apple emulation.
|
||||
|
||||
* [gromgit/fuse](https://github.com/gromgit/homebrew-fuse): macOS FUSE formulae that are no longer available in `homebrew/core`.
|
||||
|
||||
## Unsupported interesting forks
|
||||
|
||||
* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger PowerPC version.
|
||||
* [mistydemeo/tigerbrew](https://github.com/mistydemeo/tigerbrew): Experimental Tiger/Leopard PowerPC version.
|
||||
|
||||
61
docs/Taps.md
61
docs/Taps.md
@ -1,35 +1,39 @@
|
||||
# Taps (Third-Party Repositories)
|
||||
|
||||
`brew tap` adds more repositories to the list of formulae that `brew` tracks, updates,
|
||||
The `brew tap` command adds more repositories to the list of formulae that Homebrew 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 `brew tap` command
|
||||
|
||||
* `brew tap` without arguments lists the currently tapped repositories. For
|
||||
* `brew tap` without arguments lists all currently tapped repositories. For
|
||||
example:
|
||||
|
||||
```sh
|
||||
$ brew tap
|
||||
homebrew/core
|
||||
mistydemeo/tigerbrew
|
||||
dunn/emacs
|
||||
```
|
||||
```sh
|
||||
$ brew tap
|
||||
homebrew/cask
|
||||
homebrew/core
|
||||
petere/postgresql
|
||||
```
|
||||
|
||||
<!-- vale Homebrew.Terms = OFF -->
|
||||
<!-- The `terms` lint suggests changing "repo" to "repository". But we need the abbreviation in the tap syntax and URL example. -->
|
||||
|
||||
* `brew tap <user/repo>` makes a clone of the repository at
|
||||
https://github.com/user/homebrew-repo. After that, `brew` will be able to work on
|
||||
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
|
||||
_https://github.com/\<user>/homebrew-\<repo>_ into `$(brew --repository)/Library/Taps`.
|
||||
After that, `brew` will be able to work with those formulae as if they were in Homebrew's
|
||||
[homebrew/core](https://github.com/Homebrew/homebrew-core) 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.)
|
||||
|
||||
<!-- vale Homebrew.Terms = ON -->
|
||||
|
||||
* `brew tap <user/repo> <URL>` makes a clone of the repository at URL.
|
||||
Unlike the one-argument version, URL is not assumed to be GitHub, and it
|
||||
* `brew tap <user/repo> <URL>` makes a 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
|
||||
fine.
|
||||
fine, although non-GitHub taps require running `brew tap --force-auto-update <user/repo>`
|
||||
to enable automatic updating.
|
||||
|
||||
* `brew tap --repair` migrates tapped formulae from a symlink-based to
|
||||
directory-based structure. (This should only need to be run once.)
|
||||
@ -40,25 +44,24 @@ dunn/emacs
|
||||
|
||||
## Repository naming conventions and assumptions
|
||||
|
||||
* On GitHub, your repository must be named `homebrew-something` in order to use
|
||||
the one-argument form of `brew tap`. The prefix 'homebrew-' is not optional.
|
||||
(The two-argument form doesn't have this limitation, but it forces you to
|
||||
give the full URL explicitly.)
|
||||
On GitHub, your repository must be named `homebrew-something` to use
|
||||
the one-argument form of `brew tap`. The prefix "homebrew-" is not optional.
|
||||
(The two-argument form doesn't have this limitation, but it forces you to
|
||||
give the full URL explicitly.)
|
||||
|
||||
* When you use `brew tap` on the command line, however, you can leave out the
|
||||
'homebrew-' prefix in commands.
|
||||
|
||||
That is, `brew tap username/foobar` can be used as a shortcut for the long
|
||||
version: `brew tap username/homebrew-foobar`. `brew` will automatically add
|
||||
back the 'homebrew-' prefix whenever it's necessary.
|
||||
When you use `brew tap` on the command line, however, you can leave out the
|
||||
"homebrew-" prefix in commands. That is, `brew tap username/foobar` can be used as a shortcut for the long
|
||||
version: `brew tap username/homebrew-foobar`. `brew` will automatically add
|
||||
back the "homebrew-" prefix whenever it's necessary.
|
||||
|
||||
## Formula with duplicate names
|
||||
|
||||
If your tap contains a formula that is also present in
|
||||
[homebrew/core](https://github.com/Homebrew/homebrew-core), that's fine,
|
||||
but it means that you must install it explicitly by default.
|
||||
but you would need to specify its fully qualified name in the form
|
||||
`<user>/<repo>/<formula>` to install your version.
|
||||
|
||||
Whenever a `brew install foo` command is issued, `brew` will find which formula
|
||||
Whenever a `brew install foo` command is issued, `brew` selects which formula
|
||||
to use by searching in the following order:
|
||||
|
||||
* core formulae
|
||||
@ -67,13 +70,13 @@ to use by searching in the following order:
|
||||
If you need a formula to be installed from a particular tap, you can use fully
|
||||
qualified names to refer to them.
|
||||
|
||||
You can create a tap for an alternative `vim` formula. The behaviour will be:
|
||||
If you were to create a tap for an alternative `vim` formula, the behaviour would be:
|
||||
|
||||
```sh
|
||||
brew install vim # installs from homebrew/core
|
||||
brew install username/repo/vim # installs from your custom repository
|
||||
```
|
||||
|
||||
As a result, we recommend you give formulae a different name if you want to make
|
||||
As a result, we recommend you give new names to customized formulae if you want to make
|
||||
them easier to install. Note that there is (intentionally) no way of replacing
|
||||
dependencies of core formulae with those from taps.
|
||||
dependencies of core formulae with those from other taps.
|
||||
|
||||
@ -1,9 +1,8 @@
|
||||
# Tips and Tricks
|
||||
|
||||
## Installing previous versions of formulae
|
||||
## Install previous versions of formulae
|
||||
|
||||
The supported method of installing specific versions of
|
||||
some formulae is to see if there is a versioned formula (e.g. `gcc@7`) available. If the version you’re looking for isn’t available, consider using `brew extract`.
|
||||
Some formulae in `homebrew/core` are made available as [versioned formulae](Versions.md) using a special naming format, e.g. `gcc@7`. If the version you're looking for isn't available, consider using `brew extract`.
|
||||
|
||||
## Quickly remove something from Homebrew's prefix
|
||||
|
||||
@ -15,31 +14,22 @@ This can be useful if a package can't build against the version of something you
|
||||
|
||||
And of course, you can simply `brew link <formula>` again afterwards!
|
||||
|
||||
## Pre-downloading a file for a formula
|
||||
Sometimes it's faster to download a file via means other than those
|
||||
strategies that are available as part of Homebrew. For example,
|
||||
Erlang provides a torrent that'll let you download at 4–5× the normal
|
||||
HTTP method.
|
||||
## Pre-download a file for a formula
|
||||
|
||||
Download the file and drop it in `~/Library/Caches/Homebrew`, but
|
||||
watch the file name. Homebrew downloads files as `<formula>-<version>`.
|
||||
In the case of Erlang, this requires renaming the file from `otp_src_R13B03` to
|
||||
`erlang-R13B03`.
|
||||
Sometimes it's faster to download a file via means other than the strategies that are available as part of Homebrew. For example, Erlang provides a torrent that'll let you download at 4–5× compared to the normal HTTP method.
|
||||
|
||||
`brew --cache -s erlang` will print the correct name of the cached
|
||||
download. This means instead of manually renaming a formula, you can
|
||||
run `mv the_tarball "$(brew --cache -s <formula>)"`.
|
||||
Downloads are saved in the `downloads` subdirectory of Homebrew's cache directory (as specified by `brew --cache`, e.g. `~/Library/Caches/Homebrew`) and renamed as `<url-hash>--<formula>-<version>`. The command `brew --cache -s <formula>` will print the expected path of the cached download, so after downloading the file, you can run `mv the_tarball "$(brew --cache -s <formula>)"` to relocate it to the cache.
|
||||
|
||||
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.
|
||||
|
||||
## Installing stuff without the Xcode CLT
|
||||
## Install stuff without the Xcode CLT
|
||||
|
||||
```sh
|
||||
brew sh # or: eval "$(brew --env)"
|
||||
gem install ronn # or c-programs
|
||||
```
|
||||
|
||||
This imports the `brew` environment into your existing shell; `gem` will pick up the environment variables and be able to build. As a bonus `brew`'s automatically determined optimization flags are set.
|
||||
This imports the `brew` environment into your existing shell; `gem` will pick up the environment variables and be able to build. As a bonus, `brew`'s automatically determined optimization flags are set.
|
||||
|
||||
## Install only a formula's dependencies (not the formula)
|
||||
|
||||
@ -47,23 +37,27 @@ This imports the `brew` environment into your existing shell; `gem` will pick up
|
||||
brew install --only-dependencies <formula>
|
||||
```
|
||||
|
||||
## Interactive Homebrew Shell
|
||||
## Use the interactive Homebrew shell
|
||||
|
||||
```sh
|
||||
$ brew irb
|
||||
1.8.7 :001 > Formula.factory("ace").methods - Object.methods
|
||||
=> [:install, :path, :homepage, :downloader, :stable, :bottle, :head, :active_spec, :buildpath, :ensure_specs_set, :url, :version, :specs, :mirrors, :installed?, :explicitly_requested?, :linked_keg, :installed_prefix, :prefix, :rack, :bin, :doc, :include, :info, :lib, :libexec, :man, :man1, :man2, :man3, :man4, :man5, :man6, :man7, :man8, :sbin, :share, :etc, :var, :plist_name, :plist_path, :download_strategy, :cached_download, :caveats, :options, :patches, :keg_only?, :fails_with?, :skip_clean?, :brew, :std_cmake_args, :deps, :external_deps, :recursive_deps, :system, :fetch, :verify_download_integrity, :fails_with_llvm, :fails_with_llvm?, :std_cmake_parameters, :mkdir, :mktemp]
|
||||
1.8.7 :002 >
|
||||
==> Interactive Homebrew Shell
|
||||
Example commands available with: `brew irb --examples`
|
||||
irb(main):001:0> Formulary.factory("ace").methods - Object.methods
|
||||
=> [:install, :test, :test_defined?, :sbin, :pkgshare, :elisp,
|
||||
:frameworks, :kext_prefix, :any_version_installed?, :etc, :pkgetc,
|
||||
...
|
||||
:on_macos, :on_linux, :debug?, :quiet?, :verbose?, :with_context]
|
||||
irb(main):002:0>
|
||||
```
|
||||
|
||||
## Hiding the beer mug emoji when finishing a build
|
||||
## Hide the beer mug emoji when finishing a build
|
||||
|
||||
```sh
|
||||
export HOMEBREW_NO_EMOJI=1
|
||||
```
|
||||
|
||||
This sets the `HOMEBREW_NO_EMOJI` environment variable, causing Homebrew
|
||||
to hide all emoji.
|
||||
This sets the `HOMEBREW_NO_EMOJI` environment variable, causing Homebrew to hide all emoji.
|
||||
|
||||
The beer emoji can also be replaced with other character(s):
|
||||
|
||||
@ -75,23 +69,18 @@ export HOMEBREW_INSTALL_BADGE="☕️ 🐸"
|
||||
|
||||
### Sublime Text
|
||||
|
||||
In Sublime Text 2/3, you can use Package Control to install
|
||||
[Homebrew-formula-syntax](https://github.com/samueljohn/Homebrew-formula-syntax),
|
||||
which adds highlighting for inline patches.
|
||||
- [Homebrew-formula-syntax](https://github.com/samueljohn/Homebrew-formula-syntax) can be installed with Package Control in Sublime Text 2/3, which adds highlighting for inline patches.
|
||||
|
||||
### Vim
|
||||
[brew.vim](https://github.com/xu-cheng/brew.vim) adds highlighting to
|
||||
inline patches in Vim.
|
||||
|
||||
- [brew.vim](https://github.com/xu-cheng/brew.vim) adds highlighting to inline patches in Vim.
|
||||
|
||||
### Emacs
|
||||
[homebrew-mode](https://github.com/dunn/homebrew-mode) provides syntax
|
||||
highlighting for inline patches as well as a number of helper functions
|
||||
for editing formula files.
|
||||
|
||||
[pcmpl-homebrew](https://github.com/hiddenlotus/pcmpl-homebrew) provides completion
|
||||
for emacs shell-mode and eshell-mode.
|
||||
- [homebrew-mode](https://github.com/dunn/homebrew-mode) provides syntax highlighting for inline patches as well as a number of helper functions for editing formula files.
|
||||
|
||||
- [pcmpl-homebrew](https://github.com/hiddenlotus/pcmpl-homebrew) provides completion for emacs shell-mode and eshell-mode.
|
||||
|
||||
### Atom
|
||||
[language-homebrew-formula](https://atom.io/packages/language-homebrew-formula)
|
||||
adds highlighting and diff support (with the
|
||||
[language-diff](https://atom.io/packages/language-diff) plugin).
|
||||
|
||||
- [language-homebrew-formula](https://atom.io/packages/language-homebrew-formula) adds highlighting and diff support (with the [language-diff](https://atom.io/packages/language-diff) plugin).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user