mirror of
https://github.com/Homebrew/brew.git
synced 2025-07-14 16:09:03 +08:00
docs: code example reformatting
Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
This commit is contained in:
EricFromCanada
parent
59fab56afd
commit
dc7f74210a
@ -5,7 +5,7 @@ Some formulae should not go in
|
||||
additional [Interesting Taps & Forks](Interesting-Taps-&-Forks.md) and anyone can start their
|
||||
own!
|
||||
|
||||
### We try hard to avoid dupes in Homebrew/homebrew
|
||||
### We try hard to avoid dupes in `homebrew/core`
|
||||
Stuff that comes with macOS or libraries that are provided by
|
||||
[RubyGems, CPAN or PyPi](Gems,-Eggs-and-Perl-Modules.md)
|
||||
should not be duplicated. There are good reasons for this:
|
||||
@ -19,8 +19,7 @@ There are exceptions:
|
||||
|
||||
* OpenSSL - Apple has formally deprecated OpenSSL on macOS in favour of their own Security Framework
|
||||
& consequently the macOS OpenSSL is rarely updated and frequently falls behind important security updates.
|
||||
Homebrew endeavours to use our shipped OpenSSL as much
|
||||
as possible.
|
||||
Homebrew endeavours to use our shipped OpenSSL as much as possible.
|
||||
* Programs that a user will regularly interact with directly, like editors and
|
||||
language runtimes
|
||||
* Libraries that provide functionality or contain security updates not found in
|
||||
@ -57,7 +56,7 @@ 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
|
||||
Our policy is that formulae in the core tap
|
||||
([homebrew/core](https://github.com/Homebrew/homebrew-core)) must be open-source
|
||||
and either built from source or produce cross-platform binaries (e.g. Java).
|
||||
Binary-only formulae should go to
|
||||
@ -101,7 +100,7 @@ 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.
|
||||
|
||||
### Stuff that builds an .app
|
||||
### Stuff that builds an `.app`
|
||||
Don’t make your formula build an `.app` (native macOS Application); we
|
||||
don’t want those things in Homebrew (but
|
||||
[Homebrew Cask](https://github.com/caskroom/homebrew-cask) does).
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 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 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 <formula>`. If you wish to disable this you can do so by specifying `--build-from-source`.
|
||||
|
||||
@ -17,21 +17,18 @@ on the result of the job.
|
||||
For example, a job which has been queued but not yet completed will have a
|
||||
section in the pull request that looks like this:
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
A failed build looks like this:
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
A passed build looks like this:
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
@ -43,14 +40,12 @@ When you click this you'll see the results.
|
||||
|
||||
A passed build looks like this:
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
A failed build looks like this:
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@ -3,10 +3,10 @@
|
||||
There are two C++ standard libraries supported by Apple compilers.
|
||||
|
||||
The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC
|
||||
compilers, GNU GCC compilers, and clang. This was marked deprecated with a
|
||||
compilers, GNU GCC compilers, and `clang`. This was marked deprecated with a
|
||||
warning during compile as of Xcode 8.
|
||||
|
||||
The default for 10.9 is **libc++**, which is also the default for clang on older
|
||||
The default for 10.9 is **libc++**, which is also the default for `clang` on older
|
||||
platforms when building C++11 code.
|
||||
|
||||
There are subtle incompatibilities between several of the C++ standard libraries,
|
||||
|
||||
@ -17,12 +17,14 @@ After running `brew update`, you receive a Git error warning about untracked fil
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
cd $(brew --repository)
|
||||
git reset --hard FETCH_HEAD
|
||||
```
|
||||
|
||||
If `brew doctor` still complains about uncommitted modifications, also run this command:
|
||||
```bash
|
||||
|
||||
```sh
|
||||
cd $(brew --repository)/Library
|
||||
git clean -fd
|
||||
```
|
||||
@ -42,8 +44,8 @@ The incompatibilities have been addressed in more recent versions of Homebrew, a
|
||||
|
||||
To recover from this situation, do the following:
|
||||
|
||||
```
|
||||
cd /usr/local # your Homebrew prefix
|
||||
```sh
|
||||
cd $(brew --prefix)
|
||||
git fetch origin
|
||||
git reset --hard FETCH_HEAD
|
||||
brew update
|
||||
@ -56,9 +58,10 @@ When trying to load a plist file into launchctl, you receive an error that resem
|
||||
Bug: launchctl.c:2325 (23930):13: (dbfd = open(g_job_overrides_db_path, [...]
|
||||
launch_msg(): Socket is not connected
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
```
|
||||
Could not open job overrides database at: /private/var/db/launchd.db/com.apple.launchd/overrides.plist: 13: Permission denied
|
||||
launch_msg(): Socket is not connected
|
||||
```
|
||||
@ -68,11 +71,12 @@ These are likely due to one of four issues:
|
||||
1. You are using iTerm. The solution is to use Terminal.app when interacting with `launchctl`.
|
||||
2. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell.
|
||||
3. You are attempting to run `launchctl` while logged in remotely. You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine.
|
||||
4. You are su'ed as a different user.
|
||||
4. You are `su`'ed as a different user.
|
||||
|
||||
### `brew upgrade` errors out
|
||||
When running `brew upgrade`, you see something like this:
|
||||
```text
|
||||
|
||||
```
|
||||
$ brew upgrade
|
||||
Error: undefined method `include?' for nil:NilClass
|
||||
Please report this bug:
|
||||
@ -89,23 +93,24 @@ Please report this bug:
|
||||
|
||||
This happens because an old version of the upgrade command is hanging around for some reason. The fix:
|
||||
|
||||
```
|
||||
$ cd $(brew --repository)/Library/Contributions/examples
|
||||
$ git clean -n # if this doesn't list anything that you want to keep, then
|
||||
$ git clean -f # this will remove untracked files
|
||||
```sh
|
||||
cd $(brew --repository)/Library/Contributions/examples
|
||||
git clean -n # if this doesn't list anything that you want to keep, then
|
||||
git clean -f # this will remove untracked files
|
||||
```
|
||||
|
||||
### Python: easy-install.pth cannot be linked
|
||||
|
||||
```
|
||||
Warning: Could not link <formulaname>. Unlinking...
|
||||
Warning: Could not link <formula>. Unlinking...
|
||||
Error: The `brew link` step did not complete successfully
|
||||
The formula built, but is not symlinked into /usr/local
|
||||
You can try again using `brew link <formulaname>'
|
||||
You can try again using `brew link <formula>'
|
||||
|
||||
Possible conflicting files are:
|
||||
/usr/local/lib/python2.7/site-packages/site.py
|
||||
/usr/local/lib/python2.7/site-packages/easy-install.pth
|
||||
==> Could not symlink file: /homebrew/Cellar/<formulaname>/<version>/lib/python2.7/site-packages/site.py
|
||||
==> Could not symlink file: /homebrew/Cellar/<formula>/<version>/lib/python2.7/site-packages/site.py
|
||||
Target /usr/local/lib/python2.7/site-packages/site.py already exists. You may need to delete it.
|
||||
To force the link and overwrite all other conflicting files, do:
|
||||
brew link --overwrite formula_name
|
||||
@ -127,7 +132,7 @@ Upgrading macOS can cause errors like the following:
|
||||
|
||||
Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and `brew upgrade` all installed formula:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
xcode-select --install
|
||||
brew upgrade
|
||||
```
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
Homebrew depends on having an up-to-date version of Xcode because it comes with
|
||||
specific versions of build tools, e.g. `clang`.
|
||||
|
||||
Installing a custom version of GCC or `autotools` into the `$PATH` has the
|
||||
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
|
||||
compilers.
|
||||
|
||||
@ -18,4 +18,4 @@ GCC or cross-compiler suite, please link it in here.
|
||||
C++11 support on earlier versions.
|
||||
* 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.
|
||||
toolchain including binutils and GCC.
|
||||
|
||||
@ -2,8 +2,8 @@
|
||||
|
||||
Homebrew, like Git, supports *external commands*. This lets you create new commands that can be run like:
|
||||
|
||||
```shell
|
||||
$ brew mycommand --option1 --option3 formula
|
||||
```sh
|
||||
brew mycommand --option1 --option3 formula
|
||||
```
|
||||
|
||||
without modifying Homebrew's internals.
|
||||
@ -11,7 +11,7 @@ without modifying Homebrew's internals.
|
||||
## 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`.
|
||||
In both cases, the command file should be executable (`chmod +x`) and live somewhere in `PATH`.
|
||||
|
||||
### 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.
|
||||
@ -24,7 +24,7 @@ A shell script for a command named `extcmd` should be named `brew-extcmd`. This
|
||||
| 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_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). |
|
||||
@ -41,12 +41,13 @@ Check if there is a new upstream version of a formula.
|
||||
See the [`README`](https://github.com/youtux/homebrew-livecheck/blob/master/README.md) for more info and usage.
|
||||
|
||||
Install using:
|
||||
|
||||
```sh
|
||||
brew tap youtux/livecheck
|
||||
```
|
||||
|
||||
### brew-gem
|
||||
Install any gem package into a self-contained Homebrew cellar location: <https://github.com/sportngin/brew-gem>
|
||||
Install any `gem` package into a self-contained Homebrew Cellar location: <https://github.com/sportngin/brew-gem>
|
||||
|
||||
Note this can also be installed with `brew install brew-gem`.
|
||||
|
||||
@ -57,6 +58,7 @@ Get Growl notifications for Homebrew: <https://github.com/secondplanet/homebrew-
|
||||
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.): <https://github.com/Homebrew/homebrew-services>
|
||||
|
||||
Install using:
|
||||
|
||||
```sh
|
||||
brew tap homebrew/services
|
||||
```
|
||||
|
||||
49
docs/FAQ.md
49
docs/FAQ.md
@ -15,22 +15,22 @@ Upgrade everything with:
|
||||
|
||||
Or upgrade a specific formula with:
|
||||
|
||||
brew upgrade $FORMULA
|
||||
brew upgrade <formula>
|
||||
|
||||
## How do I stop certain formulae from being updated?
|
||||
To stop something from being updated/upgraded:
|
||||
|
||||
brew pin $FORMULA
|
||||
brew pin <formula>
|
||||
|
||||
To allow that formulae to update again:
|
||||
|
||||
brew unpin $FORMULA
|
||||
brew unpin <formula>
|
||||
|
||||
## How do I uninstall old versions of a formula?
|
||||
By default, Homebrew does not uninstall old versions of a formula, so
|
||||
over time you will accumulate old versions. To remove them, simply use:
|
||||
|
||||
brew cleanup $FORMULA
|
||||
brew cleanup <formula>
|
||||
|
||||
or clean up everything at once:
|
||||
|
||||
@ -43,9 +43,10 @@ or to see what would be cleaned up:
|
||||
## How do I uninstall Homebrew?
|
||||
To uninstall Homebrew, paste the command below in a terminal prompt.
|
||||
|
||||
```bash
|
||||
```sh
|
||||
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"
|
||||
```
|
||||
|
||||
Download the [uninstall script](https://raw.githubusercontent.com/Homebrew/install/master/uninstall)
|
||||
and run `./uninstall --help` to view more uninstall options.
|
||||
|
||||
@ -84,9 +85,9 @@ at <https://bintray.com/homebrew/bottles>.
|
||||
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`
|
||||
will use a bottled version of $FORMULA, but
|
||||
`brew install $FORMULA --enable-bar` will trigger a source build.
|
||||
* Options were passed to the install command, i.e. `brew install <formula>`
|
||||
will use a bottled version of the formula, but
|
||||
`brew install <formula> --enable-bar` will trigger a source build.
|
||||
* The `--build-from-source` option is invoked.
|
||||
* The environment variable `HOMEBREW_BUILD_FROM_SOURCE` is set.
|
||||
* The machine is not running a supported version of macOS as all
|
||||
@ -102,18 +103,20 @@ We aim to bottle everything.
|
||||
|
||||
## How do I get a formula from someone else’s branch?
|
||||
|
||||
brew install hub
|
||||
brew update
|
||||
cd $(brew --repository)
|
||||
hub pull someone_else
|
||||
```sh
|
||||
brew install hub
|
||||
brew update
|
||||
cd $(brew --repository)
|
||||
hub pull someone_else
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
`brew install https://raw.github.com/user/repo/branch/formula.rb`
|
||||
brew install https://raw.github.com/user/repo/branch/formula.rb
|
||||
|
||||
Or:
|
||||
|
||||
`brew pull https://github.com/Homebrew/homebrew-core/pull/1234`
|
||||
brew pull https://github.com/Homebrew/homebrew-core/pull/1234
|
||||
|
||||
## Why does Homebrew prefer I install to `/usr/local`?
|
||||
|
||||
@ -168,20 +171,20 @@ If it’s not in `man brew`, it’s probably an external command. These are docu
|
||||
If it’s been a while, bump it with a “bump” comment. Sometimes we miss requests and there are plenty of them. Maybe we were thinking on something. It will encourage consideration. In the meantime if you could rebase the pull request so that it can be cherry-picked more easily we will love you for a long time.
|
||||
|
||||
## Can I edit formulae myself?
|
||||
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!
|
||||
Yes! It’s easy! Just `brew edit <formula>`. You don’t have to submit modifications back to `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
|
||||
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`,
|
||||
formula in `EDITOR` so you can edit it, but it probably already
|
||||
installs; try it: `brew install <formula>`. If you encounter any issues,
|
||||
run the command with the `-d` switch like so: `brew install -d <formula>`,
|
||||
which drops you into a debugging shell.
|
||||
|
||||
If you want your new formula to be part of *homebrew/core* or want
|
||||
If you want your new formula to be part of `homebrew/core` or want
|
||||
to learn more about writing formulae, then please read the [Formula Cookbook](Formula-Cookbook.md).
|
||||
|
||||
## Can I install my own stuff to `/usr/local`?
|
||||
Yes, brew is designed to not get in your way so you can use it how you
|
||||
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
|
||||
@ -192,7 +195,7 @@ about this.
|
||||
Thus it’s probably better to install your own stuff to the Cellar and
|
||||
then `brew link` it. Like so:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
$ cd foo-0.1
|
||||
$ brew diy
|
||||
./configure --prefix=/usr/local/Cellar/foo/0.1
|
||||
@ -204,7 +207,7 @@ Linking /usr/local/Cellar/foo/0.1… 17 symlinks created
|
||||
```
|
||||
|
||||
## Why was a formula deleted?
|
||||
Use `brew log $FORMULA` to find out! Likely because it had unresolved issues or
|
||||
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's too generic, why was it chosen?
|
||||
@ -220,7 +223,7 @@ this for stupid reasons. You can still link in the formula if you need
|
||||
to with `brew link`.
|
||||
|
||||
## How can I specify different configure arguments for a formula?
|
||||
`brew edit $FORMULA` and edit the formula. Currently there is no
|
||||
`brew edit <formula>` and edit the formula. Currently there is no
|
||||
other way to do this.
|
||||
|
||||
## Is there a glossary of terms around?
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Formula Cookbook
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@ -30,12 +30,12 @@ Make sure you run `brew update` before you start. This turns your Homebrew insta
|
||||
Before submitting a new formula make sure your package:
|
||||
|
||||
* meets all our [Acceptable Formulae](Acceptable-Formulae.md) requirements
|
||||
* isn't already in Homebrew (check `brew search $FORMULA`)
|
||||
* isn't already in Homebrew (check `brew search <formula>`)
|
||||
* 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)
|
||||
* passes all `brew audit --new-formula $FORMULA` tests.
|
||||
* 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).
|
||||
|
||||
@ -43,11 +43,11 @@ Before submitting a new formula make sure you read over our [contribution guidel
|
||||
|
||||
Run `brew create` with a URL to the source tarball:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
brew create https://example.com/foo-0.1.tar.gz
|
||||
```
|
||||
|
||||
This creates `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` and opens it in your `$EDITOR`. It'll look something like:
|
||||
This creates `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` and opens it in your `EDITOR`. It'll look something like:
|
||||
|
||||
```ruby
|
||||
class Foo < Formula
|
||||
@ -77,7 +77,7 @@ end
|
||||
If `brew` said `Warning: Version cannot be determined from URL` when doing the `create` step, you’ll need to explicitly add the correct [`version`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#version-class_method) to the formula and then save the formula.
|
||||
|
||||
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 <url> --set-name <name>`.
|
||||
so you can override this with `brew create <URL> --set-name <name>`.
|
||||
|
||||
### Fill in the [`homepage`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#homepage%3D-class_method)
|
||||
|
||||
@ -89,7 +89,7 @@ Try to summarize from the [`homepage`](http://www.rubydoc.info/github/Homebrew/b
|
||||
|
||||
### Check the build system
|
||||
|
||||
```shell
|
||||
```sh
|
||||
brew install -i foo
|
||||
```
|
||||
|
||||
@ -126,7 +126,7 @@ to favour finding `keg_only` formulae first.
|
||||
|
||||
Homebrew maintains a special [tap that provides other useful system duplicates](https://github.com/Homebrew/homebrew-dupes).
|
||||
|
||||
*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).
|
||||
*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
|
||||
|
||||
@ -217,7 +217,7 @@ When a version scheme of a formula fails to recognise a new version as newer it
|
||||
|
||||
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`):
|
||||
|
||||
```shell
|
||||
```sh
|
||||
$ otool -L /usr/local/bin/ldapvi
|
||||
/usr/local/bin/ldapvi:
|
||||
/usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
|
||||
@ -257,7 +257,7 @@ end
|
||||
|
||||
### Install the formula
|
||||
|
||||
```shell
|
||||
```sh
|
||||
brew install --verbose --debug foo
|
||||
```
|
||||
|
||||
@ -325,7 +325,7 @@ correct. Add an explicit [`version`](http://www.rubydoc.info/github/Homebrew/bre
|
||||
|
||||
Everything is built on Git, so contribution is easy:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
brew update # required in more ways than you think (initializes the brew git repository if you don't already have it)
|
||||
cd $(brew --repo homebrew/core)
|
||||
# Create a new git branch for your formula so your pull request is easy to
|
||||
@ -356,7 +356,7 @@ If you haven’t forked Homebrew yet, [go to the `homebrew-core` repository and
|
||||
|
||||
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):
|
||||
|
||||
```shell
|
||||
```sh
|
||||
git push https://github.com/myname/homebrew-core/ <what-you-called-your-branch>
|
||||
```
|
||||
|
||||
@ -392,7 +392,9 @@ You’ll see stuff like this in some formulae. This moves the file `foo` into th
|
||||
|
||||
A convenience function that can edit files in-place. For example:
|
||||
|
||||
`inreplace "path", before, after`
|
||||
```ruby
|
||||
inreplace "path", before, after
|
||||
```
|
||||
|
||||
`before` and `after` can be strings or regular expressions. You should use the block form if you need to make multiple replacements in a file:
|
||||
|
||||
@ -409,11 +411,11 @@ Make sure you modify `s`! This block ignores the returned value.
|
||||
|
||||
If you need modify variables in a `Makefile`, rather than using `inreplace`, pass them as arguments to `make`:
|
||||
|
||||
```rb
|
||||
```ruby
|
||||
system "make", "target", "VAR2=value1", "VAR2=value2", "VAR3=values can have spaces"
|
||||
```
|
||||
|
||||
```rb
|
||||
```ruby
|
||||
args = %W[
|
||||
CC=#{ENV.cc}
|
||||
PREFIX=#{prefix}
|
||||
@ -452,7 +454,7 @@ end
|
||||
|
||||
[`patch`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#patch-class_method)es can be declared in [`stable`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#stable-class_method), [`devel`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#devel-class_method), and [`head`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#head-class_method) blocks. NOTE: always use a block instead of a conditional, i.e. `stable do ... end` instead of `if build.stable? then ... end`.
|
||||
|
||||
```rb
|
||||
```ruby
|
||||
stable do
|
||||
# some other things...
|
||||
|
||||
@ -465,7 +467,7 @@ end
|
||||
|
||||
Embedded (__END__) patches can be declared like so:
|
||||
|
||||
```rb
|
||||
```ruby
|
||||
patch :DATA
|
||||
patch :p0, :DATA
|
||||
```
|
||||
@ -483,6 +485,7 @@ index 643c60b..543379c 100644
|
||||
```
|
||||
|
||||
Patches can also be embedded by passing a string. This makes it possible to provide multiple embedded patches while making only some of them conditional.
|
||||
|
||||
```rb
|
||||
patch :p0, "..."
|
||||
```
|
||||
@ -491,7 +494,7 @@ In embedded patches, the string `HOMEBREW_PREFIX` is replaced with the value of
|
||||
|
||||
### Creating the diff
|
||||
|
||||
```shell
|
||||
```sh
|
||||
brew install --interactive --git foo
|
||||
# (make some edits)
|
||||
git diff | pbcopy
|
||||
@ -557,7 +560,7 @@ fails_with :llvm do
|
||||
the URLs of any relevant information, such as upstream bug reports. Wrap
|
||||
the text at a sensible boundary (~72-80 characters), but do not break
|
||||
URLs over multiple lines.
|
||||
EOS
|
||||
EOS
|
||||
end
|
||||
```
|
||||
|
||||
@ -592,7 +595,6 @@ Download strategies offered by Homebrew are:
|
||||
|
||||
If you need more control over the way files are downloaded and staged, you can create a custom download strategy and specify it using the [`url`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#url-class_method) method's `:using` option:
|
||||
|
||||
|
||||
```ruby
|
||||
class MyDownloadStrategy < SomeHomebrewDownloadStrategy
|
||||
# Does something cool
|
||||
@ -649,7 +651,7 @@ These can be used, for instance, in code such as
|
||||
bin.install Dir["output/*"]
|
||||
```
|
||||
|
||||
to move binaries into their correct location into the cellar, and
|
||||
to move binaries into their correct location into the Cellar, and
|
||||
|
||||
```ruby
|
||||
man.mkpath
|
||||
@ -756,7 +758,7 @@ If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew-co
|
||||
|
||||
Check out what MacPorts and Fink do:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
brew -S --macports foo
|
||||
brew -S --fink foo
|
||||
```
|
||||
@ -779,7 +781,7 @@ When using Homebrew's `gfortran` compiler, the standard `CFLAGS` are used and us
|
||||
|
||||
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
|
||||
```sh
|
||||
git checkout -f master
|
||||
git reset --hard origin/master
|
||||
```
|
||||
|
||||
@ -10,7 +10,7 @@ add-ons available to all users:
|
||||
Starting with OS X Lion (10.7), you need `sudo` to install to these like
|
||||
so: `sudo gem install`, `sudo easy_install` or `sudo cpan -i`.
|
||||
|
||||
An option to avoid `sudo` is to use an access control list:
|
||||
An option to avoid sudo is to use an access control list:
|
||||
`chmod +a 'user:YOUR_NAME_HERE allow add_subdirectory,add_file,delete_child,directory_inherit' /Library/Python/2.7/site-packages`,
|
||||
for example, will let you add packages to Python 2.7 as yourself. That
|
||||
is probably safer than changing the group ownership of the directory.
|
||||
@ -23,13 +23,14 @@ 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 the use of sudo.
|
||||
|
||||
Rather than changing the rights on /Library/Python, we recommend the
|
||||
## Python packages (eggs) without sudo
|
||||
|
||||
Rather than changing the rights on `/Library/Python`, we recommend the
|
||||
following options:
|
||||
|
||||
### With a brewed Python
|
||||
Note, `easy_install` is deprecated. We install `pip` (or `pip3` for
|
||||
python3) along with python/python3.
|
||||
Python 3) 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
|
||||
@ -47,7 +48,10 @@ On macOS, any [Python version X.Y also searches in
|
||||
`~/Library/Python/X.Y/lib/python/site-packages` for
|
||||
modules](https://docs.python.org/2/install/index.html#inst-alt-install-user).
|
||||
That dir might not yet exist, but you can create it:
|
||||
`mkdir -p ~/Library/Python/2.7/lib/python/site-packages`
|
||||
|
||||
```sh
|
||||
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
|
||||
@ -76,20 +80,26 @@ 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
|
||||
or use this:
|
||||
|
||||
echo "gem: -n/usr/local/bin" >> ~/.gemrc
|
||||
```sh
|
||||
echo "gem: -n/usr/local/bin" >> ~/.gemrc
|
||||
```
|
||||
|
||||
**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`
|
||||
```sh
|
||||
sudo gem update --system
|
||||
```
|
||||
|
||||
### An alternative
|
||||
|
||||
Just install everything into the Homebrew prefix like this:
|
||||
|
||||
`echo "export GEM_HOME=\"$(brew --prefix)\"" >> ~/.bashrc`
|
||||
```sh
|
||||
echo "export GEM_HOME=\"$(brew --prefix)\"" >> ~/.bashrc
|
||||
```
|
||||
|
||||
### It doesn’t work! I get some “permissions” error when I try to install stuff!
|
||||
|
||||
@ -99,23 +109,29 @@ is not a good default.*
|
||||
If you ever did a `sudo gem`, etc. before then a lot of files will have
|
||||
been created owned by root. Fix with:
|
||||
|
||||
`sudo chown -R $USER /Library/Ruby /Library/Perl /Library/Python`
|
||||
```sh
|
||||
sudo chown -R $USER /Library/Ruby /Library/Perl /Library/Python
|
||||
```
|
||||
|
||||
## Perl CPAN modules without sudo
|
||||
|
||||
The Perl module local::lib works similarly to rbenv/RVM (although for
|
||||
The Perl module `local::lib` works similarly to rbenv/RVM (although for
|
||||
modules only, not perl installations). A simple solution that only
|
||||
pollutes your /Library/Perl a little is to install
|
||||
[local::lib](https://metacpan.org/pod/local::lib) with sudo:
|
||||
pollutes your `/Library/Perl` a little is to install
|
||||
[`local::lib`](https://metacpan.org/pod/local::lib) with sudo:
|
||||
|
||||
`sudo cpan local::lib`
|
||||
```sh
|
||||
sudo cpan local::lib
|
||||
```
|
||||
|
||||
Note that this will install some other dependencies like `Module::Install`.
|
||||
Then put the appropriate incantation in your shell’s startup, e.g. for
|
||||
`.bash_profile` you insert the below, for others see the
|
||||
[local::lib](https://metacpan.org/pod/local::lib) docs.
|
||||
[`local::lib`](https://metacpan.org/pod/local::lib) docs.
|
||||
|
||||
`eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)`
|
||||
```sh
|
||||
eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)
|
||||
```
|
||||
|
||||
Now (after you restart your shell) `cpan` or `perl -MCPAN -eshell` etc.
|
||||
will install modules and binaries in `~/perl5` and the relevant
|
||||
@ -124,11 +140,12 @@ 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
|
||||
~/perl5 and add the relevant path to `PERL5LIB` before the .bashrc eval incantation.
|
||||
`local::lib`, just manually install `local::lib` in
|
||||
`~/perl5` and add the relevant path to `PERL5LIB` before the .bashrc eval incantation.
|
||||
|
||||
```bash
|
||||
Another alternative is to use `perlbrew` to install a separate copy of Perl in your home directory, or wherever you like:
|
||||
|
||||
```sh
|
||||
curl -L https://install.perlbrew.pl | bash
|
||||
perlbrew install perl-5.16.2
|
||||
echo ".~/perl5/perlbrew/etc/bashrc" >> ~/.bashrc
|
||||
|
||||
@ -8,42 +8,48 @@ 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.
|
||||
|
||||
|
||||
## Python 2.x or Python 3.x
|
||||
Homebrew provides a formula for Python 2.7.x and one for Python 3.x. They don't conflict, so they can both be installed. The executable `python` will always point to the 2.x and `python3` to the 3.x version.
|
||||
|
||||
([Wondering which one to choose?](https://wiki.python.org/moin/Python2orPython3))
|
||||
|
||||
|
||||
## Setuptools, Pip, etc.
|
||||
The Python formulae install [`pip`](http://www.pip-installer.org) and [Setuptools](https://pypi.python.org/pypi/setuptools).
|
||||
|
||||
Setuptools can be updated via Pip, without having to re-brew Python:
|
||||
Setuptools can be updated via pip, without having to re-brew Python:
|
||||
|
||||
pip install --upgrade setuptools
|
||||
```sh
|
||||
pip install --upgrade setuptools
|
||||
```
|
||||
|
||||
Similarly, Pip can be used to upgrade itself via:
|
||||
Similarly, pip can be used to upgrade itself via:
|
||||
|
||||
pip install --upgrade pip
|
||||
```sh
|
||||
pip install --upgrade pip
|
||||
```
|
||||
|
||||
### Note on `pip install --user`
|
||||
The normal `pip install --user` is disabled for brewed Python. This is because of a bug in distutils, because Homebrew writes a `distutils.cfg` which sets the package `prefix`.
|
||||
|
||||
A possible workaround (which puts executable scripts in `~/Library/Python/<X>.<Y>/bin`) is:
|
||||
|
||||
pip install --user --install-option="--prefix=" <package-name>
|
||||
```sh
|
||||
pip install --user --install-option="--prefix=" <package-name>
|
||||
```
|
||||
|
||||
## `site-packages` and the `PYTHONPATH`
|
||||
The `site-packages` is a directory that contains Python modules (especially bindings installed by other formulae). Homebrew creates it here:
|
||||
|
||||
$(brew --prefix)/lib/pythonX.Y/site-packages
|
||||
```sh
|
||||
$(brew --prefix)/lib/pythonX.Y/site-packages
|
||||
```
|
||||
|
||||
So, for Python 2.7.x, you'll find it at `/usr/local/lib/python2.7/site-packages`.
|
||||
|
||||
Python 2.7 also searches for modules in:
|
||||
|
||||
- `/Library/Python/2.7/site-packages`
|
||||
- `~/Library/Python/2.7/lib/python/site-packages`
|
||||
- `/Library/Python/2.7/site-packages`
|
||||
- `~/Library/Python/2.7/lib/python/site-packages`
|
||||
|
||||
Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`.
|
||||
|
||||
@ -51,23 +57,23 @@ Homebrew's `site-packages` directory is first created if (1) any Homebrew formul
|
||||
The reasoning for this location is to preserve your modules between (minor) upgrades or re-installations of Python. Additionally, Homebrew has a strict policy never to write stuff outside of the `brew --prefix`, so we don't spam your system.
|
||||
|
||||
## Homebrew-provided Python bindings
|
||||
Some formulae provide python bindings. Sometimes a `--with-python` or `--with-python3` option has to be passed to `brew install` in order to build the python bindings. (Check with `brew options <formula>`.)
|
||||
Some formulae provide Python bindings. Sometimes a `--with-python` or `--with-python3` option has to be passed to `brew install` in order to build the Python bindings. (Check with `brew options <formula>`.)
|
||||
|
||||
Homebrew builds bindings against the first `python` (and `python-config`) in your `PATH`. (Check with `which python`).
|
||||
|
||||
**Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import <module>` from a brewed Python if you ran `brew install <formula_with_python_bindings>` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with python bindings (e.g. `pyside`, `wxwidgets`, `pygtk`, `pygobject`, `opencv`, `vtk` and `boost-python`).
|
||||
**Warning!** Python may crash (see [Common Issues](Common-Issues.md)) if you `import <module>` from a brewed Python if you ran `brew install <formula_with_python_bindings>` against the system Python. If you decide to switch to the brewed Python, then reinstall all formulae with Python bindings (e.g. `pyside`, `wxwidgets`, `pygtk`, `pygobject`, `opencv`, `vtk` and `boost-python`).
|
||||
|
||||
## Policy for non-brewed Python bindings
|
||||
These should be installed via `pip install <x>`. To discover, you can use `pip search` or <https://pypi.python.org/pypi>. (**Note:** System Python does not provide `pip`. Follow the instructions at <https://pip.readthedocs.io/en/stable/installing/#install-pip> to install it for your system Python if you would like it.)
|
||||
|
||||
These should be installed via `pip install <package>`. To discover, you can use `pip search` or <https://pypi.python.org/pypi>. (**Note:** System Python does not provide `pip`. Follow the instructions at <https://pip.readthedocs.io/en/stable/installing/#install-pip> to install it for your system Python if you would like it.)
|
||||
|
||||
## Brewed Python modules
|
||||
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`.
|
||||
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 run:
|
||||
|
||||
`CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install <package>`.
|
||||
|
||||
```sh
|
||||
CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install <package>
|
||||
```
|
||||
|
||||
## Virtualenv
|
||||
**WARNING:** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**.
|
||||
@ -78,4 +84,4 @@ Homebrew will still install Python modules into Homebrew's `site-packages` and *
|
||||
Virtualenv has a switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv.
|
||||
|
||||
## Why is Homebrew's Python being installed as a dependency?
|
||||
Formulae that depend on the special :python target are bottled against the Homebrew Python and require it to be installed. You can avoid installing Homebrew's Python by building these formulae with `--build-from-source`.
|
||||
Formulae that depend on the special `:python` target are bottled against the Homebrew Python and require it to be installed. You can avoid installing Homebrew's Python by building these formulae with `--build-from-source`.
|
||||
|
||||
@ -16,7 +16,7 @@ repository’s root, or under `Formula` or `HomebrewFormula` subdirectories. We
|
||||
recommend the latter options because it makes the repository organisation
|
||||
easier to grasp, and top-level files are not mixed with formulae.
|
||||
|
||||
See [homebrew/tex](https://github.com/Homebrew/homebrew-tex) for an example of
|
||||
See [homebrew/php](https://github.com/Homebrew/homebrew-php) for an example of
|
||||
a tap with a `Formula` subdirectory.
|
||||
|
||||
### Installing
|
||||
@ -32,8 +32,8 @@ users can add it with the [`brew tap` command](brew-tap.md).
|
||||
If it’s on GitHub, they can use `brew tap user/repo`, where `user` is your
|
||||
GitHub username and `homebrew-repo` your repository.
|
||||
|
||||
If it’s hosted outside of GitHub, they have to use `brew tap user/repo <url>`,
|
||||
where `user` and `repo` will be used to refer to your tap and `<url>` is your
|
||||
If it’s hosted outside of GitHub, they have to use `brew tap user/repo <URL>`,
|
||||
where `user` and `repo` will be used to refer to your tap and `<URL>` is your
|
||||
Git clone URL.
|
||||
|
||||
Users can then install your formulae either with `brew install foo` if there’s
|
||||
|
||||
@ -6,13 +6,13 @@ The [FAQ](FAQ.md) briefly explains this.
|
||||
|
||||
As an example:
|
||||
|
||||
*OpenSSL isn’t symlinked into my `$PATH` and non-Homebrew builds can’t find it!*
|
||||
*OpenSSL isn’t symlinked into my `PATH` and non-Homebrew builds can’t find it!*
|
||||
|
||||
This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location, usually `/usr/local`.
|
||||
|
||||
## Advice on potential workarounds
|
||||
|
||||
A number of people in this situation are either forcefully linking `keg_only` tools with `brew link --force` or moving default system utilities out of the `$PATH` and replacing them with manually-created symlinks to the Homebrew-provided tool.
|
||||
A number of people in this situation are either forcefully linking `keg_only` tools with `brew link --force` or moving default system utilities out of the `PATH` and replacing them with manually-created symlinks to the Homebrew-provided tool.
|
||||
|
||||
*Please* do not remove macOS native tools and forcefully replace them with symlinks back to the Homebrew-provided tool. Doing so can and likely will cause significant breakage when attempting to build software.
|
||||
|
||||
@ -26,27 +26,27 @@ Useful, reliable alternatives exist should you wish to use `keg_only` tools outs
|
||||
|
||||
You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
./configure --prefix=/Users/Dave/Downloads CFLAGS=-I$(brew --prefix)/opt/openssl/include LDFLAGS=-L$(brew --prefix)/opt/openssl/lib
|
||||
```
|
||||
|
||||
An example using `pip`:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
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:
|
||||
You can temporarily prepend your `PATH` with the tool’s bin directory, such as:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
export PATH=$(brew --prefix)/opt/openssl/bin:$PATH
|
||||
```
|
||||
|
||||
This will prepend that folder to your `$PATH`, ensuring any build script that searches the `$PATH` will find it first.
|
||||
This will prepend that folder to your `PATH`, ensuring any build script that searches the `PATH` will find it first.
|
||||
|
||||
Changing your `$PATH` using that command ensures the change only exists for the duration of that shell session. Once you are no longer in that session, the `$PATH` reverts to the prior state.
|
||||
Changing your `PATH` using 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
|
||||
|
||||
@ -54,7 +54,7 @@ If the tool you are attempting to build is [pkg-config](https://en.wikipedia.org
|
||||
|
||||
An example of this is:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig
|
||||
```
|
||||
|
||||
@ -62,6 +62,6 @@ If you’re curious about the `PKG_CONFIG_PATH` variable `man pkg-config` goes i
|
||||
|
||||
You can get `pkg-config` to detail the default search path with:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
pkg-config --variable pc_path pkg-config
|
||||
```
|
||||
|
||||
@ -31,10 +31,12 @@ not build when installed elsewhere. One of the reasons Homebrew just
|
||||
works relative to the competition is **because** we recommend installing
|
||||
to `/usr/local`. *Pick another prefix at your peril!*
|
||||
|
||||
`mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew`
|
||||
```sh
|
||||
mkdir homebrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C homebrew
|
||||
```
|
||||
|
||||
### Multiple installations
|
||||
Create a Homebrew installation wherever you extract the tarball. Whichever brew command is called is where the packages will be installed. You can use this as you see fit, e.g. a system set of libs in `/usr/local` and tweaked formulae for development in `~/homebrew`.
|
||||
Create a Homebrew installation wherever you extract the tarball. Whichever `brew` command is called is where the packages will be installed. You can use this as you see fit, e.g. a system set of libs in `/usr/local` and tweaked formulae for development in `~/homebrew`.
|
||||
|
||||
## Uninstallation
|
||||
Uninstallation is documented in the [FAQ](FAQ.md).
|
||||
|
||||
@ -7,7 +7,7 @@ Homebrew has the capability to add (and remove) multiple taps to your local inst
|
||||
|
||||
* [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.
|
||||
|
||||
* [homebrew/boneyard](https://github.com/Homebrew/homebrew-boneyard): Formulae from other official taps, primarily (homebrew/core) are not deleted, they are moved here.
|
||||
* [homebrew/boneyard](https://github.com/Homebrew/homebrew-boneyard): Formulae from other official taps, primarily `homebrew/core` are not deleted, they are moved here.
|
||||
|
||||
* [homebrew/bundle](https://github.com/Homebrew/homebrew-bundle): Bundler for non-Ruby dependencies from Homebrew.
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
There are times when we may wish to migrate a formula from one tap into another tap. To do this:
|
||||
|
||||
1. Create a pull request to the new tap adding the formula file as-is from the original tap. Fix any test failures that may occur due to the stricter requirements for new formulae than existing formula (e.g. `brew audit --strict` must pass for that formula).
|
||||
2. Create a pull request to the original tap deleting the formula file and add it to `tap_migrations.json` with a commit message like `gv: migrating to homebrew/x11`.
|
||||
2. Create a pull request to the original tap deleting the formula file and add it to `tap_migrations.json` with a commit message like `gv: migrating to homebrew/science`.
|
||||
3. Put a link for each pull request in the other pull request so the maintainers can merge them both at once.
|
||||
|
||||
Congratulations, you've moved a formula to a tap!
|
||||
|
||||
@ -18,11 +18,9 @@ If the Node module is also available on the npm registry, we prefer npm hosted r
|
||||
|
||||
The npm registry URLs usually have the format of:
|
||||
|
||||
```
|
||||
https://registry.npmjs.org/<name>/-/<name>-<version>.tgz
|
||||
```
|
||||
https://registry.npmjs.org/<name>/-/<name>-<version>.tgz
|
||||
|
||||
Alternatively you could curl the JSON at `https://registry.npmjs.org/<name>` and look for the value of `versions[<version>].dist.tarball` for the correct tarball URL.
|
||||
Alternatively you could `curl` the JSON at `https://registry.npmjs.org/<name>` and look for the value of `versions[<version>].dist.tarball` for the correct tarball URL.
|
||||
|
||||
## Dependencies
|
||||
|
||||
@ -52,7 +50,7 @@ In the following we distinguish between two types of Node modules using formulae
|
||||
* formulae for standard Node modules compatible with npm's global module format which should use [`std_npm_install_args`](#installing-global-style-modules-with-std_npm_install_args-to-libexec) (like [`azure-cli`](https://github.com/Homebrew/homebrew-core/blob/d93fe9ba3bcc9071b699c8da4e7d733518d3337e/Formula/azure-cli.rb) or [`autocode`](https://github.com/Homebrew/homebrew-core/blob/1a670a6269e1e07f86683c2d164977c9bd8a3fb6/Formula/autocode.rb)) and
|
||||
* formulae where the `npm install` step is only one of multiple not exclusively Node related install steps (not compatible with npm's global module format) which have to use [`local_npm_install_args`](#installing-module-dependencies-locally-with-local_npm_install_args) (like [`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))
|
||||
|
||||
Both methods have in common that they are setting the correct environment for using npm inside Homebrew and are returning the arguments for invoking `npm install` for their specific use cases. This includes fixing an important edge case with the npm cache (caused by Homebrew's redirection of `$HOME` during the build and test process) by using our own custom `npm_cache` inside `HOMEBREW_CACHE`, which would otherwise result in very long build times and high disk space usage.
|
||||
Both methods have in common that they are setting the correct environment for using npm inside Homebrew and are returning the arguments for invoking `npm install` for their specific use cases. This includes fixing an important edge case with the npm cache (caused by Homebrew's redirection of `HOME` during the build and test process) by using our own custom `npm_cache` inside `HOMEBREW_CACHE`, which would otherwise result in very long build times and high disk space usage.
|
||||
|
||||
To use them you have to require the Node language module at the beginning of your formula file with:
|
||||
|
||||
@ -60,15 +58,15 @@ To use them you have to require the Node language module at the beginning of you
|
||||
require "language/node"
|
||||
```
|
||||
|
||||
### Installing global style modules with `std_npm_install_args` to libexec
|
||||
### Installing global style modules with `std_npm_install_args` to `libexec`
|
||||
|
||||
In your formula's `install` method, simply cd to the top level of your Node module if necessary and then use `system` to invoke `npm install` with `Language::Node.std_npm_install_args` like:
|
||||
In your formula's `install` method, simply `cd` to the top level of your Node module if necessary and then use `system` to invoke `npm install` with `Language::Node.std_npm_install_args` like:
|
||||
|
||||
```ruby
|
||||
system "npm", "install", *Language::Node.std_npm_install_args(libexec)
|
||||
```
|
||||
|
||||
This will install your Node module in npm's global module style with a custom prefix to `libexec`. All your modules' executables will be automatically resolved by npm into `libexec/"bin"` for you, which is not symlinked into Homebrew's prefix. We need to make sure these are installed. To do this we need to symlink all executables to `bin` with:
|
||||
This will install your Node module in npm's global module style with a custom prefix to `libexec`. All your modules' executables will be automatically resolved by npm into `libexec/bin` for you, which is not symlinked into Homebrew's prefix. We need to make sure these are installed. To do this we need to symlink all executables to `bin` with:
|
||||
|
||||
```ruby
|
||||
bin.install_symlink Dir["#{libexec}/bin/*"]
|
||||
@ -76,7 +74,7 @@ bin.install_symlink Dir["#{libexec}/bin/*"]
|
||||
|
||||
### Installing module dependencies locally with `local_npm_install_args`
|
||||
|
||||
In your formula's `install` method, do any installation steps which need to be done before the `npm install` step and then cd to the top level of the included Node module. Then, use `system` with `Language::Node.local_npm_install_args` to invoke `npm install` like:
|
||||
In your formula's `install` method, do any installation steps which need to be done before the `npm install` step and then `cd` to the top level of the included Node module. Then, use `system` with `Language::Node.local_npm_install_args` to invoke `npm install` like:
|
||||
|
||||
```ruby
|
||||
system "npm", "install", *Language::Node.local_npm_install_args
|
||||
|
||||
@ -8,11 +8,11 @@ Python libraries exist to be imported by other Python modules; they are often de
|
||||
|
||||
Bindings are a special case of libraries that allow Python code to interact with a library or application implemented in another language.
|
||||
|
||||
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.
|
||||
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. Your formula should use this 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)
|
||||
@ -44,12 +44,13 @@ If you submit a formula with this syntax to core, you may be asked to rewrite it
|
||||
|
||||
### 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:
|
||||
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:
|
||||
|
||||
```ruby
|
||||
depends_on :python if MacOS.version <= :snow_leopard
|
||||
```
|
||||
No explicit Python dependency is needed on recent OS versions since /usr/bin is always in `PATH` for Homebrew formulae; on Leopard and older, the python in `PATH` is used if it's at least version 2.7, or else Homebrew's python is installed.
|
||||
|
||||
No explicit Python dependency is needed on recent OS versions since `/usr/bin` is always in `PATH` for Homebrew formulae; on Leopard and older, the python in `PATH` is used if it's at least version 2.7, or else Homebrew's python is installed.
|
||||
|
||||
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.
|
||||
|
||||
@ -61,21 +62,21 @@ All of the Python module dependencies of the application (and their dependencies
|
||||
|
||||
You can use [homebrew-pypi-poet](https://pypi.python.org/pypi/homebrew-pypi-poet) to help you write resource stanzas. To use it, set up a virtualenv and install your package and all its dependencies. Then, `pip install homebrew-pypi-poet` into the same virtualenv. Running `poet some_package` will generate the necessary resource stanzas. You can do this like:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
# Install virtualenvwrapper
|
||||
$ brew install python
|
||||
$ python -m pip install virtualenvwrapper
|
||||
$ source $(brew --prefix)/bin/virtualenvwrapper.sh
|
||||
brew install python
|
||||
python -m pip install virtualenvwrapper
|
||||
source $(brew --prefix)/bin/virtualenvwrapper.sh
|
||||
|
||||
# Set up a temporary virtual environment
|
||||
$ mktmpenv
|
||||
mktmpenv
|
||||
|
||||
# Install the package of interest as well as homebrew-pypi-poet
|
||||
$ pip install some_package homebrew-pypi-poet
|
||||
$ poet some_package
|
||||
pip install some_package homebrew-pypi-poet
|
||||
poet some_package
|
||||
|
||||
# Destroy the temporary virtualenv you just created
|
||||
$ deactivate
|
||||
deactivate
|
||||
```
|
||||
|
||||
Homebrew provides helper methods for instantiating and populating virtualenvs. You can use them by putting `include Language::Python::Virtualenv` on the `Formula` class definition, above `def install`.
|
||||
@ -114,7 +115,7 @@ Installing a formula with dependencies will look like this:
|
||||
|
||||
```ruby
|
||||
class Foo < Formula
|
||||
url ...
|
||||
url "..."
|
||||
|
||||
resource "six" do
|
||||
url "https://pypi.python.org/packages/source/s/six/six-1.9.0.tar.gz"
|
||||
@ -145,6 +146,7 @@ def install
|
||||
venv.link_scripts(bin) { venv.pip_install buildpath }
|
||||
end
|
||||
```
|
||||
|
||||
in case you need to do different things for different resources.
|
||||
|
||||
## Bindings
|
||||
@ -175,25 +177,25 @@ If the `configure` and `make` scripts do not want to install into the Cellar, so
|
||||
1. `cd` into the directory containing the Python bindings
|
||||
1. Call `setup.py` with `system` and `Language::Python.setup_install_args` (as described above)
|
||||
|
||||
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.)
|
||||
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
|
||||
|
||||
### 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.
|
||||
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
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
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 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](https://github.com/Homebrew/homebrew-science/blob/master/matplotlib.rb) formula in [homebrew/science](https://github.com/Homebrew/homebrew-science) deploys this strategy.
|
||||
|
||||
@ -203,37 +205,36 @@ Additional commentary that explains why Homebrew does some of the things it does
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
Setuptools provides the `easy_install` command, which is an end-user package management tool that fetches and installs packages from PyPI, the Python Package Index. Pip is another, newer end-user package management tool, which is also provided outside the standard library. While pip supplants `easy_install`, pip does not replace the other functionality of the setuptools module.
|
||||
Setuptools provides the `easy_install` command, which is an end-user package management tool that fetches and installs packages from PyPI, the Python Package Index. `pip` is another, newer end-user package management tool, which is also provided outside the standard library. While pip supplants `easy_install`, pip does not replace the other functionality of the setuptools module.
|
||||
|
||||
Distutils and pip use a "flat" installation hierarchy that installs modules as individual files under site-packages while `easy_install` installs zipped eggs to site-packages instead.
|
||||
|
||||
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.
|
||||
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`?
|
||||
|
||||
`--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`.
|
||||
`--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`.
|
||||
|
||||
`easy_install` does a few things that we need to avoid:
|
||||
|
||||
* fetches and installs dependencies
|
||||
* upgrades dependencies in sys.path in place
|
||||
* upgrades dependencies in `sys.path` in-place
|
||||
* writes .pth and site.py files which aren't useful for us and cause link conflicts
|
||||
|
||||
setuptools requires that SVEM is used in conjunction with `--record`, which provides a list of files that can later be used to uninstall the package. We don't need or want this because Homebrew can manage uninstallation but since setuptools demands it we comply. The Homebrew convention is to call the record file "installed.txt".
|
||||
Setuptools requires that SVEM is used in conjunction with `--record`, which provides a list of files that can later be used to uninstall the package. We don't need or want this because Homebrew can manage uninstallation but since setuptools demands it we comply. The Homebrew convention is to call the record file "installed.txt".
|
||||
|
||||
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`
|
||||
|
||||
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.
|
||||
`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.
|
||||
|
||||
`--root` [is used](https://mail.python.org/pipermail/distutils-sig/2010-November/017099.html) when installing into a prefix that will not become part of the final installation location of the files, like when building a .rpm or binary distribution. When using a setup.py-based setuptools, `--root` has the side effect of activating `--single-version-externally-managed`. It is not safe to use `--root` with an empty `--prefix` because the `root` is removed from paths when byte-compiling modules.
|
||||
`--root` [is used](https://mail.python.org/pipermail/distutils-sig/2010-November/017099.html) when installing into a prefix that will not become part of the final installation location of the files, like when building a .rpm or binary distribution. When using a `setup.py`-based setuptools, `--root` has the side effect of activating `--single-version-externally-managed`. It is not safe to use `--root` with an empty `--prefix` because the `root` is removed from paths when byte-compiling modules.
|
||||
|
||||
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.
|
||||
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.
|
||||
[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.
|
||||
|
||||
@ -35,17 +35,23 @@ _The top-level element of the JSON output is always an array, so the `map` opera
|
||||
|
||||
### Pretty-print a single formula's info
|
||||
|
||||
`brew info --json=v1 tig | jq .`
|
||||
```sh
|
||||
brew info --json=v1 tig | jq .
|
||||
```
|
||||
|
||||
### Installed formulae
|
||||
|
||||
To show full JSON information about all installed formulae:
|
||||
|
||||
`brew info --json=v1 --all | jq "map(select(.installed != []))"`
|
||||
```sh
|
||||
brew info --json=v1 --all | jq "map(select(.installed != []))"
|
||||
```
|
||||
|
||||
You'll note that processing all formulae can be slow; it's quicker to let `brew` do this:
|
||||
|
||||
`brew info --json=v1 --installed`
|
||||
```sh
|
||||
brew info --json=v1 --installed
|
||||
```
|
||||
|
||||
### Linked keg-only formulae
|
||||
|
||||
@ -53,13 +59,17 @@ Some formulae are marked as "keg-only", meaning that installed files are not lin
|
||||
|
||||
To find the names of linked keg-only formulae:
|
||||
|
||||
`brew info --json=v1 --installed | jq "map(select(.keg_only == true and .linked_keg != null) | .name)"`
|
||||
```sh
|
||||
brew info --json=v1 --installed | jq "map(select(.keg_only == true and .linked_keg != null) | .name)"
|
||||
```
|
||||
|
||||
### Unlinked normal formulae
|
||||
|
||||
To find the names of normal (not keg-only) formulae that are installed, but not linked to the shared directories:
|
||||
|
||||
`brew info --json=v1 --installed | jq "map(select(.keg_only == false and .linked_keg == null) | .name)"`
|
||||
```sh
|
||||
brew info --json=v1 --installed | jq "map(select(.keg_only == false and .linked_keg == null) | .name)"
|
||||
```
|
||||
|
||||
## Concluding remarks
|
||||
|
||||
|
||||
@ -7,7 +7,6 @@ you need to:
|
||||
|
||||
2. Create a pull request to the corresponding tap deleting the old formula file, adding the new formula file, and adding it to `formula_renames.json` with a commit message like `newack: renamed from ack`. Use the canonical name (e.g. `ack` instead of `user/repo/ack`).
|
||||
|
||||
|
||||
A `formula_renames.json` example for a formula rename:
|
||||
|
||||
```json
|
||||
|
||||
@ -13,24 +13,27 @@ and install through the direct link. For example, Python 3.3.0 from pull request
|
||||
brew install https://raw.github.com/dsr/homebrew/9b22d42f50fcbc5e52c764448b3ac002bc153bd7/Library/Formula/python3.rb
|
||||
```
|
||||
|
||||
## Quickly remove something from /usr/local
|
||||
## Quickly remove something from `/usr/local`
|
||||
|
||||
```sh
|
||||
brew unlink $FORMULA
|
||||
brew unlink <formula>
|
||||
```
|
||||
|
||||
This can be useful if a package can't build against the version of something you have linked into `/usr/local`.
|
||||
|
||||
And of course, you can simply `brew link $FORMULA` again afterwards!
|
||||
And of course, you can simply `brew link <formula>` again afterwards!
|
||||
|
||||
## Activate a previously installed version of a formula
|
||||
|
||||
```sh
|
||||
brew info $FORMULA
|
||||
brew switch $FORMULA $VERSION
|
||||
brew info <formula>
|
||||
brew switch <formula> <version>
|
||||
```
|
||||
|
||||
Use `brew info $FORMULA` to check what versions are installed but not currently activated, then `brew switch $FORMULA $VERSION` to activate the desired version. This can be useful if you would like to switch between versions of a formula.
|
||||
Use `brew info <formula>` to check what versions are installed but not currently activated, then `brew switch <formula> <version>` to activate the desired version. This can be useful if you would like to switch between versions of a formula.
|
||||
|
||||
## Install into Homebrew without formulae
|
||||
|
||||
```sh
|
||||
./configure --prefix=/usr/local/Cellar/foo/1.2 && make && make install && brew link foo
|
||||
```
|
||||
@ -42,47 +45,50 @@ Erlang provides a torrent that'll let you download at 4–5× the normal
|
||||
HTTP method.
|
||||
|
||||
Download the file and drop it in `~/Library/Caches/Homebrew`, but
|
||||
watch the file name. Homebrew downloads files as <code>${FORMULA_NAME}-${VERSION}</code>. In the case of Erlang, this requires
|
||||
renaming the file from <code>otp_src_R13B03</code> to
|
||||
<code>erlang-R13B03</code>.
|
||||
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`.
|
||||
|
||||
`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)`.
|
||||
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 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`).
|
||||
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`).
|
||||
|
||||
Luckily, for the majority of cases setting `http_proxy` is enough.
|
||||
You can set this environment variable in several ways (search on the
|
||||
internet for details), including at runtime:
|
||||
|
||||
```
|
||||
http_proxy=http://<proxyhost>:<proxyport> brew install $FORMULA
|
||||
```sh
|
||||
http_proxy=http://<proxyhost>:<proxyport> brew install <formula>
|
||||
```
|
||||
|
||||
To use proxy authentication:
|
||||
|
||||
```sh
|
||||
http_proxy=http://<user>:<password>@<proxyhost>:<proxyport> brew install $FORMULA
|
||||
http_proxy=http://<user>:<password>@<proxyhost>:<proxyport> brew install <formula>
|
||||
```
|
||||
|
||||
## Installing stuff without the Xcode CLT
|
||||
|
||||
```sh
|
||||
$ brew sh # or: eval $(brew --env)
|
||||
$ gem install ronn # or c-programs
|
||||
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)
|
||||
|
||||
```sh
|
||||
brew install --only-dependencies $FORMULA
|
||||
brew install --only-dependencies <formula>
|
||||
```
|
||||
|
||||
## Interactive Homebrew Shell
|
||||
|
||||
```sh
|
||||
$ brew irb
|
||||
1.8.7 :001 > Formula.factory("ace").methods - Object.methods
|
||||
@ -91,6 +97,7 @@ $ brew irb
|
||||
```
|
||||
|
||||
## Hiding the beer mug emoji when finishing a build
|
||||
|
||||
```sh
|
||||
export HOMEBREW_NO_EMOJI=1
|
||||
```
|
||||
|
||||
@ -4,7 +4,6 @@
|
||||
|
||||
This document will help you check for common issues and make sure your issue has not already been reported.
|
||||
|
||||
|
||||
## Check for common issues
|
||||
|
||||
Follow these steps to fix common problems:
|
||||
@ -16,13 +15,11 @@ Follow these steps to fix common problems:
|
||||
* Read through the [Common Issues](Common-Issues.md).
|
||||
* If you’re installing something Java-related, make sure you have installed Java (you can run `brew cask install java`).
|
||||
|
||||
|
||||
## Check to see if the issue has been reported
|
||||
|
||||
* Search the [issue tracker](https://github.com/Homebrew/homebrew-core/issues) to see if someone else has already reported the same issue.
|
||||
* Make sure you search issues on the correct repository. If a formula that has failed to build is part of a tap like [homebrew/science](https://github.com/Homebrew/homebrew-science/issues) or [homebrew/dupes](https://github.com/Homebrew/homebrew-dupes/issues) check those issue trackers instead.
|
||||
|
||||
|
||||
## Create an issue
|
||||
|
||||
If your problem hasn't been solved or reported, then create an issue:
|
||||
@ -31,6 +28,6 @@ If your problem hasn't been solved or reported, then create an issue:
|
||||
- If you had a formula-related problem: run `brew gist-logs <formula>` (where `<formula>` is the name of the formula).
|
||||
- If you encountered a non-formula problem: upload the output of `brew config` and `brew doctor` to a new [Gist](https://gist.github.com).
|
||||
1. [Create a new issue](https://github.com/Homebrew/homebrew-core/issues/new).
|
||||
- Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS you are using. For example, if a formula fails to build, title your issue "\<formula name> failed to build on \<10.x>", where "\<formula name>" is the name of the formula that failed to build, and "\<10.x>" is the version of macOS you are using.
|
||||
- Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<10.x>", where "\<formula>" is the name of the formula that failed to build, and "\<10.x>" is the version of macOS you are using.
|
||||
- Include the URL output by `brew gist-logs <formula>` (if applicable).
|
||||
- Include links to any additional Gists you may have created (such as for the output of `brew config` and `brew doctor`).
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# Versions
|
||||
|
||||
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.
|
||||
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 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`.
|
||||
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
|
||||
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.
|
||||
|
||||
@ -9,7 +9,7 @@ but the command isn't limited to any one location.
|
||||
* `brew tap` without arguments lists the currently tapped repositories. For
|
||||
example:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
$ brew tap
|
||||
homebrew/dupes
|
||||
mistydemeo/tigerbrew
|
||||
@ -55,14 +55,15 @@ edavis/emacs
|
||||
|
||||
## Formula duplicate names
|
||||
|
||||
If your tap contains a formula that is also present in [`homebrew/core`](https://github.com/Homebrew/homebrew-core), that's fine,
|
||||
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.
|
||||
|
||||
If you would like to prioritize a tap over `homebrew/core`, you can use
|
||||
`brew tap-pin username/repo` to pin the tap,
|
||||
and use `brew tap-unpin username/repo` to revert the pin.
|
||||
|
||||
Whenever a `brew install foo` command is issued, brew will find which formula
|
||||
Whenever a `brew install foo` command is issued, `brew` will find which formula
|
||||
to use by searching in the following order:
|
||||
|
||||
* pinned taps
|
||||
@ -75,7 +76,7 @@ qualified names to refer to them.
|
||||
For example, you can create a tap for an alternative `vim` formula. Without
|
||||
pinning it, the behaviour will be
|
||||
|
||||
```bash
|
||||
```sh
|
||||
brew install vim # installs from homebrew/core
|
||||
brew install username/repo/vim # installs from your custom repo
|
||||
```
|
||||
@ -83,7 +84,7 @@ brew install username/repo/vim # installs from your custom repo
|
||||
However if you pin the tap with `brew tap-pin username/repo`, you will need to
|
||||
use `homebrew/core` to refer to the core formula.
|
||||
|
||||
```bash
|
||||
```sh
|
||||
brew install vim # installs from your custom repo
|
||||
brew install homebrew/core/vim # installs from homebrew/core
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user