changeset 3990:3b72743b92db

doc[installation]: update instructions
author Goffi <goffi@goffi.org>
date Thu, 24 Nov 2022 12:25:07 +0100
parents f5ba7594cced
children cd0943ceb326
files doc/conf.py doc/installation.rst
diffstat 2 files changed, 68 insertions(+), 17 deletions(-) [+]
line wrap: on
line diff
--- a/doc/conf.py	Thu Nov 24 12:25:04 2022 +0100
+++ b/doc/conf.py	Thu Nov 24 12:25:07 2022 +0100
@@ -90,7 +90,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
--- a/doc/installation.rst	Thu Nov 24 12:25:04 2022 +0100
+++ b/doc/installation.rst	Thu Nov 24 12:25:07 2022 +0100
@@ -4,18 +4,18 @@
 Installation
 ============
 
-This are the instructions to install Libervia using Python.
+These are the instructions to install Libervia using Python.
 Note that if you are using GNU/Linux, Libervia may already be present on your distribution.
 
 Libervia is made of one backend, and several frontends. To use it, the first thing to do is to install the backend.
 
-We recommand to use development version for now, until the release of 0.8.
+We recommand to use development version for now, until the release of 0.9.
 
 Development version
 -------------------
 
 *Note for Arch users: a pkgbuild is available for your distribution on
-AUR, check sat-xmpp-hg (as well as other sat-\* packages).*
+AUR, check libervia-backend-hg (as well as other libervia-\* packages).*
 
 You can install the latest development version using pip. You need to
 have the following dependencies installed first:
@@ -32,20 +32,36 @@
 -  libxlt2 with development headers
 -  D-Bus x11 tools (this doesn't needs X11, it is just needed for dbus-launch)
 -  cmake
+-  Python GPG package (and its GPG dependencies), those are needed to use all OpenPGP
+   related features. We need to use the system package as package version needs to match
+   system GPG version.
 
 On Debian and derivatives, you can get all this with following command::
 
-  $ sudo apt-get install python3-dev python3-venv python3-wheel mercurial libxml2-dev libxslt-dev libcairo2-dev libjpeg-dev libgirepository1.0-dev libdbus-1-dev libdbus-glib-1-dev dbus-x11 cmake
+  $ sudo apt-get install python3-dev python3-venv python3-wheel mercurial libxml2-dev libxslt-dev libcairo2-dev libjpeg-dev libgirepository1.0-dev libdbus-1-dev libdbus-glib-1-dev dbus-x11 cmake python3-gpg
+
+Installation With pipx
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you have `pipx`_ installed, you can install the dev version of the backend by simply
+entering::
 
-Now go in a location where you can install Libervia, for
-instance your home directory::
+  $ pipx install --system-site-packages hg+https://repos.goffi.org/libervia-backend#egg=libervia-backend[SVG]
+
+Installation With Virtual Environment And pip
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively, you can install a virtual environment, clone the repository, and pip
+install from there.
+
+Go in a location where you can install Libervia, for instance your home directory::
 
   $ cd
 
 And enter the following commands (here we install Libervia with SVG support, which is needed to
 display SVG avatars on some frontends)::
 
-  $ python3 -m venv libervia
+  $ python3 -m venv --system-site-packages libervia
   $ source libervia/bin/activate
   $ pip install -U pip wheel
   $ hg clone https://repos.goffi.org/libervia-backend
@@ -54,9 +70,13 @@
 
 Don't worry if you see the following message, Libervia should work anyway::
 
-  Failed building wheel for pygobject
+  Failed building wheel for <some_package_name>
 
-After installing Libervia, you need to install the media::
+Post Installation
+~~~~~~~~~~~~~~~~~
+
+After installing Libervia, you need to install the media (you may skip this if you don't
+plan to use any graphical frontend)::
 
   $ cd
   $ hg clone https://repos.goffi.org/libervia-media
@@ -96,7 +116,7 @@
   $ libervia-backend status
 
 **NOTE**: if ``misc/org.libervia.Libervia.service`` is installed correctly (which should
-be done by during the installation), the backend is automatically launched when a frontend
+be done during the installation), the backend is automatically launched when a frontend
 needs it.
 
 You can check that Libervia is installed correctly by trying jp (the backend need to be
@@ -111,13 +131,42 @@
 
 .. note::
 
-  if you have the message ``/!\ D-Bus is not launched, please see README to see
-  instructions on how to launch it`` that mean that the D-Bus service is not launched, this
-  usually happens when launching Libervia on a server, without graphic interface like X.org or
-  Wayland (in which case D-Bus service should be launcher automatically).
+  You may see an error message indicating that D-Bus is not launched or that its
+  environment variable is not set, this usually happens when launching Libervia on a
+  server, without graphic interface like X.org or Wayland (otherwise D-Bus service should
+  be launched automatically). In this case please follow instructions below.
+
+Launching D-Bus (on servers)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  You can launch the D-Bus service by creating a shell script with the following content
+  in a file named ``dbus_launch.sh``:
+
+  .. sourcecode:: sh
+
+    #!/bin/sh
+
+    DBUS_PATH="/tmp/.dbus.`whoami`"
 
-  As the message states, instructions on how to launch the service are given in the README
-  file of Libervia.
+    if [ ! -e $DBUS_PATH ]; then
+            dbus-launch --sh-syntax > $DBUS_PATH
+            chmod 400 $DBUS_PATH
+    fi
+
+    cat $DBUS_PATH
+
+  Then run it before the backend or frontend by entering::
+
+    $ eval $(/path/to/dbus_launch.sh)
+
+  This will launch the D-Bus daemon if necessary, and set the appropriate environment
+  variable. If you use a new shell, be sure to launch the script again in an ``eval``
+  statement to have the environment variable set. You can put this in your ``.zshrc`` (or
+  whatever you're using) to make it automatic.
+
+  If you don't want to use D-Bus, you can use another bridge, e.g. ``pb`` is a good
+  choice, by updating your :ref:`configuration` ``[DEFAULT]`` section with ``bridge =
+  pb``.
 
 Frontends
 =========
@@ -157,3 +206,5 @@
 
 Sententia
   Emacs frontend developed by a third party (development is currently stalled)
+
+.. _pipx: https://pypa.github.io/pipx/