Cabal: RFC: Begin Cabal development commentary

[phadej]

IMHO it can be a part of user's manual. Some topics to begin with are implementation commentary of

• solver
• backpack
• new-build
• parsec parser

[23Skidoo]

See also https://github.com/haskell/cabal/wiki/Source-Guide.

[phadej]

@23Skidoo didn't know about that!

[ezyang]

This shouldn't stop you from working on it, but I have been working on a solver document. It is not very far along though.

[23Skidoo]

@ezyang BTW, what's the fate of that solver document? Maybe you can put your draft on the wiki if you're no longer working on it.

[ezyang]

Apparently, I only wrote the intro :)

.. highlight:: console

Whither dependency solving
==========================

Code bases with no external dependencies are easy to build: you just,
well, build everything.

But the usual project is not an island unto itself: rather, it is
composed from other packages written by a heterogenous set of authors.
Each of these packages has multiple versions which may or may not be
compatible with one another, giving rise to the nontrivial problem of
determining a set of packages which are mutually compatible with each
other.

How can you solve this problem?

- You could rely on some third party (Stackage) to tell you
  what your version assignment should be.

- You could pick some version assignment (e.g., the latest versions
  of everything), and then tweak it until you find an assignment that
  works.

- You could use a *dependency solver*, which automates the process of
  testing version assignments to find a satisfying assignment.

Generally speaking, you would rather use the first two approaches if at
all possible.  But sometimes there is no pre-existing version assignment
that is known to work, and the obvious "by-hand" assignments don't seem
to work.  In such cases, the dependency solver can be an extremely useful
tool for generating satisfying assignments.

What a dependency solver does
=============================

The dependency solver is a pure function of type ``DependencyResolver``.
The solver takes as input:

1. The platform we are building

[hvr]

@ezyang btw, your introduction makes it sound as if dependency solving was a kind of discouraged last-resort you should avoid whever you can... whereas dependency solving lies at the core of the Hackage/Cabal/PVP ecosystem... ;-))

[phadej]

https://github.com/haskell/cabal/wiki/Source-Guide is becoming more and more outdated. Maybe it's better to admit we don't have resources to maintain it?

[23Skidoo]

We can add a disclaimer telling people that it's out of date and improvements are welcome.