.. _topics-install:

===========================================
How to install Softwarefabrica Django Utils
===========================================

.. admonition:: About this document

   This document describes how to install Softwarefabrica Django Utils and use it
   in your Django applications.

.. contents::
   :depth: 3

.. _pre-requisites:

Pre-requisites
==============

This library depends on `sflib`_ from the same author.
If you use EasyInstall_, as outlined below, dependencies will be satisfied
automatically (the ``easy_install`` command will take care of everything).

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _`softwarefabrica.django.utils`: http://pypi.python.org/pypi/softwarefabrica.django.utils
.. _`softwarefabrica.django.forms`: http://pypi.python.org/pypi/softwarefabrica.django.forms
.. _`softwarefabrica.django.crud`: http://pypi.python.org/pypi/softwarefabrica.django.crud
.. _`sflib`: http://pypi.python.org/pypi/sflib

.. _installing-official-release:

Installing an official release
==============================

Official releases are made available from PyPI_

http://pypi.python.org/pypi/softwarefabrica.django.utils

Binary distribution
-------------------

If you have EasyInstall_ available, you can download and install the most
up-to-date version in one step. For example, on a unix-like system:

::

  $ su
  # easy_install softwarefabrica.django.utils

If you are using Ubuntu, to install system-wide:

::

  $ sudo easy_install softwarefabrica.django.utils

Otherwise, if EasyInstall_ is not available, you can just download (eg. from
PyPI_) the right `distribution`_ for your platform and Python version , extract
it and run the usual ``setup.py`` commands:

::

  $ su
  # python setup.py install

These commands will install the software in your Python installation's
``site-packages`` directory.

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _PyPI: http://pypi.python.org/pypi
.. _`distribution`: http://pypi.python.org/pypi/softwarefabrica.django.utils

Source distribution
-------------------

If you have EasyInstall_ available, you can download and extract the most
up-to-date source distribution in one step. For example, on a unix-like system:

::

  easy_install --editable --build-directory ~/projects softwarefabrica.django.utils

Then from the ``softwarefabrica.django.utils`` directory you can run the
``setup.py develop`` command to install the library in your Python
`site-packages` directory using a link, which allows to continue developing
inside the working tree without the need to re-install after every change. See
the `setuptools development mode`_ documention for more information::

    $ python setup.py build
    $ sudo
    # python setup.py develop

Otherwise, if EasyInstall_ is not available, you can just download the `source
distribution`_ (eg. from PyPI_), extract it and run the usual ``setup.py`` commands:

::

  $ su
  # python setup.py install

This command will install the software in your Python installation's
``site-packages`` directory.

.. _EasyInstall: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _PyPI: http://pypi.python.org/pypi
.. _`source distribution`: http://pypi.python.org/pypi/softwarefabrica.django.utils
.. _`setuptools development mode`: http://peak.telecommunity.com/DevCenter/setuptools#development-mode


Windows installer
-----------------

A Windows installer will be made available in a next release.

.. _installing-development-version:

Installing the development version
==================================

Alternatively, if you'd like to update the software occasionally to pick
up the latest bug fixes and enhancements before they make it into an
offical release, branch from the `Bazaar`_ repository hosted on `LaunchPad`_
instead.
Just follow the procedure outlined below:

1. Make sure that you have `Bazaar`_ installed, and that you can run its
   commands from a shell. (Enter ``bzr help`` at a shell prompt to test
   this.)

2. Create a local branch and working tree from the official one::

    bzr branch lp:sf-django-utils sf-utils

3. Then from the ``sf-utils`` directory you can run the ``setup.py develop``
   command to install the library in your Python `site-packages` directory
   using a link, which allows to continue developing inside the working tree
   without the need to re-install after every change. See the
   `setuptools development mode`_ documention for more information::

    $ sudo
    # python setup.py develop

4. You can verify that the application is available on your `PYTHONPATH`_ by
   opening a Python interpreter and entering the following commands::

    >>> from softwarefabrica.django.utils import version
    >>> version.VERSION
    (1, 0, 'dev')
    >>> version.get_version()
    u'1.0-dev-BZR-rXX-panta@elasticworld.org-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

When you want to update your copy of the library source code, run the command
``bzr pull`` from within the ``sf-utils`` directory::

    bzr pull
    sudo python setup.py develop

(you need to re-run the ``setup.py develop`` command after every working tree
update, to update version numbers in script wrappers).

.. caution::

   The development version may contain bugs which are not present in the
   release version and introduce backwards-incompatible changes.

   If you're tracking trunk, keep an eye on the `changes`_ before you update
   your copy of the source code.

.. _`development home page`: https://launchpad.net/sf-django-utils
.. _`bugs`: https://bugs.launchpad.net/sf-django-utils
.. _`LaunchPad`: http://launchpad.net
.. _`Bazaar`: http://bazaar-vcs.org/
.. _`changes`: http://bazaar.launchpad.net/~softwarefabrica/sf-django-utils/trunk/changes
.. _`PYTHONPATH`: http://docs.python.org/tut/node8.html#SECTION008110000000000000000
.. _`junction`: http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx
.. _`setuptools development mode`: http://peak.telecommunity.com/DevCenter/setuptools#development-mode

Using the app in your projects
==============================

Once you've installed the library and want to use it in your Django
projects:

1. put ``'softwarefabrica.django.utils'`` in your ``INSTALLED_APPS`` setting::

    INSTALLED_APPS = (
        ...
        'softwarefabrica.django.utils',
    )

2. make sure that you have
   ``'django.template.loaders.app_directories.load_template_source'`` in your
   ``TEMPLATE_LOADERS`` setting.

3. add ``'softwarefabrica.django.utils.viewshelpers.context_vars'`` to your
   ``TEMPLATE_CONTEXT_PROCESSORS`` setting. Typically it should be::

    TEMPLATE_CONTEXT_PROCESSORS = (
        'django.core.context_processors.auth',
        'django.core.context_processors.debug',
        'django.core.context_processors.i18n',
        'django.core.context_processors.media',
        'django.core.context_processors.request',
        'softwarefabrica.django.utils.viewshelpers.context_vars',
    )

Since there are no associated models, a ``manage.py syncdb`` command is not
necessary.

That's it!
