Pyclewn installation notes
==========================

Required
--------

    Python
        Python 2.7 or Python 3.2 or newer.

    Vim
        Vim 7.0 or above with the **netbeans_intg** feature and the
        **autocmd** feature enabled (netbeans and autocmd are enabled on most
        distributions).


Quick start
-----------

A two steps installation.

1) Install the Python package::

        sudo pip install pyclewn

   This command installs the ``clewn`` package and its dependencies.

2) Install the Vim runtime files with a vimball.

   The vimball is part of the ``clewn`` package installed in the first step.
   First create the ``pyclewn-2.2.vmb`` vimball in the current directory
   with the command::

        python -c "import clewn; clewn.get_vimball()"

   Then source the vimball and install the Vim runtime files with::

        vim -S pyclewn-2.2.vmb

   Type ``:quit`` to quit Vim after the vimball is installed.


Installing with pip
-------------------

The preferred method to install pyclewn is pip_, see above. Pip is
automatically installed with Python version 3.4 and newer. It is available on
most linux distributions as a package and otherwise it is easy to install
manually, see pip_.

Pip will also install ``pdb-clone``.

Pip will also install ``trollius`` and its dependencies on Python 2.7 or on
Python versions older than 3.4.

Use a local installation when you do not have root privileges and those are
required to install Python packages::

    pip install --user pyclewn

Note that on Python 2.7, when the *wheel* package is installed (which is the
case in a *virtualenv*), the "Failed to build pyclewn" message output by pip
should be read instead "Failed to build pyclewn wheel" and must be ignored.

The ``pyclewn-2.2.vmb`` vimball is a data file, part of the ``clewn``
package, and can be obtained at any time with::

    python -c "import clewn; clewn.get_vimball()"

The vimball contains the following runtime files::

    autoload/pyclewn/start.vim      # The pyclewn plugin.
    plugin/pyclewn.vim
    autoload/pyclewn/buffers.vim    # Windows management functions.
    doc/pyclewn.txt                 # The help.
    syntax/clewn_variables.vim      # The (clewn)_variables syntax file.
    macros/.pyclewn_keys.gdb        # The 'Cmapkeys' files.
    macros/.pyclewn_keys.pdb
    macros/.pyclewn_keys.simple

See the vimball documentation with the vim command ``:help vimball``.


Installing from source
----------------------

Get the tarball from PyPi_. Unpack the tarball, change directory to the
distribution directory and run the setup script to install pyclewn::

    tar xzf pyclewn-2.2.tar.gz
    cd pyclewn-2.2
    sudo python setup.py install

To use Vim as a front-end to the pdb debugger, pyclewn requires that
``pdb-clone`` be installed separately. So optionally install ``pdb-clone``
from PyPI at pdb-clone_.

When the Python version is 2.7 or older than 3.4, you **must** also install
``trollius`` from PyPI at trollius_.

Use a local installation when you do not have root privileges and those are
required to install Python packages::

    python setup.py install --user

The runtime files must also be installed as described in the first section.
The ``pyclewn-2.2.vmb`` vimball can be found in the ``lib/clewn/runtime``
directory of the tarball.


Installing from the development version at BitBucket
----------------------------------------------------

First install the latest Pyclewn version using one of the methods described
above so that the Pyclewn dependencies (pdb-clone, trollius) are satisfied.
Then clone pyclewn::

    hg clone https://xdegaye@bitbucket.org/xdegaye/pyclewn

Build the source distribution ``dist/pyclewn-2.2.tar.gz`` from the root of
the workarea::

    python setup.py sdist

And install it as root::

    sudo pip install ---ignore-installed --find-links=dist pyclewn==2.2

Or install it locally using the user scheme::

    pip install ---ignore-installed --user --find-links=dist pyclewn==2.2

Finally the Vim run time files **must** be updated after pip has installed
the new version::

    python -c "import clewn; clewn.get_vimball()"
    vim -S pyclewn-2.2.vmb

Once you have installed a development version, do not forget to use the
``--ignore-installed`` option of pip when upgrading later to the latest
release, as pip will not upgrade when the installed version is the same as the
target version.


.. _pip: http://pip.pypa.io/en/latest/
.. _pdb-clone: http://pypi.python.org/pypi/pdb-clone
.. _trollius: http://pypi.python.org/pypi/trollius
.. _PyPi: http://pypi.python.org/pypi/pyclewn
.. vim:filetype=rst:tw=78:ts=8:et:

