GNOME 3 Porting Guide

GNOME's developer technologies have been dramatically improved for version 3.0, making them faster, easier to use, and delivering enhanced user experiences. If you are responsible for an application which makes use of GNOME's developer technologies, it is recommended that you port to GNOME 3 in order to take advantage of these improvements.

The following guide is a checklist of the steps required to port a piece of GNOME 2 software to version 3.

Essential

The following procedures are essential parts of the porting process:

• Do not use deprecated libraries:

  • libglade: use GtkBuilder instead.

    • Migration guide

    • Some examples of already ported applications.

  • libgnome, libgnomeui: use GTK+ features directly instead.

    • List of replacements

  • libsexy: use GTK+ features directly instead.

    • Migration guide for SexyIconEntry and SexyUrlLabel

    • Some examples of applications that have already been ported.

  • gnome-vfs: use GIO instead.

    • migration guide

    • Some examples of already ported applications.

  • Bonobo: use GTK+ features and GDBus (see below).

• Make your GTK+2 application GTK+3 compliant:

  • Only use toplevel Glib / GTK+ headers:

    • Guide and some examples of already ported applications.

  • Do not use deprecated GLib / GTK+ symbols:

    • Guides to migrate to the new APIs

    • Glib and GTK+ examples of already ported applications.

  • Compile your app with -DGSEAL_ENABLE:

    • Some examples of already ported applications.

  • Use Cairo instead deprecated GDK api:

    • Some examples of already ported applications.

• Port your GTK+2 application to GTK+3: migration guide

• Fix your .desktop file: more info

• Use -symbolic icons in the cases specified in the symbolic icon usage guidelines. More information:

  • Symbolic icon migration guide

  • An example patch

• Include a high-resolution application icon. Sizes covered should include 16x16, 22x22 (24x24), 32x32, 48x48 and 256x256. See the installation instructions and style guide.

• If your application reads proxy configuration from GConf (such as the keys under /system/proxy), you will need to update your code to look at the new DConf proxy keys. See DevGnomeOrg/Gnome3PortingGuide/ProxyConfiguration.

Additional steps

While the are not essential, the following steps are advised. They will prevent you from having to do further porting work in the future, and will enable you to take advantage of the full range of the improvements in GNOME 3.

• Port your application to GtkApplication, particularly if you are using libunique.

• Use GSettings instead Gconf.

  • Migration guide

  • Some examples of already ported applications.

• Use GDBus instead dbus-glib.

  • Migration guide

• Port your documentation to the new Mallard format.

• Add GObject Introspection support to your library.

  • Guidelines

  • Some examples of already ported applications.

• Use the correct icon names: more info.

• If you use Python, move to the new introspection-based PyGObject bindings.

  • Some examples of already ported applications.

• Use the XDG Base Directory Specification.

  • Some examples of already ported applications.

• Turn your references capplets into system settings panels.

  • Examples: gnome-media and vino examples.

  • See the system settings design page for more information.

• If your module installs a panel applet, consult with the GNOME designers on how to make its functionality available in GNOME 3. See the gizmos page.

All the content of this page is under Creative Commons Attribution 3.0 License