Skip to content

GitLab

Commit d0b6a9d0 authored by Matt Renaud's avatar Matt Renaud
Browse files
Options

Remove references to "sandboxes" from docs. 

Sandboxes are obsolete with the launch of Nix-style/new-/v2 commands, and thus
should not be given high visibility in the docs for the current version. If docs
are needed then the docs for a previous version of cabal can be used.

[ci skip]
parent 5392ac8c
Hide whitespace changes
Inline Side-by-side
Showing with 0 additions and 171 deletions
Cabal/doc/installing-packages.rst
View file @ d0b6a9d0
......@@ -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
-------------------------
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment