From 773451f027b2564f8444c4180073593b5e033a28 Mon Sep 17 00:00:00 2001 From: Dominyk Tiller Date: Wed, 23 Mar 2016 21:29:53 +0000 Subject: [PATCH] keg_only external builds documentation: cleanup --- ...rew-with-Homebrew-keg-only-dependencies.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/share/doc/homebrew/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md b/share/doc/homebrew/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md index 56e7c96a2e..c22979f226 100644 --- a/share/doc/homebrew/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md +++ b/share/doc/homebrew/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md @@ -1,30 +1,30 @@ -# How to build software outside Homebrew with Homebrew keg-only dependencies. +# How to build software outside Homebrew with Homebrew `keg-only` dependencies -### What does keg-only mean? +## What does `keg-only` mean? -See the [FAQ](FAQ.md) on this one. It’s a common question. +The [FAQ](FAQ.md) briefly explains this. As an example: -*OpenSSL isn’t symlinked into my $PATH and non-Homebrew builds can’t find it!* +*OpenSSL isn’t symlinked into my `$PATH` and non-Homebrew builds can’t find it!* -That’s because Homebrew keeps it locked away in its prefix, accessible only via its opt directory. `keg_only` = Not symlinked into the `$PATH` by default. +This is because Homebrew keeps it locked inside its individual prefix, rather than symlinking to the publicly-available location, usually `/usr/local`. -### How do I get non-Homebrew builds to find those tools? +## Advice on potential workarounds. A number of people in this situation are either forcefully linking `keg_only` tools with `brew link --force` or moving default system utilities out of the `$PATH` and replacing them with manually-created symlinks to the Homebrew-provided tool. -Please, *please* do not remove OS X native tools and forcefully replace them with symlinks back to the Homebrew-provided tool. Homebrew doesn’t enforce `keg_only` onto formulae unless there’s a specific, good reason for doing so, and that reason is usually that forcing that link breaks a whole boat full of builds. +*Please* do not remove OS X 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. -It is also incredibly difficult to debug a build failure if you make changes to the Homebrew-provided tools installed that `brew` is unaware of. `brew link --force` deliberately creates a warning in `brew doctor` to let both you and maintainers know that link exists and could be causing issues. +`brew link --force` creates a warning in `brew doctor` to let both you and maintainers know that link exists and could be causing issues. If you’ve linked something and there’s no problems at all? Feel free to ignore the `brew doctor` error. -If you’ve linked something and there’s no problems at all? Awesome, feel free to ignore the `brew doctor` error. But *please* don’t try to go around it. It’s really hard to help you out if we don’t know the full picture, and we *want* to be able to help you if you get stuck. +## How do I use those tools outside of Homebrew? -### How do I use those tools outside of Homebrew? +Useful, reliable alternatives exist should you wish to use `keg_only` tools outside of Homebrew. + +### Build flags: -Useful, reliable alternatives exist should you desire to use `keg_only` tools outside of Homebrew’s build processes: ----- You can set flags to give configure scripts or Makefiles a nudge in the right direction. An example of flag setting: ```shell @@ -37,7 +37,7 @@ An example using `pip`: CFLAGS=-I$(brew --prefix)/opt/icu4c/include LDFLAGS=-L$(brew --prefix)/opt/icu4c/lib pip install pyicu ``` ----- +### `$PATH` modification: You can temporarily prepend your `$PATH` with the tool’s bin directory, such as: @@ -45,13 +45,13 @@ You can temporarily prepend your `$PATH` with the tool’s bin directory, such a export PATH=$(brew --prefix)/opt/openssl/bin:$PATH ``` -This will immediately move that folder to the front of your `$PATH`, ensuring any build script that searches the `$PATH` will find it. +This will prepend that folder to your `$PATH`, ensuring any build script that searches the `$PATH` will find it first. -Changing your `$PATH` using that command ensures the change only exists for the duration of that shell session. Once you are no longer in that terminal tab/window, the `$PATH` ceases to be prepended. +Changing your `$PATH` using that command ensures the change only exists for the duration of that shell session. Once you are no longer in that session, the `$PATH` reverts to the prior state. ----- +### `pkg-config` detection: -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 that `keg_only` utility’s `.pc` file, if it has one. Not all formulae ship with those files. +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 that `keg_only` utility’s `.pc` file, if it has them. Not all formulae ship with those files. An example of that is: @@ -59,10 +59,10 @@ An example of that is: export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig ``` -If you’re curious about `PKG_CONFIG_PATH` and which paths it searches by default, `man pkg-config` goes into detail on that. +If you’re curious about the `PKG_CONFIG_PATH` variable `man pkg-config` goes into more detail. -You can also get `pkg-config` to detail its currently searched paths with: +You can get `pkg-config` to detail the default search path with: ```shell -pkg-config --variable pc_path pkg-config` +pkg-config --variable pc_path pkg-config ```