Fr:Developer Setup

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.

Communication
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:


 * The IRC channel #davical on irc.oftc.net
 * The developers mailing list http://lists.morphoss.com/listinfo/davical-dev

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

Revision Control
We use the "Git" revision control system primarily, although you can also check the code out of the Subversion or CVS repositories on Sourceforge where all the commits should eventually be mirrored.

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

git clone git://repo.or.cz/davical.git

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

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 me, you can use the git-format-patch command to produce e-mail directly to me, such as:

git format-patch --stdout myhacks@{1} | mail proposed-patches-AT-davical.org

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).

Anohter way to sent patches is via git pull requests.

Submitting changes into git directly by using the mob branch
Warning: Instructions might not be 100% complete yet, working on this one (MaWa).

You could also check out the git repo, switch to the mob branch and then commit your changes into that branch:

git clone git://repo.or.cz/davical.git cd davical git checkout -b mob origin/mob git pull git commit git push git+ssh://mob@repo.or.cz/srv/git/davical/
 * 1) grab head of master from remote repository
 * 1) create local branch based on remote mob branch
 * 1) update working copy to mob
 * 1) commit into your local branch, files will not go into the remote repo yet
 * 1) push (publish) your changes to the mob branch of the davical repository

You might need to switch your AWL to mob, too.

Browsing the Git Repository
The repo.or.cz Git repository is also available using gitweb, so you can access the DAViCal project via a web interface at:
 * http://repo.or.cz/w/davical.git - The DAViCal code base
 * http://repo.or.cz/w/awl.git - The code for Andrew's Web Libraries (AWL)

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 ServerAlias hostname.domain.foo 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:

127.0.0.1  localhost mycaldav myempty

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

 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]   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;

Running the Regression Tests
The regression tests are configured in 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 irc.oftc.net #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 git://repo.or.cz/awl.git/

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.