As suspected by @simonpj in #18535, avoiding allocations in
`GHC.Utils.Misc.splitAtList` when there are no leftover arguments is
beneficial for performance:

   On CI validate-x86_64-linux-deb9-hadrian:
    T12227 -7%
    T12545 -12.3%
    T5030  -10%
    T9872a -2%
    T9872b -2.1%
    T9872c -2.5%

Metric Decrease:
    T12227
    T12545
    T5030
    T9872a
    T9872b
    T9872c

And prefix ~

(cherry picked from commit 8dbee2c5)

We want to only run the check if ld is gold.

Fixes the fix to #17962.

Remove unused ApiAnns, add one for linear arrow.

Include API Annotations for trailing comma in export list.

Previously it failed as the `ghc` package was not visible.

Previously the code generator could produce corrupt C call sequences due
to register overlap between MachOp lowerings and the platform's calling
convention. We fix this using a hack described in Note [Evaluate C-call
arguments before placing in destination registers].

As mentioned in Note [Register parameter passing] the arguments of
foreign calls cannot refer to caller-saved registers.

as suggested by comments on !2330.

GHC 8.12.1 has been renamed to GHC 9.0.1.

See also:
  https://mail.haskell.org/pipermail/ghc-devs/2020-July/019083.html

[skip ci]

Close #18534.

See commentary in the patch.

Before this patch, this type:
  T :: forall k -> (k ~ k) => forall j -> k -> j -> Type
was printed incorrectly as:
  T :: forall k j -> (k ~ k) => k -> j -> Type

Before this change, GHC would
pretty-print   forall k. forall a -> ()
          as   forall @k a. ()
which isn't even valid Haskell.

This patch started as a small documentation change, an attempt to make
Note [Parser-Validator] and Note [Ambiguous syntactic categories]
more clear and up-to-date.

But it turned out that runECP_P/runECP_PV are weakly motivated,
and it's easier to remove them than to find a good rationale/explanation
for their existence.

As the result, there's a bit of refactoring in addition to
a documentation update.

Before this patch, we parsed types into a reversed sequence
of operators and operands. For example, (F x y + G a b * X)
would be parsed as [X, *, b, a, G, +, y, x, F],
using a simple grammar:

	tyapps
	  : tyapp
	  | tyapps tyapp

	tyapp
	  : atype
	  | PREFIX_AT atype
	  | tyop
	  | unpackedness

Then we used a hand-written state machine to assemble this
 either into a type,        using 'mergeOps',
     or into a constructor, using 'mergeDataCon'.

This is due to a syntactic ambiguity:

	data T1 a =          MkT1 a
	data T2 a = Ord a => MkT2 a

In T1, what follows after the = sign is a data/newtype constructor
declaration. However, in T2, what follows is a type (of kind
Constraint). We don't know which of the two we are parsing until we
encounter =>, and we cannot check for => without unlimited lookahead.

This poses a few issues when it comes to e.g. infix operators:

	data I1 = Int :+ Bool :+ Char          -- bad
	data I2 = Int :+ Bool :+ Char => MkI2  -- fine

By this issue alone we are forced into parsing into an intermediate
representation and doing a separate validation pass.

However, should that intermediate representation be as low-level as a
flat sequence of operators and operands?

Before GHC Proposal #229, the answer was Yes, due to some particularly
nasty corner cases:

	data T = ! A :+ ! B          -- used to be fine, hard to parse
	data T = ! A :+ ! B => MkT   -- bad

However, now the answer is No, as this corner case is gone:

	data T = ! A :+ ! B          -- bad
	data T = ! A :+ ! B => MkT   -- bad

This means we can write a proper grammar for types, overloading it in
the DisambECP style, see Note [Ambiguous syntactic categories].

With this patch, we introduce a new class, DisambTD. Just like
DisambECP is used to disambiguate between expressions, commands, and patterns,
DisambTD  is used to disambiguate between types and data/newtype constructors.

This way, we get a proper, declarative grammar for constructors and
types:

	infixtype
	  : ftype
	  | ftype tyop infixtype
	  | unpackedness infixtype

	ftype
	  : atype
	  | tyop
	  | ftype tyarg
	  | ftype PREFIX_AT tyarg

	tyarg
	  : atype
	  | unpackedness atype

And having a grammar for types means we are a step closer to using a
single grammar for types and expressions.

The patch is quite straightforward. The only tricky part is that
`Language.Haskell.TH.Lib.Internal` now must be `Trustworthy` instead
of `Safe` due to the `GHC.Exts` import (in order to import `TYPE`).

Since `CodeQ` has yet to appear in any released version of
`template-haskell`, I didn't bother mentioning the change to `CodeQ`
in the `template-haskell` release notes.

Fixes #18521.

Previously to merge a set of object files we would invoke the linker as
usual, adding -r to the command-line. However, this can result in
non-sensical command-lines which causes lld to balk (#17962).

To avoid this we introduce a new tool setting into GHC, -pgmlm, which is
the linker which we use to merge object files.

This reverts commit 2290eb02.

Closes #18504.

Also enhance bigNatCheck# and isValidNatural test

In the invocation of `cabal configure`, `--ghc-pkg-option=--global-package-db`
was already given correctly to tell `stage0/bin/ghc-pkg` that it should use
the package DB in `stage1/`.

However, `ghc` needs to be given this information as well, not only `ghc-pkg`!
Until now that was not the case; the package DB in `stage0` was given to
`ghc` instead.
This was wrong, because there is no binary compatibility guarantee that says
that the `stage0` DB's `package.cache` (which is written by the
stage0 == system-provided ghc-pkg) can be deserialised by the `ghc-pkg`
from the source code tree.

As a result, when trying to add fields to `InstalledPackageInfo` that get
serialised into / deserialised from the `package.cache`, errors like

    _build/stage0/lib/package.conf.d/package.cache: GHC.PackageDb.readPackageDb: inappropriate type (Not a valid Unicode code point!)

would appear. This was because the `stage0/bin/ghc would try to
deserialise the newly added fields from
`_build/stage0/lib/package.conf.d/package.cache`, but they were not in there
because the system `ghc-pkg` doesn't know about them and thus didn't write them
there.
It would try to do that because any GHC by default tries to read the global
package db in `../lib/package.conf.d/package.cache`.
For `stage0/bin/ghc` that *can never work* as explained above, so we
must disable this default via `-no-global-package-db` and give it the
correct package DB explicitly.

This is the same problem as #16534, and the same fix as in MR !780
(but in another context; that one was for developers trying out the
`stage0/bin/ghc` == `_build/ghc-stage1` interactively, while this fix
is for a `cabal configure` invocation).

I also noticed that the fix for #16534 forgot to pass `-no-global-package-db`,
and have fixed that in this commit as well.
It only worked until now because nobody tried to add a new ghc-pkg `.conf`
field since the introduction of Hadrian.

Fixes #18070

GHC_STAGE is the stage of the compiler we're building, it should be 1,2(,3?).
But make was generating 0 and 1.

Hadrian does this correctly using a similar `+ 1`:
https://gitlab.haskell.org/ghc/ghc/-/blob/eb8115a8c4cbc842b66798480fefc7ab64d31931/hadrian/src/Rules/Generate.hs#L245

This removes the `ConDeclGADTPrefixPs` per the discussion in #18517.
Most of this patch simply removes code, although the code in the
`rnConDecl` case for `ConDeclGADTPrefixPs` had to be moved around a
bit:

* The nested `forall`s check now lives in the `rnConDecl` case for
  `ConDeclGADT`.
* The `LinearTypes`-specific code that used to live in the
  `rnConDecl` case for `ConDeclGADTPrefixPs` now lives in
  `GHC.Parser.PostProcess.mkGadtDecl`, which is now monadic so that
  it can check if `-XLinearTypes` is enabled.

Fixes #18157.

The issue was fixed by 19e80b9a

Pretty-printing CLabel relies on sdocWithDynFlags that we want to remove
(#10143, #17957). It uses it to query the backend and the platform.

This patch exposes Clabel ppr functions specialised for each backend so
that backend code can directly use them.

Also reenable integerPowMod test which had never been reenabled by
mistake.

We don't need to use `sdocWithDynFlags` to know whether we should
display linear types for datacon types, we already have
`sdocLinearTypes` field in `SDocContext`.  Moreover we want to remove
`sdocWithDynFlags` (#10143, #17957)).

This tiny patch improves the compile time of flatten-heavy
programs by 1-2%, by adding two bangs.

Addresses (somewhat) #18502

This reduces allocation by
   T9872b   -1.1%
   T9872d   -3.3%

   T5321Fun -0.2%
   T5631    -0.2%
   T5837    +0.1%
   T6048    +0.1%

Metric Decrease:
    T9872b
    T9872d

I noticed this warning going off, and discovered that it's
really fine.  This small patch removes the warning, and docments
what is going on.

Previously, `rnFamInstEqn` would mark the name of the type/data
family used in an equation as an occurrence, regardless of what sort
of family it is. Most of the time, this is the correct thing to do.
The exception is closed type families, whose equations constitute its
definition and therefore should not be marked as occurrences.
Overzealously counting the equations of a closed type family as
occurrences can cause certain warnings to not be emitted, as observed
in #18470.  See `Note [Type family equations and occurrences]` in
`GHC.Rename.Module` for the full story.

This fixes #18470 with a little bit of extra-casing in
`rnFamInstEqn`. To accomplish this, I added an extra
`ClosedTyFamInfo` field to the `NonAssocTyFamEqn` constructor of
`AssocTyFamInfo` and refactored the relevant call sites accordingly
so that this information is propagated to `rnFamInstEqn`.

While I was in town, I moved `wrongTyFamName`, which checks that the
name of a closed type family matches the name in an equation for that
family, from the renamer to the typechecker to avoid the need for an
`ASSERT`. As an added bonus, this lets us simplify the details of
`ClosedTyFamInfo` a bit.

This patch primarily:

* Documents `checkInferredVars` (previously called
  `check_inferred_vars`) more carefully. This is the
  function which throws an error message if a user quantifies an
  inferred type variable in a place where specificity cannot be
  observed. See `Note [Unobservably inferred type variables]` in
  `GHC.Rename.HsType`.

  Note that I now invoke `checkInferredVars` _alongside_
  `rnHsSigType`, `rnHsWcSigType`, etc. rather than doing so _inside_
  of these functions. This results in slightly more call sites for
  `checkInferredVars`, but it makes it much easier to enumerate the
  spots where the inferred type variable restriction comes into
  effect.
* Removes the inferred type variable restriction for default method
  type signatures, per the discussion in #18432. As a result, this
  patch fixes #18432.

Along the way, I performed some various cleanup:

* I moved `no_nested_foralls_contexts_err` into `GHC.Rename.Utils`
  (under the new name `noNestedForallsContextsErr`), since it now
  needs to be invoked from multiple modules. I also added a helper
  function `addNoNestedForallsContextsErr` that throws the error
  message after producing it, as this is a common idiom.
* In order to ensure that users cannot sneak inferred type variables
  into `SPECIALISE instance` pragmas by way of nested `forall`s, I
  now invoke `addNoNestedForallsContextsErr` when renaming
  `SPECIALISE instance` pragmas, much like when we rename normal
  instance declarations. (This probably should have originally been
  done as a part of the fix for #18240, but this task was somehow
  overlooked.) As a result, this patch fixes #18455 as a side effect.