Add documentation on custom Prelude modules (#22228)

Specifically, custom Prelude modules that are named `Prelude`.

1 files changed, 42 insertions, 3 deletions

diff --git a/docs/users_guide/exts/rebindable_syntax.rst b/docs/users_guide/exts/rebindable_syntax.rst
index 3b41d5097b..4955e17c11 100644
--- a/docs/users_guide/exts/rebindable_syntax.rst
+++ b/docs/users_guide/exts/rebindable_syntax.rst
@@ -14,9 +14,7 @@ Rebindable syntax and the implicit Prelude import
 
 GHC normally imports ``Prelude.hi`` files for
 you. If you'd rather it didn't, then give it a ``-XNoImplicitPrelude``
-option. The idea is that you can then import a Prelude of your own. (But
-don't call it ``Prelude``; the Haskell module namespace is flat, and you
-must not conflict with any Prelude module.)
+option. The idea is that you can then import a Prelude of your own.
 
 .. extension:: RebindableSyntax
     :shortdesc: Employ rebindable syntax.
@@ -91,6 +89,47 @@ Be warned: this is an experimental facility, with fewer checks than
 usual. Use ``-dcore-lint`` to typecheck the desugared program. If Core
 Lint is happy you should be all right.
 
+Custom Prelude modules named ``Prelude``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you call your custom Prelude module ``Prelude`` and place it in a file called
+``Prelude.hs``, then your custom Prelude will be implicitly imported instead of
+the default Prelude.
+
+Here is an example that compiles: ::
+
+    $ cat Prelude.hs
+    module Prelude where
+
+    a = ()
+
+    $ cat B.hs
+    module B where
+
+    foo = a
+
+    $ ghc Prelude.hs B.hs
+    [1 of 2] Compiling Prelude          ( Prelude.hs, Prelude.o )
+    [2 of 2] Compiling B                ( B.hs, B.o )
+
+The new ``Prelude`` is implicitly imported in ``B.hs``.
+
+Here is an example that does not compile: ::
+
+    $ cat Prelude.hs
+    module Prelude where
+
+    foo = True
+
+    $ ghc Prelude.hs
+    [1 of 1] Compiling Prelude          ( Prelude.hs, Prelude.o )
+
+    Prelude.hs:3:7: error: Data constructor not in scope: True
+
+The original ``Prelude`` module is shadowed by the custom Prelude in this case.
+To include the original Prelude in your custom Prelude, you can explicitly
+import it with the ``-XPackageImports`` option and ``import "base" Prelude``.
+
 Things unaffected by :extension:`RebindableSyntax`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~