Qx v0.5.7
Qt Extensions Library
|
Qx is a basic C++ library built on top of the ubiquitous Qt framework, created with the intention of extending its existing functionality while following the same paradigm of its design.
The library primarily consists data structures and routines that facilitate a variety of common, or otherwise reoccurring programmatic tasks, largely providing convenience, flexibility, and syntactic efficiency to developers when writing applications.
Qx is provided as a CMake package containing several component libraries that roughly follow the scope and grouping of Qt modules, with Core being the primary component.
See the Components Index for a list of available components (NOTE: Some of these are platform dependent).
When importing the library package with CMake it is recommended to only include the components you need for a particular application in order to minimize the size of your build.
An imported component that depends on other Qx components will always cause said components to automatically be imported, even if they are not explicitly specified. Likewise, targets that link to interdependent components will automatically be linked to dependency components as necessary.
Qx is also composed to gracefully support CMake’s FetchContent mechanism. All exportable targets are named to match their corresponding component when packaged, and feature alias targets with the same names when building. This allows consumers to access the targets via the same name regardless of whether they are using a pre-built package of Qx or building it as a sub-project.
For example, the Core
component corresponds to the qx_core
target, which can also be referred to via Qx::Core
.
1) Download the latest Release
2) Place the package somewhere CMake can find it
3) Import the package
4) Link to the required components where necessary
5) Include the corresponding headers in your code
It is possible to include portions of the Qx API with finer granularity by only referencing the exact headers you need in accordance with the include structure shown in the File Index, but at first it is generally recommended to simply include the main header for each component you use as shown.
6) Review the rest of the documentation. A good place to start is the Core component.
The latest generally stable source is available in the 'master' branch of https://github.com/oblivioncth/Qx, while the most up-to-date source can be found in the 'dev' branch.
The requirements for building from Git are the same as for using Qx, with the obvious exception that Doxygen (as well as Graphviz) is also needed to build the documentation.
If newer to working with Qt, it is easiest to build from within Qt creator as it handles a large portion of environment setup, including adding Qt to CMake's package search list, automatically. Simply make sure that a kit is configured in Qt Creator that uses a compatible version of Qt, open the CMakeLists.txt file as a project, and build with the desired configuration.
The CMake project is designed to be used with multi-configuration generators such as Visual Studio or Ninja Multi-Config (recommended), and may require some tweaking to work with single configuration generators.
If you only need a subset of Qx's components, the QX_COMPONENTS cache variable can be set to a semicolon or whitespace separated list of components. Only these components and their required dependencies will be configured, which can save on build time.
QX_DOCS
- Set to ON
in order to generate the documentation target (OFF)QX_COMPONENTS
- Set to a semicolon/whitespace delimited list of components to limit configuration to those components only ([all-components])QX_TESTS
= Set to ON
in order to generate the test targets (OFF)BUILD_SHARED_LIBS
- Build Qx as a shared libraries instead of a static ones (OFF)all
- Builds all Qx components (the entire library) and documentation if enabledinstall
- Installs the build output into CMAKE_INSTALL_PREFIX
qx_docs
- Builds the Qx documentationqx_<lowercase_component_name>
- Builds a specific Qx componentqx_tst_...
- Builds the various test targets. To actually run tests, just build the general CMake tests target test
.qx
- Installs top-level files (README.md, CMake package configuration files, etc.)qx_docs
- Installs the Qx documentationqx_<lowercase_component_name>
- Installs a specific Qx componentIf Qx is configured as a sub-project, its install components are automatically removed from the all
component, as to not pollute the install directory of the top-level project.
In order for the qx_docs
target to be generated the CMake cache variable QX_DOCS must be set to ON when CMake is invoked:
The Qx documentation supports two optional, but highly recommended features:
In order to enable these features, the CMake variables QT_DOCS_DIR and QT_HELP_GEN_PATH respectively must be available. Qx tries to set them automatically according to the following defaults, but these can be overridden by passing definitions for the variables to CMake on the command line via -D
.
# Optional documentation defaults # Here <QT_ROOT> refers to the install directory of a given Qt build QT_DOCS_DIR: <QT_ROOT>/doc (Windows) QT_HELP_GEN_PATH: <QT_ROOT>/bin/qhelpgenerator.exe (Linux) QT_HELP_GEN_PATH: <QT_ROOT>/libexec/qhelpgenerator
If supplying QT_DOCS_DIR manually, it must be set to the root path that contains documentation for the Qt version you are building with. It should look something like this:
doc/ ├── config ├── global ├── qdoc ├── qmake ├── qtcmake ├── qtconcurrent ├── qtcore ├── ... ├── qdoc.qch ├── qmake.qch └── ... # In this case QT_DOCS_DIR should point to the directory 'doc'.
The path for this documentation varies depending on how you obtained Qt, but is generally placed in one of two locations:
# Official Qt Builds from Maintenance Tool/Installer <QT_SOFTWARE>/Docs/Qt-<QT_VERSION> # Self-built Qt <QT_ROOT>/doc # NOTE: # By default on Windows <QT_SOFTWARE> is C:\Program Files\Qt # On Linux it is often /usr/local/Qt
The project contains a suite of tests to ensure that the library functions as intended. They will be expanded upon as the library matures.
By default, the CMakeLists project configures CPack to create an artifact ZIP containing the binaries for Debug and Release configurations, as well as documentation.
The following is the general build process required to successfully generate this package via a shadow build on Windows:
This example can easily be adapted to bash for builds on Linux.
By default, build artifacts are placed into <BUILD_DIR>/out
.
If you want to use Qx compiled from source directly as a dependency in your CMake project and don't care about the intermediary redistributables, it is recommended to do the following.
Create 'FetchQx.cmake' and add it to CMAKE_MODULE_PATH:
Then in your CMake project:
This approach will avoid concerns of ensuring compatibility between Qt configurations for your project and Qx, since both will be built with the same copy of Qt. It also allows for more flexibility in downstream projects as they can more easily alter the configuration of Qx on-the-fly as needed.