.. This file is part of everyapp.bootstrap.
.. Copyright (C) 2010 Krys Lawrence
..
.. everyapp.bootstrap is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by the
.. Free Software Foundation, either version 3 of the License, or (at your
.. option) any later version.
..
.. everyapp.bootstrap is distributed in the hope that it will be useful, but
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
.. more details.
..
.. You should have received a copy of the GNU General Public License along with
.. this program.  If not, see <http://www.gnu.org/licenses/>.

.. _install:
.. _installing_upgrading:

************************
Installing and Upgrading
************************

This |file| describes the requirements, dependencies and steps necessary to
install or upgrade *everyapp.bootstrap*.

.. index:: requirements, installation; requirements, upgrading; requirements
.. _requirements:

Requirements
============

*everyapp.bootstrap* requires the follow pre-requisites in order to function:

* A |POSIX| (Linux, Mac OS X) or Windows system
* Python ≥ 2.4, < 3.0, or maybe Python 2.3 and the sub-process module

Development systems have the following additional requirements:

* Mercurial_ to clone the source code repository
* unix2dos_ on |POSIX| systems to ensure consistent line endings
* Latex_ for |PDF| documentation generation (optional)

.. index:: dependencies, installation; dependencies, upgrading; dependencies
.. dependencies:

Dependencies
============

*everyapp.bootstrap* only depends on distribute_ and virtualenv_.  They will be
installed automatically.

.. index::
   single: versioning
   single: installation; versioning
   single: upgrading; versioning
   single: release; versioning
.. _about_versioning:

About Versioning
================

This project adheres to the principals of the `Semantic Versioning`_
specification.  This means, among other things, that *everyapp.bootstrap* will
be a well-behaved dependency and that increments in the version's patch number
(the third number in the version) should never break |API| compatibility.

.. SEEALSO:: The `Semantic Versioning <http://semver.org/>`_ specification for
   more information.

.. index:: installation
.. _installation:

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

Installing *everyapp.bootstrap* is easy, but there are a few ways to do it.
Just follow the instructions in one of the sections below:

.. index::
   pair: installation; pip

Installing With pip
-------------------

To install using pip_, run::

  pip install everyapp.bootstrap

.. index::
   pair: installation; easy_install

Installing With easy_install
----------------------------

To install using easy_install_ (i.e. from distribute_ or setuptools_), run::

  easy_install everyapp.bootstrap

.. WARNING:: Currently, if you use setuptools_, distribute_ will be installed
   automatically, replacing your setuptools.  If this is unacceptable, using
   virtualenv_ to isolate the installation is recommended.  This behaviour
   might be changed in a future release.

.. index::
   pair: installation; archive

Installing From Archive
-----------------------

To install *everyapp.bootstrap* the old-fashioned way, download the tarball
from `everyapp.bootstrap on PyPI
<http://pypi.python.org/pypi/everyapp.bootstrap#downloads>`_ and then run::

  tar -zxf everyapp.bootstrap-X.Y.Z.tar.gz
  cd everyapp.bootstrap
  python setup.py install

.. NOTE:: On Windows you can extract the archive using an appropriate archive
   tool like `7-Zip`_, WinZip_, or a `Windows version`_ of the tar_ utility.

.. index::
   pair: installation; mercurial

Installing From Mercurial
-------------------------

To install the latest development version from the Mercurial_ repository, run::

  hg clone https://bitbucket.org/everyapp/bootstrap everyapp.bootstrap
  cd everyapp.bootstrap
  python setup.py install

.. SEEALSO:: |HACKING.txt| for additional information on developing/hacking on
   the development version.

.. index:: upgrading
.. _upgrading:

Upgrading
=========

Upgrading *everyapp.bootstrap* works very similarly to installing it.  Here are
some general instructions for performing the upgrade:

.. index::
    pair: upgrading; pip
    pair: upgrading; easy_install

Upgrading With pip or easy_install
----------------------------------

Upgrading works just like installing (see above), just add the ``-U`` option
before the distribution name.  E.g.::

  pip install -U everyapp.bootstrap

or::

  easy_install -U everyapp.bootstrap

.. index:: pair: upgrading; archive

Upgrading From Archive
----------------------

Upgrading from the distribution archive works exactly like installing from the
archive.  Just download the archive of the newer version and follow the
installation instruction above.

.. index::
   pair: upgrading; mercurial

Upgrading From Mercurial
------------------------

If you do not already have a clone of the Mercurial_ repository, then just
follow the installation instructions above to perform the upgrade.

If you do already have the repository cloned or kept the one from the original
installation, then run the following commands instead::

  cd everyapp.bootstrap
  hg pull -u
  python setup.py install

.. index::
   pair: upgrading; final steps

Final Steps
-----------

.. NOTE:: Once you have finished the upgrade, do not forget to regenerate
   your |bootstrap.py| script in your project.  See |USAGE.txt| for details.

.. WARNING:: The instructions above are the bare minimum necessary to perform
   an upgrade.  Be sure to all review the changes in |NEWS.txt| for any
   additional adjustments you may need to perform.
