Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation

  • Loading branch information...
commit 01c30fa19b606137a0c0ca2e4c8dba59a2acdef5 1 parent 4d8e70e
@snoyberg snoyberg authored
Showing with 56 additions and 3 deletions.
  1. 0  README
  2. +52 −0 README.md
  3. +4 −3 cabal-src.cabal
View
0  README
No changes.
View
52 README.md
@@ -0,0 +1,52 @@
+cabal-src is a package intended to help solve the Cabal diamond dependency
+problem.
+
+## The problem
+
+Let's say you have three packages. foo depends on the text package, and can use
+any version of it. bar depends on text as well, but requires version 0.10.\*.
+foobar depends on both of those.
+
+If you upload these three packages to Hackage and install foobar, cabal will
+build foo and bar against the same version of text, and then build foobar
+against them. However, if you install these packages locally, foo will be built
+against the most recent version of text (currently 0.11.something), and then
+foobar will be unbuildable, since its dependencies depend on different versions
+of text.
+
+You can see sample packages demonstrating the issue in the *example* folder.
+
+This is just one example of the diamond dependency issue. When dealing with
+complicated systems such as Yesod, with dozens of packages that are in
+development, the situation becomes much worse.
+
+## Our solution
+
+The important thing to note is that, if the packages are on Hackage, Cabal can
+handle the situation. The reason is that Cabal has enough information to
+calculate the correct versions of all dependencies to be used. So our goal is
+to give Cabal access to information on all dependencies, even those not yet on
+Hackage.
+
+Instead of installing a local package with "cabal install", you can now use
+"cabal-src-install". This program actually calls out to "cabal install", and if
+that build succeeds, will perform the following steps:
+
+1. Create a source tarball via "cabal sdist"
+
+2. Copy this tarball into a special location in your .cabal folder.
+
+3. Update a 00-index.tar file specifically kept for cabal-src.
+
+4. Update your .cabal/config file to recognize the special cabal-src folder as necessary.
+
+If you now install your "foo" and "bar" packages via "cabal-src-install", Cabal
+has full access to their source code. When it comes time to install foobar,
+Cabal can determine that foo can be recompiled with text 0.10 and will do so
+automatically.
+
+## Project status
+
+This software should be considered alpha. We'll likely be using it for all
+Yesod development going forward, so I expect that alpha to be upgraded to beta
+and finally production quality in short order. All feedback is welcome!
View
7 cabal-src.cabal
@@ -1,14 +1,15 @@
Name: cabal-src
Version: 0.1
-Synopsis: Install source tarballs
-Description: Install source tarballs
+Synopsis: Alternative install procedure to avoid the diamond dependency issue.
+Description: Please see the README.md file on Github for more information: <https://github.com/yesodweb/cabal-src/blob/master/README.md>.
License: BSD3
License-file: LICENSE
Author: Michael Snoyman
Maintainer: michael@snoyman.com
Category: Distribution
Build-type: Simple
-Cabal-version: >=1.2
+Cabal-version: >=1.6
+homepage: https://github.com/
Executable cabal-src-install
Please sign in to comment.
Something went wrong with that request. Please try again.