Core Haskell rules
Bazel

Core Haskell rules


ghc_plugin

ghc_plugin(name, args, deps, module, tools)

Declare a GHC plugin.

Example:

haskell_library(
    name = "plugin-lib",
    srcs = ["Plugin.hs"],
)

ghc_plugin(
    name = "plugin",
    module = "Plugin",
    deps = [":plugin-lib"],
)

haskell_binary(
    name = "some-binary",
    srcs = ["Main.hs"],
    plugins = [":plugin"],

Plugins to use during compilation by GHC are given by the plugins attribute to Haskell rules. Plugins are haskell libraries with some extra metadata, like the name of the module that acts as the entrypoint for the plugin and plugin options.

See https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/extending_ghc.html#writing-compiler-plugins for more information.

Attributes

name Name; required

A unique name for this target.

args List of strings; optional; default is []

Plugin options.

deps List of labels; optional; default is []

Plugin dependencies. These are compile-time dependencies only.

The dependencies of this attribute must provide: HaskellLibraryInfo

module String; optional; default is ""

Plugin entrypoint.

tools List of labels; optional; default is []

Tools needed by the plugin when it used.


haskell_doc

haskell_doc(name, deps, index_transitive_deps)

Create API documentation.

Builds API documentation (using Haddock) for the given Haskell libraries. It will automatically build documentation for any transitive dependencies to allow for cross-package documentation linking.

Examples

haskell_library(
  name = "my-lib",
  ...
)

haskell_doc(
  name = "my-lib-doc",
  deps = [":my-lib"],
)

Attributes

name Name; required

A unique name for this target.

deps List of labels; optional; default is []

List of Haskell libraries to generate documentation for.

index_transitive_deps Boolean; optional; default is False

Whether to include documentation of transitive dependencies in index.


haskell_import

haskell_import(name, deps, haddock_html, haddock_interfaces, hdrs, id, includes, linkopts,
               shared_libraries, static_libraries, static_profiling_libraries, version)

Internal rule. Do not use.

The attributes of this rule loosely correspond to the fields of the GHC package database. Refer to the GHC User’s Guide for documentation.

Attributes

name Name; required

A unique name for this target.

deps List of labels; optional; default is []
haddock_html Label; optional; default is None
haddock_interfaces List of labels; optional; default is []
hdrs List of labels; optional; default is []
id String; optional; default is ""
includes List of strings; optional; default is []
linkopts List of strings; optional; default is []
shared_libraries List of labels; optional; default is []
static_libraries List of labels; optional; default is []
static_profiling_libraries List of labels; optional; default is []
version String; optional; default is ""

haskell_repl

haskell_repl(name, collect_data, data, deps, experimental_from_binary, experimental_from_source,
             repl_ghci_args, repl_ghci_commands)

Build a REPL for multiple targets.

Examples

haskell_repl(
    name = "repl",
    deps = [
        "//lib:some_lib",
        "//exe:some_exe",
    ],
    experimental_from_source = [
        "//lib/...",
        "//exe/...",
        "//common/...",
    ],
    experimental_from_binary = [
        "//lib/vendored/...",
    ],
)

Collects all transitive Haskell dependencies from deps. Those that match experimental_from_binary or are defined in an external workspace will be loaded as binary packages. Those that match experimental_from_source and are defined in the local workspace will be loaded by source.

You can call the REPL like this:

$ bazel run //:repl

IDE Support (Experimental)

haskell_repl targets provide the hie_bios output group to optionally generate GHCi flags for hie-bios’s bios cradle. You can use this for IDE support with ghcide.

Given a haskell_repl target //:repl an example .hie-bios script could look as follows. Please refer to the hie-bios documentation for further information.

#!/usr/bin/env bash
set -euo pipefail
bazel build //:repl --output_groups=hie_bios
cat bazel-bin/repl@hie-bios >"$HIE_BIOS_OUTPUT"

Attributes

name Name; required

A unique name for this target.

collect_data Boolean; optional; default is True

Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes.

data List of labels; optional; default is []

See Bazel documentation. Only available when collect_data = True.

deps List of labels; optional; default is []

List of Haskell targets to load into the REPL

experimental_from_binary List of strings; optional; default is []

Black-list of targets to not load by source but as packages.

Wild-card targets such as //… or //:all are allowed.

The black-list takes precedence over the white-list.

Note, this attribute will change depending on the outcome of https://github.com/bazelbuild/bazel/issues/7763.

experimental_from_source List of strings; optional; default is ["//..."]

White-list of targets to load by source.

Wild-card targets such as //… or //:all are allowed.

The black-list takes precedence over the white-list.

Note, this attribute will change depending on the outcome of https://github.com/bazelbuild/bazel/issues/7763.

repl_ghci_args List of strings; optional; default is []

Arbitrary extra arguments to pass to GHCi. This extends compiler_flags and repl_ghci_args from the toolchain. Subject to Make variable substitution.

repl_ghci_commands List of strings; optional; default is []

Arbitrary extra commands to execute in GHCi.


haskell_toolchain_library

haskell_toolchain_library(name, package)

Import prebuilt libraries supplied by the toolchain.

Use this rule to make dependencies that are prebuilt (supplied as part of the compiler toolchain) available as targets.

Examples

haskell_toolchain_library(
    name = "base_pkg",
    package = "base",
)

haskell_library(
    name = "hello-lib",
    srcs = ["Lib.hs"],
    deps = [
        ":base_pkg",
        "//hello-sublib:lib",
    ],
)

Attributes

name Name; required

A unique name for this target.

package String; optional; default is ""

The name of a GHC package not built by Bazel. Defaults to the name of the rule.


haskell_binary

haskell_binary(name, src_strip_prefix, srcs, extra_srcs, deps, data, compiler_flags, repl_ghci_args,
               runcompile_flags, plugins, tools, worker, linkstatic, main_function, version, kwargs)

Build an executable from Haskell source.

Every haskell_binary target also defines an optional REPL target that is not built by default, but can be built on request. The name of the REPL target is the same as the name of binary with "@repl" added at the end. For example, the target above also defines main@repl.

You can call the REPL like this (requires Bazel 0.15 or later):

$ bazel run //:hello@repl

Examples

haskell_binary(
    name = "hello",
    srcs = ["Main.hs", "Other.hs"],
    deps = ["//lib:some_lib"]
)

Attributes

name required

A unique name for this rule.

src_strip_prefix optional; default is ""

DEPRECATED. Attribute has no effect.

srcs optional; default is []

Haskell source files.

extra_srcs optional; default is []

Extra (non-Haskell) source files that will be needed at compile time (e.g. by Template Haskell).

deps optional; default is []

List of other Haskell libraries to be linked to this target.

data optional; default is []

See Bazel documentation.,

compiler_flags optional; default is []

Flags to pass to Haskell compiler. Subject to Make variable substitution.

repl_ghci_args optional; default is []

Arbitrary extra arguments to pass to GHCi. This extends compiler_flags and repl_ghci_args from the toolchain. Subject to Make variable substitution.,

runcompile_flags optional; default is []

Arbitrary extra arguments to pass to runghc. This extends compiler_flags and repl_ghci_args from the toolchain. Subject to Make variable substitution.

plugins optional; default is []

Compiler plugins to use during compilation.

tools optional; default is []

Extra tools needed at compile-time, like preprocessors.

worker optional; default is None

Experimental. Worker binary employed by Bazel’s persistent worker mode. See use-cases documentation.

linkstatic optional; default is True

Link dependencies statically wherever possible. Some system libraries may still be linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static.

main_function optional; default is "Main.main"

A function with type IO _, either the qualified name of a function from any module or the bare name of a function from a Main module. It is also possible to give the qualified name of any module exposing a main function.

version optional; default is None

Executable version. If this is specified, CPP version macros will be generated for this build.

kwargs optional

Common rule attributes. See Bazel documentation.


haskell_library

haskell_library(name, src_strip_prefix, srcs, extra_srcs, deps, data, compiler_flags,
                repl_ghci_args, runcompile_flags, plugins, tools, worker, hidden_modules,
                reexported_modules, exports, linkstatic, package_name, version, kwargs)

Build a library from Haskell source.

Every haskell_library target also defines an optional REPL target that is not built by default, but can be built on request. It works the same way as for haskell_binary.

Examples

haskell_library(
    name = "hello-lib",
    srcs = glob(["src/**/*.hs"]),
    src_strip_prefix = "src",
    deps = [
        "//hello-sublib:lib",
    ],
    reexported_modules = {
        "//hello-sublib:lib": "Lib1 as HelloLib1, Lib2",
    },
)

Attributes

name required

A unique name for this rule.

src_strip_prefix optional; default is ""

DEPRECATED. Attribute has no effect.

srcs optional; default is []

Haskell source files.

extra_srcs optional; default is []

Extra (non-Haskell) source files that will be needed at compile time (e.g. by Template Haskell).

deps optional; default is []

List of other Haskell libraries to be linked to this target.

data optional; default is []

See Bazel documentation.,

compiler_flags optional; default is []

Flags to pass to Haskell compiler. Subject to Make variable substitution.

repl_ghci_args optional; default is []

Arbitrary extra arguments to pass to GHCi. This extends compiler_flags and repl_ghci_args from the toolchain. Subject to Make variable substitution.,

runcompile_flags optional; default is []

Arbitrary extra arguments to pass to runghc. This extends compiler_flags and repl_ghci_args from the toolchain. Subject to Make variable substitution.

plugins optional; default is []

Compiler plugins to use during compilation.

tools optional; default is []

Extra tools needed at compile-time, like preprocessors.

worker optional; default is None

Experimental. Worker binary employed by Bazel’s persistent worker mode. See use-cases documentation.

hidden_modules optional; default is []

Modules that should be unavailable for import by dependencies.

reexported_modules optional; default is {}

A dictionary mapping dependencies to module reexports that should be available for import by dependencies.

exports optional; default is []

A list of other haskell libraries that will be transparently added as a dependency to every downstream rule

linkstatic optional; default is False

Create a static library, not both a static and a shared library.

package_name optional; default is ""

Library name used in version macro generation. Only used if the version attribute is defined, see version attribute documentation. Optional, defaults to target name.

version optional; default is ""

Library version. Not normally necessary unless to build a library originally defined as a Cabal package. If this is specified, CPP version macro will be generated.

kwargs optional

Common rule attributes. See Bazel documentation.


haskell_register_toolchains

haskell_register_toolchains(kwargs)

Register GHC binary distributions for all platforms as toolchains.

Attributes

kwargs optional

haskell_test

haskell_test(name, src_strip_prefix, srcs, extra_srcs, deps, data, compiler_flags, repl_ghci_args,
             runcompile_flags, plugins, tools, worker, linkstatic, main_function, version,
             expected_covered_expressions_percentage, expected_uncovered_expression_count,
             strict_coverage_analysis, coverage_report_format, experimental_coverage_source_patterns,
             kwargs)

Build a test suite.

Additionally, it accepts all common bazel test rule fields. This allows you to influence things like timeout and resource allocation for the test.

Attributes

name required

A unique name for this rule.

src_strip_prefix optional; default is ""

DEPRECATED. Attribute has no effect.

srcs optional; default is []

Haskell source files.

extra_srcs optional; default is []

Extra (non-Haskell) source files that will be needed at compile time (e.g. by Template Haskell).

deps optional; default is []

List of other Haskell libraries to be linked to this target.

data optional; default is []

See Bazel documentation.,

compiler_flags optional; default is []

Flags to pass to Haskell compiler. Subject to Make variable substitution.

repl_ghci_args optional; default is []

Arbitrary extra arguments to pass to GHCi. This extends compiler_flags and repl_ghci_args from the toolchain. Subject to Make variable substitution.,

runcompile_flags optional; default is []

Arbitrary extra arguments to pass to runghc. This extends compiler_flags and repl_ghci_args from the toolchain. Subject to Make variable substitution.

plugins optional; default is []

Compiler plugins to use during compilation.

tools optional; default is []

Extra tools needed at compile-time, like preprocessors.

worker optional; default is None

Experimental. Worker binary employed by Bazel’s persistent worker mode. See use-cases documentation.

linkstatic optional; default is True

Link dependencies statically wherever possible. Some system libraries may still be linked dynamically, as are libraries for which there is no static library. So the resulting executable will still be dynamically linked, hence only mostly static.

main_function optional; default is "Main.main"

A function with type IO _, either the qualified name of a function from any module or the bare name of a function from a Main module. It is also possible to give the qualified name of any module exposing a main function.

version optional; default is None

Executable version. If this is specified, CPP version macros will be generated for this build.

expected_covered_expressions_percentage optional; default is -1

The expected percentage of expressions covered by testing.

expected_uncovered_expression_count optional; default is -1

The expected number of expressions which are not covered by testing.

strict_coverage_analysis optional; default is False

Requires that the coverage metric is matched exactly, even doing better than expected is not allowed.

coverage_report_format optional; default is "text"

The format to output the coverage report in.

Supported values: “text”, “html”. Default: “text”.

Report can be seen in the testlog XML file, or by setting –test_output=all when running bazel coverage.

experimental_coverage_source_patterns optional; default is ["//..."]

The path patterns specifying which targets to analyze for test coverage metrics.

Wild-card targets such as //… or //:all are allowed. The paths must be relative to the workspace, which means they must start with “//”.

Note, this attribute may leave experimental status depending on the outcome of https://github.com/bazelbuild/bazel/issues/7763.

kwargs optional

Common rule attributes. See Bazel documentation.


haskell_toolchain

haskell_toolchain(name, version, static_runtime, fully_static_link, tools, libraries,
                  compiler_flags, repl_ghci_args, haddock_flags, cabalopts, locale_archive, kwargs)

Declare a compiler toolchain.

You need at least one of these declared somewhere in your BUILD files for the other rules to work. Once declared, you then need to register the toolchain using register_toolchains in your WORKSPACE file (see example below).

Examples

In a BUILD file:

haskell_toolchain(
    name = "ghc",
    version = "1.2.3",
    static_runtime = static_runtime,
    fully_static_link = fully_static_link,
    tools = ["@sys_ghc//:bin"],
    compiler_flags = ["-Wall"],
)

where @sys_ghc is an external repository defined in the WORKSPACE, e.g. using:

nixpkgs_package(
    name = 'sys_ghc',
    attribute_path = 'haskell.compiler.ghc822',
)

register_toolchains("//:ghc")

Attributes

name required
version required
static_runtime required
tools required
libraries required
compiler_flags optional; default is []
repl_ghci_args optional; default is []
haddock_flags optional; default is []
cabalopts optional; default is []
locale_archive optional; default is None
kwargs optional

haskell_doc_aspect

haskell_doc_aspect(name)

Aspect Attributes

deps String; required.
exports String; required.

Attributes

name Name; required

A unique name for this target.


haskell_repl_aspect

haskell_repl_aspect(name)

Haskell REPL aspect.

Used to implement the haskell_repl rule. Does not generate an executable REPL by itself.

Aspect Attributes

deps String; required.

Attributes

name Name; required

A unique name for this target.