QM  7.0.0
Model-Based Design Tool
Loading...
Searching...
No Matches
Working with Files

Working with DirectoriesCode Generation

As described in the section about the physical design, QM™ provides special file items that represent files to be generated on disk. The file items can only exist inside a directory item, which determines the location of the file relative to the QM Model File or the External Package File, for files nested inside External Packages.

Internal Files

Normally, the file items are just "templates" for the files to be created on disk. Such file-templates are called internal files and can be edited in the MDI windows at the center of the QM user interface, which work exactly like any other modern code editor.

You can insert any code (or text) into the file-templates, such as #include directives, declarations, definitions, comments, and anything else that you would put into hand-crafted code. All this code will then be literally copied over to the files generated on disk. But, the twist here is that you can also direct QM to generate specific parts of the code based on the model items of your choosing, with the granularity ranging from packages and classes, down to specific state machines, states, attributes, and operations.

QM Code Generation as Expansion of Code-Generation Directives

You achieve this by inserting the special Code-Generation Directives into your file-templates. For example, you can direct QM to generate a class declaration in one place of a file on disk, a class definition in another place, and so on.

Attention
The files generated from Internal Files should not be edited manually outside the QM™ tool, because the whole body of the file will be re-generated and any edits would be lost. Therefore, to prevent inadvertent change of the files generated on disk, these files are saved as read-only.

External Files

QM also supports External Files, which can be edited outside QM tool with any editor you like. Such External Files combine user-code with the generated-code and possibly Code-Generation Directives. This merging of a file-template with generated-code is achieved by clearly delimiting the generated-sections with special comments. Such External Files can be edited inside any editor/IDE of choice and are not editable inside QM. The following listing shows an example of an External File on disk (the comments after the listing explain the interesting lines of code):

1///$file${.::calc1_sub.cpp} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
2//
3// Model: calc1_sub.qm
4// File: ${.::calc1_sub.cpp}
5//
6// This code has been generated by QM 5.2.5 <www.state-machine.com/qm>.
7// DO NOT EDIT THIS FILE MANUALLY. All your changes will be lost.
8//
9// SPDX-License-Identifier: GPL-3.0-or-later
10//
11// This generated code is open source software: you can redistribute it under
12// the terms of the GNU General Public License as published by the Free
13// Software Foundation.
14//
15// This code is distributed in the hope that it will be useful, but WITHOUT
16// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
17// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
18// more details.
19//
20// NOTE:
21// Alternatively, this generated code may be distributed under the terms
22// of Quantum Leaps commercial licenses, which expressly supersede the GNU
23// General Public License and are specifically designed for licensees
24// interested in retaining the proprietary status of their code.
25//
26// Contact information:
27// <www.state-machine.com/licensing>
28// <info@state-machine.com>
29//
30//$endhead${.::calc1_sub.cpp} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
31#include "qpcpp.h" // QP/C++ API
32#include "bsp.hpp" // Board Support Package
33#include "calc.hpp" // Application
34. . .
35$declare ${SMs::Calc}
36
37static Calc l_calc; // the only instance of the Calc class
38
39// global-scope definitions --------------------------------------
40QP::QMsm * const the_calc = &l_calc; // "opaque" pointer to MSM
41. . .
42
43//$skip${QP_VERSION} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
44// Check for the minimum required QP version
45#if (QP_VERSION < 700U) || (QP_VERSION != ((QP_RELEASE^4294967295U) % 0x3E8U))
46#error qpcpp version 7.0.0 or higher required
47#endif
48//$endskip${QP_VERSION} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
49
50//$define${SMs::the_calc} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
51
52//${SMs::the_calc} ...........................................................
53QP::QHsm * const the_calc = &Calc::inst;
54//$enddef${SMs::the_calc} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
55//$define${SMs::Calc} vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
56
57//${SMs::Calc} ...............................................................
58Calc Calc::inst;
59
60//${SMs::Calc::Calc} .........................................................
61Calc::Calc()
62 : QMsm(&initial)
63{}
64. . .
65//$enddef${SMs::Calc} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1..30 Top-level file comment generated by QM.
NOTE: This code (between the $file${..} vvvvvv and $endhead${..} ^^^^^^^ should NOT be edited manually.

21..34 user-code (editable)

35 code-generation directive (editable)

37..41 user-code (editable)

43..48 QP version requirement comment generated by QM.
NOTE: This code (between the $skip${..} vvvvvv and $endskip${..} ^^^^^^^ should NOT be edited manually.

50..65 code generated by QM by expanding the directive $define ${SMs::Calc}
NOTE: This code (between the $define${..} vvvvv and $enddef${..} ^^^^^^^^ should NOT be edited manually.

Attention
The files generated from External Files are saved as writable because the user can edit parts of these files. However, the generated sections delimited between the comments "$...vvv" and "$end...^^^" should NOT be edited, because they will be re-generated and any edits in these sections would be lost.

Adding a New File

The file items can only exist inside a directory item, which determines the location of the file relative to the QM Model File. Therefore, to add a new file item, you first need to select the directory item in the Model Explorer. Then right-click on this directory item and select the "Add File" in the popup menu, as shown below:

Adding a file item to a directory item

File Property Sheet

The following picture shows the Property Sheet of a File Item (see Property Editor):

File Item Property Sheet

File Name

The most important property of a file item is its name. QM™ automatically recognizes several file types based on the file name extension and applies a special icon for the recognized files. The following table shows the list of recognized file types and icons:

File Name Extension File Type File Icon
.h C/C++ header file  
.hpp C++ header file  
.c C implementation file  
.cpp C++ implementation file  
.cxx C++ implementation file  
.cc C++ implementation file  
.ino Arduino sketch  
.py Python script  
.mak make file  
makefile make file  
Makefile make file  
Note
Providing one of the recognized file name extensions is necessary for QM™ to be able to apply the correct syntax highlighting for the file type. The file name extensions are case-sensitive.

Encoding

The encoding drop-box property of the file item allows you to select one of the few dozens of available character encodings↑ for your file. This option might be interesting if you use special characters outside the basic ASCII character set. (NOTE: the default setting corresponds to the encoder selected in your operating system.)

External

The "external" check box designates a file as an External File that is not managed by QM, but still participates in the code generation. Such "external" files can be edited with an editor/IDE of choice.

Unix End-Of-Line Convention

QM™ applies consistently the Unix end-of-line convention↑ (single LF octet at the end of line) to all files saved on disk, regardless of the host operating system. This is done intentionally to generate identical code across diverse hosts, which might be used by various team members potentially using different operating systems.

Note
Because the LF-only end-of-line convention is nonnative on Windows, the generated files might look incorrect in some text editors (e.g., Notepad↑). However, experience shows that most programming editors designed for editing code should have no problem correctly displaying the generated code.

Working with DirectoriesCode Generation