Switch from -this-package-key to -this-unit-id.

A small cosmetic change, but we have to do a bit of work to
actually support it:

    - Cabal submodule update, so that Cabal passes us
      -this-unit-id when we ask for it.  This includes
      a Cabal renaming to be consistent with Unit ID, which
      makes ghc-pkg a bit more scrutable.

    - Build system is updated to use -this-unit-id rather than
      -this-package-key, to avoid deprecation warnings.  Needs
      a version test so I resurrected the old test we had
      (sorry rwbarton!)

    - I've *undeprecated* -package-name, so that we are in the same
      state as GHC 7.10, since the "correct" flag will have only
      entered circulation in GHC 8.0.

    - I removed -package-key.  Since we didn't deprecate -package-id
      I think this should not cause any problems for users; they
      can just change their code to use -package-id.

    - The package database is indexed by UNIT IDs, not component IDs.
      I updated the naming here.

    - I dropped the signatures field from ExposedModule; nothing
      was using it, and instantiatedWith from the package database
      field.

    - ghc-pkg was updated to use unit ID nomenclature, I removed
      the -package-key flags but I decided not to add any new flags
      for now.

Signed-off-by: Edward Z. Yang <ezyang@cs.stanford.edu>

Test Plan: validate

Reviewers: austin, hvr, bgamari

Reviewed By: bgamari

Subscribers: 23Skidoo, thomie, erikd

Differential Revision: https://phabricator.haskell.org/D1780

2 files changed, 19 insertions, 6 deletions

diff --git a/docs/users_guide/8.0.1-notes.rst b/docs/users_guide/8.0.1-notes.rst
index aaf9ca3825..c36c721be5 100644
--- a/docs/users_guide/8.0.1-notes.rst
+++ b/docs/users_guide/8.0.1-notes.rst
@@ -274,6 +274,14 @@ Compiler
    expressivity may come with a high price in terms of compilation time and
    memory consumption, it is turned off by default.
 
+-  :ghc-flag:`-this-package-key` has been renamed again (hopefully for the last time!)
+   to :ghc-flag:`-this-unit-id`.  The renaming was motivated by the fact that
+   the identifier you pass to GHC here doesn't have much to do with packages:
+   you may provide different unit IDs for libraries which are in the same
+   package.  :ghc-flag:`-this-package-key` is deprecated; you should use
+   :ghc-flag:`-this-unit-id` or, if you need compatibility over multiple
+   versions of GHC, :ghc-flag:`-package-name`.
+
 GHCi
 ~~~~
 
diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst
index 02d9cc6992..89eb2579a1 100644
--- a/docs/users_guide/packages.rst
+++ b/docs/users_guide/packages.rst
@@ -161,10 +161,12 @@ The GHC command line options that control packages are:
 
         $ ghc -o myprog Foo.hs Main.hs -package network
 
-.. ghc-flag:: -package-id ⟨pkg-id⟩
+.. ghc-flag:: -package-id ⟨unit-id⟩
 
     Exposes a package like :ghc-flag:`-package`, but the package is named by its
-    installed package ID rather than by name. This is a more robust way
+    unit ID (i.e. the value of ``id`` in its entry in the installed
+    package database, also previously known as an installed package ID)
+    rather than by name. This is a more robust way
     to name packages, and can be used to select packages that would
     otherwise be shadowed. Cabal passes ``-package-id`` flags to GHC.
     ``-package-id`` supports thinning and renaming described in
@@ -208,11 +210,14 @@ The GHC command line options that control packages are:
     By default, GHC will automatically link in the ``base`` and ``rts``
     packages. This flag disables that behaviour.
 
-.. ghc-flag:: -this-package-key ⟨pkg-key⟩
+.. ghc-flag:: -this-unit-id ⟨unit-id⟩
 
     Tells GHC the the module being compiled forms part of unit ID
-    ⟨pkg-key⟩; internally, these keys are used to determine type equality
-    and linker symbols.
+    ⟨unit-id⟩; internally, these keys are used to determine type equality
+    and linker symbols.  As of GHC 8.0, unit IDs must consist solely
+    of alphanumeric characters, dashes, underscores and periods.  GHC
+    reserves the right to interpret other characters in a special
+    way in later releases.
 
 .. ghc-flag:: -library-name ⟨hash⟩
 
@@ -255,7 +260,7 @@ The ``main`` package
 --------------------
 
 Every complete Haskell program must define ``main`` in module ``Main``
-in package ``main``. Omitting the :ghc-flag:`-this-package-key` flag compiles
+in package ``main``. Omitting the :ghc-flag:`-this-unit-id` flag compiles
 code for package ``main``. Failure to do so leads to a somewhat obscure
 link-time error of the form: