Skip to content

Commit

Permalink
Merge pull request #6613 from m-renaud/mrenaud-docs-remove-sandbox
Browse files Browse the repository at this point in the history 
Remove references to "sandboxes" from docs.
  • Loading branch information
@m-renaud
m-renaud authored Mar 24, 2020
2 parents cf25742 + d0b6a9d commit 7fda66f
Showing 1 changed file with 0 additions and 171 deletions.
171 changes: 0 additions & 171 deletions Cabal/doc/installing-packages.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -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
-------------------------
Expand Down

0 comments on commit 7fda66f

Please sign in to comment.