comparison kdiff3/README @ 80:fcd146072e0c

0.9.93

 KDiff3-Readme
 =============
 
 Author: Joachim Eibl  (joachim.eibl at gmx.de)
-Copyright: (C) 2002-2006 by Joachim Eibl
-KDiff3-Version: 0.9.92
-
+Copyright: (C) 2002-2008 by Joachim Eibl
+KDiff3-Version: 0.9.93
+
+KDiff3 runs best on KDE but can be built without it, depending only on Qt-libs.
+These are available for Un*x, Windows, Mac.
+Thus there are many setup possibilities to consider.
+
+From version 0.9.93 on the main target platform is KDE4/Qt4.
+For KDiff3 for KDE3/Qt3 use KDiff3-0.9.92 or older.
+
+Contents
+--------
+
+- Introduction
+- License
+- Requirements & Installation
+  - For KDE4
+  - With Qt4-libs, without KDE
+    - for Linux/Un*x
+    - for Windows
+    - Debugging with MinGW under Windows:
+    - for Mac: Building KDiff3 for Mac OSX (with Intel processor) as a universal binary
+- Additional hints
+
+
+Introduction
+------------
 
 KDiff3 is a program that
 - compares and merges two or three input files or directories,
 - shows the differences line by line and character by character (!),
 - provides an automatic merge-facility and
 - an integrated editor for comfortable solving of merge-conflicts
-- has support for KDE-KIO (ftp, sftp, http, fish, smb)
-- and has an intuitive graphical user interface,
-- also supports 64 bit systems. (Some build issues are discussed in here.)
-
+- has support for KDE-KIO (ftp, sftp, http, fish, smb),
+- has an intuitive graphical user interface,
+- provides a context menu for KDE-Konqueror and Windows-Explorer,
+- supports 64 bit systems. (Some build issues are discussed in here.)
 
 Do you want help translating? Read the README in the po-subdirectory!
 
 
-License:
+License
+-------
+
     GNU GENERAL PUBLIC LICENSE, Version 2, June 1991
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.

 
     For details see file "COPYING".
 
 Exception from the GPL:
     As a special exception, the copyright holder Joachim Eibl gives permission
-    to link this program with the Qt-library (commercial or non-commercial edition)
+    to link this program with the Qt-library (commercial or open source edition)
     from Trolltech (www.trolltech.com), and he permits to distribute the resulting
     executable, without including the source code for the Qt-library in the
     source distribution.
 
 
-Requirements & Installation:
-   Version 0.9.91 provides special support for KDE3, but it can also be
-   built without KDE3 if the Qt-libraries are available.
-   (I also test and use the program under Windows.)
-   It is now also possible to build with Qt4 (See further below).
+Requirements & Installation
+---------------------------
+
+- for KDE4:
+   From version 0.9.93 on KDiff3 supports KDE4.
+   For installation on most distributions you usually also require these packages (names as on opensuse):
+   - g++ (g++, version 3.4 or newer)
+   - libqt4-devel (Qt4-libs, version 4.4.0 or newer)
+   - libkde4-devel (KDE4 Header files and development libraries)
+   - libkonq-devel (optional, needed for the kdiff3-plugin, if not installed 
+                    then the contextmenu plugin for konqueror won't be built.)
+   - cmake (>2.6, checks dependencies and creates the Makefiles appopriate for your system)
+
+   Typically in a terminal (e.g. konsole) you cd into the kdiff3-directory and run these commands.
+
+      mkdir release                                  # create sub directory
+      cd release                                     # cd into that directory
+      kde4-config --prefix                           # Find out your KDE4-directory and note the result
+      cmake .. -DCMAKE_INSTALL_PREFIX=<KDE4-prefix>  # create Makefile, replace <KDE4-prefix> with the prior result
+      make                                           # run make (compile and link)
+      sudo make install                              # install as root user
+
+   Now KDiff3 should be ready to use. Type "kdiff3" to start it.
+   There should also be a entry in your KDE-start menu in "(Applications->)Development".
+
+   For creating a debug version:
+      mkdir debug
+      cd debug
+      kde4-config --prefix                           # Find out your KDE4-directory and note the result
+      cmake .. -DCMAKE_INSTALL_PREFIX=<KDE4-prefix>  -DCMAKE_BUILD_TYPE=debugfull
+      make
+      sudo make install
+
+   The <KDE4-prefix> depends on your distribution:
+   The command "kde4-config --prefix" should tell you.
+   - For opensuse 11 use "/usr".
+
+- Building KDiff3 with Qt4-libs, but without KDE
+    - for Linux/Un*x
+    - for Windows
+    - for Mac
+
+   The version 0.9.93 requires Qt 4.4.0 or newer (from www.trolltech.com) for compilation. 
 
    You always need
-      - kdiff3-0.9.91.tar.gz
-
-   For building the KDE3-version
-      - KDE>=3.3 and QT>=3.3-libraries. (but not with KDE4)
-      - gcc, g++ with version >=3.2
-
-   For building the Qt-only-version
-      - QT-libraries (version >=3.3.0, but <4.0 or >=4.2.0).
-        (www.trolltech.com)
-      - for Un*x:    gcc, g++ with version >=3.2
-      - for Windows: VC6 / VC7.1
-
-   On some distributions it will be necessary to install developer
-   packages (RPMs) that contain include files for compilation:
-      - xorg-x11-devel (or x11-devel)
-      - qt-devel
-      - kdelibs-devel
-
-Installation for KDE3:
-   - Make sure your shell-variable QTDIR is correct. (echo $QTDIR).
-     If it doesn't contain the correct path, type
-        export QTDIR=your_path_to_qt  (e.g. /usr/lib/qt3)
-   - cd into the directory kdiff3-0.9.91 and type
-   - ./configure --prefix=/opt/kde3           (your KDE3 directory here)
-   - (make clean)                    (Required if you already compiled once.)
-   - make                            (Run compilation)
-   - make install                    (You must have root-rights for this step.)
-
-   For details also see the generic instructions in file "INSTALL".
-
-   If some icons are not visible or don't seem right, probably the prefix
-   was wrong. Check where your KDE3 installation is located and
-   use that directory with the prefix-option of configure.
-
-   This command should tell you: kde-config --prefix
-
-   For SuSE and most distributions the prefix usually is /opt/kde3.
-   For Redhat/Fedora and Mandrake the prefix usually is /usr.
-   For a local installation, that doesn't need root rights try
-   - ./configure --prefix=$KDEHOME  ($KDEHOME probably is the same as $HOME/.kde)
-   - make
-   - make install    (Installs everything in $KDEHOME. No root rights required.)
-   - Run $KDEHOME/bin/kdiff3. ($KDEHOME/bin is probably not in your path.)
-   Warning: If a local installation and a global installation exist, the local
-            menu, toolbar, help etc. will be used, even if you start the global
-            executable. To avoid confusion, better remove the local version then.
-            (rm -R `find $KDEHOME -name "*kdiff3*" -not -name "kdiff3*rc"`)
-
-   On Fedora-64-bit systems the following configure-line was reported to work:
-   ./configure --prefix=`kde-config --prefix` --enable-libsuffix=64 --with-qt-libraries=/usr/lib64/qt-3.3/lib/
-   Both --enable-libsuffix=64 and -with-qt-libraries=/usr/lib64/qt-3.3/lib/ are needed;
-   without the first one it fails to find the KDE libraries,
-   and without the second one it fails to find libqt-mt
-   (strangely enough: libqt-mt is in /usr/lib64/qt-3.3/lib, 
-   and "configure" tries /usr/lib64/qt-3.3/lib64)
-   If your qt-libraries are elsewhere please adapt the path accordingly.
-
-   Some secondary dependencies aren't correctly discovered by configure.
-   If e.g the a linker error appears telling you something like
-   "Can't find -lacl" this probably means that you have to install 
-   libacl-devel-*.rpm etc.
-
-   If you run an older version of KDE and the make-process fails in the
-   doc- or po-directory, cd to the src-directory and run "make" there. Also run 
-   "make install" there. This hopefully will create a working kdiff3-binary,
-   although without doc and language support.
-
-Upgrading KDiff3 for KDE:
-   If you already installed an older version or KDiff3 and you have the 
-   impression, that the new version doesn't work as described, you should try to 
-   remove all files belonging to KDiff3 before reinstalling. 
-   Try this search command to locate KDiff3-related files:
-      find $HOME/.kde /usr /opt -iname "*kdiff3*"
-   (Will take a few minutes.)
-
-
-Building an RPM for Fedora Core (by Vadim Likhota)
-   Copy kdiff3-0.9.91.tar.gz into /usr/src/redhat/SOURCE
-   Copy kdiff3.spec into /usr/src/redhat/SPEC
-   Run rpmbuild -bb --target i686 kdiff3.spec
-   Find kdiff3-0.9.91-fc.i686.rpm in /usr/src/redhat/RPMS/I386
-
-
-Installation for the Qt-only-platforms for Un*x:
-   (for Qt >=3.3.0 but <4.0)
-   - Make sure your shell-variable QTDIR is correct. (echo $QTDIR).
-     If it doesn't contain the correct path, type
-        export QTDIR=your_path_to_qt  (e.g. /usr/lib/qt)
-   - cd into the directory kdiff3-0.9.91/src and type
-   - make -f Makefile.qt
-   - make -f Makefile.qt install     (You must have root-rights for this step.)
-     (copies the files into /usr/local/bin and /usr/local/share/doc/kdiff3)
-   - Note: The file kdiff3.pro was used to generate the Makefile.qt:
-           qmake kdiff3.pro -o Makefile.qt
-   If you want to build the Qt-only version _and_ the KDE-version, do this
-   in separate directories, otherwise there will be errors. 
-   - A user reported that on his 64-bit machine running FC4 he had to edit his Makefile.qt
-     LIBS = $(SUBLIBS) -L/usr/lib64/ -L$(QTDIR)/lib64/ -L/usr/lib -L$(QTDIR)/lib/ -L/usr/X11R6/lib/ -L/usr/X11R6/lib64/ -lqt-mt -lXext -lX11 -lm -lpthread 
- 
-
-Build for Windows:
- Use qmake and kdiff3.pro to generate
- an appropriate Makefile.
-     qmake kdiff3.pro -o Makefile
-
-
-Building KDiff3 (Qt3) for Mac OSX 10.3.8 (by Mark Teel)
--------------------------------------------------------
-   1) Install Qt/Mac with thread support and static libraries.
-   2) cd .../kdiff3-0.9.91/src
-   3) Create a makefile for kdiff3 by executing:
-      qmake kdiff3.pro -o Makefile.qt
-   4) Edit Makefile.qt and change the include path like so:
-      (old) INCPATH  = -I/Library/qt3/mkspecs/default -Isrc ...
-      (new) INCPATH  = -I/Library/qt3/mkspecs/macx-g++ -Isrc ...
-   5) Execute:
-      make -f Makefile.qt
-   6) After the build completes copy kdiff3 from the kdiff3-0.9.91/src directory to
-      /Applications
-
-Building KDiff3 (Qt4) for Mac OSX (with Intel processor) as a universal binary (by Michael Schmidt)
----------------------------------------------------------------------------------------------------
-   1) Install Qt/Mac 4.x with thread support, static libraries and universal flag.
-   2) cd .../kdiff3-0.9.91/src-QT4
-   3a) Create a makefile for kdiff3 by executing:
-      qmake kdiff3.pro
-   3b) optionally generate XCode-Project (for debugging purposes only) by executing:
-      qmake -spec macx-xcode kdiff3.pro
-   4) Execute:
-      make
-   5) After the build completes copy kdiff3 from the kdiff3-0.9.91/src-QT4 directory to
-      /Applications
-
-----------------------------------------------------------------
-
-Building KDiff3 with Qt4:
-
-Requirements & Installation:
-   The version 0.9.91 requires Qt 4.2.0 (from www.trolltech.com) for compilation. 
-
-   You always need
-      - kdiff3-0.9.91.tar.gz
+      - kdiff3-0.9.93.tar.gz
 
       - for Un*x:    gcc, g++ with version >=3.4.2
                      Qt-X11-libraries
 
       - for Windows: Qt-win-libs
-                     If you have the Qt4 commercial edition, then compile with Visual Studio.
+                     If you have the Qt4 commercial edition, then compile with Visual Studio.NET2003 or newer.
                      If you use the Qt4 open source edition, then you'll need MinGW.
                      I verified that compilation and debugging works with these packages (probably newer ones will also work):
-                     - gcc-core-3.4.2-20040916-1.tar.gz  
-                     - binutils-2.15.91-20040904-1.tar.gz  
-                     - gcc-g++-3.4.2-20040916-1.tar.gz   
-                     - mingw-runtime-3.9.tar.gz 
-                     - mingw32-make-3.80.0-3.tar.gz 
-                     - w32api-3.6.tar.gz (see also the note below)
-                     - gdb-5.2.1-1.exe (for debugging)
- 
-                     (Note: At the time of writing this README, the MinGW-package that was part
-                     of qt-win-opensource-4.1.2-mingw.exe lacked the latest w32api needed for 
-                     KDiff3-compilation. You will need to unpack w32api-3.6.tar.gz or newer
-                     from www.mingw.org into your MinGW-directory.)
+                     - Use MinGW-5.1.4.exe or newer to install the following or newer:
+                       - gcc-core-3.4.5-20060117-1.tar.gz
+                       - binutils-2.17.50-20060824-1.tar.gz
+                       - gcc-g++-3.4.5-20060117-1.tar.gz
+                       - mingw-runtime-3.14.tar.gz
+                       - mingw32-make-3.81-2.tar.gz
+                       - w32api-3.11.tar.gz
+                     - gdb-6.3-2.exe (for debugging)
 
       - for Mac:     gcc, g++ with version >=3.4.2
                      Qt-Mac-libraries
-
-
-Note for KDE-users:
-   The version 0.9.91-Qt4 doesn't provide support for KDE-3.x
-   because KDE-3.x.y requires Qt3. 
-   If you need KDE-specific features like KIO-support stick to the
-   normal version 0.9.91.
-
-Build-instructions (Unix or Mac):
-   - Make sure your shell-variable QTDIR is correct and that 
-     your path contains the Qt4-bin-directory.
-   - cd into the directory kdiff3-0.9.91/src-QT4 and type
-   - qmake kdiff3.pro
-   - make (or "gmake" for GNU-Make)
-
-Build-instructions (Windows):
-   - Run your qtvars.bat in the Qt4-bin directory.
-     (This should set your QTDIR, QMAKESPEC and PATH-environment-variables.)
-   - cd into the directory kdiff3-0.9.91/src-Qt4 and type
-   - qmake kdiff3.pro
-   - make (which calls either "mingw32-make" or "nmake")
-
-Debugging with MinGW under Windows:
-- The qt-win-opensource-4.2.0-mingw.exe only installs release dlls. You will have to compile the
-  debug dlls yourself. Enter the qt-4.2.0-directory and run "configure -debug" and then "make".
-- cd into the directory kdiff3-0.9.91/src-Qt4
-- edit the file "Makefile.Debug" and in the LFLAGS replace "-Wl,-subsystem,windows" with "-Wl,-subsystem,console"
-  (this is necessary so that gdb can send a break signal to the running program)
-- make debug (create a debuggable executable)
-- gdb debug\kdiff3.exe
-- At the "(gdb)"-prompt type "run" and enter to start.
-- While the program runs you can't set breakpoints, first interrupt it with Ctrl-C.
-- Use "help" to find out about how to use gdb. (Important commands: run, break, backtrace, print, quit)
-  Using break with c++-methods requires to specify the parameter types too. Breakpoints in constructors might not work.
-- I've tested graphical gdb-frontends too: 
-    1. Insight (also from mingw.org) worked until I wanted to interrupt the program for setting breakpoints.
-    2. Dev-Cpp: The debugger said that the app crashed before even launching it.
-  Result: For Windows I recommend gdb on the console. Please tell me when things have improved!
+      - Optional: Qt Creator IDE: Development environment optimized for Qt (http://trolltech.com/developer/qt-creator)
+
+  Build-instructions (Un*x):
+    - Make sure your shell-variable QTDIR is correct and that 
+      your path contains the Qt4-bin-directory.
+    - cd into the directory kdiff3-0.9.93/src-QT4 and type
+    - qmake kdiff3.pro
+    - make (or "gmake" for GNU-Make)
+
+  Build-instructions (Windows):
+    - set QTDIR=<QT4-dir>         e.g.: c:\qt\4.4.1
+      set "PATH=%QTDIR%\bin;%PATH%"
+    - cd into the directory kdiff3-0.9.93\src-Qt4 and type
+    - qmake kdiff3.pro
+    - Either "nmake" for Visual Studio or "mingw32-make" depending on what you have.
+
+  Debugging with MinGW under Windows:
+    - Qt Creator worked very good as debugger frontend too!
+    - Debugging without gdb on the console:
+      - The qt-win-opensource-4.4.1-mingw.exe only installs release dlls. You will have to compile the
+         debug dlls yourself. Enter the qt-4.4.1-directory and run "configure -debug" and then "mingw32-make".
+      - cd into the directory kdiff3-0.9.93\src-Qt4
+      - edit the file "Makefile.Debug" and in the LFLAGS replace "-Wl,-subsystem,windows" with "-Wl,-subsystem,console"
+         (this is necessary so that gdb can send a break signal to the running program)
+      - mingw32-make debug (create a debuggable executable)
+      - gdb debug\kdiff3.exe
+      - At the "(gdb)"-prompt type "run" and enter to start.
+      - While the program runs you can't set breakpoints, first interrupt it with Ctrl-C.
+      - Use "help" to find out about how to use gdb. (Important commands: run, break, backtrace, print, quit)
+         Using break with c++-methods requires to specify the parameter types too. Breakpoints in constructors might not work.
+
+  Building KDiff3 (Qt4) for Mac OSX (with Intel processor) as a universal binary (by Michael Schmidt)
+    1) Install Qt/Mac 4.x with thread support, static libraries and universal flag.
+       (For Qt4 run "configure -static"; only necessary if the final binary should not require shared Qt4-libs.)
+    2) cd .../kdiff3-0.9.93/src-QT4
+    3a) Create a makefile for kdiff3 by executing:
+       qmake kdiff3.pro
+    3b) optionally generate XCode-Project (for debugging purposes only) by executing:
+       qmake -spec macx-xcode kdiff3.pro
+    4) Execute:
+       make
+    5) After the build completes copy kdiff3 from the kdiff3-0.9.93/src-QT4 directory to
+       /Applications
+
 
 (End of KDiff3 with Qt4-instructions)
 ------------------------------------------------------------------------
 
-
-Start from commandline:
-- Comparing 2 files:     kdiff3 file1 file2
-- Merging 2 files:       kdiff3 file1 file2 -o outputfile
-- Comparing 3 files:     kdiff3 file1 file2 file3
-- Merging 3 files:       kdiff3 file1 file2 file3 -o outputfile
-     Note that file1 will be treated as base of file2 and file3.
-
-If all files have the same name but are in different directories, you can
-reduce typework by specifying the filename only for the first file. E.g.:
-- Comparing 3 files:     kdiff3 dir1/filename dir2 dir3
-(This also works in the open-dialog.)
-
-If you start without arguments, then a dialog will appear where you can
-select your files via a filebrowser.
-
-For more documentation, see the help-menu or the subdirectory doc.
-
-Have fun!
+Additional hints
+----------------
+
+   Start from commandline:
+   - Comparing 2 files:     kdiff3 file1 file2
+   - Merging 2 files:       kdiff3 file1 file2 -o outputfile
+   - Comparing 3 files:     kdiff3 file1 file2 file3
+   - Merging 3 files:       kdiff3 file1 file2 file3 -o outputfile
+        Note that file1 will be treated as base of file2 and file3.
+
+   If all files have the same name but are in different directories, you can
+   reduce typework by specifying the filename only for the first file. E.g.:
+   - Comparing 3 files:     kdiff3 dir1/filename dir2 dir3
+   (This also works in the open-dialog.)
+
+   If you start without arguments, then a dialog will appear where you can
+   select your files via a filebrowser.
+
+   For more documentation, see the help-menu or the subdirectory doc.
+
+   Have fun!