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

Joachim Eibl's avatar
Joachim Eibl committed
4
Author: Joachim Eibl  (joachim.eibl at gmx.de)
5
6
Copyright: (C) 2002-2012 by Joachim Eibl
KDiff3-Version: 0.9.97
Joachim Eibl's avatar
Joachim Eibl committed
7

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
8
9
10
11
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
12
From version 0.9.94 on the main target platform is KDE4/Qt4.
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
13
14
15
16
17
18
19
20
21
22
23
24
25
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:
26
27
    - for Mac: Building KDiff3 for Mac OSX (with Intel processor) as a
      universal binary
Joachim Eibl's avatar
Joachim Eibl committed
28
    - Creating and installing translation messages
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
29
30
31
32
33
- Additional hints


Introduction
------------
Joachim Eibl's avatar
Joachim Eibl committed
34
35

KDiff3 is a program that
Joachim Eibl's avatar
Joachim Eibl committed
36
- compares and merges two or three input files or directories,
Joachim Eibl's avatar
Joachim Eibl committed
37
38
39
- 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
0.9.93    
Joachim Eibl committed
40
41
42
43
- 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
44
45

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


Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
48
49
50
License
-------

Joachim Eibl's avatar
Joachim Eibl committed
51
52
53
54
55
56
57
58
59
60
61
62
63
    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
64
65
    Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA 02111-1307
    USA
Joachim Eibl's avatar
Joachim Eibl committed
66
67
68

    For details see file "COPYING".

Joachim Eibl's avatar
Joachim Eibl committed
69

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
70
71
72
73
Requirements & Installation
---------------------------

- for KDE4:
Joachim Eibl's avatar
Joachim Eibl committed
74
   From version 0.9.94 on KDiff3 supports KDE4.
75
76
   For installation on most distributions you usually also need these packages
   (names as on opensuse):
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
77
78
79
   - 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)
80
   - libkonq-devel (optional, needed for the kdiff3-plugin, if not installed
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
81
                    then the contextmenu plugin for konqueror won't be built.)
82
83
84
85
86
87
   - cmake (>2.6, checks dependencies and creates the appropriate Makefiles for
     your system)

   Typically in a terminal (e.g. konsole) you cd into the kdiff3-directory and
   run "./configure kde4". This script is essentially the same as these commands:

Joachim Eibl's avatar
Joachim Eibl committed
88
89
      mkdir releaseKde
      cd releaseKde
90
91
92
93
94
95
96
97
      # Find out your KDE4-directory and note the result
      kde4-config --prefix
      # create Makefile, replace <KDE4-prefix> with the prior result
      cmake .. -DCMAKE_INSTALL_PREFIX=<KDE4-prefix>
      # run make (compile and link)
      make
      # install as root user
      sudo make install
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
98
99

   Now KDiff3 should be ready to use. Type "kdiff3" to start it.
100
101
   There should also be a entry in your KDE-start menu in
   "(Applications->)Development".
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
102
103
104
105

   For creating a debug version:
      mkdir debug
      cd debug
106
107
108
      # Find out your KDE4-directory and note the result
      kde4-config --prefix
      cmake .. -DCMAKE_INSTALL_PREFIX=<KDE4-prefix> -DCMAKE_BUILD_TYPE=debugfull
Joachim Eibl's avatar
Joachim Eibl committed
109
      make
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
110
      sudo make install
Joachim Eibl's avatar
Joachim Eibl committed
111

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
112
113
114
   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
115

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
116
117
118
119
- Building KDiff3 with Qt4-libs, but without KDE
    - for Linux/Un*x
    - for Windows
    - for Mac
Joachim Eibl's avatar
Joachim Eibl committed
120

Joachim Eibl's avatar
Joachim Eibl committed
121
   The version 0.9.97 requires Qt 4.4.0 or newer (from http://qt-project.org/) for
122
   compilation.
Joachim Eibl's avatar
Joachim Eibl committed
123

124
125
   You always need:
      - kdiff3-0.9.97.tar.gz
Joachim Eibl's avatar
Joachim Eibl committed
126
127
128
129
130

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

      - for Windows: Qt-win-libs
131
132
133
134
135
136
137
138
                     If you have the Qt4 commercial edition, then compile with
                     Visual Studio.NET 2003 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
0.9.93    
Joachim Eibl committed
139
140
141
142
143
144
145
                       - 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
146
147
148

      - for Mac:     gcc, g++ with version >=3.4.2
                     Qt-Mac-libraries
149
      - Optional: Qt Creator IDE: Development environment optimized for Qt
Joachim Eibl's avatar
Joachim Eibl committed
150
        (from http://qt-project.org)
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
151
152

  Build-instructions (Un*x):
153
154
    Assuming Qt is correctly installed run "./configure qt4" which essentially
    does the same as:
Joachim Eibl's avatar
Joachim Eibl committed
155
156
    - mkdir releaseQt
    - cd releaseQt
157
    - qmake ../src-QT4/kdiff3.pro
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
158
159
160
    - make (or "gmake" for GNU-Make)

  Build-instructions (Windows):
Joachim Eibl's avatar
Joachim Eibl committed
161
162
163
    - If you use Qt Creator from the SDK just load the src-QT4\kdiff3.pro 
      file and build.
    On the command line (cmd.exe):
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
164
165
    - set QTDIR=<QT4-dir>         e.g.: c:\qt\4.4.1
      set "PATH=%QTDIR%\bin;%PATH%"
Joachim Eibl's avatar
Joachim Eibl committed
166
167
168
    - Prepare compiler settings:
      For Visual Studio run the respective vsvars32.bat
      For MinGW add the path: E.g. set "PATH=c:\mingw\bin;%PATH%"
169
    - cd into the directory kdiff3-0.9.97\src-Qt4 and type
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
170
    - qmake kdiff3.pro
171
    - Either "nmake" for Visual Studio or "mingw32-make" depending on what you
Joachim Eibl's avatar
Joachim Eibl committed
172
      have.  
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
173
174

  Debugging with MinGW under Windows:
175
    - Qt Creator worked very well as debugger frontend too!
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
176
    - Debugging without gdb on the console:
177
178
179
180
181
182
183
      - 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.97\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
0.9.93    
Joachim Eibl committed
184
185
186
      - mingw32-make debug (create a debuggable executable)
      - gdb debug\kdiff3.exe
      - At the "(gdb)"-prompt type "run" and enter to start.
187
188
189
190
191
192
193
      - 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.

Joachim Eibl's avatar
Joachim Eibl committed
194
195
196
  Building KDiff3 (Qt4) for Mac OSX: 
    0) Build with Qt Creator from the SDK and src-QT4\kdiff3.pro.
    Building a universal binary (by Michael Schmidt, perhaps outdated):
197
198
199
200
    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.97/src-QT4
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
201
202
    3a) Create a makefile for kdiff3 by executing:
       qmake kdiff3.pro
203
204
    3b) optionally generate XCode-Project (for debugging purposes only) by
    executing:
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
205
206
207
       qmake -spec macx-xcode kdiff3.pro
    4) Execute:
       make
208
    5) After the build completes copy kdiff3 from the kdiff3-0.9.97/src-QT4
Joachim Eibl's avatar
Joachim Eibl committed
209
       directory to:
Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
210
       /Applications
Joachim Eibl's avatar
Joachim Eibl committed
211

Joachim Eibl's avatar
Joachim Eibl committed
212
213
  Creating and installing the translation messages
    The po directory contains translations from the KDE-translation teams.
214
215
    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
216
    To create and install the translations:
217
    1) cd .../kdiff3-0.9.97/po
Joachim Eibl's avatar
Joachim Eibl committed
218
    2) sh create_qm_files install    (asks for a super user password)
219
220
    Just to create the files in the po directory (as needed for the windows
    version):
Joachim Eibl's avatar
Joachim Eibl committed
221
222
    2) sh create_qm_files local

Joachim Eibl's avatar
Joachim Eibl committed
223

Joachim Eibl's avatar
Joachim Eibl committed
224
225
226
(End of KDiff3 with Qt4-instructions)
------------------------------------------------------------------------

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
227
228
Additional hints
----------------
Joachim Eibl's avatar
Joachim Eibl committed
229

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
230
231
232
233
234
235
   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
236

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
237
238
239
240
   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.)
Joachim Eibl's avatar
Joachim Eibl committed
241

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
242
243
   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
244

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
245
   For more documentation, see the help-menu or the subdirectory doc.
Joachim Eibl's avatar
Joachim Eibl committed
246

Joachim Eibl's avatar
0.9.93    
Joachim Eibl committed
247
   Have fun!