doc: FAQ entries for #1161 and #563

doc/faq.md

@@ -281,3 +281,27 @@ collect2: error: ld returned 1 exit status
 #### Where does the output from `--ghc-options=-ddump-splices` (and other `-ddump*` options) go?
 
 These are written to `*.dump-*` files inside the package's `.stack-work` directory.
+
+#### Why is DYLD_LIBRARY_PATH ignored?
+
+<a name="disable-rootless"></a><a name="dyld-library-path-ignored"></a>If you
+are on Mac OS X 10.11 ("El Capitan") or later, System Integrity Protection
+(a.k.a. "rootless")
+[prevents the `DYLD_LIBRARY_PATH` environment variable from being passed to sub-processes](https://github.com/commercialhaskell/stack/issues/1161).
+The only workaround we are aware of is
+[disabling System Integrity Protection](http://osxdaily.com/2015/10/05/disable-rootless-system-integrity-protection-mac-os-x/):
+
+ 1. Reboot into recovery mode (hold down Cmd-R at boot)
+ 2. Open a terminal (select __Terminal__ from the __Utilities__ menu)
+ 3. Run `csrutil disable; reboot`
+
+Note that this reduces the security of your system.
+
+#### Why do I get a `/usr/bin/ar: permission denied` error?
+
+<a name="usr-bin-ar-permission-denied"></a>On OS X 10.11 ("El Capitan") and
+later, this is
+[caused by System Integrity Protection (a.k.a. "rootless")](https://github.com/commercialhaskell/stack/issues/563).
+GHC 7.10.2 includes a fix, so this only effects users of GHC 7.8.4. If you
+cannot upgrade to GHC 7.10.2, you can work around it by
+[disabling System Integrity Protection](#rootless)

doc/install_and_upgrade.md

@@ -54,6 +54,14 @@ such.
 
 ## Mac OS X
 
+Note: if you are on OS X 10.11 ("El Capitan") or later, System Integrity
+Protection (a.k.a. "rootless") can cause two problems:
+
+  * [GHC 7.8.4 fails with `/usr/bin/ar: permission denied`](faq.html#usr-bin-ar-permission-denied)
+  * [DYLD_LIBRARY_PATH is ignored](faq.html#dyld-library-path-ignored)
+
+See the above links for workarounds.
+
 ### Using Homebrew
 
 If you have a popular [brew](http://brew.sh/) tool installed, you can just do: