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 .. Debian has a stale ITP for python-numpydoc http://bugs.debian.org/631877
  50    which caused BE to be dropped  http://bugs.debian.org/609519
  51
  52 .. _PyYAML: http://pyyaml.org/
  53 .. _Jinja: http://jinja.pocoo.org/
  54 .. _CherryPy: http://cherrypy.org/
  55 .. _Sphinx: http://sphinx.pocoo.org/
  56 .. _numpydoc: http://pypi.python.org/pypi/numpydoc
  57 .. _Docutils: http://docutils.sourceforge.net/
  58 .. _science: http://overlays.gentoo.org/proj/science
  59
  60 Git repository
  61 ==============
  62
  63 BE is available as a Git repository::
  64
  65     $ git clone git://gitorious.org/be/be.git be
  66
  67 See the homepage_ for details.  If you do branch the Git repo, you'll
  68 need to run::
  69
  70     $ make
  71
  72 to build some auto-generated files (e.g. :py:mod:`libbe._version`), and::
  73
  74     $ make install
  75
  76 to install BE.  By default BE will install into your home directory,
  77 but you can tweak the ``INSTALL_OPTIONS`` variable in ``Makefile`` to
  78 install to another location.  With the default installation, you may
  79 need to add ``~/.local/bin/`` to your ``PATH`` so that your shell can
  80 find the installed ``be`` script.
  81
  82 Minimal installs
  83 ----------------
  84
  85 By default, ``make`` builds both a man page for ``be`` and the HTML
  86 Sphinx documentation (:doc:`doc`).  You can customize the
  87 documentation targets (if, for example, you don't want to install
  88 Sphinx) by overriding_ the ``DOC`` variable.  For example, to disable
  89 all documentation during a build/install, run::
  90
  91     $ make DOC= install
  92
  93 Note that ``setup.py`` (called during ``make install``) will install
  94 the man page (``doc/man/be.1``) if it exists, so::
  95
  96     $ make
  97     $ make DOC= install
  98
  99 *will* build (first ``make``) and install (second ``make``) the man
 100  page.
 101
 102 Also note that there is no need to edit the ``Makefile`` to change any
 103 of its internal variables.  You can `override them from the command
 104 line`__, as we did for ``DOC`` above.
 105
 106 __ overriding_
 107
 108 Finally, if you want to do the absolute minimum required to install BE
 109 locally, you can skip the ``Makefile`` entirely, and just use
 110 ``setup.py`` directly::
 111
 112     $ python setup.py install
 113
 114 See::
 115
 116     $ python setup.py install --help
 117
 118 for a list of installation options.
 119
 120 You will still need to install PyYAML.  Jinja is only used by the
 121 ``html`` command, so feel free to skip Jinja if you don't mind
 122 avoiding that command.  Similarly, CherryPy is only used for the
 123 ``serve-*`` commands.  The other dependencies are only used for
 124 :doc:`building these docs <doc>`, so feel free to skip them and just
 125 use the docs wherever you're currently reading them.
 126
 127 .. _homepage: http://bugseverywhere.org/
 128 .. _overriding: http://www.gnu.org/software/make/manual/html_node/Overriding.html
 129
 130
 131 Release tarballs
 132 ================
 133
 134 For those not interested in the cutting edge, or those who don't want
 135 to worry about installing Git, we'll `post release tarballs`_
 136 (once we actually make a release).  After you've downloaded the
 137 release tarball, unpack it with::
 138
 139     $ tar -xzvf be-<VERSION>.tar.gz
 140
 141 And install it with:::
 142
 143     $ cd be-<VERSION>
 144     $ make install
 145
 146 .. _post release tarballs: http://download.bugseverywhere.org/releases/