diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/source/installation.rst | 131 | ||||
| -rw-r--r-- | docs/source/installation/linux.rst | 110 | ||||
| -rw-r--r-- | docs/source/installation/osx.rst | 71 |
3 files changed, 312 insertions, 0 deletions
diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..8dc4236 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,131 @@ +************ +Installation +************ + +Generic requirements +==================== + +* Python 2.6 or later, 3.2 or later, PyPy 2.0 or later, PyPy3 2.3 or later. It + is the only non-optional requirement. + + .. warning: + It is highly advised to use UCS-4 version of Python because UCS-2 version + uses significantly slower text processing (length determination and + non-printable character replacement) functions due to the need of + supporting unicode characters above U+FFFF which are represented as + surrogate pairs. This price will be paid even if configuration has no such + characters. + +* C compiler. Required to build powerline client on linux. If it is not present + then powerline will fall back to shell script or python client. +* ``socat`` program. Required for shell variant of client which runs a bit + faster than python version of the client, but still slower than C version. +* ``psutil`` python package. Required for some segments like cpu_percent. Some + segments have linux-only fallbacks for ``psutil`` functionality. +* ``hglib`` python package *and* mercurial executable. Required to work with + mercurial repositories. +* ``pygit2`` python package or ``git`` executable. Required to work with ``git`` + repositories. +* ``bzr`` python package (note: *not* standalone executable). Required to work + with bazaar repositories. +* ``pyuv`` python package. Required for :ref:`libuv-based watcher + <config-common-watcher>` to work. +* ``i3ipc`` python package. Required for i3wm bindings and segments. +* ``xrandr`` program. Required for the multi-monitor lemonbar binding and the + :py:func:`powerline.listers.i3wm.output_lister`. + +.. note:: + Until bazaar supports Python-3 or PyPy powerline will not support + repository information when running in these interpreters. + +.. _repository-root: + +.. note:: + When using ``pip``, the ``{repository_root}`` directory referenced in + documentation may be found using ``pip show powerline-status``. In the output + of ``pip show`` there is a line like ``Location: {path}``, that ``{path}`` is + ``{repository_root}``. Unless it is ``--editable`` installation this is only + applicable for ``{repository_root}/powerline/…`` paths: something like + ``{repository_root}/scripts/powerline-render`` is not present. + + When using other packages referenced paths may not exist, in this case refer + to package documentation. + +Pip installation +================ + +Due to a naming conflict with an unrelated project, powerline is available on +PyPI under the ``powerline-status`` name: + +.. code-block:: sh + + pip install powerline-status + +is the preferred method because this will get the latest release. To get current +development version + +.. code-block:: sh + + pip install --user git+https://github.com/powerline/powerline + +may be used. If powerline was already checked out into some directory + +.. code-block:: sh + + pip install --user --editable={path_to_powerline} + +is useful, but note that in this case ``pip`` will not install ``powerline`` +executable and something like + +.. code-block:: sh + + ln -s {path_to_powerline}/scripts/powerline ~/.local/bin + +will have to be done (:file:`~/.local/bin` should be replaced with some path +present in ``$PATH``). + +.. note:: + We can use either ``https``(``git+ssh://git@github.com/powerline/powerline``) + or ``https``(``git+https://github.com/powerline/powerline``) protocols. + ``git`` protocol is deprecated by Github. + +Fonts installation +================== + +Powerline uses several special glyphs to get the arrow effect and some custom +symbols for developers. This requires having either a symbol font or a patched +font installed in the system. The used application (e.g. terminal emulator) must +also either be configured to use patched fonts (in some cases even support it +because custom glyphs live in private use area which some applications reserve +for themselves) or support fontconfig for powerline to work properly with +powerline-specific glyphs. + +:ref:`24-bit color support <config-common-term_truecolor>` may be enabled if +used terminal emulator supports it (see :ref:`the terminal emulator support +matrix <usage-terminal-emulators>`). + +There are basically two ways to get powerline glyphs displayed: use +:file:`PowerlineSymbols.otf` font as a fallback for one of the existing fonts or +install a patched font. + +.. _installation-patched-fonts: + +Patched fonts +------------- + +This method is the fallback method and works for every terminal. + +Download the font from `powerline-fonts`_. If preferred font can’t be found in +the `powerline-fonts`_ repo, then patching the preferred font is needed instead. + +.. _powerline-fonts: https://github.com/powerline/fonts + +After downloading this font refer to platform-specific instructions. + +Installation on various platforms +================================= + +.. toctree:: + + Linux <installation/linux> + OS X <installation/osx> diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst new file mode 100644 index 0000000..e134707 --- /dev/null +++ b/docs/source/installation/linux.rst @@ -0,0 +1,110 @@ +********************* +Installation on Linux +********************* + +The following distribution-specific packages are officially supported, and they +provide an easy way of installing and upgrading Powerline. The packages will +automatically do most of the configuration. + +* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_ +* `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_ +* Gentoo Live ebuild in `raiagent <https://github.com/leycec/raiagent>`_ overlay +* Powerline package is available for Debian starting from Wheezy (via `backports + <https://packages.debian.org/wheezy-backports/powerline>`_). Use `search + <https://packages.debian.org/search?keywords=powerline&searchon=names&suite=all§ion=all>`_ + to get more information. + +If used distribution does not have an official package installation guide below +should be followed: + +1. Install Python 3.2+, Python 2.6+ or PyPy and ``pip`` with ``setuptools``. + This step is distribution-specific, so no commands provided. +2. Install Powerline using one of the following commands: + + .. code-block:: sh + + pip install --user powerline-status + + will get the latest release version and + + .. code-block:: sh + + pip install --user git+https://github.com/powerline/powerline + + will get the latest development version. + + .. note:: Due to the naming conflict with an unrelated project powerline is + named ``powerline-status`` in PyPI. + + .. note:: + Powerline developers should be aware that``pip install --editable`` does + not currently fully work. Installation performed this way are missing + ``powerline`` executable that needs to be symlinked. It will be located in + ``scripts/powerline``. + +Fonts installation +================== + +Fontconfig +---------- + +This method only works on Linux. It’s the second recommended method if terminal +emulator supports it as patching fonts is not needed, and it generally works +with any coding font. + +#. Download the latest version of the symbol font and fontconfig file:: + + wget https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf + wget https://github.com/powerline/powerline/raw/develop/font/10-powerline-symbols.conf + +#. Move the symbol font to a valid X font path. Valid font paths can be + listed with ``xset q``:: + + mv PowerlineSymbols.otf ~/.local/share/fonts/ + +#. Update font cache for the path the font was moved to (root privileges may be + needed to update cache for the system-wide paths):: + + fc-cache -vf ~/.local/share/fonts/ + +#. Install the fontconfig file. For newer versions of fontconfig the config + path is ``~/.config/fontconfig/conf.d/``, for older versions it’s + ``~/.fonts.conf.d/``:: + + mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/ + +If custom symbols still cannot be seen then try closing all instances of the +terminal emulator. Restarting X may be needed for the changes to take effect. + +If custom symbols *still* can’t be seen, double-check that the font have been +installed to a valid X font path, and that the fontconfig file was installed to +a valid fontconfig path. Alternatively try to install a :ref:`patched font +<installation-patched-fonts>`. + +Patched font installation +------------------------- + +This is the preferred method, but it is not always available because not all +fonts were patched and not all fonts *can* be patched due to licensing issues. + +After downloading font the following should be done: + +#. Move the patched font to a valid X font path. Valid font paths can be + listed with ``xset q``:: + + mv 'SomeFont for Powerline.otf' ~/.local/share/fonts/ + +#. Update font cache for the path the font was moved to (root privileges may be + needed for updating font cache for some paths):: + + fc-cache -vf ~/.local/share/fonts/ + +After installing patched font terminal emulator, GVim or whatever application +powerline should work with must be configured to use the patched font. The +correct font usually ends with *for Powerline*. + +If custom symbols cannot be seen then try closing all instances of the terminal +emulator. X server may need to be restarted for the changes to take effect. + +If custom symbols *still* can’t be seen then double-check that the font have +been installed to a valid X font path. diff --git a/docs/source/installation/osx.rst b/docs/source/installation/osx.rst new file mode 100644 index 0000000..1d6fafc --- /dev/null +++ b/docs/source/installation/osx.rst @@ -0,0 +1,71 @@ +******************** +Installation on OS X +******************** + +Python package +============== + +1. Install a proper Python version (see `issue #39 + <https://github.com/powerline/powerline/issues/39>`_ for a discussion + regarding the required Python version on OS X):: + + sudo port select python python27-apple + + Homebrew may be used here:: + + brew install python + + .. note:: + There are three variants of the powerline client. The fastest is + written in C and will be compiled if the compiler and libraries are + detected during installation. The second fastest option is + :file:`powerline.sh` which requires ``socat`` and ``coreutils``. + ``coreutils`` may be installed using ``brew install + coreutils``. If neither of these are viable, then Powerline will + utilize a fallback client written in Python. + +2. Install Powerline using one of the following commands: + + .. code-block:: sh + + pip install --user powerline-status + + will get current release version and + + .. code-block:: sh + + pip install --user git+https://github.com/powerline/powerline + + will get latest development version. + + .. warning:: + When using ``brew install`` to install Python one must not supply + ``--user`` flag to ``pip``. + + .. note:: + Due to the naming conflict with an unrelated project powerline is named + ``powerline-status`` in PyPI. + + .. note:: + Powerline developers should be aware that ``pip install --editable`` does + not currently fully work. Installation performed this way are missing + ``powerline`` executable that needs to be symlinked. It will be located in + ``scripts/powerline``. + +Vim installation +================ + +Any terminal vim version with Python 3.2+ or Python 2.6+ support should work, +but MacVim users need to install it using the following command:: + + brew install macvim --env-std --with-override-system-vim + +Fonts installation +================== + +To install patched font double-click the font file in Finder, then click +:guilabel:`Install this font` in the preview window. + +After installing the patched font MacVim or terminal emulator (whatever +application powerline should work with) need to be configured to use the patched +font. The correct font usually ends with *for Powerline*. |