up-to-date mirror of the official darcs screened branch (fork of darcs's darcs-screened) (http://darcs.net/Development/GettingStarted)
root
- HLint
- contrib
- darcs
- harness
- release
- src
- tests
- .authorspellings
- .boring
- .latex2html-init
- COPYING
- COPYING.LIB
- GNUmakefile
- HACKING
- NEWS
- README
- Setup.lhs
- darcs.cabal
- hpc-sum
- hpc.README
Darcs
=====
This is the source tree for darcs, a distributed version control system
written in Haskell.
For more information, visit the darcs web site:
http://www.darcs.net
Compilation and Installation
============================
Building Darcs is best done with the Haskell Platform:
http://www.haskell.org/platform/. Any release of darcs should build with
the most recent version of the Platform at the time of the release. This
will also generally apply to unstable versions.
If you are not using the Platform, then you need GHC and Cabal.
The versions required can be found in the darcs.cabal file under
'build-tools' and 'Cabal-Version' respectively.
The cabal-install package is also recommended.
If you have the Platform or otherwise have the "cabal-install" package
on your system (that is, there is a "cabal" executable in your path),
you can use the following command to create an executable in
~/.cabal/bin/darcs (this will also automatically fetch and build
dependencies from the Hackage server).
$ cabal update
$ cabal install
Otherwise, if you have the "cabal" package but not the "cabal-install"
package, run the following:
$ runghc Setup configure
$ runghc Setup build
$ sudo runghc Setup install
You may also omit the last step and copy the darcs executable (found in
dist/build/darcs/darcs) to a location of your choosing.
More detailed instructions can be found at
<http://www.haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package>
including instructions on obtaining a copy of cabal-install.
Flags to alter compilation
==========================
There some flags that can be used to alter compilation. They are specified like this:
$ cabal install -fflag_name
Here are some may be of interest. Search for "flags" in the `darcs.cabal` file
file for the complete list.
-f-curl
By default the cabal-based build requires the cURL library and development
headers. If you can't provide cURL, use this flag to disable the use of it.
The pure Haskell 'HTTP' package will be used instead.
-frts
When trying to use the patch-index feature, you can may get an error like
this: "Stack space overflow: current size 8388608 bytes." darcs can be
recompiled with this flag to avoid the issue. Some more detail is here:
http://darcs.net/Using/PatchIndex
-fstatic
Builds a static binary, which bundles most dependencies. The resulting binary
is larger, but is able to be installed on similar machines without also
installing all the dependencies separately.
-fforce-char8-encoding
For use with base > 4.4 the standard directory functions do Unicode
translation. This flags helps building when base > 4.4.
Hacking
=======
For more information about darcs hacking and best practices please check
the darcs wiki at http://wiki.darcs.net
Of particular interest are the following documents:
* http://wiki.darcs.net/Development/GettingStarted
* http://wiki.darcs.net/Development/FAQ
Comments about do-notation warnings
===================================
You may find a number of comments (163 of them at the time of writing) looking
like:
-- Warning: A do-notation statement discarded a result of type Whatever.
They signal warnings issued by GHC that have been automatically silenced.
See http://bugs.darcs.net/issue1988 for more detail.
These warnings were most certainly harmless, but who knows... If you stumble
upon one such comment, take a minute or two to check if it is really okay to
ignore the return value (look for "_ <- " on the line next to the comment). If
everything is correct, please remove the comment and send a patch (mentioning
issue1988). If it isn't, you have found a bug, congratulations! Fix it, or
fill a bug report on http//bugs.darcs.net/. Finally, if in doubt, leave it as
is. Many thanks.
Testing
=======
For more information about the test suite, including how to run specific
tests please read tests/README.test_maintainers.txt.
Happy hacking!