README 10.1 KB
Newer Older
Joachim Eibl's avatar
Joachim Eibl committed
1 2 3
KDiff3-Readme
=============

4 5 6
Port to kf5/Qt5 by Michael Reeves (C) 2016
KDiff3-Version: 0.10.0

7
Now requires Qt 5.3 or later and KF5 5.5+. Legacy 0.9.98 and earlier builds are not supported.
8
Windows/MacOSX build is untested since port. Builds and runs under kubuntu 16.04 will likely
9 10 11 12
still work under other Linux/Un*x. The Konqueror specific plugin is not ported and no longer mantained.
This plugin would only apply to KDE before 4.6. Support as been removed from main CMakeLists.txt.
As of 1/13/17 cmake 3.1+ is the targeted cmake version. cmake 2.8.12 and 3.0.x should work but will be
given best effort support. 
13 14 15

These are the original pre kf5/qt5 Readme fallows:

Joachim Eibl's avatar
Joachim Eibl committed
16
Author: Joachim Eibl  (joachim.eibl at gmx.de)
Michael Reeves's avatar
Michael Reeves committed
17 18
Copyright: (C) 2002-2009 by Joachim Eibl
KDiff3-Version: 0.9.94
Joachim Eibl's avatar
Joachim Eibl committed
19

Joachim Eibl's avatar
Joachim Eibl committed
20 21 22 23
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.

Joachim Eibl's avatar
Joachim Eibl committed
24
From version 0.9.94 on the main target platform is KDE4/Qt4.
Joachim Eibl's avatar
Joachim Eibl committed
25 26 27 28 29 30 31 32 33 34 35 36 37
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:
Michael Reeves's avatar
Michael Reeves committed
38
    - for Mac: Building KDiff3 for Mac OSX (with Intel processor) as a universal binary
Joachim Eibl's avatar
Joachim Eibl committed
39
    - Creating and installing translation messages
Joachim Eibl's avatar
Joachim Eibl committed
40 41 42 43 44
- Additional hints


Introduction
------------
Joachim Eibl's avatar
Joachim Eibl committed
45 46

KDiff3 is a program that
Joachim Eibl's avatar
Joachim Eibl committed
47
- compares and merges two or three input files or directories,
Joachim Eibl's avatar
Joachim Eibl committed
48 49 50
- 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
Joachim Eibl's avatar
Joachim Eibl committed
51 52 53 54
- 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.)
Joachim Eibl's avatar
Joachim Eibl committed
55 56

Do you want help translating? Read the README in the po-subdirectory!
Joachim Eibl's avatar
Joachim Eibl committed
57 58


Joachim Eibl's avatar
Joachim Eibl committed
59 60 61
License
-------

Joachim Eibl's avatar
Joachim Eibl committed
62 63 64 65 66 67 68 69 70 71 72 73 74
    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
Michael Reeves's avatar
Michael Reeves committed
75
    Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA  02111-1307  USA
Joachim Eibl's avatar
Joachim Eibl committed
76 77 78

    For details see file "COPYING".

Michael Reeves's avatar
Michael Reeves committed
79 80 81 82 83 84 85
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 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.

Joachim Eibl's avatar
Joachim Eibl committed
86

Joachim Eibl's avatar
Joachim Eibl committed
87 88 89 90
Requirements & Installation
---------------------------

- for KDE4:
Joachim Eibl's avatar
Joachim Eibl committed
91
   From version 0.9.94 on KDiff3 supports KDE4.
Michael Reeves's avatar
Michael Reeves committed
92
   For installation on most distributions you usually also require these packages (names as on opensuse):
Joachim Eibl's avatar
Joachim Eibl committed
93 94 95
   - 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)
Michael Reeves's avatar
Michael Reeves committed
96
   - libkonq-devel (optional, needed for the kdiff3-plugin, if not installed 
Joachim Eibl's avatar
Joachim Eibl committed
97
                    then the contextmenu plugin for konqueror won't be built.)
Michael Reeves's avatar
Michael Reeves committed
98 99 100 101 102 103 104 105 106 107
   - 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
Joachim Eibl's avatar
Joachim Eibl committed
108 109

   Now KDiff3 should be ready to use. Type "kdiff3" to start it.
Michael Reeves's avatar
Michael Reeves committed
110
   There should also be a entry in your KDE-start menu in "(Applications->)Development".
Joachim Eibl's avatar
Joachim Eibl committed
111 112 113 114

   For creating a debug version:
      mkdir debug
      cd debug
Michael Reeves's avatar
Michael Reeves committed
115 116
      kde4-config --prefix                           # Find out your KDE4-directory and note the result
      cmake .. -DCMAKE_INSTALL_PREFIX=<KDE4-prefix>  -DCMAKE_BUILD_TYPE=debugfull
Joachim Eibl's avatar
Joachim Eibl committed
117
      make
Joachim Eibl's avatar
Joachim Eibl committed
118
      sudo make install
Joachim Eibl's avatar
Joachim Eibl committed
119

Joachim Eibl's avatar
Joachim Eibl committed
120 121 122
   The <KDE4-prefix> depends on your distribution:
   The command "kde4-config --prefix" should tell you.
   - For opensuse 11 use "/usr".
Joachim Eibl's avatar
Joachim Eibl committed
123

Joachim Eibl's avatar
Joachim Eibl committed
124 125 126 127
- Building KDiff3 with Qt4-libs, but without KDE
    - for Linux/Un*x
    - for Windows
    - for Mac
Joachim Eibl's avatar
Joachim Eibl committed
128

Michael Reeves's avatar
Michael Reeves committed
129
   The version 0.9.94 requires Qt 4.4.0 or newer (from www.trolltech.com) for compilation. 
130

Michael Reeves's avatar
Michael Reeves committed
131 132
   You always need
      - kdiff3-0.9.94.tar.gz
Joachim Eibl's avatar
Joachim Eibl committed
133 134 135 136 137

      - for Un*x:    gcc, g++ with version >=3.4.2
                     Qt-X11-libraries

      - for Windows: Qt-win-libs
Michael Reeves's avatar
Michael Reeves committed
138 139 140 141
                     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):
                     - Use MinGW-5.1.4.exe or newer to install the following or newer:
Joachim Eibl's avatar
Joachim Eibl committed
142 143 144 145 146 147 148
                       - 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)
Joachim Eibl's avatar
Joachim Eibl committed
149 150 151

      - for Mac:     gcc, g++ with version >=3.4.2
                     Qt-Mac-libraries
Michael Reeves's avatar
Michael Reeves committed
152
      - Optional: Qt Creator IDE: Development environment optimized for Qt (http://trolltech.com/developer/qt-creator)
Joachim Eibl's avatar
Joachim Eibl committed
153 154

  Build-instructions (Un*x):
Michael Reeves's avatar
Michael Reeves committed
155 156 157 158
    - Make sure your shell-variable QTDIR is correct and that 
      your path contains the Qt4-bin-directory.
    - cd into the directory kdiff3-0.9.94/src-QT4 and type
    - qmake kdiff3.pro
Joachim Eibl's avatar
Joachim Eibl committed
159 160 161 162 163
    - 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%"
Michael Reeves's avatar
Michael Reeves committed
164
    - cd into the directory kdiff3-0.9.94\src-Qt4 and type
Joachim Eibl's avatar
Joachim Eibl committed
165
    - qmake kdiff3.pro
Michael Reeves's avatar
Michael Reeves committed
166
    - Either "nmake" for Visual Studio or "mingw32-make" depending on what you have.
Joachim Eibl's avatar
Joachim Eibl committed
167 168

  Debugging with MinGW under Windows:
Michael Reeves's avatar
Michael Reeves committed
169
    - Qt Creator worked very good as debugger frontend too!
Joachim Eibl's avatar
Joachim Eibl committed
170
    - Debugging without gdb on the console:
Michael Reeves's avatar
Michael Reeves committed
171 172 173 174 175
      - 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.94\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)
Joachim Eibl's avatar
Joachim Eibl committed
176 177 178
      - mingw32-make debug (create a debuggable executable)
      - gdb debug\kdiff3.exe
      - At the "(gdb)"-prompt type "run" and enter to start.
Michael Reeves's avatar
Michael Reeves committed
179 180 181 182 183 184 185 186
      - 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.94/src-QT4
Joachim Eibl's avatar
Joachim Eibl committed
187 188
    3a) Create a makefile for kdiff3 by executing:
       qmake kdiff3.pro
Michael Reeves's avatar
Michael Reeves committed
189
    3b) optionally generate XCode-Project (for debugging purposes only) by executing:
Joachim Eibl's avatar
Joachim Eibl committed
190 191 192
       qmake -spec macx-xcode kdiff3.pro
    4) Execute:
       make
Michael Reeves's avatar
Michael Reeves committed
193
    5) After the build completes copy kdiff3 from the kdiff3-0.9.94/src-QT4 directory to
Joachim Eibl's avatar
Joachim Eibl committed
194
       /Applications
Joachim Eibl's avatar
Joachim Eibl committed
195

Joachim Eibl's avatar
Joachim Eibl committed
196 197
  Creating and installing the translation messages
    The po directory contains translations from the KDE-translation teams.
Michael Reeves's avatar
Michael Reeves committed
198 199
    If you use the Qt-only-version of KDiff3, then the installation described above 
    won't install translations automatically.
Joachim Eibl's avatar
Joachim Eibl committed
200
    To create and install the translations:
Michael Reeves's avatar
Michael Reeves committed
201 202 203
    0) Make sure /usr/lib/qt3/bin/msg2qm exists 
       (comes with qt3-devel-tools. [Yes, really Qt3. There is no Qt4 replacement yet.])
    1) cd .../kdiff3-0.9.95/po
Joachim Eibl's avatar
Joachim Eibl committed
204
    2) sh create_qm_files install    (asks for a super user password)
Michael Reeves's avatar
Michael Reeves committed
205
    Just to create the files in the po directory (as needed for the windows version): 
Joachim Eibl's avatar
Joachim Eibl committed
206 207
    2) sh create_qm_files local

Joachim Eibl's avatar
Joachim Eibl committed
208

Joachim Eibl's avatar
Joachim Eibl committed
209 210 211
(End of KDiff3 with Qt4-instructions)
------------------------------------------------------------------------

Joachim Eibl's avatar
Joachim Eibl committed
212 213
Additional hints
----------------
Joachim Eibl's avatar
Joachim Eibl committed
214

Joachim Eibl's avatar
Joachim Eibl committed
215 216 217 218 219 220
   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.
Joachim Eibl's avatar
Joachim Eibl committed
221

Joachim Eibl's avatar
Joachim Eibl committed
222 223 224 225
   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.)
226

Joachim Eibl's avatar
Joachim Eibl committed
227 228
   If you start without arguments, then a dialog will appear where you can
   select your files via a filebrowser.
Joachim Eibl's avatar
Joachim Eibl committed
229

Joachim Eibl's avatar
Joachim Eibl committed
230
   For more documentation, see the help-menu or the subdirectory doc.
Joachim Eibl's avatar
Joachim Eibl committed
231

Joachim Eibl's avatar
Joachim Eibl committed
232
   Have fun!