allow dev repo to be specified in cabal file

We need a spec for how we should specify the source control in a .cabal file.

Here are some questions to consider. They are not necessarily all requirements.

• what are the use cases?
• what kinds of integration would we like with other tools, eg hackage or cabal-install.
• how to specify the kind of source control being uses, eg darcs, svn, git etc. Though it's for hackage to support darcs better than others we should allow all necessary info for other systems to be specified in the .cabal file for other tools to take advantage of.
• how to specify the url, does that work for other SCMs?
• what about tags or branches?
• what if the package is not at the root of the repo but within some sub-dir? We may want to find it.
• should we be specifying the repo/tag for the exact release? should we specify the branch this release was made from or the main development branch, or both?

We need support for arbitrary repo types, beyond just git. So something like:

source: http://foo.org/code.git

That is, an untyped url without information about what type of repo it is.

Or we include type information about the source:

source: http://foo.org/code.git
source-type: git

It shouldn't be constrained to just darcs, in any case. Besides darcs, probably the most common case is google code's svn repos, in fact.

Isn't it vital to know what kind of repo we're dealing with, otherwise how do we know automatically which tool to use?

For example if it's darcs (or another supported scm) then we can make darcs-graph activity graphs and other fun things. That's not possible if one has to somehow inspect the content at the other end of the url to guess what kind of repo it is.

I'd like a tool that downloads the scm version of a cabal package. very simple yet I'd find it much useful.

cabal-source get zlib

should run darcs and give me the zlib repo in the current dir. Nice...

About knowing which kind of repo it is, lets have a look what other tools does. Layman is an application to help the user get and update his Gentoo overlays (extra stuff not covered in portage). It uses a description file, http://www.gentoo.org/proj/en/overlays/layman-global.txt . A short snippet from the xml:

 type = "darcs"
 src  = "http://www.haskell.org/~gentoo/gentoo-haskell/"

It mentions both the type of scm, and the location.

Another alternative would be to just write an URI, possibly combining the tool and the source location:

darcs+http://www.haskell.org/~gentoo/gentoo-haskell/

That would require us to invent the URI scheme when the scm itself doesn't provide such names itself.

I guess writing both the type and the location in separate fields would be easiest. Either way, I really think the type of the tool to use must be described or we will not be able to do much cool stuff.

Replying to kolmodin:

I'd like a tool that downloads the scm version of a cabal package. very simple yet I'd find it much useful. {{{ cabal-source get zlib }}} should run darcs and give me the zlib repo in the current dir. Nice...

I'd expect a --development flag, or similar, to be needed if you want the source from the RCS. Otherwise I'd expect it to give you the source from the latest tarball.

The SCM field is indeed rather vital, given that almost every distributed SCM supports fetching via HTTP in addition to SSH and any native protocol it may have. Anyway, it's simpler to implement that way.

It would probably also be good to keep a registry of SCM names for the rare occasion where it isn't obvious what to put in the field -- arch comes to mind, and I guess there might be some confusion regarding mercurial/hg. Speaking of arch, some SCMs will very possibly require further parameters -- in arch's case, the branch to check out -- and others may benefit -- e.g. git could use a branch name, though master makes a reasonable default.

A similar proposal for the RPM packaging system: http://lwn.net/Articles/290300/

SCMType: {cvs|svn|git|hg|etc.}
SCMRepo: <repo_url, complete spec for SCMs like git, would be cvs_root
for cvs>
SCMModule: <module name for repo types that need this, such as cvs>
SCMTag: <tag representing exact source matching binary package>
SCMBranch: <branch on which tag exists, allowing the installation of
later sources from the same product line branch instead of exact sources
of the installed package at the user's option>

Clearly we need to know which scm we're dealing with. But I think we also want to be able to refer to more specific things, in particular the 'HEAD' branch where new development happens and also the branch from which this release was made (if different) and optionally a tag for this specific release.

Not all that information is required of course, but we should be able to specify it in a clear way. If the meaning is well defined then it allows us to to integration like rebuilding from the same branch+tag, following activity in a head repo (for info on the hackage website).

If we don't give clear meanings it's almost useless, it can then only be used as a link for humans to follow and interpret.

Would hackage then check that the contents of the tarball actually matches what's in the repository -- or simply make the tarball on its own?

Replying to SamB:

Would hackage then check that the contents of the tarball actually matches what's in the repository -- or simply make the tarball on its own?

No, it would not check or generate tarballs. It'd be for other uses (manual or automatic) which wants the equivalent of a release in the source control system. What kind of uses? I'm sure there are several. How about looking at changes since a release, generating automatic changelogs. I'm sure other people can think of others.

Done.

Tue Sep 30 15:27:08 PDT 2008  Duncan Coutts <duncan@haskell.org>
  * Add support for specifying source repos in .cabal files
  Ticket #58. Does not yet include checking.

Tue Sep 30 20:36:37 PDT 2008  Duncan Coutts <duncan@haskell.org>
  * Use unknown rather than specific other repo kinds
  We can still add more as necessary

Tue Sep 30 20:37:55 PDT 2008  Duncan Coutts <duncan@haskell.org>
  * Add some checks on the repository sections

Tue Sep 30 20:39:28 PDT 2008  Duncan Coutts <duncan@haskell.org>
  * Document the source-repository stuff

It looks like:

source-repository head
  type:     darcs
  location: http://darcs.haskell.org/cabal/

And has support for git, cvs, svn and others including specifying branches and tags. It also supports subdirs for projects that include multiple packages in a single repo.