all: Migrate to GKeyfileSettingsBackend and generate man pages from s…

…chemas Now we've removed the internal key file object, we've had to put in place another method for supporting the existing TRACKER_USE_CONFIG_FILES environment variable. Thanks to the GKeyfileSettingsBackend provided by GLib, we can fallback to old school INI type config files for embedded solutions or cases where we don't want dconf as a backend. This works rather well. IT should be noted, the INI files are *NOT* written out in full if they do not exist, only options which are saved or different to the default settings are. This is how it should be too. Now we build man pages based on GSettings schemas using xsltproc with the template in docs/manpages/gsettings.xsl. This is a useful aid when trying to understand what config files can have in them. One thing it does highlight, is the config documentation could be better :)
GNOME · Oct 27, 2014 · 2b53cd5 · 2b53cd5
1 parent dc4fbfe
commit 2b53cd5
Show file tree

Hide file tree

Showing 22 changed files with 527 additions and 96 deletions.
diff --git a/configure.ac b/configure.ac
@@ -1771,6 +1771,32 @@ fi
 
 AM_CONDITIONAL(HAVE_LIBXML2, test "x$have_libxml2" = "xyes")
 
+##################################################################
+# Check for xsltproc, used to generate cfg man pages (5)
+##################################################################
+
+AC_ARG_ENABLE([cfg-man-pages],
+              AS_HELP_STRING([--enable-cfg-man-pages],
+                             [enable man pages for config (.cfg) files [[default=yes]]]),
+              [enable_cfg_man_pages=$enableval],
+              [enable_cfg_man_pages=yes])
+
+if test "x$enable_cfg_man_pages" != "xno" ; then
+   # Check for graphviz if we are building gtk_doc
+   AC_PATH_PROG(XSLTPROC, xsltproc)
+   AC_SUBST(XSLTPROC)
+else
+   have_xsltproc="no  (disabled)"
+fi
+
+if test "x$enable_cfg_man_pages" = "xyes"; then
+   if test -z "$XSLTPROC"; then
+      AC_MSG_ERROR([Couldn't find xsltproc, try installing libxslt.])
+   fi
+fi
+
+AM_CONDITIONAL(HAVE_XSLTPROC, test -n "$XSLTPROC")
+
 ####################################################################
 # Check for tracker-extract: gstreamer/mplayer/etc
 ####################################################################
@@ -2719,6 +2745,7 @@ Build Configuration:
 	Win32:                                  $native_win32
 
 	Enable gtk doc (for documentation):     $enable_gtk_doc
+	Enable man pages for GSettings:         $enable_cfg_man_pages
 
 	Enable functional tests:                $enable_functional_tests
 	Enable unit tests:                      $have_unit_tests

diff --git a/docs/manpages/Makefile.am b/docs/manpages/Makefile.am
@@ -35,4 +35,5 @@ EXTRA_DIST = \
 	$(common) \
 	$(tp) \
 	$(tn) \
-	$(tmrss)
+	$(tmrss) \
+	gsettings.xsl
diff --git a/docs/manpages/gsettings.xsl b/docs/manpages/gsettings.xsl
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<xsl:output method="xml" omit-xml-declaration="yes" disable-output-escaping="yes"/>
+
+<xsl:template match="/">
+.TH <xsl:value-of select="$config-file"/> 5 "<xsl:value-of select="$current-date"/>" <xsl:value-of select="$version"/> "Tracker Manual"
+
+.SH NAME
+<xsl:value-of select="$config-file"/>
+
+.SH SYNOPSIS
+$HOME/.config/tracker/<xsl:value-of select="$config-file"/>
+
+.SH DESCRIPTION
+Tracker's configuration is built on top of GSettings, part of GLib. This means that there is a proper schema for configurations and they can be viewed (normally) using the \fBdconf-editor\fR tool.
+
+Tracker also allows switching from the GSettings database, used by most (cross) desktop applications, to a key/value formatted files (like Microsoft's INI format). To do this, the environment variable \fBTRACKER_USE_CONFIG_FILES\fR must be defined before running the application using that configuration.
+
+So where is this configuration? Well, normally they're stored in \fI$HOME/.config/tracker/\fR, however, default values are not stored to config files, only \fBdifferent\fR values are. This man page describes what keys and values can be used.
+
+See EXAMPLES for a general overview.
+
+.SH OPTIONS
+<xsl:for-each select="schemalist/schema/key">
+.TP
+\fB<xsl:value-of select="@name"/>\fR=<xsl:value-of select="translate(default, '(\[ | \])', '')" disable-output-escaping="yes"/>
+.nf
+
+<xsl:value-of select="description"  disable-output-escaping="yes"/>
+
+<xsl:for-each select="range">
+Values range from <xsl:value-of select="@min"/> to <xsl:value-of select="@max"/>.
+</xsl:for-each>
+.fi
+
+</xsl:for-each>
+
+.SH EXAMPLES
+The top level group is "General". The default configuration (if saved to <xsl:value-of select="$config-file"/>), would look like:
+
+.nf
+    [General]
+    <xsl:for-each select="schemalist/schema/key">
+      <xsl:value-of select="@name"/>=<xsl:value-of select="translate(default, '(\[ | \])', '')" disable-output-escaping="yes"/>;
+    </xsl:for-each>
+.fi
+
+.SH SEE ALSO
+.BR <xsl:value-of select="translate($config-file, '.', '\n')"/>
+
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/src/libtracker-data/.gitignore b/src/libtracker-data/.gitignore
@@ -6,3 +6,4 @@ tracker-sparql-scanner.c
 tracker-turtle-reader.c
 *.xml
 *.valid
+*.cfg.5
diff --git a/src/libtracker-data/Makefile.am b/src/libtracker-data/Makefile.am
@@ -16,6 +16,8 @@ AM_CPPFLAGS =                                          \
 	-DSHAREDIR=\""$(datadir)"\"                    \
 	$(LIBTRACKER_DATA_CFLAGS)
 
+all: $(libtracker_data_LTLIBRARIES) $(man_MANS)
+
 libtracker_datadir = $(libdir)/tracker-$(TRACKER_API_VERSION)
 libtracker_data_LTLIBRARIES = libtracker-data.la
 
@@ -86,14 +88,30 @@ gsettings_SCHEMAS = org.freedesktop.Tracker.DB.gschema.xml
 
 @GSETTINGS_RULES@
 
+if HAVE_XSLTPROC
+DATE=`date +'%B %Y'`
+man_MANS = tracker-db.cfg.5
+else
+man_MANS =
+endif
+
+%.cfg.5: $(gsettings_SCHEMAS)
+	$(AM_V_GEN)$(XSLTPROC) \
+	  --stringparam version "${VERSION}" \
+	  --stringparam current-date "${DATE}" \
+	  --stringparam config-file "$(@:.cfg.5=.cfg)" \
+	  $(top_srcdir)/docs/manpages/gsettings.xsl $^ > $@
+
 # Dist / Clean rules for all data
 BUILT_SOURCES = \
 	libtracker_data_la_vala.stamp
 
 CLEANFILES = \
 	libtracker_data_la_vala.stamp \
-	$(gsettings_SCHEMAS)
+	$(gsettings_SCHEMAS) \
+	$(man_MANS)
 
 EXTRA_DIST = \
 	libtracker-data.vapi \
-	$(gsettings_SCHEMAS:.xml=.xml.in)
+	$(gsettings_SCHEMAS:.xml=.xml.in) \
+	$(man_MANS)
diff --git a/src/libtracker-data/tracker-db-config.c b/src/libtracker-data/tracker-db-config.c
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2009, Nokia <ivan.frade@nokia.com>
+ * Copyright (C) 2014, Lanedo <martyn@lanedo.com>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -25,10 +26,15 @@
 #include <glib.h>
 #include <gio/gio.h>
 
+#define G_SETTINGS_ENABLE_BACKEND
+#include <gio/gsettingsbackend.h>
+
+#include <libtracker-common/tracker-common.h>
+
 #include "tracker-db-config.h"
 
-/* GKeyFile defines */
-#define GROUP_JOURNAL     "Journal"
+#define CONFIG_SCHEMA "org.freedesktop.Tracker.DB"
+#define CONFIG_PATH   "/org/freedesktop/tracker/db/"
 
 /* Default values */
 #define DEFAULT_JOURNAL_CHUNK_SIZE           50
@@ -139,22 +145,61 @@ config_finalize (GObject *object)
 	(G_OBJECT_CLASS (tracker_db_config_parent_class)->finalize) (object);
 }
 
-
 static void
 config_constructed (GObject *object)
 {
+	GSettings *settings;
+
 	(G_OBJECT_CLASS (tracker_db_config_parent_class)->constructed) (object);
 
-	g_settings_delay (G_SETTINGS (object));
+	settings = G_SETTINGS (object);
+
+	if (G_LIKELY (!g_getenv ("TRACKER_USE_CONFIG_FILES"))) {
+		g_settings_delay (settings);
+	}
+
+	g_settings_bind (settings, "journal-chunk-size", object, "journal-chunk-size", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
+	g_settings_bind (settings, "journal-rotate-destination", object, "journal-rotate-destination", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
 }
 
 TrackerDBConfig *
 tracker_db_config_new (void)
 {
-	return g_object_new (TRACKER_TYPE_DB_CONFIG,
-	                     "schema-id", "org.freedesktop.Tracker.DB",
-	                     "path", "/org/freedesktop/tracker/db/",
-	                     NULL);
+	TrackerDBConfig *config = NULL;
+
+	/* FIXME: should we unset GSETTINGS_BACKEND env var? */
+
+	if (G_UNLIKELY (g_getenv ("TRACKER_USE_CONFIG_FILES"))) {
+		GSettingsBackend *backend;
+		gchar *filename;
+		gboolean need_to_save;
+
+		filename = g_build_filename (g_get_user_config_dir (), "tracker", "tracker-db.cfg", NULL);
+
+		need_to_save = g_file_test (filename, G_FILE_TEST_EXISTS) == FALSE;
+
+		backend = g_keyfile_settings_backend_new (filename, CONFIG_PATH, "General");
+		g_info ("Using config file '%s'", filename);
+		g_free (filename);
+
+		config = g_object_new (TRACKER_TYPE_DB_CONFIG,
+		                       "backend", backend,
+		                       "schema-id", CONFIG_SCHEMA,
+		                       "path", CONFIG_PATH,
+		                       NULL);
+		g_object_unref (backend);
+
+		if (need_to_save) {
+			g_info ("  Config file does not exist, using default values...");
+		}
+	} else {
+		config = g_object_new (TRACKER_TYPE_DB_CONFIG,
+		                       "schema-id", CONFIG_SCHEMA,
+		                       "path", CONFIG_PATH,
+		                       NULL);
+	}
+
+	return config;
 }
 
 gboolean

diff --git a/src/libtracker-fts/.gitignore b/src/libtracker-fts/.gitignore
@@ -1,2 +1,3 @@
 *.xml
 *.valid
+*.cfg.5
diff --git a/src/libtracker-fts/Makefile.am b/src/libtracker-fts/Makefile.am
@@ -4,6 +4,8 @@ AM_CPPFLAGS =                                          \
 	-DNDEBUG                                       \
 	$(LIBTRACKER_FTS_CFLAGS)
 
+all: $(noinst_LTLIBRARIES) $(man_MANS)
+
 noinst_LTLIBRARIES = libtracker-fts.la
 
 fts4_sources =                                         \
@@ -65,6 +67,25 @@ gsettings_SCHEMAS = org.freedesktop.Tracker.FTS.gschema.xml
 
 @GSETTINGS_RULES@
 
+if HAVE_XSLTPROC
+DATE=`date +'%B %Y'`
+man_MANS = tracker-fts.cfg.5
+else
+man_MANS =
+endif
+
+%.cfg.5: $(gsettings_SCHEMAS)
+	$(AM_V_GEN)$(XSLTPROC) \
+	  --stringparam version "${VERSION}" \
+	  --stringparam current-date "${DATE}" \
+	  --stringparam config-file "$(@:.cfg.5=.cfg)" \
+	  $(top_srcdir)/docs/manpages/gsettings.xsl $^ > $@
+
 # Dist / Clean rules for all data
-CLEANFILES = $(gsettings_SCHEMAS)
-EXTRA_DIST += $(gsettings_SCHEMAS:.xml=.xml.in)
+CLEANFILES = \
+	$(gsettings_SCHEMAS) \
+	$(man_MANS)
+
+EXTRA_DIST += \
+	$(gsettings_SCHEMAS:.xml=.xml.in) \
+	$(man_MANS)
diff --git a/src/libtracker-fts/tracker-fts-config.c b/src/libtracker-fts/tracker-fts-config.c
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2009, Nokia <ivan.frade@nokia.com>
+ * Copyright (C) 2014, Lanedo <martyn@lanedo.com>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -25,10 +26,15 @@
 #include <glib.h>
 #include <gio/gio.h>
 
+#define G_SETTINGS_ENABLE_BACKEND
+#include <gio/gsettingsbackend.h>
+
+#include <libtracker-common/tracker-common.h>
+
 #include "tracker-fts-config.h"
 
-/* GKeyFile defines */
-#define GROUP_INDEXING             "Indexing"
+#define CONFIG_SCHEMA "org.freedesktop.Tracker.FTS"
+#define CONFIG_PATH   "/org/freedesktop/tracker/fts/"
 
 /* Default values */
 #define DEFAULT_MAX_WORD_LENGTH      30     /* 0->200 */
@@ -217,18 +223,62 @@ config_finalize (GObject *object)
 static void
 config_constructed (GObject *object)
 {
+	GSettings *settings;
+
 	(G_OBJECT_CLASS (tracker_fts_config_parent_class)->constructed) (object);
 
-        g_settings_delay (G_SETTINGS (object));
+	settings = G_SETTINGS (object);
+
+	if (G_LIKELY (!g_getenv ("TRACKER_USE_CONFIG_FILES"))) {
+		g_settings_delay (settings);
+	}
+
+	g_settings_bind (settings, "max-word-length", object, "max-word-length", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
+	g_settings_bind (settings, "enable-stemmer", object, "enable-stemmer", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
+	g_settings_bind (settings, "enable-unaccent", object, "enable-unaccent", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
+	g_settings_bind (settings, "ignore-numbers", object, "ignore-numbers", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
+	g_settings_bind (settings, "ignore-stop-words", object, "ignore-stop-words", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
+	g_settings_bind (settings, "max-words-to-index", object, "max-words-to-index", G_SETTINGS_BIND_GET | G_SETTINGS_BIND_GET_NO_CHANGES);
 }
 
 TrackerFTSConfig *
 tracker_fts_config_new (void)
 {
-	return g_object_new (TRACKER_TYPE_FTS_CONFIG,
-                             "schema-id", "org.freedesktop.Tracker.FTS",
-                             "path", "/org/freedesktop/tracker/fts/",
-	                     NULL);
+	TrackerFTSConfig *config = NULL;
+
+	/* FIXME: should we unset GSETTINGS_BACKEND env var? */
+
+	if (G_UNLIKELY (g_getenv ("TRACKER_USE_CONFIG_FILES"))) {
+		GSettingsBackend *backend;
+		gchar *filename;
+		gboolean need_to_save;
+
+		filename = g_build_filename (g_get_user_config_dir (), "tracker", "tracker-fts.cfg", NULL);
+
+		need_to_save = g_file_test (filename, G_FILE_TEST_EXISTS) == FALSE;
+
+		backend = g_keyfile_settings_backend_new (filename, CONFIG_PATH, "General");
+		g_info ("Using config file '%s'", filename);
+		g_free (filename);
+
+		config = g_object_new (TRACKER_TYPE_FTS_CONFIG,
+		                       "backend", backend,
+		                       "schema-id", CONFIG_SCHEMA,
+		                       "path", CONFIG_PATH,
+		                       NULL);
+		g_object_unref (backend);
+
+		if (need_to_save) {
+			g_info ("  Config file does not exist, using default values...");
+		}
+	} else {
+		config = g_object_new (TRACKER_TYPE_FTS_CONFIG,
+		                       "schema-id", CONFIG_SCHEMA,
+		                       "path", CONFIG_PATH,
+		                       NULL);
+	}
+
+	return config;
 }
 
 gboolean

diff --git a/src/miners/fs/.gitignore b/src/miners/fs/.gitignore
@@ -2,3 +2,4 @@ tracker-miner-fs
 *.service
 *.xml
 *.valid
+*.cfg.5