From 4920157a2e5b7679b6971632c1b1f7be38c09f53 Mon Sep 17 00:00:00 2001 From: "simonpj@microsoft.com" Date: Mon, 29 Oct 2007 16:25:05 +0000 Subject: [PATCH] Improve documentation of orphan instances (thanks to Adrian Hey) Please push to stable branch Simon --- docs/users_guide/flags.xml | 10 ++--- docs/users_guide/separate_compilation.xml | 63 ++++++++++++++++++++--------- docs/users_guide/using.xml | 14 +++++++ 3 files changed, 62 insertions(+), 25 deletions(-) diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index beb082e..f0f6f36 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -434,11 +434,7 @@ file - Read the interface in - file and dump it as text to - stdout. - mode - - + See . @@ -1062,8 +1058,8 @@ - warn when the module contains "orphan" instance declarations - or rewrite rules + warn when the module contains orphan instance declarations + or rewrite rules dynamic diff --git a/docs/users_guide/separate_compilation.xml b/docs/users_guide/separate_compilation.xml index f963ca0..fc22fbd 100644 --- a/docs/users_guide/separate_compilation.xml +++ b/docs/users_guide/separate_compilation.xml @@ -595,9 +595,9 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` - Where file is the name of + where file is the name of an interface file, dumps the contents of that interface in - a human-readable (ish) format. + a human-readable (ish) format. See . @@ -1184,8 +1184,31 @@ and GHC has no other reason for visiting the module. Example: class C a where ... Here, neither D nor T is declared in module Orphan. -We call such modules “orphan modules”, -defined thus: +We call such modules “orphan modules”. +GHC identifies orphan modules, and visits the interface file of +every orphan module below the module being compiled. This is usually +wasted work, but there is no avoiding it. You should therefore do +your best to have as few orphan modules as possible. + + +Functional dependencies complicate matters. Suppose we have: + + module B where + instance E T Int where ... + data T = ... + +Is this an orphan module? Apparently not, because T +is declared in the same module. But suppose class E had a +functional dependency: + + module Lib where + class E x y | y -> x where ... + +Then in some importing module M, the constraint (E a Int) should be "improved" by setting +a = Int, even though there is no explicit mention +of T in M. + +These considerations lead to the following definition of an orphan module: An orphan module orphan module @@ -1193,12 +1216,21 @@ defined thus: least one orphan rule. An instance declaration in a module M is an orphan instance if - orphan instance - none of the type constructors - or classes mentioned in the instance head (the part after the “=>”) are declared - in M. - - Only the instance head counts. In the example above, it is not good enough for C's declaration + orphan instance + + + The class of the instance declaration is not declared in M, and + + + Either the class has no functional dependencies, and none of the type constructors + in the instance head is declared in M; or there + is a functional dependency for which none of the type constructors mentioned + in the non-determined part of the instance head is defined in M. + + + + Only the instance head (the part after the “=>”) + counts. In the example above, it is not good enough for C's declaration to be in module A; it must be the declaration of D or T. @@ -1210,16 +1242,11 @@ defined thus: - GHC identifies orphan modules, and visits the interface file of -every orphan module below the module being compiled. This is usually -wasted work, but there is no avoiding it. You should therefore do -your best to have as few orphan modules as possible. - - - You can identify an orphan module by looking in its interface +GHC will warn you if you are creating an orphan module, if you add `-fwarn-orphan-modules`. +You can identify an orphan module by looking in its interface file, M.hi, using the -. If there is a “!” on the + mode. If there is a [orphan module] on the first line, GHC considers it an orphan module. diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml index 5d92ab2..b171ad3 100644 --- a/docs/users_guide/using.xml +++ b/docs/users_guide/using.xml @@ -342,6 +342,20 @@ module X where + ghc --show-iface file + + + + + Read the interface in + file and dump it as text to + stdout. For example ghc --show-iface M.hi. + + + + + + ghc --supported-languages -- 1.7.10.4