The Whole Shebang - Running QML Files Directly

The Whole Shebang - Running QML Files Directly

By Jeff Tranter

A new feature in Qt version 5 is an executable program similar to qmlscene that can execute QML files. It is sometimes referred to as the QML Tooling or QML Run-time, although both of these terms are sometimes used to refer to other aspects of QML. A few colleagues mentioned to me that they were not familiar with this feature of Qt, so I thought it would make a good topic for a short blog post.

The program is called qml. Unlike qmlscene, it supports the standard shebang (1) feature of Linux, UNIX and other POSIX systems that allows specifying the interpreter to run a program. By placing a line like the one below at the top of a QML file, and making it executable (e.g. chmod +x), you can directly run the file as a program:

#!/usr/local/Qt-5.3.1/bin/qml

The shebang feature requires specifying the full path to the command. However, the qml program is not always in a fixed location. For example, I typically have several Qt installs on my development system and switch between them by changing my search path. This problem can be solved by using the env command to pick up a program from the path. The line below will pick up whatever qml executable is found first in the search path:

#!/usr/bin/env qml

As a simple example, try running the short QML program below. Remember to make it executable (e.g. by running chmod +x example.qml).

#!/usr/bin/env qml

import QtQuick 2.2

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

A screen shot is shown below:

 

 

 

 

 

This feature will work on Linux, UNIX and other POSIX systems. I don't have access to a Macintosh computer, but I am told it also works on Mac OS X. It doesn't work on Windows, although you could set a file association between the qml file extension and the qml program.

As of Qt 5.3.1, the qml program is not documented in the Qt documentation. The command accepts a number of options, some of which are the same as the qmlscene program. Here is the help usage output of the qml command:

Usage: qml [options] [files]

Any argument ending in .qml will be treated as a QML file to be loaded.
Any number of QML files can be loaded. They will share the same engine.
Any argument which is not a recognized option and which does not end in .qml will be ignored.
'gui' application type is only available if the QtGui module is available.
'widget' application type is only available if the QtWidgets module is available.

General Options:
    -h, -help..................... Print this usage information and exit.
    -v, -version.................. Print the version information and exit.
    -apptype [core|gui|widget] ... Select which application class to use. Default is gui.
    -quiet ....................... Suppress all output.
    -I [path] .................... Prepend the given path to the import paths.
    -f [file] .................... Load the given file as a QML file.
    -config [file] ............... Load the given file as the configuration file.
    -- ........................... Arguments after this one are ignored by the launcher, but may be used within the QML application.
    Debugging options:
    -verbose ..................... Print information about what qml is doing, like specific file urls being loaded.
    -translation [file] .......... Load the given file as the translations file.
    -dummy-data [directory] ...... Load QML files from the given directory as context properties.
    -slow-animations ............. Run all animations in slow motion.
    -fixed-animations ............ Run animations off animation tick rather than wall time.

The source code for the program can be found in the Qt source distribution under the directory qtdeclarative/tools/qml.

Summary

The usefulness of this tool is somewhat limited, because it only works for self-contained QML files and most real-world applications have some C++ code. However, it can be useful for applications such as tests and small demo programs. You might want to consider using it for small applications that you would have normally written as a shell script, but with QML (and JavaScript) can be done in a more portable way, as well as supporting a graphical user interface.

References

  1. Shebang (Unix), accessed June 5, 2014, en.wikipedia.org/wiki/Shebang_(Unix)