GConf comes with a GSettings backend that can be used to facility the transition to the GSettings API until you are ready to make the jump to a different backend (most likely dconf). To use it, you need to set the GSETTINGS_BACKEND to 'gconf', e.g. by using

  g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE);

early on in your program. Note that this backend is meant purely as a transition tool, and should not be used in production.

GConf also comes with a utility called gsettings-data-convert, which is designed to help with the task of migrating user settings from GConf into another GSettings backend. It can be run manually, but it is designed to be executed automatically, every time a user logs in. It keeps track of the data migrations that it has already done, and it is harmless to run it more than once.

To make use of this utility, you must install a keyfile in the directory /usr/share/GConf/gsettings which lists the GSettings keys and GConf paths to map to each other, for each schema that you want to migrate user data for.

Here is an example:

[org.gnome.fonts]
antialiasing = /desktop/gnome/font_rendering/antialiasing
dpi = /desktop/gnome/font_rendering/dpi
hinting = /desktop/gnome/font_rendering/hinting
rgba-order = /desktop/gnome/font_rendering/rgba_order

[apps.myapp:/path/to/myapps/]
some-odd-key1 = /apps/myapp/some_ODD-key1

        

The last key demonstrates that it may be necessary to modify the key name to comply with stricter GSettings key name rules. Of course, that means your application must use the new key names when looking up settings in GSettings.

The last group in the example also shows how to handle the case of 'relocatable' schemas, which don't have a fixed path. You can specify the path to use in the group name, separated by a colon.

There are some limitations: gsettings-data-convert does not do any transformation of the values. And it does not handle complex GConf types other than lists of strings or integers.

Don't forget to require GConf 2.31.1 or newer in your configure script if you are making use of the GConf backend or the conversion utility.

If, as an application developer, you are interested in manually ensuring that gsettings-data-convert has been invoked (for example, to deal with the case where the user is logged in during a distribution upgrade or for non-XDG desktop environments which do not run the command as an autostart) you may invoke it manually during your program initialisation. This is not recommended for all application authors -- it is your choice if this use case concerns you enough.

Internally, gsettings-data-convert uses a keyfile to track which settings have been migrated. The following code fragment will check that keyfile to see if your data conversion script has been run yet and, if not, will attempt to invoke the tool to run it. You should adapt it to your application as you see fit.

static void
ensure_migrated (const gchar *name)
{
  gboolean needed = TRUE;
  GKeyFile *kf;
  gchar **list;
  gsize i, n;

  kf = g_key_file_new ();

  g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
                                  NULL, G_KEY_FILE_NONE, NULL);
  list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);

  if (list)
    {
      for (i = 0; i < n; i++)
        if (strcmp (list[i], name) == 0)
          {
            needed = FALSE;
            break;
          }

      g_strfreev (list);
    }

  g_key_file_free (kf);

  if (needed)
    g_spawn_command_line_sync ("gsettings-data-convert",
                               NULL, NULL, NULL, NULL);
}


        

Although there is the possibility that the gsettings-data-convert script will end up running multiple times concurrently with this approach, it is believed that this is safe.