Merge pull request #6613 from m-renaud/mrenaud-docs-remove-sandbox

Remove references to "sandboxes" from docs.

Author: m-renaud

Cabal/doc/installing-packages.rst

@@ -64,12 +64,6 @@ Various environment variables affect ``cabal-install``.
     Note, the nix-style builds build directory (``dist-newstyle``)
     is not affected by this environment variable.
 
-``CABAL_SANDBOX_PACKAGE_PATH``
-   Variable related to deprecated sandbox functionality.
-
-``CABAL_SANDBOX_CONFIG``
-   Variable related to deprecated sandbox functionality.
-
 Configuration file discovery
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -309,171 +303,6 @@ dependencies in a single step. To do this, run:
 To browse the list of available packages, visit the
 Hackage_ web site.
 
-Developing with sandboxes
--------------------------
-
-.. warning::
-
-   This functionality is deprecated.
-   Please migrate to use nix-style builds.
-
-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:
-
-::
-
-    $ mkdir -p /path/to/shared-sandbox
-    $ cd /path/to/shared-sandbox
-    $ cabal sandbox init --sandbox .
-    $ 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
-
-Note that ``cabal sandbox init --sandbox .`` puts all sandbox files into
-the current directory. By default, ``cabal sandbox init`` initialises a
-new sandbox in a newly-created subdirectory of the current working
-directory (``./.cabal-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``) 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'
-    [...]
-
-The ``--require-sandbox`` option makes all sandbox-aware commands
-(``install``/``build``/etc.) exit with error if there is no sandbox
-present. This makes it harder to accidentally modify the user package
-database. The option can be also turned on via the per-user
-configuration file (``~/.cabal/config``) or the per-project one
-(``$PROJECT_DIR/cabal.config``). The error can be squelched with
-``--no-require-sandbox``.
-
-The option ``--sandbox-config-file`` allows to specify the location of
-the ``cabal.sandbox.config`` file (by default, ``cabal`` searches for it
-in the current directory). This provides the same functionality as
-shared sandboxes, but sometimes can be more convenient. Example:
-
-::
-
-    $ mkdir my/sandbox
-    $ cd my/sandbox
-    $ cabal sandbox init
-    $ cd /path/to/my/project
-    $ cabal --sandbox-config-file=/path/to/my/sandbox/cabal.sandbox.config install
-    # Uses the sandbox located at /path/to/my/sandbox/.cabal-sandbox
-    $ cd ~
-    $ cabal --sandbox-config-file=/path/to/my/sandbox/cabal.sandbox.config install
-    # Still uses the same sandbox
-
-The sandbox config file can be also specified via the
-``CABAL_SANDBOX_CONFIG`` environment variable.
-
-Finally, the flag ``--ignore-sandbox`` lets you temporarily ignore an
-existing sandbox:
-
-::
-
-    $ mkdir my/sandbox
-    $ cd my/sandbox
-    $ cabal sandbox init
-    $ cabal --ignore-sandbox install text
-    # Installs 'text' in the user package database ('~/.cabal').
 
 Creating a binary package
 -------------------------