Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This commit introduces so-called "private dependencies".
High-level Overview
~~~~~~~~~~~~~~~~~~~
Since its inception, Cabal has enforced the restriction that a library
must only link against one version of each package it depends on. This
ensures that all of the dependencies in the build plan work together. In
your application you use different libraries together, so it’s of
paramount importance that they all agree on what `Text` means or what a
`ByteString` is.
However, sometimes it’s desirable to allow multiple versions of the same
library into a build plan. In this case, it’s desirable to allow a
library author to specify a private dependency with the promise that its
existence will not leak from the interface of the library which uses it.
The two main use cases of private dependencies are:
- Writing benchmarks and testsuites for your library which test new
versions of your library against old versions.
- Writing libraries which can communicate with processes built against
a range of different library versions (such as cabal-install calling
./Setup).
A user specifies a private dependency in their cabal file using
`private-build-depends`. The specification starts with the name of the
private dependency scope and then contains a list of normal dependency
specifications which dictates what is included in that private scope:
private-build-depends: TEXT1 with (text == 1.2.*), TEXT2 with (text == 2.*)
Each private scope is then solved independently of all other scopes. In
this example the TEXT1 scope can choose a version of text in the 1.2.x
range and the TEXT2 scope can choose a version of text in the 2.* range.
Private scopes do not apply transitively, so the dependencies of text
will be solved in the normal top-level scope. If your program contains a
value of type Bool, that comes from the base package, which text depends
on, because the scopes are not applied transitively the same Bool value
can be passed to functions from the TEXT1 scope and TEXT2 scope.
Dependencies introduced privately can be imported into modules in the
project by prefixing the name of the private scope to an exposed module
name.
import qualified TEXT1.Data.Text as T1
import qualified TEXT2.Data.Text as T2
Closure of Private Scopes
~~~~~~~~~~~~~~~~~~~~~~~~~
Private dependency scopes can contain multiple packages. Packages in the
same scope are solved together. For example, if two packages are tightly
coupled and you need to use compatible versions with each other, then
you can list them in the same private scope. Such packages will then be
solved together, but independently of other packages.
Private scopes must be closed. A scope is closed if, whenever we have a
dependency chain P1 -> Q -> P2, in which P1 and P2 are both in a given
private scope S, then Q also belongs to the private scope S. The solver
checks this property, but doesn’t implicitly add packages into a private
scope.
Implementation
~~~~~~~~~~~~~~
To implement private dependencies we changed
* Cabal-syntax to introduce the new `private-build-depends: ALIAS (packages, in, private, scope)` syntax.
See the new type `Dependencies` and changes in `Distribution.Types.Dependency`.
* cabal-install-solver now considers both public and private
dependencies of a given package (see e.g. `solverPkgLibDeps`), has
a new constructor `PrivateScope` in `ConstraintScope` for goals in a
private scope, and there's a new `Qualifier` for packages introduced
in private scopes (see also [Namespace vs Qualifier refactor] below),
to solve them separately from packages introduced by `build-depends`.
* cabal-install-solver needs to check that the private-scope closure
property holds (the closure of the packages in a private scope is in
the private scope) (see `Distribution.Solver.Modular.PrivateScopeClosure`).
We check that the closure holds by looking at the reverse dependency
map while traversing down the tree, at every node:
For every package in a private scope, traverse up the reverse
dependency map until a package in the same private scope is found.
If one exists, and if along the way up any package was not in the same
private scope as the packages in the two ends, we fail.
* cabal-install understands plans with private dependencies and has a
new `UserQualifier` to support constrainting packages in private
scopes using the `--constraint` flag.
Example: `--constraint=private.pkg-a.TEXT01:text == 1.2.*`
* Cabal the library uses the ghc module-renaming mechanism (also used by
Backpack) to rename modules from the packages in a private scope to
prefix them with the private scope alias. It also ensures `cabal
check` fails if there exist the package has private dependencies, as
it is currently an experimental feature which we don't necessarily
want to allow in hackage yet -- e.g. how will haddock render private
dependencies?
Namespace vs Qualifier refactor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We also refactored the `Namespace` vs `Qualifier` types in the solver,
clarifying their interaction such that:
* A package goal with an indepedent namespace is fully solved
indepently from other namespaces, i.e. all the dependency goals
introduced by a goal in a given namespace are also solved in that
namespace.
* In contrast, a package goal with a qualifier is shallow-solved
separately from other goals in the same namespace. The dependency
goals introduced by it will be solved unqualified (`QualTopLevel`) in
that namespace.
For example, goal `pkg-a == 0.1` in `DefaultNamespace+QualTopLevel`, and
goal `pkg-a == 0.2` in the same namespace but with `QualAlias A2 ...`
can be solved together and yield a different version of pkg-a for each
of the goals, however, the dependencies of both will be solved together
-- if they both dependend on `base`, we'd have to find a single
solution. If `pkg-a == 0.2` was in an `Independent` namespace, we could
still solve the two goals with two versions of `pkg-a`, but we could
also pick different versions for all the subdependencies of `pkg-a ==
0.2`.
Besides Namespace vs Qualifier being a welcome refactor that facilitates
implementing private dependencies, it also fixes haskell#9466 and helps with haskell#9467.
---
Co-authored-by: Rodrigo Mesquita <[email protected]>- Loading branch information
1 parent
00835c0
commit 3378e7b