Rename PackageId to PackageKey, distinguishing it from Cabal's PackageId.

Summary:
Previously, both Cabal and GHC defined the type PackageId, and we expected
them to be roughly equivalent (but represented differently).  This refactoring
separates these two notions.

A package ID is a user-visible identifier; it's the thing you write in a
Cabal file, e.g. containers-0.9.  The components of this ID are semantically
meaningful, and decompose into a package name and a package vrsion.

A package key is an opaque identifier used by GHC to generate linking symbols.
Presently, it just consists of a package name and a package version, but
pursuant to #9265 we are planning to extend it to record other information.
Within a single executable, it uniquely identifies a package.  It is *not* an
InstalledPackageId, as the choice of a package key affects the ABI of a package
(whereas an InstalledPackageId is computed after compilation.)  Cabal computes
a package key for the package and passes it to GHC using -package-name (now
*extremely* misnamed).

As an added bonus, we don't have to worry about shadowing anymore.

As a follow on, we should introduce -current-package-key having the same role as
-package-name, and deprecate the old flag.  This commit is just renaming.

The haddock submodule needed to be updated.

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

Test Plan: validate

Reviewers: simonpj, simonmar, hvr, austin

Subscribers: simonmar, relrod, carter

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

Conflicts:
	compiler/main/HscTypes.lhs
	compiler/main/Packages.lhs
	utils/haddock

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/users_guide/7.10.1-notes.xml b/docs/users_guide/7.10.1-notes.xml
index 8d0545ebf3..0af4c3145b 100644
--- a/docs/users_guide/7.10.1-notes.xml
+++ b/docs/users_guide/7.10.1-notes.xml
@@ -234,6 +234,27 @@
     </sect3>
 
     <sect3>
+        <title>ghc</title>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    Many internal functions in GHC related to package IDs have been
+                    renamed to refer to package keys, e.g. <literal>PackageId</literal>
+                    is now <literal>PackageKey</literal>, the wired-in names
+                    such as <literal>primPackageId</literal> are now
+                    <literal>primPackageKey</literal>, etc.  This reflects a distinction
+                    that we are now making: a package ID is, as before, the user-visible
+                    ID from Cabal <literal>foo-1.0</literal>; a package key is now
+                    a compiler-internal entity used for generating linking symbols, and
+                    may not correspond at all to the package ID.  In
+                    particular, there may be multiple package keys per
+                    package ID.
+               </para>
+           </listitem>
+       </itemizedlist>
+    </sect3>
+
+    <sect3>
         <title>ghc-prim</title>
         <itemizedlist>
             <listitem>