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
============
-============== ======================= ============= ===========================
-Package Role Debian Gentoo
-============== ======================= ============= ===========================
-PyYAML_ serialized data storage python-yaml dev-python/pyyaml
-Sphinx_ see :doc:`doc` python-sphinx dev-python/sphinx
-numpydoc_ see :doc:`doc`
-xsltproc_ see :doc:`doc` xsltproc dev-libs/libxslt
-============== ======================= ============= ===========================
-
-The XSLT stylesheets reqired to generate the manpage are packaged in
-``docbook-xsl-ns`` on Debian [#debian] and
-``app-text/docbook-xsl-ns-stylesheets`` on Gentoo [#gentoo]. For
-futher details on DocBook publishing, see the DocBook wiki pages on
-tools_ and stylesheets_.
+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
-.. _xsltproc: http://www.xmlsoft.org/XSLT/
-.. [#debian] See bugs `490716
- <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=490716>`_
- and `447959
- <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=447959>`_.
-.. [#gentoo] See Diego Elio Pettenò's `blog entry
- <http://blog.flameeyes.eu/2008/09/22/docbook-5-and-gentoo>`_.
-.. _tools: http://wiki.docbook.org/topic/DocBookPublishingTools
-.. _stylesheets: http://wiki.docbook.org/topic/DocBookXslStylesheets
-
+.. _Docutils: http://docutils.sourceforge.net/
+.. _science: http://overlays.gentoo.org/proj/science
Git repository
==============
$ make
-to build some auto-generated files (e.g. :mod:`libbe._version`), and::
+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 ``PREFIX`` variable in ``Makefile`` to install
-to another location.
+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 by overriding_ the ``DOC`` variable. For
-example, to disable all documentation during a build/install, run::
+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
$ make
$ make DOC= install
-*will* build (first ``make``) install (second ``make``) the man page.
+*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#Overriding
+.. _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 somewhere
-(once we actually make a release). After you've downloaded the
-release tarball, unpack it with::
+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
$ cd be-<VERSION>
$ make install
-
-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.
-
-.. _Debian: http://packages.debian.org/sid/bugs-everywhere
-.. _Ubuntu: http://packages.ubuntu.com/lucid/bugs-everywhere
+.. _post release tarballs: http://download.bugseverywhere.org/releases/
projects / be.git / blobdiff