HASKELL-CABAL.ECLASS

Section: eclass-manpages (5)
Updated: Jul 2025
Index Return to Main Contents

NAME

haskell-cabal.eclass - for packages that make use of the Haskell Common Architecture for Building Applications and Libraries (cabal)

DESCRIPTION

Basic instructions:

Before inheriting the eclass, set CABAL_FEATURES to reflect the tools and features that the package makes use of.

Currently supported features:
  haddock    --  for documentation generation
  hscolour   --  generation of colourised sources
  hoogle     --  generation of documentation search index
  profile    --  if package supports to build profiling-enabled libraries
  bootstrap  --  only used for the cabal package itself
  lib        --  the package installs libraries
  nocabaldep --  don't add dependency on cabal.
                 only used for packages that _must_ not pull the dependency
                 on cabal, but still use this eclass (e.g. haskell-updater).
  ghcdeps    --  constraint dependency on package to ghc once
                 only used for packages that use libghc internally and _must_
                 not pull upper versions
  test-suite --  add support for cabal test-suites (introduced in Cabal-1.8)
  rebuild-after-doc-workaround -- enable doctest test failure workaround.
                 Symptom: when `./setup haddock` is run in a `build-type: Custom`
                 package it might cause cause the test-suite to fail with
                 errors like:
                 > <command line>: cannot satisfy -package-id singletons-2.7-3Z7pnljD8tU1NrslJodXmr
                 Workaround re-registers the package to avoid the failure
                 (and rebuilds changes).
                 FEATURE can be removed once https://github.com/haskell/cabal/issues/7213
                 is fixed.

SUPPORTED EAPIS

7 8

FUNCTIONS

cabal-check-cache

Check the state of the GHC cache by running 'ghc-pkg check' and looking for the string "WARNING: cache is out of date". If the string is not found, the cache is considered valid and the function returns 0. If it is found, the cache is considered invalid and the function returns 1.

cabal_flag

ebuild.sh:use_enable() taken as base

Usage examples:

CABAL_CONFIGURE_FLAGS=$(cabal_flag gui)
leads to "--flags=gui" or "--flags=-gui" (useflag 'gui')

CABAL_CONFIGURE_FLAGS=$(cabal_flag gtk gui)
also leads to "--flags=gui" or " --flags=-gui" (useflag 'gtk')

cabal_chdeps

See the CABAL_CHDEPS variable for the preferred way to use this function.

Allows easier patching of $CABAL_FILE (${S}/${PN}.cabal by default) depends

Accepts argument list as pairs of substitutions: <from-string> <to-string>...

Dies on error.

cabal-constraint

Allows to set constraint to the libraries that are used by specified package

replace-hcflags <old> <new>

Replace the <old> flag with <new> in HCFLAGS. Accepts shell globs for <old>. The implementation is picked from flag-o-matic.eclass:replace-flags()

cabal-register-inplace

Register the package library with the in-place package DB, located in "${S}/dist/package.conf.inplace/". This is sometimes needed for tests when the package is not yet installed. Unfortunately, prebuilt solutions to this problem, such as './setup register --inplace', do not seem to work correctly.

This function will not run unless CABAL_HAS_LIBRARIES is set to a nonempty value.

You can set SKIP_REGISTER_INPLACE to a nonempty value to skip this function (useful since it is automatically called from within haskell-cabal_src_test).

The environment variables TEST_CABAL_PN and TEST_PN can be manually set in case the test suite is within a separate haskell package.

The environment variable EXTRA_PACKAGE_DBS can be used to set extra databases for ghc-pkg to read.

cabal-run-dist-bin <bin> [args]

Run an executable that was built but has not been installed to the system. These live in "${S}/dist/build/", which also includes libraries that are needed by the executable. (Needed libraries are automatically added to LD_LIBRARY_PATH by haskell-cabal_src_compile().)

This is only intended to be run in the test and install phases.

ECLASS VARIABLES

CABAL_EXTRA_CONFIGURE_FLAGS (USER VARIABLE)

User-specified additional parameters passed to 'setup configure'. example: /etc/portage/make.conf:
CABAL_EXTRA_CONFIGURE_FLAGS="--enable-shared --enable-executable-dynamic"

CABAL_EXTRA_BUILD_FLAGS (USER VARIABLE)

User-specified additional parameters passed to 'setup build'. example: /etc/portage/make.conf: CABAL_EXTRA_BUILD_FLAGS=-v

GHC_BOOTSTRAP_FLAGS (USER VARIABLE)

User-specified additional parameters for ghc when building _only_ 'setup' binary bootstrap. example: /etc/portage/make.conf: GHC_BOOTSTRAP_FLAGS=-dynamic to make linking 'setup' faster.

CABAL_EXTRA_HADDOCK_FLAGS (USER VARIABLE)

User-specified additional parameters passed to 'setup haddock'. example: /etc/portage/make.conf:
CABAL_EXTRA_HADDOCK_FLAGS="--haddock-options=--latex --haddock-options=--pretty-html"

CABAL_EXTRA_HOOGLE_FLAGS (USER VARIABLE)

User-specified additional parameters passed to 'setup haddock --hoogle'. example: /etc/portage/make.conf:
CABAL_EXTRA_HOOGLE_FLAGS="--haddock-options=--show-all"

CABAL_EXTRA_HSCOLOUR_FLAGS (USER VARIABLE)

User-specified additional parameters passed to 'setup hscolour'. example: /etc/portage/make.conf:
CABAL_EXTRA_HSCOLOUR_FLAGS="--executables --tests"

CABAL_EXTRA_TEST_FLAGS (USER VARIABLE)

User-specified additional parameters passed to 'setup test'. example: /etc/portage/make.conf:
CABAL_EXTRA_TEST_FLAGS="-v3 --show-details=streaming"

CABAL_DEBUG_LOOSENING

Show debug output for 'cabal_chdeps' function if set. Needs working 'diff'.

CABAL_REPORT_OTHER_BROKEN_PACKAGES ?= yes

Show other broken packages if 'cabal configure' fails. It should be normally enabled unless you know you are about to try to compile a lot of broken packages. Default value: 'yes' Set to anything else to disable.

CABAL_HACKAGE_REVISION ?= 0 (SET BEFORE INHERIT)

Set the upstream revision number from Hackage. This will automatically add the upstream cabal revision to SRC_URI and apply it in src_prepare.

CABAL_PN ?= ${PN} (SET BEFORE INHERIT)

Set the name of the package as it is recorded in the Hackage database. This is mostly used when packages use CamelCase names upstream, but we want them to be lowercase in portage.

CABAL_PV ?= ${PV} (SET BEFORE INHERIT)

Set the version of the package as it is recorded in the Hackage database. This can be useful if we use a different versioning scheme in Portage than the one from upstream

CABAL_P = "${CABAL_PN}-${CABAL_PV}" (GENERATED BY ECLASS)

The combined $CABAL_PN and $CABAL_PV variables, analogous to $P

CABAL_FILE ?= "${S}/${CABAL_PN}.cabal"

The location of the .cabal file for the Haskell package. This defaults to "${S}/${CABAL_PN}.cabal".

NOTE: If $S is redefined in the ebuild after inheriting this eclass, $CABAL_FILE will also need to be redefined as well.

CABAL_DISTFILE (GENERATED BY ECLASS)

The name of the .cabal file downloaded from Hackage. This filename does not include $DISTDIR

CABAL_CHDEPS

Specifies changes to be made to the .cabal file. Accepts argument list as pairs of substitutions: <from-string> <to-string>... Uses the cabal_chdeps function internally and shares the same syntax.

Example:

CABAL_CHDEPS=( 'base >= 4.2 && < 4.6' 'base >= 4.2 && < 4.7'
'containers ==0.4.*' 'containers >= 0.4 && < 0.6'
)

CABAL_LIVE_VERSION (SET BEFORE INHERIT)

Set this to any value to prevent SRC_URI from being set automatically.

GHC_BOOTSTRAP_PACKAGES

Extra packages that need to be exposed when compiling Setup.hs

CABAL_TEST_REQUIRED_BINS

Binaries included in this package which are needed during testing. This adjusts PATH during src_test() so that the binaries can be found, even if they have not been installed yet.

Example:

CABAL_TEST_REQUIRED_BINS=( arbtt-{capture,dump,import,recover,stats} )

CABAL_HADDOCK_TARGETS

Manually set the targets for haddock/hoogle. This is occasionally needed when './setup haddock' cannot calculate the transient dependencies.

Example:

CABAL_HADDOCK_TARGETS="lib:${CABAL_PN}"

CABAL_CHBINS

Renames executables that are installed with the package. Accepts argument list as pairs of substitutions: <from-string> <to-string>...

Example:

CABAL_CHBINS=(         'demo' 'byline-demo'
        'simple' 'byline-simple'
        'menu' 'byline-menu'
        'shell' 'byline-shell'
)

AUTHORS

Original author: Andres Loeh <kosmikus@gentoo.org>
Original author: Duncan Coutts <dcoutts@gentoo.org>

MAINTAINERS

Haskell herd <haskell@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

haskell-cabal.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, July 14, 2025

HASKELL-CABAL.ECLASS

NAME

DESCRIPTION

SUPPORTED EAPIS

FUNCTIONS

ECLASS VARIABLES

AUTHORS

MAINTAINERS

REPORTING BUGS

FILES

SEE ALSO

Index