Developer Setup

From Davical
Revision as of 19:17, 4 September 2015 by Gorka (talk | contribs)
Jump to navigationJump to search

Template:TOCright The setup for a developer of DAViCal can, of course, just be a normal setup. If you are interested in contributing code, however, there are some tricks to make it easier for you to do so.


If you want to hack on something to do with DAViCal it's important to communicate with the other developers so we know what you're doing, and can suggest ways of approaching the problem that won't be impacted by other ongoing development. Or we can change our plans to make sure we don't step on your toes, and so on. Communication is very important.

The best communication channels for developers are:

This isn't a busy list, and the natives are friendly.

Revision Control

We use the "Git" revision control system at Gitlab. Other mirrors, such as Github or the Subversion or CVS repositories on Sourceforge, are no longer updated and will eventually be deleted!

To create a checkout of DAViCal, assuming you have Git installed, you can:

git clone

Updating Your Local Branch

To update your local branch, merging remote changes into your local changes, you just need to:

cd davical
git pull

Create a new local branch for your own work

git branch myhacks

You may wish to switch to your newly created branch

git checkout myhacks

Write code. Commit changes:

git commit -am "My feature is ready"

Push your branch to GitLab:

git push origin $myhacks

Occasionally you might want to fetch from the remote head branch and rebase your changes against it:

git fetch
git rebase master

Sending A Patch

If you have a particular patch which you wish to send us, you can use the git-format-patch command to produce e-mail directly to the davical-devel list, such as:

git format-patch --stdout myhacks@{1} | mail

That will send the most recent commit on the branch 'myhacks' (i.e. myhacks@{1} refers to the most recent commit - see git-rev-parse man page for exhaustive details of Git references).

Another way to sent patches is via Gitlab pull requests.

Browsing the Git Repository

The Git repository is also available using gitweb, so you can access the DAViCal project via a web interface at:

Make-ing changes

 aptitude install build-essential gettext
 cd ../davical_working_copy
 make all

Apache Setup

Running from the Development Code

There are several ways to run from the development code, but the easiest is probably to use a VirtualHost setup on your development machine, with a hosts file entry on the system with your web browser and/or CalDAV client.

To do this you need to set the following in your Apache configuration:

 DocumentRoot /path/to/davical/htdocs
 ServerName hostname
 DirectoryIndex index.php index.html
 php_value include_path /path/to/awl/inc
 php_value magic_quotes_gpc 0
 php_value register_globals 0

Regression Testing Virtual Hosts

The regression testing for DAViCal expects that there will be a virtual host which responds to URLs like http://mycaldav/ and some regression tests also look for "http://myempty/davical/... for regression testing operation in a subdirectory. Those names are likely to change to more sensible ones like http://davical-regression/ and http://davical-regression-sub/ which will be set up in the same way.

One way to configure this is to add entries to your /etc/hosts file:   localhost mycaldav myempty

Then you need to define your virtual hosts using those entries. They could look something like:

<VirtualHost >
  DocumentRoot /home/user/projects/davical/htdocs
  ServerName mycaldav
  ServerAlias mycaldav.localhost

  DirectoryIndex index.php index.html
  php_value include_path /home/user/projects/awl/inc
  php_value magic_quotes_gpc 0
  php_value register_globals 0

  # This is useful for browsing the docs locally
  AliasMatch ^/docs(.*)$ /home/user/projects/davical/docs/website$1

  # This style of rewriting is tested  in the regression tests.
  # Enable these two lines when debugging rewriting. 
  # RewriteLog /tmp/rewrite.log
  # RewriteLogLevel 4
  RewriteEngine On

  # Not if it's the root URL
  RewriteCond %{REQUEST_URI} !^/$

  # Not if it explicitly specifies a .php program, stylesheet or image
  RewriteCond %{REQUEST_URI} !\.(php|css|png|gif|js|jpg)

  # Not if it is the docs alias above.
  RewriteCond %{REQUEST_URI} !^/docs
  RewriteRule ^(.*)$ /caldav.php$1  [NC,L]

<VirtualHost >
  DocumentRoot /home/user/projects/empty
  ServerName myempty
  ServerAlias myempty.localhost

  DirectoryIndex index.php index.html

  php_value include_path /home/user/projects/awl/inc
  php_value magic_quotes_gpc 0
  php_value register_globals 0 

Note that you have to either copy or better link your htdocs folder to the empty folder for the myempty regression tests to pass. An ls on /home/user/projects/empty (or the folder of your choice) should contain an folder or symlink called davical, which should contain/point to the davical htdocs folder.

You have to create DAViCAL configuration files for all of your testing / production vhosts running on the machine. For testing you need at least mycaldav-conf.php and myempty-conf.php.

You should explicitely not set 'php_value default_charset "utf-8"' in your virtual hosts, as it might break DAViCAL functionality for Evolution. Same applies for 'AddDefaultCharset UTF-8' statements somewhere in your apache.conf or conf.d/charset configuration files.

DAViCal Configuration

You will, of course, need some configuration of DAViCal. For development this is best placed in the file config/config.php so that you can edit it easily as a non-root user. The configuration file is pretty standard, but you should be aware of the error logging availability through setting "$c->dbg['something']" variables.

For example:

/** Every Damn Thing **/
// $c->dbg['ALL'] = 1;

/** Base Server Programs **/
//  $c->dbg['caldav'] = 1;
//  $c->dbg['ics'] = 1;
//  $c->dbg['freebusy'] = 1;

/** HTTP Request Methods **/
//  $c->dbg['options'] = 1;
//  $c->dbg['report'] = 1;
//  $c->dbg['get'] = 1;
//  $c->dbg['put'] = 1;
//  $c->dbg['propfind'] = 1;

/** AWL Objects **/
//  $c->dbg['icalendar'] = 1;
//  $c->dbg['user'] = 1;
//  $c->dbg['i18n'] = 1;
//  $c->dbg['querystring'] = 1;

// use this setting for regression testing only, this influences the order
// of results for some report queries, having strict result ordering off
// might cause your regression test suite to display false results
$c->strict_result_ordering = true;

Other Stuff

Running the Regression Tests

The regression tests are configured in {{{testing/regression.conf}}} and there is a base example configuration to guide you. Some of the regression tests confirm that elements of the system still work when DAViCal is operating in a subdirectory, rather than from the root of the virtual host, so you need an additional virtual host set up for these to work.

Your user will need to have the ability to create/drop databases in order to run the regression tests, since the tests start by dropping the database, creating it from scratch, populating it with some sample data and then testing various caldav operations on it.

Building the API Docs

DAViCal (and AWL) objects are documented in-line using PHPDoc. Essentially you need to download the phpdoc application from PEAR and arrange for the phpdoc command to be somewhere in your path. The top-level Makefile in DAViCal should be able to work from that, but if you have problems get on #davical and ask for some help from an existing developer.

Tracking AWL as well

If you are tracking DAViCal source code it may be a good idea to track The AWL libraries at the same time. Although these libraries are used in other projects besides DAViCal there are often changes within the libraries which new versions of DAViCal will also depend on. Most released versions of DAViCal have depended on a version of AWL released at the same time, though there have been a few occasions of AWL releases without DAViCal releases, or vice-versa.

These are also in a Git repository and can be checked out with:

git clone

You will also need to change the php_include_path in your Apache Virtual Host definition (see above) to point at the checked out libraries, rather than pointing at the default location.