Using the Qt SCXML Compiler (qscxmlc)¶

The Qt SCXML Compiler, qscxmlc, compiles state chart XML (.scxml) files to C++ source files.

The qscxmlc tool reads an .scxml file and produces C++ source and header files, containing a class that implements a state machine as defined in SCXML.

Usage¶

The qscxmlc tool is invoked automatically if the project is linked against the scxml library in the project file, and the .scxml file to use is specified using the special build directives STATECHARTS or qt6_add_statecharts.

When using cmake:

find_package(Qt6 REQUIRED COMPONENTS Scxml)
target_link_libraries(mytarget PRIVATE Qt6::Scxml)

qt6_add_statecharts(mytarget
    MyStatemachine.scxml
)

When using qmake:

QT += scxml

STATECHARTS = MyStatemachine.scxml

With above definitions, qmake or cmake invokes qscxmlc to generate MyStatemachine.h and MyStatemachine.cpp, and adds them appropriately to the project as headers and sources.

By default, the name of the generated class that implements the state machine corresponds with the name attribute of the <scxml> root element.

The qscxmlc tool can also be invoked manually and the resulting header and source files can be used as regular source files in a project. When using these source files as part of a cmake project, one must additionally disable automatic moc in the CMakeLists.txt file as illustrated by this example:

set_source_files_properties(statemachine.h PROPERTIES SKIP_AUTOMOC TRUE)

If you omit this, you will see duplicate symbol errors during compilation.

Command-Line Options¶

The qscxmlc tool supports the following command-line options:

Option

Description

--namespace <namespace>

Put the generated class(es) in the specified namespace.

-o <base/out/name>

The base name of the output files. This can include a path. If none is specified, the basename of the input file is used.

--header <header/out>

The name of the output header file. If none is specified, .h is added to the base name.

--impl <cpp/out>

The name of the output header file. If none is specified, .cpp is added to the base name.

--classname <StateMachineClassName>

The class name of the generated state machine. If none is specified, the value of the name attribute of the <scxml> tag is taken. If that attribute is not specified either, the basename (excluding path) is taken from the input file name.

--statemethods

Generate extra accessor and signal methods for states. This way you can connect to state changes with plain QObject::connect() and directly call a method to find out if a state is currently active.

Option	Description
`--namespace <namespace>`	Put the generated class(es) in the specified namespace.
`-o <base/out/name>`	The base name of the output files. This can include a path. If none is specified, the basename of the input file is used.
`--header <header/out>`	The name of the output header file. If none is specified, .h is added to the base name.
`--impl <cpp/out>`	The name of the output header file. If none is specified, .cpp is added to the base name.
`--classname <StateMachineClassName>`	The class name of the generated state machine. If none is specified, the value of the name attribute of the <scxml> tag is taken. If that attribute is not specified either, the basename (excluding path) is taken from the input file name.
`--statemethods`	Generate extra accessor and signal methods for states. This way you can connect to state changes with plain QObject::connect() and directly call a method to find out if a state is currently active.

The qmake and CMake project files support the following options:

Option

Description

QSCXMLC_DIR|OUTPUT_DIRECTORY <directory>

QSCXMLC_DIR (qmake) or OUTPUT_DIRECTORY (cmake) specifies the directory for the output files. OUTPUT_DIR (cmake) has been deprecated.

QSCXMLC_NAMESPACE|NAMESPACE <namespace>

QSCXMLC_NAMESPACE (qmake) or NAMESPACE (cmake) specifies the namespace for the generated classes.

QSCXMLC_ARGUMENTS|OPTIONS <options>

QSCXMLC_ARGUMENTS (qmake) or OPTIONS (cmake) allows specifying additional options for the qscxmlc compiler. QSCXMLC_ARGUMENTS with cmake has been deprecated.

Option	Description
`QSCXMLC_DIR\|OUTPUT_DIRECTORY <directory>`	`QSCXMLC_DIR` (qmake) or `OUTPUT_DIRECTORY` (cmake) specifies the directory for the output files. OUTPUT_DIR (cmake) has been deprecated.
`QSCXMLC_NAMESPACE\|NAMESPACE <namespace>`	`QSCXMLC_NAMESPACE` (qmake) or `NAMESPACE` (cmake) specifies the namespace for the generated classes.
`QSCXMLC_ARGUMENTS\|OPTIONS <options>`	`QSCXMLC_ARGUMENTS` (qmake) or `OPTIONS` (cmake) allows specifying additional options for the `qscxmlc` compiler. QSCXMLC_ARGUMENTS with cmake has been deprecated.