1--------------------------------------- 2Installation instructions for GIMP @GIMP_APP_VERSION@ 3--------------------------------------- 4 5There are some basic steps to building and installing GIMP. 6 7GIMP @GIMP_APP_VERSION@ replaces earlier GIMP 2.x versions. It is advised that you 8uninstall them before installing GIMP @GIMP_APP_VERSION@. If you want to keep your 9older GIMP 2.x installation in parallel to GIMP @GIMP_APP_VERSION@, you have to 10choose a separate prefix which is not in your default library search 11path. 12 13GIMP @GIMP_APP_VERSION@ is fully backward compatible to all earlier GIMP 2.x version. 14Plug-ins and scripts written for GIMP 2.8, 2.6 or earlier GIMP 2.x 15versions will continue to work and don't need to be changed nor 16recompiled to be used with GIMP @GIMP_APP_VERSION@. 17 18The most important part is to make sure the requirements for a build 19are fulfilled. We depend on a number of tools and libraries which are 20listed below. For libraries this means you need to also have the 21header files installed. 22 23 24 ****************************************************************** 25 * Unless you are experienced with building software from source, * 26 * you should not attempt to build all these libraries yourself! * 27 * We suggest that you check if your distributor has development * 28 * packages of them and use these instead. * 29 ****************************************************************** 30 31 32 1. You need to have installed a recent version of pkg-config (>= @GIMP_PKGCONFIG_VERSION@) available 33 from https://www.freedesktop.org/software/pkgconfig/. 34 35 2. You need intltool (at least @INTLTOOL_REQUIRED_VERSION@, but preferably a newer version). 36 Intltool can be downloaded from 37 https://ftp.gnome.org/pub/gnome/sources/intltool/ 38 You also need gettext version @XGETTEXT_REQUIRED_VERSION@ or over. Earlier gettext had 39 issues with script-fu localization, ending up in incomplete GIMP localization. 40 41 3. You need to have GEGL version @GEGL_REQUIRED_VERSION@ or newer and babl version 42 @BABL_REQUIRED_VERSION@ or newer. You can get them from https://gegl.org/ or clone 43 them from the GNOME git repository: 44 45 https://gitlab.gnome.org/GNOME/babl.git 46 https://gitlab.gnome.org/GNOME/gegl.git 47 48 Note: install GEGL with libumfpack (SuiteSparse) for alternative Matting 49 engine "gegl:matting-levin" and OpenEXR library for OpenEXR format 50 support. 51 52 4. You need to have installed GTK+ version @GTK_REQUIRED_VERSION@ or newer. 53 GIMP also needs a recent version of GLib (>= @GLIB_REQUIRED_VERSION@), GDK-Pixbuf 54 (>= @GDK_PIXBUF_REQUIRED_VERSION@), and Pango (>= @PANGOCAIRO_REQUIRED_VERSION@). Sources for these can be grabbed 55 from ftp://ftp.gtk.org/. 56 57 5. We use cairo >= @CAIRO_REQUIRED_VERSION@, which is hosted at 58 https://www.cairographics.org/. 59 60 6. We require PangoCairo, a Pango backend using Cairo. Make sure you 61 have Cairo, FreeType2 and fontconfig installed before you compile 62 Pango. GIMP depends on freetype2 being newer than version @FREETYPE2_REQUIRED_VERSION@ 63 and fontconfig @FONTCONFIG_REQUIRED_VERSION@ or newer. Older versions are known to have 64 bugs that seriously affect the stability of GIMP. 65 66 We also require HarfBuzz @HARFBUZZ_REQUIRED_VERSION@ or newer, an 67 OpenType text shaping tool. As this is a dependency for Pango, you 68 will likely have it installed, but you may have to install a 69 development package for the headers. 70 71 7. The file-compressor plug-in requires zlib, libbzip2, and liblzma to 72 be installed. All these libraries are required dependencies. 73 74 8. For metadata access GIMP requires the gexiv2 library. It is hosted 75 at https://wiki.gnome.org/Projects/gexiv2 . 76 77 9. libpng, libjpeg, libtiff and lcms are hard dependencies that can 78 not be disabled. 79 80 10. For MyPaint brushes, brushlib (libmypaint) @LIBMYPAINT_REQUIRED_VERSION@ is used. 81 The libmypaint repository is hosted at: 82 83 https://github.com/mypaint/libmypaint 84 85 If installing from repository, do not install the master branch! 86 Checkout the tag "v1.3.0" instead, or simply install from a tarball 87 or from your favorite package manager. 88 You may also checkout the "libmypaint-v1" branch, which is the 89 development branch for libmypaint v1.x and has some more recent 90 fixes. 91 92 11. We also need the mypaint-brushes data package: 93 94 https://github.com/mypaint/mypaint-brushes 95 96 If installing from repository, install from branch "v1.3.x" or the 97 particular tag "v1.3.0". In particular do not install from master 98 which installs brushes incompatible with GIMP. 99 100 Also this is a data packages and therefore it will install the 101 pkg-config file inside `$PREFIX/share/pkgconfig/`. If you install 102 mypaint-brushes from repository in a non-standard prefix, you will 103 have to make sure your $PKG_CONFIG_PATH environment variable also 104 lists `$PREFIX/share/pkgconfig/`. 105 106 12. You may want to install other third party libraries or programs 107 that are needed for some of the available plug-ins. We recommend 108 to check that the following libraries are installed: openjpeg, 109 webkit, libmng, librsvg, libwmf, libaa and libgs (Ghostscript). 110 111 13. HEIF support depends on the libheif library. If you don't have 112 access to pre-built packages, the code is available at: 113 114 https://github.com/strukturag/libheif 115 116 Make sure you build libheif with libde265 and libx265 support (for 117 respectively decoding and encoding), otherwise the plug-in is 118 mostly useless. 119 120 14. The Python extension requires Python 2 development headers (@PYTHON2_REQUIRED_VERSION@ 121 or newer) to be present. You will also need PyGTK and the 122 respective development headers. 123 124 15. Windows builds can now generate backtrace logs upon a crash. 125 The logs will be available in: %APPDATA%\GIMP\@GIMP_APP_VERSION@\CrashLog\ 126 The feature depends on Dr.MinGW's ExcHndl library: 127 128 https://github.com/jrfonseca/drmingw 129 130 16. Configure GIMP by running the `configure' script. You may want 131 to pass some options to it, see below. 132 133 17. Build GIMP by running `make'. The use of GNU make is recommended. 134 If you need to tweak the build to make it work with other flavours 135 of make, we'd appreciate if you'd send us a patch with the changes. 136 137 18. Install GIMP by running `make install'. In order to avoid clashes 138 with other versions of GIMP, we install a binary called gimp-@GIMP_APP_VERSION@. 139 By default there's also a link created so that you can type 'gimp' 140 to start gimp-@GIMP_APP_VERSION@. 141 142 19. Summary of required packages and what version you need: 143 144 Package Name Version 145 146 ATK @ATK_REQUIRED_VERSION@ 147 babl @BABL_REQUIRED_VERSION@ 148 cairo @CAIRO_REQUIRED_VERSION@ 149 Fontconfig @FONTCONFIG_REQUIRED_VERSION@ 150 freetype2 @FREETYPE2_REQUIRED_VERSION@ 151 GDK-PixBuf @GDK_PIXBUF_REQUIRED_VERSION@ 152 GEGL @GEGL_REQUIRED_VERSION@ 153 GIO 154 GLib @GLIB_REQUIRED_VERSION@ 155 glib-networking 156 GTK+ @GTK_REQUIRED_VERSION@ 157 HarfBuzz @HARFBUZZ_REQUIRED_VERSION@ 158 libbzip2 159 libjpeg 160 liblzma @LIBLZMA_REQUIRED_VERSION@ 161 libmypaint @LIBMYPAINT_REQUIRED_VERSION@ 162 libpng @LIBPNG_REQUIRED_VERSION@ 163 libpoppler-glib @POPPLER_REQUIRED_VERSION@ 164 librsvg @RSVG_REQUIRED_VERSION@ 165 libtiff 166 Little CMS @LCMS_REQUIRED_VERSION@ 167 mypaint-brushes-1.0 168 pangocairo @PANGOCAIRO_REQUIRED_VERSION@ 169 poppler-data @POPPLER_DATA_REQUIRED_VERSION@ 170 zlib 171 172 20. Summary of optional packages: 173 174 Package Name Version Feature 175 176 cairo-pdf @CAIRO_PDF_REQUIRED_VERSION@ PDF export 177 ExcHndl - Crash logs on Windows with Dr. MinGW 178 gs - ghostscript 179 libaa - ASCII art 180 libheif @LIBHEIF_REQUIRED_VERSION@ HEIF 181 libmng - MNG 182 libwebp @WEBP_REQUIRED_VERSION@ WebP (built with --enable-libwebpmux and --enable-libwebpdemux) 183 libwmf @WMF_REQUIRED_VERSION@ WMF 184 libXcursor - X11 Mouse Cursor 185 libxpm - XPM 186 openexr @OPENEXR_REQUIRED_VERSION@ OpenEXR 187 OpenJPEG @OPENJPEG_REQUIRED_VERSION@ JPEG 2000 188 python 2 @PYTHON2_REQUIRED_VERSION@ Python plug-ins 189 webkit @WEBKIT_REQUIRED_VERSION@ Help browser & webpage 190 191 21. Summary of optional runtime dependencies: 192 193 darktable >= 1.7, with lua support enabled for raw loading 194 RawTherapee >= 5.2 for raw loading 195 xdg-email for sending emails 196 sendmail for sending emails if --with-sendmail enabled 197 gdb or lldb for our new bug-reporting dialog 198 "gegl:matting-levin" GEGL operation for alternative matting engine 199 200Please make sure you don't have any old GTK+-2.x, jpeg, etc. libraries 201lying around on your system, otherwise configure may fail to find the 202new ones. 203 204 205Generic instructions for configuring and compiling auto-configured 206packages are included below. Here is an illustration of commands that 207might be used to build and install GIMP. The actual configuration, 208compilation and installation output is not shown. 209 210 % tar xvfz gimp-@GIMP_VERSION@.tar.gz # unpack the sources 211 % cd gimp-@GIMP_VERSION@ # change to the toplevel directory 212 % ./configure # run the `configure' script 213 % make # build GIMP 214 % make install # install GIMP 215 216 217The `configure' script examines your system, and adapts GIMP to run on 218it. The script has many options, some of which are described in the 219generic instructions included at the end of this file. All of the 220options can be listed using the command `./configure --help'. There 221are several special options the GIMP `configure' script recognizes. 222These are: 223 224 --disable-vector-icons. This option installs raster icons instead of 225 vector icons. 226 227 --enable-relocatable-bundle. This option forces GIMP to search some 228 resources (e.g. MyPaint brushes or libwmf fonts) relatively to the 229 running prefix, rather than using build-time paths. 230 231 --enable-shared and --disable-shared. This option affects whether 232 shared libraries will be built or not. Shared libraries provide 233 for much smaller executables. The default is to enable shared 234 libraries. Disabling shared libraries is almost never a good idea. 235 236 --enable-debug and --disable-debug. This option causes the build 237 process to compile with debugging enabled. If debugging is 238 disabled, GIMP will instead be compiled with optimizations turned 239 on. The default is for debugging to be disabled. NOTE: This 240 option is intended primarily as a convenience for developers. 241 242 --enable-profile and --disable-profile. This option causes the build 243 process to compile with execution profiling enabled. The default is 244 for profiling to be disabled. NOTE: This option is intended primarily 245 as a convenience for developers. 246 247 --enable-ansi and --disable-ansi. This option causes stricter 248 ANSI C checking to be performed when compiling with GCC. The 249 default is for strict checking to be disabled. NOTE: This option 250 is intended primarily as a convenience for developers. 251 252 --with-gimpdir=DIR. This option changes the default directory 253 GIMP uses to search for its configuration files from 254 ~/.config/GIMP/@GIMP_APP_VERSION@ (the directory .config/GIMP/@GIMP_APP_VERSION@ 255 in the user's home directory) to ~/.config/DIR/@GIMP_APP_VERSION@. 256 If DIR is an absolute path, the directory will be changed to DIR. 257 258 --with-shm=[none|sysv|posix|auto]. This option allows you to specify 259 how image data is transported between the core and plug-ins. Usually 260 the best way to do this is detected automatically. 261 262 --without-libtiff. configure will bail out if libtiff can not be 263 found. You better fix the underlying problem and install these 264 libraries with their header files. If you absolutely want to 265 compile GIMP without support for TIFF you need to explicitly 266 disable them using this option. 267 268 --without-aa. The AA plug-in needs libaa and configure checks for 269 its presence. Use --without-aa if you run into problems. 270 271 --without-libxpm. The XPM plug-in needs libxpm and configure checks 272 for its presence. If for some reason you don't want to build the 273 XPM plug-in even though the library is installed, use 274 --without-libxpm to disable it explicitly. 275 276 --without-libmng. The MNG plug-in needs libmng and configure checks 277 for its presence. If for some reason you don't want to build the 278 MNG plug-in even though the library is installed, use 279 --without-libmng to disable it explicitly. 280 281 --without-wmf. The WMF plug-in needs libwmf2 and configure checks for 282 its presence. Use --without-wmf if you run into problems. 283 284 --without-webkit. If for some reason you don't want to build the 285 Help Browser plug-in, you can use --without-webkit to disable 286 it explicitly. 287 288 --without-librsvg. If for some reason you want to build GIMP without 289 SVG support, you can build --without-librsvg. 290 291 --without-print. If for some reason you don't want to build the Print 292 plug-in based on the GtkPrint API, you can build with --without-print. 293 294 --without-alsa. If you don't want to compile ALSA support into the 295 MIDI input controller module, you can use the --without-alsa option. 296 297 --without-linux-input. If you don't want to compile the Linux Input 298 controller module, you can use the --without-linux-input option. 299 300 --without-hal. If you want to build the Linux Input controller module 301 without HAL support, you can use the --without-hal option. 302 303 --without-mac-twain. If you don't want to compile the Mac OS X 304 TWAIN plug-in, you can use the --without-mac-twain option. 305 306 --with-gif-compression=[lzw|rle|none]. Allows to tune the compression 307 algorithm used by the GIF plug-in. If you are afraid of Unisys' LZW 308 patent (which should have expired in most countries by now), you 309 can go for simple run-length encoding or even configure the plug-in 310 to create uncompressed GIFs. 311 312 --enable-gtk-doc. This option controls whether the libgimp API 313 references will be created using gtk-doc. The HTML pages are 314 included in a standard tarball, so you will only need this if you 315 are building from SVN. 316 317 --with-html-dir=PATH. This option allows to specify where the 318 libgimp API reference should be installed. You might want to modify 319 the path so it points to the place where glib and gtk+ installed 320 their API references so that the libgimp reference can link to 321 them. 322 323 --disable-mp. This option allows you to disable support for multiple 324 processors. It is enabled by default. 325 326 --with-sendmail[=PATH]. This option is used to tell GIMP to send email 327 through sendmail instead of xdg-email. You can optionally indicate 328 where to find the sendmail command. Otherwise sendmail will simply 329 be searched in your $PATH at runtime. 330 331 --with-desktop-dir=[PATH]. This option specifies where to install 332 desktop files. These files are used by desktop environments that 333 comply to the specs published at freedesktop.org. The default 334 value ${prefix}/share should be fine if your desktop environment 335 is installed in the same prefix as gimp. No files are installed 336 if you call configure with --without-desktop-dir. 337 338 --disable-default-binary. Use this option if you don't want to make 339 gimp-@GIMP_APP_VERSION@ the default GIMP installation. Otherwise a link called 340 gimp pointing to the gimp-@GIMP_APP_VERSION@ executable will be installed. 341 342 --disable-gimp-console. Use this option if you don't want the 343 gimp-console binary to be built in addition to the standard binary. 344 gimp-console is useful for command-line batch mode or as a server. 345 346 --disable-python. If for some reason you don't want to build the 347 Python based PyGIMP plug-in, you can use --disable-python. 348 349 --without-script-fu. If for some reason you don't want to build the 350 Script-Fu plug-in, you can use --without-script-fu. 351 352 --without-xmc. The X11 Mouse Cursor(XMC) plug-in needs libXcursor 353 and configure checks for its presence. If for some reason you 354 don't want to build the XMC plug-in even though the library is 355 installed, use --without-xmc to disable it explicitly. 356 357 358The `make' command builds several things: 359 - A bunch of public libraries in the directories starting with 'libgimp'. 360 - The plug-in programs in the 'plug-ins' directory. 361 - Some modules in the 'modules' subdirectory. 362 - The main GIMP program 'gimp-@GIMP_APP_VERSION@' in `app'. 363 364The `make install' commands installs the GIMP header files associated 365with the libgimp libraries, the plug-ins, some data files and the GIMP 366executable. After running `make install' and assuming the build process 367was successful you should be able to run `gimp'. 368 369 370When ./configure fails 371====================== 372 373'configure' uses pkg-config, a tool that replaces the old foo-config 374scripts. The most recent version is available from 375 https://www.freedesktop.org/software/pkgconfig/ 376 377'configure' tries to compile and run a short GTK+ program. There are 378several reasons why this might fail: 379 380* pkg-config could not find the file 'gtk+-2.0.pc' that gets installed 381 with GTK. (This file is used to get information about where GTK+ is 382 installed.) 383 384 Fix: Either make sure that this file is in the path where pkg-config 385 looks for it (try 'pkg-config --debug' or add the location of 386 gtk+-2.0.pc to the environment variable PKG_CONFIG_PATH before running 387 configure. 388 389* Libraries you installed are not found when you attempt to start GIMP. 390 The details of how to fix this problem will depend on the system: 391 392 On Linux and other systems using ELF libraries, add the directory to 393 holding the library to /etc/ld.so.conf or to the environment variable 394 LD_LIBRARY_PATH, and run 'ldconfig'. 395 396 On other systems, it may be necessary to encode this path 397 into the executable, by setting the LDFLAGS environment variable 398 before running configure. For example: 399 400 LDFLAGS="-R/home/joe/lib" ./configure 401 or 402 LDFLAGS="-Wl,-rpath -Wl,/home/joe/lib" ./configure 403 404* An old version of the GTK+ libraries was found instead of 405 your newly installed version. This commonly happens if a 406 binary package of GTK+ was previously installed on your system, 407 and you later compiled GTK+ from source. 408 409 Fix: Remove the old libraries and include files. If you are afraid 410 that removing the old libraries may break other packages supplied by 411 your distributor, you can try installing GLib, GTK+ and other 412 libraries in a different prefix after setting the environment 413 variable PKG_CONFIG_LIBDIR to point to lib/pkgconfig/ in that new 414 prefix so that it does not try to read the *.pc files from the 415 default directory (/usr/lib/pkgconfig). However, removing the old 416 packages is often the easier solution. 417 418A detailed log of the ./configure output is written to the file 419config.log. This may help diagnose problems. 420 421 422When ./configure fails on plug-ins 423================================== 424 425There are some GIMP plug-ins that need additional third-party libraries 426installed on your system. For example to compile the plug-ins that load 427and save JPEG, PNG or TIFF files you need the related libraries and header 428files installed, otherwise you'll get a message that plug-in xyz will not 429be built. 430 431If you are sure that those libraries are correctly installed, but configure 432fails to detect them, the following might help: 433 434Set your LDFLAGS environment variable to look for the library in a certain 435place, e.g. if you are working in a bash shell you would say: 436 export LDFLAGS="-L<path_to_library> -L<path_to_another_one>" 437before you run configure. 438 439Set your CPPFLAGS environment variable to look for the header file in a 440certain place, e.g. if you are working in a bash shell you would say: 441 export CPPFLAGS="-I<path_to_header_file> -I<path_to_another_one>" 442before you run configure. 443 444 445 Generic Instructions for Building Auto-Configured Packages 446 ========================================================== 447 448 449To compile this package: 450 4511. Configure the package for your system. In the directory that this 452file is in, type `./configure'. If you're using `csh' on an old 453version of System V, you might need to type `sh configure' instead to 454prevent `csh' from trying to execute `configure' itself. 455 456The `configure' shell script attempts to guess correct values for 457various system-dependent variables used during compilation, and 458creates the Makefile(s) (one in each subdirectory of the source 459directory). In some packages it creates a C header file containing 460system-dependent definitions. It also creates a file `config.status' 461that you can run in the future to recreate the current configuration. 462Running `configure' takes a minute or two. 463 464To compile the package in a different directory from the one 465containing the source code, you must use GNU make. `cd' to the 466directory where you want the object files and executables to go and 467run `configure' with the option `--srcdir=DIR', where DIR is the 468directory that contains the source code. Using this option is 469actually unnecessary if the source code is in the parent directory of 470the one in which you are compiling; `configure' automatically checks 471for the source code in `..' if it does not find it in the current 472directory. 473 474By default, `make install' will install the package's files in 475/usr/local/bin, /usr/local/lib, /usr/local/man, etc. You can specify 476an installation prefix other than /usr/local by giving `configure' the 477option `--prefix=PATH'. 478 479You can specify separate installation prefixes for machine-specific 480files and machine-independent files. If you give `configure' the 481option `--exec-prefix=PATH', the package will use PATH as the prefix 482for installing programs and libraries. Normally, all files are 483installed using the same prefix. 484 485`configure' ignores any other arguments that you give it. 486 487If your system requires unusual options for compilation or linking 488that `configure' doesn't know about, you can give `configure' initial 489values for some variables by setting them in the environment. In 490Bourne-compatible shells, you can do that on the command line like 491this: 492 CC='gcc -traditional' DEFS=-D_POSIX_SOURCE ./configure 493 494The `make' variables that you might want to override with environment 495variables when running `configure' are: 496 497(For these variables, any value given in the environment overrides the 498value that `configure' would choose:) 499CC C compiler program. 500 Default is `cc', or `gcc' if `gcc' is in your PATH. 501INSTALL Program to use to install files. 502 Default is `install' if you have it, `cp' otherwise. 503INCLUDEDIR Directory for `configure' to search for include files. 504 Default is /usr/include. 505 506(For these variables, any value given in the environment is added to 507the value that `configure' chooses:) 508DEFS Configuration options, in the form '-Dfoo -Dbar ...' 509LIBS Libraries to link with, in the form '-lfoo -lbar ...' 510 511If you need to do unusual things to compile the package, we encourage 512you to teach `configure' how to do them and mail the diffs to the 513address given in the README so we can include them in the next 514release. 515 5162. Type `make' to compile the package. 517 5183. Type `make install' to install programs, data files, and 519documentation. 520 5214. You can remove the program binaries and object files from the 522source directory by typing `make clean'. To also remove the 523Makefile(s), the header file containing system-dependent definitions 524(if the package uses one), and `config.status' (all the files that 525`configure' created), type `make distclean'. 526 527The file `configure.ac' is used as a template to create `configure' by 528a program called `autoconf'. You will only need it if you want to 529regenerate `configure' using a newer version of `autoconf'. 530