setup-commands.rst

.. _setup-commands:

Setup.hs Commands
=================

.. highlight:: console

GHC provides the commands ``runhaskell`` and ``runghc`` (they are equivalent)
to allow you to run Haskell programs without first having to compile them
(scripts). The low-level Cabal interface is implemented using ``Setup.hs``
scripts. You should prefer using higher level interface provided by nix-style
builds. However, the documentation of the low level interface below may be helpful
to high level interface users as well, because it delves into internal details
common to both and omitted elsewhere.

::

$ runhaskell Setup.hs [command] [option...]

For the summary of the ``Setup.hs`` script's command syntax, run:

::

$ runhaskell Setup.hs --help

Building and installing a system package
----------------------------------------

::

$ runhaskell Setup.hs configure --ghc
$ runhaskell Setup.hs build
$ runhaskell Setup.hs install

The first line readies the system to build the tool using GHC; for
example, it checks that GHC exists on the system. The second line
performs the actual building, while the last both copies the build
results to some permanent place and registers the package with GHC.

.. note ::

Global installing of packages is not recommended.
The :ref:`nix-style-builds` is the preferred way of building and installing
packages.

Creating a binary package
-------------------------

When creating binary packages (e.g. for Red Hat or Debian) one needs to
create a tarball that can be sent to another system for unpacking in the
root directory:

::

$ runhaskell Setup.hs configure --prefix=/usr
$ runhaskell Setup.hs build
$ runhaskell Setup.hs copy --destdir=/tmp/mypkg
$ tar -czf mypkg.tar.gz /tmp/mypkg/

If the package contains a library, you need two additional steps:

::

$ runhaskell Setup.hs register --gen-script
$ runhaskell Setup.hs unregister --gen-script

This creates shell scripts ``register.sh`` and ``unregister.sh``, which
must also be sent to the target system. After unpacking there, the
package must be registered by running the ``register.sh`` script. The
``unregister.sh`` script would be used in the uninstall procedure of the
package. Similar steps may be used for creating binary packages for
Windows.

The following options are understood by all commands:

.. program:: setup

.. option:: --help, -h or -?

List the available options for the command.

.. option:: --verbose=n or -v n

Set the verbosity level (0-3). The normal level is 1; a missing *n*
defaults to 2.

There is also an extended version of this command which can be
used to fine-tune the verbosity of output. It takes the
form ``[silent|normal|verbose|debug]``\ *flags*, where *flags*
is a list of ``+`` flags which toggle various aspects of
output. At the moment, only ``+callsite`` and ``+callstack``
are supported, which respectively toggle call site and call
stack printing (these are only supported if Cabal
is built with a sufficiently recent GHC.)

The various commands and the additional options they support are
described below. In the simple build infrastructure, any other options
will be reported as errors.

.. _setup-configure:

runhaskell Setup.hs configure
-----------------------------

.. program:: runhaskell Setup.hs configure

Prepare to build the package. Typically, this step checks that the
target platform is capable of building the package, and discovers
platform-specific features that are needed during the build.

The user may also adjust the behaviour of later stages using the options
listed in the following subsections. In the simple build infrastructure,
the values supplied via these options are recorded in a private file
read by later stages.

If a user-supplied ``configure`` script is run (see the section on
:ref:`system-dependent parameters` or
on :ref:`more-complex-packages`), it is
passed the :option:`--with-hc-pkg`, :option:`--prefix`, :option:`--bindir`,
:option:`--libdir`, :option:`--dynlibdir`, :option:`--datadir`, :option:`--libexecdir` and
:option:`--sysconfdir` options. In addition the value of the
:option:`--with-compiler` option is passed in a :option:`--with-hc-pkg` option
and all options specified with :option:`--configure-option` are passed on.

.. note::
`GNU autoconf places restrictions on paths, including the directory
that the package is built from.
`_
The errors produced when this happens can be obscure; Cabal attempts to
detect and warn in this situation, but it is not perfect.

In Cabal 2.0, support for a single positional argument was added to
``runhaskell Setup.hs configure`` This makes Cabal configure the specific component to
be configured. Specified names can be qualified with ``lib:`` or
``exe:`` in case just a name is ambiguous (as would be the case for a
package named ``p`` which has a library and an executable named ``p``.)
This has the following effects:

- Subsequent invocations of ``cabal build``, ``register``, etc. operate only
on the configured component.

- Cabal requires all "internal" dependencies (e.g., an executable
depending on a library defined in the same package) must be found in
the set of databases via :option:`--package-db` (and related flags): these
dependencies are assumed to be up-to-date. A dependency can be
explicitly specified using :option:`--dependency` simply by giving the name
of the sublibrary; e.g., the dependency for a sublibrary
named ``foo`` is given as
``--dependency=Lib:foo=foo-0.1-abc``.

- Only the dependencies needed for the requested component are
required. Similarly, when :option:`--exact-configuration` is specified,
it's only necessary to specify :option:`--dependency` for the component.
(As mentioned previously, you *must* specify internal dependencies as
well.)

- Internal ``build-tool-depends`` and ``build-tools`` dependencies are expected
to be in the ``PATH`` upon subsequent invocations of ``setup``.

Full details can be found in the `Componentized Cabal
proposal `__.

Programs used for building
^^^^^^^^^^^^^^^^^^^^^^^^^^

The following options govern the programs used to process the source
files of a package:

.. option:: -g, --ghc
--ghcjs
--uhc
--haskell-suite

Specify which Haskell implementation to use to build the package. At
most one of these flags may be given. If none is given, the
implementation under which the setup script was compiled or
interpreted is used.

.. option:: -w PATH or -wPATH, --with-compiler=PATH

Specify the path to a particular compiler. If given, this must match
the implementation selected above. The default is to search for the
usual name of the selected implementation.

This flag also sets the default value of the :option:`--with-hc-pkg`
option to the package tool for this compiler. Check the output of
``runhaskell Setup.hs configure -v`` to ensure that it finds the right package
tool (or use :option:`--with-hc-pkg` explicitly).

.. option:: --with-hc-pkg=PATH

Specify the path to the package tool, e.g. ``ghc-pkg``. The package
tool must be compatible with the compiler specified by
:option:`--with-compiler`. If this option is omitted, the default value is
determined from the compiler selected.

.. option:: --with-PROG=PATH

Specify the path to the program *prog*. Any program known to Cabal
can be used in place of *prog*. It can either be a fully path or the
name of a program that can be found on the program search path. For
example: ``--with-ghc=ghc-6.6.1`` or
``--with-cpphs=/usr/local/bin/cpphs``. The full list of accepted
programs is not enumerated in this user guide. Rather, run
``cabal install --help`` to view the list.

.. option:: --PROG-options=OPTS

Specify additional options to the program *prog*. Any program known
to Cabal can be used in place of *prog*. For example:
``--alex-options="--template=mytemplatedir/"``. The *options* is
split into program options based on spaces. Any options containing
embedded spaced need to be quoted, for example
``--foo-options='--bar="C:\Program File\Bar"'``. As an alternative
that takes only one option at a time but avoids the need to quote,
use :option:`--PROG-option` instead.

.. option:: --PROG-option=OPT

Specify a single additional option to the program *prog*. For
passing an option that contains embedded spaces, such as a file name
with embedded spaces, using this rather than :option:`--PROG-options`
means you do not need an additional level of quoting. Of course if you
are using a command shell you may still need to quote, for example
``--foo-options="--bar=C:\Program File\Bar"``.

All of the options passed with either :option:`--PROG-options`
or :option:`--PROG-option` are passed in the order they were
specified on the configure command line.

Installation paths
^^^^^^^^^^^^^^^^^^

The following options govern the location of installed files from a
package:

.. option:: --prefix=DIR

The root of the installation. For example for a global install you
might use ``/usr/local`` on a Unix system, or ``C:\Program Files``
on a Windows system. The other installation paths are usually
subdirectories of *prefix*, but they don't have to be.

In the simple build system, *dir* may contain the following path
variables: ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``,
``$os``, ``$arch``, ``$abi``, ``$abitag``

.. option:: --bindir=DIR

Executables that the user might invoke are installed here.

In the simple build system, *dir* may contain the following path
variables: ``$prefix``, ``$pkgid``, ``$pkg``, ``$version``,
``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag``

.. option:: --libdir=DIR

Object-code libraries are installed here.

In the simple build system, *dir* may contain the following path
variables: ``$prefix``, ``$bindir``, ``$pkgid``, ``$pkg``,
``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
``$abitag``

.. option:: --dynlibdir=DIR

Dynamic libraries are installed here.

By default, this is set to `$libdir/$abi`, which is usually not equal to
`$libdir/$libsubdir`.

In the simple build system, *dir* may contain the following path
variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$pkgid``, ``$pkg``,
``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
``$abitag``

.. option:: --libexecdir=DIR

Executables that are not expected to be invoked directly by the user
are installed here.

In the simple build system, *dir* may contain the following path
variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``,
``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``,
``$arch``, ``$abi``, ``$abitag``

.. option:: --datadir=DIR

Architecture-independent data files are installed here.

In the simple build system, *dir* may contain the following path
variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``,
``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``,
``$arch``, ``$abi``, ``$abitag``

.. option:: --sysconfdir=DIR

Installation directory for the configuration files.

In the simple build system, *dir* may contain the following path
variables: ``$prefix``, ``$bindir``, ``$libdir``, ``$libsubdir``,
``$pkgid``, ``$pkg``, ``$version``, ``$compiler``, ``$os``,
``$arch``, ``$abi``, ``$abitag``

In addition the simple build system supports the following installation
path options:

.. option:: --libsubdir=DIR

A subdirectory of *libdir* in which libraries are actually installed. For
example, in the simple build system on Unix, the default *libdir* is
``/usr/local/lib``, and *libsubdir* contains the compiler ABI and package
identifier,
e.g. ``x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A``, so
libraries would be installed in
``/usr/local/lib/x86_64-linux-ghc-8.0.2/mypkg-0.1.0-IxQNmCA7qrSEQNkoHSF7A/``.

*dir* may contain the following path variables: ``$pkgid``,
``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
``$abitag``

.. option:: --libexecsubdir=DIR

A subdirectory of *libexecdir* in which private executables are
installed. For example, in the simple build system on Unix, the default
*libexecdir* is ``/usr/local/libexec``, and *libsubdir* is
``x86_64-linux-ghc-8.0.2/mypkg-0.1.0``, so private executables would be
installed in ``/usr/local/libexec/x86_64-linux-ghc-8.0.2/mypkg-0.1.0/``

*dir* may contain the following path variables: ``$pkgid``,
``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
``$abitag``

.. option:: --datasubdir=DIR

A subdirectory of *datadir* in which data files are actually
installed.

*dir* may contain the following path variables: ``$pkgid``,
``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
``$abitag``

.. option:: --docdir=DIR

Documentation files are installed relative to this directory.

*dir* may contain the following path variables: ``$prefix``,
``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``,
``$datasubdir``, ``$pkgid``, ``$pkg``, ``$version``, ``$compiler``,
``$os``, ``$arch``, ``$abi``, ``$abitag``

.. option:: --htmldir=DIR

HTML documentation files are installed relative to this directory.

*dir* may contain the following path variables: ``$prefix``,
``$bindir``, ``$libdir``, ``$libsubdir``, ``$datadir``,
``$datasubdir``, ``$docdir``, ``$pkgid``, ``$pkg``, ``$version``,
``$compiler``, ``$os``, ``$arch``, ``$abi``, ``$abitag``

.. option:: --program-prefix=PREFIX

Prepend *prefix* to installed program names.

*prefix* may contain the following path variables: ``$pkgid``,
``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
``$abitag``

.. option:: --program-suffix=SUFFIX

Append *suffix* to installed program names. The most obvious use for
this is to append the program's version number to make it possible
to install several versions of a program at once:
``--program-suffix='$version'``.

*suffix* may contain the following path variables: ``$pkgid``,
``$pkg``, ``$version``, ``$compiler``, ``$os``, ``$arch``, ``$abi``,
``$abitag``

Path variables in the simple build system
"""""""""""""""""""""""""""""""""""""""""

For the simple build system, there are a number of variables that can be
used when specifying installation paths. The defaults are also specified
in terms of these variables. A number of the variables are actually for
other paths, like ``$prefix``. This allows paths to be specified
relative to each other rather than as absolute paths, which is important
for building relocatable packages (see :ref:`prefix independence`).

$prefix
The path variable that stands for the root of the installation. For
an installation to be relocatable, all other installation paths must
be relative to the ``$prefix`` variable.
$bindir
The path variable that expands to the path given by the :option:`--bindir`
configure option (or the default).
$libdir
As above but for :option:`--libdir`
$libsubdir
As above but for :option:`--libsubdir`
$dynlibdir
As above but for :option:`--dynlibdir`
$datadir
As above but for :option:`--datadir`
$datasubdir
As above but for :option:`--datasubdir`
$docdir
As above but for :option:`--docdir`
$pkgid
The name and version of the package, e.g. ``mypkg-0.2``
$pkg
The name of the package, e.g. ``mypkg``
$version
The version of the package, e.g. ``0.2``
$compiler
The compiler being used to build the package, e.g. ``ghc-6.6.1``
$os
The operating system of the computer being used to build the
package, e.g. ``linux``, ``windows``, ``osx``, ``freebsd`` or
``solaris``
$arch
The architecture of the computer being used to build the package,
e.g. ``i386``, ``x86_64``, ``ppc`` or ``sparc``
$abitag
An optional tag that a compiler can use for telling incompatible
ABI's on the same architecture apart. GHCJS encodes the underlying
GHC version in the ABI tag.
$abi
A shortcut for getting a path that completely identifies the
platform in terms of binary compatibility. Expands to the same value
as ``$arch-$os-compiler-$abitag`` if the compiler uses an abi tag,
``$arch-$os-$compiler`` if it doesn't.

Paths in the simple build system
""""""""""""""""""""""""""""""""