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; required Plugin entrypoint.
`tools`	List of labels; optional; default is `[]` Tools needed by the plugin when enabled.

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_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, narrowed_deps, data, ghcopts,
               repl_ghci_args, runcompile_flags, plugins, non_default_plugins, tools, worker,
               linkstatic, main_function, main_file, version, kwargs)

Build an executable from Haskell source.

Haskell source file names must match their module names. E.g.

My/Module.hs  -->  module My.Module

Any invalid path prefix is stripped. E.g.

Some/prefix/My/Module.hs  -->  module My.Module

Binary targets require a main module named Main or with the module name defined by main_function. If main_file is specified then it must have the main module name. Otherwise, the following heuristics define the main module file.

The source file that matches the main module name. E.g. Main.hs.
The source file that matches no valid module name. E.g. exe.hs.
The only source file of the target.

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. File names must match module names, see above.
`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. Any module coming from a library in `deps` is available to be imported in any modules in this binary.
`narrowed_deps`	optional; default is `[]` Like deps, but modules in these libraries can only be imported by modules listed in the `modules` attribute, and only if the corresponding `haskell_module` rules list such modules as dependencies. Note: This attribute is experimental and not ready for production, yet.
`data`	optional; default is `[]` See Bazel documentation.,
`ghcopts`	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 `ghcopts` 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 `ghcopts` and `repl_ghci_args` from the toolchain. Subject to Make variable substitution.
`plugins`	optional; default is `[]` Compiler plugins to use during compilation. Every module is compiled with `-fplugin=...`.
`non_default_plugins`	optional; default is `[]` Like `plugins` but doesn’t pass `-fplugin=...` to modules by default.
`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.
`main_file`	optional; default is `None` The source file that defines the `Main` module or the module containing `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, narrowed_deps, modules, data,
                ghcopts, repl_ghci_args, runcompile_flags, plugins, non_default_plugins, tools,
                worker, hidden_modules, reexported_modules, exports, linkstatic, package_name,
                version, kwargs)

Build a library from Haskell source.

Haskell source file names must match their module names. E.g.

My/Module.hs  -->  module My.Module

Any invalid path prefix is stripped. E.g.

Some/prefix/My/Module.hs  -->  module My.Module

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. File names must match module names, see above.
`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. Any module coming from a library in `deps` is available to be imported in any modules in this library.
`narrowed_deps`	optional; default is `[]` Like deps, but modules in these libraries can only be imported by modules listed in the `modules` attribute, and only if the corresponding `haskell_module` rules list such modules as dependencies. Note: This attribute is experimental and not ready for production, yet.
`modules`	optional; default is `[]` List of extra haskell_module() dependencies to be linked into this library. Note: This attribute is experimental and not ready for production, yet.
`data`	optional; default is `[]` See Bazel documentation.,
`ghcopts`	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 `ghcopts` 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 `ghcopts` and `repl_ghci_args` from the toolchain. Subject to Make variable substitution.
`plugins`	optional; default is `[]` Compiler plugins to use during compilation. Every module is compiled with `-fplugin=...`.
`non_default_plugins`	optional; default is `[]` Like `plugins` but doesn’t pass `-fplugin=...` to modules by default.
`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 any Haskell module outside of this library.
`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, or which is a dependency of 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)

Attributes

kwargs optional

haskell_repl

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

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)

The haskell_repl macro also creates a runnable target name@bios that generates 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 run //:repl@bios

Args:
  name: A unique name for this rule.
  deps: List of Haskell targets to load into the REPL.
  data: See [Bazel documentation](https://docs.bazel.build/versions/master/be/common-definitions.html#common.data). Only available when `collect_data = True`.
  experimental_from_source: 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.
  experimental_from_binary:
        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.
  repl_ghci_args:
        Arbitrary extra arguments to pass to GHCi. This extends `ghcopts` (previously `compiler_flags`) and `repl_ghci_args` from the toolchain. Subject to Make variable substitution.
  repl_ghci_commands:
        Arbitrary extra commands to execute in GHCi.
  collect_data:
        Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes.

Deprecated:
  hie_bios_path_prefix: Attribute has no effect (now that we output absolute paths).

Attributes

`name`	required
`deps`	required
`data`	optional; default is `[]`
`experimental_from_source`	optional; default is `["//..."]`
`experimental_from_binary`	optional; default is `[]`
`repl_ghci_args`	optional; default is `[]`
`repl_ghci_commands`	optional; default is `[]`
`collect_data`	optional; default is `True`
`kwargs`	optional

haskell_runfiles

haskell_runfiles(name, module_name, base)

Convenience wrapper around rules_haskell runfiles library.

This wrapper is especially usefull with bzlmod, when a haskell library with runfiles is used from another module (see runfiles).

Usage

The haskell_runfiles rule is called in a BUILD file as follows, in order to generate the haskell_runfiles library (this default name can be customized).

haskell_runfiles()
haskell_library(
  ...
  deps = [":haskell_runfiles"],
)

The library can then be used similarly to the runfiles library:

import Runfiles
r <- Runfiles.create
let location = Runfiles.rlocation r "module_name/path/to/datafile"

Attributes

`name`	optional; default is `"haskell_runfiles"` A unique name for this rule.
`module_name`	optional; default is `"Runfiles"` The name of the generated haskell module
`base`	optional; default is `"@rules_haskell//tools/runfiles:base"` The label of the `base` library to depend on.

haskell_test

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

Build a test suite.

Haskell source file names must match their module names. E.g.

My/Module.hs  -->  module My.Module

Any invalid path prefix is stripped. E.g.

Some/prefix/My/Module.hs  -->  module My.Module

The source file that matches the main module name. E.g. Main.hs.
The source file that matches no valid module name. E.g. exe.hs.
The only source file of the target.

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. File names must match module names, see above.
`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. Any module coming from a library in `deps` is available to be imported in any modules in this test suite.
`narrowed_deps`	optional; default is `[]` Like deps, but modules in these libraries can only be imported by modules listed in the `modules` attribute, and only if the corresponding `haskell_module` rules list such modules as dependencies. Note: This attribute is experimental and not ready for production, yet.
`data`	optional; default is `[]` See Bazel documentation.,
`ghcopts`	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 `ghcopts` 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 `ghcopts` and `repl_ghci_args` from the toolchain. Subject to Make variable substitution.
`plugins`	optional; default is `[]` Compiler plugins to use during compilation. Every module is compiled with `-fplugin=...`.
`non_default_plugins`	optional; default is `[]` Like `plugins` but doesn’t pass `-fplugin=...` to modules by default.
`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.
`main_file`	optional; default is `None` The source file that defines the `Main` module or the module containing `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,
                  asterius_binaries, ghcopts, 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"],
    ghcopts = ["-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 A unique name for this toolchain.
`version`	required Version of your GHC compiler. It has to match the version reported by the GHC used by bazel.
`static_runtime`	required Whether GHC was linked with a static runtime.
`fully_static_link`	required Whether GHC should build fully-statically-linked binaries.
`tools`	required GHC and executables that come with it. First item takes precedence.
`libraries`	required The set of libraries that come with GHC. Requires haskell_import targets.
`asterius_binaries`	optional; default is `None` An optional filegroup containing asterius binaries. If present the toolchain will target WebAssembly and only use binaries from `tools` if needed to complete the toolchain.
`ghcopts`	optional; default is `[]` A collection of flags that will be passed to GHC on every invocation.
`repl_ghci_args`	optional; default is `[]` A collection of flags that will be passed to GHCI on repl invocation. It extends the `ghcopts` collection. Flags set here have precedance over `ghcopts`.
`haddock_flags`	optional; default is `[]` A collection of flags that will be passed to haddock.
`cabalopts`	optional; default is `[]` Additional flags to pass to `Setup.hs configure` for all Cabal rules. Note, Cabal rules do not read the toolchain attributes `ghcopts`, `compiler_flags` or `haddock_flags`. Use `--ghc-option=OPT` to configure additional compiler flags. Use `--haddock-option=OPT` to configure additional haddock flags. Use `--haddock-option=--optghc=OPT` if haddock generation requires additional compiler flags.
`locale_archive`	optional; default is `None` Label pointing to the locale archive file to use. Linux-specific and mostly useful on NixOS.
`kwargs`	optional Common rule attributes. See Bazel documentation.

make_repl_kwargs

make_repl_kwargs(args_list, kwargs)

Create extra attributes for the auto-generated haskell_repl target.

Copies the extra attributes specified in args_list from the extra haskell_library|binary|test attributes listed in kwargs.

Adds a manual tag so that the REPL is not built by default.

Attributes

`args_list`	required
`kwargs`	required

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.
`narrowed_deps`	String; required.

Attributes

name

Name; required

A unique name for this target.