[Git][ghc/ghc][wip/T19629] 3 commits: primops: Ensure that deprecations are properly tracked
Sylvain Henry (@hsyl20)
gitlab at gitlab.haskell.org
Fri May 17 12:01:20 UTC 2024
Sylvain Henry pushed to branch wip/T19629 at Glasgow Haskell Compiler / GHC
Commits:
5db20656 by Ben Gamari at 2024-05-17T14:00:59+02:00
primops: Ensure that deprecations are properly tracked
We previously failed to insert DEPRECATION pragmas into GHC.Prim's
ModIface, meaning that they would appear in the Haddock documentation
but not issue warnings. Fix this.
Fixes #19629.
Co-authored-by: Sylvain Henry <sylvain at haskus.fr>
- - - - -
0598c70c by Ben Gamari at 2024-05-17T14:00:59+02:00
primops: Undeprecate addr2Int# and int2Addr#
addr2Int# and int2Addr# were marked as deprecated with the introduction
of the OCaml code generator (1dfaee318171836b32f6b33a14231c69adfdef2f)
due to its use of tagged integers. However, this backend has long
vanished and `base` has all along been using `addr2Int#` in the Show
instance for Ptr.
While it's unlikely that we will have another backend which has tagged
integers, we may indeed support platforms which have tagged pointers.
Consequently we undeprecate the operations but warn the user that the
operations may not be portable.
- - - - -
a2860763 by Sylvain Henry at 2024-05-17T14:00:59+02:00
primops: Undeprecate par#
par# is still used in base and it's not clear how to replace it with
spark# (see #24825)
- - - - -
11 changed files:
- compiler/GHC/Builtin/PrimOps.hs
- compiler/GHC/Builtin/Utils.hs
- compiler/GHC/Builtin/primops.txt.pp
- compiler/GHC/Iface/Load.hs
- compiler/GHC/Iface/Make.hs
- + compiler/GHC/Iface/Warnings.hs
- compiler/ghc.cabal.in
- hadrian/src/Rules/Generate.hs
- hadrian/src/Rules/Lint.hs
- hadrian/src/Settings/Builders/GenPrimopCode.hs
- utils/genprimopcode/Main.hs
Changes:
=====================================
compiler/GHC/Builtin/PrimOps.hs
=====================================
@@ -18,7 +18,7 @@ module GHC.Builtin.PrimOps (
primOpOutOfLine, primOpCodeSize,
primOpOkForSpeculation, primOpOkToDiscard,
- primOpIsWorkFree, primOpIsCheap, primOpFixity, primOpDocs,
+ primOpIsWorkFree, primOpIsCheap, primOpFixity, primOpDocs, primOpDeprecations,
primOpIsDiv, primOpIsReallyInline,
PrimOpEffect(..), primOpEffect,
@@ -163,12 +163,15 @@ primOpFixity :: PrimOp -> Maybe Fixity
* *
************************************************************************
-See Note [GHC.Prim Docs]
+See Note [GHC.Prim Docs] in GHC.Builtin.Utils
-}
primOpDocs :: [(FastString, String)]
#include "primop-docs.hs-incl"
+primOpDeprecations :: [(OccName, FastString)]
+#include "primop-deprecations.hs-incl"
+
{-
************************************************************************
* *
=====================================
compiler/GHC/Builtin/Utils.hs
=====================================
@@ -34,6 +34,8 @@ module GHC.Builtin.Utils (
ghcPrimExports,
ghcPrimDeclDocs,
+ ghcPrimWarns,
+ ghcPrimFixities,
-- * Random other things
maybeCharLikeCon, maybeIntLikeCon,
@@ -61,9 +63,11 @@ import GHC.Core.TyCon
import GHC.Types.Avail
import GHC.Types.Id
+import GHC.Types.Fixity
import GHC.Types.Name
import GHC.Types.Name.Env
import GHC.Types.Id.Make
+import GHC.Types.SourceText
import GHC.Types.Unique.FM
import GHC.Types.Unique.Map
import GHC.Types.TyThing
@@ -73,8 +77,10 @@ import GHC.Utils.Outputable
import GHC.Utils.Misc as Utils
import GHC.Utils.Panic
import GHC.Utils.Constants (debugIsOn)
+import GHC.Parser.Annotation
import GHC.Hs.Doc
import GHC.Unit.Module.ModIface (IfaceExport)
+import GHC.Unit.Module.Warnings
import GHC.Data.List.SetOps
@@ -256,6 +262,54 @@ ghcPrimNames
map tyConName exposedPrimTyCons
]
+-- See Note [GHC.Prim deprecations] in genprimopcode's Main.hs
+ghcPrimWarns :: Warnings a
+ghcPrimWarns = WarnSome
+ -- declaration warnings
+ (map mk_decl_dep primOpDeprecations)
+ -- export warnings
+ []
+ where
+ mk_txt msg =
+ DeprecatedTxt NoSourceText [noLocA $ WithHsDocIdentifiers (StringLiteral NoSourceText msg Nothing) []]
+ mk_decl_dep (occ, msg) = (occ, mk_txt msg)
+
+ghcPrimFixities :: [(OccName,Fixity)]
+ghcPrimFixities = fixities
+ where
+ -- The fixity listed here for @`seq`@ should match
+ -- those in primops.txt.pp (from which Haddock docs are generated).
+ fixities = (getOccName seqId, Fixity NoSourceText 0 InfixR)
+ : mapMaybe mkFixity allThePrimOps
+ mkFixity op = (,) (primOpOcc op) <$> primOpFixity op
+
+{-
+Note [GHC.Prim Docs]
+~~~~~~~~~~~~~~~~~~~~
+For haddocks of GHC.Prim we generate a dummy haskell file (gen_hs_source) that
+contains the type signatures and the comments (but no implementations)
+specifically for consumption by haddock.
+
+GHCi's :doc command reads directly from ModIface's though, and GHC.Prim has a
+wired-in iface that has nothing to do with the above haskell file. The code
+below converts primops.txt into an intermediate form that would later be turned
+into a proper DeclDocMap.
+
+We output the docs as a list of pairs (name, docs). We use stringy names here
+because mapping names to "Name"s is difficult for things like primtypes and
+pseudoops.
+
+Note [GHC.Prim Deprecations]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Like Haddock documentation, we must record deprecation pragmas in two places:
+in the GHC.Prim source module consumed by Haddock, and in the
+declarations wired-in to GHC. To do the following we generate
+GHC.Builtin.PrimOps.primOpDeprecations, a list of (OccName, DeprecationMessage)
+pairs. We insert these deprecations into the mi_warns field of GHC.Prim's ModIface,
+as though they were written in a source module.
+-}
+
+
{-
************************************************************************
* *
=====================================
compiler/GHC/Builtin/primops.txt.pp
=====================================
@@ -74,7 +74,7 @@
-- 2. The dummy Prim.hs file, which is used for Haddock and
-- contains descriptions taken from primops.txt.pp.
-- All definitions are replaced by placeholders.
--- See Note [GHC.Prim Docs] in genprimopcode.
+-- See Note [GHC.Prim Docs] in GHC.Builtin.Utils.
--
-- 3. The module PrimopWrappers.hs, which wraps every call for GHCi;
-- see Note [Primop wrappers] in GHC.Builtin.Primops for details.
@@ -2312,13 +2312,13 @@ primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
{Return the remainder when the 'Addr#' arg, treated like an 'Int#',
is divided by the 'Int#' arg.}
primop AddrToIntOp "addr2Int#" GenPrimOp Addr# -> Int#
- {Coerce directly from address to int.}
+ {Coerce directly from address to int. Users are discouraged from using
+ this operation as it makes little sense on platforms with tagged pointers.}
with code_size = 0
- deprecated_msg = { This operation is strongly deprecated. }
primop IntToAddrOp "int2Addr#" GenPrimOp Int# -> Addr#
- {Coerce directly from int to address.}
+ {Coerce directly from int to address. Users are discouraged from using
+ this operation as it makes little sense on platforms with tagged pointers.}
with code_size = 0
- deprecated_msg = { This operation is strongly deprecated. }
primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Int#
primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Int#
@@ -3642,14 +3642,24 @@ primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
section "Parallelism"
------------------------------------------------------------------------
-primop ParOp "par#" GenPrimOp
- a -> Int#
+primop ParOp "par#" GenPrimOp a -> Int#
+ {Create a new spark evaluating the given argument.
+ The return value should always be 1.
+ Users are encouraged to use spark# instead.}
with
-- Note that Par is lazy to avoid that the sparked thing
-- gets evaluated strictly, which it should *not* be
effect = ReadWriteEffect
code_size = { primOpCodeSizeForeignCall }
- deprecated_msg = { Use 'spark#' instead }
+ -- `par#` was suppose to be deprecated in favor of `spark#` [1], however it
+ -- wasn't clear how to replace it with `spark#` [2] and `par#` is still used
+ -- to implement `GHC.Internal.Conc.Sync.par`. So we undeprecated it until
+ -- everything is sorted out (see #24825).
+ --
+ -- [1] https://gitlab.haskell.org/ghc/ghc/-/issues/15227#note_154293
+ -- [2] https://gitlab.haskell.org/ghc/ghc/-/merge_requests/5548#note_347791
+ --
+ -- deprecated_msg = { Use 'spark#' instead }
primop SparkOp "spark#" GenPrimOp
a -> State# s -> (# State# s, a #)
=====================================
compiler/GHC/Iface/Load.hs
=====================================
@@ -53,6 +53,7 @@ import GHC.Driver.DynFlags
import GHC.Driver.Hooks
import GHC.Driver.Plugins
+import GHC.Iface.Warnings
import GHC.Iface.Syntax
import GHC.Iface.Ext.Fields
import GHC.Iface.Binary
@@ -74,14 +75,12 @@ import GHC.Settings.Constants
import GHC.Builtin.Names
import GHC.Builtin.Utils
-import GHC.Builtin.PrimOps ( allThePrimOps, primOpFixity, primOpOcc )
import GHC.Core.Rules
import GHC.Core.TyCon
import GHC.Core.InstEnv
import GHC.Core.FamInstEnv
-import GHC.Types.Id.Make ( seqId )
import GHC.Types.Annotations
import GHC.Types.Name
import GHC.Types.Name.Cache
@@ -90,7 +89,6 @@ import GHC.Types.Avail
import GHC.Types.Fixity
import GHC.Types.Fixity.Env
import GHC.Types.SourceError
-import GHC.Types.SourceText
import GHC.Types.SourceFile
import GHC.Types.SafeHaskell
import GHC.Types.TypeEnv
@@ -101,6 +99,7 @@ import GHC.Types.PkgQual
import GHC.Unit.External
import GHC.Unit.Module
+import GHC.Unit.Module.Warnings
import GHC.Unit.Module.ModIface
import GHC.Unit.Module.Deps
import GHC.Unit.State
@@ -1021,19 +1020,18 @@ ghcPrimIface
= empty_iface {
mi_exports = ghcPrimExports,
mi_decls = [],
- mi_fixities = fixities,
- mi_final_exts = (mi_final_exts empty_iface){ mi_fix_fn = mkIfaceFixCache fixities },
- mi_docs = Just ghcPrimDeclDocs -- See Note [GHC.Prim Docs]
+ mi_fixities = ghcPrimFixities,
+ mi_docs = Just ghcPrimDeclDocs, -- See Note [GHC.Prim Docs] in GHC.Builtin.Utils
+ mi_warns = toIfaceWarnings ghcPrimWarns, -- See Note [GHC.Prim Deprecations] in GHC.Builtin.Utils
+ mi_final_exts = (mi_final_exts empty_iface)
+ { mi_decl_warn_fn = mkIfaceDeclWarnCache ghcPrimWarns
+ , mi_export_warn_fn = mkIfaceExportWarnCache ghcPrimWarns
+ , mi_fix_fn = mkIfaceFixCache ghcPrimFixities
+ }
}
where
empty_iface = emptyFullModIface gHC_PRIM
- -- The fixity listed here for @`seq`@ should match
- -- those in primops.txt.pp (from which Haddock docs are generated).
- fixities = (getOccName seqId, Fixity NoSourceText 0 InfixR)
- : mapMaybe mkFixity allThePrimOps
- mkFixity op = (,) (primOpOcc op) <$> primOpFixity op
-
{-
*********************************************************
* *
=====================================
compiler/GHC/Iface/Make.hs
=====================================
@@ -14,7 +14,6 @@ module GHC.Iface.Make
, mkFullIface
, mkIfaceTc
, mkIfaceExports
- , toIfaceWarningTxt
)
where
@@ -28,6 +27,7 @@ import GHC.StgToCmm.Types (CmmCgInfos (..))
import GHC.Tc.Utils.TcType
import GHC.Tc.Utils.Monad
+import GHC.Iface.Warnings
import GHC.Iface.Decl
import GHC.Iface.Syntax
import GHC.Iface.Recomp
@@ -67,8 +67,6 @@ import GHC.Types.SourceFile
import GHC.Types.TyThing
import GHC.Types.HpcInfo
import GHC.Types.CompleteMatch
-import GHC.Types.SourceText
-import GHC.Types.SrcLoc ( unLoc )
import GHC.Utils.Outputable
import GHC.Utils.Panic
@@ -401,23 +399,6 @@ ifaceRoughMatchTcs tcs = map do_rough tcs
do_rough (RM_KnownTc n) = Just (toIfaceTyCon_name n)
--------------------------
-toIfaceWarnings :: Warnings GhcRn -> IfaceWarnings
-toIfaceWarnings (WarnAll txt) = IfWarnAll (toIfaceWarningTxt txt)
-toIfaceWarnings (WarnSome vs ds) = IfWarnSome vs' ds'
- where
- vs' = [(occ, toIfaceWarningTxt txt) | (occ, txt) <- vs]
- ds' = [(occ, toIfaceWarningTxt txt) | (occ, txt) <- ds]
-
-toIfaceWarningTxt :: WarningTxt GhcRn -> IfaceWarningTxt
-toIfaceWarningTxt (WarningTxt mb_cat src strs) = IfWarningTxt (unLoc . iwc_wc . unLoc <$> mb_cat) src (map (toIfaceStringLiteralWithNames . unLoc) strs)
-toIfaceWarningTxt (DeprecatedTxt src strs) = IfDeprecatedTxt src (map (toIfaceStringLiteralWithNames . unLoc) strs)
-
-toIfaceStringLiteralWithNames :: WithHsDocIdentifiers StringLiteral GhcRn -> (IfaceStringLiteral, [IfExtName])
-toIfaceStringLiteralWithNames (WithHsDocIdentifiers src names) = (toIfaceStringLiteral src, map unLoc names)
-
-toIfaceStringLiteral :: StringLiteral -> IfaceStringLiteral
-toIfaceStringLiteral (StringLiteral sl fs _) = IfStringLiteral sl fs
-
coreRuleToIfaceRule :: CoreRule -> IfaceRule
-- A plugin that installs a BuiltinRule in a CoreDoPluginPass should
-- ensure that there's another CoreDoPluginPass that removes the rule.
=====================================
compiler/GHC/Iface/Warnings.hs
=====================================
@@ -0,0 +1,34 @@
+module GHC.Iface.Warnings
+ ( toIfaceWarnings
+ , toIfaceWarningTxt
+ )
+where
+
+import GHC.Prelude
+
+import GHC.Hs
+
+import GHC.Iface.Syntax
+
+import GHC.Types.SourceText
+import GHC.Types.SrcLoc ( unLoc )
+
+import GHC.Unit.Module.Warnings
+
+toIfaceWarnings :: Warnings GhcRn -> IfaceWarnings
+toIfaceWarnings (WarnAll txt) = IfWarnAll (toIfaceWarningTxt txt)
+toIfaceWarnings (WarnSome vs ds) = IfWarnSome vs' ds'
+ where
+ vs' = [(occ, toIfaceWarningTxt txt) | (occ, txt) <- vs]
+ ds' = [(occ, toIfaceWarningTxt txt) | (occ, txt) <- ds]
+
+toIfaceWarningTxt :: WarningTxt GhcRn -> IfaceWarningTxt
+toIfaceWarningTxt (WarningTxt mb_cat src strs) = IfWarningTxt (unLoc . iwc_wc . unLoc <$> mb_cat) src (map (toIfaceStringLiteralWithNames . unLoc) strs)
+toIfaceWarningTxt (DeprecatedTxt src strs) = IfDeprecatedTxt src (map (toIfaceStringLiteralWithNames . unLoc) strs)
+
+toIfaceStringLiteralWithNames :: WithHsDocIdentifiers StringLiteral GhcRn -> (IfaceStringLiteral, [IfExtName])
+toIfaceStringLiteralWithNames (WithHsDocIdentifiers src names) = (toIfaceStringLiteral src, map unLoc names)
+
+toIfaceStringLiteral :: StringLiteral -> IfaceStringLiteral
+toIfaceStringLiteral (StringLiteral sl fs _) = IfStringLiteral sl fs
+
=====================================
compiler/ghc.cabal.in
=====================================
@@ -592,6 +592,7 @@ Library
GHC.Iface.Syntax
GHC.Iface.Tidy
GHC.Iface.Tidy.StaticPtrTable
+ GHC.Iface.Warnings
GHC.IfaceToCore
GHC.Iface.Type
GHC.JS.Ident
=====================================
hadrian/src/Rules/Generate.hs
=====================================
@@ -95,6 +95,7 @@ compilerDependencies = do
, "primop-vector-tys.hs-incl"
, "primop-vector-uniques.hs-incl"
, "primop-docs.hs-incl"
+ , "primop-deprecations.hs-incl"
, "GHC/Platform/Constants.hs"
, "GHC/Settings/Config.hs"
]
=====================================
hadrian/src/Rules/Lint.hs
=====================================
@@ -116,6 +116,7 @@ hsIncls path = [ path </> "primop-vector-tycons.hs-incl"
, path </> "primop-is-cheap.hs-incl"
, path </> "primop-fixity.hs-incl"
, path </> "primop-docs.hs-incl"
+ , path </> "primop-deprecations.hs-incl"
, path </> "primop-primop-info.hs-incl"
, path </> "primop-out-of-line.hs-incl"
, path </> "primop-effects.hs-incl"
=====================================
hadrian/src/Settings/Builders/GenPrimopCode.hs
=====================================
@@ -23,4 +23,5 @@ genPrimopCodeBuilderArgs = builder GenPrimopCode ? mconcat
, output "//primop-vector-tys-exports.hs-incl" ? arg "--primop-vector-tys-exports"
, output "//primop-vector-tycons.hs-incl" ? arg "--primop-vector-tycons"
, output "//primop-docs.hs-incl" ? arg "--wired-in-docs"
+ , output "//primop-deprecations.hs-incl" ? arg "--wired-in-deprecations"
, output "//primop-usage.hs-incl" ? arg "--usage" ]
=====================================
utils/genprimopcode/Main.hs
=====================================
@@ -199,6 +199,9 @@ main = getArgs >>= \args ->
"--wired-in-docs"
-> putStr (gen_wired_in_docs p_o_specs)
+ "--wired-in-deprecations"
+ -> putStr (gen_wired_in_deprecations p_o_specs)
+
_ -> error "Should not happen, known_args out of sync?"
)
@@ -223,7 +226,8 @@ known_args
"--make-haskell-wrappers",
"--make-haskell-source",
"--make-latex-doc",
- "--wired-in-docs"
+ "--wired-in-docs",
+ "--wired-in-deprecations"
]
------------------------------------------------------------------
@@ -639,22 +643,7 @@ gen_switch_from_attribs attrib_name fn_name (Info defaults entries)
-> unlines alternatives
++ fn_name ++ " _thisOp = " ++ getAltRhs xx ++ "\n"
-{-
-Note [GHC.Prim Docs]
-~~~~~~~~~~~~~~~~~~~~
-For haddocks of GHC.Prim we generate a dummy haskell file (gen_hs_source) that
-contains the type signatures and the comments (but no implementations)
-specifically for consumption by haddock.
-
-GHCi's :doc command reads directly from ModIface's though, and GHC.Prim has a
-wired-in iface that has nothing to do with the above haskell file. The code
-below converts primops.txt into an intermediate form that would later be turned
-into a proper DeclDocMap.
-
-We output the docs as a list of pairs (name, docs). We use stringy names here
-because mapping names to "Name"s is difficult for things like primtypes and
-pseudoops.
--}
+-- See Note [GHC.Prim Docs] in GHC.Builtin.Utils
gen_wired_in_docs :: Info -> String
gen_wired_in_docs (Info _ entries)
= "primOpDocs =\n [ " ++ intercalate "\n , " (catMaybes $ map mkDoc $ concatMap desugarVectorSpec entries) ++ "\n ]\n"
@@ -663,6 +652,27 @@ gen_wired_in_docs (Info _ entries)
, not $ null $ desc po = Just $ "(fsLit " ++ show poName ++ "," ++ show (desc po) ++ ")"
| otherwise = Nothing
+-- See Note [GHC.Prim Deprecations] in GHC.Builtin.Utils
+gen_wired_in_deprecations :: Info -> String
+gen_wired_in_deprecations (Info _ entries)
+ = "primOpDeprecations =\n [ "
+ ++ intercalate "\n , " (catMaybes $ map mkDep $ concatMap desugarVectorSpec entries)
+ ++ "\n ]\n"
+ where
+ mkDep po
+ | Just poName <- getName po
+ , Just (OptionString _ depMsg) <- lookup_attrib "deprecated_msg" (opts po)
+ = let mkOcc =
+ case po of
+ PrimOpSpec{} -> "mkVarOcc"
+ PrimVecOpSpec{} -> "mkVarOcc"
+ PseudoOpSpec{} -> "mkVarOcc"
+ PrimTypeSpec{} -> "mkTcOcc"
+ PrimVecTypeSpec{} -> "mkTcOcc"
+ Section{} -> error "impossible(Section)"
+ in Just $ "(" ++ mkOcc ++ " " ++ show poName ++ ", fsLit " ++ show depMsg ++ ")"
+ | otherwise = Nothing
+
------------------------------------------------------------------
-- Create PrimOpInfo text from PrimOpSpecs -----------------------
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/0e4c304b75afe229c140064bb42e76a14e023e5e...a28607632dd14e806fdd2620087718b31c62fc09
--
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/0e4c304b75afe229c140064bb42e76a14e023e5e...a28607632dd14e806fdd2620087718b31c62fc09
You're receiving this email because of your account on gitlab.haskell.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240517/fdab50a4/attachment-0001.html>
More information about the ghc-commits
mailing list