*************
Installing BE
*************

Distribution packages
=====================

Some distributions (Debian_ , Ubuntu_ , others?) package BE.  If
you're running one of those distributions, you can install the package
with your regular package manager.  For Debian, Ubuntu, and related
distros, that's::

    $ apt-get install bugs-everywhere

However, the official packages can lag behind current development.

If you're running Gentoo_, I've got a live ebuild in my overlay_ that
installs the current version of BE from the Git source.

Michel Alexandre Salim maintains a Fedora_ package.

.. _Debian: http://packages.debian.org/sid/bugs-everywhere
.. _Ubuntu: http://packages.ubuntu.com/lucid/bugs-everywhere
.. _Gentoo: http://www.gentoo.org/
.. _overlay: http://blog.tremily.us/posts/Gentoo_overlay/
.. _Fedora: https://admin.fedoraproject.org/pkgdb/acls/name/be


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

If your distribution does not package BE, you'll have to install it
yourself, along with its dependencies.  Not all of these are strictly
required.  See `Minimal installs`_ for possible shortcuts.

==============  =======================  ================  ===========================
Package         Role                     Debian_           Gentoo_
==============  =======================  ================  ===========================
PyYAML_         upgrade old BE storage   python-yaml       dev-python/pyyaml
Jinja_          HTML templating          python-jinja2     dev-python/jinja
CherryPy_       serve repos over HTTPS   python-cherrypy3  dev-python/cherrypy
Sphinx_         see :doc:`doc`           python-sphinx     dev-python/sphinx
numpydoc_       see :doc:`doc`                             dev-python/numpydoc [#npd]_
Docutils_       manpage generation       python-docutils   dev-python/docutils
==============  =======================  ================  ===========================

.. [#npd] In the science_ overlay.

.. Debian has a stale ITP for python-numpydoc http://bugs.debian.org/631877
   which caused BE to be dropped  http://bugs.debian.org/609519

.. _PyYAML: http://pyyaml.org/
.. _Jinja: http://jinja.pocoo.org/
.. _CherryPy: http://cherrypy.org/
.. _Sphinx: http://sphinx.pocoo.org/
.. _numpydoc: http://pypi.python.org/pypi/numpydoc
.. _Docutils: http://docutils.sourceforge.net/
.. _science: http://overlays.gentoo.org/proj/science

Git repository
==============

BE is available as a Git repository::

    $ git clone git://gitorious.org/be/be.git be

See the homepage_ for details.  If you do branch the Git repo, you'll
need to run::

    $ make

to build some auto-generated files (e.g. :py:mod:`libbe._version`), and::

    $ make install

to install BE.  By default BE will install into your home directory,
but you can tweak the ``INSTALL_OPTIONS`` variable in ``Makefile`` to
install to another location.  With the default installation, you may
need to add ``~/.local/bin/`` to your ``PATH`` so that your shell can
find the installed ``be`` script.

Minimal installs
----------------

By default, ``make`` builds both a man page for ``be`` and the HTML
Sphinx documentation (:doc:`doc`).  You can customize the
documentation targets (if, for example, you don't want to install
Sphinx) by overriding_ the ``DOC`` variable.  For example, to disable
all documentation during a build/install, run::

    $ make DOC= install

Note that ``setup.py`` (called during ``make install``) will install
the man page (``doc/man/be.1``) if it exists, so::

    $ make
    $ make DOC= install

*will* build (first ``make``) and install (second ``make``) the man
page.

Also note that there is no need to edit the ``Makefile`` to change any
of its internal variables.  You can `override them from the command
line`__, as we did for ``DOC`` above.

__ overriding_

Finally, if you want to do the absolute minimum required to install BE
locally, you can skip the ``Makefile`` entirely, and just use
``setup.py`` directly::

    $ python setup.py install

See::

    $ python setup.py install --help

for a list of installation options.

You only need YAML support if you will be upgrading a BE repository
based on ``Bugs Everywhere Directory v1.4`` or earlier (see
:file:`.be/version`).  If you're installing a fresh instance of BE,
there's no need to install PyYAML.  Jinja is only used by the ``html``
command, so there's no need to install Jinja if you don't mind
avoiding that command.  Similarly, CherryPy is only used for the
``serve-*`` commands.  The other dependencies are only used for
:doc:`building these docs <doc>`, so feel free to skip them and just
use the docs wherever you're currently reading them.

.. _homepage: http://bugseverywhere.org/
.. _overriding: http://www.gnu.org/software/make/manual/html_node/Overriding.html


Release tarballs
================

For those not interested in the cutting edge, or those who don't want
to worry about installing Git, we'll `post release tarballs`_
(once we actually make a release).  After you've downloaded the
release tarball, unpack it with::

    $ tar -xzvf be-<VERSION>.tar.gz

And install it with:::

    $ cd be-<VERSION>
    $ make install

.. _post release tarballs: http://download.bugseverywhere.org/releases/