admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

Add & remove line breaks

Browse Source
This commit is contained in:
EricFromCanada 2021-11-16 12:34:46 -05:00
parent 45bf8b0118
commit 77efcdf8fb
No known key found for this signature in database
GPG Key ID: 179D9CDDDB814168
8 changed files with 53 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/Adding-Software-to-Homebrew.md
View File

@ -9,6 +9,7 @@ Next, you will want to go through the [Acceptable Formulae](Acceptable-Formulae.
If everything checks out, you're ready to get started on a new formula!
## Writing the formula
1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled.
1. If you're starting from scratch, the [`brew create` command](Manpage.md#create-options-url) can be used to produce a basic version of your formula. This command accepts a number of options and you may be able to save yourself some work by using an appropriate template option like `--python`.

6
docs/Common-Issues.md
View File

@ -3,15 +3,19 @@
This is a list of commonly encountered problems, known issues, and their solutions.
### `brew` complains about absence of "Command Line Tools"
You need to have the Xcode Command Line Utilities installed (and updated): run `xcode-select --install` in the terminal.
### Ruby: `bad interpreter: /usr/bin/ruby^M: no such file or directory`
You cloned with `git`, and your Git configuration is set to use Windows line endings. See this page: <https://help.github.com/articles/dealing-with-line-endings>
### Ruby: `bad interpreter: /usr/bin/ruby`
You don't have a `/usr/bin/ruby` or it is not executable. It's not recommended to let this persist; you'd be surprised how many `.app`s, tools and scripts expect your macOS-provided files and directories to be *unmodified* since macOS was installed.
### `brew update` complains about untracked working tree files
After running `brew update`, you receive a Git error warning about untracked files or local changes that would be overwritten by a checkout or merge, followed by a list of files inside your Homebrew installation.
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:
@ -29,6 +33,7 @@ git clean -fd
```
### `launchctl` refuses to load launchd plist files
When trying to load a plist file into launchctl, you receive an error that resembles
```
@ -51,6 +56,7 @@ These are likely due to one of four issues:
4. You are `su`'ed as a different user.
### `brew upgrade` errors out
When running `brew upgrade`, you see something like this:
```

6
docs/External-Commands.md
View File

@ -9,6 +9,7 @@ brew mycommand --option1 --option3 <formula>
without modifying Homebrew's internals.
## Command types
External commands come in two flavours: Ruby commands and shell scripts.
In both cases, the command file should be executable (`chmod +x`) and live somewhere in `PATH`.
@ -16,11 +17,13 @@ In both cases, the command file should be executable (`chmod +x`) and live somew
External commands can be added to a tap to allow easy distribution. See [below](#external-commands-in-taps) for more details.
### 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. Be wary of using Homebrew internals; they may change at any time without warning.
The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return `0`.
### Other executable scripts
An executable script for a command named `extcmd` should be named `brew-extcmd`. The script itself can use any suitable shebang (`#!`) line, so an external script can be written in Bash, Ruby, or even Python. Unlike the ruby commands this file must not end with a language-specific suffix (`.sh`, or `.py`). This file will be run via `exec` with some Homebrew variables set as environment variables, and passed any additional command-line arguments.
| Variable | Description |
@ -38,16 +41,19 @@ All internal and external Homebrew commands can provide styled `--help` output b
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`.
## Unofficial external commands
These commands have been contributed by Homebrew users but are not included in the main Homebrew organisation, nor are they installed by the installer script. You can install them manually, as outlined above.
Note they are largely untested, and as always, be careful about running untested code on your machine.
### 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`.
## External commands in taps
External commands can be hosted in a [tap](Taps.md) to allow users to easily install and use them. See [How to Create and Maintain a Tap](How-to-Create-and-Maintain-a-Tap.md) for more details about creating and maintaining a tap.
External commands should be added to a `cmd` directory in the tap. An external command `extcmd` implemented as a Ruby command should live in `cmd/extcmd.rb` (don't forget to `chmod +x`).

50
docs/FAQ.md
View File

@ -1,9 +1,11 @@
# FAQ
## Is there a glossary of terms around?
All your terminology needs can be [found here](Formula-Cookbook.md#homebrew-terminology).
## How do I update my local packages?
First update the formulae and Homebrew itself:
brew update
@ -21,6 +23,7 @@ Or upgrade a specific formula with:
brew upgrade <formula>
## How do I stop certain formulae from being updated?
To stop something from being updated/upgraded:
brew pin <formula>
@ -32,9 +35,11 @@ To allow that formulae to update again:
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 outdated versions. If this is not desired, you can instead `brew extract` to [maintain your own copy of the formula in a tap](How-to-Create-and-Maintain-a-Tap.md).
## How do I uninstall Homebrew?
To uninstall Homebrew, run the [uninstall script from the Homebrew/install repository](https://github.com/homebrew/install#uninstall-homebrew).
## How can I keep old versions of a formula when upgrading?
Homebrew automatically uninstalls old versions of a formula after that formula is upgraded with `brew upgrade`, and periodically performs additional cleanup every 30 days.
To __disable__ automatic `brew cleanup`:
@ -50,6 +55,7 @@ When automatic `brew cleanup` is disabled, if you uninstall a formula, it will o
In this case, to remove a formula entirely, you may run `brew uninstall --force <formula>`. Be careful as this is a destructive operation.
## Why does `brew upgrade <formula>` or `brew install <formula>` also upgrade a bunch of other stuff?
Homebrew doesn't support arbitrary mixing and matching of formula versions, so everything a formula depends on, and everything that depends on it in turn, needs to be upgraded to the latest version as that's the only combination of formulae we test. As a consequence any given `upgrade` or `install` command can upgrade many other (seemingly unrelated) formulae, if something important like `python` or `openssl` also needed an upgrade.
## Where does stuff get downloaded?
@ -59,27 +65,25 @@ Homebrew doesn't support arbitrary mixing and matching of formula versions, so e
Which is usually: `~/Library/Caches/Homebrew`
## My Mac `.app`s don’t find Homebrew utilities!
GUI apps on macOS don’t have Homebrew's prefix in their `PATH` by default. If you're on Mountain Lion or later, you can fix this by running `sudo launchctl config user path "$(brew --prefix)/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 [this page](https://developer.apple.com/legacy/library/qa/qa1067/_index.html).
## How do I contribute to Homebrew?
Read our [contribution guidelines](https://github.com/Homebrew/brew/blob/HEAD/CONTRIBUTING.md#contributing-to-homebrew).
## Why do you compile everything?
Homebrew provides pre-compiled versions for many formulae. These
pre-compiled versions are referred to as [bottles](Bottles.md) and are available
at <https://github.com/Homebrew/homebrew-core/packages>.
If available, bottled binaries will be used by default except under the
following conditions:
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 the formula, but
`brew install --enable-bar <formula>` 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 --enable-bar <formula>` will trigger a source build.
* The `--build-from-source` option is invoked.
* The machine is not running a supported version of macOS as all
bottled builds are generated only for supported macOS versions.
* Homebrew is installed to a prefix other than the default
(although some bottles support this).
* The machine is not running a supported version of macOS as all bottled builds are generated only for supported macOS versions.
* Homebrew is installed to a prefix other than the default (although some bottles support this).
We aim to bottle everything.
@ -105,65 +109,65 @@ The prefix `/opt/homebrew` was chosen to allow installations in `/opt/homebrew`
The prefix `/home/linuxbrew/.linuxbrew` was chosen so that users without admin access can ask an admin to create a `linuxbrew` role account and still benefit from precompiled binaries. If you do not yourself have admin privileges, consider asking your admin staff to create a `linuxbrew` role account for you with home directory `/home/linuxbrew`.
## Why does Homebrew say sudo is bad?
**tl;dr** Sudo is dangerous, and you installed TextMate.app without sudo
anyway.
Homebrew refuses to work using sudo.
You should only ever sudo a tool you trust. Of course, you can trust Homebrew
😉 But do you trust the multi-megabyte Makefile that Homebrew runs? Developers
often understand C++ far better than they understand make syntax. It’s too high
a risk to sudo such stuff. It could modify (or upload) any files on your
system. And indeed, we’ve seen some build scripts try to modify `/usr` even when
the prefix was specified as something else entirely.
You should only ever sudo a tool you trust. Of course, you can trust Homebrew 😉 But do you trust the multi-megabyte Makefile that Homebrew runs? Developers often understand C++ far better than they understand make syntax. It’s too high a risk to sudo such stuff. It could modify (or upload) any files on your system. And indeed, we’ve seen some build scripts try to modify `/usr` even when the prefix was specified as something else entirely.
We use the macOS sandbox to stop this but this doesn't work when run as the `root` user (which also has read and write access to almost everything on the system).
Did you `chown root /Applications/TextMate.app`? Probably
not. So is it that important to `chown root wget`?
Did you `chown root /Applications/TextMate.app`? Probably not. So is it that important to `chown root wget`?
If you need to run Homebrew in a multi-user environment, consider
creating a separate user account especially for use of Homebrew.
If you need to run Homebrew in a multi-user environment, consider creating a separate user account especially for use of Homebrew.
## Why isn’t a particular command documented?
If it’s not in `man brew`, it’s probably an external command. These are documented [here](External-Commands.md).
## Why haven’t you merged my pull request?
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/core`, just edit the formula as you personally need it and `brew install <formula>`. 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 encounter any issues, run the command with the
`--debug` switch like so: `brew install --debug <formula>`, which drops you
into a debugging shell.
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).
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).
## Why was a formula deleted or disabled?
Use `brew log <formula>` to find out! Likely because it had [unresolved issues](Acceptable-Formulae.md) and/or [our analytics](Analytics.md) identified it was not widely used.
For disabled and deprecated formulae, running `brew info <formula>` will also provide an explanation.
## Homebrew is a poor name, it's too generic, why was it chosen?
Homebrew's creator @mxcl was too concerned with the beer theme and didn't consider that the project may actually prove popular. By the time Max realised that it was popular, it was too late. However, today, the first Google hit for "homebrew" is not beer related 😉
## What does "keg-only" mean?
It means the formula is installed only into the Cellar and is not linked into the default prefix. This means most tools will not find it. You can see why a formula was installed as keg-only, and instructions to include it in your `PATH`, by running `brew info <formula>`.
You can still link in the formula if you need to with `brew link <formula>`, though this can cause unexpected behaviour if you are shadowing macOS software.
## How can I specify different configure arguments for a formula?
`brew edit <formula>` and edit the formula. Currently there is no
other way to do this.
## The app can’t be opened because it is from an unidentified developer
Chances are that certain apps will give you a popup message like this:
<img src="https://i.imgur.com/CnEEATG.png" width="532" alt="Gatekeeper message">
@ -182,8 +186,8 @@ Finally, click the `Open` button if you want macOS to permanently allow the app
Alternatively, you may provide the [`--no-quarantine` flag](https://github.com/Homebrew/homebrew-cask/blob/HEAD/USAGE.md#options) at install time to not add this feature to a specific app.
## Why some apps aren’t included in `upgrade`
After running `brew upgrade`, you may notice some casks you think should be upgrading, aren’t.
As you’re likely aware, a lot of macOS software can upgrade itself:

2
docs/Gems,-Eggs-and-Perl-Modules.md
View File

@ -20,6 +20,7 @@ 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?
Habit maybe?
One reason is executables go in `/usr/local/bin`. Usually this isn’t a
@ -28,6 +29,7 @@ writable location. But if you installed Homebrew as we recommend on macOS Intel,
install the development tools you need without risking the use of sudo.
### Python packages (eggs) without sudo using system’s Python
_This is only recommended if you **don't** use a brewed Python._
On macOS, any [Python version X.Y also searches in

9
docs/Homebrew-and-Python.md
View File

@ -11,6 +11,7 @@ Homebrew provided a `python@2` formula until the end of 2019, at which point it
**Important:** If you choose to use a Python which isn't either of these two (system Python or brewed Python), the Homebrew team cannot support any breakage that may occur.
## Python 3.x
Homebrew provides a formula for Python 3.x (`python@3.x`).
**Important**: Python may be upgraded to a newer version at any time. Consider using a version
@ -28,6 +29,7 @@ $(brew --prefix)/opt/python/libexec/bin
```
## Setuptools, Pip, etc.
The Python formulae install [pip](https://pip.pypa.io/) (as `pip3`) and [Setuptools](https://pypi.python.org/pypi/setuptools).
Setuptools can be updated via pip3, without having to re-brew Python:
@ -43,6 +45,7 @@ python3 -m pip install --upgrade pip
```
## `site-packages` and the `PYTHONPATH`
The `site-packages` is a directory that contains Python modules (especially bindings installed by other formulae). Homebrew creates it here:
```sh
@ -59,19 +62,23 @@ Python 3.y also searches for modules in:
Homebrew's `site-packages` directory is first created if (1) any Homebrew formula with Python bindings are installed, or (2) upon `brew install python`.
### Why here?
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.
**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:** 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 `pip3` or `python3 setup.py install` will be installed to the `$(brew --prefix)/lib/pythonX.Y/site-packages` directory (explained above). Executable Python scripts will be in `$(brew --prefix)/bin`.
The system Python may not know which compiler flags to set in order to build bindings for software installed in Homebrew so you may need to run:
@ -81,6 +88,7 @@ CFLAGS="-I$(brew --prefix)/include" LDFLAGS="-L$(brew --prefix)/lib" pip install
```
## Virtualenv
**WARNING:** When you `brew install` formulae that provide Python bindings, you should **not be in an active virtual environment**.
Activate the virtualenv *after* you've brewed, or brew in a fresh terminal window.
@ -89,4 +97,5 @@ Homebrew will still install Python modules into Homebrew's `site-packages` and *
Virtualenv has a `--system-site-packages` switch to allow "global" (i.e. Homebrew's) `site-packages` to be accessible from within the virtualenv.
## Why is Homebrew's Python being installed as a dependency?
Formulae that declare an unconditional dependency on the `"python"` formula are bottled against Homebrew's Python 3.x and require it to be installed.

1
docs/Shell-Completion.md
View File

@ -32,7 +32,6 @@ If you install the `bash-completion` formula, this will automatically source the
If you are using the `bash` formula as your shell (i.e. `bash` >= v4) you should use the `bash-completion@2` formula instead.
## 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:

2
docs/Xcode.md
View File

@ -1,10 +1,12 @@
# Xcode
## Supported Xcode versions
Homebrew supports and recommends the latest Xcode and/or Command Line
Tools available for your platform (see `OS::Mac::Xcode.latest_version` and `OS::Mac::CLT.latest_version` in [`Library/Homebrew/os/mac/xcode.rb`](https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/os/mac/xcode.rb)).
## Updating for new Xcode releases
When a new Xcode release is made, the following things need to be
updated: