Remove GHCJS

[philderbeast]

Fixes #11609, removing GHCJS.

I'll squash commits before applying the merge label if this pull request is approved.

Important

The removed exceptions and ghcjsVersionImplInfo were exported from Cabal,
so this needs a major version bump.

GHCJS was a standalone compiler that predates the JavaScript backend of GHC, which shipped with GHC 9.6. Its repository has been dormant for years and Cabal's Distribution.Simple.GHCJS module was a stranded, untested duplicate of the GHC module.

What is removed

• The Distribution.Simple.GHCJS module and its PackageTests/GHCJS test.
• The --ghcjs flag and the ghcjs and ghcjs-pkg builtin programs, with the ghcjs-* lines they contributed to the generated config file and the program lists in the help text and the manual.
• ghcjsVersionImplInfo and the GHCJS branch of getImplInfo.
• The VersionMismatchJS (9001) and VersionMismatchGHCJS (4001) exceptions. Their codes are marked retired.
• Every GHCJS -> case left in Cabal and cabal-install. None were reachable once configure could no longer produce the flavour.

Selecting the flavour, with compiler: ghcjs in a project file or on the Setup configure command line, now fails with a dedicated error:

Error: [Cabal-4002]
GHCJS is no longer supported. Use the JavaScript backend of GHC instead,
for example with --with-compiler=javascript-unknown-ghcjs-ghc.

What is kept

• In Cabal-syntax, the GHCJS constructor of CompilerFlavor, PerCompilerFlavor and the ghcjs-options, ghcjs-prof-options, ghcjs-shared-options and ghcjs-prof-shared-options fields. Packages on Hackage use these fields and must keep parsing. The manual marks them deprecated and ignored.
• OS Ghcjs and the ghcjs_HOST_OS CPP guards. These describe the javascript-unknown-ghcjs target that the JavaScript backend of GHC still uses, not the GHCJS compiler.

Deprecation process

The deprecation process that asks for a four release window is skipped in favour of a faster removal I proposed on discourse. So far, we've received no objections.

QA Notes

• cabal build in a project with compiler: ghcjs in cabal.project should fail with [Cabal-4002] and the message above.
• cabal build --ghcjs should be rejected as an unrecognised option.
• cabal build --help should no longer list --ghcjs, and the --with-PROG program list should no longer include ghcjs or ghcjs-pkg.
• A fresh ~/.config/cabal/config should have no ghcjs-location, ghcjs-pkg-location, ghcjs-options or ghcjs-pkg-options lines.
• A package with ghcjs-options: -foo should still configure and build with GHC, with no warning and no effect.

Tests

• PackageTests/GHCJS/NotSupported checks the new error.
• The IntegrationTests2 config test drops its ghcjs-* assertions and passes.
• The project-config-shared parser test uses uhc instead of ghcjs as its sample flavour.
• The help text under doc/ was regenerated with make -B -C doc cmd-help and make users-guide builds the manual cleanly.

---

Template Α: This PR modifies behaviour or interface

Include the following checklist in your PR:

• Patches conform to the coding conventions.
• Any changes that could be relevant to users have been recorded in the changelog.
  • Is the change significant? If so, remember to add significance: significant in the changelog file.
• The documentation has been updated, if necessary.
• Manual QA notes have been included.
• Tests have been added. (Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!)

[zlonast]

Thank you very much for the work done!

[andreabedini]

IIUC project fields like ghcjs-options and the like will now cause a unknown field warning, am I correct? It would be better to say "deprecated". The changelog say they are ignored, it might be worth being more specific.

[philderbeast]

@andreabedini, I've updated the changelog to be more explicit. The ghcjs-options field in a package is ignored but like other unknown PROG-options and PROG-location, the ghcjs-* and ghcjs-pkg-* ones in a project will get a warning. I don't think the effort is worth it to issue a deprecated message for these special cases in the project.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-14 14:50 UTC · Rule: default · triggered by rule Put pull requests in the rebase+merge queue
• ✅ Checks passed · on draft merge queue: checking #12396 on master (59f7356) #12458
• ✅ Merged — 2026-10-14 16:57 UTC · at eb2b4de5fb2315c8b395e3d3cd14578a82a9b135 · merge

This pull request spent 2 hours 6 minutes 36 seconds in the queue, including 1 hour 54 minutes 53 seconds running CI.

Required conditions to merge

• #review-threads-unresolved = 0 [🛡 GitHub branch protection]
  • Remove GHCJS #12396
• github-review-approved [🛡 GitHub branch protection]
  • Remove GHCJS #12396
• any of [🛡 GitHub branch protection]:
  • check-success = Doctest Cabal
  • check-neutral = Doctest Cabal
  • check-skipped = Doctest Cabal
• any of [🛡 GitHub branch protection]:
  • check-success = Meta checks
  • check-neutral = Meta checks
  • check-skipped = Meta checks
• any of [🛡 GitHub branch protection]:
  • check-success = docs/readthedocs.org:cabal
  • check-neutral = docs/readthedocs.org:cabal
  • check-skipped = docs/readthedocs.org:cabal
• any of [🛡 GitHub branch protection]:
  • check-success = Validate post job
  • check-neutral = Validate post job
  • check-skipped = Validate post job
• any of [🛡 GitHub branch protection]:
  • check-success = fourmolu
  • check-neutral = fourmolu
  • check-skipped = fourmolu
• any of [🛡 GitHub branch protection]:
  • check-success = hlint
  • check-neutral = hlint
  • check-skipped = hlint
• any of [🛡 GitHub branch protection]:
  • check-success = Bootstrap post job
  • check-neutral = Bootstrap post job
  • check-skipped = Bootstrap post job
• any of [🛡 GitHub branch protection]:
  • check-success = whitespace
  • check-neutral = whitespace
  • check-skipped = whitespace
• any of [🛡 GitHub branch protection]:
  • check-success = Check sdist post job
  • check-neutral = Check sdist post job
  • check-skipped = Check sdist post job
• any of [🛡 GitHub branch protection]:
  • check-success = Changelogs
  • check-neutral = Changelogs
  • check-skipped = Changelogs