Skip to content

[2.x] fix: Filter semanticdb options from scaladoc invocations#8760

Open
0xRozier wants to merge 3 commits intosbt:developfrom
0xRozier:fix/issue-8740-scaladoc-semanticdb-options-filtering
Open

[2.x] fix: Filter semanticdb options from scaladoc invocations#8760
0xRozier wants to merge 3 commits intosbt:developfrom
0xRozier:fix/issue-8740-scaladoc-semanticdb-options-filtering

Conversation

@0xRozier
Copy link
Copy Markdown

@0xRozier 0xRozier commented Feb 17, 2026 •
edited
Loading

Problem

When semanticdbEnabled := true is set on Scala 2.x projects, the doc task fails because semanticdb-related compiler options (-Xplugin:...semanticdb..., -P:semanticdb:targetroot:*, -Yrangepos) leak into doc / scalacOptions. Scaladoc does not support these options, causing:

[error] bad option: -P:semanticdb:targetroot:/path/to/target/meta
[error] (Compile / doc) Scaladoc generation failed

Fixes #8740.

Solution

Added a doc / scalacOptions setting in SemanticdbPlugin.configurationSettings that, when semanticdbEnabled is true, filters out:

  1. All options from semanticdbOptions (-Yrangepos, -P:semanticdb:targetroot:* for Scala 2.x; -Xsemanticdb, -semanticdb-target for Scala 3.x)
  2. Any -Xplugin: flag containing semanticdb (the compiler plugin JAR)

This is placed in SemanticdbPlugin because it introduces these options, so it should be responsible for scoping them away from doc.

Tests

New scripted test project/semanticdb-doc that:

  • Runs doc on both Scala 2.12 and Scala 3.6 with semanticdbEnabled := true
  • Verifies that compile still generates .semanticdb files

AI Disclosure

This PR was created with assistance from Claude Opus 4.6 (AI). All code changes have been reviewed and verified for correctness.

Generated-by: Claude Opus 4.6

0xRozier and others added 2 commits February 17, 2026 22:12
@0xRozier @claude
[2.x] fix: Filter semanticdb options from scaladoc invocations
793d8a2 
**Problem**
When `semanticdbEnabled := true` is set on Scala 2.x projects, the `doc`
task fails because semanticdb-related compiler options (-Xplugin for
semanticdb, -P:semanticdb:targetroot, -Yrangepos) are passed to scaladoc,
which does not support them. Fixes sbt#8740.

**Solution**
Add a `doc / scalacOptions` setting in SemanticdbPlugin's configuration
settings that filters out semanticdb options from the doc task scope.
This removes both the options from `semanticdbOptions` (like -Yrangepos,
-P:semanticdb:targetroot for Scala 2.x, and -Xsemanticdb,
-semanticdb-target for Scala 3.x) and the -Xplugin flag for the
semanticdb compiler plugin. The filtering only applies when
`semanticdbEnabled` is true.

Generated-by: Claude Opus 4.6

Co-Authored-By: Claude Opus 4.6 <[email protected]>
@0xRozier @claude
[2.x] style: Fix scalafmt formatting in SemanticdbPlugin
fc825f7 
Generated-by: Claude Opus 4.6

Co-Authored-By: Claude Opus 4.6 <[email protected]>
@0xRozier 0xRozier force-pushed the fix/issue-8740-scaladoc-semanticdb-options-filtering branch from 4716e36 to fc825f7 Compare February 17, 2026 21:47
eed3si9n
eed3si9n requested changes Feb 18, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@eed3si9n eed3si9n left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. While this approach might work specifically for semanticdb plugin my guess is that it would still be broken for all other compiler plugins until we fix the root cause, which should be fixed in Zinc AnalyzingCompiler similar to sbt/zinc#1545.

@0xRozier 0xRozier mentioned this pull request Feb 18, 2026
Open
2 tasks
@0xRozier
Copy link
Copy Markdown
Author

0xRozier commented Feb 18, 2026

Thanks for the feedback @eed3si9n! You're right that the fix should be in Zinc to handle all compiler plugins generically, not just semanticdb.

I've created a PR against Zinc that filters compiler plugin options (-Xplugin:, -Xplugin-require:, -P:) in AnalyzingCompiler.doc() before passing them to the Scaladoc bridge: sbt/zinc#1640

I've also reverted the semanticdb-specific filtering from SemanticdbPlugin in this branch, since the fix now belongs in Zinc. The scripted test (semanticdb-doc) is kept as it will validate the fix once the new Zinc version is picked up.

@0xRozier 0xRozier force-pushed the fix/issue-8740-scaladoc-semanticdb-options-filtering branch from d8d3ca2 to fc825f7 Compare February 18, 2026 10:01
@0xRozier
Copy link
Copy Markdown
Author

0xRozier commented Feb 18, 2026

Update: I've restored the semanticdb-specific filtering in SemanticdbPlugin as a short-term workaround while the generic Zinc fix (sbt/zinc#1640) goes through review.

Once the Zinc fix is merged and the dependency is bumped in sbt, this workaround can be removed since AnalyzingCompiler.doc() will filter all compiler plugin options generically.

@0xRozier 0xRozier requested a review from eed3si9n February 18, 2026 15:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@eed3si9n eed3si9n Awaiting requested review from eed3si9n

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[2.x] scaladoc failure when semanticdbEnabled is enabled on scala 2.x projects

2 participants

@0xRozier @eed3si9n