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:

    - a supported C++ compiler: g++ 3.2 or later.
    - an installed copy of boost 1.32.0 or later.
    - zlib 1.1.4 or later.

        on debian: 

           apt-get install libboost-filesystem-dev
           apt-get install libboost-regex-dev
           apt-get install libboost-test-dev
           apt-get install libboost-dev
           apt-get install g++

        on fedora: 

           apt-get install boost-devel 
           apt-get install g++

        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

1.1 building boost:

  many people have reported difficulty building boost. the main
  problem is that boost builds with an unorthodox build tool called
  "bjam" which must, itself, be built or installed before boost can be
  built. the bjam sources are contained within the boost distribution,
  but somewhat hidden. there are instructions on
  http://www.boost.org/more/getting_started.html, but we have
  assembled this abbreviated bourne shell sequence for advanced users
  who do not need all the preamble:

    wget http://internap.dl.sourceforge.net/sourceforge/boost/boost_1_33_1.tar.gz
    tar -xzf boost_1_33_1.tar.gz
    cd boost_1_33_1
    (cd tools/build/jam_src && ./build.sh)
    BJAM=`find tools/build/jam_src/ -name bjam -a -type f`
    $BJAM "-sBUILD=release <threading>single <optimization>speed <runtime-link>static"
    for i in `find bin -type d -a -name \*.a`; 
      do for j in `find $i -type f -a -name \*.a`; 
        do mv $j libs/`basename $i`; 
      done; 
    done
    ranlib libs/*.a

  if this completes successfully, you will have a selection of boost
  libraries in boost_1_33_1/libs and boost headers in
  boost_1_33_1/boost. you can then either copy the .a files to your
  standard library path and the directory "boost_1_33_1/boost" to your
  standard include path, or you can pass additional configuration
  options to your monotone configure build, such as:

    ./configure CPPFLAGS="-Iboost_1_33_1" LDFLAGS="-Lboost_1_33_1/libs"

  monotone does not use all of boost -- for instance, people often
  have trouble building boost.python, which we do not use.  you don't
  need to build any libraries that we don't use!

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'.

     --enable-static-boost[=prefix]

       this will attempt to link a "mostly static" version of monotone
       using the .a files supplied with your installation of
       boost. the resulting binary will be larger but more portable
       than a normal (dynamic) link.

       you can optionally pass a prefix to the option, which will be
       used to look for the static libraries; otherwise a list of
       predefined directories will be used.  for example:

         ./configure --enable-static-boost=/usr/local/boost

     --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.

     --disable-large-file

       this will disable large file support from the builtin sqlite, to
       achieve maximum binary compatibility with old systems.

     BOOST_SUFFIX=string

       this variable, to be set on configure's command line, can be used
       to specify a special string suffix to be appended to boost library
       names.  many Linux distributions provide symlinks to hide this
       suffix, but others do not.  therefore, you need to pass it to the
       configure script through this variable for correct detection of
       boost.  for example:

         ./configure BOOST_SUFFIX=-gcc

       note that, sometimes, the configure script will be able to guess
       the correct suffix by itself.

     --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". 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!

    You might also like to try fetching monotone's sources from our
    monotone server. this process will transfer the complete development
    history (about 40 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 venge.net "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.

