From d6d6435fffe5e694715beb1bcb696eff08088d13 Mon Sep 17 00:00:00 2001 From: Melvin Keskin Date: Wed, 22 Feb 2023 08:33:40 +0100 Subject: [PATCH] README: Use Markdown syntax, improve explanations and add REUSE badge --- README.md | 144 +++++++++++++++++++++++++++--------------------------- 1 file changed, 73 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 540c7dfdd..a50a0b019 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,9 @@ SPDX-FileCopyrightText: 2009 Manjeet Dahiya SPDX-License-Identifier: CC0-1.0 --> + +# QXmpp - Cross-platform C++/Qt XMPP library +

QXmpp logo @@ -32,105 +35,104 @@ SPDX-License-Identifier: CC0-1.0 Donate using Liberapay + + REUSE status +

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