
                     Subcommander, installation guide.
               ============================================

$LastChangedDate: 2007-08-15 09:10:25 -0700 (Wed, 15 Aug 2007) $

Contents:

     I.  Introduction
    II.  Build Notes
      A.  Requirements
       1.  Common
       2.  Unix
       3.  MacOSX
       4.  Windows
      B.  Unix
      C.  MacOSX
      D.  Windows



I.   Introduction

     This document tries to  collect the necessary information  to build
     Subcommander from source.
     
     If  you want  to  build  Subcommander  and the notes  below are not
     enough write to 
          
                         dev@subcommander.tigris.org
                      
     and I will try to fill the gaps in the notes below.
     

     To subscribe to the list send an email to:
     
                     dev-subscribe@subcommander.tigris.org



II.  Build Notes



  A. Requirements
  ===============
  
     1. Common Requirements:
     -----------------------
     
        - Subcommander version 2.0.0+ requires at least Subversion 1.4.4
          or better and everything subversion depends on.
          (neon, openssl, berkeley db (bdb), apr)
          http://subversion.tigris.org
             
          Subcommander expects a full subversion build with ssl. bdb  is
          only required for the Win32  build. Unix and MacOSX  can do do
          without bdb.
          
        - Qt 4.3 ( >= 4.3.0 )
          http://www.trolltech.com
          
        - boost
          http://www.boost.org
       

     2. Unix Requirements:
     ---------------------
     
        If your c++ compiler does have an incomplete stl (like gcc 2.96)
        you will need stlport to build Subcommander.
        
        - stlport
          http://www.stlport.org

        
        System Notes:
        ~~~~~~~~~~~~~

        - Debian based systems

          No boost?
          install the libboost-dev package. You don't need any other
          boost package.
          
          No -lk5crypto?
          install the libkrb5-dev package.

          
     3. MacOSX Requirements:
     -----------------------
     
        - MacOSX 10.3, XCode 1.5
          MacOSX 10.4, XCode 2.x (gcc 3.3)
                                 (gcc 4.x, see section C.)
        
        - Qt 4.3
          Subcommander depends on the native MacOSX version.
          
          
     4. Windows Requirements:
     ------------------------
     
        - Qt 4.3
          patched for MS VS2005, see XXXX
          
        - Compiler
          vs8 c++ compiler (ie. MS VS2005 or MS VS2005 Express)

        - cppunit 1.9.11 or better.
          http://cppunit.sourceforge.net
          only necessary if you want to build the test.

        - Perl
          apr build.
        
        - Python
          subversion build.
        
        - Ruby
          Subcommander build.
        
     
  B. Unix
  =======
  
     If you  downloaded a  source archive  from  subcommander.tigris.org
     simply run the typical
     
     
     ./configure
     make
     make install
     
     
     To build the Subcommander source  from the  repository you have to
     run a few additional steps before you  can run configure, make and
     make install.
     
     ./gen_ac.sh           # this will create the configure script by
                           # running autoconf/automake etc.
                           
     ./gen_version.rb      # this will create sublib/version.out.h and
                           # a few other files which need the version
                           # information. It uses svnversion to extract
                           # the revision number from the working copy.
     
     make install  will copy the binaries to --prefix/bin and  the icons
     to --prefix/share/subcommander/icons.
     
     The binaries are named "subcommander" and "submerge".

     The configure  script  will try to  automatically detect  where the
     necessary libraries are installed on your system.

     If it is unable to automatically detect a library  you have to tell
     configure where it is using one of the --with-<library> options:

     --with-apr
     --with-apr-util
     --with-boost
     --with-subversion
     --with-qt
     --with-neon
     --with-openssl
     --with-berkeley-db
     --with-stlport

     apr, apr-util, subversion and qt are detected at several places.
     
     The qt detection uses $QTDIR to find Qt.  If $QTDIR  is not set you
     have to set --with-qt.
     
     boost, neon, ssl, bdb and  stlport  are only detected  if they  are
     installed in a standard path the compiler knows about.
     
     If you build with nls (i18n) support the gettext tools should be in
     PATH.  

     Building with  stlport links to  stlport_gcc  lib. You may  have to
     patch the library name if you build with a different compiler.

     boost
     ~~~~~
     
     You do not need a complete install of boost. Subcommander is  happy
     with just the path to its sources. You can simply extract boost  to
     a place of your  choice. Enter  the directory (boost-<version>) and
     create an 'include' link that points to the current directory '.'. 
     
     > cd boost-<version>
     > ln -s . include

     After that you can give the source path to Subcommanders  configure
     script.


     startup
     ~~~~~~~
     
     You  will   have  to   install  Subcommander   before  running  it.
     subcommander looks  for its   icons  and  the submerge   binary  in
     the  --prefix   path.   It  will    not   find  them  if  you   run
     subcommander  from  the  build  directory  (without  a  prior  make
     install).
      
 
  C. MacOSX build
  ===============
  
     You can follow the Unix/Linux build description for configure   and
     make. But do NOT run make install.
     
     After make finished successfully run 
     
     make bundle
     
     to create the MacOSX bundles subcommander.app and submerge.app.
     
     The bundles are created in the folder dist/macosx/Subcommander.
     
     make image
     
     will create a disk image from dist/macosx/Subcommander.
    
       
  D. Windows build
  ================
  
     Generally, setting up the build environment on Windows is a painful
     job. :-(

     Building on Windows involves a couple of steps for each dependency.
     I will try to collect the steps here. Currently it is not complete.
     

  
     apr, apr-iconv, apr-util
     ~~~~~~~~~~~~~~~~~~~~~~~~
 
     Step 1:    
     Download the latest apr, apr-iconv, and apr-util versions and unzip
     the archives side by side.
     
     Step 2:
     If you want to build with berkeley db support you have to tell
     apr-util where it can find the bdb header file and lib files with
     the w32locatedb.pl script in the build folder:

     .\build\w32locatedb.pl dll <bdb include path> <bdb lib path>
     
     Step 3:
     Apply the small patch apr-iconv.patch from Subcommanders doc folder
     to apr-iconv/lib/iconv_module.c.

     This patch will make sure that subcommander and submerge use "our"
     iconv modules and not those from another program.
     
     Step 4:
     Remove the version info from the folders, ie. rename apr-1.2.8 to
     apr and so on. Step 5 won't find the visual studio project files
     with the version numbers in the folder names.
     
     Step 5:
     Build by openening the .dsw file in apr-util. It will also build
     apr and apr-iconv.
     
     It will build the static lib into the folders LibD/LibR and the
     dlls into the folder Debug/Release.
     
     
     berkeley db
     ~~~~~~~~~~~
     
     Follow the build instructions.
     
     
     openssl
     ~~~~~~~
     
     Follow the build instructions.
     
     zlib
     ~~~~

     build zlibstat.lib, zlibstatd.lib
     
     
     neon
     ~~~~
     
     patch neonmak to use zlibstat.lib, zlibstatd.lib
     
     Build neon debug and release like this:
     
     nmake /f neon.mak
       EXPAT_INC=..\apr-util-1.2.8\xml\expat\lib
       OPENSSL_SRC=..\httpd-2.2.3\srclib\openssl
       ZLIB_SRC=..\zlib-1.2.3
       
     To build the debug version add  the option DEBUG_BUILD=yes
     
     
     gettext
     ~~~~~~~
     
     Uhhh, that one is tricky.. requires patching the gettext build.
     
     ..gettext-runtime\intl>nmake -f Makefile.msvc MFLAGS=-MD DLL=1     
     ..gettext-runtime\intl>nmake -f Makefile.msvcd MFLAGS=-MDd DLL=1     
     
     subversion
     ~~~~~~~~~~
     
     Follow subversions build instructions. Basically this is running
     gen_make.py with the options to set the paths to the dependencies.
     This will look like this:
     
     gen-make.py -t vcproj --vsnet-version=2005
      --with-berkeley-db=G:\Development\db-4.3.29-vc8
      --with-openssl=G:\Development\httpd-2.2.3\srclib\openssl
      --with-zlib=G:\Development\zlib-1.2.3
      --enable-nls
      --with-libint=G:\Development\gettext-0.14.5-vc8

     It creates visual studio project files and a solution. The solution
     doesn't really work. Currently I remove apr, apr-util, apur-iconv,
     zlib and neon and then fix the link issues (debug release crt) by
     hand.
     
     At least svns zlib project is broken. It builds debug and release
     in the same folder. This leads to debug and release versions which
     are linked bothe to same (debug or release) runtime. Because the
     object files are already there the second build will not build
     anything and just reuse the existing object files.
     
     
     boost
     ~~~~~
     
     Just unpack the zip. You do NOT have to build it. Subcommander only
     requires header files from boost.
        
     
     Subcommander
     ~~~~~~~~~~~~
     
     Finally... :-)
  
     The Windows build requires  all dependencies in a  "libs" subfolder
     in the subcommander source root folder. This should look like this:
     
     libs/apr                root dir of apr        source tree
          apr-iconv          root dir of apr-iconv  source tree
          apr-util           root dir of apr-util   source tree
          boost              root dir of boost      source tree
          openssl            root dir of openssl    source tree
          subversion         root dir of subversion source tree
          neon               root dit of neon       source tree
          gettext            root dir of gettext installation
          qt                 root dir of qt installation
          db4                create this directory layout by copying the
            /include         files from the bdb build dirs.
              db.h
            /lib
              libdb42.lib
              libdb42d.lib

     The easiest way to create this is to use Windows junction points.

     Run the ruby script gen_version.rb  from the root source folder  to
     create  sublib/version.out.h.  If  you don't   have  ruby  you  can
     simply copy sublib/version.in.h to sublib/version.out.h.

     Open sc.sln with VC8 and build...
