Installation
============

.. sectionauthor:: Max Battcher <me@worldmaker.net>

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

Dependencies
------------

.. seealso::

  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 :file:`settings.py` that affect operation of 
Darcsforge applications.

.. highlight:: python
.. data:: 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 :mod:`darcsforge.deepdish`.  To use this formatter::

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

.. data:: 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.

.. data:: SITE_ID

Most Darcsforge applications use references to the 
:class:`django.contrib.sites.Site` model and it is suggested that your sites 
correctly set :data:`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 :ref:`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.

.. _Python: http://www.python.org/
.. _Django: http://www.django-project.org/
.. _reStructuredText: http://docutils.sf.net/
.. _Pygments: http://pygments.pocoo.org/
.. _django-mptt: http://django-mptt.googlecode.com/
.. _Sphinx: http://sphinx.pocoo.org/

.. vim: ai spell tw=72