Commit 7861a225 authored by Ben Gamari's avatar Ben Gamari Committed by Ben Gamari

Add a note describing the protocol for adding a language extension

Reviewers: hvr, thomie, austin

Reviewed By: austin

Subscribers: duncan

Differential Revision: https://phabricator.haskell.org/D1741

GHC Trac Issues: #8176, #4437
parent 89ba83d9
......@@ -233,6 +233,59 @@ import qualified GHC.LanguageExtensions as LangExt
-- have effect, and annotate it accordingly. For Flags use defFlag, defGhcFlag,
-- defGhciFlag, and for FlagSpec use flagSpec or flagGhciSpec.
-- Note [Adding a language extension]
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--
-- There are a few steps to adding (or removing) a language extension,
--
-- * Adding the extension to GHC.LanguageExtensions
--
-- The LangExt type in libraries/ghc-boot/GHC/LanguageExtensions.hs is
-- the canonical list of language extensions known by GHC.
--
-- * Adding a flag to DynFlags.xFlags
--
-- This is fairly self-explanatory. The name should be concise, memorable,
-- and consistent with any previous implementations of the similar idea in
-- other Haskell compilers.
--
-- * Adding the flag to the documentation
--
-- This is the same as any other flag. See
-- Note [Updating flag description in the User's Guide]
--
-- * Adding the flag to Cabal
--
-- The Cabal library has its own list of all language extensions supported
-- by all major compilers. This is the list that user code being uploaded
-- to Hackage is checked against to ensure language extension validity.
-- Consequently, it is very important that this list remains up-to-date.
--
-- To this end, there is a testsuite test (testsuite/tests/driver/T4437.hs)
-- whose job it is to ensure these GHC's extensions are consistent with
-- Cabal.
--
-- The recommended workflow is,
--
-- 1. Temporarily add your new language extension to the
-- expectedGhcOnlyExtensions list in T4437 to ensure the test doesn't
-- break while Cabal is updated.
--
-- 2. After your GHC change is accepted, submit a Cabal pull request adding
-- your new extension to Cabal's list (found in
-- Cabal/Language/Haskell/Extension.hs).
--
-- 3. After your Cabal change is accepted, let the GHC developers know so
-- they can update the Cabal submodule and remove the extensions from
-- expectedGhcOnlyExtensions.
--
-- * Adding the flag to the GHC Wiki
--
-- There is a change log tracking language extension additions and removals
-- on the GHC wiki: https://ghc.haskell.org/trac/ghc/wiki/LanguagePragmaHistory
--
-- See Trac #4437 and #8176.
-- -----------------------------------------------------------------------------
-- DynFlags
......@@ -3103,6 +3156,7 @@ xFlags :: [FlagSpec LangExt.Extension]
xFlags = [
-- See Note [Updating flag description in the User's Guide]
-- See Note [Supporting CLI completion]
-- See Note [Adding a language extension]
-- Please keep the list of flags below sorted alphabetically
flagSpec "AllowAmbiguousTypes" LangExt.AllowAmbiguousTypes,
flagSpec "AlternativeLayoutRule" LangExt.AlternativeLayoutRule,
......
-- | A test for ensuring that GHC's supporting language extensions remains in
-- sync with Cabal's own extension list.
--
-- If you have ended up here due to a test failure, please see
-- Note [Adding a language extension] in compiler/main/DynFlags.hs.
module Main (main) where
......@@ -29,6 +34,7 @@ check title expected got
showProblems "Unexpected flags" unexpected
showProblems "Missing flags" missing
-- See Note [Adding a language extension] in compiler/main/DynFlags.hs.
expectedGhcOnlyExtensions :: [String]
expectedGhcOnlyExtensions = ["RelaxedLayout",
"AlternativeLayoutRule",
......
......@@ -352,6 +352,11 @@ test('withRtsOpts', [ extra_clean(['withRtsOpts', 'withRtsOpts.exe',
test('T3389', normal, compile_and_run, [''])
test('T3364', normalise_fun(normalise_errmsg), run_command,
['$MAKE -s --no-print-directory T3364'])
# T4437: A test to ensure that Cabal's language extension list remains
# consistent with those known by GHC.
#
# See Note [Adding a language extension] in DynFlags.hs for details.
test('T4437', only_ways(['normal']), compile_and_run, ['-package ghc'])
test('werror', normal, compile_fail, [''])
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment