HACKING

   1 Requirements
   2 ------------
   3 If you want to hack on the GIMP project, it will make your life easier
   4 to have the following packages (or newer versions) installed:
   5
   6     * GNU autoconf 2.54
   7         - ftp://ftp.gnu.org/gnu/autoconf/
   8     * GNU automake 1.9 (automake 1.10 should also work)
   9         - ftp://ftp.gnu.org/gnu/automake/
  10     * GNU libtool 1.5
  11         - ftp://ftp.gnu.org/gnu/libtool/
  12
  13 Fine GNU mirrors are listed at https://www.gnu.org/prep/ftp.html
  14 Beta software can be found at alpha.gnu.org.
  15
  16     * pkg-config 0.16.0 (or preferably a newer version)
  17         - https://www.freedesktop.org/software/pkgconfig/
  18
  19     * gtkdocize
  20         - https://ftp.gnome.org/pub/GNOME/sources/gtk-doc/
  21
  22     * xsltproc
  23         - ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.1/
  24
  25 These are only the additional requirements if you want to compile from
  26 the git repository. The file INSTALL lists the various libraries we
  27 depend on.
  28
  29
  30 Compilation
  31 -----------
  32 If you are accessing gimp via git, then you will need to take several
  33 steps to get it to compile.  You can do all these steps at once by
  34 running:
  35
  36     gimp/trunk$ ./autogen.sh
  37
  38 Basically this does the following for you:
  39
  40     gimp/trunk$ aclocal-1.9; libtoolize; automake-1.9 -a;
  41     gimp/trunk$ autoconf; intltoolize --automake
  42
  43 The above commands create the "configure" script.  Now you can run the
  44 configure script in gimp/trunk to create all the Makefiles.
  45
  46 Before running autogen.sh or configure, make sure you have libtool in
  47 your path. Also make sure glib-2.0.m4 glib-gettext.m4, gtk-2.0.m4,
  48 pkg.m4 and intltool.m4 are either installed in the same
  49 $prefix/share/aclocal relative to your automake/aclocal installation
  50 or call autogen.sh as follows:
  51
  52     $ ACLOCAL_FLAGS="-I $prefix/share/aclocal" ./autogen.sh
  53
  54 Note that autogen.sh runs configure for you.  If you wish to pass
  55 options like --prefix=/usr to configure you can give those options to
  56 autogen.sh and they will be passed on to configure.
  57
  58 If AUTOGEN_CONFIGURE_ARGS is set, these options will also be passed to
  59 the configure script. If for example you want to enable the build of
  60 the GIMP API reference manuals, you can set AUTOGEN_CONFIGURE_ARGS to
  61 "--enable-gtk-doc". Please note that you will then need a recent
  62 version of gtk-doc as well as a working setup for handling DocBook/XML.
  63
  64 If you do not have a recent version of gtk-doc, you can pass the
  65 option "--disable-gtk-doc" to autogen.sh.  This will completely
  66 disable the support for gtk-doc so you will not be able to generate
  67 the API documentation.
  68
  69 If you want to use libraries from a non-standard prefix, you should set
  70 PKG_CONFIG_PATH appropriately. Some libraries do not use pkgconfig, see
  71 the output of ./configure --help for information on what environment
  72 variables to set to point the compiler and linker to the correct path.
  73 Note that you need to do this even if you are installing Gimp itself
  74 into the same prefix as the library.
  75
  76
  77 Git
  78 ---
  79 GIMP is available from GNOME Git. You can use the following commands
  80 to get GIMP from the the git server:
  81
  82     $ git clone https://gitlab.gnome.org/GNOME/gimp.git
  83
  84 You can read more on using GNOME's git service at these URLs:
  85
  86     https://wiki.gnome.org/Git
  87     https://www.kernel.org/pub/software/scm/git/docs/
  88
  89
  90 You will also need relatively new stable releases of glib, pango, atk,
  91 gtk+, cairo, gtkhtml2, etc. for building GIMP, which you can get as a
  92 part of recent Linux distribution releases.
  93
  94
  95 Patches
  96 -------
  97
  98 The best way to submit patches is to provide files created with
  99 git-format-patch.
 100
 101 It is recommended that you file a bug report at
 102 https://gitlab.gnome.org/GNOME/gimp
 103 and either create a merge request or attach your patch to it as a plain
 104 text file, not compressed. If your patch is reasonably small you can
 105 submit it to the gimp-developer-list@gnome.org mailing list.
 106
 107 If the patch needs to be discussed, you should also consider using the
 108 mailing list instead of Bugzilla because bug reports tend to be hard
 109 to read if they contain too many comments. For the code, please try to
 110 follow the guidelines given in Hackordnung, below.
 111
 112
 113 Auto-generated Files
 114 --------------------
 115 Please notice that some files in the source are generated from other
 116 sources. All those files have a short notice about being generated
 117 somewhere at the top. Among them are the files ending in pdb.[ch] in
 118 the libgimp directory and the files ending in cmds.c in the app/pdb
 119 subdirectory. Those are generated from the respective .pdb files in
 120 pdb/groups.
 121
 122
 123 Hackordnung
 124 -----------
 125 We encourage you to follow the GIMP coding style throughout the GIMP
 126 project.  For the core components (application and libs) this coding
 127 style is enforced.  The GIMP coding style is defined as follows:
 128
 129     * There's a single space between the function name and the opening
 130       paren.
 131
 132     * Function names are lowercase, words separated by underscores.
 133
 134     * Macros and enums are all uppercase, words separated by
 135       underscores.
 136
 137     * Types are all words capitalized, no separators between words.
 138
 139     * All functions in header files need to be prototyped.
 140
 141     * Indentation rules are GNU coding style, in particular:
 142         - 2 characters indentation level
 143         - Do not use tabs (of course your editor can accept the TAB key
 144           as a command, typically to indent the current line properly
 145           or to add spaces at the cursor until the next multiple of 8
 146           columns, but it should not put TAB characters in the file).
 147         - When editing files that still have TABs in them, make sure your
 148           editor interprets the TABs correctly, that is, has tab stops
 149           at 8 column intervals.
 150         - Opening braces are on a new line and indented one level.
 151         - Function header have the return type on one line, the name
 152           starting in the first column of the following line. All
 153           parameters are prototyped and there's a new line for each.
 154
 155 The source tree contains local config files which can be used to set the
 156 right coding style in common editors: `.dir-locals.el` for Emacs,
 157 `.kateconfig` for Kate, and `devel-docs/c.vim` for Vim (check the top
 158 comments to see how to enable it automatically when opening a file in
 159 the GIMP tree).
 160
 161 Try to make use of GLib's object system as much as possible. Do not
 162 create wrappers around functions of parent classes. If you end up
 163 duplicating code, try to create a common parent class and implement
 164 the common methods there.
 165
 166 Don't include headers in headers except where unavoidable (e.g. for
 167 deriving objects). Opaque typedefs go to app/base/base-types.h,
 168 app/core/core-types.h etc. See devel-docs/includes.txt for a
 169 detailed description of the include policy.
 170
 171 Don't use the GTK wrappers around the GLib object and signal system.
 172
 173 One goal of GIMP development is to make the GIMP code more readable
 174 and understandable. Please help us to achieve this goal by cleaning up
 175 the present code and make sure that all new code follows the coding
 176 guidelines.