Compiling Plug-ins

In this chapter, we will explain how to compile plug-ins so they can be used in Gimp.

Compile

---

A plug-in is a program that can't run on its own; it needs to be started by Gimp. Most of the time, plug-ins are distributed in the source code. All programs have a source code (if they aren't written directly in machine code). The source code is written in a language humans can understand, such as C, C++ and so forth.

The computer doesn't understand C or C++, so the code needs to be translated to machine code that the computer understands and can execute. This translation is called compiling.

Before you can compile, you must have a compiler installed. You must also have programs such as make or ld. Those tools are standard in all major Linux distributions, but you may not have them installed. Consult your Linux distribution manual for information about how to install the development packages you need to be able to compile.

If you work in a Solaris environment, and you chose to install Development system support when you installed Solaris, you already have nearly everything you need for compiling. What you need now is a compiler. You can get GCC (GNU C- compiler) for free. See http://www.sunfreeware.com/ for where to download GCC for Solaris.

Different Ways Of Compiling

There are four common ways to compile: with Gimptool, Make, Configure or plain CC. This chapter covers the basics of different types of compiling, but not extras, such as special compiler flags and debugging.

We really want you to try to compile a plug-in, even if you aren't a programmer or hacker. If you have a friend who is a UNIX programmer, we still think that it's a good idea to read this chapter and give it your best shot. If it goes totally wrong in spite of your having followed the instructions to the best of your capabilities, then by all means, call in your friend.

Gimptool

Gimptool is a program that is integrated with Gimp. It was designed to facilitate the compilation of plug-ins, so using Gimptool is the easiest way to compile plug-ins for Gimp. The plug-in you build, however, can't contain more than a single source file. This means that you can only use the gimp-tool command to build and install plug-ins that consist of one .c file. It can't be modularized to several .c files (we don't mean header files, i.e., files ending with .h). To find out more about Gimptool, see Appendix B; The gimp-tool Man Page, and Using gimp-tool To Compile The Plug-in.

Compiling With Make, Configure Or Plain Cc

There are three ways to compile:

1. Make is a program that executes a specification file commonly called Makefile. By running this file, it will compile the program with the help of the compiler.

2. Configure is a program that generates a Makefile. After doing this, you will have to run Make to compile.

3. The most basic, but also the hardest way, is to use the compiler to compile the code without a help program.

How To Obtain And Install The Source Code

---

Most of the time, you will go to the plug-in registry or the Gimp.org FTP site to obtain/download the source code. Other sources of information are Gimp News and the Gimp developer/Gimp user mailing lists.

Unpacking The Source Code

When you have downloaded the source code, you must unpack it. Usually, the code ends with xxx.c.gz, xxx.tgz or xxx.tar.gz.

The xxx.c.gz can be decompressed with:

gunzip xxx.c.gz

The xxx.tgz and xxx.tar.gz archives can be unpacked with:

cat xxx.tgz | gunzip|tar xvf -

Before you unpack the source, move it to a new directory. Then unpack and build the plug-in. For example, in an Xterm window, enter the following commands:

If the plug-in source file ends with xxx.c, then the file has already been decompressed. If you have used Netscape to download the file, you can save it. Remember, however, that Netscape often tries to decompress downloaded archives and that it sometimes fails to do this.

If this is the case, check the source file xxx.c with a file viewer such as More (for example, more xxx.c). If you can't read what's in the file, then it's not decompressed. To fix it, enter:

mv xxx.c xxx.c.gz && gunzip xxx.c.gz.

Compiling The Code

---

We will use GNU tools to compile the code. If you are using a system that doesn't have GNU tools installed, then you have two options: Download and install GNU tools (beyond the scope of this book) or use the system's own tools.

There is no big difference between GNU and system tools. Some of the GNU tools can be recognized by the fact that their names start with the letter g. For example, the GNU compiler is called gcc and the system's own compiler is called cc.We think that this won't make any difference here, but we can't be sure because there are a lot of different Unix systems out there, and we can't cover them all.

Finding Out How To Compile The Plug-in

When you have downloaded and unpacked the plug-in source, you have to find out how to compile it. The plug-ins are often packed with several other files. Sometimes, there is a README or INSTALL file. If you find one of these files, always read it.

Most of the time, you will find information about how to compile and install the plug-in in one of these files. You can also look in the head of the C code file. If there is no information, follow our examples here.

The README file should tell you whether you need additional libraries to compile the plug-in. For example, you may need the libtif library and header files to compile the plug-in. If you don't have these libraries or header files, the building of the plug-in will fail.

To find out if you have these libraries or other required programs, read the section called Installing A Source Distribution.

Compiling a library is a bit different than compiling a plug-in, but the start is basically the same.

If the plug-in you've downloaded is a single file or if the archive you just unpacked has no Makefile (it may be called Makefile, Makefile.classic, MAKEFILE,etc.) or configure file, then you have to compile it directly with Gimptool or GCC, or create a Makefile or configure script.

If there is a Makefile, then you can use make to compile the plug-in. Before you begin, check the Makefile to find out whether it is correct for your system. If there is a configure script, then use the configure script to generate a Makefile.

Using gimp-tool To Compile The Plug-in

This is the easiest way to compile a single source plug-in:

gimptool --build plugin.c

where plugin.c is the name of the plug-in source file. This will most likely build your plug-in.

However, if the build process failed and a message such as the following appears, then read Using GCC To Compile The Plug-in and compile it with GCC directly.

When you have compiled it, you will probably also want to install the plug-in. You can do this by invoking Gimptool:

gimptool --install plugin.c

This will both compile the plug-in and install it in your personal .gimp directory. If you are a system administrator and want to install the plug-in for all users on your system, then use Gimptool like this:

gimptool --install-admin plugin.c

This will compile and install the plug-in in the system-wide Gimp directory.

Using GCC To Compile The Plug-in

A First Try

If the file is named plugin.c, then compile it with:

gcc -o plug-in plugin.c.

The -o flag tells the compiler that the final output (the plug-in) should be named plug-in. If your C compiler (GCC) is configured to search the standard directories for the include and library files and those files are in the standard directories, then the plug-in will compile cleanly. However, it is quite unlikely that this will happen; you will probably need specific Gimp libraries and include files.

The following example shows what appeared when we compiled the waterselect.c file in the way we just described:

Libraries

This happens when the necessary libraries aren't linked to the executable that you are trying to build. A library is a set of functions, for example, a function that creates a window or a scrollbar. The compiler checks that the functions are available for the plug-in to use when it is executed.

Another Try

Now, let's try to compile it with:

gcc -o plug-in plugin.c -L/usr/local/lib -lgtk
-lgimp

Now the plug-in compiles cleanly on the system. If you work on Sun Solaris system, add the following before even starting to think about libraries:

-I/usr/local/include

Include File

The error messages telling you that an include (header file) is missing looks like this:

waterselect.c:39: gtk/gtk.h: No such file or directory

Although this message tells us that a file named gtk.h is missing, this is not always the case. A more correct answer is that the compiler (more accurately the preprocessor compiler) can't find it in the directories it was configured to search.

To tell the compiler where to search for the file, add the following:

-I/where/to/search

Because the file is located in /usr/local/include/gtk, and the error was "can't find gtk/gth.h," this tells us that the compile line will be:

gcc -o plug-in plugin.c -L/usr/local/lib \
-lgimp -lgtk -I/usr/local/include

-I/usr/local/include that was added tells the compiler to search that directory for include files (in our case, gtk/gtk.h). The compiler will find the file because it will add:

gtk/gtk.h

to:

/usr/local/include

resulting in:

/usr/local/include/gtk/gtk.h

which is where the file is located.

The -L Flag And How To Find Out Which Libs To Link

The -L flag works the same way. It tells the compiler where to search for libraries (in this case, the libraries libgimp.so and libgtk.so). The -lgimp is a shortcut, so we don't have to write libgimp.so.

To determine which libraries to add and which directories to include, look inside the code (generally located in the beginning of the file). Here's an example from the waterselect.c file:

This code tells us that the compiler will include five files when it compiles the code. The first three are ordinary standard C include files and the other ones are special Gimp and GTK files.

The -I Flag

The standard C header files are located in a standard include directory, which the compiler will search. However, the gtk.h and gimp.h files aren't in a standard directory, so tell the compiler (-I flag).

If the -I flag is /usr/local/include, the compiler will try to get the gtk.h files in:

/usr/local/include/gtk/gtk.h.

The source code lines can also give us a hint about which libraries to link with (in this case, libgimp and libgtk). The standard C library and Math library are linked by default on most systems.

How To Use Gimptool To Get Lib And Include Flags

If you invoke Gimptool with the command gimptool --libs, it will reply with the following (site dependent):

It will give you all of the libraries and -L flags that were used to compile Gimp. This can be very useful if you compile a plug-in that needs the TIFF library and the Gimptool libraries. Then, you can invoke gcc like this:

gcc -o plug-in `gimptool --libs` -ltiff plugin.c

Gcc will now compile and link your plug-in with all Gimp libraries, in addition to the TIFF library. If you want to include all include flags, invoke Gimptool like this:

gimptool --cflags

It will reply with a list of the CFLAGS used to compile Gimp.

What To Do When There Are Several Source Files

A plug-in can contain more that one C source code file. If the extra file is a header file (named plugin.h), then we can compile the plug-in just as we did before. The header file is a file that specifies functions and how to call these functions. Look at the files (or just the header file) to find out what include directories to include and which libraries to link.

If the plug-in is built up of several files (such as: pluginmain.c, pluginpart1.c, pluginpart2.c, etc.), compile each part separately and then link them to an executable plug-in.

Object files must be made out of each part. These object files will then be linked, thus creating the final executable plug-in. For example :

On the first three lines, the object files are made. The compiler is instructed to make object files by adding the -c flag. When object files are made, we don't need to worry about libraries, we only have to make sure that the compiler finds the include files which is why only the -I flag is used when the object files are created.

On the last line, the final plug-in is made. Here, we don't need to worry about include files, we only have to make sure that we link the libraries needed by the plug-in. When the object files are made, descriptions of library function calls are included by including header files. The plug-in object file happily uses them because it assumes that it will be linked to these libraries later on. You can also use the gimptool --cflags and gimptool --libs commands to include libraries and directories. We recommend using Gimptool to avoid errors, and a lot of typing.

On the last line, the compiler is told that the final outcome will be a plug-in by adding -o plug-in, then the object files made in the first three lines. Because a lot of library functions have been used in the object files, add the libraries to provide these functions to the plug-in by adding -lgimp, -lgimpui. Tell the compiler where to search for the libraries by adding -L/usr/local/lib. The directory /usr/lib and /lib are also searched by default.

When building a plug-in that consists of several parts, compiling the different parts manually is often the wrong method to use. If something goes wrong, you will have to type all your commands again. The solution is to create a Makefile. A Makefile is a specification that the Make command uses as an input to compile the entire plug-in with the help of the compiler.

How To Create A Makefile And How To Use It

Now, we'll take a look at how to create a simple Makefile. This will help us understand the structure of a Makefile, so that we'll know how to edit a Makefile which comes with a plug-in. The following is an example of a generic Makefile:

This Makefile builds the object files first, and then links the plug-in. To use it, replace the header, object and source files with the correct ones. You can also change what libraries to link and what directories to search for libs and includes. The CFLAG -O2 represents optimization of the executable. Notice the tab at the last line. If you forgot the tab you will get this error message:

Makefile:11: *** missing separator. Stop.

A Makefile Example

Here's how the Makefile looked when we built the Guash plug-in at our Linux system (there is a Makefile included in the distribution of Guash; this example is only for training):

The important thing is to change and maybe add include and library directories so it will fit your system. Remember that you can write a Make-file in several different ways, this is only one of many.

Variables

When you edit your Makefile, it may not look like this, but with the basic instruction and knowledge about how to compile, you should be able to edit it anyway. The first eight lines are variables that are called later on lines 10 and 11 with $(VARIABLE). The special $@ variable is an internal variable that expands to the first word in the line above it (i.e., Guash, in this example).

To build the plug-in, invoke Make by entering make or:

make -f WhatYouCallYourMakefile.

Make will invoke gcc to build your object files and to link your executable.

A common error that occurs when you use a Makefile to compile a plug-in that comes as an archive is that the Make-program complains about dependencies. If so, remove the .deps directory (rm -rf .deps) in the building directory. Dependencies can also be included in the Makefile. You will find them at the end of the file. Remove them, and everything should work fine.

How To Use Gimptool In A Makefile

This is the way to change the previous Makefile using Gimptool instead of specifying all of the libraries and include directories.

There is a lot less typing involved, and you may also be sure of getting all of the necessary Gimp-related libraries and includes into the Makefile. If the plug-in needs more libraries or include directories, you can add it after the gimptool command:

INCDIR = `gimptool --cflags` -I/usr/opt/include

or like this:

LIBDIR = `gimptool --libs` -L/opt/lib -ltiff

Configure To Automate The Building Process

The configure script that comes with the plug-in is a way to automate the process of making a Makefile. The configure script will try to find the include files and libraries that the plug-in needs.

If you are on a common UNIX platform like Solaris or Linux, then it's simple to use a configure script. To build your plug-in, enter the following in the directory where you unpacked the plug-in:

./configure && make

Now, the plug-in will be compiled and ready to use. Make sure that you are in the directory where the configure script is located; otherwise, you will get this error message:

bash: ./configure: No such file or directory.

If you don't have a certain file or library, or the script can't find it, then you will have to install it or tell the script where to find it.

To find out how to tell the script where to find include files and libraries, invoke the script like this:

./configure --help

This will result in several lines of flags that you can supply the script with. Here's an extract of the most important flags that you can include in your script:

--libdir=DIR

--includedir=DIR

With these two flags you can add an include/library directory like this:

--includedir=/your/includedir.

If you want to add more than one include directory, you have to do it this way if you work in an ordinary shell:
If you are working in a C shell, then you have to do it like this:

If you want to add more than one libdir, enter the same commands as for the CFLAGS, but type: LDFLAGS instead.

You may run into several problems, especially if you are using a UNIX dialect that is different from what the authors of the configure script were working on. If you run into a problem, first try to add all of the libraries and include directories to the script with the FLAGS or manually in the generated Makefile. If this still doesn't solve the problem, try writing to the Gimp mailing list.