diff options
Diffstat (limited to 'docs/source/installation')
| -rw-r--r-- | docs/source/installation/linux.rst | 110 | ||||
| -rw-r--r-- | docs/source/installation/osx.rst | 71 |
2 files changed, 181 insertions, 0 deletions
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*. |