[commit: packages/Cabal] ghc-head: Add docs for sandboxes. (87245ea)

[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=87245ea63ff329e450e4e46b9e5aed9f29f6994d

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

commit 87245ea63ff329e450e4e46b9e5aed9f29f6994d
Author: Mikhail Glushenkov <mikhail.glushenkov at gmail.com>
Date:   Fri Aug 23 11:56:57 2013 +0200

    Add docs for sandboxes.


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

87245ea63ff329e450e4e46b9e5aed9f29f6994d
 Cabal/doc/index.markdown               |    3 +
 Cabal/doc/installing-packages.markdown |  110 ++++++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+)

diff --git a/Cabal/doc/index.markdown b/Cabal/doc/index.markdown
index d86cd53..ece0ebc 100644
--- a/Cabal/doc/index.markdown
+++ b/Cabal/doc/index.markdown
@@ -35,6 +35,9 @@ builders and users to work with Cabal packages.
       - [Building and installing a system package](installing-packages.html#building-and-installing-a-system-package)
       - [Building and installing a user package](installing-packages.html#building-and-installing-a-user-package)
       - [Installing packages from Hackage](installing-packages.html#installing-packages-from-hackage)
+      - [Developing with sandboxes](installing-packages.html#developing-with-sandboxes)
+          + [Sandboxes: basic usage](installing-packages.html#sandboxes-basic-usage)
+          + [Sandboxes: advanced usage](installing-packages.html#sandboxes-advanced-usage)
       - [Creating a binary package](installing-packages.html#creating-a-binary-package)
       - [setup configure](installing-packages.html#setup-configure)
           + [Programs used for building](installing-packages.html#programs-used-for-building)
diff --git a/Cabal/doc/installing-packages.markdown b/Cabal/doc/installing-packages.markdown
index a5de920..2f1defb 100644
--- a/Cabal/doc/installing-packages.markdown
+++ b/Cabal/doc/installing-packages.markdown
@@ -56,6 +56,116 @@ cabal install [PACKAGE...]
 
 To browse the list of available packages, visit the [Hackage] web site.
 
+## Developing with sandboxes ##
+
+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. One way to avoid this problem is to build each
+package in an isolated environment ("sandbox"), with a sandbox-local package
+database. Because sandboxes are per-project, inconsistent dependencies can be
+simply disallowed.
+
+For more on sandboxes, see also
+[this article](http://coldwa.st/e/blog/2013-08-20-Cabal-sandbox.html).
+
+### Sandboxes: basic usage ###
+
+To initialise a fresh sandbox in the current directory, run `cabal sandbox
+init`. All subsequent commands (such as `build` and `install`) from this point
+will use the sandbox.
+
+~~~~~~~~~~~~~~~
+$ cd /path/to/my/haskell/library
+$ cabal sandbox init                   # Initialise the sandbox
+$ cabal install --only-dependencies    # Install dependencies into the sandbox
+$ cabal build                          # Build your package inside the sandbox
+~~~~~~~~~~~~~~~
+
+It can be useful to make a source package available for installation in the
+sandbox - for example, if your package depends on a patched or an unreleased
+version of a library. This can be done with the `cabal sandbox add-source`
+command - think of it as "local [Hackage]". If an add-source dependency is later
+modified, it is reinstalled automatically.
+
+~~~~~~~~~~~~~~~
+$ cabal sandbox add-source /my/patched/library # Add a new add-source dependency
+$ cabal install --dependencies-only            # Install it into the sandbox
+$ cabal build                                  # Build the local package
+$ $EDITOR /my/patched/library/Source.hs        # Modify the add-source dependency
+$ cabal build                                  # Modified dependency is automatically reinstalled
+~~~~~~~~~~~~~~~
+
+Normally, the sandbox settings (such as optimisation level) are inherited from
+the main Cabal config file (`$HOME/cabal/config`). Sometimes, though, you need
+to change some settings specifically for a single sandbox. You can do this by
+creating a `cabal.config` file in the same directory with your
+`cabal.sandbox.config` (which was created by `sandbox init`). This file has the
+same syntax as the main Cabal config file.
+
+~~~~~~~~~~~~~~~
+$ cat cabal.config
+documentation: True
+constraints: foo == 1.0, bar >= 2.0, baz
+$ cabal build                                  # Uses settings from the cabal.config file
+~~~~~~~~~~~~~~~
+
+When you have decided that you no longer want to build your package inside a
+sandbox, just delete it:
+
+~~~~~~~~~~~~~~~
+$ cabal sandbox delete                       # Built-in command
+$ rm -rf .cabal-sandbox cabal.sandbox.config # Alternative manual method
+~~~~~~~~~~~~~~~
+
+### Sandboxes: advanced usage ###
+
+The default behaviour of the `add-source` command is to track modifications done
+to the added dependency and reinstall the sandbox copy of the package when
+needed. Sometimes this is not desirable: in these cases you can use `add-source
+--snapshot`, which disables the change tracking. In addition to `add-source`,
+there are also `list-sources` and `delete-source` commands.
+
+Sometimes one wants to share a single sandbox between multiple packages. This
+can be easily done with the `--sandbox` option:
+
+~~~~~~~~~~~~~~~
+$ cd /path/to/shared-sandbox
+$ cabal sandbox init
+$ cd /path/to/package-a
+$ cabal sandbox init --sandbox /path/to/shared-sandbox
+$ cd /path/to/package-b
+$ cabal sandbox init --sandbox /path/to/shared-sandbox
+~~~~~~~~~~~~~~~
+
+Using multiple different compiler versions simultaneously is also supported, via
+the `-w` option:
+
+~~~~~~~~~~~~~~~
+$ cabal sandbox init
+$ cabal install --only-dependencies -w /path/to/ghc-1 # Install dependencies for both compilers
+$ cabal install --only-dependencies -w /path/to/ghc-2
+$ cabal configure -w /path/to/ghc-1                   # Build with the first compiler
+$ cabal build
+$ cabal configure -w /path/to/ghc-2                   # Build with the second compiler
+$ cabal build
+~~~~~~~~~~~~~~~
+
+It can be occasionally useful to run the compiler-specific package manager tool
+(e.g. `ghc-pkg`) tool on the sandbox package DB directly (for example, you may
+need to unregister some packages). The `cabal sandbox hc-pkg` command is a
+convenient wrapper that runs the compiler-specific package manager tool with the
+arguments:
+
+~~~~~~~~~~~~~~~
+$ cabal -v sandbox hc-pkg list
+Using a sandbox located at /path/to/.cabal-sandbox
+'ghc-pkg' '--global' '--no-user-package-conf'
+    '--package-conf=/path/to/.cabal-sandbox/i386-linux-ghc-7.4.2-packages.conf.d'
+    'list'
+[...]
+~~~~~~~~~~~~~~~
+
 ## Creating a binary package ##
 
 When creating binary packages (e.g. for RedHat or Debian) one needs to