From ca5b2cd7c726f49fb16072660121ad38800844dc Mon Sep 17 00:00:00 2001 From: Bruno Lopes Date: Sat, 13 Jan 2024 22:26:07 -0300 Subject: [PATCH] devel-docs: Update content according to 'gimp-web-devel' - Drops HACKING file (it is outdated and we have the "same thing", updated, in the devel site), but moved PDB content to the README * Update various links now to the devel site + Added 'TODOs' to avoid confusion from titles with empty content and removed some that are already implemented --- devel-docs/HACKING.md | 155 ------------------------------------------ devel-docs/README.md | 86 +++++++++++------------ 2 files changed, 40 insertions(+), 201 deletions(-) delete mode 100644 devel-docs/HACKING.md diff --git a/devel-docs/HACKING.md b/devel-docs/HACKING.md deleted file mode 100644 index 4a9e60ab4a..0000000000 --- a/devel-docs/HACKING.md +++ /dev/null @@ -1,155 +0,0 @@ -# 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; - -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 and -pkg.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](https://developer.gimp.org/core/coding_style/). 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: - -* `AUTHORS` from `authors.xml` diff --git a/devel-docs/README.md b/devel-docs/README.md index 0b87f5e8de..5faf2e8836 100644 --- a/devel-docs/README.md +++ b/devel-docs/README.md @@ -72,7 +72,7 @@ The whole C reference documentation for both these libraries can be generated in the main GIMP build with the `-Dgi-docgen=enabled` meson option (you need to have the `gi-docgen` tools installed). -TODO: add online links when it is up for the new APIs. +See the [API documentation](https://developer.gimp.org/api/3.0/) ### Programming Languages @@ -101,7 +101,7 @@ full-featured since they don't require manual tweaking. Therefore any function in the C library should have an equivalent in any of the bindings. -TODO: binding reference documentation. +**TODO**: binding reference documentation. **Note**: several GObject-Introspection's Scheme bindings exist though we haven't tested them. Nevertheless, GIMP also provides historically @@ -112,17 +112,18 @@ development](#script-fu-development) section. ### Tutorials -TODO: at least in C and in one of the officially supported binding +**TODO**: at least in C and in one of the officially supported binding (ideally even in all of them). ### Porting from GIMP 2 plug-ins +Take a look at our [porting guide](GIMP3-plug-in-porting-guide/README.md). + ### Debugging GIMP provides an infrastructure to help debugging plug-ins. -You are invited to read the [dedicated -documentation](debug-plug-ins.txt). +You are invited to read the [dedicated documentation](https://developer.gimp.org/resource/debug-plug-ins/). ## Script-fu development @@ -132,11 +133,13 @@ Scheme mini-interpreter and therefore `Script-fu` scripts do not use `libgimp` or `libgimpui`. They interface with the PDB through the `Script-fu` plug-in. -### Tutorials +### TODO: Tutorials ### Porting from GIMP 2 scripts -## GEGL operation development +Take a look at our [ScriptFu porting guide](GIMP3-plug-in-porting-guide/script-fu-author-guide.md) + +## TODO: GEGL operation development ## Custom data @@ -176,8 +179,8 @@ recent versions. If you are interested in brushes from a developer perspective, you are welcome to read specifications of GIMP formats: -[GBR](specifications/gbr.txt), [GIH](specifications/gih.txt), -[VBR](specifications/vbr.txt) or the obsolete [GPB](specifications/gpb.txt). +[GBR](https://developer.gimp.org/core/standards/gbr/), [GIH](https://developer.gimp.org/core/standards/gih/), +[VBR](https://developer.gimp.org/core/standards/vbr/) or the obsolete [GPB](https://developer.gimp.org/core/standards/gpb/). If you want to contribute brushes to the official GIMP, be aware we would only accept brushes in non-obsolete GIMP formats. All these @@ -199,11 +202,11 @@ within GIMP. ### Patterns GIMP supports the GIMP Pattern format (PAT, whose -[specification](specifications/pat.txt) is available for developers). +[specification](https://developer.gimp.org/core/standards/pat/) is available for developers). This format can be exported by GIMP itself. -Alternatively GIMP supports patterns from `GdkPixbuf` (TODO: get more +Alternatively GIMP supports patterns from `GdkPixbuf` (**TODO**: get more information?). ### Palettes @@ -214,7 +217,7 @@ GIMP. ### Gradients GIMP supports the GIMP Gradient format (GGR, whose -[specification](specifications/ggr.txt) is available for developers) +[specification](https://developer.gimp.org/core/standards/ggr/) is available for developers) which can be generated from within GIMP. Alternatively GIMP supports the SVG Gradient format. @@ -239,14 +242,7 @@ Finally you can look at our existing themes, like the [System theme](https://gitlab.gnome.org/GNOME/gimp/-/blob/master/themes/System/gimp.css). Note though that this `System` theme is pretty bare, and that's its goal (try to theme as few as possible over whatever is the current real -system theme). - -TODO: for any theme maker reading this, what we want for GIMP 3.0 are at -least the following additional themes: - -- a full custom theme using neutral grayscale colors with a dark and - light variant; -- a mid-gray neutral theme. +GTK system theme). As a last trick for theme makers, we recommend to work with the GtkInspector tool, which allows you to test CSS rules live in the `CSS` @@ -294,10 +290,10 @@ styling. See the dedicated [icons documentation](icons.md) for more technical information. -### Tool presets +### TODO: Tool presets -## GIMP extensions (*.gex*) +## TODO: GIMP extensions (*.gex*) ## Continuous Integration @@ -385,35 +381,20 @@ When writing code, any core developer is expected to follow: - the [directory structure](#directory-structure-of-gimp-source-tree) - our [header file inclusion policy](includes.txt) -[GIMP's developer wiki](https://wiki.gimp.org/index.php/Main_Page) can -also contain various valuable resources. +[GIMP's developer site](https://developer.gimp.org/) contain various valuable resources. -Finally the [debugging-tips](debugging-tips.md) file contain many very +Finally the [debugging-tips](https://developer.gimp.org/core/debug/debugging-tips/) file contain many very useful tricks to help you debugging in various common cases. ### Newcomers If this is your first time contributing to GIMP, you might be interested -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. +by [build instructions](https://developer.gimp.org/core/setup/). -You might also like to read these [instructions on submitting -patches](https://gimp.org/bugs/howtos/submit-patch.html). +You might also like to read these instructions on the process of +[submitting patches](https://developer.gimp.org/core/submit-patch/). -If you are unsure what to work on, this [list of bugs for -newcomers](https://gitlab.gnome.org/GNOME/gimp/-/issues?scope=all&state=opened&label_name[]=4.%20Newcomers) -might be a good start. It doesn't necessarily contain only bugs for -beginner developers. Some of them might be for experienced developers -who just don't know yet enough the codebase. - -Nevertheless we often recommend to rather work on topics which you -appreciate, or even better: fixes for bugs you encounter or features you -want. These are the most self-rewarding contributions which will really -make you feel like developing on GIMP means developing for yourself. - -### Core Contributors +### TODO: Core Contributors ### Directory structure of GIMP source tree @@ -484,6 +465,19 @@ The source code of the main GIMP application is found in the `app/` directory: | app/widgets/ | Collection of widgets used in the application GUI | | app/xcf/ | XCF file handling in **core** | +#### 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: + +* `AUTHORS` from `authors.xml` + You should also check out [gimp-module-dependencies.svg](gimp-module-dependencies.svg). **TODO**: this SVG file is interesting yet very outdated. It should not be considered as some kind dependency rule and should be updated. @@ -497,7 +491,7 @@ features made available in GIMP. More than an image format, you may consider it as a work or project format, as it is not made for finale presentation of an artwork but for the work-in-progress processus. -Developers are welcome to read the [specifications of XCF](specifications/xcf.txt). +Developers are welcome to read the [specifications of XCF](https://developer.gimp.org/core/standards/xcf/). #### Locks @@ -510,8 +504,8 @@ This is further explained in [the specifications of locks](https://developer.gim GIMP has an evolved GUI framework, with a toolbox, dockables, menus… -This [document describing how the GIMP UI framework functions and how it -is implemented](ui-framework.txt) might be of interest. +This document describing how the GIMP UI framework functions and how it +is [implemented](ui-framework.txt) might be of interest. #### Contexts