diff --git a/INSTALL.asciidoc b/INSTALL.asciidoc index aaff04162..6c50575d4 100644 --- a/INSTALL.asciidoc +++ b/INSTALL.asciidoc @@ -17,6 +17,10 @@ still relatively easy! You can use packages that are built for every release or build it yourself from git. +On Ubuntu 16.04 and 16.10 it's recommended to <> +instead in order to be able to use the new QtWebEngine backend. Newer versions +have a QtWebEngine package in the repositories. + Using the packages ~~~~~~~~~~~~~~~~~~ @@ -26,6 +30,10 @@ Install the dependencies via apt-get: # apt-get install python3-lxml python-tox python3-pyqt5 python3-pyqt5.qtwebkit python3-pyqt5.qtquick python3-sip python3-jinja2 python3-pygments python3-yaml ---- +On Debian Stretch or Ubuntu 17.04 or later, it's also recommended to install +`python3-pyqt5.qtwebengine` and start qutebrowser with `--backend webengine` in +order to use the new backend. + Get the qutebrowser package from the https://github.com/qutebrowser/qutebrowser/releases[release page] and download the https://qutebrowser.org/python3-pypeg2_2.15.2-1_all.deb[PyPEG2 package]. @@ -42,43 +50,14 @@ Build it from git Install the dependencies via apt-get: -[NOTE] -========================== -On Debian, it's recommended to install the Qt packages from the -https://wiki.debian.org/DebianExperimental[experimental] repository as those -are a much newer version of Qt which is more stable. - -Add the following line to your `/etc/apt/sources.list`: - ----- -deb http://ftp.debian.org/debian experimental main ----- - -Then install the packages like this: - ----- -# apt-get update -# apt-get install -t experimental python3-pyqt5 python3-pyqt5.qtwebkit python3-pyqt5.qtquick python3-sip python3-dev -# apt-get install python-tox ----- - -It's also recommended to pin those packages to receive updates by creating a -file `/etc/apt/preferences.d/qutebrowser` with the following contents: - ----- -Package: python3-pyqt5* libqt5* -Pin: release a=experimental -Pin-Priority: 800 ----- -========================== - -For distributions other than Debian or if you prefer to not use the -experimental repo: - ---- # apt-get install python3-pyqt5 python3-pyqt5.qtwebkit python3-pyqt5.qtquick python-tox python3-sip python3-dev ---- +On Debian Stretch or Ubuntu 17.04 or later, it's also recommended to install +`python3-pyqt5.qtwebengine` and start qutebrowser with `--backend webengine` in +order to use the new backend. + To generate the documentation for the `:help` command, when using the git repository (rather than a release): @@ -104,6 +83,9 @@ qutebrowser is available in the official repositories for Fedora 22 and newer. # dnf install qutebrowser ---- +It's also recommended to install `qt5-qtwebengine` and start with `--backend +webengine` to use the new backend. + On Archlinux ------------ @@ -113,6 +95,10 @@ qutebrowser is available in the official [community] repository. # pacman -S qutebrowser ---- +It's also recommended to install `qt5-webkit-ng` or `qt5-webengine` (and start +with `--backend webengine`) to use an up-to-date backend. Note that private +browsing won't work with QtWebKit-NG yet. + There is also a -git version available in the AUR: https://aur.archlinux.org/packages/qutebrowser-git/[qutebrowser-git]. @@ -177,6 +163,11 @@ Make sure you have `python3_4` in your `PYTHON_TARGETS` (`/etc/portage/make.conf`) and rebuild your system (`emerge -uDNav @world`) if necessary. +It's also recommended to install QtWebKit-NG via +https://gist.github.com/annulen/309569fb61e5d64a703c055c1e726f71[this ebuild], +or install Qt >= 5.7.1 with QtWebEngine in order to use an up-to-date backend. +Note that private browsing won't work with QtWebKit-NG yet. + If video or sound don't seem to work, try installing the gstreamer plugins: ---- @@ -194,6 +185,9 @@ with: # xbps-install qutebrowser ---- +It's currently recommended to install `python-PyQt5-webengine` and start with +`--backend webengine` to use the new backend. + On NixOS -------- @@ -204,6 +198,9 @@ it with: $ nix-env -i qutebrowser ---- +It's recommended to install `qt5.qtwebengine` and start with +`--backend webengine` to use the new backend. + On openSUSE ----------- @@ -245,7 +242,7 @@ There are different ways to install qutebrowser on Windows: Prebuilt binaries ~~~~~~~~~~~~~~~~~ -Prebuilt standalone packages and MSI installers +Prebuilt standalone packages and installers https://github.com/qutebrowser/qutebrowser/releases[are built] for every release. @@ -346,17 +343,18 @@ Then run tox inside the qutebrowser repository to set up a https://docs.python.org/3/library/venv.html[virtual environment]: ---- -$ tox -e mkvenv +$ tox -e mkvenv-pypi ---- -On Windows, run tox with the 'mkvenv-win' option, however make sure that ONLY Python3 is in your PATH before running tox. +Alternatively, you can use `tox -e mkvenv` (without `-pypi`) to symlink your +local Qt install instead of installing PyQt in the virtualenv. However, unless +you have QtWebKit-NG or QtWebEngine available, qutebrowser will use the legacy +QtWebKit backend. ----- -$ tox -e mkvenv-win ----- +On Windows, run `tox -e 'mkvenv-win' instead, however make sure that ONLY +Python3 is in your PATH before running tox. -This installs all needed Python dependencies in a `.venv` subfolder. The -system-wide Qt5/PyQt5 installations are symlinked into the virtual environment. +This installs all needed Python dependencies in a `.venv` subfolder. You can then create a simple wrapper script to start qutebrowser somewhere in your `$PATH` (e.g. `/usr/local/bin/qutebrowser` or `~/bin/qutebrowser`): @@ -384,5 +382,5 @@ virtualenv. Thus it's recommended to run the following command to recreate the virtualenv: ---- -$ tox -r -e mkvenv +$ tox -r -e mkvenv-pypi ----