Generated HTML for Release 3.1.0

Author: Sonia Mathew

docs/art-lang/cpp-extensions/index.html

@@ -1409,12 +1409,13 @@ <h2 id="excluding-source-files">Excluding Source Files</h2>
 </code></pre>
 <p>If you have set-up the TC to place generated C++ files in a subfolder of the workspace folder, you don't have to exclude them by means of the <a href="../transformation-configurations/#sources"><code>sources</code></a> TC property. Generated files will always be included in the build exactly once, no matter where they are located. </p>
 <h2 id="c-extension-source-code-analysis">C++ Extension Source Code Analysis</h2>
-<p>The C++ extension that you use with Code RealTime makes use of JSON files for knowing how to analyze C++ source code. Such JSON files are automatically generated by the C++ code generator based on information provided in the TC:</p>
+<p>The C++ extension that you use with Code RealTime makes use of JSON files for knowing how to analyze C++ source code. It needs to do this to provide editing features such as content assist, navigation and hover tooltips. The JSON files are automatically generated by the C++ code generator based on information provided in the TC:</p>
 <ul>
-<li>For the <a href="https://code.visualstudio.com/docs/languages/cpp">Microsoft C++ extension</a> a file called <a href="https://code.visualstudio.com/docs/cpp/c-cpp-properties-schema-reference"><code>c_cpp_properties.json</code></a> is used</li>
-<li>For the <a href="https://clangd.llvm.org/">Clangd extension</a> a file called <a href="https://clang.llvm.org/docs/JSONCompilationDatabase.html"><code>compile_commands.json</code></a> is used</li>
+<li>For the <a href="https://code.visualstudio.com/docs/languages/cpp">Microsoft C++ extension</a> a file called <a href="https://code.visualstudio.com/docs/cpp/c-cpp-properties-schema-reference"><code>c_cpp_properties.json</code></a> is used. It's placed in the <code>.vscode</code> subfolder.</li>
+<li>For the <a href="https://clangd.llvm.org/">Clangd extension</a> a file called <a href="https://clang.llvm.org/docs/JSONCompilationDatabase.html"><code>compile_commands.json</code></a> is used. It's placed in the root folder.</li>
 </ul>
-<p>When you add C++ source files to a workspace folder that you want to build together with the Art files it contains, you should also create such a JSON file to enable the C++ extension to also analyze these files. Without doing so, features such as content assist, navigation and hover tooltips will not work when you edit those files. Rather than creating these files manually it's often easiest to copy the ones that are generated by the C++ code generator from the target folder, and then modify them as required. The most important thing to get right is the inclusion paths to make sure the C++ extension is able to find all include files required by a certain C++ source file.</p>
+<p>These JSON files are always generated into the target folder, but they are only generated into the source workspace folder if it contains at least one C++ source file. </p>
+<p>If a workspace folder has more than one TC, each building a subset of the source files present in the workspace folder, then the C++ extension may show errors for those source files that are not source elements of the currently active TC. This can be seen in the sample <a href="../../samples/#socketinterface">SocketInterface</a> where two TCs build a server and a client application that have some source files in common. A way to avoid such errors can be to break out common source files and build them into a library which multiple applications then can link with.</p>
 
 
 

docs/art-lang/images/number_of_elements_function_content_assist.png

@@ -1100,6 +1100,13 @@
     sources
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#sourcesubdirectory" class="md-nav__link">
+    sourceSubdirectory
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -1149,6 +1156,13 @@
     unitName
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unitsubdirectory" class="md-nav__link">
+    unitSubdirectory
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -1765,6 +1779,13 @@
     sources
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#sourcesubdirectory" class="md-nav__link">
+    sourceSubdirectory
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -1814,6 +1835,13 @@
     unitName
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#unitsubdirectory" class="md-nav__link">
+    unitSubdirectory
+  </a>
+  
 </li>
 
           <li class="md-nav__item">
@@ -1858,7 +1886,7 @@ <h1>Transformation Configurations</h1>
 <p>A transformation configuration (or TC for short) contains all properties needed for transforming Art files into C++ code and for building the generated code into an application or a library. It is a text file in JavaScript format with the file extension .tcjs. Using JavaScript for defining build properties has many advantages. For example, it allows for <a href="../build-variants/#dynamic-transformation-configurations">dynamic properties</a> where the value is not a static value but computed dynamically by JavaScript code when the TC is built.</p>
 <p>Code RealTime provides a dedicated language server for TCs to make them just as easy to work with as Art files. A <a href="#form-based-tc-editor">form-based editor</a> is also provided as an alternative.</p>
 <h2 id="creating-transformation-configurations">Creating Transformation Configurations</h2>
-<p>To create a new TC select a file in the workspace folder that contains the Art files you want to transform to C++. Then invoke the command <strong>File - New File - Transformation Configuration</strong>. In the popup that appears specify the name of the TC or keep the suggested default name.</p>
+<p>To create a new TC select a file in the workspace folder that contains the Art files you want to transform to C++. Then invoke the command <strong>File - New File - New Transformation Configuration</strong>. In the popup that appears specify the name of the TC or keep the suggested default name.</p>
 <p><img alt="" src="../images/default-tc-name.png" /></p>
 <p>A .tcjs file will be created with the minimal contents. Specify the mandatory <a href="#topcapsule">topCapsule</a> property (if you are building an executable) and any other <a href="#properties">properties</a> needed.</p>
 <h2 id="setting-a-transformation-configuration-as-active">Setting a Transformation Configuration as Active</h2>
@@ -2061,6 +2089,11 @@ <h2 id="properties">Properties</h2>
 <td align="left">["*.art"]</td>
 </tr>
 <tr>
+<td><a href="#sourcesubdirectory">sourceSubdirectory</a></td>
+<td align="left">String</td>
+<td align="left">N/A</td>
+</tr>
+<tr>
 <td><a href="#targetconfiguration">targetConfiguration</a></td>
 <td align="left">String</td>
 <td align="left">Depends on current operating system</td>
@@ -2096,6 +2129,11 @@ <h2 id="properties">Properties</h2>
 <td align="left">"UnitName"</td>
 </tr>
 <tr>
+<td><a href="#unitsubdirectory">unitSubdirectory</a></td>
+<td align="left">String</td>
+<td align="left">N/A</td>
+</tr>
+<tr>
 <td><a href="#userlibraries">userLibraries</a></td>
 <td align="left">List of strings</td>
 <td align="left">[]</td>
@@ -2197,6 +2235,10 @@ <h3 id="sources">sources</h3>
 <p>You can find a sample application that has a TC with the "sources" property set <a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/tc_sources">here</a>.</p>
 </div>
 <p>The <code>sources</code> property can also be used to specify which regular (i.e. non-generated) C++ files that should be included in the build. See <a href="../build-cpp-files/#excluding-source-files">this chapter</a> for more information.</p>
+<h3 id="sourcesubdirectory">sourceSubdirectory</h3>
+<p>This property can be set to place generated source files into a sub folder within the <a href="#targetfolder">target folder</a>. It should be a string that is valid as the name of a folder.</p>
+<pre><code class="language-js">tc.sourceSubdirectory = 'subdir';
+</code></pre>
 <h3 id="targetconfiguration">targetConfiguration</h3>
 <p>Specifies which <a href="../../target-rts/#target-configurations">TargetRTS configuration</a> to use. The TargetRTS location specified in the <a href="#targetrtslocation">targetRTSLocation</a> property defines valid values for this property. If this property is not specified, and the default TargetRTS location from the Code RealTime installation is used, then it will get a default value according to the operating system that is used. For Windows a MinGw-based configuration will be used, while for Linux a GCC-based configuration will be used.</p>
 <pre><code class="language-js">tc.targetConfiguration = &quot;WinT.x64-VisualC++-17.0&quot;;
@@ -2261,6 +2303,10 @@ <h3 id="topcapsule">topCapsule</h3>
 <p>If you don't specify a value for this property, the TC will build a library instead of an executable.</p>
 <h3 id="unitname">unitName</h3>
 <p>Specifies the base name of the so called unit header and implementation files that are generated from the TC. By default the value of this property is <code>UnitName</code> which means that these unit files will be called <code>UnitName.cpp</code> and <code>UnitName.h</code>. The unit files contain certain information that applies to the whole unit of code that is generated from a TC. The header unit file is included by all files that are generated from the TC.</p>
+<h3 id="unitsubdirectory">unitSubdirectory</h3>
+<p>This property can be set to place the generated unit files (see <a href="#unitname">unitName</a>) into a sub folder within the <a href="#targetfolder">target folder</a>. It should be a string that is valid as the name of a folder.</p>
+<pre><code class="language-js">tc.unitSubdirectory = 'unitSubDir';
+</code></pre>
 <h3 id="userlibraries">userLibraries</h3>
 <p>This property is a list of user libraries that should be linked with the application. The property is only applicable for TCs that build executables.</p>
 <pre><code class="language-js">tc.userLibraries = [&quot;../../libs/libMyLib.a&quot;];

docs/art-lang/index.html

@@ -426,6 +426,29 @@ <h2>
                 </div>
             </div>
 
+            <div class="persona-item">
+                <div class="feature-5">
+                    <!-- persona image -->
+                </div>
+                <div class="persona-name black">
+                    <h2>
+                        Tracing
+                    </h2>
+                </div>
+                <div class="persona-body body-text black">
+                    <p>
+                        Capture and analyze run-time traces from your application and visualize them graphically as sequence diagrams
+                    </p>
+                </div>
+                <div class="persona-button">
+
+                    <p><a href="running-and-debugging/tracing" class="md-button">
+                            Read More
+                        </a>
+                    </p>
+                </div>
+            </div>
+
         </div>
     </div>
 

docs/assets/art-trace.png

@@ -20,7 +20,7 @@
 
 
 
-        <title>3.0.0 (2025-09-23 15:57) - DevOps Code RealTime</title>
+        <title>3.1.0 (2025-11-19 12:02) - DevOps Code RealTime</title>
 
 
 
@@ -88,7 +88,7 @@
     <div data-md-component="skip">
 
 
-        <a href="#300-2025-09-23-1557" class="md-skip">
+        <a href="#310-2025-11-19-1202" class="md-skip">
           Skip to content
         </a>
 
@@ -120,7 +120,7 @@
         <div class="md-header__topic" data-md-component="header-topic">
           <span class="md-ellipsis">
 
-              3.0.0 (2025-09-23 15:57)
+              3.1.0 (2025-11-19 12:02)
 
           </span>
         </div>
@@ -1295,6 +1295,30 @@
 
 
 
+<h1 id="310-2025-11-19-1202">3.1.0 (2025-11-19 12:02)</h1>
+<ol>
+<li>A new diagram setting has been added to control if excluded elements should be shown or not in state and structure diagrams. It's available both as a global workspace setting and as a setting for an individual diagram (i.e. a new checkbox in the Properties view). If shown, excluded transitions are now drawn with a "crossed" line style to be consistent with how other excluded elements are shown.</li>
+<li>The support for visualizing C++ code in class diagrams has been improved. Now it handles C++ code both inside <code>[[rt::decl]]</code> code snippets in an Art file as well as in a regular C++ header file (<code>.h</code>). In addition to inheritance relationships, associations and composition relationships are also shown. You can click symbols and lines on these diagrams to navigate to the corresponding C++ declaration.</li>
+<li>Diagram layout settings are now validated and warnings are reported in case some problem in a layout setting file prevents it from being used when the diagram is opened. Such problems can for example occur as a result of a faulty merge, or a rename refactoring that failed to update all references to the renamed element in layout files.</li>
+<li>The C++ language server files (<code>c_cpp_properties.json</code> and <code>compile_commands.json</code>) are now generated automatically in a workspace folder. These files are needed when your workspace folder contains C++ source files, and previously it was necessary to write and maintain these files manually which was tedious.</li>
+<li>Use of deep history in class state machines is now supported.</li>
+<li>Field descriptors for member variables of array type are now generated so that by default all elements of the array will be included when encoding it. Previously only the first element was included. The C++ code generator also supports to define a custom "number of elements" function for such a field descriptor to exclude some of the trailing array elements from the encoding.</li>
+<li>Code generation for field descriptors can now be customized by means of three new C++ attributes that can be set on member variables: <code>[[rt::no_descriptor]]</code>, <code>[[rt::no_type_modifier]]</code> and <code>[[rt::type_descriptor]]</code>. Read more about these attributes <a href="https://secure-dev-ops.github.io/code-realtime/art-lang/cpp-extensions/#field-descriptor">in the documentation</a>.</li>
+<li>The code generator supports two new properties for a capsule and a class with state machine. The properties <code>generate_file_header</code> and/or <code>generate_file_impl</code> can be set to <code>false</code> to prevent generation of the header and/or implementation file for the capsule/class. This can for example be useful if you prefer to write one or both of these files manually.</li>
+<li>For a class with state machine the code generator supports a new property <code>kind</code> which, if set to <code>struct</code>, will generate a struct instead of a class for it.</li>
+<li>It's now possible to use a type descriptor for a class with state machine. Set the property <code>generate_descriptor</code> to <code>true</code> to use an automatically generated type descriptor, or set it to <code>manual</code> if you prefer to implement the type descriptor yourself. Customization of type descriptor functions works in the same way as for C++ types, i.e. just provide your custom implementation for the type descriptor functions you need to customize, and the code generator will then use these instead of the default ones.</li>
+<li>Two new TC properties <code>sourceSubdirectory</code> and <code>unitSubdirectory</code> are supported by the Art Compiler. They can be set to place generated code and/or generated unit files into sub directories.</li>
+<li>Captured traces may now include an "external" instance (with address 0x0) to represent the injection of external messages into an application. Typical examples of such external messages include programmatic injection of messages on ports and when using the Art Debugger for sending events on ports during a debug session. But in general they represent an "unknown sender" and are used whenever it's not possible to determine the sender of a received message.</li>
+<li>Captured traces now contain information about the port on which a received message was sent, as well as the port index (both for the sender and receiver port).</li>
+<li>What to include in a trace file can now be configured by means of a JSON configuration file. For example, it's possible to configure tracing so that it includes timestamps for when a message was received and handled. Such information can be used when analyzing the performance of an application based on captured traces.</li>
+<li>The parser for <code>.art-trace</code> files has been published as open source on <a href="https://github.com/HCL-TECH-SOFTWARE/art-trace">GitHub</a> and is also available as an <a href="https://www.npmjs.com/package/art-trace">npm package</a>. This makes it possible to write your own scripts for analyzing, translating or visualizing traces. A few examples of such scripts are included in the GitHub repository.</li>
+<li>The sequence diagram viewer for trace files now supports navigation from lifeline headers to instances, and from message arrows to messages in the trace file.</li>
+<li>A <a href="https://secure-dev-ops.github.io/code-realtime/target-rts/message-communication/#custom-controller">new chapter in the documentation</a> describes the TargetRTS class <code>RTCustomController</code> which allows a capsule to customize the event loop of its controller. A typical example of such a customization is to integrate socket communication in the event loop, and this is shown in <a href="https://secure-dev-ops.github.io/code-realtime/samples/#socketinterface">a new sample application</a>.</li>
+<li>The TargetRTS and Art Compiler now supports the wide character primitive type (<code>wchar_t</code>). For example, you can encode and decode wide characters and arrays of wide characters.</li>
+<li>The TargetRTS provides a new utility <code>RTLock</code> for protecting a piece of code from being run by more than one thread at the same time.</li>
+<li>The TargetRTS now supports printing 64 bit integers with its <code>RTFormat</code> class. </li>
+<li>Version 2.1.0 of the Art Exporter is now available. Among many other improvements it now can export layout information for state diagrams. See <a href="https://model-realtime.hcldoc.com/help/topic/com.ibm.xtools.rsarte.webdoc/Utilities/Art%20Exporter.html">this page</a> for more detailed release notes for the Art Exporter.</li>
+</ol>
 <h1 id="300-2025-09-23-1557">3.0.0 (2025-09-23 15:57)</h1>
 <ol>
 <li>The size of parent symbols are now automatically increased when a nested child symbol is moved outside the boundaries of the parent symbol, so that the child symbol still fits within the parent symbol afterwards. This simplifies movement of nested symbols and avoids the step of first having to resize the parent symbol. </li>