d1db2d30a1
Pseudo-backend (really more like a plugin for Buteo) and testing framework changes were removed because Buteo is obsolete.
368 lines
15 KiB
Text
368 lines
15 KiB
Text
Compiling from Source
|
|
---------------------
|
|
|
|
To compile the code the source or an installation of the Synthesis
|
|
SyncML engine is needed. A compatible snapshot of it is included in
|
|
SyncEvolution source packages and will be used automatically.
|
|
The section _`Checking out the source` explains how to work
|
|
with sources obtained via the git repositories.
|
|
|
|
Also needed are the Evolution (can be disabled), Boost (>= 1.35) and
|
|
pcre development files. For HTTP, either Curl or libsoup can be used.
|
|
For compiling libsynthesis, sqlite, expat, libz are needed.
|
|
|
|
On Debian based systems, the required packages can be installed with
|
|
apt-get install evolution-data-server-dev \
|
|
libglib2.0-dev \
|
|
libecal1.2-dev libebook1.2-dev \
|
|
libsoup2.4-dev \
|
|
libpcre3-dev \
|
|
libexpat-dev \
|
|
libz-dev \
|
|
libboost-dev
|
|
|
|
If gio (part of libglib) is not available in version 2.26 or higher,
|
|
then libdbus can be used as fallback (not needed otherwise):
|
|
apt-get install libdbus-glib-1-dev
|
|
|
|
libboost-dev >= 1.34, available as libboost1.35-dev backport for Debian Etch.
|
|
|
|
Necessary on some distros due to bad dependencies (not needed by SyncEvolution itself):
|
|
apt-get install libdb3-dev
|
|
|
|
Optional (enables reading proxy settings from GNOME preferences):
|
|
apt-get install libsoup-gnome2.4-dev
|
|
|
|
Optional (enables direct sync with phones):
|
|
apt-get install libopenobex-dev libbluetooth-dev
|
|
|
|
Optional (only used for SHA-256 when glib is not already a dependency):
|
|
apt-get install libnss3-dev
|
|
|
|
The test framework also requires CPPUnit:
|
|
apt-get install libcppunit-dev
|
|
|
|
For the GUI and its D-Bus based service backend:
|
|
apt-get install xsltproc \
|
|
libglib2.0-dev \
|
|
libgtk2.0-dev libglade2-dev \
|
|
libgnome-keyring-dev \
|
|
libgconf2-dev libgnomevfs2-dev
|
|
|
|
Optional packages for GUI:
|
|
apt-get install libunique-dev
|
|
|
|
libunique = ensure that GTK GUI only runs once per user
|
|
|
|
Optional packages for GNOME Bluetooth Panel plugin:
|
|
apt-get install libgnome-bluetooth-dev
|
|
|
|
The plugin adds a button to invoke sync-UI after a device
|
|
was paired which supports SyncML.
|
|
|
|
The build system is the normal autotools system. See INSTALL for
|
|
general instructions how to use that and "./configure --help" for
|
|
SyncEvolution specific options.
|
|
|
|
Note that compiling without the Evolution development files is
|
|
possible. But because this is usually not what people want,
|
|
the configure script needs explicit --disable-ecal --disable-ebook
|
|
parameters, otherwise it will refuse to compile without Evolution
|
|
support.
|
|
|
|
When compiling from a git checkout, remember to run "./autogen.sh".
|
|
It depends on:
|
|
apt-get install libtool intltool automake
|
|
|
|
|
|
Checking out the Source
|
|
-----------------------
|
|
|
|
SyncEvolution is hosted on moblin.org. Anonymous access is via
|
|
git clone git://git.moblin.org/syncevolution.git
|
|
|
|
Before using sources checked out from Subversion, invoke "sh
|
|
autogen.sh" with appropriate autotools packages installed.
|
|
|
|
When running the configure script, it can be told to compile a
|
|
Synthesis library automatically via the --with-synthesis-src configure
|
|
option. This has advantages when modifying the Synthesis source
|
|
together with SyncEvolution (no need to install Synthesis and thus
|
|
faster compilation) and will bundle the Synthesis sources in source
|
|
.tar.gz archives.
|
|
|
|
The upstream Synthesis source code is here:
|
|
git://www.synthesis.ch/libsynthesis.git
|
|
The staging area for patches developed as part of Moblin are
|
|
in the following repository:
|
|
git://git.moblin.org/libsynthesis.git
|
|
|
|
The intention is to include all these patches upstream to
|
|
prevent forking the code. If you want to get patches included
|
|
in the Synthesis code base, then please work directly with
|
|
the upstream branch.
|
|
|
|
For doing development work the recommended configure line is:
|
|
configure --with-synthesis-src=<path to libsynthesis source> \
|
|
--enable-warnings=fatal \
|
|
--enable-unit-tests \
|
|
--enable-libcurl \
|
|
--disable-shared \
|
|
--enable-developer-mode
|
|
|
|
Enabling libcurl explicitly ensures that it gets built even when not
|
|
the default.
|
|
|
|
--disable-shared results in easier to debug executables (no shell
|
|
wrapper scripts, all symbols available before the program runs).
|
|
|
|
Backend libraries are dynamically scannned and loaded into syncevolution, the
|
|
library path defaults to $prefix/syncevolution/backends. When developer-mode is
|
|
enabled, it will scan libraries in current build directory instead.
|
|
|
|
-Wno-unknown-pragmas is required to avoid warnings triggered by
|
|
'#pragma }', a trick to preserve indention after 'extern "C" {' in
|
|
/usr/include/evolution-data-server-1.12/libical/
|
|
|
|
Working with the Code
|
|
---------------------
|
|
|
|
The code follows the code formatting of the Funambol
|
|
C++ client library. Just emulate the existing
|
|
code when possible.
|
|
|
|
Exceptions derived from std::exception are used to report errors. The
|
|
EvolutionSyncSource::handleException() function deals with logging the
|
|
exception.
|
|
|
|
SyncEvolution uses the a CPPUnit based testing framework. Configure
|
|
with --enable-integration-tests and (optionally) --enable-unit-tests,
|
|
then run "src/client-test" as described in src/client-test-app.cpp.
|
|
|
|
It understands several environment variables, among them:
|
|
- CLIENT_TEST_SERVER = chooses config
|
|
- CLIENT_TEST_SOURCES = comma separated list of enabled sources, identified
|
|
by their name
|
|
For Evolution: eds_contact,eds_event,eds_task,eds_memo
|
|
For file backend: file_contact,file_event,file_task,file_memo (uses same test
|
|
data and vCard flavor as Evolution)
|
|
- CLIENT_TEST_EVOLUTION_PREFIX=[name|file://<path>] overrides
|
|
the evolutionsource setting in the configuration; if file:// is used
|
|
then these database will be created automatically
|
|
NOTE : The automatic database creation is not supported for EDS 2.32. We need
|
|
to create manually the databases using Evolution. New database names must be
|
|
named ${CLIENT_TEST_EVOLUTION_PREFIX}${CLIENT_TEST_SOURCES}_[12].
|
|
Example: if CLIENT_TEST_EVOLUTION_PREFIX=Test_ and Client::Sync::eds_contact
|
|
is used, then addressbooks with the names 'Test_eds_contact_1' and
|
|
'Test_eds_contact_2' must exist.
|
|
- CLIENT_TEST_XML=1 use XML format as default instead of the normal WBXML
|
|
|
|
For unattended testing:
|
|
- CLIENT_TEST_FAILURES = comma separated list of tests which are allowed
|
|
to fail without affecting the return code of the test runner; each list
|
|
entry is a regex which must match a complete test name
|
|
- CLIENT_TEST_SKIP = comma separated list of tests or test groups which
|
|
are not to be executed at all; for this to work the test or test group
|
|
has to be passed through test.h's version of ADD_TEST or FilterTest,
|
|
which is the case for most tests but not all; as in CLIENT_TEST_FAILURES,
|
|
each entry is a regex
|
|
- CLIENT_TEST_LOG = name of server log file, will be copied and reset
|
|
after each sync
|
|
- CLIENT_TEST_ALARM = number of seconds a single test is allowed to run
|
|
before aborting it
|
|
|
|
Most Client::Sync tests use the default encoding, usually WBXML unless
|
|
changed via CLIENT_TEST_XML=1. Client::Sync::*::testItemsXML always
|
|
uses XML and Client::Sync::*::testItems always WBXML.
|
|
|
|
Here are step-by-step instructions to get started with testing,
|
|
using ScheduleWorld as example:
|
|
- CLIENT_TEST_SERVER=scheduleworld \
|
|
CLIENT_TEST_EVOLUTION_PREFIX=file:///tmp/testing/ \
|
|
./client-test -h
|
|
=> creates ~/.config/syncevolution/scheduleworld_[12]/ configs
|
|
which use data bases under /tmp/testing, then
|
|
prints all available tests
|
|
- edit ~/.config/syncevolution/scheduleworld_[12]/spds/syncml/config.txt
|
|
and enter account data for ScheduleWorld in both configurations;
|
|
check that the syncURL is correct
|
|
- CLIENT_TEST_SERVER=scheduleworld \
|
|
CLIENT_TEST_EVOLUTION_PREFIX=file:///tmp/testing/ \
|
|
./client-test Client::Source
|
|
=> runs alls tests involving just local operations
|
|
- CLIENT_TEST_SERVER=scheduleworld \
|
|
CLIENT_TEST_EVOLUTION_PREFIX=file:///tmp/testing/ \
|
|
./client-test Client::Sync::vcard30::testCopy
|
|
=> runs one test that checks that one contact can
|
|
be copied to and from the server using the two
|
|
configurations
|
|
- CLIENT_TEST_SERVER=scheduleworld \
|
|
CLIENT_TEST_EVOLUTION_PREFIX=file:///tmp/testing/ \
|
|
./client-test Client::Sync
|
|
=> runs all tests which involve the SyncML server;
|
|
tests involving just one source are run first,
|
|
followed by the same tests with all enabled
|
|
sources in two different orders
|
|
|
|
"make valgrind" runs the same tests inside valgrind
|
|
[http://www.valgrind.org]. A suppression file is
|
|
used to hide errors inside system libraries which
|
|
are not caused by SyncEvolution or Synthesis
|
|
library code. Most likely the suppressions are system
|
|
dependent and might have to be updated from time to time.
|
|
|
|
|
|
Committing Changes
|
|
------------------
|
|
|
|
Here are some guidelines for well-formed commits:
|
|
- Avoid unnecessary white space changes in the source code.
|
|
- Don't mix unrelated changes in one single commit. Every
|
|
single commit should leave the code in a functional state
|
|
(compiles, unit tests pass, ...).
|
|
- Document new functions and structures with Doxygen comments.
|
|
These comments should really add information, not just
|
|
repeat the name of the entity. At least paraphrase the names.
|
|
- Each commit message should follow the format
|
|
<item>: <summary> [(BMC #1234)]
|
|
<blank line>
|
|
<body>
|
|
- <item> here refers to the module, class or functionality modified
|
|
in the commit, for example "autotools" for the build scripts,
|
|
"EvolutionContactSource" for the EDS contact backend, etc.
|
|
- <summary> should be consise enough to describe the patch on
|
|
its own.
|
|
- The optional bugs.meego.com (BMC) number in round brackets
|
|
refers to the issue addressed by the commit. Most changes,
|
|
in particular bug fixes, should have such an issue filed
|
|
for tracking purposes.
|
|
- The body (hard-wrapped, multiple paragraphs for long text)
|
|
should include the following pieces of information,
|
|
if applicable:
|
|
- problem statement (*why* is the change relevant?)
|
|
- summary of the solution (*how* is the problem solved?)
|
|
- what other solutions were considered and rejected (*context*
|
|
for the solution)
|
|
- known gaps (in particularly useful during code review,
|
|
which will start with the oldest, possibly incomplete patch first)
|
|
|
|
When writing source code comments and commit messages, always remember
|
|
that you are communicating with someone. This person might be even be
|
|
you in some distant future, trying to remember why the heck something
|
|
was done the way it was done... There might not be a chance to ask
|
|
questions, so think about what such a person might want to know and
|
|
answer it in advance.
|
|
|
|
There is a certain redundancy between source code comments, commit
|
|
messages and issue tracker comments. Whenever possible, the
|
|
description of the solution should be in the source code itself, with
|
|
only a brief summary and/or pointer in the commit message. It's fine
|
|
to copy-and-paste to reduce the overall effort.
|
|
|
|
|
|
Building a Release
|
|
------------------
|
|
|
|
- increase version number in configure-pre.in/AM_INIT_AUTOMAKE
|
|
For prereleases use "old version"+"new prerelease"-1 as
|
|
package version. That ensures that package versions are
|
|
higher than the old release, but lower than the final
|
|
release. Avoid hyphens as part of the release names, i.e.
|
|
use "0.7+0.8beta1" instead of "0.7+0.8-beta1".
|
|
- ensure files were updated:
|
|
./NEWS debian/changelog
|
|
- update po/LINGUAS
|
|
- check and if necessary, bump the Synthesis .so versions
|
|
(libsynthesis/src/Makefile.am.in)
|
|
- ensure that Synthesis source code is tagged:
|
|
use <base version>+<syncevo version> if local changes exist
|
|
- commit and tag SyncEvolution source code
|
|
- make distcheck
|
|
- compile binary .tar.gz packages for different Evolution versions;
|
|
done automatically by runtests.py on estamos.de (= Debian 3.0), using different Garnome
|
|
installations, and with special configure options to ensure maximum
|
|
portability (LDFLAGS=-Wl,--as-needed --enable-static-cxx)
|
|
- compile .deb for Maemo
|
|
- update entries on the web about the release:
|
|
http://maemo.org/downloads/product/OS2008/syncevolution/
|
|
http://www.estamos.de/blog/wp-admin
|
|
http://www.estamos.de/projects/SyncEvolution/Roadmap.html
|
|
http://freshmeat.net/projects/syncevolution/
|
|
|
|
|
|
Compiling for Maemo
|
|
-------------------
|
|
unpack source archive in Scratchbox (for maximum compatibility: use Chinook 4.0
|
|
rootstrap; for support of all backends: ensure that the EDS-DBus calendar dev packages
|
|
are installed),
|
|
DEB_BUILD_OPTIONS=maemo fakeroot dpkg-buildpackage
|
|
NOTE: dpkg-buildpackage -rfakeroot does *not* work as it leads to strange problems executing a.out
|
|
during the client-src configure.
|
|
|
|
Maemo EDS-DBus calendar dev packages /etc/apt/source.list:
|
|
deb http://maemo.o-hand.com/packages chinook/
|
|
|
|
|
|
Compiling for iPhone
|
|
--------------------
|
|
Requires iPhone toolchain and a libcurl compiled for the iPhone.
|
|
libcurl is ideally configured as small as possible
|
|
and statically (to avoid packaging problems):
|
|
./configure --prefix=/usr/local/iphone --host=arm-apple-darwin --disable-shared \
|
|
--disable-crypto-auth --without-gnutls --without-ssl --without-zlib \
|
|
--without-libssh2 --disable-ipv6 --disable-manual --disable-telnet \
|
|
--disable-tftp --disable-ldap --disable-file --disable-ftp
|
|
manually set HAVE_POSIX_STRERROR_R in lib/config.h
|
|
|
|
Potential problems with toolchain:
|
|
std++ not found: ln -s libstdc++.6.dylib /usr/local/iphone-filesystem/usr/lib/libstdc++.dylib
|
|
AddressBook framework must be added to iphone-dev/include/install-headers.sh.in
|
|
|
|
Compile with curl-config in the PATH:
|
|
PATH=/usr/local/iphone/bin/:$PATH ~/projects/SyncEvolution/trunk/configure --host=arm-apple-darwin --with-funambol-src=/home/patrick/projects/native CXXFLAGS=-O0 --disable-ecal --disable-ebook --enable-addressbook --prefix=/usr
|
|
PATH=/usr/local/iphone/bin/:$PATH make all
|
|
|
|
Build a package with:
|
|
make distbin BINSUFFIX="iphone"
|
|
|
|
Compiling for Mac OS X
|
|
----------------------
|
|
|
|
Configuring for development:
|
|
<path>/configure --with-funambol-src=<path> \
|
|
--enable-addressbook \
|
|
--disable-ecal --disable-ebook \
|
|
CXXFLAGS="-Wall -Werror -Wno-unknown-pragmas" \
|
|
LDFLAGS="-framework Addressbook -framework CoreServices" \
|
|
CXXFLAGS=-g \
|
|
CFLAGS=-g
|
|
|
|
|
|
|
|
Compiling final release:
|
|
./configure --enable-addressbook \
|
|
--disable-ecal --disable-ebook \
|
|
CXXFLAGS="-O -g -arch i386 -arch ppc" \
|
|
CFLAGS="-O -g -arch i386 -arch ppc" \
|
|
LDFLAGS="-arch i386 -arch ppc -framework Addressbook -framework CoreServices" \
|
|
--disable-dependency-tracking
|
|
make BINSUFFIX=mac-os-x distbin
|
|
|
|
Fine-grained memory checking:
|
|
MallocStackLogging=1 MallocStackLoggingNoCompact=1 \
|
|
MallocScribble=1 MallocPreScribble=1 MallocGuardEdges=1 \
|
|
MallocCheckHeapStart=1 MallocCheckHeapEach=100
|
|
|
|
|
|
Debugging
|
|
---------
|
|
|
|
The following packages contain debug information for
|
|
relevant libraries on Ubuntu 7.10:
|
|
evolution-data-server-dbg libglib2.0-0-dbg evolution-dbg
|
|
|
|
Normally, syncevolution redirects stderr to its own log file. In
|
|
crash scenarios the final error messages may get lost. To debug such
|
|
cases, disable redirection by setting the environment variable
|
|
SYNCEVOLUTION_DEBUG (value doesn't matter) and capture the output
|
|
normally.
|