Wiki Navigation

OpenSync devel-branch 0.30

This is (at the moment) a quick and dirty introduction in the devel-branch 0.3x (ie, trunk in SVN).
Please help in enhancing this introduction and feel free to add questions if something is not described detailed enough.

Please add also missing features to http://www.opensync.org/wiki/TODO

Whats so special about the devel-branch?!

capabilities
merger
improved sync engine
- faster synchronization
- discovering of supported object types
- configurable enabling/disabling of object types
...

See the glossary for explanations of some of the important new terms and concepts.

Build it!

(Please! Do not waste your time in searching/asking for packages of this version. It is very experimental!)

Setting up an Build and Developing Environment

For developing OpenSync you don't have to mess up your system and install the OpenSync framework system global. Following global environments have to be set to build and run a local build of OpenSync. It is recommend to put this in a file and source this one everytime if you want to use/build OpenSync:

# directory for the build ( /usr and/or /usr/local is not recommended for developing only! )
export OPENSYNC_BUILD=/home/user/build
export LIBSUFFIX=lib

# For 64bit systems...
#export LIBSUFFIX=lib64

# this is required that frontends and plugins find the opensync-1.0.pc file
export PKG_CONFIG_PATH=$OPENSYNC_BUILD/$LIBSUFFIX/pkgconfig:$PKG_CONFIG_PATH

export PATH=$OPENSYNC_BUILD/bin:$PATH

# If the libraries got no installed in /etc/ld.so.conf locations
export LD_LIBRARY_PATH=$OPENSYNC_BUILD/$LIBSUFFIX:$LD_LIBRARY_PATH

# enable tracing -- target directory has to exist already
export OSYNC_TRACE=/tmp/osync_trace/

# useful for valgrind and --leak-check
# export G_SLICE=always-malloc

# Inspired by KDE4:
# cmake setup function for people which aren't familiar with cmake. Shame on you!
function osync_cmake {

if test -z "$1"; then
echo -e "usage: osync_cmake <source directory>\n\n Run this in a separeted directory out of your source tree.\n"
return -1;
fi

# 64bit systems should add -DLIB_SUFFIX=64 to the cmake command
cmake -DCMAKE_INSTALL_PREFIX=$OPENSYNC_BUILD $1
make VERBOSE=1
make install

}

Put this in a file and source this file everytime you want to build or run OpenSync. Or source this file in your ~/.bashrc

. ~/projects/opensync/source.me

If you're new to CMake build environment this allows you to use the command "osync_cmake <source directory>".

OpenSync Framework

To build OpenSync you need CMake, (check for unit tests - optional) and the devel packages of sqlite3, glib2, libxml2, and libsxlt; optionally, swig for python bindings. 64-bit systems should add the -DLIB_SUFFIX=64 flag to cmake.

If you have sourced the "source.me" file then you can use "osync_cmake":

svn co http://svn.opensync.org/trunk opensync
cd opensync/
mkdir build
cd build
osync_cmake ../

... or do it the native CMake way:

svn co http://svn.opensync.org/trunk opensync
cd opensync/
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=$OPENSYNC_BUILD ../
make
make install

Plugins

All plugins from the trunk version need to be ported for the devel-branch. See PluginPortingGuide-0.30.

file-sync

With "osync_cmake":

svn co http://svn.opensync.org/plugins/file-sync
cd file-sync
mkdir build
cd build
osync_cmake ../

... native CMake build:

svn co http://svn.opensync.org/plugins/file-sync
cd file-sync
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=$OPENSYNC_BUILD ../
make
make install

vformat

This is needed to support discoverable object types with msynctool (see example below).

With "osync_cmake":

svn co http://svn.opensync.org/format-plugins/vformat
cd vformat
mkdir build
cd build
osync_cmake ../

... native CMake build:

svn co http://svn.opensync.org/format-plugins/vformat
cd vformat
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=$OPENSYNC_BUILD ../
make
make install

Frontends

There is only msynctool for the devel-branch. GUIs like kitchensync and multisync get ported later...

msynctool

With "osync_cmake":

svn co http://svn.opensync.org/multisync/trunk msynctool
cd msynctool
mkdir build
cd build
osync_cmake ../

... or native CMake:

svn co http://svn.opensync.org/multisync/trunk msynctool
cd msynctool
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=$OPENSYNC_BUILD ../
make
make install

msynctool should return:

> msynctool --version
This is msynctool version "0.33"
using OpenSync version "0.33"

Synchronization Example

Simple file-to-file syncing

msynctool --addgroup file2file
msynctool --addmember file2file file-sync
msynctool --addmember file2file file-sync
msynctool --configure file2file 1

The file-sync config changed with the devel branch. It is possible to store different object types in different directories:

<config><directory><path>/tmp/osync-aaa/mycontacts/</path><objtype>contact</objtype></directory></config>

This configuration stores all contacts in /tmp/osync-aaa/mycontacts/. Also it will not accept/store any other object type. You have to create another directory node to add/store further object types. By default object type "data" is set. The data object type is still kind of special. "data" accepts every object type, like in the trunk version of OpenSync.

msynctool --configure file2file 2

We also configure this member with contact only:

<config><directory><path>/tmp/osync-bbb/mycontacts/</path><objtype>contact</objtype></directory></config>

Now the group is configured... isn't it?! No! :P The devel-branch supports discovering supported object types. With msynctool you have to do this before the inital synchronization. Otherwise you will get something like this:

> msynctool --sync file2file
Synchronizing group "file2file"
ERROR: No synchronizable objtype

Discovering supported object types of the group for each member:

dani@sugga:~> msynctool --discover file2file 1
Discovered Objtypes:
        contact
                Format: file
dani@sugga:~> msynctool --discover file2file 2
Discovered Objtypes:
        contact
                Format: file

Note: If you change the object types in your file-sync configuration you have to run this again!

Now your sync group is ready:

dani@sugga:~> msynctool --showobjtypes file2file
Member 1 Objtypes:
        Objtype contact: Enabled
                Format: file
Member 2 Objtypes:
        Objtype contact: Enabled
                Format: file
Objtypes for the group:
        contact: Enabled

Time to sync:

msynctool --sync file2file

Modules of the devel-branch

Client

Data

Engine

Format

Filter

Converter

Group

Groups

Members

Helpers

The Helpers are function which provide needed synchronization function for the plugins. These are only used in the plugins and not in the engine.

Hashtable

Anchor

The Anchor module stores some kind of data (called "anchor") from the Member. This "anchor" gets updated once on each sync. If the "anchor" doesn't match on the next sync a slow-sync got triggered.

Example: A random string gets generated on the Member on each sync: XYZ XYZ got stored as "anchor". The Member didn't get reseted/synced somewhere else in meantime. On the beginning of the next sync the anchor and the string got compared and match: XYZ == XYZ Regular sync and new random string: ABC. This time the Member got synced with another system and generate a new random string: DEF On the next local sync the anchor got compared with the Member stored string: ABC != DEF The "anchor" didn't match with the Member string. To avoid any data loss and to get the changed entries of the previous sync a slow-sync is required.

Example implementation in plugins: syncml, palm-sync, irmc-sync, ...

IPC

Mapping

Merger

The Merger module is intended to avoid data loss between different Member which doesn't support the same amount of attributes. (e.g. Member 1: Name, Telephone, EMail, URL; Member 2: Name, Telephone, EMail, Member 3: Name, EMail, IM) The Merger stores the whole entry in the Archive (tbl_archive). Then it compare the known Capabilities with the entry and remove (demerge) unsupported fields. Finally the modified entry get send to the Member.

When the (modified) entry got changed or requested by engine the Merger checks again for unsupported fields/attributes. The unsupported fields/attributes got included from the copy, which is stored in the Archive. (TODO: diagram of the merge/demerge process)

Capabilities

The Capabilities module provide the information which fields/attributes of an entry is supported by the certain device. This is stored in a XML format. There is for each object type a different XML Scheme. The listed XML items stands for support fields/attributes. The capabilities are stored in the OpenSync data directory "capablities" (e.g /usr/local/share/opensync/capabilities/file-sync.xml). Individual defined capabilities are stored in the member directory and have a higher priority then the global one which is stored in the OpenSync data directory. If the device/application can handle every attribute/information no capabilities have to be defined (white listing).

(The XML Capabilities format _must_ be sorted. Child nodes of attributes also have to be sorted .. the child doesn't get sorted by the sort() function!)

Module

Plugin

Sink

Version

The Version module is needed to identify a device or application to load predefined capabilities (if available). The Version module can handle following details:

plugin name
model name/version
firmware version
software version
hardware version

FAQ

Download in other formats:

Plain Text