QI-QMP

QI-QMP is a minuscule C++ library, which utilizes Qt, that provides an interface to QEMU instances via the QEMU Machine Protocol. In other words, this library implements the client side of QMP for C++.

The interface takes the form of the library's sole class, Qmpi.

Relevant Reading

• QMP Specification
• QMP Reference Manual

Requirements

• An x64, C++20 capable compiler
• Qt6
• CMake 3.23.0 or greater
• OS
  • Windows 10 or above
  • Linux (untested on more general Unix systems)

Packaging

QI-QMP is provided as a CMake package composed of a single library and accompanying public header file.

Package Components:

• Qmpi - The main library

# Example QI-QMP Import
find_package(QI-QMP)

If no components are specified in the find_package() call, only the library will be imported.

QI-QMP 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 QI-QMP or building it as a sub-project.

For example, the Qmpi component corresponds to the qi_qmp_qmpi target, which can also be referred to via QI-QMPQmpi.

Getting Started

Note

For a recommended alternative, see Source Build as a Direct CMake Dependency

1) Download the latest Release

2) Place the package somewhere CMake can find it

# Add to a default search path or...
set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} path\to\QI_QMP_package)

3) Import the package

# When no components are specified, all available components will be imported
find_package(QI-QMP 0.1) # Or whichever version

4) Link to the library

target_link_libraries(example_app PUBLIC QI-QMP::Qmpi)

5) Include the public header in your code

#include <qi-qmp/qmpi.h>

6) Review the documentation for the Qmpi class.

Minimal Example

#include <QDebug>
#include <qi-qmp/qmpi.h>
 
// Somewhere inside a Qt event loop
Qmpi iQemu(QHostAddress::LocalHost, 4444);
QObject::connect(&iQemu, &Qmpi::connected, [](QJsonObject version, QJsonArray capabilities){
    qDebug() << "Version: " << version;
    qDebug() << "Capabilities: " << capabilities;
});
QObject::connect(&iQemu, &Qmpi::readyForCommands, [&](){
    iQemu.execute("query-status", QJsonObject(), QString("query-status"));
});
QObject::connect(&iQemu, &Qmpi::connectionErrorOccured, [](QAbstractSocket::SocketError error){
    qDebug() << "Socker Error: " << error;
});
QObject::connect(&iQemu, &Qmpi::communicationErrorOccured, [](Qmpi::CommunicationError error){
    qDebug() << "Communication Error: " << error;
});
QObject::connect(&iQemu, &Qmpi::responseReceived, [](QJsonValue data, std::any context){
    qDebug() << "Command " << std::any_cast<QString>(context) << " returned the data: " << data;
});
QObject::connect(&iQemu, &Qmpi::errorResponseReceived, [](QString errorClass, QString desc, std::any context){
    qDebug() << "Command " << std::any_cast<QString>(context) << " threw the error: [" << errorClass << "] " << desc;
});
 
iQemu.connectToHost();
...

Building From Source

The latest generally stable source is available in the 'master' branch of https://github.com/oblivioncth/QI-QMP, 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 QI-QMP, 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.

CMake Options:

• QI_QMP_DOCS - Set to ON in order to generate the documentation target (OFF)
• BUILD_SHARED_LIBS - Build QI-QMP as a shared library instead of a static one (OFF)

CMake Targets:

• all - Effectively an alias for the qi_qmp_qmpi target, also builds documentation if enabled
• install - Installs the build output into CMAKE_INSTALL_PREFIX
• qi_qmp_docs - Builds the QI-QMP documentation
• qi_qmp_qmpi - Builds the project's sole library

CMake Install Components:

• qi_qmp - Installs top-level files (README.md, CMake package configuration files, etc.)
• qi_qmp_docs - Installs documentation
• qi_qmp_qmpi - Installs the built library

If QI-QMP is configured as a sub-project, its install components are automatically removed from the default install component, as to not pollute the install directory of the top-level project. They can still be installed by directly referencing their component names as shown above.

Documentation:

In order for the qi_qmp_docs target to be generated the CMake cache variable QI_QMP_DOCS must be set to ON when CMake is invoked:

cmake.exe (...) -D QI_QMP_DOCS=ON

The QI_QMP documentation supports two optional, but highly recommended features:

• Linking to Qt documentation
• Generating a Qt Compressed Help (.qch) file for use in Qt Creator

In order to enable these features, the CMake variables QT_DOCS_DIR and QT_HELP_GEN_PATH respectively must be available. QI-QMP 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

Package

By default, the CMakeLists project configures CPack to create an artifact ZIP containing the binaries/archives for the library configurations, as well as documentation.

The following is the general build process required to successfully generate this package via a shadow build on Windows. Adjust the configuration as you see fit::

# Set the environment variables that follow as desired
 
# Setup C++ Build Environment
CALL "%VS_PATH%\Common7\Tools\VsDevCmd.bat" -arch=amd64
 
# Configure CMake using Qt wrapper
CALL "%Qt_ROOT%\bin\qt-cmake" -G "Ninja Multi-Config" -S "%QI_QMP_SOURCE_DIR%" -B "%QI_QMP_BUILD_DIR%" -D QI_QMP_DOCS=ON
 
# Go to Build directory
cd /D "%QI_QMP_BUILD_DIR%"
 
# Build the Debug/Release libraries and documentation
cmake.exe --build . --target all --config Debug
cmake.exe --build . --target all --config Release
 
# Install Debug/Release libraries and documentation
cmake --install . --config Debug
cmake --install . --config Release
 
# Create the output package
cpack.exe -C Debug;Release

Source Build as a Direct CMake Dependency

If you want to use QI-QMP 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 'FetchQI-QMP.cmake' and add it to CMAKE_MODULE_PATH:

# FetchQI-QMP.cmake - REQUIRES GIT
 
# This will checkout QI-QMP, make its targets available directly at configure time without needing to call
# find_package(), and automatically build it as a dependency at build time.
 
function(fetch_qi_qmp git_ref)
    include(FetchContent)
    FetchContent_Declare(QI-QMP
        GIT_REPOSITORY "https://github.com/oblivioncth/QI-QMP"
        GIT_TAG ${git_ref}
    )
    FetchContent_MakeAvailable(QI-QMP)
endfunction()

Then in your CMake project:

include(FetchQI-QMP)
fetch_qi_qmp(<commitish_here>) # Get QI-QMP
 
add_executable(SomeExe
    ...
)
 
target_link_libraries(SomeExe
    PRIVATE
        QI-QMP::Qmpi
)

This allows for more flexibility in downstream projects as they can more easily alter the configuration of libsquish on-the-fly as needed.