mirrors/brew
1
0
Fork 0
mirror of https://github.com/Homebrew/brew.git synced 2025-07-14 16:09:03 +08:00
Code Issues Packages Projects Releases Wiki Activity
brew/docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md

72 lines
2.7 KiB
Markdown
Raw Normal View History

Add a `last_reviewed_date` to docs metadata - At the AGM we formed an ad-hoc documentation working group. - One of our ideas was that we should have a last reviewed date for documentation, so that we can periodically implement a review mechanism (GitHub Actions posts to Slack for a regular documentation outdatedness check?) to track how old docs are and ensure they're still relevant. - This is a first step towards that goal, by adding a `last_review_date` to the metadata of all docs with a date of earlier than Homebrew's inception because everything needs reviewing so that we start from a good base!
2025-02-03 10:59:02 +00:00
---
last_review_date: "1970-01-01"
---
docs: Title-case every h1 it made sense to title-case
2019-12-11 22:53:27 +00:00
# How to Build Software Outside Homebrew with Homebrew `keg_only` Dependencies
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page.
2017-03-18 17:45:12 -04:00
## What does "keg-only" mean?
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
Various documentation edits Mostly edits to formatting, grammar, wording for consistency & readability.
2018-10-05 17:23:22 -04:00
The [FAQ](FAQ.md#what-does-keg-only-mean) briefly explains this.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
As an example:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
*OpenSSL isn’t symlinked into my `PATH` and non-Homebrew builds can’t find it!*
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
This is because Homebrew isolates it within its individual prefix, rather than symlinking to the publicly available location.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page.
2017-03-18 17:45:12 -04:00
## Advice on potential workarounds
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
A number of people in this situation are either forcefully linking keg-only tools with `brew link --force` or moving default system utilities out of the `PATH` and replacing them with manually created symlinks to the Homebrew-provided tool.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
Use new "macOS" naming where appropriate. Not quite a mass replacement as I've used OS X and Mac OS X where describing specific older versions and added compatibility methods for things in the DSL.
2016-09-18 19:57:19 +01:00
*Please* do not remove macOS native tools and forcefully replace them with symlinks back to the Homebrew-provided tool. Doing so can and likely will cause significant breakage when attempting to build software.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page.
2017-03-18 17:45:12 -04:00
`brew link --force` creates a warning in `brew doctor` to let both you and maintainers know that a link exists that could be causing issues. If you’ve linked something and there’s no problems at all? Feel free to ignore the `brew doctor` error.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
keg_only external builds documentation: cleanup
2016-03-23 21:29:53 +00:00
## How do I use those tools outside of Homebrew?
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
Useful, reliable alternatives exist should you wish to use keg-only tools outside of Homebrew.
keg_only external builds documentation: cleanup
2016-03-23 21:29:53 +00:00
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page.
2017-03-18 17:45:12 -04:00
### Build flags
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting:
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
docs: fix up more `brew --prefix` usage. The new form used to be slow but both are now fast.
2023-02-21 08:57:12 +00:00
./configure --prefix=/Users/Dave/Downloads CFLAGS="-I$(brew --prefix openssl)/include" LDFLAGS="-L$(brew --prefix openssl)/lib"
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
```
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
An example using `pip`:
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
docs: fix up more `brew --prefix` usage. The new form used to be slow but both are now fast.
2023-02-21 08:57:12 +00:00
CFLAGS="-I$(brew --prefix icu4c)/include" LDFLAGS="-L$(brew --prefix icu4c)/lib" pip install pyicu
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
```
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
### `PATH` modification
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
Various documentation edits Mostly edits to formatting, grammar, wording for consistency & readability.
2018-10-05 17:23:22 -04:00
You can temporarily prepend your `PATH` with the tool’s `bin` directory, such as:
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
docs: fix up more `brew --prefix` usage. The new form used to be slow but both are now fast.
2023-02-21 08:57:12 +00:00
export PATH="$(brew --prefix openssl)/bin:${PATH}"
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
```
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
This will prepend the directory to your `PATH`, ensuring any build script that searches the `PATH` will find it first.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
Changing your `PATH` using this command ensures the change only exists for the duration of the shell session. Once the current session ends, the `PATH` reverts to its prior state.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page.
2017-03-18 17:45:12 -04:00
### `pkg-config` detection
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
If the tool you are attempting to build is [pkg-config](https://en.wikipedia.org/wiki/Pkg-config) aware, you can amend your `PKG_CONFIG_PATH` to find a keg-only utility’s `.pc` files, if it has any. Not all formulae ship with these files.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: grammar edits, sentence-case secondary headings Also changes some heading levels so only one primary heading appears per page.
2017-03-18 17:45:12 -04:00
An example of this is:
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
docs: fix up more `brew --prefix` usage. The new form used to be slow but both are now fast.
2023-02-21 08:57:12 +00:00
export PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig"
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
```
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
If you’re curious about the `PKG_CONFIG_PATH` variable, `man pkg-config` goes into more detail.
Documenting keg-only outside of Homebrew. How-to-use-keg-only-outside-of-brew: * A new piece of documentation detailing how to deal with using keg_only formula outside of Brew itself. We’ve had a lot of questions and issues about this recently, and the solutions aren’t as easy and explicit to find elsewhere, so detailing it here may help reduce some of the questions we’ve seen recently. * I possibly whinged too much in the second section. I’m open to criticism and being called whiny. * Details flags, prepending the $PATH, and dealing with pkg-config. Closes Homebrew/homebrew#34608. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2014-12-02 14:15:38 +00:00
docs: update wording for rest of Users section
2022-01-03 16:57:25 -05:00
You can get `pkg-config` to print the default search path with:
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
docs: code example reformatting Add labeled fences to most code blocks, monospace terms where appropriate, omit "$" when referring to variables
2017-03-25 22:53:33 -04:00
```sh
keg_only external builds documentation: cleanup
2016-03-23 21:29:53 +00:00
pkg-config --variable pc_path pkg-config
Overhaul, simplify and cleanup documentation. Remove duplication, link to the API documentation more often, tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s and `@adamv`'s significant past contributions to Homebrew, delete some outdated or unneeded documentation, add some missing `Formula` API. entries and simplify/improve `CONTRIBUTING.md`. Closes Homebrew/homebrew#46179. Closes Homebrew/homebrew#46618. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
2015-12-06 22:18:16 +00:00
```
Reference in New Issue Copy Permalink