building and installation process for monotone
==============================================

1. prerequisites:

  * hardware prerequisites:

    - g++ consumes a lot of memory building monotone, due to
      monotone's liberal use of C++ features. it may be possible to
      build on a system with 128mb of memory, but not pleasant. we are
      working on making this situation better.

  * software prerequisites:

    - autoconf
    - automake
    - gettext
    - a supported C++ compiler: g++ 3.2 or later
    - boost 1.33.0 or later: either an installed copy or an extracted
      tarball of its unbuilt sources somewhere in the file system are
      supported
    - zlib 1.1.4 or later
    - libiconv if the iconv() function is missing
    - texinfo (to build the documentation)
    - Botan 1.6.3 or later (Botan might require bzip2, OpenSSL and / or
      GnuMP in addition, depending on the package you're using.)
    - PCRE 7.4 or later
    - SQLite 3.3.8 or later
    - Lua 5.1
    - GNU IDN Library

        on Debian and Ubuntu:

           install the following packages:
             autoconf automake gettext g++ libboost-dev libz-dev
             libbotan1.8-dev libsqlite3-dev libpcre3-dev liblua5.1-0-dev
             libidn11-dev texinfo

           (On etch, you may need to use libbotan1.8 from lenny.)

        on FreeBSD:

           install the following packages from the ports collection:
             databases/sqlite3 devel/automake1.9 devel/boost devel/gettext
             devel/gmake devel/pcre lang/lua security/botan

        on Gentoo:

           emerge the following packages:
             autoconf automake boost botan gettext libpcre libidn lua sqlite
             zlib

           (you might need to add the "~x86" flag to dev-libs/botan, so you
            get at least version 1.6.3, we recommend using at 1.8.0 or newer)

        on Fedora:

           install the following packages:
             autoconf automake gettext boost boost-devel zlib zlib-devel
             lua lua-devel pcre pcre-devel sqlite sqlite-devel libidn
             libidn-devel gcc-c++ texinfo texinfo-tex botan botan-devel

        on Mac OS X:

           use MacPorts (http://www.macports.org) to install the following
           packages:
             autoconf automake gettext boost zlib lua pcre botan
             sqlite3 libidn libiconv texinfo

           monotone only uses header-only libraries from boost, so if you don't
           like to spend a lot of time building boost via MacPorts, you can also
           download and extract it manually and let CXXFLAGS point to the
           include/ directory of the extracted version.

        on Windows (using MinGW):

           tools and packages needed:

           Package  | Version | URL
           --------------------------
           MingGW   | 5.1.3   | http://prdownloads.sf.net/mingw/MinGW-5.1.3.exe?download
           MSYS     | 1.0.10  | http://prdownloads.sf.net/mingw/MSYS-1.0.10.exe?download
           msysDTK  | 1.0.1   | http://prdownloads.sf.net/mingw/msysDTK-1.0.1.exe?download
           libiconv | 1.11    | http://prdownloads.sf.net/mingw/libiconv-1.11-mingwPORT-20070423-1.tar.bz2?download
           autoconf | 2.59    | http://prdownloads.sf.net/mingw/autoconf-2.59-mingwPORT.tar.bz2?download
           automake | 1.9.5   | http://prdownloads.sf.net/mingw/automake-1.9.5-mingwPORT.tar.bz2?download
           zlib     | 1.2.3   | http://prdownloads.sf.net/mingw/zlib-1.2.3-mingwPORT.tar.bz2?download
           gettext  | 0.16.1  | ftp://aeneas.mit.edu/pub/gnu/gettext/gettext-0.16.1.tar.gz
           boost    | 1.34.1  | http://prdownloads.sf.net/boost/boost_1_34_1.tar.bz2?download
           Lua      | 5.1     | http://www.lua.org/
           pcre     | 7.8     | http://www.pcre.org/
           botan    | 1.8     | http://botan.randombit.net/news/
           sqlite3  | 3.6.10  | http://www.sqlite.org/download.html - sqlite-amalgamation-3_6_10.tar.gz, with makefile
           libidn   | 1.9     | ftp://ftp.gnu.org/gnu/libidn

           The installer defaults put MinGW in `c:\MinGW` and MSYS in
           `c:\Msys`. However, later steps sometimes install new items
           in `c:\MinGW\bin`, and sometimes in `c:\Msys\bin`. So it is
           difficult to ensure that the new items are always first in
           path. Installing MinGW and MSYS both to `c:\MinGW` avoids
           this issue. However, in this case the MSYS installer
           mistakenly renames 'make' to 'mingw32-make', so we need to
           change it back.

           msysDTK installs Perl, CVS, crypt, and other tools needed
           by the autoconf tools. The installed autoconf scripts are a
           little broken, so we need to manually fix them.

           1. MinGW - install, accept defaults but add g++ on the package selection page
           2. MSYS - install to same directory as MinGW (`c:\MinGW`), otherwise accept defaults
           3. msysDTK - install into MinGW directory
           4. Rename `make`:
              $ mv /bin/mingw32-make.exe /bin/make.exe

           5. libiconv
              $ cd /usr/src
              $ export SRCROOT=/usr/src
              $ tar jxf libiconv-1.11-mingwPORT.tar.bz2
              $ cd libiconv-1.11/mingwPORT
              $ ./mingwPORT.sh

           6. Accept all defaults by hitting the enter key. The following steps also always accept all defaults.

           7. autoconf
              $ cd /usr/src
              $ tar jxf autoconf-2.59-mingwPORT.tar.bz2
              $ cd autoconf-2.59/mingwPORT
              $ ./mingwPORT.sh

           8. Open `/mingw/bin/autoconf` in an editor and change the following line from something like

              : ${AUTOM4TE='c:/mingw/bin/autom4te'}

              to

              : ${AUTOM4TE='/mingw/bin/autom4te'}

           9. automake
               $ cd /usr/src
               $ tar jxf automake-1.9.5-mingwPORT.tar.bz2
               $ cd automake-1.9.5/mingwPORT
               $ ./mingwPORT.sh

           10. Open the files `/mingw/bin/aclocal`,
               `/mingw/bin/aclocal-1.9`, and all files matching
               `auto*` in an editor and delete `c:/` from all paths,
               as was done above for `autoconf`.

           11. zlib
               $ cd /usr/src
               $ tar jxf zlib-1.2.3-mingwPORT.tar.bz2
               $ cd zlib-1.2.3/mingwPORT
               $ ./mingwPORT.sh

           12. gettext
               $ cd /usr/src
               $ tar zxf gettext-0.17.tar.gz
               $ cd gettext-0.17
               $ ./configure --prefix=/usr/local
               $ make install

           13. boost; only need headers
               $ cd /usr/src
               $ tar jxf boost_1_34_1.tar.bz2
               $ cd boost_1_34_1
               $ cp -a boost /mingw/include

           14. Lua
               $ cd /usr/src
               $ tar zxf lua-5.1.4.tar.gz
               $ cd lua-5.1.4
               $ make mingw
               $ make install

           15. pcre
               $ cd /usr/src
               $ tar zxf pcre-7.8.tar.gz
               $ cd pcre-7.8
               $ ./configure
               $ make install

           16. botan
               $ cd /usr/src
               $ tar zxf Botan-1.8.0.tgz
               $ cd Botan-1.8
               $ ./configure.pl --with-tr1=none
               $ make install

           17. sqlite3
               $ cd /usrsrc
               $ tar zxf sqlite-amalgamation-3_6_10.tar.gz
               $ cd sqlite-amalgamation-3.6.10
               $ ./configure
               $ make install

           18. libidn
               $ cd /usr/src
               $ tar zxf libidn-1.9.tar.gz
               $ cd libidn-1.9
               $ ./configure
               $ make install

            cd monotone
            ./configure lua_CFLAGS=-I/usr/local/include lua_LIBS="-L/usr/local/lib -llua" \
                        sqlite_CFLAGS=-I/usr/local/include sqlite_LIBS="-L/usr/local/lib -lsqlite3" \
                        idn_CFLAGS=-I/usr/local/include idn_LIBS="-L/usr/local/lib -lidn"

           # Notes

           * If the `./configure` step of the monotone build fails
             claiming your system is unrecognized while checking the
             build system type, it may be caused by `uname -s`
             returning a string containing MSYS rather than MINGW.
             This indicates that your build environment is in a
             special mode for producing MSYS binaries, which is not
             what you want when building monotone. See
             [MsysBuildEnvironment](http://www.mingw.org/MinGWiki/index.php/MsysBuildEnvironment)
             for a detailed explanation.

             * If you get strange errors from perl when running
               `autoreconf -i`, check that you edited the paths
               correctly in `aclocal-*` and `auto*`.

        on Windows (using Cygwin):

           Monotone needs the following packages to compile:

             Runtime requirements:
               cygwin-1.5.24 or newer
               libiconv2-1.11 or newer
               libintl8-0.15 or newer
               zlib-1.2.3-2 or newer

             Build requirements:
               gcc-3.4.4 or newer
               binutils-20050610 or newer
               boost-devel-1.33.1 or newer
               gettext-0.14.5 or newer
               zlib-1.2.3-2 or newer
               perl-5.8.7 or newer
               sqlite3-3.6.2-1 or newer
               libidn-devel-1.9-1 or newer
               lua-5.1.4-1 or newer (*)
               botan-1.8.0-1 or newer (*)
           
           currently every prerequisite is avaialble as packages except
           lua and botan; an official Cygwin package for monotone and 
           all its dependencies will be available soon after release

           the following is needed to succesfulyl configure
             CXXFLAGS+="-I/usr/include/boost-1_33_1/"

        on other systems:

           check your system package repository, you may need to
           build some of these from source. if your package repository
           does not contain the libraries, see:

                http://gcc.gnu.org/                  for g++
                http://www.boost.org/                for Boost
                http://www.pcre.org/                 for PCRE
                http://www.lua.org/                  for Lua
                http://www.sqlite.org/               for SQLite
                http://botan.randombit.net/          for Botan
                http://www.gnu.org/software/libidn/  for GNU IDN

1.1 using boost in the build process:

  monotone uses the boost libraries in multiple parts of its code.
  fortunately, it only uses the so-called header-only libraries: these
  can be used very easily from other projects, as there is no need to
  build them by hand prior usage.

  therefore you can use an installed version of boost if shipped with your
  distribution but, if you do not want to mess with the Boost.Build build
  system (which is hard to deal with for beginners), you can simply use an
  extracted copy of the boost sources.  the two procedures are detailed
  below:

  * if your system already has the boost development libraries installed,
    you must tell the compiler where to find them.  their location will
    usually be somewhere under /usr/include.  try the following command:

      ls -d /usr/include/boost*

    if the command shows a single directory named 'boost', you do not have
    to take any extra steps.  configure will automatically find the
    necessary files.  instead, if the command shows a directory name of the
    form boost_1_33_1, boost-1.33.1 or similar, you will have to pass that
    to the configure script.  do so as follows:

      ./configure CPPFLAGS="-I/usr/include/boost-1.33.1"

    if no directories are shown, look for prebuilt boost packages for your
    system and install them.  if there aren't any, resort to the procedure
    described in the following point.

  * if you do not have boost already installed, and you cannot easily
    install it from prebuilt packages, fetch a copy of the boost sources
    from their site (see previous section) and unpack them somewhere in
    your system -- for example, your home directory.  once done, tell the
    configure script where the files are:

      ./configure CPPFLAGS="-I${HOME}/boost-1.33.1"

  it is important to note that, once monotone is built, you can get rid of
  all the boost sources or boost development packages from your system.
  the required header-only libraries will have been built into the final
  binary, which will not rely on any binary boost library.  in some sense,
  you can think of it as static linkage.

2. configuring monotone:

  * if there is no ./configure script in your source tree you'll need
    to create one before proceeding to the next step. one of the
    following auto* commands should work:

        $ aclocal-1.9 && autoreconf --install
        $ AUTOMAKE=automake-1.9 ACLOCAL=aclocal-1.9 autoreconf --install

    If this fails early, check that you have gettext packages installed.

  * type "./configure" for a basic configuration of monotone.  several
    configuration options are available; type "configure --help" for a
    list of all of them. some special options are shown here:

     --enable-ipv6[=auto|no|yes]

       specify whether IPv6 support has to be enabled or disabled.  the
       default is to try automatic detection (auto) and use the guessed
       results.  however, you can force IPv6 detection by saying 'yes'
       or completely disable it using 'no'.

     --disable-nls

       build a version of monotone without support for local message
       catalogs. you might like to do this if you do not have a
       working installation of GNU gettext.

     --enable-pch

       this will enable precompiled headers, which should improve compile
       time. some versions of gcc have problems with this option, so
       try disabling it if you run into trouble.

3. building monotone

  * type "make" to invoke GNU make (please notice it might be named
    "gmake" on systems where system make is not GNU make).
    this should produce a mtn binary in your current directory.
    if not, please send a build log to
    monotone-devel@nongnu.org with a description of the failure.

4. testing monotone

  * there is a "make check" target which you can try, if you'd like to
    confirm monotone's functionality on your system.
    Do not run "make check" as root (Unix)!  Doing so will cause the
    failure of some of the tests!
    Also, make sure your testing process has enough memory.  Experience
    has shown that some tests may fail "mysteriously" when there is too
    little memory.  A possible hint is that 128MB was too little on
    FreeBSD 6 on x86 while 256MB was enough.

    You might also like to try fetching monotone's sources from our
    monotone server. this process will transfer the complete development
    history (about 70 megabytes) to your database, and you will then
    be free to share it with others or make changes and submit them to
    us:

        mtn --db=mt.mtn db init

        mtn --db=mt.mtn pull monotone.ca net.venge.monotone

        mtn --db=mt.mtn --branch=net.venge.monotone checkout monotone-sources

5. upgrading

  * if you have an existing monotone installation, you may need to
    perform some additional steps to migrate your data to the newest
    version; see the file UPGRADE for details.

