annotate kdiff3/README @ 73:f7dad0aa6146

KDiff3-0.9.90-Qt4

KDiff3-Readme
=============

Author: Joachim Eibl  (joachim.eibl at gmx.de)
Copyright: (C) 2002-2006 by Joachim Eibl
KDiff3-Version: 0.9.90-Qt4


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.


Do you want help translating? Read the README in the po-subdirectory!


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

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA  02111-1307  USA

    For details see file "COPYING".


Requirements & Installation:
   The version 0.9.90-Qt4 requires Qt 4.x.y (from www.trolltech.com) for compilation. 
   (Qt-version >= 4.1.2 is recommended.)

   You always need
      - kdiff3-0.9.90-Qt4.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 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.)

      - for Mac:     gcc, g++ with version >=3.4.2
                     Qt-Mac-libraries


Note for KDE-users:
   The version 0.9.90-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.90.

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.90-Qt4/src 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.90-Qt4/src and type
   - qmake kdiff3.pro
   - make (which calls either "mingw32-make" or "nmake")

Debugging with MinGW under Windows:
- cd into the directory kdiff3-0.9.90-Qt4/src
- 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!

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!