Document tidyProgram
The important function tidyProgram is sadly un-documented. See this ghc-devs conversation.
It should have a Note like Note [CorePrep Overview] in
GHC.CoreToStg.Prep.
I think the invariants of tidyProgram are these.
In the the output of tidyProgram:
-
There is no shadowing of
OccNames. In Core it is fine to have(\x_22. \x_31. x_22), but tidying will convert it to\x. \x1. x, where theOccNames no longer shadow. Main reason: when we serialise to the interface file, we use theOccNamealone, not the unique. -
"Implicit bindings" have been added, such as data constructor wrappers and class method selectors. See Note [Injecting implicit bindings]). These bindings are not subject to the Simplifier (which can't improve them), but we need to generate code for them.
-
...probably some more...
-
A non-invariant:
tidyProgramdoes not ensure that allUniques are globally unique. That is done byCorePrep.
One point I note is that the implicit_binds in GHC.Iface.Tidy.tidyProgram are not themselves tidied,
so there is no a priori reason to suppose that they satisfy the "no-shadowing-of-OccNames" condition.
At very least we should document the invariant that all implicit bindings are pre-tidied. See #21363