Add docs on persisting settings across upgrades

There are some formulas in which Homebrew symlinks configuration files
into /usr/local/etc/ instead of copying them, resulting in custom
settings being overwritten on package upgrades. This addition to the
documentation illustrates one way to avoid this behavior by ensuring the
configure script is told where to copy the configuration file(s).

Refs https://github.com/Homebrew/homebrew-core/issues/8711

1 files changed, 2 insertions, 0 deletions

diff --git a/docs/Formula-Cookbook.md b/docs/Formula-Cookbook.md
index df86be92f..a77772939 100644
--- a/docs/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -783,6 +783,8 @@ The symlinks created by `install_symlink` are guaranteed to be relative. `ln_s`
 
 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.
 
+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}`
+
 ### launchd plist files
 
 Homebrew provides two Formula methods for launchd plist files. [`plist_name`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#plist_name-instance_method) will return e.g. `homebrew.mxcl.<formula>` and [`plist_path`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#plist_path-instance_method) will return e.g. `/usr/local/Cellar/foo/0.1/homebrew.mxcl.foo.plist`.