[commit: ghc] master: Document meaning of order of --package-db flags, fixes #12485. (5eab6a0)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/5eab6a0da5f22a47d04b97a0ec8988346675b33b/ghc

>---------------------------------------------------------------

commit 5eab6a0da5f22a47d04b97a0ec8988346675b33b
Author: Edward Z. Yang <ezyang at cs.stanford.edu>
Date:   Mon Sep 5 19:19:57 2016 -0400

    Document meaning of order of --package-db flags, fixes #12485.
    
    Test Plan: none
    
    Reviewers: austin, niteria, bgamari
    
    Reviewed By: niteria
    
    Subscribers: thomie
    
    Differential Revision: https://phabricator.haskell.org/D2514
    
    GHC Trac Issues: #12485


>---------------------------------------------------------------

5eab6a0da5f22a47d04b97a0ec8988346675b33b
 docs/users_guide/packages.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst
index 15c97c7..d3da125 100644
--- a/docs/users_guide/packages.rst
+++ b/docs/users_guide/packages.rst
@@ -384,6 +384,11 @@ stack. Several command line options described below can further manipulate this
 initial stack. You can see GHC's effective package database stack by running
 GHC with the :ghc-flag:`-v` flag.
 
+This stack structure means that the order of :ghc-flag:`-package-db` flags or
+:envvar:`GHC_PACKAGE_PATH` is important.  Each substack of the stack
+must be well formed (packages in databases on top of the stack can refer
+to packages below, but not vice versa).
+
 *Package shadowing:* When multiple package databases are in use it
 is possible, though rarely, that the same installed package id is present in
 more than one database. In that case, packages closer to the top of the stack