diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/source/installation/linux.rst | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst new file mode 100644 index 0000000..15ec606 --- /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+git://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 priveleges 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. |