Development/FAQ

Questions that new darcs hackers may have...

Patches

I sent a patch and got no response!

We're very sorry to hear that! The most likely explanation is that we did not get your patch (we do try to respond to every patch we receive, and slip-ups are rare). Have a look at our informal darcs send documentation some troubleshooting advice

Can I amend a patch I sent to the tracker?

You can only amend a patch before it has been screened. Some tricks for finding out if the patch has been screened or not:

darcs changes --repo http://darcs.net/screened --match 'author Bob' -i
darcs changes --repo http://darcs.net/screened --match 'name foo'

If your patch has not yet been screened, it should be fine to amend. If it already has been applied, you cannot amend, but must send a followup.

How can I replace a patch I already sent to the tracker?

First, see the question above: has your patch already been screened?

Our preferred way is just to send a reply to the original ticket. Check the Getting Started guide (search for "send") for details.

If you've already sent a new patch, no problem! Just mark the old as obsoleted and add the ticket number for the new patch in its superseder field.

Test suite

Do I really have to run all those tests?

If you're pretty sure that your modification is ok, you could do a darcs record --no-test. A useful trick if you're working on many patches is to run darcs trackdown at the very end, when you're ready to test them out. Keep in mind that you can also use the tests/tests_to_run mechanism to select which tests you want to run whenever you do a make test.

Should I worry about tests unexpectedly succeeding?

No. These are tests written for when certain wishlist features are implemented or bugs are corrected. If they unexpectedly succeed, it could either mean that the feature in question has been implemented (and that the test suite should be modified), or that darcs has system-specific behaviour or that there is something non-deterministic going on. (FIXME: any comments?)

How do I run a subset of tests?

TODO

::

cabal test tests/foo.sh tests/bar.sh

Other infrastructure

How do I edit the documentation?

The .tex files for the documentation are automatically generated from comments in the code, so don't look for the manual. Just edit relevant comments in the code.

Hacking darcs on Debian 5.0 (Lenny)

Darcs can be hacked using the ghc6 package included in Debian Lenny, but the README highly recommends a newer version. To use the stock Lenny ghc, Debian Lenny needs additional software installed to compile darcs.

If you follow the instructions in HACKING you will get the error:

Setup.lhs:31:7:
     Could not find module `Distribution.Text':

The solution (per the README) is to install a newer version of cabal-install (if not a newer version of ghc). Cabal-install installation instructions are on the haskell wiki. The basic steps involve getting a tarball and running ./bootstrap.sh. Along the way you may need to install the following packages:

  • libghc6-parsec-dev
  • libghc6-network-dev
  • libghc6-mtl-dev
  • libcurl4-openssl-dev (or libcurl4-gnutls-dev)

The new cabal binaries go in ~/.cabal/bin/, which needs to be added to $PATH. Subsequent binaries produced by cabal also go in this directory, including any new darcs you install with cabal. After installing cabal-install do:

cabal update

Once this is done you can begin work within your copy of the darcs repo.

If you are using the stock Lenny ghc you will need to do:

cabal -f-zlib configure

To build a new darcs from source (result in dist/build/darcs/darcs):

cabal build

To run the unit tests

cabal test

To install your own version:

cabal install

To re-install the latest darcs to recover after breaking your own version (ghc versions newer than Lenny's should omit the -f-zlib):

cabal -f-zlib --reinstall install darcs

How can I play around with darcs functions and commands in GHCi?

Unfortunately we no longer (2009-08) have a good way of dealing with this. You may be able to get away with loading the darcs module in GHCi after cabal build.

See also http://wiki.darcs.net/Development/Tips#faster-edit-compile-cycle

Code questions

What does p C(x y) in the type signatures mean?

C is a pre-processor macro used for selectively enabling/disabling the type witnesses. You can pretty much ignore them if you don't know what they mean. After you get used to them, they make the code a bit easier to read. For more details, see gadts.h and David Roundy's FOSDEM talk and Jason Dagit's masters thesis at Talks.

Do DarcsArguments support optional arguments?

No. (TODO hasn't this changed recently?)

What would it take to make it support optional arguments? (No idea. --MarnixKlooster)

What is the format of a patch bundle?

  1. a blank line
  2. "New patches:"
  3. a blank line
  4. The patches (see gzipped files in _darcs/patches for format).
  5. "Context:"
  6. The context (see darcs changes --context for format).
  7. "Patch bundle hash:"
  8. Hex representation of the sha1-hash of the patches in (4) WITHOUT "New patches", "Context:" and without blank lines. (Note that I'm not a developer of darcs itself. These information is kind of reverse-engineered.)

Darcs does not allow tabs in Haskell code, how do I disable them in my editor?

If you use Emacs there are several ways according to Dave Love

(add-hook 'haskell-mode-hook '(lambda () (setq indent-tabs-mode nil)))

or use http://www.loveshack.ukfsn.org/emacs/dir-locals.el or http://www.loveshack.ukfsn.org/emacs/indent-tabs-maybe.el to set indent-tabs-mode locally.