I plan to eventually post it to the official gimp manual.
I was helped by some people in #gimp, and without their help, I would still be lost.
tml and schumaml helped me with technical problems, and Ankh made suggestions about some sentences which could anger others.
I have just been the will that gathers knowledges from others.
Please read the attached HTML manual and make suggestions.
How to compile a C gimp plugin on windows
Written on 17 Apr 2010 by muffin
- Introduction to gimptool-2.0, pkg-config, MinGW, and MSYS
When you compile a gimp plugin on windows, you have to make sure every relevant import library and header is included.
GIMPTOOL-2.0
Gimptool-2.0 takes care of finding and including headers and import libraries. Gimptool-2.0 is simple to use. "Gimptool-2.0 --build xxx.c" will build but not install an .exe plugin, and "gimptool-2.0 --install xxx.c" will build and install an .exe plugin in "the gimp plugin directory in user's home directory". Gimptool-2.0 is simply a front-end that passes appropriate compiler options to GCC.
MinGW
GCC is the GNU compiler collection and contains a C compiler. GCC is mainly used in unix systems, but people made "GCC for windows" and gave it the name, MinGW(Minimal GNU for window).
MSYS
MSYS(Minimal SYStem) is a unix-like shell and is well integrated with MinGW. We'll learn how to install and configure MinGW and MSYS later in this article. For now, it is enough to know there are such things.
PKG-CONFIG
Pkg-config.exe acquires locations of headers and import libraries and lists of required libraries from .pc(acronym for pkg(package) config) files. Pkg-config.exe then interprets them into compiler options and outputs those compiler options. Gimptool-2.0.exe, in turn, gives compiler options gained from pkg-config.exe to GCC. Pkgconfig files contain information about where header files are, where import libraries are, and what import libraries are required.
- The packages which are required to compile a windows gimp plugin.
We need gimp-dev and gtk+-bundle to compile a windows gimp plugin proper. You can also download pure gtk+ and associated packages, but it requires a lot more work to download, extract, and manage all those archives separately. The reason we need gimp-dev and gtk+-bundle is a gimp plugin uses gimp library and gtk+ library. Another reason is gimp-dev contains gimptool-2.0.exe, and gtk+-bundle contains pkg-config.exe.
You must choose the version of gtk+-bundle that (1)"is the same as or older than"(because of backward compatibility) and (2)"matches most closely to" the gtk+ version of your gimp. If a library is backward compatible, a plugin compiled using an older library would work with newer versions of DLLs of that library although there are exceptions of backward compatibility. ".def" files are related to backward compatibility of programs.
Programs, which call a function in a dll, find the function from the dll by referring to the exact position in the DLL of the function defined in .def files. Not only .def files but import libraries contain infomation about positions of functions. If you want to know more about .def files, you need to learn how to make DLLs or import libraries.
- How to download and install gtk+-bundle, gimp-dev, MinGW, and MSYS
We'll first download gtk+-bundle and gimp-dev from the internet, and in my case I saved those archive files in F:\DevTools. You need to find or make a directory to save and extract those archives, too.
GTK+-BUNDLE
Gtk+-bundle is available on http://www.gtk.org/. In the website, you click download and then click Windows. Gtk+ 2.16 all-in-one bundle matches most closely to the gtk+ version of gimp-2.6.8.
GIMP-DEV
Unfortunately, gimp-dev is only available for the version 2.6.1, but it can work with gimp 2.6.x versions. I tested it with gimp-2.6.8. Go to http://sourceforge.net/ and search "gimp windows". You will see "GTK+ and GIMP installers for Windows". Click it ,and then click "Files" in the menu. Wait until the webpage is loaded completely.
You can see that gimp 2.6.8 is associated with gtk+ 2.16.6. Click GIMP "2.6.1" + GTK+ 2.14.3 and download "gimp-dev-2.6.1.zip". I downloaded both gtk+-bundle-2.16 and gimp-dev-2.6.1 in F:\DevTools folder as I said above. Believe me, no other versions of gimp for windows have gimp-dev currently.
However, a plugin built from gimp-dev-2.6.1 would work in later versions. It's an example of backward compatibility. However, if you compiled a plugin using gimp-dev-2.6.1 and the plugin doesn't work with newer gimp 2.x versions, then there were old behaviors that needed to be fixed, and changes done to fix those are not backward compatible. But if bug fixes were done in those cases, you have to change your plugin code as well.
Plus, a library can't be forward compatible. If, for example, you compiled a gimp plugin using gtk+-bundle-2.20 and your plugin uses g_new function, and if you run the plugin on gimp-2.6.8 which is associated with gtk+ 2.16.6, then your plugin will make an error that it can't find g_malloc_n from glib DLL. I experienced this case. Extract gtk+-bundle and gimp-dev where you downloaded them.
MinGW AND MSYS
It's time to install MinGW first and then MSYS. It's important to install MinGW first. Go to http://www.MinGW.org/. Find "downloads" in the menu and click it. Wait until the webpage loading completes. Please download MinGW and MSYS base system on the MinGW download webpage.
For now, MSYS base system 1.0.11 is the most recent version that comes with an installer. More recent versions of MSYS only have source codes. I prefer not to download them in the folder where gtk+-bundle and gimp-dev files are because MinGW and MSYS don't seem to belong to DevTools.
Install MinGW. I recommend installing it in the default folder, c:\MinGW. Now install MSYS. I recommend installing MSYS in the default folder, c:\MSYS\1.0\. After you install MSYS, there will appear a post-installation script that asks you whether you installed MinGW and where you installed MinGW. You're ready to use MinGW and MSYS. But let's not do anything with those tools for a while. We need to learn the underlying notions from now on.
- Environment variables that we need to change
An environment variable is a variable that usually tells "where to find something", "how programs should act", etc.
PATH
PATH env(environment) variable tells your shell where to find needed files. By setting PATH properly, we can avoid typing the full path to gimptool-2.0.exe and let gimptool-2.0 find pkg-config.exe. If PATH is not set properly, gimptool-2.0 can't find pkg-config.exe. You need to add , to PATH, the directories that contain pkg-config.exe and gimptool-2.0.exe.
PKG_CONFIG_PATH
Since PKG_CONFIG_PATH env variable specifies directories in which pkg-config.exe searches for .pc(pkg(package) config) files, PKG_CONFIG_PATH must specify a directory that contains pkgconfig files of gtk+-bundle-dev and another that contains pkgconfig files of gimp-dev.
CC
Gimptool-2.0 recognizes the value of CC env variable as the compiler that it should use. If you don't set CC to 'gcc' and if you type "gimptool-2.0 --build xxx.c" or "gimptool-2.0 --install xxx.c", then gimptool-2.0 from gimp-dev-2.6.1 will recognize i686-pc-mingw32-gcc as the compiler name.
i686-pc-mingw32-gcc is the name of the cross compiler that works on linux and compiles .c files into .exe files. Linux has some cross compilers that compile source codes into .exe files. The person who compiled gimptool-2.0.exe used i686-pc-mingw32-gcc as the cross compiler, and the value of CC at that time was 'i686-pc-mingw32-gcc'. The value of CC was built into gimptool-2.0.exe when she compiled gimptool-2.0.exe.
If you don't override CC built in gimptool-2.0.exe by setting CC on your shell, then gimptool-2.0 will try to compile with 'i686-pc-mingw32-gcc' which you don't have.
"How we should change env variables"
To change env variables on windows means to change system env variables in the control panel. Since changes to system env variables cannot be undone, if you delete the content in a system env variable and press enter accidentally, you will be very frustrated. In addition to that, It requires fair amount of mouse clicks to reach there and I didn't want to change system variables just for the purpose of compiling plugins.
But I happened to reach a decent solution. It is to install MinGW and MSYS and set env variables properly on MSYS. You can compile a gimp plugin on cmd.exe or powershell with MinGW, but MSYS and MinGW are way better. Thus, you don't have to make changes to system variables in the windows control panel. Before you learn how to set env variables on MSYS, you need to know MSYS virtual file system first.
- MSYS virtual file system
The root directory("/") of MSYS shell is usually c:\MSYS\1.0\ if you didn't change the installation setting. How will you go to directories outside c:\MSYS\1.0 and other hard drives and other partitions? If you type /f/, then you will be directed to f:\ drive or partition. It recognizes a hard drive or a partition as a folder in the root directory, "/". So /f/sourcecodes/gimp_plugins is the same as f:\sourcecodes\gimp_plugins. Be aware that MSYS and unix shells use "/" instead of "\" as in windows.
Unix systems recognize ~/ as home directory, and home directory is usually /home/youraccountname. If you type "cd ~/", you will be directed to /home/youraccountname. During installation of MSYS, MSYS retrieves information from windows and uses it as your account name on MSYS.
Because gimptool-2.0 installs plugins in homefolder\.gimp-gimpversion\plug-ins\, if you type "gimptool-2.0 --install xxx.c" on MSYS, xxx.exe will be installed in c:\MSYS\1.0\home\youraccountname\.gimp-gimpversion\plug-ins while executing that on powershell or cmd.exe would result in a plugin in the right folder. And you don't want that to happen.
The only circumvention I know is setting the MSYS home directory to where gimp actually seeks, and $HOME env variable specifies the MSYS home directory. If you want this, you can set $HOME to "c:\users\accountname" in case of windows vista. But that could lead to problems if other MSYS applications also use the home directory. So when you compile a plugin on MSYS, it's better to type "gimptool-2.0 --build xxx.c" and copy it manually to the right gimp plugin folders.
- How to set and view env variables on cmd.exe and MSYS
ON CMD.EXE
You use "set" command on cmd.exe to set an env variable and see the list of all env variables. For example, you set 'CC' by typing "set CC=GCC" or " set CC='GCC' ". If you want to add multiple directories to PATH, you can separate each directory by the symbol ";". For example, you can set PATH by typing "set PATH=c:\MinGW;'c:\program files\gimp-2.6.8\bin' ".
If the full path to a directory has a space as in c:\program files\gimp-2.6.8\bin, there will be problems because a space can be interpreted in many ways. Hence, you should embrace the full path to a directory that contains a space with '' or " " symbol. C:\program files\gimp-2.6.8\bin contains a space because "program files" has a space between "program" and "files".
If you already tried setting PATH, you would be surprised that the previous content of PATH has gone. If you type "path" on cmd.exe, cmd.exe shows the content of PATH. But it's ok since the change by "set" command is only temporary and undone when you exit cmd.exe.
Instead of overriding, you can add any content to a variable by 'set variable=content;%variable%'. When you specify an env variable on cmd.exe in general, "%" is added to both sides of the name of the variable. Thus, you have to type 'set PATH=c:\MinGW;%PATH%' if you want to add c:\MinGW to PATH.
ON MSYS
If you want to set an env variable on MSYS or unix shells, the command "export" does the job. You specify an env variable by $variable, but not %variable% as on cmd.exe. Plus, you should use ":" instead of ";" to separate each directory in $PATH. Therefore, you can add c:\MinGW to $path by typing 'export PATH=/c/MinGW:$PATH'.
However, changes made by the export command are undone when you exit MSYS. This is the point where a startup script comes handy. By the way, "come handy" is more common in australia, and "comes in handy" is more common in UK and USA, and I wonder whether the adjective "handy" can be used as in "comes in handy".
You can view all env variables by typing "env" on MSYS. If you type "env | grep XXX", you'll see variables that contain the string "XXX". By typing "|", you are using a pipeline. If you want to know about pipeline, you need to search unix or linux "shell" manuals.
- How to set MSYS environment with a startup script
Unix shells and MSYS run a startup script each time they are executed. Hence, if you put export commands in a startup script, you won't have to type export commands each time you run MSYS. MSYS uses bash as its shell, and different implementations of bash use different names for their startup script.
I googled the name of MSYS startup script. In case of MSYS 1.0.11, it uses ~/.profile as the startup script. It's in the home directory as you can see. Since it's difficult to make a file whose name contains nothing before comma on windows, let's make ~/.profile on MSYS. Go to the home directory by typing 'cd ~/'. Make '.profile' by typing 'touch .profile'. You can edit ~/.profile with vim if you like, but FYI, vim is somewhat complex for many of windows users. Below is the content of my ~/.profile. Your ~/.profile should look like this, too.
export PKG_CONFIG_PATH=/f/DevTools/gimp-dev-2.6.1/lib/pkgconfig:/f/DevTools/gtk+_win32_2.16.6/lib/pkgconfig
export CC='GCC'
export PATH=/f/DevTools/gtk+_win32_2.16.6/bin:/f/DevTools/bin/:$PATH
Let me explain my ~/.profile file. PKG_CONFIG_PATH has two folders. One contains pkgconfig files of gimp-dev-2.6.1 and the other contains those of gtk+-bundle-2.16.6. You would understand export CC='GCC'. PATH includes two folders. The bin folder of gimp-dev-2.6.1 contains gimptool-2.0.exe, and the bin folder of gtk+-bundle-2.16.6 contains pkg-config.exe and DLL files of gtk+ and of associated libraries.
Glib DLL is also included in the bin folder of gkt+-bundle, and gimptool-2.0.exe requires glib DLL. After you write and save those lines in ~/.profile, MSYS will always have those env variables after you restart MSYS unless you make changes later. That ~/.profile was enough on my computer to compile gimp C plugins on MSYS.
- How to compile a plugin on MSYS
On MSYS, go to the folder that contains your plugin source codes. Let's assume you want to compile xxx.c into xxx.exe. Then you need to type 'gimptool-2.0 --build xxx.c'. If there is no error, this command will build xxx.exe. You also need to test it on gimp because sometimes a well compiled plugin caused errors in gimp on my computer.
- I've compiled a plugin. Where are gimp plugin folders?
With windows vista and gimp-2.6.8, there are two plugin folders. One is "C:\Program Files\GIMP-2.0\lib\gimp\2.0\plug-ins", and the other is "c:\users\youraccountname\.gimp-2.6\plug-ins". You can copy your built plugins to one of those folders. However, Plugins in "C:\Program Files\GIMP-2.0\lib\gimp\2.0\plug-ins" could be removed when you remove gimp and install a newer version of it. Therefore, I recommend copying plugins into "c:\users\youraccountname\.gimp-2.6\plug-ins".
_______________________________________________ Gimp-developer mailing list Gimp-developer@xxxxxxxxxxxxxxxxxxxxxx https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer
