mirror of
https://github.com/Homebrew/brew.git
synced 2025-07-14 16:09:03 +08:00
Various documentation edits
Mostly edits to formatting, grammar, wording for consistency & readability.
This commit is contained in:
EricFromCanada
parent
88837353fb
commit
31dbc4f985
@ -5,7 +5,7 @@ First time contributing to Homebrew? Read our [Code of Conduct](https://github.c
|
||||
|
||||
* Run `brew update` (twice).
|
||||
* Run and read `brew doctor`.
|
||||
* Read [the Troubleshooting Checklist](https://docs.brew.sh/Troubleshooting).
|
||||
* Read the [Troubleshooting checklist](https://docs.brew.sh/Troubleshooting).
|
||||
* Open an issue on the formula's repository or on Homebrew/brew if it's not a formula-specific issue.
|
||||
|
||||
### Propose a feature
|
||||
|
||||
@ -93,7 +93,7 @@ Our bottles (binary packages) are hosted by [Bintray](https://bintray.com/homebr
|
||||
|
||||
[](https://bintray.com/homebrew)
|
||||
|
||||
Secure password storage and syncing provided by [1Password for Teams](https://1password.com/teams/) by [AgileBits](https://agilebits.com).
|
||||
Secure password storage and syncing is provided by [1Password for Teams](https://1password.com/teams/) by [AgileBits](https://agilebits.com).
|
||||
|
||||
[](https://agilebits.com)
|
||||
|
||||
|
||||
@ -15,7 +15,7 @@ We now accept versioned formulae as long as they [meet the requirements](Version
|
||||
Software that can upgrade itself does not integrate well with Homebrew's own
|
||||
upgrade functionality. The self-update functionality should be disabled (if possible without complicating the formula).
|
||||
|
||||
### We don’t like install-scripts that download unversioned things
|
||||
### We don’t like install scripts that download unversioned things
|
||||
We don't like install scripts that are pulling from the `master` branch of Git repositories or unversioned, unchecksummed tarballs. These should use `resource` blocks with specific revisions or checksummed tarballs instead. Note that we now allow tools like `cargo`, `gem` and `pip` to download specifically versioned libraries during installation.
|
||||
|
||||
### We don’t like binary formulae
|
||||
@ -23,7 +23,7 @@ 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, Mono).
|
||||
Binary-only formulae should go to
|
||||
[Homebrew Cask](https://github.com/Homebrew/homebrew-cask).
|
||||
[homebrew/cask](https://github.com/Homebrew/homebrew-cask).
|
||||
|
||||
### Stable versions
|
||||
Formulae in the core repository must have a stable version tagged by
|
||||
@ -57,10 +57,10 @@ running a package manager.
|
||||
|
||||
### Stuff that builds an `.app`
|
||||
Don’t make your formula build an `.app` (native macOS Application); we
|
||||
don’t want those things in Homebrew. Encourage upstream projects to build and support a `.app` that can be distributed by [Homebrew Cask](https://github.com/Homebrew/homebrew-cask) (and used without it, too).
|
||||
don’t want those things in Homebrew. Encourage upstream projects to build and support a `.app` that can be distributed by [homebrew/cask](https://github.com/Homebrew/homebrew-cask) (and used without it, too).
|
||||
|
||||
### Stuff that builds a GUI by default (but doesn't have to)
|
||||
Make it build a command-line tool or a library by default and, if the GUI is useful and would be widely used, add an option to build the GUI. Don't offer an option for multiple GUI backends e.g. X11 is a bad user experience for GUIs on macOS.
|
||||
Make it build a command-line tool or a library by default and, if the GUI is useful and would be widely used, add an option to build the GUI. Don't offer an option for multiple GUI backends, e.g. X11 is a bad user experience for GUIs on macOS.
|
||||
|
||||
### Stuff that doesn't build with the latest, stable Xcode's Clang
|
||||
Clang is the default C/C++ compiler on macOS (and has been for a long time). Software that doesn't build with it hasn't been adequately ported to macOS.
|
||||
|
||||
@ -25,10 +25,10 @@ Homebrew's analytics record some shared information for every 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 --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`.
|
||||
|
||||
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.
|
||||
|
||||
@ -45,7 +45,7 @@ Homebrew's analytics are sent throughout Homebrew's execution to Google Analytic
|
||||
Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). A JSON API is also available.
|
||||
|
||||
## How?
|
||||
The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection.
|
||||
The code is viewable in [`analytics.rb`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [`analytics.sh`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection.
|
||||
|
||||
## 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:
|
||||
|
||||
@ -10,7 +10,7 @@ Bottles will not be used if the user requests it (see above), if the formula req
|
||||
## Creation
|
||||
Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pull --bottle` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew).
|
||||
|
||||
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 optimized for something else, you can pass the `--bottle-arch=` option to build for another architecture - for example, `brew install foo --bottle-arch=penryn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad!
|
||||
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 optimized 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).
|
||||
@ -62,7 +62,7 @@ Sometimes bottles may need be updated without bumping the version of the formula
|
||||
Contains the SHA-256 hash of a bottle for a particular version of macOS.
|
||||
|
||||
## Formula DSL
|
||||
Additionally there is a method available in the formula DSL.
|
||||
An additional 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.
|
||||
|
||||
@ -8,4 +8,4 @@ As Homebrew became primarily a binary package manager, most users were fulfillin
|
||||
|
||||
## Today
|
||||
|
||||
If you wish to build against custom non-Homebrew dependencies that are provided by Homebrew (e.g. a non-Homebrew, non-macOS `ruby`) then you must [create and maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) as these formulae will not be accepted in Homebrew/homebrew-core. Once you have done that you can specify `env :std` in the formula which will allow a e.g. `which ruby` to access your existing `PATH` variable and allow compilation to link against this Ruby.
|
||||
If you wish to build against custom non-Homebrew dependencies that are provided by Homebrew (e.g. a non-Homebrew, non-macOS `ruby`) then you must [create and maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) as these formulae will not be accepted in Homebrew/homebrew-core. Once you have done that you can specify `env :std` in the formula which will allow e.g. `which ruby` to access your existing `PATH` variable and allow compilation to link against this Ruby.
|
||||
|
||||
@ -7,18 +7,22 @@ platforms when building C++11 code.
|
||||
|
||||
The default for 10.8 and earlier was **libstdc++**, supported by Apple GCC
|
||||
compilers, GNU GCC compilers, and `clang`. This was marked deprecated with a
|
||||
warning during compile as of Xcode 8.
|
||||
warning during compilation as of Xcode 8.
|
||||
|
||||
There are subtle incompatibilities between several of the C++ standard libraries,
|
||||
so Homebrew will refuse to install software if a dependency was built with an
|
||||
incompatible C++ library. It's recommended that you install the dependency tree
|
||||
using a compatible compiler.
|
||||
|
||||
**If you've upgraded to 10.9 or later from an earlier version** - because the default C++
|
||||
**If you've upgraded to 10.9 or later from an earlier version:** Because the default C++
|
||||
standard library is now libc++, you may not be able to build software using
|
||||
dependencies that you built on 10.8 or lower. If you're reading this page because
|
||||
dependencies that you built on 10.8 or earlier. If you're reading this page because
|
||||
you were directed here by a build error, you can most likely fix the issue if
|
||||
you reinstall all the dependencies of the package you're trying to build.
|
||||
|
||||
Example install using GCC 4.8: ```brew install DESIRED_FORMULA --cc=gcc-4.8```.
|
||||
Get GCC 4.8 via: ```brew install gcc48```
|
||||
Example install using GCC 4.8:
|
||||
|
||||
```sh
|
||||
brew install gcc48
|
||||
brew install --cc=gcc-4.8 <formula>
|
||||
```
|
||||
|
||||
@ -99,7 +99,7 @@ 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
|
||||
### Python: `easy-install.pth` cannot be linked
|
||||
|
||||
```
|
||||
Warning: Could not link <formula>. Unlinking...
|
||||
|
||||
@ -17,6 +17,6 @@ GCC or cross-compiler suite, please link it in here.
|
||||
- Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
|
||||
C++11 support on earlier versions.
|
||||
- Homebrew provides older GCC formulae, e.g. `gcc@4.9` and `gcc@6`.
|
||||
- Homebrew provides the LLVM clang, which is bundled with the `llvm` formula.
|
||||
- Homebrew provides the LLVM Clang, which is bundled with the `llvm` formula.
|
||||
- [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
|
||||
toolchain including binutils and GCC.
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
Homebrew, like Git, supports *external commands*. This lets you create new commands that can be run like:
|
||||
|
||||
```sh
|
||||
brew mycommand --option1 --option3 formula
|
||||
brew mycommand --option1 --option3 <formula>
|
||||
```
|
||||
|
||||
without modifying Homebrew's internals.
|
||||
@ -27,7 +27,7 @@ A shell script for a command named `extcmd` should be named `brew-extcmd`. This
|
||||
| `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). |
|
||||
| `HOMEBREW_REPOSITORY` | If installed from a Git clone, the repository directory (i.e. where Homebrew’s `.git` directory lives). |
|
||||
|
||||
Note that the script itself can use any suitable shebang (`#!`) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else.
|
||||
|
||||
@ -35,7 +35,7 @@ Note that the script itself can use any suitable shebang (`#!`) line, so an exte
|
||||
|
||||
All internal and external Homebrew commands can provide styled `--help` output by using lines starting with `#:` (a comment then `:` character in both Bash and Ruby) which are then output by `--help`.
|
||||
|
||||
For example, see the [header of `brew services`](https://github.com/Homebrew/homebrew-services/blob/a5115e47b05e8d2a632ba7775599e698b240e5a2/cmd/brew-services.rb#L1-L31) which is output with `brew services --help`.
|
||||
For example, see the [header of `brew-services.rb`](https://github.com/Homebrew/homebrew-services/blob/a58a1fe9145de4e50e1cbfb5b0e8a30087826393/cmd/brew-services.rb#L1-L23) which is output with `brew services --help`.
|
||||
|
||||
## Homebrew organisation external commands
|
||||
|
||||
|
||||
12
docs/FAQ.md
12
docs/FAQ.md
@ -26,7 +26,7 @@ To allow that formulae to update again:
|
||||
|
||||
brew unpin <formula>
|
||||
|
||||
Note that pinned, outdated formulae that are depended on by another formula need to be upgraded when required as we do not allow formulae to be built against non-latest versions.
|
||||
Note that pinned, outdated formulae that another formula depends on need to be upgraded when required as we do not allow formulae to be built against non-latest versions.
|
||||
|
||||
## How do I uninstall old versions of a formula?
|
||||
By default, Homebrew does not uninstall old versions of a formula, so
|
||||
@ -57,7 +57,7 @@ If you do not uninstall all of the versions that Homebrew has installed,
|
||||
Homebrew will continue to attempt to install the newest version it knows
|
||||
about when you run `brew upgrade`. This can be surprising.
|
||||
|
||||
To remove a formula entirely, you may run `brew uninstall formula_name --force`.
|
||||
To remove a formula entirely, you may run `brew uninstall --force <formula>`.
|
||||
|
||||
Be careful as this is a destructive operation.
|
||||
|
||||
@ -72,11 +72,11 @@ GUI apps on macOS don’t have `/usr/local/bin` in their `PATH` by
|
||||
default. If you’re on Mountain Lion or later, you can fix this by
|
||||
running `sudo launchctl config user path "/usr/local/bin:$PATH"` and
|
||||
then rebooting, as documented in `man launchctl`. Note that this sets
|
||||
the launchctl PATH for _all users_. For earlier versions of macOS, see
|
||||
the launchctl PATH for *all users*. For earlier versions of macOS, see
|
||||
[this page](https://developer.apple.com/legacy/library/qa/qa1067/_index.html).
|
||||
|
||||
## How do I contribute to Homebrew?
|
||||
Read [CONTRIBUTING.md](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING.md).
|
||||
Read our [contribution guidelines](https://github.com/Homebrew/brew/blob/master/CONTRIBUTING.md#contributing-to-homebrew).
|
||||
|
||||
## Why do you compile everything?
|
||||
Homebrew provides pre-compiled versions for many formulae. These
|
||||
@ -88,7 +88,7 @@ following conditions:
|
||||
|
||||
* 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.
|
||||
`brew install --enable-bar <formula>` will trigger a source build.
|
||||
* The `--build-from-source` option is invoked.
|
||||
* The environment variable `HOMEBREW_BUILD_FROM_SOURCE` is set
|
||||
(intended for developers only).
|
||||
@ -203,7 +203,7 @@ our analytics identified it was not widely used.
|
||||
@mxcl was too concerned with the beer theme and didn’t consider that the
|
||||
project may actually prove popular. By the time he realised it was, it was too
|
||||
late. However, today, the first Google hit for “homebrew” is not beer
|
||||
related ;-)
|
||||
related ;‑)
|
||||
|
||||
## What does "keg-only" mean?
|
||||
It means the formula is installed only into the Cellar; it is not linked
|
||||
|
||||
@ -12,8 +12,8 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
|
||||
| **Cellar** | All **Kegs** are installed here | `/usr/local/Cellar` |
|
||||
| **Tap** | A Git repository of **Formulae** and/or commands | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core` |
|
||||
| **Bottle** | Pre-built **Keg** used instead of building from source | `qt-4.8.4.mavericks.bottle.tar.gz` |
|
||||
| **Cask** | An [extension of homebrew](https://github.com/Homebrew/homebrew-cask) to install macOS native apps | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown` |
|
||||
| **Brew Bundle**| An [extension of homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` |
|
||||
| **Cask** | An [extension of Homebrew](https://github.com/Homebrew/homebrew-cask) to install macOS native apps | `/Applications/MacDown.app/Contents/SharedSupport/bin/macdown` |
|
||||
| **Brew Bundle**| An [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies | `brew 'myservice', restart_service: true` |
|
||||
|
||||
## An introduction
|
||||
|
||||
@ -34,7 +34,7 @@ Before submitting a new formula make sure your package:
|
||||
* 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#contributing-to-homebrew).
|
||||
|
||||
@ -112,7 +112,7 @@ There are plenty of others; check `/usr/lib` for them.
|
||||
|
||||
We generally try not to duplicate system libraries and complicated tools in core Homebrew but we do duplicate some commonly used tools.
|
||||
|
||||
Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be built using Homebrew’s shipped equivalent and our test bot's post-install `audit` will warn if it detects you haven't done this.
|
||||
Special exceptions are OpenSSL and LibreSSL. Things that use either *should* be built using Homebrew’s shipped equivalent and our Brew Test Bot's post-install `audit` will warn if it detects you haven't done this.
|
||||
|
||||
Homebrew’s OpenSSL is [`keg_only`](https://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method)
|
||||
to avoid conflicting with the system so sometimes formulae need to
|
||||
@ -216,7 +216,7 @@ $ otool -L /usr/local/bin/ldapvi
|
||||
|
||||
### Specifying gems, Python modules, Go projects, etc. as dependencies
|
||||
|
||||
Homebrew doesn’t package already packaged language-specific libraries. These should be installed directly from `gem`/`cpan`/`pip` etc.
|
||||
Homebrew doesn’t package already-packaged language-specific libraries. These should be installed directly from `gem`/`cpan`/`pip` etc.
|
||||
|
||||
If you're installing an application then use [`resource`](https://www.rubydoc.info/github/Homebrew/brew/master/Formula#resource-class_method)s for all language-specific dependencies:
|
||||
|
||||
@ -245,7 +245,7 @@ brew install --verbose --debug foo
|
||||
|
||||
`--debug` will ask you to open an interactive shell if the build fails so you can try to figure out what went wrong.
|
||||
|
||||
Check the top of the e.g. `./configure` output. Some configure scripts do not recognize e.g. `--disable-debug`. If you see a warning about it, remove the option from the formula.
|
||||
Check the top of the e.g. `./configure` output. Some configure scripts do not recognise e.g. `--disable-debug`. If you see a warning about it, remove the option from the formula.
|
||||
|
||||
### Add a test to the formula
|
||||
|
||||
@ -269,13 +269,13 @@ Some software installs to `man` instead of `share/man`, so check the output and
|
||||
|
||||
Name the formula like the project markets the product. So it’s `pkg-config`, not `pkgconfig`; `sdl_mixer`, not `sdl-mixer` or `sdlmixer`.
|
||||
|
||||
The only exception is stuff like “Apache Ant”. Apache sticks “Apache” in front of everything, but we use the formula name `ant`. We only include the prefix in cases like *GNUplot* (because it’s part of the name) and *GNU Go* (because everyone calls it “GNU Go”—nobody just calls it “Go”). The word “Go” is too common and there are too many implementations of it.
|
||||
The only exception is stuff like “Apache Ant”. Apache sticks “Apache” in front of everything, but we use the formula name `ant`. We only include the prefix in cases like `gnuplot` (because it’s part of the name) and `gnu-go` (because everyone calls it “GNU Go”—nobody just calls it “Go”). The word “Go” is too common and there are too many implementations of it.
|
||||
|
||||
If you’re not sure about the name check the homepage, and check the Wikipedia page and [what Debian calls it](https://www.debian.org/distrib/packages).
|
||||
If you’re not sure about the name, check its homepage, Wikipedia page and [what Debian calls it](https://www.debian.org/distrib/packages).
|
||||
|
||||
When Homebrew already has a formula called `foo` we typically do not accept requests to replace that formula with something else also named `foo`. This is to avoid both confusing and surprising users’ expectations.
|
||||
|
||||
When two formulae share an upstream name, e.g. [`AESCrypt`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt.rb) and [`AESCrypt`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt the name to avoid conflict with the current formula.
|
||||
When two formulae share an upstream name, e.g. [AESCrypt](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt.rb) and [AES Crypt](https://github.com/Homebrew/homebrew-core/blob/master/Formula/aescrypt-packetizer.rb) the newer formula must typically adapt its name to avoid conflict with the current formula.
|
||||
|
||||
If you’re *still* not sure, just commit. We’ll apply some arbitrary rule and make a decision 😉.
|
||||
|
||||
@ -306,7 +306,7 @@ brew update # required in more ways than you think (initializes the brew git rep
|
||||
cd $(brew --repo homebrew/core)
|
||||
# Create a new git branch for your formula so your pull request is easy to
|
||||
# modify if any changes come up during review.
|
||||
git checkout -b <some-descriptive-name>
|
||||
git checkout -b <some-descriptive-name> origin/master
|
||||
git add Formula/foo.rb
|
||||
git commit
|
||||
```
|
||||
@ -315,7 +315,7 @@ The established standard for Git commit messages is:
|
||||
|
||||
* the first line is a commit summary of *50 characters or less*
|
||||
* two (2) newlines, then
|
||||
* explain the commit thoroughly
|
||||
* explain the commit thoroughly.
|
||||
|
||||
At Homebrew, we like to put the name of the formula up front like so: `foobar 7.3 (new formula)`.
|
||||
This may seem crazy short, but you’ll find that forcing yourself to summarise the commit encourages you to be atomic and concise. If you can’t summarise it in 50-80 characters, you’re probably trying to commit two commits as one. For a more thorough explanation, please read Tim Pope’s excellent blog post, [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
|
||||
@ -338,8 +338,8 @@ git push https://github.com/myname/homebrew-core/ <what-you-called-your-branch>
|
||||
|
||||
Now, [open a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request) for your changes.
|
||||
|
||||
* One formula per commit; one commit per formula
|
||||
* Keep merge commits out of the pull request
|
||||
* One formula per commit; one commit per formula.
|
||||
* Keep merge commits out of the pull request.
|
||||
|
||||
## Convenience tools
|
||||
|
||||
@ -457,11 +457,11 @@ 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
|
||||
```ruby
|
||||
patch :p0, "..."
|
||||
```
|
||||
|
||||
In embedded patches, the string `HOMEBREW_PREFIX` is replaced with the value of the constant `HOMEBREW_PREFIX` before the patch is applied.
|
||||
In embedded patches, the string "HOMEBREW\_PREFIX" is replaced with the value of the constant `HOMEBREW_PREFIX` before the patch is applied.
|
||||
|
||||
### Creating the diff
|
||||
|
||||
@ -473,7 +473,7 @@ brew edit foo
|
||||
```
|
||||
|
||||
Now just paste into the formula after `__END__`.
|
||||
Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formula/foo.rb` might help you ensure that the patch is not touched (e.g. white space removal, indentation, etc.)
|
||||
Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formula/foo.rb` might help you ensure that the patch is not touched, e.g. white space removal, indentation changes, etc.
|
||||
|
||||
## Advanced formula tricks
|
||||
|
||||
@ -691,7 +691,7 @@ The symlinks created by [`install_symlink`](https://www.rubydoc.info/github/Home
|
||||
|
||||
### Handling files that should persist over formula upgrades
|
||||
|
||||
For example, Ruby 1.9’s gems should be installed to `var/lib/ruby/` so that gems don’t need to be reinstalled when upgrading Ruby. You can usually do this with symlink trickery, or *better* a configure option.
|
||||
For example, Ruby 1.9’s gems should be installed to `var/lib/ruby/` so that gems don’t need to be reinstalled when upgrading Ruby. You can usually do this with symlink trickery, or (ideally) a configure option.
|
||||
|
||||
Another example would be configuration files that should not be overwritten on package upgrades. If after installation you find that to-be-persisted configuration files are not copied but instead *symlinked* into `/usr/local/etc/` from the Cellar, this can often be rectified by passing an appropriate argument to the package’s configure script. That argument will vary depending on a given package’s configure script and/or Makefile, but one example might be: `--sysconfdir=#{etc}`
|
||||
|
||||
@ -708,14 +708,14 @@ Eventually a new version of the software will be released. In this case you shou
|
||||
|
||||
Leave the `bottle do ... end` block as-is; our CI system will update it when we pull your change.
|
||||
|
||||
Check if the formula you are updating is a dependency for any other formulae by running `brew uses UPDATED_FORMULA`. If it is a dependency, run `brew reinstall` for all the dependencies after it is installed and verify they work correctly.
|
||||
Check if the formula you are updating is a dependency for any other formulae by running `brew uses <formula>`. If it is a dependency, run `brew reinstall` for all the dependencies after it is installed and verify they work correctly.
|
||||
|
||||
## Style guide
|
||||
|
||||
Homebrew wants to maintain a consistent Ruby style across all formulae based on [Ruby Style Guide](https://github.com/styleguide/ruby). Other formulae may not have been updated to match this guide yet but all new ones should. Also:
|
||||
|
||||
* The order of methods in a formula should be consistent with other formulae (e.g.: `def install` goes before `def post_install`)
|
||||
* An empty line is required before the `__END__` line
|
||||
* The order of methods in a formula should be consistent with other formulae (e.g.: `def install` goes before `def post_install`).
|
||||
* An empty line is required before the `__END__` line.
|
||||
|
||||
## Troubleshooting for people writing new formulae
|
||||
|
||||
@ -740,8 +740,8 @@ If that fixes it, please open an [issue](https://github.com/Homebrew/homebrew-co
|
||||
Check out what MacPorts and Fink do:
|
||||
|
||||
```sh
|
||||
brew -S --macports foo
|
||||
brew -S --fink foo
|
||||
brew search --macports foo
|
||||
brew search --fink foo
|
||||
```
|
||||
|
||||
## Superenv notes
|
||||
|
||||
@ -3,16 +3,20 @@
|
||||
On a fresh macOS installation there are three empty directories for
|
||||
add-ons available to all users:
|
||||
|
||||
/Library/Ruby
|
||||
/Library/Python
|
||||
/Library/Perl
|
||||
* `/Library/Ruby`
|
||||
* `/Library/Python`
|
||||
* `/Library/Perl`
|
||||
|
||||
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:
|
||||
`chmod +a 'user:YOUR_NAME_HERE allow add_subdirectory,add_file,delete_child,directory_inherit' /Library/Python/3.y/site-packages`,
|
||||
for example, will let you add packages to Python 3.y as yourself. That
|
||||
An option to avoid sudo is to use an access control list. For example:
|
||||
|
||||
```sh
|
||||
chmod +a 'user:<YOUR_NAME_HERE> allow add_subdirectory,add_file,delete_child,directory_inherit' /Library/Python/3.y/site-packages
|
||||
```
|
||||
|
||||
will let you add packages to Python 3.y as yourself, which
|
||||
is probably safer than changing the group ownership of the directory.
|
||||
|
||||
### So why was I using sudo?
|
||||
@ -57,10 +61,12 @@ To teach `easy_install` and `pip` to install there, either use the
|
||||
`--user` switch or create a `~/.pydistutils.cfg` file with the
|
||||
following content:
|
||||
|
||||
```
|
||||
[install]
|
||||
install_lib = ~/Library/Python/$py_version_short/lib/python/site-packages
|
||||
```
|
||||
|
||||
### Using virtualenv - works with brewed and system’s Python
|
||||
### Using virtualenv (works with brewed and system’s Python)
|
||||
|
||||
[Virtualenv](https://virtualenv.pypa.io/) ships `pip` and
|
||||
creates isolated Python environments with separate site-packages,
|
||||
@ -141,7 +147,7 @@ subdirectories will be in your `PATH` and `PERL5LIB` etc.
|
||||
|
||||
If you don’t even want (or can’t) use sudo for bootstrapping
|
||||
`local::lib`, just manually install `local::lib` in
|
||||
`~/perl5` and add the relevant path to `PERL5LIB` before the .bashrc eval incantation.
|
||||
`~/perl5` and add the relevant path to `PERL5LIB` before the `.bashrc` eval incantation.
|
||||
|
||||
Another alternative is to use `perlbrew` to install a separate copy of Perl in your home directory, or wherever you like:
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ This page describes how Python is handled in Homebrew for users. See [Python for
|
||||
|
||||
Homebrew should work with any [CPython](https://stackoverflow.com/questions/2324208/is-there-any-difference-between-cpython-and-python) and defaults to the macOS system Python.
|
||||
|
||||
Homebrew provides formulae to brew 3.x and a more up-to-date Python 2.7.x.
|
||||
Homebrew provides formulae to brew Python 3.x and a more up-to-date Python 2.7.x.
|
||||
|
||||
**Important:** If you choose to install a Python which isn't either of these two (system Python or brewed Python), the Homebrew team cannot support any breakage that may occur.
|
||||
|
||||
@ -12,6 +12,7 @@ Homebrew provides formulae to brew 3.x and a more up-to-date Python 2.7.x.
|
||||
Homebrew provides one formula for Python 3.x (`python`) and another for Python 2.7.x (`python@2`).
|
||||
|
||||
The executables are organized as follows so that Python 2 and Python 3 can both be installed without conflict:
|
||||
|
||||
* `python3` points to Homebrew's Python 3.x (if installed)
|
||||
* `python2` points to Homebrew's Python 2.7.x (if installed)
|
||||
* `python` points to Homebrew's Python 2.7.x (if installed) otherwise the macOS system Python. Check out `brew info python` if you wish to add Homebrew's 3.x `python` to your `PATH`.
|
||||
@ -55,8 +56,8 @@ So, for Python 3.y.z, you'll find it at `/usr/local/lib/python3.y/site-packages`
|
||||
|
||||
Python 3.y also searches for modules in:
|
||||
|
||||
- `/Library/Python/3.y/site-packages`
|
||||
- `~/Library/Python/3.y/lib/python/site-packages`
|
||||
* `/Library/Python/3.y/site-packages`
|
||||
* `~/Library/Python/3.y/lib/python/site-packages`
|
||||
|
||||
Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`.
|
||||
|
||||
@ -69,7 +70,9 @@ Some formulae provide Python bindings. Sometimes a `--with-python` or `--with-py
|
||||
**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 <package>`. To discover, you can use `pip search` or <https://pypi.python.org/pypi>. (**Note:** System Python does not provide `pip`. Follow the [pip documentation](https://pip.readthedocs.io/en/stable/installing/#install-pip) to install it for your system Python if you would like it.)
|
||||
These should be installed via `pip install <package>`. To discover, you can use `pip search` or <https://pypi.python.org/pypi>.
|
||||
|
||||
**Note:** macOS's system Python does not provide `pip`. Follow the [pip documentation](https://pip.readthedocs.io/en/stable/installing/#install-pip) to install it for your system Python if you would like it.
|
||||
|
||||
## 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`.
|
||||
@ -83,7 +86,7 @@ CFLAGS=-I$(brew --prefix)/include LDFLAGS=-L$(brew --prefix)/lib pip install <pa
|
||||
## Virtualenv
|
||||
**WARNING:** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**.
|
||||
|
||||
Activate the virtualenv *after* you've brewed, or brew in a fresh Terminal window.
|
||||
Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window.
|
||||
Homebrew will still install Python modules into Homebrew's `site-packages` and *not* into the virtual environment's site-package.
|
||||
|
||||
Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# How to Create and Maintain a Tap
|
||||
|
||||
Taps are external sources of Homebrew formulae and/or external commands. They
|
||||
[Taps](Taps.md) are external sources of Homebrew formulae and/or external commands. They
|
||||
can be created by anyone to provide their own formulae and/or external commands
|
||||
to any Homebrew user.
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
## What does "keg-only" mean?
|
||||
|
||||
The [FAQ](FAQ.md) briefly explains this.
|
||||
The [FAQ](FAQ.md#what-does-keg-only-mean) briefly explains this.
|
||||
|
||||
As an example:
|
||||
|
||||
@ -38,7 +38,7 @@ CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c
|
||||
|
||||
### `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:
|
||||
|
||||
```sh
|
||||
export PATH=$(brew --prefix)/opt/openssl/bin:$PATH
|
||||
|
||||
@ -4,7 +4,7 @@ The suggested and easiest way to install Homebrew is on the
|
||||
[homepage](https://brew.sh).
|
||||
|
||||
The standard script installs Homebrew to `/usr/local` so that
|
||||
[you don’t need sudo](FAQ.md) when you
|
||||
[you don’t need sudo](FAQ.md#why-does-homebrew-say-sudo-is-bad) when you
|
||||
`brew install`. It is a careful script; it can be run even if you have stuff
|
||||
installed to `/usr/local` already. It tells you exactly what it will do before
|
||||
it does it too. And you have to confirm everything it will do before it starts.
|
||||
@ -24,11 +24,10 @@ it does it too. And you have to confirm everything it will do before it starts.
|
||||
Using the instructions on https://brew.sh or below whenever you call `curl` you must pass `--insecure` as an argument. This is because your system `curl` is too old to speak to GitHub using HTTPS. Don't worry, on the first `brew update` Homebrew will install a newer, more secure `curl` for your machine.
|
||||
|
||||
### Untar anywhere
|
||||
Just extract (or `git clone`) Homebrew wherever you want. Just
|
||||
avoid:
|
||||
Just extract (or `git clone`) Homebrew wherever you want. Just avoid:
|
||||
|
||||
* Directories with names that contain spaces. Homebrew itself can handle spaces, but many build scripts cannot.
|
||||
* `/tmp` subdirectories because Homebrew gets upset
|
||||
* `/tmp` subdirectories because Homebrew gets upset.
|
||||
* `/sw` and `/opt/local` because build scripts get confused when Homebrew is there instead of Fink or MacPorts, respectively.
|
||||
|
||||
However do yourself a favor and install to `/usr/local`. Some things may
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# Interesting Taps & Forks
|
||||
|
||||
A _tap_ is homebrew-speak for a Git repository containing extra formulae.
|
||||
Homebrew has the capability to add (and remove) multiple taps to your local installation with the `brew tap` and `brew untap` commands. Type `man brew` in your Terminal. The main repository [https://github.com/Homebrew/homebrew-core](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 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.
|
||||
|
||||
Your taps are Git repositories located at `$(brew --repository)/Library/Taps`.
|
||||
|
||||
|
||||
@ -12,6 +12,7 @@ This document is current practice. If you wish to change or discuss any of the b
|
||||
## Quick checklist
|
||||
|
||||
This is all that really matters:
|
||||
|
||||
- Ensure the name seems reasonable.
|
||||
- Add aliases.
|
||||
- Ensure it uses `keg_only :provided_by_macos` if it already comes with macOS.
|
||||
@ -118,7 +119,6 @@ Formulae that:
|
||||
- do not have known security vulnerabilities or CVEs for the version we package
|
||||
- are shown to be still installed by users in our analytics with a `BuildError` rate of <25%
|
||||
|
||||
|
||||
should not be removed from Homebrew. The exception to this rule are [versioned formulae](Versions.md) for which there are higher standards of usage and a maximum number of versions for a given formula.
|
||||
|
||||
### Closing issues/PRs
|
||||
|
||||
@ -26,22 +26,22 @@ contribute to Homebrew, but we will ask you to step down as a maintainer.
|
||||
|
||||
A few requests:
|
||||
|
||||
- please make pull requests on any changes to Homebrew/brew code or any
|
||||
- Please make pull requests on any changes to Homebrew/brew code or any
|
||||
non-trivial (e.g. not a test or audit improvement or version bump) changes
|
||||
to formulae code and don't merge them unless you get at least one approval
|
||||
and passing tests.
|
||||
- use `brew pull` for formulae changes that require new bottles or change
|
||||
- Use `brew pull` for formulae changes that require new bottles or change
|
||||
multiple formulae and let it auto-close issues wherever possible (it may
|
||||
take ~5m). When this isn't necessary use GitHub's "Merge pull request"
|
||||
button in "create a merge commit" mode for Homebrew/brew or "squash and
|
||||
merge" for a single formulae change. If in doubt, check with e.g. GitX that
|
||||
you've not accidentally added merge commits
|
||||
- still create your branches on your fork rather than in the main repository.
|
||||
you've not accidentally added merge commits.
|
||||
- Still create your branches on your fork rather than in the main repository.
|
||||
Note GitHub's UI will create edits and reverts on the main repository if you
|
||||
make edits or click revert on the Homebrew/brew repository rather than your
|
||||
make edits or click "Revert" on the Homebrew/brew repository rather than your
|
||||
own fork.
|
||||
- if still in doubt please ask for help and we'll help you out
|
||||
- please read:
|
||||
- If still in doubt please ask for help and we'll help you out.
|
||||
- Please read:
|
||||
- https://docs.brew.sh/Brew-Test-Bot-For-Core-Contributors
|
||||
- https://docs.brew.sh/Maintainer-Guidelines
|
||||
- anything else you haven't read on https://docs.brew.sh
|
||||
@ -54,23 +54,23 @@ Thanks for all your work so far!
|
||||
If they accept, follow a few steps to get them set up:
|
||||
|
||||
- Invite them to the [**@Homebrew/maintainers** team](https://github.com/orgs/Homebrew/teams/maintainers) (or any relevant [subteams](https://github.com/orgs/Homebrew/teams/maintainers/teams)) to give them write access to relevant repositories (but don't make them owners). They will need to enable [GitHub's Two Factor Authentication](https://help.github.com/articles/about-two-factor-authentication/).
|
||||
- Ask them to sign in to [Bintray](https://bintray.com) using their GitHub account and they should auto-sync to [Bintray's Homebrew organisation](https://bintray.com/homebrew/organization/edit/members) as a member so they can publish new bottles
|
||||
- Add them to the [Jenkins' GitHub Authorization Settings admin user names](https://jenkins.brew.sh/configureSecurity/) so they can adjust settings and restart jobs
|
||||
- Add them to the [Jenkins' GitHub Pull Request Builder admin list](https://jenkins.brew.sh/configure) to enable `@BrewTestBot test this please` for them
|
||||
- Invite them to the [`homebrew-maintainers` private maintainers mailing list](https://lists.sfconservancy.org/mailman/admin/homebrew-maintainers/members/add)
|
||||
- Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites) (and ensure they've read the [communication guidelines](Maintainer-Guidelines.md#communication))
|
||||
- Ask them to sign in to [Bintray](https://bintray.com) using their GitHub account and they should auto-sync to [Bintray's Homebrew organisation](https://bintray.com/homebrew/organization/edit/members) as a member so they can publish new bottles.
|
||||
- Add them to the [Jenkins' GitHub Authorization Settings admin user names](https://jenkins.brew.sh/configureSecurity/) so they can adjust settings and restart jobs.
|
||||
- Add them to the [Jenkins' GitHub Pull Request Builder admin list](https://jenkins.brew.sh/configure) to enable `@BrewTestBot test this please` for them.
|
||||
- Invite them to the [`homebrew-maintainers` private maintainers mailing list](https://lists.sfconservancy.org/mailman/admin/homebrew-maintainers/members/add).
|
||||
- Invite them to the [`machomebrew` private maintainers Slack](https://machomebrew.slack.com/admin/invites) (and ensure they've read the [communication guidelines](Maintainer-Guidelines.md#communication)).
|
||||
- Ask them to disable SMS as a 2FA device or fallback on their GitHub account in favour of using one of the other authentication methods.
|
||||
- Ask them to (regularly) review remove any unneeded [GitHub personal access tokens](https://github.com/settings/tokens)
|
||||
- Add them to [Homebrew/brew's README](https://github.com/Homebrew/brew/edit/master/README.md)
|
||||
- Ask them to (regularly) review remove any unneeded [GitHub personal access tokens](https://github.com/settings/tokens).
|
||||
- Add them to [Homebrew/brew's README](https://github.com/Homebrew/brew/edit/master/README.md).
|
||||
|
||||
If they are also interested in doing system administration work:
|
||||
|
||||
- Invite them to the [`homebrew-ops` private operations mailing list](https://lists.sfconservancy.org/mailman/admin/homebrew-ops/members/add)
|
||||
- Invite them to the [`homebrew` private 1Password](https://homebrew.1password.com/people)
|
||||
- Invite them to the [`homebrew-ops` private operations mailing list](https://lists.sfconservancy.org/mailman/admin/homebrew-ops/members/add).
|
||||
- Invite them to the [`homebrew` private 1Password](https://homebrew.1password.com/people).
|
||||
|
||||
If they want to consume raw anonymous aggregate analytics data (rather than use `brew formula-analytics`):
|
||||
|
||||
- Invite them to [Google Analytics](https://analytics.google.com/analytics/web/?authuser=1#management/Settings/a76679469w115400090p120682403/%3Fm.page%3DAccountUsers/)
|
||||
- Invite them to [Google Analytics](https://analytics.google.com/analytics/web/?authuser=1#management/Settings/a76679469w115400090p120682403/%3Fm.page%3DAccountUsers/).
|
||||
|
||||
Once they have been active maintainers for at least a year and had some activity on more than one Homebrew organisation repository (or one repository and helped with system administration work):
|
||||
|
||||
|
||||
@ -18,7 +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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
@ -46,11 +48,12 @@ Also note that such a formula would only be compatible with the same Node major
|
||||
|
||||
Node modules should be installed to `libexec`. This prevents the Node modules from contaminating the global `node_modules`, which is important so that npm doesn't try to manage Homebrew-installed Node modules.
|
||||
|
||||
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/0f3b27d252b8112c744e0460d871cfe1def6b993/Formula/azure-cli.rb) or [`webpack`](https://github.com/Homebrew/homebrew-core/blob/6282879973d569962e63da7c81ac4623e1a8336b/Formula/webpack.rb)) and
|
||||
* formulae where the `npm install` call is not the only required install step (e.g. need to compile non-JavaScript sources too) 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/4bb491b7b246830aed57b97348a17e9401374978/Formula/elixirscript.rb)
|
||||
In the following we distinguish between two types of Node modules installed using formulae:
|
||||
|
||||
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.
|
||||
* 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/0f3b27d252b8112c744e0460d871cfe1def6b993/Formula/azure-cli.rb) or [`webpack`](https://github.com/Homebrew/homebrew-core/blob/6282879973d569962e63da7c81ac4623e1a8336b/Formula/webpack.rb))
|
||||
* formulae where the `npm install` call is not the only required install step (e.g. need to also compile non-JavaScript sources) 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/4bb491b7b246830aed57b97348a17e9401374978/Formula/elixirscript.rb) or [`grunt-cli`](https://github.com/Homebrew/homebrew-core/blob/93be1840908adb2f9ee8c48c66586ee6327480e3/Formula/grunt-cli.rb))
|
||||
|
||||
What both methods have in common is 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:
|
||||
|
||||
@ -112,8 +115,6 @@ class Foo < Formula
|
||||
end
|
||||
```
|
||||
|
||||
For examples using the `local_npm_install_args` method look at the [`elixirscript`](https://github.com/Homebrew/homebrew-core/blob/ec1e40d37e81af63122a354f0101c377f6a4e66d/Formula/elixirscript.rb) or [`kibana`](https://github.com/Homebrew/homebrew-core/blob/c6202f91a129e2f994d904f299a308cc6fbd58e5/Formula/kibana.rb) formulae.
|
||||
|
||||
## Tooling
|
||||
|
||||
You can use [homebrew-npm-noob](https://github.com/zmwangx/homebrew-npm-noob) to automatically generate a formula like the example above for an npm package.
|
||||
|
||||
@ -4,7 +4,7 @@ This document explains how to successfully use Python in a Homebrew formula.
|
||||
|
||||
Homebrew draws a distinction between Python **applications** and Python **libraries**. The difference is that users generally do not care that applications are written in Python; it is unusual that a user would expect to be able to `import foo` after installing an application. Examples of applications are [`ansible`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/ansible.rb) and [`jrnl`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/jrnl.rb).
|
||||
|
||||
Python libraries exist to be imported by other Python modules; they are often dependencies of Python applications. They are usually no more than incidentally useful from a Terminal.app command line. Examples of libraries are [`py2cairo`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/py2cairo.rb) and the bindings that are installed by [`protobuf --with-python`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/protobuf.rb).
|
||||
Python libraries exist to be imported by other Python modules; they are often dependencies of Python applications. They are usually no more than incidentally useful in a terminal. Examples of libraries are [`py2cairo`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/py2cairo.rb) and the bindings that are installed by [`protobuf --with-python`](https://github.com/Homebrew/homebrew-core/blob/master/Formula/protobuf.rb).
|
||||
|
||||
Bindings are a special case of libraries that allow Python code to interact with a library or application implemented in another language.
|
||||
|
||||
@ -143,11 +143,11 @@ If the configure script takes a `--with-python` flag, it usually will not need e
|
||||
|
||||
If the `configure` and `make` scripts do not want to install into the Cellar, sometimes you can:
|
||||
|
||||
1. Call `./configure --without-python` (or a similar named option)
|
||||
1. `cd` into the directory containing the Python bindings
|
||||
1. Call `setup.py` with `system` and `Language::Python.setup_install_args` (as described above)
|
||||
1. call `./configure --without-python` (or a similar named option)
|
||||
2. `cd` into the directory containing the Python bindings
|
||||
3. 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 edit a `Makefile` on-the-fly to use our prefix for the Python bindings using Homebrew's [`inreplace`](Formula-Cookbook.md#inreplace) helper method.
|
||||
|
||||
## Libraries
|
||||
|
||||
@ -155,17 +155,17 @@ Sometimes we have to `inreplace` a `Makefile` to use our prefix for the Python b
|
||||
|
||||
Libraries built for Python 3 should include `depends_on "python"`, which will bottle against Homebrew's Python 3.x. Python 2.x libraries must function when they are installed against either the system Python or brewed Python.
|
||||
|
||||
Python 2 libraries do not need a `depends_on "python@2"` declaration; they will be built with the system Python, but should still be usable with any other Python 2.7. If this is not the case, it is an upstream bug; [here is some advice for resolving it](https://blog.tim-smith.us/2015/09/python-extension-modules-os-x/).
|
||||
Python 2 libraries do not need a `depends_on "python@2"` declaration; they will be built with the system Python, but should still be usable with any other Python 2.7. If this is not the case, it's an upstream bug; [here's some advice for resolving it](https://blog.tim-smith.us/2015/09/python-extension-modules-os-x/).
|
||||
|
||||
### 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. 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. To minimise 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.
|
||||
|
||||
## Further down the rabbit hole
|
||||
|
||||
@ -199,7 +199,7 @@ where `prefix` is the destination prefix (usually `libexec` or `prefix`).
|
||||
|
||||
* fetches and installs dependencies
|
||||
* upgrades dependencies in `sys.path` in-place
|
||||
* writes .pth and site.py files which aren't useful for us and cause link conflicts
|
||||
* 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".
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@ From the manpage:
|
||||
|
||||
The current schema version is `v1`. Note that fields may be added to the schema as needed without incrementing the schema. Any significant breaking changes will cause a change to the schema version.
|
||||
|
||||
The schema itself is not currently documented outside of the code that generates it: [Formula#to_hash](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/formula.rb)
|
||||
The schema itself is not currently documented outside of the code in [`formula.rb`](https://github.com/Homebrew/brew/blob/e9b9ea49a16b7879731d01ff2842460d33257a06/Library/Homebrew/formula.rb#L1594-L1680) that generates it.
|
||||
|
||||
## Examples
|
||||
|
||||
@ -71,7 +71,7 @@ brew info --json=v1 --installed | jq "map(select(.keg_only == false and .linked_
|
||||
|
||||
## formulae.brew.sh
|
||||
|
||||
formulae.brew.sh has a [documented JSON API](https://formulae.brew.sh/docs/api/) which provides access to the `brew info --json=v1` output without needing access to Homebrew.
|
||||
[formulae.brew.sh](https://formulae.brew.sh) has a [documented JSON API](https://formulae.brew.sh/docs/api/) which provides access to the `brew info --json=v1` output without needing access to Homebrew.
|
||||
|
||||
## Concluding remarks
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ fi
|
||||
```
|
||||
|
||||
## Configuring Completions in `zsh`
|
||||
To make Homebrew's completions available in `zsh`, you must get the Homebrew-managed zsh site-functions on your `$FPATH` before initialising `zsh`'s completion facility. Add the following to your `~/.zshrc` file:
|
||||
To make Homebrew's completions available in `zsh`, you must get the Homebrew-managed zsh site-functions on your `FPATH` before initialising `zsh`'s completion facility. Add the following to your `~/.zshrc` file:
|
||||
|
||||
```sh
|
||||
if type brew &>/dev/null; then
|
||||
@ -26,7 +26,7 @@ if type brew &>/dev/null; then
|
||||
fi
|
||||
```
|
||||
|
||||
This must be done before `compinit` is called. (Note: if you are using Oh My Zsh, it will call `compinit` for you, so this must be done before you call `oh-my-zsh.sh`.)
|
||||
This must be done before `compinit` is called. Note that if you are using Oh My Zsh, it will call `compinit` for you, so this must be done before you call `oh-my-zsh.sh`.
|
||||
|
||||
You may also need to forcibly rebuild `zcompdump`:
|
||||
|
||||
|
||||
16
docs/Taps.md
16
docs/Taps.md
@ -4,7 +4,7 @@
|
||||
and installs from. By default, `tap` assumes that the repositories come from GitHub,
|
||||
but the command isn't limited to any one location.
|
||||
|
||||
## The command (`brew tap`)
|
||||
## The `brew tap` command
|
||||
|
||||
* `brew tap` without arguments lists the currently tapped repositories. For
|
||||
example:
|
||||
@ -28,8 +28,8 @@ dunn/emacs
|
||||
doesn't have to be HTTP. Any location and any protocol that Git can handle is
|
||||
fine.
|
||||
|
||||
* Add `--full` to either the one- or two-argument invocations above, and Git
|
||||
will make a complete clone rather than a shallow one. Full is the default for
|
||||
* Add `--full` to either the one- or two-argument invocations above to have Git
|
||||
make a complete clone rather than a shallow one. Full is the default for
|
||||
Homebrew developers.
|
||||
|
||||
* `brew tap --repair` migrates tapped formulae from a symlink-based to
|
||||
@ -56,7 +56,7 @@ dunn/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,
|
||||
[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 prioritise a tap over `homebrew/core`, you can use
|
||||
@ -74,21 +74,21 @@ If you need a formula to be installed from a particular tap, you can use fully
|
||||
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
|
||||
pinning it, the behaviour will be:
|
||||
|
||||
```sh
|
||||
brew install vim # installs from homebrew/core
|
||||
brew install username/repo/vim # installs from your custom repo
|
||||
brew install username/repo/vim # installs from your custom repository
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```sh
|
||||
brew install vim # installs from your custom repo
|
||||
brew install vim # installs from your custom repository
|
||||
brew install homebrew/core/vim # installs from homebrew/core
|
||||
```
|
||||
|
||||
Do note that pinned taps are prioritized only when the formula name is directly
|
||||
Note that pinned taps are prioritized only when the formula name is directly
|
||||
given by you, i.e. it will not influence formulae automatically installed as
|
||||
dependencies.
|
||||
|
||||
@ -7,10 +7,10 @@ some formulae is to see if there is a versioned formula (e.g. `gcc@6`) available
|
||||
|
||||
### Installing directly from pull requests
|
||||
You can [browse pull requests](https://github.com/Homebrew/homebrew-core/pulls)
|
||||
and install through the direct link. For example, Python 3.3.0 from pull request [Homebrew/homebrew#15199](https://github.com/Homebrew/homebrew/pull/15199):
|
||||
and install through their direct link. For example, Python 3.7.0 from pull request [Homebrew/homebrew-core#29490](https://github.com/Homebrew/homebrew-core/pull/29490):
|
||||
|
||||
```sh
|
||||
brew install https://raw.github.com/dsr/homebrew/9b22d42f50fcbc5e52c764448b3ac002bc153bd7/Library/Formula/python3.rb
|
||||
brew install https://raw.githubusercontent.com/sashkab/homebrew-core/176823eb82ee1b5ce55a91e5e1bf2f50aa674092/Formula/python.rb
|
||||
```
|
||||
|
||||
## Quickly remove something from `/usr/local`
|
||||
@ -53,7 +53,7 @@ In the case of Erlang, this requires renaming the file from `otp_src_R13B03` to
|
||||
download. This means instead of manually renaming a formula, you can
|
||||
run `mv the_tarball $(brew --cache -s <formula>)`.
|
||||
|
||||
You can also pre-cache the download by using the command `brew fetch formula` which also displays the SHA-256 hash. This can be useful for updating formulae to new versions.
|
||||
You can also pre-cache the download by using the command `brew fetch <formula>` which also displays the SHA-256 hash. This can be useful for updating formulae to new versions.
|
||||
|
||||
## Installing stuff without the Xcode CLT
|
||||
|
||||
@ -85,7 +85,7 @@ $ brew irb
|
||||
export HOMEBREW_NO_EMOJI=1
|
||||
```
|
||||
|
||||
This sets the HOMEBREW_NO_EMOJI environment variable, causing Homebrew
|
||||
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):
|
||||
|
||||
@ -17,16 +17,16 @@ Follow these steps to fix common problems:
|
||||
## 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 non-homebrew-core tap or a cask is part of [Homebrew/cask](https://github.com/Homebrew/homebrew-cask/issues) check those issue trackers instead.
|
||||
* Make sure you search issues on the correct repository. If a formula that has failed to build is part of a non-homebrew-core tap or a cask is part of [homebrew/cask](https://github.com/Homebrew/homebrew-cask/issues) check those issue trackers instead.
|
||||
|
||||
## Create an issue
|
||||
|
||||
If your problem hasn't been solved or reported, then create an issue:
|
||||
|
||||
0. Upload debugging information to a [Gist](https://gist.github.com):
|
||||
1. Upload debugging information to a [Gist](https://gist.github.com):
|
||||
- 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/choose).
|
||||
2. [Create a new issue](https://github.com/Homebrew/homebrew-core/issues/new/choose).
|
||||
- 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`).
|
||||
|
||||
@ -9,17 +9,17 @@ Versioned formulae we include in [homebrew/core](https://github.com/homebrew/hom
|
||||
|
||||
* Versioned software should build on all Homebrew's supported versions of macOS.
|
||||
* Versioned formulae should differ in major/minor (not patch) versions from the current stable release. This is because patch versions indicate bug or security updates and we want to ensure you apply security updates.
|
||||
* Upstream should have a release branch for the versioned formulae version and still make security updates for that version, when necessary. For example, [PHP 5.5 was not a supported version but PHP 7.2 was](https://php.net/supported-versions.php) in January 2018
|
||||
* Upstream should have a release branch for the versioned formulae version and still make security updates for that version, when necessary. For example, [PHP 5.5 was not a supported version but PHP 7.2 was](https://php.net/supported-versions.php) in January 2018.
|
||||
* Formulae that depend on versioned formulae must not depend on the same formulae at two different versions twice in their recursive dependencies. For example, if you depend on `openssl@1.0` and `foo`, and `foo` depends on `openssl` then you must instead use `openssl`.
|
||||
* Versioned formulae should only be linkable at the same time as their non-versioned counterpart if the upstream project provides support for it, e.g. using suffixed binaries. If this is not possible, use `keg_only :versioned_formula` to allow users to have multiple versions installed at once.
|
||||
* A `keg_only :versioned_formula` should not `post_install` anything in the `HOMEBREW_PREFIX` that conflicts with or duplicates the non-versioned counterpart (or other versioned formulae). For example, a `node@6` formula should not install its `npm` into `HOMEBREW_PREFIX` like the `node` formula does.
|
||||
* Versioned formulae submitted should be expected to be used by a large number of people. If this ceases to be the case: they will be removed. We will aim not to remove those in the [top 3,000 `install_on_request` formulae](https://brew.sh/analytics/install-on-request/).
|
||||
* Versioned formulae should not have `resource`s that require security updates. For example, a `node@6` formula should not have an `npm` resource but instead rely on the `npm` provided by the upstream tarball.
|
||||
* Versioned formulae should be as similar as possible and sensible to the unversioned formulae. Creating or updating a versioned formula should be a chance to ask questions of the unversioned formula e.g. can some unused or useless options be removed or made default?
|
||||
* Versioned formulae should be as similar as possible and sensible compared to the non-versioned formulae. Creating or updating a versioned formula should be a chance to ask questions of the non-versioned formula, e.g. can some unused or useless options be removed or made default?
|
||||
* No more than five versions of a formula (including the non-versioned one) will be supported at any given time, regardless of usage. When removing formulae that violate this we will aim to do so based on usage and support status rather than age.
|
||||
|
||||
Homebrew's versions are not intended to be used for any old versions you personally require for your project. You should create your own [tap](How-to-Create-and-Maintain-a-Tap.md) for formulae you or your organisation wish to control the versioning of or those that do not meet the above standards. Software that has regular API or ABI breaking releases still needs to meet all the above requirements; that a `brew upgrade` has broken something for you is not an argument for us to add and maintain a formula for you.
|
||||
|
||||
If there is a formula that currently exists in the Homebrew/homebrew-core repository or has existed in the past (i.e. was migrated or deleted), you can recover it for your own use with the `brew extract` command. This will copy the desired version of the formula into a custom tap. For example, if your project depends on `automake` 1.12 instead of the most recent version, you can obtain the `automake` formula at version 1.12 by running `brew extract automake $YOUR_GITHUB_USER/$YOUR_TAP_REPOSITORY_NAME --version=1.12`. Formulae obtained this way may have use deprecated, disabled or removed Homebrew syntax (e.g. checksums may have `sha1` checksums instead of `sha256`); the `brew extract` command does not edit or update formulae to meet current standards and style requirements.
|
||||
If there is a formula that currently exists in the Homebrew/homebrew-core repository or has existed in the past (i.e. was migrated or deleted), you can recover it for your own use with the `brew extract` command. This will copy the desired version of the formula into a custom tap. For example, if your project depends on `automake` 1.12 instead of the most recent version, you can obtain the `automake` formula at version 1.12 by running `brew extract automake <YOUR_GITHUB_USER>/<YOUR_TAP_REPOSITORY_NAME> --version=1.12`. Formulae obtained this way may contain deprecated, disabled or removed Homebrew syntax (e.g. checksums may be `sha1` instead of `sha256`); the `brew extract` command does not edit or update formulae to meet current standards and style requirements.
|
||||
|
||||
We may temporarily add versioned formulae for our own needs that do not meet these standards in [homebrew/core](https://github.com/homebrew/homebrew-core). The presence of a versioned formula there does not imply it will be maintained indefinitely or that we are willing to accept any more versions that do not meet the requirements above.
|
||||
|
||||
@ -12,9 +12,9 @@ See `OS::Mac::STANDARD_COMPILERS` in [`Library/Homebrew/os/mac.rb`](https://gith
|
||||
When a new Xcode release is made, the following things need to be
|
||||
updated:
|
||||
|
||||
- In [`Library/Homebrew/os/mac/xcode.rb`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/os/mac/xcode.rb)
|
||||
* In [`Library/Homebrew/os/mac/xcode.rb`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/os/mac/xcode.rb)
|
||||
* `OS::Mac::Xcode.latest_version`
|
||||
* `OS::Mac::CLT.latest_version`
|
||||
* `OS::Mac::Xcode.detect_version_from_clang_version`
|
||||
- In [`Library/Homebrew/os/mac.rb`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/os/mac.rb)
|
||||
* In [`Library/Homebrew/os/mac.rb`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/os/mac.rb)
|
||||
* `OS::Mac::STANDARD_COMPILERS`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user