b6861ed768
The distinction between vcard21 and vcard30 became mute in the Evolution backend a while ago. Both tests ended up using the vCard 3.0 Evolution tests data and the default uri for each server. This patch removes the vCard 2.1 special case. It also renames the tests and test data to reflect that they always were Evolution specific. The new naming convention, also applied to file, QtContacts, KCalExtended, XMLRPC, Maemo and Akonadi backends, is now <backend>_contact/event/task/memo, with eds/file/qt/kcal/maemo/kde as backend names. The reasoning is: - results in unique string (in particular no overlap with backend type names), easier to search for - underscore already used before (in contrast to hyphen) - no plural-s to keep the name shorter The Akonadi backend should be using its own test data instead of the Evolution ones.
384 lines
16 KiB
Text
384 lines
16 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 and Boost (>= 1.35) development
|
|
files. For HTTP, either Curl or libsoup can be used.
|
|
|
|
On Debian based systems the required packages can be installed with
|
|
apt-get install evolution-data-server-dev \
|
|
libecal1.2-dev libebook1.2-dev \
|
|
libsoup2.4-dev \
|
|
libboost-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
|
|
|
|
For compiling libsynthesis:
|
|
apt-get install libpcre3-dev libsqlite3-dev libexpat-dev libz-dev
|
|
|
|
This was copied from the libsynthesis README.
|
|
|
|
The test framework also requires CPPUnit:
|
|
apt-get install libcppunit-dev
|
|
|
|
For the GUI and its D-Bus based service backend:
|
|
apt-get install libdbus-glib-1-dev \
|
|
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 CFLAGS="-g -Wall -Werror -Wno-unknown-pragmas" \
|
|
CXXFLAGS="-g -Wall -Werror -Wno-unknown-pragmas" \
|
|
--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
|
|
- 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
|
|
- 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
|
|
- 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.
|
|
|
|
Testing Buteo
|
|
---------
|
|
|
|
SyncEvolution enables Buteo testing based client-test. Configure with
|
|
--enable-integration-tests and --enable-buteo-tests and then run
|
|
"src/client-test" to test Buteo with the above described environment
|
|
variables. The only difference is that you have to set a new one
|
|
"CLIENT_TEST_BUTEO=1". Buteo testing supports testing two kinds of
|
|
data: qt_contact and kcal_event.
|
|
|
|
Here are step-by-step instructions to get started with Buteo testing,
|
|
also 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
|
|
- create Buteo sync profile file ~/.sync/profiles/sync/scheduleworld.xml
|
|
and edit and enter account data for ScheduleWorld.
|
|
- chmod -R 666 /etc/sync
|
|
=> change the access mode of the directory /etc/sync
|
|
- CLIENT_TEST_SERVER=scheduleworld \
|
|
CLIENT_TEST_EVOLUTION_PREFIX=file:///tmp/testing/ \
|
|
./client-test Client::Sync::qt_contact
|
|
=> runs all tests for qt_contact
|