Adding new plug-ins to The Gimp

So you have downloaded the latest super-duper, all-doing, nice-looking plug-in for The Gimp, but you don't know how to actually plug it in. Here I will try to explain precisely how to do that.

A little background...

A nice thing about The Gimp is that each plug-in is really a separate process. This has the following advantages:

• Since each plug-in is a separate process, they automatically multitask while being applied. You can be scaling an image while you whirl another one and brush-paint on a third.
• The development of new plug-ins is simplified. You only need to know how to use the simple API provided by The Gimp. Your plug-in only needs to display the appropriate dialogs (if necessary), make a mess of the image, and quit.
• If a plug-in crashes, it does not bring down the whole program.

Compiling a new plug-in

Plug-ins are distributed in source form. So, of course, you have to compile them before being able to use them :)

Compiling a plug-in is actually very easy. For now let's assume the plug-in is called mess-up.c. First of all, you have to move the source file to the directory where all the other plug-ins source resides (you *have* the source for The Gimp, don't you? If not, click here). You'll need The Gimp's source code, because it contains the librares which the plug-ins use.

Then you have to modify the Makefile. Look at it; it has a long definition like the following (right below the big bold "You shouldn't have to modify anything below this line"):

FILTERSRC = 	blur.c relief.c to-gray.c to-color.c to-indexed.c	\
		grayify.c bleed.c spread.c edge.c invert.c pixelize.c 	\
		flip_horz.c flip_vert.c shift.c enhance.c		\
		multiply.c difference.c subtract.c add.c		\
		duplicate.c offset.c blend.c composite.c		\
		gamma.c scale.c rotate.c tile.c	gauss.c			\
		compose.c decompose.c netpbm.c				\
		jpeg.c tiff.c gif.c png.c gbrush.c xpm.c tga.c

You have to add the filename of the new plug-in to the end of the list. So, the last lines of that mess should look now like

		compose.c decompose.c netpbm.c				\
		jpeg.c tiff.c gif.c png.c gbrush.c xpm.c tga.c		\
		mess-up.c

In case you have never used makefiles, that instructs make (the program used to organize and compile multifile source packages) to take your plug-in into account.

If your plug-in is one which does not require libraries other than libgimp (The Gimp's plug-in library) and libc (the standard C library; most C programs need this), that's all there is to it. Save the Makefile, and at the prompt, type

	make mess-up

This should compile everything that the plug-in needs. If you get a bunch of errors about missing files or erroneous pathnames, then you will have to edit the Makefile so that it contains the correct paths and all. I won't explain how to do this... if you get to this point and you don't know what to do, it is a good time to learn about make. Type

	man make

to get some idea of what make does, and later visit the GNU Info Tree for detailed documentation.

However, if the plug-in *does* require additional libraries (such as libm, the math library), you will have to add a few more lines to the Makefile. Look below the big definition listed above; there should be some lines which look like

gamma:  gamma.c $(LIBGIMP)
	-$(CC) $(CFLAGS) $(LINCLUDE) -o gamma gamma.c $(LIBGIMP) -lc -lm

rotate: rotate.c $(LIBGIMP)
	-$(CC) $(CFLAGS) $(LINCLUDE) -o rotate rotate.c $(LIBGIMP) -lc -lm

Etcetera. If your plug-in only requires the math library (very likely), you would have to add another two lines like the following:

mess-up: mess_up.c $(LIBGIMP)
	-$(CC) $(CFLAGS) $(LINCLUDE) -o mess-up mess-up.c $(LIBGIMP) -lc -lm

***Note the syntax, it is important!*** If you do not use the correct syntax, make will shout very loudly at you. The whitespace before the second line ("-$(CC) etc.") is a TAB character, not a bunch of spaces.

This tells make the following:

1. The target name is mess-up (that is before the colon).
2. Its dependencies are mess-up.c and whatever is defined into the LIBGIMP variable.
3. The second line is the command line used to compile the plug-in. The last option, -lm, tells the linker to link in the math library (which is called libm.a).

But how do you know which additional libraries the plug-in needs? A good rule of thumb is that if the plug-in uses any of the functions in math.h, it will need the math library (using option -lm, like above). You could test whether the plug-in needs it by using

	grep math.h mess-up.c

This runs the command grep, which looks for text (actually, regular expressions) inside the files you specify. If grep does find the string "math.h" inside the source file, you will have to -lm like above.

To avoid having to add an entry for each new plug-in which requires the math library, you can look for the lines in the Makefile which look like this:

	# If you are using gmake use the following 2 rules...
	%: %.c $(LIBGIMP)
	        $(CC) $(CFLAGS) -o $@ $< $(LIBGIMP) -lc

And you can change the last line to look like

	        $(CC) $(CFLAGS) -o $@ $< $(LIBGIMP) -lc -lm

This instructs the linker to link in the math library by default. This is convenient if you will be adding a lot of plug-ins and you don't want to see whether each of them needs libm.

If you are absolutely clueless about what libraries and include files and all that stuff means, then it is a *VERY* good time to learn some programming :) If you are in a real hurry, politely ask the plug-in's author to help you into compiling and linking the plug-in... most likely, he or she will be glad to help.

Adding the plug-in to the plug-in list

The Gimp reads a file called .gimprc in your home directory at startup to know which plug-ins are installed (and their location). You might remember this file from the time you installed The Gimp.

If you store the compiled plug-ins in a different directory from their source code, you should move the compiled plug-in to that directory.

Open .gimprc and look for lines similar to these:

plug-in blur       "Blur/Blur"                  "AltB"        "Alt+B"
plug-in gauss      "Blur/Gaussian Blur"         "Shift AltB"  "Shft+Alt+B"

The general syntax of these lines is

plug-in binary-name  "Submenu/Title"     "Hotkey"    "Hotkey description"

For our beloved mess-up filter, we would add a line like the following:

plug-in mess-up  "My Plug-ins/Mess Up"

This would cause mess-up not to have any hotkeys defined. If you want, you can add them as described in The Gimp's documentation (or you can figure it out from .gimprc).

Using the plug-in

You have to restart The Gimp to have it re-read .gimprc, so that it will know about your brand-new plug-in. Happy Gimp'ing!

This page last updated: 1996/07/21 11:06:13