doc (installation): Update instructions:
- Instructions have been checked and updated. OS packages dependencies have been added for Arch Linux. - Added missing package. - Reordered/refreshed instructions. - Old/not relevant content has been removed. - Tested on latest docker images of Debian/Arch/Unbutu. rel 466
This commit is contained in:
Goffi
parent
8c35f015f1
commit
c1cb70ac1a
1 changed files with 124 additions and 116 deletions
|
|
@ -4,209 +4,217 @@
|
|||
Installation
|
||||
============
|
||||
|
||||
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.
|
||||
These are the instructions to install **Libervia** using Python. Note that if you are
|
||||
using GNU/Linux, Libervia may already be available in your distribution’s repositories.
|
||||
|
||||
Libervia is made of one backend, and several frontends. To use it, the first thing to do is to install the backend.
|
||||
Libervia consists of one backend and several frontend. To use it, the first step is to
|
||||
install the backend.
|
||||
|
||||
We recommand to use development version for now, until the release of 0.9.
|
||||
We recommend using the 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 libervia-backend-hg (as well as other libervia-\* packages).*
|
||||
*Note for Arch users*: a PKGBUILD is available for your distribution on the AUR; check
|
||||
``libervia-backend-hg`` (as well as the other ``libervia‑*`` packages).
|
||||
|
||||
You can install the latest development version using pip. You need to
|
||||
have the following dependencies installed first:
|
||||
You can install the latest development version using **pip**. You need to have the
|
||||
following dependencies installed first:
|
||||
|
||||
- Python 3 with development headers
|
||||
- Python 3 "venv", which may already be installed with Python 3
|
||||
- Mercurial
|
||||
- libcairo 2 with development header
|
||||
- libjpeg with development headers
|
||||
- libgirepository 1.0 with development headers
|
||||
- libdbus-1 with development headers
|
||||
- libdbus-glib-1 with development headers
|
||||
- libxml2 with development headers
|
||||
- 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.
|
||||
- Python 3 with development headers
|
||||
- Python 3 ``venv`` (usually installed with Python 3)
|
||||
- Mercurial
|
||||
- libcairo 2 with development headers
|
||||
- libjpeg with development headers
|
||||
- libgirepository 2.0 with development headers
|
||||
- libdbus‑1 with development headers
|
||||
- libdbus‑glib‑1 with development headers
|
||||
- libxml2 with development headers
|
||||
- libxslt with development headers
|
||||
- D‑Bus X11 tools (required for ``dbus-launch``; does not need an X server)
|
||||
- CMake
|
||||
- Python GPG package (and its GPG dependencies). The system package must be
|
||||
used because the package version has to match the system GPG version.
|
||||
- build-essential (basic build tools – e.g., make, GCC – for compiling native extensions)
|
||||
- python3-wheel (Python wheel support – pip uses it to install pre-compiled packages)
|
||||
- gir1.2-glib-2.0 (GObject‑Introspection bindings for GLib – required by some rontends)
|
||||
|
||||
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 python3-gpg
|
||||
On Debian and derivatives you can install all of these with the following command::
|
||||
|
||||
Installation With pipx
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
$ sudo apt-get install build-essential python3-dev python3-venv python3-wheel mercurial libxml2-dev libxslt-dev libcairo2-dev libjpeg-dev libgirepository-2.0-dev gir1.2-glib-2.0 libdbus-1-dev libdbus-glib-1-dev dbus-x11 cmake python3-gpg
|
||||
|
||||
On Arch Linux the command is::
|
||||
|
||||
$ sudo pacman -S --needed base-devel python python-wheel mercurial libxml2 libxslt cairo libjpeg-turbo gobject-introspection dbus-glib cmake python-gpgme
|
||||
|
||||
Installation with **pipx**
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you have `pipx`_ installed, you can easily install the development version of the
|
||||
backend by entering the following command:
|
||||
backend by running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ pipx install --system-site-packages hg+https://repos.goffi.org/libervia-backend#egg=libervia-backend[all]
|
||||
|
||||
Installation With Virtual Environment And pip
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Installation with a virtual environment and **pip**
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Alternatively, you can install a virtual environment, clone the repository, and pip
|
||||
install from there.
|
||||
Alternatively, you can create a virtual environment, clone the repository, and pip install
|
||||
the backend from there.
|
||||
|
||||
Go in a location where you can install Libervia, for instance your home directory::
|
||||
Choose a location where you would like to install Libervia – for instance, your home
|
||||
directory::
|
||||
|
||||
$ cd
|
||||
|
||||
And enter the following commands (here we install Libervia with all extra dependencies
|
||||
support, i.e. will dependencies needed for optional features)::
|
||||
Then run the following commands (the ``[all]`` extra installs all optional dependencies
|
||||
for full feature support)::
|
||||
|
||||
$ python3 -m venv --system-site-packages libervia
|
||||
$ source libervia/bin/activate
|
||||
$ pip install -U pip wheel
|
||||
$ hg clone https://repos.goffi.org/libervia-backend
|
||||
$ cd libervia-backend
|
||||
$ pip install -e .
|
||||
$ pip install -e .[all]
|
||||
|
||||
Don't worry if you see the following message, Libervia should work anyway::
|
||||
|
||||
Failed building wheel for <some_package_name>
|
||||
Do not worry if you see a message such as ``Failed building wheel for
|
||||
<some_package_name>``: Libervia should still work.
|
||||
|
||||
Post Installation
|
||||
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)::
|
||||
After installing the backend, you may want to install the media repository (if you plan to
|
||||
use a graphical frontend, you may skip otherwise)::
|
||||
|
||||
$ cd
|
||||
$ hg clone https://repos.goffi.org/libervia-media
|
||||
|
||||
then, create the directory ``~/.config/libervia``::
|
||||
Create the configuration directory::
|
||||
|
||||
$ mkdir -p ~/.config/libervia
|
||||
|
||||
and the file ``~/.config/libervia/libervia.conf`` containing:
|
||||
and write the file ``~/.config/libervia/libervia.conf`` containing:
|
||||
|
||||
.. sourcecode:: cfg
|
||||
|
||||
[DEFAULT]
|
||||
media_dir = ~/libervia-media
|
||||
[DEFAULT]
|
||||
media_dir = ~/libervia-media
|
||||
|
||||
Of course, replace ``~/libervia-media`` with the actual path you have used.
|
||||
Replace ``~/libervia-media`` with the actual path you used.
|
||||
|
||||
You can check :ref:`configuration` for details
|
||||
See :ref:`configuration` for more details.
|
||||
|
||||
|
||||
.. _installation_dbus:
|
||||
|
||||
Launching D‑Bus (on servers)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you run Libervia on a server without a desktop environment, you may need to start D‑Bus
|
||||
manually.
|
||||
|
||||
Create a shell script named ``dbus_launch.sh`` with the following content:
|
||||
|
||||
.. sourcecode:: sh
|
||||
|
||||
#!/bin/sh
|
||||
|
||||
DBUS_PATH="/tmp/.dbus.`whoami`"
|
||||
|
||||
if [ ! -e "$DBUS_PATH" ]; then
|
||||
dbus-launch --sh-syntax > "$DBUS_PATH"
|
||||
chmod 400 "$DBUS_PATH"
|
||||
fi
|
||||
|
||||
cat "$DBUS_PATH"
|
||||
|
||||
Make it executable::
|
||||
|
||||
$ chmod +x /path/to/dbus_launch.sh
|
||||
|
||||
Before starting the backend or any frontend, evaluate the script::
|
||||
|
||||
$ eval $(/path/to/dbus_launch.sh)
|
||||
|
||||
This will launch the D-Bus daemon if needed and set the necessary environment variables.
|
||||
To ensure D-Bus is active in new shell sessions, run the script again using ``eval`` in
|
||||
each session. For convenience, you can add the script execution (using ``eval``) to your
|
||||
shell configuration file (e.g., ``.zshrc``).
|
||||
|
||||
|
||||
|
||||
If you prefer not to use D‑Bus, you can use an alternative bridge such as ``pb`` by
|
||||
updating the ``[DEFAULT]`` section of the configuration file::
|
||||
|
||||
bridge = pb
|
||||
|
||||
.. note::
|
||||
|
||||
Currently only D‑Bus is supported by all frontend. In particular, the
|
||||
web frontend supports D‑Bus exclusively. This limitation is temporary.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
To launch the Libervia backend, enter::
|
||||
To launch the Libervia backend, run::
|
||||
|
||||
$ libervia-backend
|
||||
|
||||
…or, if you want to launch it in foreground::
|
||||
To run it in the foreground::
|
||||
|
||||
$ libervia-backend fg
|
||||
|
||||
You can stop it with::
|
||||
To stop the backend::
|
||||
|
||||
$ libervia-backend stop
|
||||
|
||||
To know if backend is launched or not::
|
||||
To check whether the backend is running::
|
||||
|
||||
$ libervia-backend status
|
||||
|
||||
**NOTE**: if ``misc/org.libervia.Libervia.service`` is installed correctly (which should
|
||||
be done during the installation), the backend is automatically launched when a frontend
|
||||
needs it.
|
||||
.. note::
|
||||
|
||||
You can check that Libervia is installed correctly by trying jp (the backend need to be
|
||||
launched first, check below)::
|
||||
If ``misc/org.libervia.Libervia.service`` is installed correctly (it should be
|
||||
installed as part of the installation process), the backend is automatically launched
|
||||
when a frontend needs it.
|
||||
|
||||
You can verify that Libervia is installed correctly by checking its version::
|
||||
|
||||
$ li --version
|
||||
Libervia CLI 0.8.0D « La Cecília » (rev 184c66256bbc [M] (default 2021-06-09 11:35 +0200) +524) Copyright (C) 2009-2021 Jérôme Poisson, Adrien Cossa
|
||||
Libervia CLI 0.8.0D « La Cecília » (rev 184c66256bbc [M] (default 2021-06-09 11:35 +0200) +524) Copyright (C) 2009‑2021 Jérôme Poisson, Adrien Cossa
|
||||
This program comes with ABSOLUTELY NO WARRANTY;
|
||||
This is free software, and you are welcome to redistribute it under certain conditions.
|
||||
|
||||
If you have a similar output, Libervia is working.
|
||||
If you see a similar output, Libervia is working.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
You may encounter an error indicating that D‑Bus is not launched or that its
|
||||
environment variable is unset. This usually happens when launching Libervia
|
||||
on a server without a graphical environment (X.org or Wayland). Follow the
|
||||
instructions above to start D‑Bus manually.
|
||||
|
||||
Launching D-Bus (on servers)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
frontend
|
||||
==========
|
||||
|
||||
You can launch the D-Bus service by creating a shell script with the following content
|
||||
in a file named ``dbus_launch.sh``:
|
||||
The following frontend are actively maintained:
|
||||
|
||||
.. sourcecode:: sh
|
||||
- **Libervia Desktop** – desktop frontend
|
||||
- **Libervia Web** – web frontend
|
||||
- **Libervia TUI** – text‑user interface
|
||||
- **Libervia CLI** – command‑line interface
|
||||
|
||||
#!/bin/sh
|
||||
|
||||
DBUS_PATH="/tmp/.dbus.`whoami`"
|
||||
|
||||
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
|
||||
=========
|
||||
|
||||
So far, the following frontends exist and are actively maintained:
|
||||
|
||||
Libervia Desktop (aka Cagou)
|
||||
desktop/mobile (Android) frontend
|
||||
|
||||
Libervia Web
|
||||
the web frontend
|
||||
|
||||
Libervia TUI (aka Primitivus)
|
||||
Text User Interface
|
||||
|
||||
Libervia CLI (aka jp or li)
|
||||
Command Line Interface
|
||||
|
||||
To launch Libervia TUI, just type::
|
||||
To launch the TUI, run::
|
||||
|
||||
$ libervia-tui
|
||||
|
||||
then create a profile (XMPP account must already exist).
|
||||
Then create a profile (the XMPP account must already exist).
|
||||
|
||||
To use Libervia CLI, follow its help (``li`` is a shortcut for ``libervia-cli``)::
|
||||
For the CLI, use the ``li`` shortcut (``libervia-cli``) and consult the help::
|
||||
|
||||
$ li --help
|
||||
|
||||
|
||||
There are some other frontends:
|
||||
|
||||
Bellaciao
|
||||
based on Qt, a rich desktop frontend (currently on hold)
|
||||
|
||||
Wix
|
||||
former desktop frontend based on WxWidgets (deprecated with version 0.6.0)
|
||||
|
||||
Sententia
|
||||
Emacs frontend developed by a third party (development is currently stalled)
|
||||
|
||||
.. _pipx: https://pypa.github.io/pipx/
|
||||
|
|
|
|||
Loading…
Reference in a new issue