Some Lesser Known Qt Tools and Commands

Some Lesser Known Qt Tools and Commands – Part 1

Wednesday, February 25, 2015

Every Qt developer should be familiar with the common tools like qmake, Qt Designer and Assistant, but looking in your Qt installation’s bin directory will reveal a few more programs there. In this and future blogs, we’ll look at some of the lesser known Qt development tools.

First, let’s review a list of the tools for which you should be familiar. A few, like moc, rcc, and uic may be less familiar to you if you primarily let qmake or your IDE take care of building software, but the tools shown in the table below are ones that most Qt developers use on a regular basis.

Table 1 – Commonly Used Qt Tools
Tool Name Description
assistant Qt Assistant documentation tool
designer Qt Designer GUI layout tool
linguist Qt Linguist translation tool
lrelease Localization tool to compile ts files to qm files
lupdate Localization tool to extract translation strings and generate or update ts files
moc Qt Meta Object Compiler
qmake Qt software build tool
qmlscene QML file viewer (for Qt Quick2/Scene Graph)
qmlviewer QML file viewer (for Qt Quick 1)
rcc Qt resource file compiler
uic Qt User Interface Compiler for generating code from ui files

If any of the tools above don’t look familiar, I encourage you to review the Qt documentation to learn more about them. In this post we’ll look at three lesser-known tools: lconvert, pixeltool and qlalr.

Lconvert

Lconvert is one of the translation tools included with Qt. It is a command line tool that can convert between different translation file formats. It was introduced in Qt 4.5.0. If you use Qt’s standard ts files for translations, you may not have occasion to use this tool. However, if you use another translation file format, like the GNU Gettext PO format, lconvert can be useful for converting to and from this format. Even if you are using the ts file format, if your translations are done by a large translation house, they may not have heard of Qt’s file format. However, they may be able to supply you with translations in XLIFF (1) format. The lconvert tool can convert your translations between XLIFF and PO format. Because it is a non-graphical command line program, you may find it useful to incorporate the tool into your software build system to automate building or conversion of translation files. The tool also has some filtering capabilities. You can get further details by reading the Qt documentation.

Pixeltool

The Qt Pixel Zooming Tool, pixeltool, is a handy little graphical application that magnifies the screen around the mouse pointer so you can look more closely at individual pixels. It is useful for testing small areas of a graphical user interface (GUI), something you might need to do when developing a new custom widget or theme, for example. Pixeltool has a number of options that are accessible via a context menu. A screenshot is shown below, as well as the context (right click) menu.

Pixeltool has been a part of Qt for a long time, at least as far back as the early Qt 4 releases.

QLALR

A little known but occasionally very useful tool that ships with Qt is qlalr, the Qt parser generator. QLALR accepts an input file that defines a grammar and generates C++ code to generate a parser for it. It is much like the traditional UNIX Yacc (or GNU equivalent, Bison) tools. Like those tools, it accepts LALR(1) parsing grammars and supports associativity and ambiguity. Unlike these tools, however, QLALR generates Qt-based C++ code rather than plain C. It is used internally by Qt for QML’s JavaScript parser and Qt’s XML stream reader. The tool is not mentioned in Qt’s reference documentation, but a couple of blog posts (2)(3) have been written by developers that describe it.

Summary

I hope you found this brief article regarding some of the more obscure Qt tools useful. I plan to cover more of the lesser known commands in future blog posts.

References

  1. XLIFF, Wikipedia article, accessed 12 February 2015, en.wikipedia.org/wiki/XLIFF
  2. QLALR Adventures, Using QLALR to generate a parser for a text adventure, Qt project blog post, accessed 12 February 2015, qt-project.org/quarterly/view/qlalr_adventures
  3. Developer Daze(tm) presents: A Closer Look at QLALR, Qt project blog post, accessed 12 February 2015, blog.qt.digia.com/blog/category/qlalr

Some Lesser Known Qt Tools and Commands – Part 2

Wednesday, April 1, 2015

Continuing with our series of blog posts on some of the lesser known Qt commands, this time we will look at some tools related to Qt and D-Bus.

D-Bus (1) is an inter-process communication (IPC) system that allows multiple concurrently running computer programs to communicate.

It was developed by the freedesktop.org project to standardize services provided by Linux desktop environments. D-Bus is free software and runs on Linux and most POSIX-compatible operating systems, and a port to Windows exists. While originally developed for desktop systems, it is also commonly available and used on embedded Linux systems.

Qt (2) provides a set of interfaces to D-Bus, which are covered in detail in the Qt documentation. Some of the relevant Qt classes include QDBusConnectionQDBusInterface and QDBusMessage. Qt also comes with a handful of example applications that use D-Bus. Four D-Bus related tools are included in Qt: qdbus, qdbusviewer, qdbuscpp2xml and qdbusxml2cpp.

qdbus

This is a command-line tool that can list D-Bus services, object paths, methods, signals and properties available. It has a number of options to control the output it produces, all of which are well covered in the Qt documentation.

Here is an example of the output on a Linux desktop system when running the command without any options, where the behavior is to list all of the services available on the bus. Not all of the output is shown, as it is quite long.

% qdbus
org.kde.klauncher
org.kde.ActivityManager
org.kde.kactivitymanagerd
org.freedesktop.ScreenSaver
org.kde.ksmserver
org.kde.ksmserver-2228
org.kde.screensaver
org.freedesktop.Notifications

Command line options allow specifying the D-Bus service to connect to, path to the object or a D-Bus method to call.

qdbusviewer

This is a graphical tool to show D-Bus services, object paths, and the methods, signals and properties available. A typical screen shot is shown below. It is similar to the qtdbus tool, but offers a graphical user interface.

qdbuscpp2xml

Qt provides some tools to make it easy to access D-Bus services from C++ code. One of the features of D-Bus is introspection. D-Bus objects that support this feature can be introspected at run time, returning an XML string that describes the object. The qdbuscpp2xml tool parses the C++ source or header file containing a QObject-derived class and produces the D-Bus Introspection XML.

qdbusxml2cpp

The qdbusxml2cpp tool is also used for implementing D-Bus services in C++. It produces the C++ code to implement the interfaces defined in an XML input file.

Summary

D-Bus can be a complex and sometimes confusing technology that can take some time to learn. It can be a powerful tool, particularly when used with Qt. The details are outside the scope of what can be covered in this blog post, but you can learn more from the relevant Qt documentation.

I hope you found this blog post interesting. We haven’t yet exhausted the list of lesser-known Qt commands. I plan to continue this series in future blog posts.

References

  1. Wikipedia article on D-Bus, retrieved 20 Mar 2015, http://en.wikipedia.org/wiki/D-Bus
  2. On-line version of Qt reference documentation for Qt D-Bus, retrieved 20 Mar 2015, http://doc.qt.io/qt-5/qtdbus-index.html

Some Lesser Known Qt Tools and Commands – Part 3

Wednesday, June 24, 2015

In this next installment of our blog series on lesser-known Qt commands, we’ll look at four tools related to documentation: qdoc, qhelpgenerator, qcollectiongenerator and qhelpconverter.

Qdoc

Qdoc1 is the tool used to generate the developer documentation for the Qt Project. It is not specific to Qt, and can be used to create documentation for other projects or applications.

Similar to tools like Javadoc2 and Doxygen3, it works by extracting structured comments from source files and using them to generate documentation in HTML or other formats.

The comments are typically located in cpp, qml or qdoc files and use a simple markup language with tags. A partial example from the Qt source file for the QBrush class, qbrush.cpp, is shown below:

/*!
    \class QBrush
    \ingroup painting
    \ingroup shared
    \inmodule QtGui

    \brief The QBrush class defines the fill pattern of shapes drawn
    by QPainter.

    A brush has a style, a color, a gradient and a texture.

    The brush style() defines the fill pattern using the
    Qt::BrushStyle enum. The default brush style is Qt::NoBrush
    (depending on how you construct a brush). This style tells the
    painter to not fill shapes. The standard style for filling is
    Qt::SolidPattern. The style can be set when the brush is created
    using the appropriate constructor, and in addition the setStyle()
    function provides means for altering the style once the brush is
    constructed.

    ...

*/

The qdoc program is a command line utility which accepts a number of options, all of which are well documented.

Something to note is that, beginning with Qt 5.5, a new way to run qdoc is available that can, in some cases, greatly reduce the time taken to generate Qt 5 documentation. Read the documentation about the new „single execution mode“ for more details.

Qhelpgenerator

Qt help can be produced as separate HTML files, but it is often desirable to store the documentation in a smaller self-contained format. The qhelpgenerator tool is used to do this. It accepts a Qt Help Project (qhp) file that defines the structure of the documentation and html files and produces a standalone qch or Qt Compressed Help file containing all the documentation.

Qcollectiongenerator

Help can also be combined into collections of help files. A help collection can include any number of compressed help files.

The qcollectiongenerator tool is used for generating a qhc or Qt Help Collection file. It accepts as input a Qt Help Collection Project (qhcp) file, which defines the compressed help files that should be included in the collection. The tool produces a Qt Help Collection (qhc) file that contains references to the compressed help files in the collection.

Qhelpconverter

The last documentation-related tool we will look at is qhelpconverter.

In Qt versions up to 4.3, the help system was based on the Document Content File (DCF) and Qt Assistant Documentation Profile (ADP) file formats. Qt 4.4 and later (including Qt 5) use different file formats. In order to provide a way to migrate existing files to the newer format, the qhelpconverter tool is provided. It is a graphical wizard-type application that steps the user through the process of converting help files to the new qch and qhcp formats. Screen shots of a couple of the wizard screens are shown below:

Summary

This blog post was not intended to be a tutorial for the documentation system. All of these different help-related files and tools may sound confusing, but the Qt documentation4 does a good job of explaining the overall process and I refer you to it for more details.

References

  1. QDoc Manual, Qt documentation web site, accessed 1 Jun 2015, http://doc.qt.io/qt-5/qdoc-index.html
  2. Javadoc tool, Java SE documentation web site, accessed 1 Jun 2015, http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/
  3. Doxygen tool, project web site, accessed 1 Jun 2015, http://www.doxygen.org
  4. The Qt Help Framework, Qt documentation web site, accessed 1 Jun 2015, http://doc.qt.io/qt-5/qthelp-framework.html

Some Lesser Known Qt Tools and Commands – Part 4

Wednesday, July 8, 2015

In the next installment of this blog series on the lesser-known Qt commands, we’ll look at the QML-related tools that come with Qt 5.

qml

This program is the so-called QML tooling, which allows running QML files directly like a script, much like UNIX shell scripts or Python programs. I’ve covered this specific topic before and and refer you to that previous blog post1 for more details.

qmlbundle

Qmlbundle is a tool that allows combining resources, like QML and JavaScript files and images, into a single file. The idea is to simplify deployment by combining multiple source files into one bundle file. The current implementation is a prototype and is not mentioned in the Qt documentation. As the original developers have stopped working on it, a decision was made to remove qmlbundle in Qt 5.5.0. While it may come back again in the future in some form, currently there is no compelling reason to use this tool. Much of the same capability can be achieved by using Qt’s resource system.

qmleasing

Qmleasing is a graphical application that allows you to experiment and visualize easing curves. You can use the tool to assist in getting the desired effect, after which you copy and paste the control points into your code. A screen shot of the tool running is shown below. For more details, see the documentation for the QEasingCurve class.

qmlimportscanner

This tool parses and reports on QML imports to assist in deployment, so that the necessary QML modules are deployed as part of the application. It is used by Qt Creator and by the Mac OS X deployment tools.

qmllint

Because QML is interpreted at run-time, rather than compiled like C++ code, errors can go undetected until the offending code is executed, possibly when the end user is running it. The qmllint program, new in Qt 5.4, is a tool that checks QML files for correct syntax. It can be useful to run as part of a Continuous Integration (CI) system to detect errors at build time or on code check-in. It is covered in detail in this blog post2. The tool is quite new and does not detect all possible errors, but can be useful for catching errors earlier in the development process.

qmlmin

The qmlmin program is a utility that „minimizes“ a QML file, removing comments and layout characters. It can optionally restrict the output to a specific width. It is useful for reducing the size of QML code that needs to be deployed, resulting in smaller executables (when the code is stored as resources) and installers.

As an example, when run on the following simple QML example program:

// Simple QML example

import QtQuick 2.4

Rectangle {
  width: 640
  height: 480
  Text {
    anchors.centerIn: parent
    text: "Hello, world!"
  }
  MouseArea {
    anchors.fill: parent
    onClicked: {
      Qt.quit()
    }
  }
}

The output is this smaller, but equivalent, one line program:

import QtQuick 2.4;Rectangle{width:640;height:480;Text{anchors.centerIn:parent;text:"Hello, world!";}MouseArea{anchors.fill:parent;onClicked:{Qt.quit();}}}

Obviously, you will want to keep and work with the original commented and formatted QML code, and only use the minimized code for delivery.

qmlplugindump and qml1plugindump

The qmlplugindump utility is used to generate a .qmltypes type description file. These files are used by tools like Qt Creator to obtain information about the types used by plugins, so it is good practice to ship a type description file with QML plugins.

Qml1plugindump is a similar tool that works with Qt Quick 1.

For an example of using the tool to generate a .qmltypes file, see the Qt documentation section entitled „Using QML Modules with Plugins“.

qmlprofiler

The Qt QML module provides facilities for debugging, inspecting and profiling QML code via a TCP network port. The Qt Creator IDE provides a user interface for performance profiling of QML code.

The qmlprofiler command line tool is provided to capture profiling data to a file. It can be useful if you are not using Qt Creator or want to integrate profiling into some other development tool.

qmltestrunner

The qmltestrunner utility facilitates running unit tests on QML code written using the Qt Quick Test unit test framework. It isn’t currently documented very well, but I was able to find a tutorial 3 that was written as part of the Ubuntu developer documentation.

Summary

I hope you enjoyed this look at the QML-related Qt command line tools. Looking ahead, there are still more tools to cover, enough for at least one more installment in this blog series.

References

  1. The Whole Shebang – Running QML Files Directly, ICS blog post, accessed 1-Jun-2015, www.ics.com/blog/whole-shebang-running-qml-files-directly
  2. KDAB contributions to Qt 5.4: qmllint, KDAB blog post, accessed 1-Jun-2015, www.kdab.com/kdab-contributions-qt-5-4-qmllint/
  3. QML Unit testing, Ubuntu developer documentation, accessed 1-Jun-2015, developer.ubuntu.com/en/apps/qml/tutorials/qml-unit-testing/

Some Lesser Known Qt Tools and Commands – Part 5

Wednesday, July 22, 2015

In this blog post, the last in the series, I’ll cover the remaining Qt command line tools as there are only a few programs we have not already discussed.

xmlpatterns and xmlpatternsvalidator

These two XML-related tools are for working with Qt’s XQuery support. XQuery is a query and functional programming language for querying and transforming collections of structured and unstructured data.

The xmlpatterns command is a tool for running XQuery queries. The xmlpatternsvalidator program is used for validating Qt XML Patterns.

As a piece of useless trivia, xmlpatternsvalidator ties with qcollectiongenerator for the Qt tool with the longest file name, at twenty characters. The creators of UNIX, who preferred short commands like „ls“ and „cat“, would certainly not have been pleased with these choices.

The details of these commands are beyond the scope of what I can cover here. I refer you to the Qt documentation section on „XQuery“ 1 and the „C++ Source Code Analyzer Example“ 2.

qtplugininfo

The qtplugininfo command dumps meta-data about Qt plugins in JSON format. This command is new in the Qt 5.5.0 release. Here is an example of the output:

% qtplugininfo  /usr/local/Qt-5.5.0/plugins/imageformats/libqjpeg.so 

IID "org.qt-project.Qt.QImageIOHandlerFactoryInterface" Qt 5.5.0 (release)
User Data: {
    "Keys": [
        "jpg",
        "jpeg"
    ],
    "MimeTypes": [
        "image/jpeg",
        "image/jpeg"
    ]
}

Offhand, I’m not sure what it would be useful for exactly. Presumably, for development tools that interface with Qt plugins and need to query their capabilities.

qtdiag

This command outputs information about the current Qt install. It can be useful when users are reporting bugs, for example, to give details of Qt on the specific machine. The output can be quite long (more than 100 lines on my Linux desktop system). A partial output of the command is listed below.

Qt 5.5.0 (i386-little_endian-ilp32 shared (dynamic) release build; by GCC 4.8.2) on "xcb" 
OS: Ubuntu 14.04.2 LTS [linux version 3.13.0-53-generic]

Architecture: i386; features: SSE2 SSE3 SSSE3 SSE4.1 SSE4.2 AVX

Library info:
  PrefixPath: /usr/local/Qt-5.5.0
  DocumentationPath: /usr/local/Qt-5.5.0/doc
  HeadersPath: /usr/local/Qt-5.5.0/include
  LibrariesPath: /usr/local/Qt-5.5.0/lib

Standard paths [*...* denote writable entry]:
  DesktopLocation: "Desktop" */home/tranter/Desktop*
  DocumentsLocation: "Documents" */home/tranter*

Network:
  Using "OpenSSL 1.0.1f 6 Jan 2014", version: 0x1000106f

Platform capabilities: ThreadedPixmaps OpenGL ThreadedOpenGL WindowMasks MultipleWindows ForeignWindows NonFullScreenWindows NativeWidgets WindowManagement SyncState RasterGLSurface

LibGL Vendor: NVIDIA Corporation
Renderer: NVS 5200M/PCIe/SSE2
Version: 4.4.0 NVIDIA 331.113
Shading language: 4.40 NVIDIA via Cg compiler
Format: Version: 4.4 Profile: 0 Swap behavior: 0 Buffer size (RGB): 8,8,8 Depth buffer: 24

qtpaths

This program is a command line client to the QStandardPaths class. I’ve previously written a blog post 3 on this topic. It can be useful to run from scripts that need to determine information about the current system, such as the location of Qt binaries.

Below is some sample output showing three different invocations of the program.

% qtpaths --types
ConfigLocation
DesktopLocation
DocumentsLocation
DownloadLocation
FontsLocation
GenericCacheLocation
GenericConfigLocation
GenericDataLocation
HomeLocation
MoviesLocation
MusicLocation
PicturesLocation
RuntimeLocation

% qtpaths --binaries-dir
/usr/local/Qt-5.5.0/bin

% qtpaths --paths DownloadLocation
/home/tranter/Downloads

qtwaylandscanner

This program is part of the Qt Wayland module, which supports using Wayland, a new replacement for X11. A previous blog 4 post covered how to get Wayland running on the Raspberry Pi platform. I hope to talk more about Qt and Wayland in a future blog post.

sdpscanner

This is a utility program provided as part of Qt’s Bluetooth module. It performs a scan on a remote Bluetooth using Service Discovery Protocol (SDP). SDP allows service applications running on different Bluetooth devices to discover each other’s existence and exchange information on their characteristics.

syncqt.pl

This program, a Perl script, is a development tool that synchronizes Qt header files. If you work with a git clone of Qt and change branches, running this tool will perform some actions that are needed to avoid build errors due to Qt’s forwarding headers in the include directories. It can be run after doing a „git pull“ or „git checkout“.

Summary

At a recent ICS Qt training class, the students asked the instructor the purpose of each of the programs in the Qt binary directory. Surprisingly, there was no obvious place to get that information. That indicated to me that this web series was useful, and we may in fact include some of the content in our training material.

With that, we have completed this series on the lesser-known Qt commands. I may update it in the future to cover any new commands that may be added in upcoming Qt releases.

References

  1. XQuery Introduction, Qt documentation, accessed 1 Jul 2015, doc.qt.io/qt-5/xmlprocessing.html
  2. C++ Source Code Analyzer Example, Qt documentation, accessed 1 Jul 2015, doc.qt.io/qt-5/qtxmlpatterns-xquery-example.html
  3. What’s new in Qt 5: QStandardPaths, ICS blog post, accessed 1 Jul 2015, www.ics.com/blog/whats-new-qt-5-qstandardpaths
  4. Building Qt and QtWayland for Raspberry Pi, ICS blog post, accessed 1 Jul 2015, www.ics.com/blog/building-qt-and-qtwayland-raspberry-pi

Schreibe einen Kommentar

Trage deine Daten unten ein oder klicke ein Icon um dich einzuloggen:

WordPress.com-Logo

Du kommentierst mit Deinem WordPress.com-Konto. Abmelden / Ändern )

Twitter-Bild

Du kommentierst mit Deinem Twitter-Konto. Abmelden / Ändern )

Facebook-Foto

Du kommentierst mit Deinem Facebook-Konto. Abmelden / Ändern )

Google+ Foto

Du kommentierst mit Deinem Google+-Konto. Abmelden / Ändern )

Verbinde mit %s