GSettings is a GLib API for storing persistent application settings (but not large amounts of data or user documents). It is the successor to GConf, and is similar in use to the Windows Registry. GSettings is used by Apertis for application preferences and configuration data. Its main advantages over databases or configuration files are its support for structured data (using GVariant), and its fast reads. It has good integration with GObject, with powerful features such as binding to object properties with
Due to its tight integration with other GLib utilities, it should be used in preference to (e.g.) SQLite for configuration data (but not for user data or documents, or high volumes of data).
- Compile and install all schemas using the
GLIB_GSETTINGSautoconf macro. (#Schema installation)
- Ensure schemas are named consistently. (#Schema design)
- Ensure schemas are fully translatable. (#Schema design)
- Use relocatable schemas where appropriate for instantiating the same schema at multiple paths. (#Relocatable schemas)
- Do not use schema overrides in upstream code. (#Schema overrides)
GSettings uses compiled schemas, which describe the available settings and their types. A single schema should contain a group of related settings, such as the settings for a single application. Every setting used by an application must be in a schema, and that schema must be compiled and installed. This can be done using the
@GSETTINGS_RULES@ automake macro provided by GLib.
Schemas should be named appropriately, using an Apertis namespace and a project-specific namespace, then the schema name, e.g.
All schemas should be translatable, which allows for configuration key default values to differ for different locales. This can be useful for settings which are known to be different in different countries. For example, a setting specifying which is the first day of the week. Schemas are automatically marked as translatable if intltool 0.50.1 is in use, and the schema is listed in
All schemas should be installed on the system. This is automatically handled by the
@GSETTINGS_RULES@ automake macro, simply by listing the schema file in
gsettings_SCHEMAS = org.foo.MyApp.gschema.xml EXTRA_DIST = $(gsettings_SCHEMAS) @GSETTINGS_RULES@
Note that the
GLIB_GSETTINGS macro must have been used in
configure.ac for this to work.
By installing schemas, there is no need to check for schema or key availability at run time, as all keys have default values provided by the schema. Calls to
g_settings_list_keys() are almost always unnecessary except when using #Relocatable schemas. Instead, schema keys should be retrieved on the assumption that they exist, simply by calling (e.g.)
g_settings_get_string() without any checks.
GSettings has a feature called ‘relocatable schemas’ which is designed specifically for situations where an unknown set of applications need to use a common schema template — where one schema is used multiple times at different GSettings paths. Each path has an instance of the schema and all its keys, and represents the configuration for a single app.
In such specific situations, a single relocatable schema should be used rather than copying the schema for each application.
g_settings_list_relocatable_schemas() should be used with
g_settings_new_with_path() to instantiate the schema for each path.
See the GSettings documentation for more information.
GSettings override files are designed for vendors to be able to override upstream-provided GSettings schema defaults, allowing for customisation of their distributions of software. If used, they should be added by the vendors using custom patches, and should not be added upstream in Apertis.
The GSettings database for the current environment can be explored and modified using the
gsettings command line tool. See
gsettings --help for more information. Note that the tool needs to be run in the same environment as the application in order to see the same GSettings database.