Using GSettings

This page describes how to manage your application settings with GSettings. For information on how to use GSettings when developing an application, look at the GSettings documentation. For information on migrating to GSettings from GConf, see the migration guide.

Concepts

GSettings are a nice way to manage your application’s settings. Those settings are stored in binary form for fast retrieval, and can be manipulated outside of your application as well using specific tools.

This system can be seen as a database, whose schema is described in an XML file (conventionally named .gschema.xml) which is then compiled to improve runtime performance.

GSettings is actually an interface with multiple possible storage backends. The typical and recommended one is dconf, but a key file backend can also be used.

Using GSettings in your project

If the build system of your project is based on autotools then it is very easy to integrate GSettings support into your application.

As an example, we're going to set up GSettings for a project with an application ID of "org.example.myapp". See HowDoI/ChooseApplicationID for information about choosing an application ID.

We start by writing a schema for the settings that our project needs to store. For now, let's start small.

Name the schema file according to the name of the schema found inside of it, and ending with ".gschema.xml". You can put multiple schemas inside of one file, but typically there will be a "top level" schema that you can use to name the file. Although the filename itself has no particular meaning, it is a very strong convention that you must choose a name that correctly indicates the contents and avoids conflicts with other installed applications.

Typically, you will place this file in the toplevel data/ directory in your project's source, but you can put it anywhere you like, according to the conventions used in your project.

There are several examples in the wild of projects that use .gschema.xml.in files. This is almost always wrong. You should absolutely never use intltool or itstool-based XML "translation merging" functionality with schema files. It is also typically unnecessary to use expansions such as @GETTEXT_PACKAGE@, as these things are not configurable by the user (and shouldn't be).

For our example, we will create a file named "org.example.myapp.gschema.xml":

   1 <?xml version="1.0" encoding="utf-8"?>
   2 
   3 <schemalist>
   4 
   5   <schema path="/org/example/myapp/" id="org.example.myapp">
   6 
   7     <key name='automatic-updates' type='b'>
   8       <default>true</default>
   9       <summary>Automatically install updates</summary>
  10       <description>
  11         If enabled, updates will automatically be downlaoded and installed.
  12         If disabled, updates will still be downloaded, but the user will be
  13         asked to install them manually.
  14       </description>
  15     </key>
  16 
  17   </schema>
  18 
  19 </schemalist>

Once the file is created, you need to enable GSettings support in your project and tell the rules about your schema files.

Meson

Edit the appropriate meson.build file, and tell it to install the schema file in the schemas directory:

schemas_dir = get_option('prefix') / get_option('datadir') / 'glib-2.0' / 'schemas'
settings_schemas = [ 'org.example.myapp.gschema.xml' ]

install_data(settings_schemas, install_dir: schemas_dir)

# Compile the schemas in the current directory; this is only
# useful for testing
gnome = import('gnome')
gnome.compile_schemas(depend_files: files(settings_schemas))

In order to compile the settings schemas when installing, you will need a post-install script:

meson.add_install_script('glib-compile-schemas', schemas_dir)

Autotools

Edit the Makefile.am in the same directory as the schema file that you just created and add the following lines:

gsettings_SCHEMAS = org.example.myapp.gschema.xml

@GSETTINGS_RULES@

You will also need to update your automake setup in order to make the GSettings makefile rules available. Add this line to your configure.ac file:

GLIB_GSETTINGS

You may now need to re-run autoregen on your project in order to make sure everything is properly updated.

Tools

These tools are typically helpful for debugging.

glib-compile-schemas

This is used to compile GSettings schema XML files to a cached binary form. It should typically be used via the GLIB_GSETTINGS macro in an automake build system; not directly.

dconf-editor

Running this command will open a graphical interface which will allow you to browse and modify settings trees.

gsettings

This is a command line tool for viewing and modifying GSettings, and works regardless of the GSettings backend in use. For modifying the dconf backend storage itself, use the dconf tool; but gsettings should be used by preference.

See the --help output from the two tools for information on how to use them.