This is a guide to building gedit on OS X. This guide assumes that you are
already familiar with building gtk+ software on OS X (natively) using jhbuild.
Please make sure to read https://live.gnome.org/GTK%2B/OSX/Building
before proceeding.


Building gedit for OS X
=============================================================================

Since version 3.14, gedit hosts a self-contained, in-tree guided build
process using jhbuild. The ./build script in this directory is the main
entry-point which handles:

1) Initializing the build environment (installing jhbuild in-tree)
2) Bootstrapping and building all the necessary dependencies
3) Simple wrapper around common jhbuild tasks (build, make, shell, etc.)

The basic build procedure in a pristine environment is:

    ./build all

This will first initialize the build environment (if necessary), install
jhbuild if needed, bootstrap jhbuild and then continue to build gedit and
all its dependencies. Each of these stages can also be invoked manually:

    ./build init
    ./build bootstrap
    ./build build

Note that at the moment of writing, ./build bootstrap is not entirely
equivalent to ./build jh bootstrap. The reason is that there is a problem
when building python as part of the bootstrap process. As a workaround,
python is actually built twice during bootstrap.

By default, ./build will build against the 10.7 (Lion) OS X SDK, which
has to be already installed and available at

$(xcode-select -p)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk

Although Xcode 5 does not distribute the 10.7 SDK by default, it can be
easily obtained from previous Xcode versions. To do so, find the last
version of Xcode to support a given SDK and download it from apple
developer downloads [1]. Open the package, and without installing,
extract the SDK directory and copy it to the right location. For 10.7,
the latest Xcode version to support it is 4.3.3, which can be downloaded
at [2] (links subject to change).

It is also possible to build gedit against a different SDK by exporting
the GEDIT_SDK environment variable (defaults to 10.7). For example:

    export GEDIT_SDK=10.9
    ./build all

Would build gedit against the 10.9 SDK and install in .build/10.9
(see Directory structure below).

Note that building gedit for OS X, although made easier by use of this
./build script, often still requires expertise and manual intervention
when things go wrong. If this is the case, please feel free to visit the
#gedit channel on GIMPnet IRC or send an e-mail to the gedit mailing list
(gedit-list@gnome.org).


Directory structure
=============================================================================
The general structure is as follows:

 /.build
   root jhbuild directory. This directory will contain all the sources,
   checkout directories and install locations during building.

     /$SDK : separated by SDK version
         /source : checkout directory for all the sources
         /inst   : install directory for $SDK

     /pkgs : download location for tarballs

 /.home
   an automatically created fake $HOME directory. This is used to create
   an artificial separation for jhbuild such that it will not pick up on
   possible existing .jhbuildrc files. This directory is also used to
   install jhbuild itself.

 /config
     /jhbuildrc-gedit : the gedit specific jhbuild environment configuration

 /modulesets
   the jhbuild modulesets used to build gedit. Note that these are
   self-contained and are updated each release.

     /patches           : directory with jhbuild patches
     /bootstrap.modules : the bootstrap modules
     /gedit.modules     : modules for gedit and all its dependencies

 /updater
     /gedit-bootstrap-overrides.modules
       jhbuild moduleset overrides for bootstrap

     /gedit-overrides.modules
       jhbuild moduleset overrides for gedit

     /update_modulesets.py
       an application which is used to update and merge jhbuild moduleset
       files. The use of this application is two-fold:

       1) It merges the override module files with the latest gtk-osx stable
          modulesets, allowing for clean separation. The overrides files
          contain only gedit specific changes on top of the gtk-osx stable
          modulesets to obtain a gedit build. Additionally, it creates a
          single moduleset file with only modules required for gedit in it and
          copies any required patches specified in the moduleset to a local
          directory.

       2) It automatically looks for new versions (stable and unstable) of
          GNOME libraries and queries whether or not to update modules that
          have newer versions than those already in the moduleset. This makes
          it easier to update to next-release versions of all required
          dependencies.

       The output of running this application is a /modulesets directory
       which is a self-contained modulesets/patches jhbuild configuration.
       It can be copied to the parent directory to replace the previous
       modulesets (which were generated in the same manner).

       Versions queried from GNOME ftp and downloaded patches are cached by
       default in /.cache. Make sure to remove this directory (or parts of
       it) to get up-to-date.


[1] https://developer.apple.com/downloads
[2] http://adcdownload.apple.com/Developer_Tools/xcode_4.3.3_for_lion/xcode_4.3.3_for_lion.dmg