doc/install.txt

   1 *************
   2 Installing BE
   3 *************
   4
   5 Distribution packages
   6 =====================
   7
   8 Some distributions (Debian_ , Ubuntu_ , others?) package BE.  If
   9 you're running one of those distributions, you can install the package
  10 with your regular package manager.  For Debian, Ubuntu, and related
  11 distros, that's::
  12
  13     $ apt-get install bugs-everywhere
  14
  15 However, the official packages can lag behind current development.
  16
  17 If you're running Gentoo_, I've got a live ebuild in my overlay_ that
  18 installs the current version of BE from the Git source.
  19
  20 Michel Alexandre Salim maintains a Fedora_ package.
  21
  22 .. _Debian: http://packages.debian.org/sid/bugs-everywhere
  23 .. _Ubuntu: http://packages.ubuntu.com/lucid/bugs-everywhere
  24 .. _Gentoo: http://www.gentoo.org/
  25 .. _overlay: http://blog.tremily.us/posts/Gentoo_overlay/
  26 .. _Fedora: https://admin.fedoraproject.org/pkgdb/acls/name/be
  27
  28
  29 Dependencies
  30 ============
  31
  32 If your distribution does not package BE, you'll have to install it
  33 yourself, along with its dependencies.  Not all of these are strictly
  34 required.  See `Minimal installs`_ for possible shortcuts.
  35
  36 ==============  =======================  ================  ===========================
  37 Package         Role                     Debian_           Gentoo_
  38 ==============  =======================  ================  ===========================
  39 PyYAML_         serialized data storage  python-yaml       dev-python/pyyaml
  40 Jinja_          HTML templating          python-jinja2     dev-python/jinja
  41 CherryPy_       serve repos over HTTPS   python-cherrypy3  dev-python/cherrypy
  42 Sphinx_         see :doc:`doc`           python-sphinx     dev-python/sphinx
  43 numpydoc_       see :doc:`doc`                             dev-python/numpydoc [#npd]_
  44 Docutils_       manpage generation       python-docutils   dev-python/docutils
  45 ==============  =======================  ================  ===========================
  46
  47 .. [#npd] In the science_ overlay.
  48
  49 .. _PyYAML: http://pyyaml.org/
  50 .. _Jinja: http://jinja.pocoo.org/
  51 .. _CherryPy: http://cherrypy.org/
  52 .. _Sphinx: http://sphinx.pocoo.org/
  53 .. _numpydoc: http://pypi.python.org/pypi/numpydoc
  54 .. _Docutils: http://docutils.sourceforge.net/
  55 .. _science: http://overlays.gentoo.org/proj/science
  56
  57 Git repository
  58 ==============
  59
  60 BE is available as a Git repository::
  61
  62     $ git clone git://gitorious.org/be/be.git be
  63
  64 See the homepage_ for details.  If you do branch the Git repo, you'll
  65 need to run::
  66
  67     $ make
  68
  69 to build some auto-generated files (e.g. :py:mod:`libbe._version`), and::
  70
  71     $ make install
  72
  73 to install BE.  By default BE will install into your home directory,
  74 but you can tweak the ``INSTALL_OPTIONS`` variable in ``Makefile`` to
  75 install to another location.  With the default installation, you may
  76 need to add ``~/.local/bin/`` to your ``PATH`` so that your shell can
  77 find the installed ``be`` script.
  78
  79 Minimal installs
  80 ----------------
  81
  82 By default, ``make`` builds both a man page for ``be`` and the HTML
  83 Sphinx documentation (:doc:`doc`).  You can customize the
  84 documentation targets (if, for example, you don't want to install
  85 Sphinx) by overriding_ the ``DOC`` variable.  For example, to disable
  86 all documentation during a build/install, run::
  87
  88     $ make DOC= install
  89
  90 Note that ``setup.py`` (called during ``make install``) will install
  91 the man page (``doc/man/be.1``) if it exists, so::
  92
  93     $ make
  94     $ make DOC= install
  95
  96 *will* build (first ``make``) and install (second ``make``) the man
  97  page.
  98
  99 Also note that there is no need to edit the ``Makefile`` to change any
 100 of its internal variables.  You can `override them from the command
 101 line`__, as we did for ``DOC`` above.
 102
 103 __ overriding_
 104
 105 Finally, if you want to do the absolute minimum required to install BE
 106 locally, you can skip the ``Makefile`` entirely, and just use
 107 ``setup.py`` directly::
 108
 109     $ python setup.py install
 110
 111 See::
 112
 113     $ python setup.py install --help
 114
 115 for a list of installation options.
 116
 117 You will still need to install PyYAML.  Jinja is only used by the
 118 ``html`` command, so feel free to skip Jinja if you don't mind
 119 avoiding that command.  Similarly, CherryPy is only used for the
 120 ``serve-*`` commands.  The other dependencies are only used for
 121 :doc:`building these docs <doc>`, so feel free to skip them and just
 122 use the docs wherever you're currently reading them.
 123
 124 .. _homepage: http://bugseverywhere.org/
 125 .. _overriding: http://www.gnu.org/software/make/manual/html_node/Overriding.html
 126
 127
 128 Release tarballs
 129 ================
 130
 131 For those not interested in the cutting edge, or those who don't want
 132 to worry about installing Git, we'll `post release tarballs`_
 133 (once we actually make a release).  After you've downloaded the
 134 release tarball, unpack it with::
 135
 136     $ tar -xzvf be-<VERSION>.tar.gz
 137
 138 And install it with:::
 139
 140     $ cd be-<VERSION>
 141     $ make install
 142
 143 .. _post release tarballs: http://download.bugseverywhere.org/releases/