diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..35936a983 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,88 @@ + + +# Contributing + +This is a guideline for contributing to QXmpp. + +## Git Hooks Setup + +QXmpp currently just provides a hook for code formatting before commiting. +You can enable it as follows: +``` +cd qxmpp +./utils/setup-hooks.sh +``` +This requires `git-clang-format` to be installed, though. + +## Pull-requests (PRs) + +You can submit suggestions for changes via GitHub pull-requests. +The maintainers of QXmpp will review your code. However, everybody is welcome to review the code and give feedback. +You can find the current maintainers and other people involved in the project in the `AUTHORS` file. + +### Guidelines for Creating PRs + +1. Do not use the *master* branch of your personal fork to create PRs. It leads to confusion and + makes it harder to check out your branch, making changes to it and in the end also merging your + PR into the *master* branch of the main repository. +1. For fixes, target the branch of the latest release (e.g. *1.3*) instead of the *master* branch. +1. Write short commit messages starting with an upper case letter and the imperative. +1. Split your commits logically. +1. Do not mix unrelated changes in the same PR. +1. Check the tasks in the pull-request template when they are done or no changes were needed. + +## Testing + +After building QXmpp with `-DBUILD_TESTS=ON`, you can run QXmpp's unit tests in the build directory with: +``` +make test +``` + +### Internal Tests + +There are some additional internal tests that only work with debug builds because they are using unexported symbols from the QXmpp library. +You can enable those using `-DBUILD_INTERNAL_TESTS=ON`. +They are also run using `make test`, along with the regular tests. + +### Integration Tests + +There are some tests that also provide integration testing with a real XMPP server. +The code of those test cases is always built, but the cases are skipped when running `make test` without further configuration. + +You can enable them by exporting the following environment variables: + +* `QXMPP_TESTS_INTEGRATION_ENABLED=1` +* `QXMPP_TESTS_JID=` +* `QXMPP_TESTS_PASSWORD=` + +Replace `` and `` with the credentials of the account for connecting to the server. + +## Documentation + +The documentation is generated using Doxygen. +You can enable it using the CMake option `-DBUILD_DOCUMENTATION=ON` and build it manually using: +``` +make doc +``` + +The generated files are located in `doc/html/`. +You can open `doc/html/index.html` for reading the documentation. + +To correctly view the list of supported XEPs, a local webserver is needed, see the [DOAP rendering documentation][doap-rendering] for details. + +## Copyright + +QXmpp is [REUSE-compatible][reuse]. +Thus, you need to add an appropriate copyright header to each new file. +If do significant changes to a file (e.g. no search and replace, typo fixes or just adding of pure +non-copyrightable data like XML namespaces), you may add yourself as a copyright holder in the +copyright header. This is recommended for large changes. + +If the file does not allow such a header, add a `.license` file for the copyright information. + +[doap-rendering]: /doc/doap-rendering/README.md +[reuse]: https://api.reuse.software/info/github.com/qxmpp-project/qxmpp diff --git a/README.md b/README.md index 540c7dfdd..8d4c254ae 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 diff --git a/doc/doap-rendering/README.md b/doc/doap-rendering/README.md index 7f09af51d..79945d4b2 100644 --- a/doc/doap-rendering/README.md +++ b/doc/doap-rendering/README.md @@ -6,6 +6,11 @@ SPDX-License-Identifier: CC0-1.0 # DOAP rendering -Run `doc/doap-rendering/update-xeplist.sh` to get the latest XEP metadata -before building the documentation. +Run `doc/doap-rendering/update-xeplist.sh` to get the latest XEP metadata before building the documentation. +You maybe need to open a local web server to display the list of supported XEPs in case your web browser prohibits the request to `doc/doap-rendering/doap.xsl`. +Here is an example with Python's built-in web server and Firefox: +``` +python3 -m http.server +firefox http://0.0.0.0:8000/xep.html +``` diff --git a/utils/pre-commit.sh b/utils/pre-commit.sh new file mode 100755 index 000000000..a38e1166f --- /dev/null +++ b/utils/pre-commit.sh @@ -0,0 +1,9 @@ +#!/bin/sh -e + +# SPDX-FileCopyrightText: 2023 Melvin Keskin +# +# SPDX-License-Identifier: CC0-1.0 + +# This script runs all Git pre-commit hook scripts. + +git-clang-format diff --git a/utils/setup-hooks.sh b/utils/setup-hooks.sh new file mode 100755 index 000000000..9a7a9db59 --- /dev/null +++ b/utils/setup-hooks.sh @@ -0,0 +1,11 @@ +#!/bin/sh + +# SPDX-FileCopyrightText: 2023 Melvin Keskin +# +# SPDX-License-Identifier: CC0-1.0 + +# This script sets up useful git hooks in the local repository. + +REPO_ROOT=$(dirname "$(readlink -f "${0}")")/.. + +cp $REPO_ROOT/utils/pre-commit.sh .git/hooks/pre-commit