Building GTK-OSX
Building the core libraries and preconfigured applications in GTK-OSX is pretty simple: Download the installation script, run a few commands in Terminal.app (or your favorite substitute), and watch.
Building other libraries or applications can be only a little harder. See Building Other Programs below.
How It Works
GTK+ is a unix graphical framework originally designed to run on Unix systems with X-Windows... but the GTK developers have included an interface to OSX's Quartz graphics engine, so it can be built to run on OSX without enabling the X11 subsystem.
But there is a lot to GTK+, including a lot of dependencies, that are included as part of most Linux distributions and either aren't included or aren't sufficiently up to date on OSX. End applications may have even more dependencies falling into one of those categories. GTK-OSX provides an easy way to download, build, and install all of those various dependencies.
The actual work is done by a Python program called jhbuild which takes its instructions from a collection of XML files called modulesets.
GTK-OSX's installation script installs jhbuild along with a configuration file and a set of modulesets which have been tailored and tested for OSX.
Prerequisites
GTK-OSX requires
- MacOSX 10.4 (Tiger), 10.5 (Leopard), or 10.6 (Snow Leopard). It builds successfully on both PowerPC and Intel Macs.
- Developer Tools (XCode) 2.3 or newer; 2.5 or 3.x is recommended. (Snow Leopard comes with 3.2, Leopard with 3.0, and Tiger with 2.0. Tiger users will need to get a free Apple Developer Connection ID to download an updated version. While Developer Tools is included on the installation DVD, it is not installed along with OSX, but must be installed separately after OSX is configured.)
- Subversion. Leopard and Snow Leopard includes it; Tiger users can download a pre-built dmg at http://www.open.collab.net/downloads/community/
- git. You can get this from http://metastatic.org/source/git-osx.html
If you have MacPorts or Fink installed, be sure to remove their paths from $PATH, $DYLD_LIBRARY_PATH, $PKG_CONFIG_PATH and any build-related environment variables ($CFLAGS, $LDFLAGS, etc.) before you try to run jhbuild. Mixing Fink/MacPorts and GTK-OSX will fail.
Procedure
Download gtk-osx-setup.sh to your home directory and run it:
$ sh gtk-osx-build-setup.sh
It will install jhbuild in ~/Source and create ~/.local/bin/jhbuild. It will also install ~/.jhbuildrc and ~/.jhbuildrc-custom and will copy the current gtk-osx modules into ~/Source/jhbuild/modulesets.
Note: jhbuild requires Python 2.5 to unpack tar files, but Tiger provides Python 2.3. We provide Python 2.5 in meta-gtk-osx-bootstrap, but that doesn't help for running jhbuild because the non-jhbuild shell doesn't ordinarily see your gtk installation. You can define an alias to get around this problem:
$ alias jhbuild="PATH=gtk-prefix/bin:$PATH jhbuild"
Obviously you should substitute the actual path of your gtk installation for gtk-prefix. If you add it to your .bashrc or .bash_profile you won't need to worry about it.
Now do
$ jhbuild bootstrap $ jhbuild build meta-gtk-osx-bootstrap $ jhbuild build meta-gtk-osx-core
And you have a reasonably complete GTK+ installation ready for you to build the application that interests you.
$ jhbuild build gimp
For example will build The GIMP and all of its dependencies. You may want to set
build_policy = "updated-deps"
in your .jhbuildrc-custom to avoid rebuilding packages which haven't changed since the last build.
More details on using jhbuild can be found at http://library.gnome.org/devel/jhbuild/unstable/
Important Rule
When you're working on your GTK+ application or any libraries, it's important to have the environment properly configured. jhbuild build does this when it's building things, of course, but if you're tweaking and building manually the easiest thing to do is start a jhbuild shell:
$ jhbuild shell $ export PATH=$PREFIX/bin:$PATH
If you work from inside an IDE or programmer's editor, you'll need to configure its shell environment to match what jhbuild shell does.
When running jhbuild shell, note that it sets $PATH before running your .bashrc, so depending on how you set $PATH, you may want to
$ export PATH=$PREFIX/bin:$PATH
after starting the jhbuild shell and before you try to do anything. We don't recommend making this your ordinary $PATH because some of the programs installed in the gtk directory work differently from the ones which Apple provides, which could cause trouble elsewhere. ($PREFIX won't work right outside of the jhbuild shell anyway.)
Modulesets
GTK-OSX supplies 3 modulesets: modulesets-stable, modulesets, and modulesets-unstable. The default is modulesets-stable. You can switch to one of the others by putting the line
moduleset="http://github.com/jralls/gtk-osx-build/raw/master/MODULESETS/gtk-osx.modules"
to your ~/.jhbuildrc-custom, substituting one of the modulesets listed above for MODULESETS.
Modulesets-stable pulls in mostly tar archives (mostly because there are a couple of modules for which tar archives aren't available). Modulesets pulls mostly from development version control repositories (git, subversion, or cvs, mostly git) with revision or tag attributes designating a stable release, with a few tarballs where version control access isn't available, the project is dormant (no updates in over a year), or there is no suitable tag, revision id, or stable branch to ensure a stable release. Modulesets-unstable pulls from the same repositories as modulesets, but has the revision and tag attributes removed so that you get the latest development work for almost all modules.
Modulesets-unstable is really unstable. Any one of the modules can be broken by a developer checking in a change that causes the module to not compile. If it won't compile at all, it will in most cases be fixed within a few hours, but if it just won't compile on OSX, then it may take some work on your part to get it going again. We don't regard this as our problem, and won't provide support. Don't use modulesets-unstable unless you are comfortable with autotools, C programming, and bugzilla! In general, if you want to work on a module under version control, the best plan is to use modulesets and override the branch on that specific module in ~/.jhbuildrc-custom:
branches["foo"]=""
Snow Leopard
Snow Leopard will default to building 64-bit binaries. This will work only with modulesets-unstable, and has been tested so far only through meta-gtk-osx-core, but the result is likely to run only on other Snow Leopard machines. For maximum portability of your binaries, include
moduleset = "http://github.com/jralls/gtk-osx-build/raw/master/modulesets-stable/gtk-osx.modules" setup_sdk(target="10.4", sdk_version="10.4", architectures=["i386"])
in your .jhbuildrc-custom. Note that the revisions of pango, cairo, and gtk+ are held back for Tiger compatibility -- but won't run successfully if built for 64-bit. More details on 64-bit building is available at the Snow Leopard page.
Building Other Programs
The procedure for building other programs is the same as for included programs, once you have set up a moduleset. Before you dive in, though, look through (or grep) the gtk-osx modulesets in ~/Source/jhbuild/modulesets. If the program you need is already there, then you just have to tell jhbuild to build it: jhbuild build theprogram
If it's not there, the first step is to open ~/.jhbuildrc-custom and ~/mymodules.modules in your favorite editor. .jhbuildrc-custom needs only one line for now:
moduleset=os.environ['HOME'] + '/mymodules.modules'
mymodules.modules (which can be any name you like, but must use the "modules" extension) will start off like this:
<?xml version="1.0"?>
<!DOCTYPE moduleset SYSTEM "moduleset.dtd">
<?xml-stylesheet type="text/xsl" href="moduleset.xsl"?>
<moduleset>
<import href="http://github.com/jralls/gtk-osx-build/raw/master/modulesets-stable/gtk-osx.modules"/>
</moduleset>
You'll insert any new modules and repositories after the <import/> element.
Before writing a module yourself, be sure to look through the modules in ~/Source/jhbuild/modulesets and see if there's one that you can copy into mymodules.modules. Of course, if there's one in one of the gtk-osx modulesets, you don't even need to do that. Be sure to copy the repository as well as the module.
Writing modules is beyond the scope of this page, but it's pretty easy to do. Read through jhbuild's documentation and look at the provided modulesets for examples. The hard work is in figuring out the dependencies.
Python
Gtk+ includes a python binding called PyGtk. Getting it built is almost straightforward, but bundling apps can be tricky. Visit the PyGtk page for more information or to share tips.
A Note About Building Your Own Programs
It is common for people new to Unix programming to think that they can distribute their sources with just a Makefile (or even a bunch of Makefiles). This is unfortunately naive, because there are a number of different sorts of Unix and Unix-like operating systems, and the way that they provide services to programs varies greatly. This is true even among different versions of Linux.
To get around this problem, there have arisen a variety of different build systems which are able to explore the operating system hosting the build and make appropriate adjustments to the build files so that the program builds and runs correctly. The most commonly encountered is the GNU Autotools suite, which provides the familiar configure && make && sudo make install sequence. You'll find several choices supported by jhbuild in the documentation. Make sure that you use one for your program!
Framework
The gtk-osx-framework package builds framework bundles which can be installed when you are going to have more than one GTK+ app on a machine. Details may be found in the README file.
WARNING: The frameworks as built, including the intel binary at http://gtk-osx.org, are not suitable for end-user use at this time. This is an area of active development work, and we will have downloadable binaries of the frameworks in the downloads area here at Sourceforge as soon as we're satisfied that the result is generally usable. If you want to help out, please join the Frameworks discussion in the Building Forum.
I've pinched Richard's page from Gnome Live and put it in Frameworks, with some additional notes.
