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

$LastChangedDate: 2006-08-23 08:59:03 +0200 (Wed, 23 Aug 2006) $

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:
     -----------------------
     
        - Subversion 1.2.0 or better and anything 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.
          
        - Qt3 ( >= 3.2+ and < 4.0, ie. 3.2.x or 3.3.x)
          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.)
        
        - Qt3
          Subcommander depends on the native MacOSX version.
          
          
     4. Windows Requirements:
     ------------------------
     
        - Qt3
          As far as I know, the  only way to get the 3.2  Non-Commercial
          Windows version is to buy  the book "C++ GUI Programming  with
          Qt 3".
          
        - 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.

     
  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 "sc" (subcommander) and "sm" (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.
     
     
     building with GCC 4
     ~~~~~~~~~~~~~~~~~~~
     
     To build Subcommander with gcc 4.x  you will have to  make a  small
     tweak to the generated makefile in util subdirectory:

     Replace 

     DEFAULT_INCLUDES =  -I. -I$(srcdir) -I$(top_builddir)

     with

     DEFAULT_INCLUDES =  -iquote. -iquote$(srcdir) -I$(top_builddir)


     After this small change  Subcommander should build without  errors.
     If you like to know why this  is necessary read on. If not you  can
     skip the rest of this section.

     The issue with GCC4 is 
       - the case insensitive MacOSX file system
       - the -I. include option added by autoconf/automake
       - the String.h header in the util subdirectory


     The  gcc  documentation states  that  directories named  by  the -I
     option are searched before the standard system path.

     The autoconf/automake universe adds an -I. .

     util contains a file String.h


     apr wants to include the system string.h header

     .. /Users/hauner/svn-1.3.1-static-nls-4/include/apr-1/apr_want.h
     ... /Users/hauner/svn-1.3.1-static-nls-4/include/apr-1/apr.h
     ... /usr/include/string.h


     with gcc 4.0 it includes

     .. /Users/hauner/svn-1.3.1-static-nls-4/include/apr-1/apr_want.h
     ... /Users/hauner/svn-1.3.1-static-nls-4/include/apr-1/apr.h
     ... ./string.h


     Because  it  doesn't  care  that  "string.h"  and  "String.h"  have
     different case it loads the wrong header.


     This should happen with gcc 3.x too but it does not.

     Looks like gcc 3 does check the include files case sensitive  while
     gcc 4 does not check them case sensitive.
     
    
       
  D. Windows build
  ================
  
     1. Apply doc/apr-iconv.patch to apr-iconv/lib/iconv_module.c.
        This patch will  make sure that  we use "our"  iconv modules and
        not those from another program (like TortoiseSVN..).
        
     2. Build Subversion.
        See  subversions INSTALL  file and  build  subversion  with nls,
        openssl and zlib.
     
     3. Build Subcommander
  
     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
          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...
