From bad465c6816e817a9f5148e41a394c1ca66a4ade Mon Sep 17 00:00:00 2001 From: Jehan Date: Mon, 7 Feb 2022 15:14:12 +0100 Subject: [PATCH] README, devel-docs: reorganize a bit the main README and devel docs. - ps-menurc removed in GIMP 2.7.2 (i.e. stable 2.8.0) according to NEWS.pre-2-8. - in our main README, redirect now to devel-docs/README.md as entry point for contributors. - move HACKING to devel-docs/ and specialize it into a "how to build from git and contributed" docs: * Make it markdown. * Remove some now obsolete or redundant recommendations (to be fair, we can probably clean up the file a bit more, but we'll see). * Add/improve relevant information. * Make more obvious when you want to build from tarball or git. * Just keep a single short paragraph about the coding style to redirect people to the appropriate CODING_STYLE.md file. * Don't recommend sending patches to the mailing list anymore. - move CODING_STYLE.md to devel-docs/. --- HACKING | 149 ---------------- README | 11 +- CODING_STYLE.md => devel-docs/CODING_STYLE.md | 0 devel-docs/HACKING.md | 160 ++++++++++++++++++ devel-docs/README.md | 9 +- 5 files changed, 171 insertions(+), 158 deletions(-) delete mode 100644 HACKING rename CODING_STYLE.md => devel-docs/CODING_STYLE.md (100%) create mode 100644 devel-docs/HACKING.md diff --git a/HACKING b/HACKING deleted file mode 100644 index fb17479186..0000000000 --- a/HACKING +++ /dev/null @@ -1,149 +0,0 @@ -Requirements ------------- -If you want to hack on the GIMP project, it will make your life easier -to have the following packages (or newer versions) installed: - - * GNU autoconf 2.54 or over - - ftp://ftp.gnu.org/gnu/autoconf/ - * GNU automake 1.13 or over - - ftp://ftp.gnu.org/gnu/automake/ - * GNU libtool 1.5 or over - - ftp://ftp.gnu.org/gnu/libtool/ - -Alternatively a build with meson 0.54.0 or over is possible but it is -not complete yet, hence not usable for packaging (yet usable for -development). - -Fine GNU mirrors are listed at https://www.gnu.org/prep/ftp.html -Beta software can be found at alpha.gnu.org. - - * pkg-config 0.16.0 (or preferably a newer version) - - https://www.freedesktop.org/software/pkgconfig/ - - * xsltproc - - ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.1/ - -These are only the additional requirements if you want to compile from -the git repository. The file INSTALL lists the various libraries we -depend on. - - -Compilation ------------ -If you are accessing gimp via git, then you will need to take several -steps to get it to compile. You can do all these steps at once by -running: - - gimp/trunk$ ./autogen.sh - -Basically this does the following for you: - - gimp/trunk$ aclocal-1.9; libtoolize; automake-1.9 -a; - gimp/trunk$ autoconf; intltoolize --automake - -The above commands create the "configure" script. Now you can run the -configure script in gimp/trunk to create all the Makefiles. - -Before running autogen.sh or configure, make sure you have libtool in -your path. Also make sure glib-2.0.m4 glib-gettext.m4, gtk-2.0.m4, -pkg.m4 and intltool.m4 are either installed in the same -$prefix/share/aclocal relative to your automake/aclocal installation -or call autogen.sh as follows: - - $ ACLOCAL_FLAGS="-I $prefix/share/aclocal" ./autogen.sh - -Note that autogen.sh runs configure for you. If you wish to pass -options like --prefix=/usr to configure you can give those options to -autogen.sh and they will be passed on to configure. - -If AUTOGEN_CONFIGURE_ARGS is set, these options will also be passed to -the configure script. If for example you want to enable the build of -the GIMP API reference manuals, you can set AUTOGEN_CONFIGURE_ARGS to -"--enable-gtk-doc". Please note that you will then need a recent -version of gtk-doc as well as a working setup for handling DocBook/XML. - -If you do not have a recent version of gtk-doc, you can pass the -option "--disable-gtk-doc" to autogen.sh. This will completely -disable the support for gtk-doc so you will not be able to generate -the API documentation. - -If you want to use libraries from a non-standard prefix, you should set -PKG_CONFIG_PATH appropriately. Some libraries do not use pkgconfig, see -the output of ./configure --help for information on what environment -variables to set to point the compiler and linker to the correct path. -Note that you need to do this even if you are installing Gimp itself -into the same prefix as the library. - - -Git ---- -GIMP is available from GNOME Git. You can use the following commands -to get GIMP from the the git server: - - $ git clone https://gitlab.gnome.org/GNOME/gimp.git - -You can read more on using GNOME's git service at these URLs: - - https://wiki.gnome.org/Git - https://www.kernel.org/pub/software/scm/git/docs/ - - -You will also need relatively new stable releases of glib, pango, atk, -gtk+, cairo, gtkhtml2, etc. for building GIMP, which you can get as a -part of recent Linux distribution releases. - - -Patches -------- - -The best way to submit patches is to provide files created with -git-format-patch. The recommended command for a patch against the -`master` branch is: - - $ git format-patch origin/master - -It is recommended that you file a bug report at -https://gitlab.gnome.org/GNOME/gimp -and either create a merge request or attach your patch to it as a plain -text file, not compressed. If your patch is reasonably small you can -submit it to the gimp-developer-list@gnome.org mailing list. - -If the patch needs to be discussed, you should also consider using the -mailing list instead of Bugzilla because bug reports tend to be hard -to read if they contain too many comments. For the code, please try to -follow the guidelines given in Hackordnung, below. - - -Auto-generated Files --------------------- -Please notice that some files in the source are generated from other -sources. All those files have a short notice about being generated -somewhere at the top. Among them are the files ending in pdb.[ch] in -the libgimp directory and the files ending in cmds.c in the app/pdb -subdirectory. Those are generated from the respective .pdb files in -pdb/groups. - - -Hackordnung ------------ -We encourage you to follow the GIMP coding style throughout the GIMP -project. For the core components (application and libs) this coding -style is enforced. See separate CODING_STYLE.md for a detailed description -of the source code style. - -Try to make use of GLib's object system as much as possible. Do not -create wrappers around functions of parent classes. If you end up -duplicating code, try to create a common parent class and implement -the common methods there. - -Don't include headers in headers except where unavoidable (e.g. for -deriving objects). Opaque typedefs go to app/base/base-types.h, -app/core/core-types.h etc. See devel-docs/includes.txt for a -detailed description of the include policy. - -Don't use the GTK wrappers around the GLib object and signal system. - -One goal of GIMP development is to make the GIMP code more readable -and understandable. Please help us to achieve this goal by cleaning up -the present code and make sure that all new code follows the coding -guidelines. diff --git a/README b/README index a9a60309a7..d91f6116af 100644 --- a/README +++ b/README @@ -12,8 +12,8 @@ If you think you found a bug in this version, please make sure that it hasn't been reported earlier and that it is not just new stuff that is still being worked on and obviously not quite finished yet. -If you want to hack on GIMP, please read the file HACKING. For -detailed installation instructions, see the file INSTALL. +If you want to hack on GIMP, please read the file devel-docs/README.md. +For detailed installation instructions, see the file INSTALL. 1. Web Resources @@ -76,11 +76,8 @@ gtk.css in particular) or by using "themes" (ready-made customizations). Additionally, GIMP reads `${XDG_CONFIG_HOME}/GIMP/2.99/gimp.css` so you can have settings that only apply to GIMP. -Included is a set of keybindings similar to those in Adobe Photoshop. -You can find them in the ps-menurc file. To use them, copy this file -to `${XDG_CONFIG_HOME}/GIMP/2.99/menurc`. You can also manually change -the keybindings to any of your choice by editing: -`${XDG_CONFIG_HOME}/GIMP/2.99/menurc`. +You can also manually change the keybindings to any of your choice by +editing: `${XDG_CONFIG_HOME}/GIMP/2.99/menurc`. Have fun, diff --git a/CODING_STYLE.md b/devel-docs/CODING_STYLE.md similarity index 100% rename from CODING_STYLE.md rename to devel-docs/CODING_STYLE.md diff --git a/devel-docs/HACKING.md b/devel-docs/HACKING.md new file mode 100644 index 0000000000..0e8a482ba7 --- /dev/null +++ b/devel-docs/HACKING.md @@ -0,0 +1,160 @@ +# Building from git and contributing + +While packagers are expected to compile GIMP from tarballs (same for +personal usage), developers who wish to contribute patches should +compile from the git repository. + +The procedure is basically the same (such as described in the `INSTALL` +file, which you will notice doesn't exist in the repository; you can +find [INSTALL.in](/INSTALL.in) instead, whose base text is the same +before substitution by the build configuration step). Yet it has a few +extra steps. + +## Git + +GIMP is available from GNOME Git. You can use the following commands +to get GIMP from the the git server: + + $ git clone https://gitlab.gnome.org/GNOME/gimp.git + +You can read more on using GNOME's git service at these URLs: + + https://wiki.gnome.org/Git + https://www.kernel.org/pub/software/scm/git/docs/ + + +The development branches of GIMP closely follow the development branches +of `babl` and `GEGL` which are considered part of the project. Therefore +you will also have to clone and build these repositories: + + $ git clone https://gitlab.gnome.org/GNOME/babl.git + $ git clone https://gitlab.gnome.org/GNOME/gegl.git + + +As for other requirements as listed in the `INSTALL` file, if you use +a development-oriented Linux distribution (Debian Testing or Fedora for +instance), you will often be able to install all of them from your +package manager. On Windows, the MSYS2 project is great for keeping up +with libraries too. On macOS, it is unfortunately much more of a hurdle +and you should probably look at instructions in our [gimp-macos-build +repository](https://gitlab.gnome.org/Infrastructure/gimp-macos-build) +which is how we build GIMP for macOS. + +We also know that GIMP is built on various \*BSD, proprietary Unixes, +even on GNU-Hurd and less known systems such as Haiku OS but we don't +have much details to help you there. Yet we still welcome patches to +improve situation on any platform. + +In any case, if you use a system providing too old packages, you might +be forced to build from source (tarballs or repositories) the various +dependencies list in `INSTALL`. + +## Additional Requirements + +Our autotools build system requires the following packages (or newer +versions) installed when building from git (unlike building from +tarball): + + * GNU autoconf 2.54 or over + - ftp://ftp.gnu.org/gnu/autoconf/ + * GNU automake 1.13 or over + - ftp://ftp.gnu.org/gnu/automake/ + * GNU libtool 1.5 or over + - ftp://ftp.gnu.org/gnu/libtool/ + +Alternatively a build with meson 0.53.0 or over is possible but it is +not complete yet, hence not usable for packaging (yet usable for +development). + +For some specific build rules, you will also need: + + * xsltproc + - ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.1/ + +In any cases, you will require this tool for dependency retrieval: + + * pkg-config 0.16.0 (or preferably a newer version) + - https://www.freedesktop.org/software/pkgconfig/ + +These are only the additional requirements if you want to compile from +the git repository. The file `INSTALL` lists the various libraries we +depend on. + + +## Additional Compilation Steps + +If you are accessing GIMP via git, then you will need to take more +steps to get it to compile. You can do all these steps at once by +running: + + gimp/trunk$ ./autogen.sh + +Basically this does the following for you: + + gimp/trunk$ aclocal-1.9; libtoolize; automake-1.9 -a; + gimp/trunk$ autoconf; intltoolize --automake + +The above commands create the "configure" script. Now you can run the +configure script in gimp/trunk to create all the Makefiles. + +Before running autogen.sh or configure, make sure you have libtool in +your path. Also make sure glib-2.0.m4 glib-gettext.m4, gtk-3.0.m4, +pkg.m4 and intltool.m4 are either installed in the same +$prefix/share/aclocal relative to your automake/aclocal installation +or call autogen.sh as follows: + + $ ACLOCAL_FLAGS="-I $prefix/share/aclocal" ./autogen.sh + +Note that autogen.sh runs configure for you. If you wish to pass +options like --prefix=/usr to configure you can give those options to +autogen.sh and they will be passed on to configure. + +If AUTOGEN_CONFIGURE_ARGS is set, these options will also be passed to +the configure script. If for example you want to enable the build of +the GIMP API reference manuals, you can set AUTOGEN_CONFIGURE_ARGS to +"--enable-gi-docgen". + +If you want to use libraries from a non-standard prefix, you should set +PKG_CONFIG_PATH appropriately. Some libraries do not use pkgconfig, see +the output of ./configure --help for information on what environment +variables to set to point the compiler and linker to the correct path. +Note that you need to do this even if you are installing GIMP itself +into the same prefix as the library. + + +## Patches + +The best way to submit patches is to provide files created with +git-format-patch. The recommended command for a patch against the +`master` branch is: + + $ git format-patch origin/master + +It is recommended that you file a bug report in our +[tracker](https://gitlab.gnome.org/GNOME/gimp) and either create a merge +request or attach your patch to the report as a plain text file, not +compressed. + +Please follow the guidelines for coding style and other requirements +listed in [CODING_STYLE.md](CODING_STYLE.md). When you will contribute +your first patches, you will notice that we care very much about clean +and tidy code, which helps for understanding. Hence we care about coding +style and consistency! + + +## Auto-generated Files + +Please notice that some files in the source are generated from other +sources. All those files have a short notice about being generated +somewhere at the top. Among them are the files ending in `pdb.[ch]` in +the `libgimp/` directory and the files ending in `cmds.c` in the +`app/pdb/` subdirectory. Those are generated from the respective `.pdb` +files in `pdb/groups`. + +Other files are: + +* `plug-ins/common/Makefile.am` generated by running + `plug-ins/common/mkgen.pl`. +* `icons/Color/Makefile.am` and `icons/Symbolic/Makefile.am` generated + by `tools/generate-icon-makefiles.py` +* `AUTHORS` from `authors.xml` diff --git a/devel-docs/README.md b/devel-docs/README.md index 2808615f13..f310614fe2 100644 --- a/devel-docs/README.md +++ b/devel-docs/README.md @@ -330,7 +330,7 @@ Eventually we want to move this pipeline to Gitlab as well. When writing code, any core developer is expected to follow: -- GIMP's [coding style](/CODING_STYLE.md); +- GIMP's [coding style](CODING_STYLE.md); - the [directory structure](#directory-structure-of-gimp-source-tree) - our [header file inclusion policy](includes.txt) @@ -340,7 +340,12 @@ also contain various valuable resources. ### Newcomers If this is your first time contributing to GIMP, you might be interested -by these [instructions on submitting +by build instructions. The previously mentioned wiki in particular has a +[Hacking:Building](https://wiki.gimp.org/wiki/Hacking:Building) page +with various per-platform subpages. The [HACKING](HACKING.md) docs will +also be of interest. + +You might also like to read these [instructions on submitting patches](https://gimp.org/bugs/howtos/submit-patch.html). If you are unsure what to work on, this [list of bugs for