src/building_darcs.tex

   1 \chapter{Building darcs}
   2
   3 This chapter should walk you through the steps necessary to build darcs for
   4 yourself.  There are in general two ways to build darcs.  One is for
   5 building released versions from tarballs, and the other is to build the
   6 latest and greatest darcs, from the darcs repo itself.
   7
   8 Please let me know if you have any problems building darcs, or don't have
   9 problems described in this chapter and think there's something obsolete
  10 here, so I can keep this page up-to-date.
  11
  12 \section{Prerequisites}
  13 To build darcs you will need to have {\tt ghc}, the Glorious Glasgow
  14 Haskell Compiler. You should have at the very minimum version 6.4.
  15
  16 It is a good idea (but not required) to have software installed that provide darcs
  17 network access. The {\tt libwww-dev}, {\tt libwww-ssl-dev} or {\tt libcurl} packages
  18 newer than than 7.18.0 are recommended because they provide pipelining support speed
  19 up HTTP access. They have to be explicitly chosen with {\tt --with-libwww} or
  20 {\tt --with-curl-pipelining}. Otherwise, darcs will automatically look for one of
  21 libcurl, {\tt curl} or {\tt wget}.  You also might want to have scp
  22 available if you want to grab your repos over ssh\ldots
  23
  24 To use the \verb!diff! command of darcs, a \verb!diff! program supporting
  25 options \verb!-r! (recursive diff) and \verb!-N! (show new files as
  26 differences against an empty file) is required. The \verb!configure!
  27 script will look for \verb!gdiff!, \verb!gnudiff! and \verb!diff! in this
  28 order. You can force the use of another program by setting the \verb!DIFF!
  29 environment variable before running \verb!configure!.
  30
  31 To rebuild the documentation (which should not be necessary since it is
  32 included in html form with the tarballs), you will need to have latex
  33 installed, as well as latex2html if you want to build it in html form.
  34
  35
  36 \section{Building on Mac~OS~X}
  37 To build on Mac~OS~X, you will need the Apple Developer Tools and the ghc
  38 6.4 package installed.
  39
  40 \section{Building on Microsoft Windows}
  41 To build on Microsoft Windows, you will need:
  42
  43 \begin{itemize}
  44 \item \htmladdnormallinkfoot{MinGW}{http://www.mingw.org/} which provides the GCC
  45   toolchain for win32.
  46 \item \htmladdnormallinkfoot{MSYS}{http://www.mingw.org/msys.shtml} which provides
  47   a unix build environment for win32.  Be sure to download the separate
  48   msysDTK, autoconf and automake.
  49 \item \htmladdnormallinkfoot{zlib-1.2.1+}{http://www.gzip.org/zlib/} library
  50   and headers.
  51 \item \htmladdnormallinkfoot{curl-7.12.2+}{http://curl.haxx.se/} library
  52   and headers.
  53 \item If building with an SSL enabled curl you will need the OpenSSL
  54   libraries, unofficial builds are available at\\
  55   \htmladdnormallink{http://www.slproweb.com/products/Win32OpenSSL.html}{http://www.slproweb.com/products/Win32OpenSSL.html}.
  56 \end{itemize}
  57
  58 Copy the zlib and curl libraries and headers to both GHC and MinGW.  GHC
  59 stores C headers in \verb!<ghc-dir>/gcc-lib/include! and libraries in
  60 \verb!<ghc-dir>/gcc-lib!.  MinGW stores headers in
  61 \verb!<mingw-dir>/include! and libraries in \verb!<mingw-dir>/lib!.
  62
  63 Set PATH to include the \verb!<msys-dir>/bin!, \verb!<mingw-dir>/bin!,
  64 \verb!<curl-dir>!, and a directory containing a pre-built darcs.exe if you
  65 want the build's patch context stored for `\verb!darcs --exact-version!'.
  66
  67 \begin{verbatim}
  68 C:\darcs> cd <darcs-source-dir>
  69 C:\darcs> sh
  70
  71 $ export GHC=/c/<ghc-dir>/bin/ghc.exe
  72 $ autoconf
  73 $ ./configure --target=mingw
  74 $ make
  75 \end{verbatim}
  76
  77 \section{Building from tarball}
  78 If you get darcs from a tarball, the procedure (after unpacking the tarball
  79 itself) is as follows:
  80 \begin{verbatim}
  81 % ./configure
  82 % make
  83 # Optional, but recommended
  84 % make test
  85 % make install
  86 \end{verbatim}
  87
  88 There are options to configure that you may want to check out with
  89 \begin{verbatim}
  90 % ./configure --help
  91 \end{verbatim}
  92
  93 If your header files are installed in a non-standard location, you may need
  94 to define the \verb!CFLAGS! and \verb!CPPFLAGS! environment variables to
  95 include the path to the headers.  e.g. on NetBSD, you may need to run
  96 \begin{verbatim}
  97 % CFLAGS=-I/usr/pkg/include CPPFLAGS=-I/usr/pkg/include ./configure
  98 \end{verbatim}
  99
 100 \section{Building darcs from the repository}
 101 To build the latest darcs from its repository, you will first need a
 102 working copy of Darcs 2. You can get darcs using:
 103 \begin{verbatim}
 104 % darcs get -v http://darcs.net/
 105 \end{verbatim}
 106 and once you have the darcs repository you can bring it up to date with a
 107 \begin{verbatim}
 108 % darcs pull
 109 \end{verbatim}
 110
 111 The repository doesn't hold automatically generated files, which include
 112 the configure script and the HTML documentation, so you need to run
 113 \verb!autoconf! first.
 114
 115 You'll need \verb!autoconf! 2.50 or higher. Some systems have more than one
 116 version of \verb!autoconf! installed. For example, \verb!autoconf! may point to
 117 version 2.13, while \verb!autoconf259!  runs version 2.59.
 118
 119 Also note that \verb!make! is really "GNU make". On some systems, such as
 120 the *BSDs, you may need to type \verb!gmake! instead of make for this to work.
 121
 122 If you want to create readable documentation you'll need to have latex installed.
 123 \begin{verbatim}
 124 % autoconf
 125 % ./configure
 126 % make
 127 % make install
 128 \end{verbatim}
 129
 130 If you want to tweak the configure options, you'll need to run {\tt
 131   ./configure} yourself after the make, and then run make again.
 132
 133 \section{Submitting patches to darcs}
 134 I know, this doesn't really belong in this chapter, but if you're using the
 135 repository version of darcs it's really easy to submit patches to me using
 136 darcs. In fact, even if you don't know any Haskell, you could submit fixes
 137 or additions to this document (by editing \verb!building_darcs.tex!) based
 138 on your experience building darcs\ldots
 139
 140 To do so, just record your changes (which you made in the darcs repository)
 141 \begin{verbatim}
 142 % darcs record --no-test
 143 \end{verbatim}
 144 making sure to give the patch a nice descriptive name.  The
 145 \verb!--no-test! options keeps darcs from trying to run the unit tests,
 146 which can be rather time-consuming.  Then you can send the patch to the
 147 darcs-devel mailing list by email by
 148 \begin{verbatim}
 149 % darcs send
 150 \end{verbatim}
 151 If you are using darcs 2.0.0 or earlier, please use
 152 \begin{verbatim}
 153 % darcs send -u
 154 \end{verbatim}
 155 instead.
 156 The darcs repository stores the email address to which patches should be
 157 sent by default.  The email address you see is actually my own, but when
 158 darcs notices that you haven't signed the patch with my GPG key, it will
 159 forward the message to darcs-devel.
 160