Core Haskell rules
Rules
ghc_plugin
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.
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "ghc_plugin")
ghc_plugin(
# A unique name for this target.
name = "",
# Plugin entrypoint.
module = "",
)
name
A unique name for this target.
args
Plugin options.
deps
Plugin dependencies. These are compile-time dependencies only.
module
Plugin entrypoint.
tools
Tools needed by the plugin when enabled.
haskell_doc
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"],
)
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_doc")
haskell_doc(
# A unique name for this target.
name = "",
)
name
A unique name for this target.
deps
List of Haskell libraries to generate documentation for.
index_transitive_deps
Whether to include documentation of transitive dependencies in index.
haskell_import
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.
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_import")
haskell_import(
# A unique name for this target.
name = "",
)
name
A unique name for this target.
deps
haddock_html
haddock_interfaces
hdrs
id
includes
linkopts
shared_libraries
static_libraries
static_profiling_libraries
version
haskell_repl
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"
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_repl")
haskell_repl(
# A unique name for this target.
name = "",
)
name
A unique name for this target.
collect_data
Whether to collect the data runfiles from the dependencies in srcs, data and deps attributes.
data
See Bazel documentation. Only available when collect_data = True
.
deps
List of Haskell targets to load into the REPL
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.
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.
hie_bios_path_prefix
Path prefix for hie-bios paths. The elements of the list are joined together to build the path. See IDE support.
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.
haskell_toolchain_library
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",
],
)
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_toolchain_library")
haskell_toolchain_library(
# A unique name for this target.
name = "",
)
name
A unique name for this target.
package
The name of a GHC package not built by Bazel. Defaults to the name of the rule.
Macros and Functions
haskell_binary
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"]
)
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_binary")
haskell_binary(
# A unique name for this rule.
name = "",
)
name
A unique name for this rule.
src_strip_prefix
DEPRECATED. Attribute has no effect.
srcs
Haskell source files. File names must match module names, see above.
extra_srcs
Extra (non-Haskell) source files that will be needed at compile time (e.g. by Template Haskell).
deps
List of other Haskell libraries to be linked to this target.
narrowed_deps
Like deps, but only for dependencies using the modules attribute. These dependencies are only used if this library uses the modules attribute and the haskell_module rules depend on modules provided by these dependencies. Note: This attribute is experimental and not ready for production, yet.
data
See Bazel documentation.,
compiler_flags
DEPRECATED. Use new name ghcopts.
ghcopts
Flags to pass to Haskell compiler. Subject to Make variable substitution.
repl_ghci_args
Arbitrary extra arguments to pass to GHCi. This extends ghcopts
and repl_ghci_args
from the toolchain. Subject to Make variable substitution.,
runcompile_flags
Arbitrary extra arguments to pass to runghc. This extends ghcopts
and repl_ghci_args
from the toolchain. Subject to Make variable substitution.
plugins
Compiler plugins to use during compilation. Every module is compiled with -fplugin=...
.
non_default_plugins
Like plugins
but doesn't pass -fplugin=...
to modules by default.
tools
Extra tools needed at compile-time, like preprocessors.
worker
Experimental. Worker binary employed by Bazel's persistent worker mode. See use-cases documentation.
linkstatic
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
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
The source file that defines the Main
module or the module containing main_function
.
version
Executable version. If this is specified, CPP version macros will be generated for this build.
kwargs
Common rule attributes. See Bazel documentation.
haskell_library
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",
},
)
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_library")
haskell_library(
# A unique name for this rule.
name = "",
)
name
A unique name for this rule.
src_strip_prefix
DEPRECATED. Attribute has no effect.
srcs
Haskell source files. File names must match module names, see above.
extra_srcs
Extra (non-Haskell) source files that will be needed at compile time (e.g. by Template Haskell).
deps
List of other Haskell libraries to be linked to this target.
narrowed_deps
Like deps, but only for dependencies using the modules attribute. These dependencies are only used if this library uses the modules attribute and the haskell_module rules depend on modules provided by these dependencies. Note: This attribute is experimental and not ready for production, yet.
modules
List of extra haskell_module() dependencies to be linked into this library. Note: This attribute is experimental and not ready for production, yet.
data
See Bazel documentation.,
compiler_flags
DEPRECATED. Use new name ghcopts.
ghcopts
Flags to pass to Haskell compiler. Subject to Make variable substitution.
repl_ghci_args
Arbitrary extra arguments to pass to GHCi. This extends ghcopts
and repl_ghci_args
from the toolchain. Subject to Make variable substitution.,
runcompile_flags
Arbitrary extra arguments to pass to runghc. This extends ghcopts
and repl_ghci_args
from the toolchain. Subject to Make variable substitution.
plugins
Compiler plugins to use during compilation. Every module is compiled with -fplugin=...
.
non_default_plugins
Like plugins
but doesn't pass -fplugin=...
to modules by default.
tools
Extra tools needed at compile-time, like preprocessors.
worker
Experimental. Worker binary employed by Bazel's persistent worker mode. See use-cases documentation.
hidden_modules
Modules that should be unavailable for import by dependencies.
reexported_modules
A dictionary mapping dependencies to module reexports that should be available for import by dependencies.
exports
A list of other haskell libraries that will be transparently added as a dependency to every downstream rule
linkstatic
Create a static library, not both a static and a shared library.
package_name
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
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
Common rule attributes. See Bazel documentation.
haskell_register_toolchains
Register GHC binary distributions for all platforms as toolchains.
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_register_toolchains")
haskell_register_toolchains(
)
kwargs
haskell_test
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
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.
Additionally, it accepts all common bazel test rule fields. This allows you to influence things like timeout and resource allocation for the test.
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_test")
haskell_test(
# A unique name for this rule.
name = "",
)
name
A unique name for this rule.
src_strip_prefix
DEPRECATED. Attribute has no effect.
srcs
Haskell source files. File names must match module names, see above.
extra_srcs
Extra (non-Haskell) source files that will be needed at compile time (e.g. by Template Haskell).
deps
List of other Haskell libraries to be linked to this target.
narrowed_deps
Like deps, but only for dependencies using the modules attribute. These dependencies are only used if this library uses the modules attribute and the haskell_module rules depend on modules provided by these dependencies. Note: This attribute is experimental and not ready for production, yet.
data
See Bazel documentation.,
compiler_flags
DEPRECATED. Use new name ghcopts.
ghcopts
Flags to pass to Haskell compiler. Subject to Make variable substitution.
repl_ghci_args
Arbitrary extra arguments to pass to GHCi. This extends ghcopts
and repl_ghci_args
from the toolchain. Subject to Make variable substitution.,
runcompile_flags
Arbitrary extra arguments to pass to runghc. This extends ghcopts
and repl_ghci_args
from the toolchain. Subject to Make variable substitution.
plugins
Compiler plugins to use during compilation. Every module is compiled with -fplugin=...
.
non_default_plugins
Like plugins
but doesn't pass -fplugin=...
to modules by default.
tools
Extra tools needed at compile-time, like preprocessors.
worker
Experimental. Worker binary employed by Bazel's persistent worker mode. See use-cases documentation.
linkstatic
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
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
The source file that defines the Main
module or the module containing main_function
.
version
Executable version. If this is specified, CPP version macros will be generated for this build.
expected_covered_expressions_percentage
The expected percentage of expressions covered by testing.
expected_uncovered_expression_count
The expected number of expressions which are not covered by testing.
strict_coverage_analysis
Requires that the coverage metric is matched exactly, even doing better than expected is not allowed.
coverage_report_format
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
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
Common rule attributes. See Bazel documentation.
haskell_toolchain
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")
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "haskell_toolchain")
haskell_toolchain(
# A unique name for this toolchain.
name = "",
# Version of your GHC compiler
version = None,
# Whether GHC was linked with a static runtime.
static_runtime = None,
# Whether GHC should build fully-statically-linked binaries.
fully_static_link = None,
# GHC and executables that come with it
tools = None,
# The set of libraries that come with GHC
libraries = None,
)
name
A unique name for this toolchain.
version
Version of your GHC compiler. It has to match the version reported by the GHC used by bazel.
static_runtime
Whether GHC was linked with a static runtime.
fully_static_link
Whether GHC should build fully-statically-linked binaries.
tools
GHC and executables that come with it. First item takes precedence.
libraries
The set of libraries that come with GHC. Requires haskell_import targets.
asterius_binaries
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.
compiler_flags
DEPRECATED. Use new name ghcopts.
ghcopts
A collection of flags that will be passed to GHC on every invocation.
repl_ghci_args
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
A collection of flags that will be passed to haddock.
cabalopts
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
Label pointing to the locale archive file to use.
Linux-specific and mostly useful on NixOS.
kwargs
Common rule attributes. See Bazel documentation.
make_repl_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.
Example usage (generated)
load("@rules_haskell//haskell:defs.bzl", "make_repl_kwargs")
make_repl_kwargs(
args_list = None,
kwargs = None,
)
args_list
kwargs
Aspects
haskell_doc_aspect
Propagates along attributes named:deps,exports
name
A unique name for this target.
haskell_repl_aspect
Haskell REPL aspect.
Used to implement the haskell_repl rule. Does not generate an executable REPL by itself.
Propagates along attributes named:deps
name
A unique name for this target.