Installation

Installation of Darcsforge components is intended to be similar to the installation of any other Django applications. It is suggested that users should be familiar with Django.

Contents

• Installation
  • Dependencies
  • Django Settings
  • Darcs Defaults
  • Darcs Apply Posthook

Dependencies

See also

Python

Python is the language of choice.

Django Framework

Django provides the fundamental web stack used by Darcsforge.

reStructuredText

reStructuredText is the dominant markup language for Darcsforge.

Pygments

Pygments is a Python syntax colorizer used by several parts of Darcsforge.

django-mptt

MPTT provides a standardized way of dealing with tree models in Django, by optimizing for the common case (retrieval queries) with a small expense to the insertion and deletion queries. (This is a near future dependency.)

Additionally, to build this documentation you will need the Sphinx documentation tool.

Django Settings

These are settings for your settings.py that affect operation of Darcsforge applications.

DARCSFORGE_CONTENT_FORMATTER

The Content Formatter is the deep-linker and markup engine for most Darcsforge entities. The encouraged formatter is for reStructuredText, and is a component of darcsforge.deepdish. To use this formatter:

# Darcsforge Markup Setting
from darcsforge.deepdish.formatters import ReStructuredText
DARCSFORGE_CONTENT_FORMATTER = ReStructuredText

INSTALLED_APPS

Most Darcsforge applications contain models. It is suggested to refer to individual application modules for more details on whether to install them or not. Don’t forget to python manage.py syncdb when installing new applications.

SITE_ID

Most Darcsforge applications use references to the django.contrib.sites.Site model and it is suggested that your sites correctly set SITE_ID.

Darcs Defaults

Darcsforge assumes that any repository that it should display has an immutable history and so it is a good idea that for each repository for Darcsforge that you set a good defaults file, with a particular eye towards disabling “dangerous” or history-changing commands. Here is an example _darcs/prefs/defaults file:

apply posthook python patchlog.py
apply run-posthook
amend-record disable
unpull disable
unrecord disable

Darcs Apply Posthook

Darcsforge can gather a lot of data about a repository state from a post-hook connected to darcs apply, which you will probably want to include in the repository’s Darcs Defaults file so that it can happen automatically in response to changes to the repository. The actions you will want to take during the post-hook may depend on the individual Darcsforge applications you wish to support.

A basic example post-hook for Patch Marshalling and patch annotation:

#!/usr/bin/python

# FIXME: Path mangling and django settings setup.

from xml.etree.cElementTree import fromstring
from darcsforge.darcs import DarcsRepository
from darcsforge.deepdish.formatters import DarcsFormatter
from darcsforge.patches.models import Patch
import os

patches = fromstring(os.environ["DARCS_PATCHES_XML"])
hashes = [p.attrib["hash"] for p in patches.findall("patch")]
match = "hash " + " || hash".join(hashes)
darcs = DarcsRepository('.')
df = DarcsFormatter(darcs)
for patch in darcs.changes_match(match):
      p = Patch.objects.marshal(patch)
      df.annotate_patch(p) # create the cached patch annotation
      print p

Note

DARCS_PATCHES_XML is exported by darcs >= 2.0 and ElementTree is provided by python >= 2.5.