Hello all!
TL;DR; if you don't care at all about how crossroad works, and you just want to cross-build GIMP in a few commands, see at the bottom of the article.
Over the years, I have written a tool to cross-compile software under a GNU/Linux OS for other targets: crossroad. Well to this day, the only supported targets are Windows 32/64-bit. I realized I never advertised this tool much which — even though it has been originally built to help me build and hack a specific project (GIMP) — ended up as a generic cross-compilation system for Linux.
So today, I will explain crossroad by giving a concrete example:
Cross-compiling GIMP on GNU/Linux for Windows system
The basics
The cool stuff about crossroad is that it allows to cross-build as easily as a native build. For instance f your build system were the autotools, you would run the famous triptych ./configure && make && make install, right? Well with crossroad, you only wrap the configure step but the rest is the same!
cmake is also fully supported, even though my examples below won’t show it (check out the manual for more).
All what crossroad does is preparing you a suitable environment, with the right environment variables, but also wrappers to various tools (for instance, you get the x86_64-w64-mingw32-pkg-config tool inside a crossroad environment, which is no more than a wrapper to detect packages inside the cross-built prefix only).
Enough chit-chat. Let’s install crossroad!
pip3 install crossroad
Running crossroad the first time
I will now go through a full cross-build of GIMP for Windows 64-bit, from a brand new crossroad install. It may be a little long and boring, but I want to show you a full process. So you can just run:
$ crossroad --list-targets
crossroad, version 0.6
Available targets:
Uninstalled targets:
w32 Windows 32-bit
w64 Windows 64-bit
See details about any target with `crossroad --help <TARGET>`.
Ok so at this point, you may have no cross-compilation compiler installed. Let’s see what I need for Windows 64-bit.
$ crossroad --help w64
w64: Setups a cross-compilation environment for Microsoft Windows operating systems (64-bit).
Not available. Some requirements are missing:
- x86_64-w64-mingw32-gcc [package "gcc-mingw-w64-x86-64"] (missing)
- x86_64-w64-mingw32-ld [package "binutils-mingw-w64-x86-64"] (missing)
The package name was actually based off a Mint or a Mageia, I think. If you use Fedora for instance, you will want to install mingw64-gcc and mingw64-binutils. Just adapt to your case.
Let’s check the output of crossroad again:
$ crossroad --help w64
w64: Setups a cross-compilation environment for Microsoft Windows operating systems (64-bit).
Installed language list:
- C
Uninstalled language list:
- Ada Common package name providing the feature: gnat-mingw-w64-x86-64
- C++ Common package name providing the feature: g++-mingw-w64-x86-64
- OCaml Common package name providing the feature: mingw-ocaml
- Objective C Common package name providing the feature: gobjc++-mingw-w64-x86-64
- fortran Common package name providing the feature: gfortran-mingw-w64-x86-64
We could stop here, but I actually know some programs make use of the C++ compiler, so let’s also install `mingw64-gcc-c++`. And now we are good to go!
I create a Windows 64-bit cross-build environment, that I will call “gimp-build”:
$ crossroad w64 gimp-build
Creating project "gimp-build" for target w64...
You are now at the crossroads...
Your environment has been set to cross-compile the project 'gimp-build' on Windows 64-bit (w64).
Use `crossroad help` to list available commands and `man crossroad` to get a full documentation of crossroad capabilities.
To exit this cross-compilation environment, simply `exit` the current shell session.
Dependencies
babl
Now let’s cross-build babl! Very easy one to start with because it does not have any dependencies:
$ cd /path/to/src/of/babl/
$ crossroad configure && make && make install
Done! You’ll notice that you don’t even need to specify a prefix. crossroad is taking care of it.
GExiv2
$ cd /path/to/src/of/gexiv2
$ crossroad configure
The configure ends up with a pretty clear error:
checking for GLIB... no
configure: error: GLib is required. Please install it.
Well basically you have to install glib. And then you think: the hell is starting! Do I have to build every dependency by hand? Fortunately no! crossroad relies on the OpenSUSE cross platform builds and can automatically download many dependencies for you. The reason I don’t do it for for all dependencies (babl, GEGL, libmypaint and GExiv2 in this tutorial) is when packages are either too old or non available. Install glib with:
$ crossroad install glib2-devel
That’s all! Neat right? Well you also have to install Exiv2 (trying to run the configure again, you’d see another error. I spare you the wasted time). You can run a separate command, or could have installed them both at the same time:
$ crossroad install glib2-devel libexiv2-devel
Try again:
$ crossroad configure
In the configuration summary, you’ll see that introspection and python bindings won’t be built-in. But since they are not needed for GIMP, we don’t care.
$ make && make install
And now GExiv2 has been cross-built too!
gegl
Now for gegl:
$ cd /path/to/src/of/gegl
$ crossroad configure
Once again, you’ll get a few dependency errors. I spare you the try and fail process. Here are all the other mandatory libs to install:
$ crossroad install libjson-glib json-glib-devel libjpeg8-devel libpng-devel
And for a fuller list of optional dependencies:
$ crossroad install cairo-devel libtiff-devel librsvg-2-2 librsvg-devel pango-devel libwebp5 libwebp-devel libjasper-devel gdk-pixbuf-devel
Well there are actually more dependencies you could install or build yourself, but I don’t think they are really needed for GIMP. I’ll just leave it there. Now I build:
$ make
But then… a build error (I’ll admit: I left a dependency error on purpose!)!
In file included from /usr/include/SDL/SDL_main.h:26:0,
from /usr/include/SDL/SDL.h:30,
from /home/jehan/dev/src/gegl/operations/external/sdl-display.c:35:
/usr/include/SDL/SDL_stdinc.h:74:20: fatal error: iconv.h: No such file or directory
compilation terminated.
Makefile:1277: recipe for target 'sdl_display_la-sdl-display.lo' failed
make[4]: *** [sdl_display_la-sdl-display.lo] Error 1
make[4]: Leaving directory '/home/jehan/dev/crossbuild/w64/gegl/operations/external'[…]
Well that’s a good example to debug. Look well at the paths… /usr/include/[…], they are definitely for the native platform! So something is wrong.
Also I don’t even remember having installed SDL through crossroad anyway. Well if you were to check out the config.log, you would understand why the configure script found it:
configure:22069: checking for sdl-config
configure:22087: found /usr/bin/sdl-config
configure:22100: result: /usr/bin/sdl-config
Sometimes, some projects would use their own *-config script instead of relying on pkg-config (SDL seems to also have a pkg-config file, not sure why we’d prefer usind sdl-config, but well…). And while pkg-config allows to really separate the build and target environments, I can’t remove the current $PATH because a lot of native tools are needed in a cross-compilation. All this to say: you may encounter issues with software distributing custom *-config script. Be warned!
Anyway let’s install SDL, don’t forget to re-run configure (otherwise the native lib will still be used), then build again.
$ crossroad install libSDL-devel && crossroad configure && make && make install
Easy said, easy done.
libmypaint
Only a single dependency (json-c), then classical configure, make, make install:
$ crossroad install libjson-c2 libjson-c-devel && crossroad configure && make && make install
GIMP
And now for the main course! Once again, I spare you some of the search of dependencies. Here for mandatory deps:
$ crossroad install atk-devel gtk2-devel libbz2-1 libbz2-devel liblzma-devel liblcms2-2 liblcms2-devel
I’ll skip completely Python dependencies. This is the only major part of GIMP I’m still having issues with in my cross-builds so I will run configure with --disable-python.
As for optional dependencies:
crossroad install libgs8 libgs-devel libmng1 libmng-devel libpoppler-glib8 libpoppler-glib-devel poppler-data xpm-nox-devel headers iso-codes-devel libwmf-devel
Note 1: libwmf-devel has the same issue as SDL, thus the configure script would see it installed if you have it on your main system because of the libwmf-config in your $PATH.
Note 2: you can use crossroad search to discover package names. Even better, sometimes you know a file name that configure is looking for (after a dependency error, check out the configure.ac file or the config.log file for this info). For instance, I can’t find a libghostcript but I see that GIMP‘s configure is looking for the file ghostscript/iapi.h to detect ghostscript:
$ crossroad search --search-files iapi.h
"iapi.h" not found in any package name.
The following packages have files matching the search "iapi.h":
- headers
- libgs-devel
Then using crossroad list-files libgs-devel, I can confirm that this is the right package (crossroad info libgs-devel also confirms this is the package for Ghostscript development files).
Back to building GIMP:
$ crossroad configure --disable-python
$ make && make install
Note that I don’t built some options in, like the Ascii Art, the help browser, or OpenEXR because I could not find prebuilt dependencies, but it should not be hard for you to build the dependencies yourself as we did for babl/GEGL/…
Running under Windows!
And now you can for instance make a zip to put on a Windows, like this:
$ crossroad --compress=gimp-build.zip w64 gimp-build
This will just compress the whole target build, where GIMP for Windows is under bin/gimp-2.9.exe. Now this is *not* an installer or whatever finale. The target directory is full of files useful for building, yet completely useless for the finale installation. crossroad is *not* meant for making installers… to this day at least (saying that I would not be against if anyone wanted to implement something of the sort. Why not?! Send me a patch!).
Since I usually run Windows in a Virtualbox VM, rather than zipping a whole archive, I would simply share a directory and symlink the target directory like this:
$ cd /path/to/dir/shared/with/windows/vm/
$ crossroad --symlink w64 gimp
Note: in your Windows environment, you must update the PATH environment variable to add your build’s bin/ directory otherwise Windows won’t find your various built DLLs. You’ll find information on how to do so everywhere in the web.
I use crossroad as a developer, to test and sometimes patch directly GIMP for Windows, without ever getting out of my Linux OS. Well I still test under a Windows VM, which runs in Linux. But I develop and compile in my GNU/Linux shell.
Hopefully this tool can be useful to other people willing to test their program under Windows while hacking on GNU/Linux.
About having a good build system
If you followed good programming practice, and use a full-featured build system such as autotools and cmake, chances are that you can cross-build your program with barely any fix to the code. This is for instance what happened when I ported GExiv2 to autotools after we started using it in GIMP. GExiv2 maintainer would say in the blog post:
This in turn allows gexiv2 to build on Windows, something we’d not targeted at all when we began development but is obviously a hard requirement for GIMP.
Just having a good build system turn their Linux-only library into a multi-platform one. Pretty cool, no? And now libmypaint got the same fate, I autotooled it making it just so easy to cross-compile!
But if you have hand-made makefiles (like GExiv2 did), a scons build (like libmypaint did), or other build systems which don’t have a proper support for cross-building, this won’t be as easy. Think twice when you set up your software. The tool you use for builds is definitely not something to take lightly!
The one-step crossbuild script
This was all for you to see how crossroad is working. If you are only interested into building GIMP specifically, I compiled my whole tutorial below into a single build script that you are welcome to copy paste and run with crossroad like this:
crossroad install glib2-devel libexiv2-devel libjson-glib json-glib-devel \ libjpeg8-devel libpng-devel cairo-devel libtiff-devel librsvg-2-2 \ librsvg-devel pango-devel libwebp5 libwebp-devel libjasper-devel \ gdk-pixbuf-devel libSDL-devel libjson-c2 libjson-c-devel atk-devel \ gtk2-devel libbz2-1 libbz2-devel liblzma-devel liblcms2-2 \ liblcms2-devel libgs8 libgs-devel libmng1 libmng-devel \ libpoppler-glib8 libpoppler-glib-devel poppler-data \ xpm-nox-devel headers iso-codes-devel libwmf-devel headers git clone git://git.gnome.org/babl cd babl && crossroad configure && make && make install && cd .. git clone git://git.gnome.org/gegl cd gegl && crossroad configure && make && make install && cd .. git clone git://git.gnome.org/gexiv2 cd gexiv2 && crossroad configure && make && make install && cd .. git clone https://github.com/mypaint/libmypaint.git cd libmypaint && crossroad configure && make && make install && cd .. git clone git://git.gnome.org/gimp cd gimp && crossroad configure --disable-python && make && make install
If you copy these into a file, say build-gimp.sh, you can run it at once with:
$ crossroad w64 gimp-build --run build-gimp.sh -n
I hope you enjoyed this tutorial on how to build GIMP with crossroad!
Note: if you like what I do, consider sponsoring our animation film (CC by-sa), made with GIMP: ZeMarmot! We fund it with Patreon (USD) and Tipeee (EUR).