haskell / haskell/cabal

documentation: True runs Haddock for inferred multi-repl targets

Open Beginner friendly
#12,242 5 comments 1 reaction 0 assignees View on GitHub
attention: pr-welcome cabal-install: cmd/repl type: bug
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

**Describe the bug**

When `documentation: True` is enabled, `cabal repl --enable-multi-repl` can run Haddock for a component that was added to the multi-repl session by dependency-closure calculation. That component is configured as `BuildInplaceOnly InMemory`, so one of its promised in-memory dependencies is not present in the installed package index used by Haddock. Haddock then fails with `Cabal-4569`.

This is similar to #10166, which was closed by #10248. That pull request fixed the package version passed through `--promised-dependency`. The reproduction below still fails with the fix from #10248 present, including on the current `master`, because the inferred multi-repl target retains `elabBuildHaddocks = True`.

`haddock-internal` is not required to reproduce the problem.

**To reproduce**

Starting from Cabal `master` at `a21f3544700afb25529db8b825ad25a05e7a145c`, add `documentation: True` to the existing multi-repl closure test project:

```diff
diff --git a/cabal-testsuite/PackageTests/MultiRepl/EnabledClosure/cabal.project b/cabal-testsuite/PackageTests/MultiRepl/EnabledClosure/cabal.project
@@
packages: pkg-a/*.cabal
packages: pkg-b/*.cabal
packages: pkg-c/*.cabal
+documentation: True
```

Then run the existing test, or run the equivalent multi-repl command against `pkg-a` and `pkg-c`:

```console
cabal repl --enable-multi-repl pkg-c pkg-a
```

`pkg-b` is added to the session to satisfy the multi-repl closure property. The command then attempts to build its documentation and fails:

```text
Running Haddock on library for pkg-b-0...
Error: [Cabal-4569]
internal error when calculating transitive package dependencies.
Debug info: []
```

As a control, the same multi-repl command succeeds when documentation is disabled.

**Expected behavior**

Every component configured as `BuildInplaceOnly InMemory` for a multi-repl session should have `elabBuildHaddocks = False`. The command should load `pkg-a`, inferred `pkg-b`, and `pkg-c` into GHCi without running Haddock for any of those interactive components.

The explicit REPL-target path already clears `elabBuildHaddocks` in `setRootTargets`. The dependency-closure path in `add_repl_target` sets `elabReplTarget` and `elabBuildStyle`, but does not clear `elabBuildHaddocks`.

A one-field change fixes the reproduction:

```haskell
{ elabReplTarget = maybeToList (ComponentTarget <$> elabComponentName ecp <*> pure WholeComponent)
, elabBuildHaddocks = False
, elabBuildStyle = BuildInplaceOnly InMemory
}
```

I also tested a regression change that enables `documentation: True` in `PackageTests/MultiRepl/EnabledClosure` and asserts that Haddock is not run for inferred `pkg-b`. The test fails with `Cabal-4569` before the one-field change and passes after it.

**Why this matters for HLS**

Haskell Language Server uses Cabal multi-repl when the editor enables both whole-project checking and multiple-component session loading. A project that wants all three of the following currently cannot use them together when its component graph triggers the closure path:

```text
documentation: True
haskell.checkProject: true
haskell.sessionLoading: multipleComponents
```

Disabling documentation avoids the Cabal failure but also prevents the normal project build from generating Haddock documentation.

**System information**

- macOS 26.6.1 on Apple Silicon
- GHC 9.12.2
- Reproduced with cabal-install 3.16.1.0 and Cabal 3.16.1.0
- Reproduced with Cabal and cabal-install 3.19.0.0 development versions from `master` at `a21f3544700afb25529db8b825ad25a05e7a145c`

Contributor guide

Open the contributing guide

Research direction

Start with add_repl_target and compare its elaboration with setRootTargets, which already handles explicit REPL targets. Reproduce the failure by enabling documentation: True in cabal-testsuite/PackageTests/MultiRepl/EnabledClosure/cabal.project and running the existing multi-repl test or cabal repl --enable-multi-repl pkg-c pkg-a. Done means the inferred pkg-b loads without running Haddock, and the regression test passes.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell
Domain
build-system, cli, testing
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.