Mercurial > libervia-backend
annotate doc/installation.rst @ 4326:5fd6a4dc2122
cli (output/std): use `rich` to output JSON.
author | Goffi <goffi@goffi.org> |
---|---|
date | Wed, 20 Nov 2024 11:38:44 +0100 |
parents | 810f2b80146b |
children |
rev | line source |
---|---|
3022 | 1 .. _installation: |
2 | |
2946 | 3 ============ |
4 Installation | |
5 ============ | |
6 | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
7 These are the instructions to install Libervia using Python. |
3505 | 8 Note that if you are using GNU/Linux, Libervia may already be present on your distribution. |
2946 | 9 |
3505 | 10 Libervia is made of one backend, and several frontends. To use it, the first thing to do is to install the backend. |
2946 | 11 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
12 We recommand to use development version for now, until the release of 0.9. |
2946 | 13 |
14 Development version | |
15 ------------------- | |
16 | |
17 *Note for Arch users: a pkgbuild is available for your distribution on | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
18 AUR, check libervia-backend-hg (as well as other libervia-\* packages).* |
2946 | 19 |
20 You can install the latest development version using pip. You need to | |
21 have the following dependencies installed first: | |
22 | |
3260
e9ecd133773b
doc (installation): updated instructions for backend
Goffi <goffi@goffi.org>
parents:
3022
diff
changeset
|
23 - Python 3 with development headers |
3383 | 24 - Python 3 "venv", which may already be installed with Python 3 |
2946 | 25 - Mercurial |
3383 | 26 - libcairo 2 with development header |
2946 | 27 - libjpeg with development headers |
28 - libgirepository 1.0 with development headers | |
29 - libdbus-1 with development headers | |
30 - libdbus-glib-1 with development headers | |
31 - libxml2 with development headers | |
32 - libxlt2 with development headers | |
33 - D-Bus x11 tools (this doesn't needs X11, it is just needed for dbus-launch) | |
34 - cmake | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
35 - Python GPG package (and its GPG dependencies), those are needed to use all OpenPGP |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
36 related features. We need to use the system package as package version needs to match |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
37 system GPG version. |
2946 | 38 |
39 On Debian and derivatives, you can get all this with following command:: | |
40 | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
41 $ 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 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
42 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
43 Installation With pipx |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
44 ~~~~~~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
45 |
4113
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
46 If you have `pipx`_ installed, you can easily install the development version of the |
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
47 backend by entering the following command: |
2946 | 48 |
4113
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
49 .. code-block:: bash |
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
50 |
4257
810f2b80146b
doc (installation): use `[all]` in extra arguments.
Goffi <goffi@goffi.org>
parents:
4113
diff
changeset
|
51 $ pipx install --system-site-packages hg+https://repos.goffi.org/libervia-backend#egg=libervia-backend[all] |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
52 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
53 Installation With Virtual Environment And pip |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
54 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
55 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
56 Alternatively, you can install a virtual environment, clone the repository, and pip |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
57 install from there. |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
58 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
59 Go in a location where you can install Libervia, for instance your home directory:: |
2946 | 60 |
61 $ cd | |
62 | |
4257
810f2b80146b
doc (installation): use `[all]` in extra arguments.
Goffi <goffi@goffi.org>
parents:
4113
diff
changeset
|
63 And enter the following commands (here we install Libervia with all extra dependencies |
810f2b80146b
doc (installation): use `[all]` in extra arguments.
Goffi <goffi@goffi.org>
parents:
4113
diff
changeset
|
64 support, i.e. will dependencies needed for optional features):: |
2946 | 65 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
66 $ python3 -m venv --system-site-packages libervia |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
67 $ source libervia/bin/activate |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
68 $ pip install -U pip wheel |
3774
df836d6f9c8a
doc (installation): fix missing `hg clone` instructions
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
69 $ hg clone https://repos.goffi.org/libervia-backend |
df836d6f9c8a
doc (installation): fix missing `hg clone` instructions
Goffi <goffi@goffi.org>
parents:
3563
diff
changeset
|
70 $ cd libervia-backend |
4113
3f59a2b141cc
doc (installation): update `pipx` instruction and remove `requirements.txt` mention
Goffi <goffi@goffi.org>
parents:
3990
diff
changeset
|
71 $ pip install -e . |
2946 | 72 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
73 Don't worry if you see the following message, Libervia should work anyway:: |
2946 | 74 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
75 Failed building wheel for <some_package_name> |
2946 | 76 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
77 Post Installation |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
78 ~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
79 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
80 After installing Libervia, you need to install the media (you may skip this if you don't |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
81 plan to use any graphical frontend):: |
2946 | 82 |
83 $ cd | |
3776
4d333f249625
doc (installation): `sat_media` is now `libervia-media`
Goffi <goffi@goffi.org>
parents:
3774
diff
changeset
|
84 $ hg clone https://repos.goffi.org/libervia-media |
2946 | 85 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
86 then, create the directory ``~/.config/libervia``:: |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
87 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
88 $ mkdir -p ~/.config/libervia |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
89 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
90 and the file ``~/.config/libervia/libervia.conf`` containing: |
2946 | 91 |
92 .. sourcecode:: cfg | |
93 | |
94 [DEFAULT] | |
3776
4d333f249625
doc (installation): `sat_media` is now `libervia-media`
Goffi <goffi@goffi.org>
parents:
3774
diff
changeset
|
95 media_dir = ~/libervia-media |
2946 | 96 |
3776
4d333f249625
doc (installation): `sat_media` is now `libervia-media`
Goffi <goffi@goffi.org>
parents:
3774
diff
changeset
|
97 Of course, replace ``~/libervia-media`` with the actual path you have used. |
2946 | 98 |
3260
e9ecd133773b
doc (installation): updated instructions for backend
Goffi <goffi@goffi.org>
parents:
3022
diff
changeset
|
99 You can check :ref:`configuration` for details |
2946 | 100 |
101 Usage | |
102 ===== | |
103 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
104 To launch the Libervia backend, enter:: |
2946 | 105 |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
106 $ libervia-backend |
2946 | 107 |
108 …or, if you want to launch it in foreground:: | |
109 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
110 $ libervia-backend fg |
2946 | 111 |
112 You can stop it with:: | |
113 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
114 $ libervia-backend stop |
2946 | 115 |
116 To know if backend is launched or not:: | |
117 | |
3563
267e4987b58b
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents:
3558
diff
changeset
|
118 $ libervia-backend status |
2946 | 119 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
120 **NOTE**: if ``misc/org.libervia.Libervia.service`` is installed correctly (which should |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
121 be done during the installation), the backend is automatically launched when a frontend |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
122 needs it. |
2946 | 123 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
124 You can check that Libervia is installed correctly by trying jp (the backend need to be |
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
125 launched first, check below):: |
2946 | 126 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
127 $ li --version |
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
128 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 |
2946 | 129 This program comes with ABSOLUTELY NO WARRANTY; |
130 This is free software, and you are welcome to redistribute it under certain conditions. | |
131 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
132 If you have a similar output, Libervia is working. |
2946 | 133 |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
134 .. note:: |
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
135 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
136 You may see an error message indicating that D-Bus is not launched or that its |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
137 environment variable is not set, this usually happens when launching Libervia on a |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
138 server, without graphic interface like X.org or Wayland (otherwise D-Bus service should |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
139 be launched automatically). In this case please follow instructions below. |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
140 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
141 Launching D-Bus (on servers) |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
143 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
144 You can launch the D-Bus service by creating a shell script with the following content |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
145 in a file named ``dbus_launch.sh``: |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
146 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
147 .. sourcecode:: sh |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
148 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
149 #!/bin/sh |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
150 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
151 DBUS_PATH="/tmp/.dbus.`whoami`" |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
152 |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
153 if [ ! -e $DBUS_PATH ]; then |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
154 dbus-launch --sh-syntax > $DBUS_PATH |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
155 chmod 400 $DBUS_PATH |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
156 fi |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
157 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
158 cat $DBUS_PATH |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
159 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
160 Then run it before the backend or frontend by entering:: |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
161 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
162 $ eval $(/path/to/dbus_launch.sh) |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
163 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
164 This will launch the D-Bus daemon if necessary, and set the appropriate environment |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
165 variable. If you use a new shell, be sure to launch the script again in an ``eval`` |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
166 statement to have the environment variable set. You can put this in your ``.zshrc`` (or |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
167 whatever you're using) to make it automatic. |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
168 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
169 If you don't want to use D-Bus, you can use another bridge, e.g. ``pb`` is a good |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
170 choice, by updating your :ref:`configuration` ``[DEFAULT]`` section with ``bridge = |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
171 pb``. |
3353
7726916c1ba6
doc: updated installation instructions
Goffi <goffi@goffi.org>
parents:
3260
diff
changeset
|
172 |
2946 | 173 Frontends |
174 ========= | |
175 | |
176 So far, the following frontends exist and are actively maintained: | |
177 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
178 Libervia Desktop (aka Cagou) |
2946 | 179 desktop/mobile (Android) frontend |
180 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
181 Libervia Web |
2946 | 182 the web frontend |
183 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
184 Libervia TUI (aka Primitivus) |
2946 | 185 Text User Interface |
186 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
187 Libervia CLI (aka jp or li) |
2946 | 188 Command Line Interface |
189 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
190 To launch Libervia TUI, just type:: |
2946 | 191 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
192 $ libervia-tui |
2946 | 193 |
194 then create a profile (XMPP account must already exist). | |
195 | |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
196 To use Libervia CLI, follow its help (``li`` is a shortcut for ``libervia-cli``):: |
2946 | 197 |
3558
d8581c83fef3
doc (installation): update instruction to use requirements + fix name in a few places
Goffi <goffi@goffi.org>
parents:
3536
diff
changeset
|
198 $ li --help |
2946 | 199 |
200 | |
201 There are some other frontends: | |
202 | |
203 Bellaciao | |
204 based on Qt, a rich desktop frontend (currently on hold) | |
205 | |
206 Wix | |
207 former desktop frontend based on WxWidgets (deprecated with version 0.6.0) | |
208 | |
209 Sententia | |
210 Emacs frontend developed by a third party (development is currently stalled) | |
3990
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
211 |
3b72743b92db
doc[installation]: update instructions
Goffi <goffi@goffi.org>
parents:
3776
diff
changeset
|
212 .. _pipx: https://pypa.github.io/pipx/ |