rules_haskell

The rules_haskell repository provides several example workspaces to demonstrate different Haskell build scenarios with Bazel:

• vector: Demonstrates how to build a Hackage package (specifically vector) and its transitive dependencies (primitive, transformers) without using Cabal.
• cat_hs: A non-trivial application example featuring multiple third-party Hackage dependencies, C library dependencies, and a project structure split into multiple libraries and a binary. This example uses a rule that wraps Cabal to manage Hackage dependencies.
• rts: Demonstrates how to handle foreign exports and how to link against GHC's Runtime System (RTS) library (e.g., libHSrts.so).

This Bazel-compatible version of ghc-paths resolves GHC paths using the following priority:

1. Environment Variables: It checks for the following variables:
   • RULES_HASKELL_GHC_PATH
   • RULES_HASKELL_GHC_PKG_PATH
   • RULES_HASKELL_LIBDIR_PATH
   • RULES_HASKELL_DOCDIR_PATH
2. Bazel Runfiles: If the environment variables are empty, it queries the Bazel runfiles tree using @rules_haskell//tools/runfiles.

Note on Implementation: The paths are exposed as pure String constants using unsafePerformIO. The values are memoized upon the first lookup and will not change even if the environment changes later during the process lifetime.

By default, Bazel targets are only visible to other targets within the same BUILD.bazel file (the same package). To allow a target in one package to be used by a target in a different package, you must use the visibility attribute.

Example: Making a library visible to a specific package

In lib/BUILD.bazel:

haskell_library(
    name = "booleans",
    srcs = ["Bool.hs"],
    visibility = ["//main:__pkg__"],
)

In main/BUILD.bazel, you can then reference it using its full label:

haskell_binary(
    name = "demorgan",
    srcs = ["Main.hs"],
    deps = ["//lib:booleans"],
)

The Bazel.Runfiles library provides utilities to locate files within a Bazel runfiles tree. This is essential for tests or binaries that need to access data files or executables bundled with the Bazel target. You first create a runfiles handle using Runfiles.create, and then use Runfiles.rlocation to resolve the path to a specific file relative to the workspace root.

import qualified Bazel.Runfiles as Runfiles

main :: IO ()
main = do
    r <- Runfiles.create
    -- Resolve path using rlocation
    path <- Runfiles.rlocation r "rules_haskell/tools/runfiles/test-data.txt"
    content <- readFile path
    putStrLn content

In BUILD.bazel files and when using the Bazel CLI, you reference targets using labels. The syntax depends on the scope of the target you are referencing:

• Full Label: //path/to/package:target-name (Used to reference a target in a different package).
• Package-relative Label: //:target-name (Used to reference a target within the same package, skipping the path).
• Local Label: :target-name (Used to reference a target within the same BUILD.bazel file, skipping the workspace root identifier //).

For rule targets, path/to/package is the directory containing the BUILD.bazel file, and target-name is the value of the name attribute. For file targets, path/to/package is the package root, and target-name is the name of the file including its path.

Choosing a build system depends on your project's scale, language composition, and distribution requirements. Use the following rules of thumb to decide:

Use Cabal or Stack if:

• Your project is an independently publishable single library or a small set of libraries.
• Your project is open source and has minimal static assets (suitable for Hackage).
• Your project is almost entirely Haskell (with perhaps minimal C).
• Your project relies heavily on Hackage packages but has few system-level dependencies (e.g., zlib, libpng).

Use Bazel if:

• Your project cannot be hosted on Hackage (e.g., games with large assets or proprietary code).
• You are managing a very large codebase within a single repository (monorepo).
• Your project is polyglot, involving two or more languages (e.g., Haskell/PureScript, Haskell/Java, or Haskell/C++/FORTRAN).

To quickly bootstrap a new Haskell project, use the provided installation script. This will generate the necessary WORKSPACE and BUILD files.

Standard Setup

Run the following command in a fresh directory:

curl https://haskell.build/start | sh

Bzlmod Setup

If you want to start a project using Bazel's Bzlmod system, run:

sh <(curl https://haskell.build/start) --with-bzlmod=true

Nixpkgs Setup

If you are on NixOS or want to use Nixpkgs to provision your GHC toolchain and fetch Hackage packages, use the --use-nix flag:

sh <(curl https://haskell.build/start) --use-nix

Once the files are generated, you can build and test your project using standard Bazel commands:

bazel build //...
bazel test //...

By default, stack_snapshot invokes stack on every fetch, which can be slow, require network access, and impact reproducibility. To enable pinning, which uses a lock file and allows for Bazel repository caching, follow these steps:

1. Generate a lock file: bazel run @stackage-unpinned//:pin.
2. Update your stack_snapshot definition to include the stack_snapshot_json attribute pointing to the generated file.

stack_snapshot(
    ...
    stack_snapshot_json = "//:stackage_snapshot.json",
)