From d0b6a9d0c804b9c0e47057b4e26e7a07cf5be2e1 Mon Sep 17 00:00:00 2001 From: Matt Renaud Date: Sat, 21 Mar 2020 17:22:16 -0700 Subject: [PATCH] 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] --- Cabal/doc/installing-packages.rst | 171 ------------------------------ 1 file changed, 171 deletions(-) diff --git a/Cabal/doc/installing-packages.rst b/Cabal/doc/installing-packages.rst index 22c4cc4135f..7e79753176d 100644 --- a/Cabal/doc/installing-packages.rst +++ b/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 `__. - -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 -------------------------