[GHC] #10622: Rename Backpack packages to units

[GHC]

#10622: Rename Backpack packages to units
-------------------------------------+-------------------------------------
        Reporter:  ezyang            |                   Owner:  ezyang
            Type:  task              |                  Status:  new
        Priority:  normal            |               Milestone:
       Component:  Compiler          |                 Version:  7.11
      Resolution:                    |                Keywords:  backpack
Operating System:  Unknown/Multiple  |            Architecture:
 Type of failure:  None/Unknown      |  Unknown/Multiple
      Blocked By:                    |               Test Case:
 Related Tickets:                    |                Blocking:
                                     |  Differential Revisions:  Phab:D1057
-------------------------------------+-------------------------------------
Description changed by ezyang:

Old description:

> After today's weekly Backpack call, we have come to the conclusion that
> we have two different types of "packages" in the Backpack world:
>
> 1. Cabal packages, which have a single `.cabal` file and are a unit of
> distribution which get uploaded to Hackage, and
>
> 2. Backpack packages, of which there may be multiple defined in a
> Backpack file shipped with a Cabal package; and are the building blocks
> for modular development in the small.
>
> It's really confusing to have both of these called packages: thus, we
> propose to rename all occurrences of Backpack package to unit.  A Cabal
> ''package'' may contain MULTIPLE Backpack ''units'', although old-style
> Cabal files will only define one unit.
>
> A Cabal package remains
>  * The unit of distribution
>  * The unit that Hackage handles
>  * The unit of versioning
>  * The unit of ownership (who maintains it etc)
>
> Here are some of the consequences:
>
> 1. We rename `PackageKey` to `UnitKey`, as it identifies a unit rather
> than a Cabal package. (I think this actually makes the function of these
> identifiers clearer.) We'll also distinguish Cabal-file level
> `PackageName`s from Backpack-file `UnitName`s.  Finally, any given unit
> will be uniquely identified by an `InstalledUnitId`.
>
> 2. The source-level syntax of Backpack files will use `unit` in place of
> where `package` was used before.
>
> 3. For backwards compatibility reasons, we'll sometimes arrange for
> `PackageName`/`UnitName` and `InstalledUnitId`/`InstalledPackageId` to
> coincide.  Specifically, the unit of a package which has the same
> `UnitName` as the `PackageName` is treated specially: its
> `InstalledUnitId` is guaranteed to be the same as the
> `InstalledPackageId` and it is what is "visible" when a user uses old
> concepts such as `-package foo-0.1` to select a package.
>
> 4. The installed package database is extended to record some number of
> units per an installed package: the public facing API is that you can
> register a package CONTAINING some number of units. For old-style
> packages, there will be only one unit with a matching `UnitName`, so this
> will be isomorphic to an old style package; however, GHC will grow some
> new APIs for selecting specific units to bring into scope.  GHC really
> mostly only cares about units, but if a user asks for a package using,
> e.g. `-package` it will translate this request into a request for the
> appropriate unit.
>
> 5. For old-style packages, Cabal will continue to write and register a
> package configuration file which implicitly defines a single unit.
> However, the plan is to give GHC the capacity to generate unit
> description files (like package description files, but per unit), which
> Cabal can interpret and use to register packages in the global database
> using a `ghc-pkg` which can register units and "unitless" package
> description files which don't implicitly define a unit. (NB: we must
> create unit description files, because `ghc-pkg recache` is expected to
> be able to regenerate the database.) (NB: we want to be able to add units
> for a package separately, because this is how units for indefinite
> packages are created as they are instantiated with new implementations.)
>
> 6. Cabal could also finally grow the "multiple libraries per single Cabal
> file" support people have wanted; it's just a stylized use of the
> Backpack facilities.
>
> The work plan:
>
> 1. Modify `bin-package-db` to reflect the unit/package split, but
> otherwise keep ghc-pkg and GHC the same (so old-style package description
> still supported, and interpreted as a package containing one unit.)
> Source modifications to GHC assume that a package only has one unit.
>
> 2. Generalize GHC to work with packages with multiple units
>
> 3. Add capability to Cabal/ghc-pkg to register just units. For
> compilation of Backpack files, GHC will write out units which Cabal will
> then install to the real registry
>
> 4. Backpack!

New description:

 After today's weekly Backpack call, we have come to the conclusion that we
 have two different types of "packages" in the Backpack world:

 1. Cabal packages, which have a single `.cabal` file and are a unit of
 distribution which get uploaded to Hackage, and

 2. Backpack packages, of which there may be multiple defined in a Backpack
 file shipped with a Cabal package; and are the building blocks for modular
 development in the small.

 It's really confusing to have both of these called packages: thus, we
 propose to rename all occurrences of Backpack package to unit.  A Cabal
 ''package'' may contain MULTIPLE Backpack ''units'', although old-style
 Cabal files will only define one unit.

 A Cabal package remains
  * The unit of distribution
  * The unit that Hackage handles
  * The unit of versioning
  * The unit of ownership (who maintains it etc)

 Here are some of the consequences:

 1. We rename `PackageKey` to `UnitKey`, as it identifies a unit rather
 than a Cabal package. (I think this actually makes the function of these
 identifiers clearer.) We'll also distinguish Cabal-file level
 `PackageName`s from Backpack-file `UnitName`s.  Finally, any given unit
 will be uniquely identified by an `InstalledUnitId`.

 2. The source-level syntax of Backpack files will use `unit` in place of
 where `package` was used before.

 3. For backwards compatibility reasons, we'll sometimes arrange for
 `PackageName`/`UnitName` and `InstalledUnitId`/`InstalledPackageId` to
 coincide.  Specifically, the unit of a package which has the same
 `UnitName` as the `PackageName` is treated specially: its
 `InstalledUnitId` is guaranteed to be the same as the `InstalledPackageId`
 and it is what is "visible" when a user uses old concepts such as
 `-package foo-0.1` to select a package.

 4. The installed package database is extended to record some number of
 units per an installed package: the public facing API is that you can
 register a package CONTAINING some number of units. For old-style
 packages, there will be only one unit with a matching `UnitName`, so this
 will be isomorphic to an old style package; however, GHC will grow some
 new APIs for selecting specific units to bring into scope.  GHC really
 mostly only cares about units, but if a user asks for a package using,
 e.g. `-package` it will translate this request into a request for the
 appropriate unit.

 5. For old-style packages, Cabal will continue to write and register a
 package configuration file which implicitly defines a single unit.
 However, the plan is to give GHC the capacity to generate unit description
 files (like package description files, but per unit), which Cabal can
 interpret and use to register packages in the global database using a
 `ghc-pkg` which can register units and "unitless" package description
 files which don't implicitly define a unit. (NB: we must create unit
 description files, because `ghc-pkg recache` is expected to be able to
 regenerate the database.) (NB: we want to be able to add units for a
 package separately, because this is how units for indefinite packages are
 created as they are instantiated with new implementations.) (NB: For BC
 purposes, since Cabal has to write old-style packages for old GHC, this is
 pretty irritating.)

 6. Cabal could also finally grow the "multiple libraries per single Cabal
 file" support people have wanted; it's just a stylized use of the Backpack
 facilities. (Note: Actually, not QUITE: multiple libraries are likely to
 want separate sets of dependencies, whereas our units proposal has
 external dependencies shared over all units. If we want the multiple
 libraries, cabal-install has to learn about units.)

 The work plan:

 1. Modify `bin-package-db` to reflect the unit/package split, but
 otherwise keep ghc-pkg and GHC the same (so old-style package description
 still supported, and interpreted as a package containing one unit.)
 Source modifications to GHC assume that a package only has one unit.

 2. Generalize GHC to work with packages with multiple units

 3. Add capability to Cabal/ghc-pkg to register just units. For compilation
 of Backpack files, GHC will write out units which Cabal will then install
 to the real registry

 4. Backpack!

--

--
Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/10622#comment:4>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler