[commit: packages/Cabal] ghc-head: Add basic sandbox documentation (6bfb5a2)

[git at git.haskell.org]

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

On branch  : ghc-head
Link       : http://git.haskell.org/?p=packages/Cabal.git;a=commit;h=6bfb5a200c2202baa313903c95ced835316b23aa

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

commit 6bfb5a200c2202baa313903c95ced835316b23aa
Author: Johan Tibell <johan.tibell at gmail.com>
Date:   Tue Aug 6 08:27:51 2013 +0200

    Add basic sandbox documentation


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

6bfb5a200c2202baa313903c95ced835316b23aa
 Cabal/doc/installing-packages.markdown |   39 ++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/Cabal/doc/installing-packages.markdown b/Cabal/doc/installing-packages.markdown
index 909644b..c6d5528 100644
--- a/Cabal/doc/installing-packages.markdown
+++ b/Cabal/doc/installing-packages.markdown
@@ -928,6 +928,45 @@ This command takes the following option:
 :   Append today's date (in "YYYYMMDD" format) to the version number for
     the generated source package.  The original package is unaffected.
 
+## setup sandbox ##
+
+By default, any dependencies of the package are installed into the
+global or user package databases (e.g. using `cabal install
+--only-dependencies`). If you're building several different packages
+that have incompatible dependencies, this can cause the build to fail.
+By installing all dependencies in a package database specific to each
+sandbox, these problems can be avoided.
+
+Typical usage:
+
+~~~~~~~~~~~~~~~~
+runhaskell Setup.hs sandbox init  # only once per directory
+runhaskell Setup.hs configure
+runhaskell Setup.hs build
+~~~~~~~~~~~~~~~~
+
+### setup sandbox init ###
+
+Create a sandbox. This command only needs to be run once per build
+directory (i.e. the directory in which the `.cabal` file resides).
+
+### setup sandbox delete ###
+
+Delete the sandbox and all package's installed into it.
+
+### setup sandbox add-source ###
+
+Make package source directory available to the sandbox. This lets you
+depend on yet unreleased packages while developing your current
+package.
+
+Example usage:
+
+~~~~~~~~~~~~~~~~
+runhaskell Setup.hs sandbox add-source ../otherpkg
+runhaskell Setup.hs configure
+~~~~~~~~~~~~~~~~
+
 
 [dist-simple]:  ../libraries/Cabal/Distribution-Simple.html
 [dist-make]:    ../libraries/Cabal/Distribution-Make.html