installing-packages.rst 7.96 KB
Newer Older
1 2 3
Configuration
=============

4 5
.. highlight:: cabal

6 7 8 9 10 11 12 13
Overview
--------

The global configuration file for ``cabal-install`` is
``~/.cabal/config``. If you do not have this file, ``cabal`` will create
it for you on the first call to ``cabal update``. Alternatively, you can
explicitly ask ``cabal`` to create it for you using

14 15 16
.. code-block:: console

    $ cabal user-config update
17

18 19 20 21
You can change the location of the global configuration file by specifying
either ``--config-file=FILE`` on the command line or by setting the
``CABAL_CONFIG`` environment variable.

22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
Most of the options in this configuration file are also available as
command line arguments, and the corresponding documentation can be used
to lookup their meaning. The created configuration file only specifies
values for a handful of options. Most options are left at their default
value, which it documents; for instance,

::

    -- executable-stripping: True

means that the configuration file currently does not specify a value for
the ``executable-stripping`` option (the line is commented out), and
that the default is ``True``; if you wanted to disable stripping of
executables by default, you would change this line to

::

    executable-stripping: False

You can also use ``cabal user-config update`` to migrate configuration
files created by older versions of ``cabal``.

44 45 46 47 48 49 50 51 52 53 54
Environment variables
---------------------

Various environment variables affect ``cabal-install``.

``CABAL_CONFIG``
   The variable to find global configuration file.

``CABAL_DIR``
   Default content directory for ``cabal-install`` files.
   Default value is ``getAppUserDataDirectory "cabal"``, which is
55
   ``$HOME/.cabal`` on unix systems and ``%APPDATA%\cabal`` in Windows.
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84

   .. note::

       The CABAL_DIR might be dropped in the future, when
       ``cabal-install`` starts to use XDG Directory specification.

``CABAL_BUILDDIR``
    The override for default ``dist`` build directory.
    Note, the nix-style builds build directory (``dist-newstyle``)
    is not affected by this environment variable.

Configuration file discovery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. If ``$CABAL_CONFIG`` is set use it,
2. otherwise if ``$CABAL_DIR`` is set use ``$CABAL_DIR/config``
3. otherwise use ``getAppUserDirectory "cabal"``

If the configuration file doesn't exist ``cabal-install``
will generate the default one, with directories based on
``$CABAL_DIR`` (if set) or ``getAppUserDirectory "cabal"`` prefix.

.. note:

    If ``$CABAL_CONFIG`` is set, but the file doesn't exist,
    one will be generated with ``$CABAL_DIR`` or ``getAppUserDirectory "cabal"``
    based prefixes. In other words not the prefixes based on a
    directory part of ``$CABAL_CONFIG`` path.

85 86 87
Repository specification
------------------------

88
An important part of the configuration is the specification of the
89 90 91 92 93 94 95 96 97 98 99 100
repository. When ``cabal`` creates a default config file, it configures
the repository to be the central Hackage server:

::

    repository hackage.haskell.org
      url: http://hackage.haskell.org/

The name of the repository is given on the first line, and can be
anything; packages downloaded from this repository will be cached under
``~/.cabal/packages/hackage.haskell.org`` (or whatever name you specify;
you can change the prefix by changing the value of
101
:cfg-field:`remote-repo-cache`). If you want, you can configure multiple
102 103 104 105
repositories, and ``cabal`` will combine them and be able to download
packages from any of them.

Using secure repositories
106
^^^^^^^^^^^^^^^^^^^^^^^^^
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133

For repositories that support the TUF security infrastructure (this
includes Hackage), you can enable secure access to the repository by
specifying:

::

    repository hackage.haskell.org
      url: http://hackage.haskell.org/
      secure: True
      root-keys: <root-key-IDs>
      key-threshold: <key-threshold>

The ``<root-key-IDs>`` and ``<key-threshold>`` values are used for
bootstrapping. As part of the TUF infrastructure the repository will
contain a file ``root.json`` (for instance,
http://hackage.haskell.org/root.json) which the client needs to do
verification. However, how can ``cabal`` verify the ``root.json`` file
*itself*? This is known as bootstrapping: if you specify a list of root
key IDs and a corresponding threshold, ``cabal`` will verify that the
downloaded ``root.json`` file has been signed with at least
``<key-threshold>`` keys from your set of ``<root-key-IDs>``.

You can, but are not recommended to, omit these two fields. In that case
``cabal`` will download the ``root.json`` field and use it without
verification. Although this bootstrapping step is then unsafe, all
subsequent access is secure (provided that the downloaded ``root.json``
selinger's avatar
selinger committed
134
was not tampered with). Of course, adding ``root-keys`` and
135 136 137 138 139 140
``key-threshold`` to your repository specification only shifts the
problem, because now you somehow need to make sure that the key IDs you
received were the right ones. How that is done is however outside the
scope of ``cabal`` proper.

More information about the security infrastructure can be found at
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
https://github.com/haskell/hackage-security.

Local no-index repositories
^^^^^^^^^^^^^^^^^^^^^^^^^^^

It's possible to use a directory of `.tar.gz` package files as a local package
repository.

::

    repository my-local-repository
      url: file+noindex:///absolute/path/to/directory

``cabal`` will construct the index automatically from the
``package-name-version.tar.gz`` files in the directory, and will use optional
corresponding ``package-name-version.cabal`` files as new revisions.

158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
For example, if ``/absolute/path/to/directory`` looks like
::

    /absolute/path/to/directory/
        foo-0.1.0.0.tar.gz
        bar-0.2.0.0.tar.gz
        bar-0.2.0.0.cabal

then ``cabal`` will create an index with two packages:

- ``foo-0.1.0.0`` using the source and ``.cabal`` file inside
  ``foo-0.1.0.0.tar.gz``
- ``bar-0.2.0.0`` using the source inside ``bar-0.2.0.0.tar.gz``
  and ``bar-0.2.0.0.cabal``

173 174 175 176 177
The index is cached inside the given directory. If the directory is not
writable, you can append ``#shared-cache`` fragment to the URI,
then the cache will be stored inside the :cfg-field:`remote-repo-cache` directory.
The part of the path will be used to determine the cache key part.

178 179 180 181 182
.. note::
    ``cabal-install`` creates a ``.cache`` file, and will aggressively use
    it contents if it exists. Therefore if you change the contents of
    the directory, remember to wipe the cache too.

183 184 185 186
.. note::
    The URI scheme ``file:`` is interpreted as a remote repository,
    as described in the previous sections, thus requiring manual construction
    of ``01-index.tar`` file.
187 188

Legacy repositories
189
^^^^^^^^^^^^^^^^^^^
190

Oleg Grenrus's avatar
Oleg Grenrus committed
191 192
Currently ``cabal`` supports single kind of “legacy” repositories.
It is specified using
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209

::

    remote-repo: hackage.haskell.org:http://hackage.haskell.org/packages/archive

This is just syntactic sugar for

::

    repository hackage.haskell.org
      url: hackage.haskell.org:http://hackage.haskell.org/packages/archive

although, in (and only in) the specific case of Hackage, the URL
``http://hackage.haskell.org/packages/archive`` will be silently
translated to ``http://hackage.haskell.org/``.

Secure local repositories
210
^^^^^^^^^^^^^^^^^^^^^^^^^
211 212 213 214

If you want to use repositories on your local file system, it is
recommended instead to use a *secure* local repository:

215
::
216 217 218 219 220 221 222 223

    repository my-local-repo
      url: file:/path/to/local/repo
      secure: True
      root-keys: <root-key-IDs>
      key-threshold: <key-threshold>

The layout of these secure local repos matches the layout of remote
224
repositories exactly; the :hackage-pkg:`hackage-repo-tool`
225 226
can be used to create and manage such repositories.

227 228
.. _installing-packages:

229 230 231
Building and installing packages
================================

232
To be written
233 234 235 236 237

Installing packages from Hackage
--------------------------------

The ``cabal`` tool also can download, configure, build and install a
238
Hackage_ package and all of its
239 240 241 242
dependencies in a single step. To do this, run:

::

243
   $ cabal install [PACKAGE...]
244 245

To browse the list of available packages, visit the
246
Hackage_ web site.