In this chapter, we will explain how to compile plug-ins so they can be used in Gimp.
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
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 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
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.
Most of the time, you will go to the plug-in registry or the
When you have downloaded the source code, you must unpack it. Usually, the code ends with
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
If this is the case, check the source file
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
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
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.
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
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.
This is the easiest way to compile a single source 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:
This will both compile the plug-in and install it in your personal
This will compile and install the plug-in in the system-wide Gimp directory.
If the file is named
The following example shows what appeared when we compiled the
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.
Now, let's try to compile it with:
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:
The error messages telling you that an include (header file) is missing looks like this:
Although this message tells us that a file named
To tell the compiler where to search for the file, add the following:
Because the file is located in
which is where the file is located.
The -L flag works the same way. It tells the compiler where to search for libraries (in this case, the libraries
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
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 standard C header files are located in a standard include directory, which the compiler will search. However, the
If the -
The source code lines can also give us a hint about which libraries to link with (in this case,
If you invoke Gimptool with the command
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 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:
It will reply with a list of the
A plug-in can contain more that one C source code file. If the extra file is a header file (named
If the plug-in is built up of several files (such as:
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
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
On the last line, the compiler is told that the final outcome will be a plug-in by adding
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.
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
Makefile:11: *** missing separator. Stop.
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.
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
To build the plug-in, invoke Make by entering
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
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
or like this:
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:
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:
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:
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:
With these two flags you can add an include/library directory like this:
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 want to add more than one libdir, enter the same commands as for the
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
|Frozenriver Digital Design
Voice: +46 (0)31 474356
Fax: +46 (0)31 493833