Skip to content
Snippets Groups Projects
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
setup-commands.rst 51.14 KiB

.. _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.