Skip to content

Redesign of SyncEvolution Config Handling

The config file handling of SyncEvolution is not particularly user-friendly. The reason is that it is a direct port of the Funambol client configuration mechanism, which was supposed to be manipulated via a GUI, not via a text editor. With 0.7 released, now is a good time to rethink that approach. This post explains how the new configuration mechanism could work and how it could be rolled out – this is your chance to object before it is too late!

The Bad

Let’s start by looking at what is bad about the current system. For a server called foo with a data source called bar it consists of the following files:

  • .sync4j/evolution/foo/spds/syncml/config.txt – settings per server
  • .sync4j/evolution/foo/spds/sources/bar/config.txt – settings per source

There are a few things which I don’t like about this layout:

  • redundant directories: what the heck does spds stand for anyway? Do we really need syncml?
  • Funambol has long ago changed its name, .sync4j is dead.
  • Some of these config.txt files are modified by SyncEvolution during a sync.
  • The file suffix does not reflect the file type, .ini would have been better. With that suffix syntax highlighting in e.g. Emacs (everyone’s favorite editor, right?) is enabled automatically.

The Good

I like the simple, .ini-style config files. It is easy to manipulate the settings with shell tools. It’s just the location of these files and the mixture of read/write and read-only properties in the same file which bothers me. So here’s the proposal for the a directory hierarchy:

  • .syncevolution/foo – base directory for server foo
    • config.ini – constant per-server settings
    • .internal.ini – read/write server properties – hidden from users because of the leading dot
    • sources/bar – base directory for source bar
      • config.ini – constant per-source settings
      • .internal.ini – read/write source properties

The Ugly

The biggest problem with this change is the transition from older configs to the new one. Since version 0.1 of SyncEvolution it has never been necessary to change anything manually when going to a new version (but there were recommended changes) and it was always possible to go back to an older version. Never has an update forced a slow sync (which can lead to duplicates).

I still find these aspects important and would like to preserve them when introducing the new schema. So here’s the plan:

  • if only an old-style server configuration exists, then SyncEvolution will continue to use it
  • a new command line option --migrate will take the properties from an existing old-style configuration and create the new one

There are some problems with this: the GUIs for SyncEvolution (the Funambol iPhone Plug-in and Frederik’s Genesis) make assumptions about the layout of config files and would have to be adapted.

Automatic Changes to Configuration

I also thought about simplifying the setup procedure, for example by integrating the copying of the example configs into SyncEvolution and making the most common changes based on user input without ever opening a text editor. I decided against it because I fear that this will never be flexible enough and not much easier to use than mkdir -p ~/.syncevolution; cp -r foo ~/.syncevolution; emacs ~/.syncevolution/foo/config.ini.

[Update 2008-02-10] Because of the ensuing discussion and the problem that the example configs were deleted during installation on Internet Tablets I have changed my mind about that: now I think that some options to setup or update a configuration would be useful. The intention is that front-ends like Genesis can interact with the configuration without ever having to read files directly. Here’s my proposal for the new options:

Prints the names of all configured servers to stdout.

Prints the complete configuration for the selected server
to stdout, including up-to-date comments for all properties. The
format is the normal .ini format with source configurations in
different sections introduced with [<source>] lines.

Modify the configuration files for the selected server. If no such
configuration exists, then a new one is created using one of the
template configurations (see –template option). When creating
a new configuration only the active sources will be set to active
in the new configuration, i.e. “syncevolution -c scheduleworld addressbook”
followed by “syncevolution scheduleworld” will only synchronize the
address book.
In SyncEvolution <= 0.7 a different layout of configuration files
was used. Using –configure will automatically migrate to the new
layout and rename the old directory $HOME/.sync4j/evolution/<server>
into $HOME/.sync4j/evolution/<server>.old to prevent accidental use
of the old configuration. WARNING: old SyncEvolution releases cannot
use the new configuration!

–sync-property|-y <property>=<value>
Overrides a configuration property in the <server>/config.ini file
for the current synchronization run or permanently when –configure
is used to update the configuration. Can be used multiple times.
Specifying an unused property will trigger an error message.

–source-property|-z <property>=<value>
Same as –sync-option, but applies to the configuration of all active
sources. “–sync <mode>” is a shortcut for “–source-option sync=<mode>”.

–properties|-r <file name>|-
Same as –sync-property and –source-property, but with properties
specified in a file with the same format that –print-config uses.
“-” reads from stdin.

–template|-l <server name>
Can be used to select from one of the built-in default configurations
for known SyncML servers. Defaults to the <server> name, so –template
only has to be specified when creating multiple different configurations
for the same server.
SyncEvolution has configurations for:
scheduleworld =
funambol =

Here are some uses cases for these options:

Migrate a configuration from the <= 0.7 format to the current one:
$ syncevolution –configure scheduleworld

Deactivate all sources:
$ syncevolution –configure –source-property sync=none scheduleworld

Activate address book synchronization again, using the –sync shortcut:
$ syncevolution –configure –sync two-way scheduleworld addressbook

Set up another configuration for scheduleworld under a different name:
$ syncevolution –configure \
–sync-property user=joe \
–sync-property password=foo \
–template scheduleworld \

Edit all configuration properties at once:
$ syncevolution –print-config scheduleworld >config.ini
$ $EDITOR config.ini
$ syncevolution –configure –properties config.ini scheduleworld

{ 6 } Comments

  1. Frederik | December 30, 2007 at 1:48 pm | Permalink


    I like your ideas about a new config layout. I especially like the separation of user configuration and syncevolution’s internals.

    Regarding Genesis, I would probably simply drop support for the old config style once the new one is supported by a release of syncevolution. If you provide a –migrate option, it would be easy to notify the user and ask for migration, so he or she can continue using Genesis. But this will only become relevant once Genesis has a configuration editor that allows the editing of existing configurations.

    You mentioned simplifying the setup. How would you ask the user for the necessary input? With a text interface? Currently, this is what Genesis’ setup assistant does: Ask for the needed information and create the config files in the right place. But of course a text-based interface in syncevolution is more generic and would work on more systems. It’s only a matter of if you want to add this kind of interface to syncevolution itself, or if external frontends should handle this.

    If this should take place in syncevolution itself, I might adopt Genesis to access syncevolutions capabilities instead of implementing it by myself. Or I could easily create a python interface for this separate of Genesis, so one could write a text interface using the same mechanisms Genesis currently uses.


  2. Patrick Ohly | December 30, 2007 at 2:30 pm | Permalink

    “How would you ask the user for the necessary input? With a text interface?” — That’s the sticky point. An interactive, text-based interface would create new dependencies on libcurses (when using text masks) or libreadline (for question/answer style interaction). I’d like to avoid that to preserve the portability of the code.

    The other open question is: how many options should be controlled by the user and how many should be taken from the config templates? Okay, let’s think about this a bit: required are account name and password and the template which is to be used. Optionally perhaps a specification of which sources are to be synchronized and the logdir.

    Anything going beyond that (servers for which no template exists, non-standard Evolution database names) would have to be configured via an editor. Hmm, this seems doable.

    So here’s an updated proposal:

    syncevolution –setup [--username name] [--password passwd] server [source1 source2 ...]

    This will create (if it does not yet exist) or update (if it exists) a new-style config for server. The default settings for all properties come from an old-style config (if one with the same server name is found), one of the example configs (again, only if one exists) or from built-in defaults. Configs for all sources will be created, but only the ones enabled in the config template will be active or (if sources were listed on the command line) those selected explicitly.

    One more comment about the “bad” aspects of the both the old and new config files: the files are always called “config.txt”. If you have multiple of them open in a text editor, then it is not easy to tell them apart. Instead of sources/bar/config.ini and sources/bar/.internal.ini, would it be better to use sources/bar.ini and sources/ Hmm, no, I don’t think so: renaming a source would involve renaming two files, one of them not even visible to the user.

  3. Frederik | December 31, 2007 at 1:21 pm | Permalink

    In addition, proxy settings might be essential for some users. And regarding the non-standard evolution database names: How does l10n affect this? The templates contain evolution sources called “Personal” as default. On a German system, the default sources are called “Persönlich”. Now I simply don’t know if EDS/syncevolution do handle this, so that a default of “Personal” would also work with sources called “Persönlich” because of some internal default settings.

    Another way would be to leave this entirely out of syncevolution and leave this to frontends. Genesis does this for GNOME environments (asking for a server name, a template or a custom server URL (using the funambol template for the other settings), username, password, proxy settings. When selecting the sources to sync, it provides the existing database names for selection. A separate commandline tool could do the same for non-graphical (or non-GNOME) environments.

    But if you decide to build this into syncevolution, frontends could use syncevolution directly for the basic setup and still provide further options (like source database selection).

    Regarding the file names: Some editors do show the full path to the file, so identical file names would be less a problem. And I like the directory structure better than only organizing them by file name in a common directory.

  4. John | January 2, 2008 at 2:00 pm | Permalink

    You may want to have a look at the groups basedir spec:

    This would mean that you could put your config in $XDG_CONFIG/syncevolution or .config/syncevolution

    Just a thought.

    Cheers for a great solution by the way. It working great here for sync from phone and Evo next up is my n800.

  5. Patrick Ohly | January 2, 2008 at 6:49 pm | Permalink

    @Frederik: I’m not sure whether proxy settings really are important. I believe that libcurl will use the http_proxy environment variable which at least I have in my environment anyway at work. It probably doesn’t hurt to add an option.

    Localization is indeed a point. I had never bothered to check whether the default data source name is localized. Hmm, in that case I guess I will add another automatism: when creating a new config, the first data source of each type should be used unless overridden, e.g. with “syncevolution –setup server addressbook=Persönlich”.

    @John: thanks for the pointer, I wasn’t aware of this standard. I’m not exactly sure about the use cases, but as we are about to break with the past we might as well do it right. So $XDG_CONFIG_HOME/syncevolution = $HOME/.config/syncevolution it is… I still intend to put the writable properties there, though, and not use $XDG_DATA_HOME for those.

  6. gazza | January 3, 2008 at 6:17 pm | Permalink

    Just some clarifications on the DM tree implementation for posix:
    * .sync4j is a leftover and must be changed, also for the funambol DM for posix. The easiest change is to make it .funambol, but i would like to have it configurable by the client. We’re going to change it on the HEAD, since this is not a problem for SyncEvolution anymore.
    * .txt, for what I know, is the extension you choose. No problem to change it for the DM too.
    * just for info, spds stands for Sync Protocol Data Synchronization, which means you can have in the DM tree also a spdm subtree (guess what it means.. ;) ) and other subtree specific for the client.

{ 2 } Trackbacks

  1. [...] redesign of the SyncEvolution config handling is now ready to be tried out by brave users. This is still in a very early stage, but I have spent [...]

  2. [...] New configuration file layout: following the recommendation, new configurations are stored in $XDG_CONFIG_HOME/syncevolution or $HOME/.config/syncevolution if XDG_CONFIG_HOME is not set. The old layout under $HOME/.sync4j/evolution is still supported. [...]

Post a Comment

Your email is never published nor shared. Required fields are marked *