aboutsummaryrefslogtreecommitdiffstats
path: root/doc/install.txt
blob: 2c369fdbe3eb6796354d7de385eeef301cf67906 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
*************
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
``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/