path: root/HACKING

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 \
             --enable-developer-mode

Enabling libcurl explicitly ensures that it gets built even when not
the default.

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 (ical20, vcard21, vcard30, itodo20, text (= memos))
- 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.


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.