From 19861c7038631b317e86b8c3d6878ffe9dc90595 Mon Sep 17 00:00:00 2001
From: Amin Bandali <amin.bandali@savoirfairelinux.com>
Date: Thu, 14 Jul 2022 10:18:14 -0400
Subject: [PATCH] build: start writing the manual, starting with introduction
Change-Id: Iefa04fa4ef450589a6f244bc7915ec018e54e9e1
---
build/index.rst | 19 +++++++++++++++++
build/introduction.rst | 48 ++++++++++++++++++++++++++++++++++++++++++
index.rst | 1 +
3 files changed, 68 insertions(+)
create mode 100644 build/index.rst
create mode 100644 build/introduction.rst
diff --git a/build/index.rst b/build/index.rst
new file mode 100644
index 00000000..d54a2748
--- /dev/null
+++ b/build/index.rst
@@ -0,0 +1,19 @@
+############
+Build manual
+############
+
+The Jami build manual documents the various aspects of building Jami
+from source, as well as packaging Jami for various package systems.
+This manual is aimed at those looking to build Jami from source -- for
+instance to hack on Jami and contribute to its development, or to try
+recently-added unreleased features -- as well as package maintainers
+and contributors to GNU/Linux distributions looking to package or help
+maintain a Jami package for their distribution's repositories.
+
+.. toctree::
+ :maxdepth: 1
+
+ introduction
+ dependencies
+ building
+ packaging
diff --git a/build/introduction.rst b/build/introduction.rst
new file mode 100644
index 00000000..78cf9262
--- /dev/null
+++ b/build/introduction.rst
@@ -0,0 +1,48 @@
+Introduction
+============
+
+An installation of Jami typically has two main components:
+
+1. the Jami daemon/library, and
+2. the client (i.e. front-end or user interface).
+
+To use Jami, the Jami daemon/library is always needed, since it is
+the core of Jami and contains all of the connectivity, communication,
+cryptography, and media logic. It uses libraries such as OpenDHT,
+PJSIP, GnuTLS, and FFmpeg, and has several APIs including DBus,
+libwrap (shared library), JNI, and REST. These APIs make it possible
+to interact with Jami without going through a graphical user interface
+(especially useful for using Jami in a headless/server setting), build
+automation tools/scripts around Jami, and build custom user interfaces
+for Jami.
+
+The client (i.e. user interface) may vary depending on the operating
+system and/or platform being used. For example, on Android/Replicant
+systems this would be jami-client-android, and on GNU/Linux, Windows,
+and macOS this would be the jami-client-qt. There also used to be a
+GTK-based jami-client-gnome for GNU/Linux and a jami-client-macos for
+macOS, both of which were deprecated in favour of the newer
+cross-platform jami-client-qt based on the Qt framework.
+
+On GNU/Linux systems, jami-client-qt can be configured and built to
+use one of two main APIs for communicating with the Jami
+daemon/library:
+
+1. libwrap: when jami-client-qt is configured to use libwrap (which is
+ always the case on macOS and Windows), it will use Jami daemon's
+ shared library API, and there will be no separate daemon process.
+ This has the advantage of things being somewhat more efficient than
+ with the DBus API mentioned below, in exchange for less flexibility
+ (not being able to interact with Jami via DBus when using libwrap).
+
+ The Jami packages distributed via dl.jami.net are currently all
+ configured to use the libwrap API.
+
+2. DBus: when jami-client-qt is configured to use DBus, it will
+ communicate with the Jami daemon via its DBus API, and the daemon
+ will be running as a separate process by itself. This is greatly
+ flexible for communicating with and controlling the daemon through
+ other means (for example small utility scripts) simultaneously
+ while the Jami Qt client also uses and interacts with it.
+ The associated cost of this added flexibility is the overhead of
+ using DBus.
diff --git a/index.rst b/index.rst
index 5bda01b6..aabc84b5 100644
--- a/index.rst
+++ b/index.rst
@@ -22,4 +22,5 @@ This documentation is community-driven and :ref:`anyone can contribute
:maxdepth: 2
user/index
+ build/index
technical/index
--
GitLab