forked from qxmpp-project/qxmpp
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
README: Use Markdown syntax, improve explanations and add REUSE badge
- Loading branch information
Showing
1 changed file
with
73 additions
and
71 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,6 +3,9 @@ SPDX-FileCopyrightText: 2009 Manjeet Dahiya <[email protected]> | |
SPDX-License-Identifier: CC0-1.0 | ||
--> | ||
|
||
# QXmpp - Cross-platform C++/Qt XMPP library | ||
|
||
<h1 align="center"> | ||
<picture> | ||
<img alt="QXmpp logo" src="./logo.svg" height="150"> | ||
|
@@ -32,105 +35,104 @@ SPDX-License-Identifier: CC0-1.0 | |
<a href="https://liberapay.com/QXmpp/donate"> | ||
<img alt="Donate using Liberapay" src="https://img.shields.io/liberapay/patrons/QXmpp.svg?logo=liberapay"> | ||
</a> | ||
<a href="https://api.reuse.software/info/github.com/qxmpp-project/qxmpp"> | ||
<img alt="REUSE status" src="https://api.reuse.software/badge/github.com/qxmpp-project/qxmpp"> | ||
</a> | ||
</p> | ||
|
||
QXmpp is a cross-platform C++ XMPP client and server library. It is written | ||
in C++ and uses Qt framework. | ||
|
||
QXmpp strives to be as easy to use as possible, the underlying TCP socket, the | ||
core XMPP RFCs (RFC6120 and RFC6121) and XMPP extensions have been nicely | ||
encapsulated into classes. QXmpp is ready to build XMPP clients complying with | ||
the [XMPP Compliance Suites 2022][xmpp-compliance] for IM and Advanced Mobile. | ||
It comes with full API documentation, automatic tests and some examples. | ||
in C++ and uses the Qt framework. | ||
|
||
QXmpp uses Qt extensively, and as such users need to a have working knowledge of | ||
C++ and Qt basics (Signals and Slots and Qt data types). | ||
QXmpp strives to be as easy to use as possible. The underlying TCP socket, the core XMPP RFCs | ||
(RFC6120 and RFC6121) and the [supported XMPP extensions][xeps] have been nicely encapsulated in | ||
classes. | ||
With QXmpp, it is possible to build XMPP clients complying with the | ||
[XMPP Compliance Suites 2022][xmpp-compliance] for IM and Advanced Mobile. | ||
It comes with full API documentation, automatic tests and examples. | ||
|
||
Qt is the only third party library which is required to build QXmpp, but | ||
libraries such as GStreamer enable additional features. | ||
QXmpp uses Qt extensively. Thus, users need to have a good knowledge of C++ and Qt basics | ||
(including the concept of signals/slots and Qt's data types). | ||
Qt is the only third party library required to build QXmpp, but libraries such as GStreamer enable | ||
additional features. | ||
|
||
QXmpp is released under the terms of the GNU Lesser General Public License, | ||
version 2.1 or later. | ||
QXmpp is released under the terms of the GNU Lesser General Public License, version 2.1 or later. | ||
|
||
Building QXmpp | ||
============== | ||
## Building | ||
|
||
QXmpp requires Qt 5.15 or Qt 6.0 or higher with SSL enabled. | ||
It uses CMake as build system. | ||
QXmpp requires **Qt 5.15** or **Qt 6.0 or higher** with SSL enabled. | ||
|
||
Build from command line: | ||
|
||
mkdir build | ||
cd build | ||
cmake .. | ||
cmake --build . | ||
You can build QXmpp with CMake: | ||
``` | ||
mkdir build | ||
cd build | ||
cmake .. | ||
cmake --build . | ||
``` | ||
|
||
You can pass the following arguments to CMake: | ||
|
||
BUILD_SHARED to build with shared type library, otherwise static (default: true) | ||
BUILD_DOCUMENTATION to build the documentation, requires Doxygen (default: false) | ||
BUILD_EXAMPLES to build the examples (default: true) | ||
BUILD_TESTS to build the unit tests (default: true) | ||
BUILD_INTERNAL_TESTS to build the unit tests testing private parts of the API (default: false) | ||
BUILD_OMEMO to build the OMEMO module (default: false) | ||
WITH_GSTREAMER to enable audio/video over jingle (default: false) | ||
QT_VERSION_MAJOR=5/6 to build with a specific Qt major version (default behaviour: prefer 6) | ||
|
||
For building the OMEMO module [additional dependencies](src/omemo/README.md) | ||
are required. | ||
|
||
Installing QXmpp | ||
================ | ||
|
||
After building QXmpp, you can install the Headers, Libraries | ||
and Documentation using the following command: | ||
Option | Default | Description | ||
---|---|--- | ||
`BUILD_SHARED` | `ON` | Build as shared library, otherwise static | ||
`BUILD_DOCUMENTATION` | `ON` | Build documentation, requires Doxygen | ||
`BUILD_EXAMPLES` | `ON` | Build examples | ||
`BUILD_TESTS` | `ON` | Build unit tests | ||
`BUILD_INTERNAL_TESTS` | `OFF` | Build unit tests testing private parts of the API | ||
`BUILD_OMEMO` | `OFF` | Build the [OMEMO module][omemo] | ||
`WITH_GSTREAMER` | `OFF` | Enable audio/video over Jingle | ||
`QT_VERSION_MAJOR=5/6` | `` | to build with a specific Qt major version, prefers Qt 6 if undefined | ||
|
||
Install from command line: | ||
For example, to build without unit tests you could do: | ||
``` | ||
cmake .. -DBUILD_TESTS=OFF | ||
``` | ||
|
||
cmake --build . --target install | ||
## Installing | ||
|
||
Examples | ||
======== | ||
After building QXmpp, you can install it using the following command: | ||
``` | ||
cmake --build . --target install | ||
``` | ||
|
||
Look at the example directory for various examples. Here is a description of | ||
a few. | ||
## Examples | ||
|
||
* *example_0_connected* | ||
This example just connects to the xmpp server and start receiving presences | ||
(updates) from the server. After running this example, you can see this user | ||
online, if it's added in your roster (friends list). | ||
There are various [examples][examples] in order to quickly start using QXmpp. | ||
|
||
* *example_1_echoClient* | ||
This is a very simple bot which echoes the message sent to it. Run this | ||
example, send it a message from a friend of this bot and you will | ||
receive the message back. This example shows how to receive and send messages. | ||
### `example_0_connected` | ||
|
||
Documentation | ||
============= | ||
This example connects to the XMPP server and starts receiving presences from the server. | ||
You can see whether the user is online and if the user is in your roster (contact list). | ||
|
||
You can find the API documentation for the latest stable QXmpp version here: | ||
### `example_1_echoClient` | ||
|
||
https://doc.qxmpp.org/ | ||
This is a very simple bot which echoes the message sent to it. | ||
The example helps to understand how to receive and send messages. | ||
|
||
The API documentation of the master branch is also available: | ||
## Documentation | ||
|
||
https://doc.qxmpp.org/qxmpp-dev/ | ||
There is an API documentation for the [latest stable QXmpp version][qxmpp-documentation] and one | ||
for the [master branch][qxmpp-master-documentation]. | ||
|
||
Supported Platforms | ||
=================== | ||
## Supported Platforms | ||
|
||
It should work on all the platforms supported by Qt. For a complete list of | ||
platforms support by Qt, see: | ||
QXmpp should work on all [platforms supported by Qt][supported-platforms]. | ||
|
||
https://doc.qt.io/qt-5/supported-platforms.html | ||
## Bugs | ||
|
||
How to report a bug | ||
=================== | ||
If you think you have found a bug in QXmpp, we would like to hear about it. | ||
That way, we can fix it. | ||
Before [reporting a bug][issues], please check if the issue is already known at. | ||
|
||
If you think you have found a bug in QXmpp, we would like to hear about | ||
it so that we can fix it. Before reporting a bug, please check if the issue | ||
is already know at: | ||
## Contributing | ||
|
||
https://github.com/qxmpp-project/qxmpp/issues | ||
If you are interested in contributing to QXmpp, please have a look at our [contribution guidelines][contributing]. | ||
|
||
[xeps]: https://doc.qxmpp.org/qxmpp-1/xep.html | ||
[contributing]: /CONTRIBUTING.md | ||
[examples]: /examples | ||
[issues]: https://github.com/qxmpp-project/qxmpp/issues | ||
[omemo]: /src/omemo/README.md | ||
[qxmpp-documentation]: https://doc.qxmpp.org | ||
[qxmpp-master-documentation]: https://doc.qxmpp.org/qxmpp-dev/ | ||
[supported-platforms]: https://doc.qt.io/qt-5/supported-platforms.html | ||
[xmpp-compliance]: https://xmpp.org/extensions/xep-0459.html |