Hacking:Developer FAQ

From GIMP Developer Wiki
Revision as of 19:58, 21 January 2014 by Scl (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Below you find a collection of frequently asked questions regarding development of the GIMP.

GIMP Development

Who coordinates GIMP development?

GIMP development is coordinated by Wilber the GIMP along with a loosely knit team of GIMP developers. The developers can be reached through the GIMP developer mailing list.

How can I become a GIMP developer?

If you are a developer who wants to start contributing code to the GIMP, the best way to get to know its structure is by fixing bugs reported in Bugzilla. Pick a bug, perhaps ask the advice of another developer as to whether he/she thinks it will be an easy bug or not, and then fix it. Sounds easy, doesn't it?

After helping with a couple of bugs, people will start to recognize your immense talent, and you will be on your way to becoming a GIMP hacker. Any time you feel able, you can pick a smaller enhancement request and have a go at implementing it. It's that easy.

Where can I discuss GIMP development?

There are several mailing lists associated with the GIMP project. Developments related issues can be brought up on the GIMP Developer mailing list.

The GIMP has its own IRC channel on GIMPNet where most of the active developers hang out. Join us in #gimp on irc.gimp.org.

Every once in a while the GIMP developers get together for a few days to throw a GIMP Developers Conference, also referred to as GIMPCon.

Where can I find documentation for the GIMP API?

You can pass --enable-gtk-doc to the gimp configure script. This requires having gtk-doc installed. After running make you can find the GIMP API reference in the devel-docs directory.

Pre-generated API documentation is included in the official GIMP tarballs.

The API reference will normally be installed in PREFIX/share/gtk-doc/html. An online version of the GIMP API reference can be found here.

How do I make a stack trace?

A stack trace is a list of function calls that leads to some point in the program. Debugging tools like gdb can get stack traces from crashed applications so that developers can figure out what went wrong. By including a stack trace with your bug report, it will be much easier for the developers to fix the reported problem.

Information on how to make a stack trace can be found in the document Capturing Stack Traces.

What is the best way to submit a patch?

The best way to submit a patch is to open a bug report in Bugzilla and attach the patch there along with a description of what it does and why it should be applied.

An introduction to how this is done can be found in the How To Create and Submit a Patch document.

What is the preferred coding style used in GIMP?

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. The GIMP coding style is defined as follows:

   Function names are lowercase, words separated by underscores.
   Macros and enums are all uppercase, words separated by underscores
   Types are all words capitalized, no separators between words.
   All functions in header files need to be prototyped.
   Indentation rules are GNU coding style, in particular:
       2 characters indentation level
       Do not use tabs (of course your editor can use tabs, but it should write them to file as 8 spaces each).
       Opening brackets are on a new line and indented one level.
       Function header have the return type on one line, the name starting in the first column of the following line. All parameters are prototyped and there's a new line for each.

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.

The above coding style, along with other useful information, is documented in the file HACKING.

How can I configure my editor for this coding style?

Your editor will not be able to do everything for you, but you can configure most editors so that they use two spaces for indentation, use spaces instead of tabs, etc.

If you are using Emacs, you can insert the following settings into your ~/.emacs file:

   ;; Merge this into your custom-set-variables section if you already have one
    ;; Syntax highlighting
    '(global-font-lock-mode t nil (font-lock))
    '(show-paren-mode t nil (paren))
   ;; use UTF-8 by default
   (prefer-coding-system 'mule-utf-8)
   ;; use the GNU style for C files, spaces instead of tabs, highlight bad spaces
   (setq c-mode-common-hook '(lambda () (c-set-style "gnu")
                               (setq indent-tabs-mode nil)
                               (setq show-trailing-whitespace t))) 

If you are using Vim, you can insert the following settings into your ~/.vimrc file:

   syn on           " syntax highlighting
   set expandtab    " use spaces instead of tabs
   set shiftwidth=2 " default indentation is 2 spaces 

If you are using another editor and you know how to configure it correctly, please tell us about it on the GIMP developer mailing list so that we can update this FAQ.

Who coordinates the GIMP translation efforts?

Any help with translations is appreciated. If you want to help, please get in contact with the people from the GNOME Translation Project who coordinate all translation efforts for projects hosted in the GNOME GIT repository.

More information about GIMP and localisation can be found in the file README.i18n.

How can I support GIMP development?

By using GIMP and reporting any bugs you find to Bugzilla you're helping a great deal. But there are other non-technical ways of supporting the development of The GIMP as well.

GIMP has a web site, application documentation, lots of tutorials, and more. Unfortunately, as GIMP develops over time, much of this documentation needs to be re-written or freshened up, documentation needs to be added for new functionality, the web site needs to get a new lick of paint and so on.

If you're interested in helping out you should drop an e-mail to the GIMP developer mailing list offering your help.

Plug-In Development

Is there a plug-in template available?

Yes. An official GIMP plug-in template is available in the gimp-plugin-template git module. Snapshots are available at ftp.gimp.org.

How about a Script-Fu template?

Yes. Simon Budig has written a fill-in-the-blanks Script-Fu template which is available here.

How do I get my plug-in included in the GIMP?

The best way to make your plug-in available to the World is to submit it to the GIMP Plug-In Registry.

If you are certain that your plug-in will be useful to all GIMP users, then you can ask the GIMP developers to consider it for inclusion in future GIMP release. The best way to do that is to suggest it on the GIMP developer mailing list or to open an enhancement request in Bugzilla. However, we would like to limit the number of plug-ins included in the standard distribution and encourage all users to use the registry.

How do I debug a GIMP plug-in?

Eeek! The plug-in you're working on has a bug in it! And the fix isn't completely obvious, so you want to use debugger to see what is going on. But hmm, how does one start a plug-in under a debugger if GIMP is the one who is starting the plug-in...

To address this issue, libgimp has some hooks controlled by the GIMP_PLUGIN_DEBUG environment variable. The idea is that you can attach a debugger to the pid of the plug-in you want to debug. The process is described in the file debug-plug-ins.txt.

Will the plug-in I compiled against 2.0 work with GIMP 2.2 or 2.4?

The short answer is yes. GIMP 2.2 and 2.4 are binary compatible with plug-ins compiled for GIMP 2.0. The API is also backwards source compatible, so your plug-in should also compile cleanly against GIMP 2.2 and 2.4.

If the plug-in you compiled for 2.0 does not work with 2.2 or 2.4, there is one change which has been made which is not backwards compatible, since the old behaviour was considered incorrect. If you create a temporary drawable, using for example gimp_layer_new(), you are now required to add it to an image before calling any functions with the drawable as an argument.


What should I put in the commit message when doing a git commit?

Please put a short explanation of the change on the first line. Then, after an empty line, you can describe the change in more detail using as many lines as you need. Try not to exceed 72 colums.

If the commit fixes a bug or part of a bug please use the bug number and description as the first line of the commit message. It's most convenient to just copy the line from the Bugzilla bug page.


What is GEGL?

GEGL is the Generic Graphical Library. It is supposed to replace the handling of various image processing tasks in GIMP in a not too distant future (planned for GIMP 2.6).

What will GEGL be able to do?

GEGL will be a general image processing library. It uses a directed acyclic graph, a DAG, to represent image processing operations. In the DAG, images are edges, and operations are nodes. It takes advantage of this DAG to minimize regions which are processed, provide efficient caching of operations, and efficient redrawing when a parameter of the graph changes.

GEGL should also be independent of the data type being processed and will be able to handle high bit depth images, ICC profiles and parallel processing of image tiles.

What does all that gibberish mean for GIMP?

Many highly requested features of the GIMP will be easier to do using GEGL. Layer effects, layer groups, and adjustment layers are quite easily represented (and efficiently calculated) using the DAG organization of GEGL. CMYK and high bit depth support will be easier because GEGL does not make the same assumptions about color spaces and data types that the GIMP does.

The reusability of image processing operations means that plug-ins will be able to be designed in a much more modular way. The brush system will be able to become more flexible, especially when filter plug-ins are able to be used as procedural brush plug-ins.


What is Bugzilla?

The GIMP project uses GNOME Bugzilla for tracking of bug reports, enhancement requests etc.

A beginners tutorial describing how to report a bug can be found in the How To Report GIMP Bugs document.

An easy to use interface to reporting GIMP bugs can be found on bugs.gimp.org.

What is the meaning of the NEEDINFO status code in Bugzilla?

If the status of a bug is changed to NEEDINFO it means the GIMP developers need more information from the bug reporter in order to resolve the bug.

More information about the meaning of the Bugzilla status field codes can be found in A Bug's Life Cycle.

What is the best way to refer to a bug in Bugzilla?

The best way to refer to a bug is “bug #nnnnn”, where nnnnn is the bug number. Using “bug” before the number allows Bugzilla to link to the corresponding bug report automatically. Using “#” before the number is optional for Bugzilla but makes it easier to locate references to bug reports in the ChangeLog or in e-mails.

When referencing multiple bugs, it is better to be a bit redundant by writing “bug #xxxxx, bug #yyyyy and bug #zzzzz” instead of “bugs #xxxxx, #yyyyy and #zzzzz” in order to allow Bugzilla to link all bugs automatically.

What is the proper way of handling duplicate bug reports?

A bug report describing the same bug as a previous bug report should be marked as DUPLICATE of the older one. In some exceptional cases, it is possible to mark an old bug report as DUPLICATE of a newer one (e.g., when the newer bug report has a significantly better description than the older one).

Another exception is when the same person submits the same bug report several times (same description): in this case, it is better to mark the additional copies of the bug report as INVALID in order to avoid inflating the statistics about the number of duplicates.

What is the proper way of marking a bug as RESOLVED?

When fixing a bug, always mention the bug number in the commit message. Once the changes are in git, paste the relevant part of the commit message (or all of it) in the comment field and mark the bug as RESOLVED FIXED. These cross-references help a lot when trying to find when a bug was fixed, its relations to other bugs, and potential regressions.

A bug that is fixed in git or in an unstable release should be marked as RESOLVED FIXED. Optionally, the reporter or someone other than the one who fixed the bug can mark it as VERIFIED after some testing. When the fix is part of a stable release, it can be marked as CLOSED.

This is explained further in A Bug's Life Cycle except for the difference between stable and unstable releases.


Where can I learn more about the GObject system used by GIMP?

The GObject documentation has a nice tutorial that you might want to have a look at.

Where can I learn more about color spaces etc.?

Charles Poynton has collected a set of Frequently Asked Questions about Color.

Where can I learn more about image manipulation algorithms?

A good source of information is the comp.graphics.algorithms list of Frequently Asked Questions.

Is there a GIMP user FAQ available?

There is no user FAQ available at the moment. However there has been discussions about creating one. If you would like to help with this please drop a mail on the GIMP developer mailing list.

How can I contribute to this FAQ?

If you would like to contribute to this FAQ, send an e-mail to the GIMP developer mailing list with the exact text you think should be included (both question and answer).

With your help this FAQ will grow and become more useful.