*************
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 https://gitlab.com/bugseverywhere/bugseverywhere.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
``html`` and ``serve-*`` commands with the ``--ssl`` option set. 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`_. 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/
