Generated HTML for Release 2.0.7

Author: Sonia Mathew

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

@@ -542,6 +542,13 @@
     Inheritance
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#generated-files" class="md-nav__link">
+    Generated Files
+  </a>
+  
 </li>
 
       </ul>
@@ -1340,6 +1347,13 @@
     Inheritance
   </a>
 
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#generated-files" class="md-nav__link">
+    Generated Files
+  </a>
+  
 </li>
 
       </ul>
@@ -1367,7 +1381,9 @@
 
   <h1>C++ Extensions</h1>
 
-<p>An Art file may contain code snippets at various places, where the C++ code within these snippets takes the form of expressions (e.g., guard conditions), statements (e.g., transition effects), or declarations (e.g., types, functions, variables, etc.). While most code snippets are copied directly to the generated C++ files during the translation process from an Art file to C+, certain snippets containing declarations (specifically, those marked as <code>rt::decl</code> and <code>rt::impl</code>) undergo parsing and analysis by the code generator. The code generator identifies and processes certain C+ extensions, such as attributes applied to the declarations in these snippets, translating them into additional C++ code. This capability enables the code generator to enhance the C++ code you write by incorporating additional boilerplate code. This chapter provides details on the applicable C++ extensions and the corresponding generated code for each.</p>
+<p>An Art file may contain code snippets at various places, where the C++ code within these snippets takes the form of expressions (e.g., guard conditions), statements (e.g., transition effects), or declarations (e.g., types, functions, variables, etc.). While most code snippets are copied directly to the generated C++ files during the translation process from an Art file to C++, certain snippets containing declarations (specifically, those marked as <code>rt::decl</code> and <code>rt::impl</code>) undergo parsing and analysis by the code generator. The code generator identifies and processes certain C+ extensions, such as attributes applied to the declarations in these snippets, translating them into additional C++ code. This capability enables the code generator to enhance the C++ code you write by incorporating additional boilerplate code. </p>
+<p>An alternative to using <code>rt::decl</code> and <code>rt::impl</code> code snippets in an Art file is to directly <a href="../../building/build-cpp-files/">include C++ source files</a> in your workspace folder. Code in such C++ files are also analyzed by the code generator, and extra code will be generated from attributes present in them. The main difference in this case is that the extra code will be placed in separate generated files, since there is no Art file that will be translated to C++ where it could be placed. See <a href="#generated-files">Generated Files</a> for more information.</p>
+<p>This chapter provides details on the applicable C++ extensions and the corresponding generated code for each.</p>
 <h2 id="type-descriptor">Type Descriptor</h2>
 <p>A type descriptor is meta data about a C++ type. The <a href="../../target-rts/">TargetRTS</a> uses the type descriptor to know how to initialize, copy, move, destroy, encode and decode an instance of the type. Type descriptors for all primitive C++ types are included in the TargetRTS, but for other types you need to ensure type descriptors are available if you plan to use them in a way where the TargetRTS needs it.</p>
 <div class="admonition note">
@@ -1537,6 +1553,41 @@ <h3 id="automatically-generated">Automatically Generated</h3>
 `
 </code></pre>
 <p>Note that the default implementation of a type descriptor for a typedef or type alias makes the assumption that the typedefed or aliased type is a structured type which has both a parameterless constructor, a copy constructor and a move constructor. If this assumption is not correct, you need to write your own type descriptor functions, or even <a href="#manually-implemented">implement the whole type descriptor manually</a>.</p>
+<p>If your <code>[[rt::auto_descriptor]]</code> marked type is defined in a C++ header file (see <a href="../../building/build-cpp-files/">C++ Source Files</a>), and you want to customize its type descriptor, you need to declare the custom type descriptor functions in the header file, and then implement them in a C++ implementation file. Here is the above example again, but now using C++ source files <code>MyTypes.h</code> and <code>MyTypes.cpp</code> instead of an Art file.</p>
+<p><em>MyTypes.h</em></p>
+<pre><code class="language-cpp">    #ifndef MyTypes_h
+    #define MyTypes_h
+
+    #include &quot;RTStructures.h&quot;
+    #include &lt;string&gt;
+
+    enum class [[rt::auto_descriptor]] Colors { 
+        Red, Green, Yellow 
+    }; 
+
+    void rtg_Colors_init(const RTObject_class * type, Colors * target);
+
+    typedef std::string [[rt::auto_descriptor]] MyString;
+
+    int rtg_MyString_encode(const RTObject_class* type, const MyString* source, RTEncoding* coding);
+
+    #endif // MyTypes_h
+</code></pre>
+<p><em>MyTypes.cpp</em></p>
+<pre><code class="language-cpp">    #include &quot;MyTypes.h&quot;
+
+    void rtg_Colors_init(const RTObject_class * type, Colors * target)
+    {
+        *target = Colors::Green; // Make Green the default color instead of Red
+    }
+
+    #if OBJECT_ENCODE
+    int rtg_MyString_encode(const RTObject_class* type, const MyString* source, RTEncoding* coding)
+    {
+        return coding-&gt;put_string(source-&gt;c_str()); // Encode as string literal
+    }
+    #endif
+</code></pre>
 <div class="admonition example">
 <p class="admonition-title">Example</p>
 <p>You can find sample applications that use automatically generated type descriptors here:</p>
@@ -1545,7 +1596,10 @@ <h3 id="automatically-generated">Automatically Generated</h3>
 <li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/enum_type_descriptor_custom_encode">Automatically generated type descriptor for an enum class with a custom encode function</a></li>
 <li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/struct_type_descriptor">Automatically generated type descriptor for a struct</a></li>
 <li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/struct_type_descriptor_nested">Automatically generated type descriptor for a struct that contains another struct</a></li>
-<li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/typedef_type_descriptor">Automatically generated type descriptor for a typedef and type alias</a></li>
+<li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/typedef_type_descriptor">Automatically generated type descriptor for a typedef and type alias (with customized type descriptors)</a></li>
+<li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/struct_type_descriptor_header_file">Automatically generated type descriptor for a struct defined in a C++ header file</a></li>
+<li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/enum_type_descriptor_header_file">Automatically generated type descriptor for an enum defined in a C++ header file</a></li>
+<li><a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/typedef_type_descriptor_header_file">Automatically generated type descriptor for a typedef and type alias defined in a C++ header file (with customized type descriptors)</a></li>
 </ul>
 </div>
 <h3 id="manually-implemented">Manually Implemented</h3>
@@ -1633,6 +1687,12 @@ <h3 id="inheritance">Inheritance</h3>
 <p class="admonition-title">Example</p>
 <p>You can find a sample application that uses an automatically implemented type descriptor for a class that inherits from another class <a href="https://github.com/secure-dev-ops/code-realtime/tree/main/art-comp-test/tests/type_descriptor_inheritance">here</a>.</p>
 </div>
+<h3 id="generated-files">Generated Files</h3>
+<p>The code mentioned above related to type descriptors, which the code generator generates for the <code>[[rt::auto_descriptor]]</code> and <code>[[rt::manual_descriptor]]</code> attributes, will be placed in generated header and implementation files:</p>
+<ol>
+<li>If the type with the attribute is located in an <code>[[rt::decl]]</code> code snippet in an Art file, the generated files get the same name as the Art file, but with the extensions <code>.h</code> or <code>.cpp</code> appended. For example, if the Art file is called <code>MyTypes.art</code> the type descriptor code for a type contained in an <code>[[rt::decl]]</code> code snippet in that file will be placed in files <code>MyTypes.art.h</code> and <code>MyTypes.art.cpp</code>. To use the type you include the file <code>MyTypes.art.h</code>.</li>
+<li>If the type with the attribute is located in a C++ header file that is present in the workspace folder (see <a href="../../building/build-cpp-files/">C++ Source Files</a>), the generated files get the same name as the C++ header file but prefixed with <code>RTType_</code>. For example, if your workspace folder contains a file <code>MyType.h</code> with a type that has a type descriptor attribute applied, two files <code>RTType_MyType.h</code> and <code>RTType_MyType.cpp</code> will be generated. Note that <code>RTType_MyType.h</code> will include the original header file <code>MyType.h</code> which means that if you need to use the type in a way that requires its type descriptor, you should include <code>RTType_MyType.h</code> rather than <code>MyType.h</code>.</li>
+</ol>
 
 
 

docs/building/images/custom_property.png

@@ -931,6 +931,26 @@
     Editing Transformation Configurations
   </a>
 
+    <nav class="md-nav" aria-label="Editing Transformation Configurations">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#form-based-tc-editor" class="md-nav__link">
+    Form-based TC Editor
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#custom-tc-properties" class="md-nav__link">
+    Custom TC Properties
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -1480,6 +1500,26 @@
     Editing Transformation Configurations
   </a>
 
+    <nav class="md-nav" aria-label="Editing Transformation Configurations">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#form-based-tc-editor" class="md-nav__link">
+    Form-based TC Editor
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#custom-tc-properties" class="md-nav__link">
+    Custom TC Properties
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
         <li class="md-nav__item">
@@ -1718,7 +1758,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="#editing-transformation-configurations">form-based editor</a> is also provided as an alternative.</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><img alt="" src="../images/default-tc-name.png" /></p>
@@ -1756,9 +1796,22 @@ <h2 id="editing-transformation-configurations">Editing Transformation Configurat
 <li>TC properties are validated when edited and found problems will be reported. Click the "More information" hyperlink for a more detailed description of a problem, including suggestions for how to fix it.</li>
 </ul>
 <p><img alt="" src="../images/tc-editor-validation.png" /></p>
+<h3 id="form-based-tc-editor">Form-based TC Editor</h3>
 <p>As an alternative to editing a TC as a JavaScript file Code RealTime also provides a form-based editor which may be easier to use, especially until you are familiar with all TC properties that exist and what they mean.</p>
 <p>To open the form-based TC editor, right-click on a TC file and invoke the context menu command <strong>Edit Properties (UI)</strong>. </p>
 <p><img alt="" src="../images/tc-editor.png" /></p>
+<p>The editor groups the TC properties into three sections:</p>
+<ul>
+<li>
+<p><strong>General</strong>: Properties which define the scope of the TC (which elements to transform to C++ and where to place generated files)</p>
+</li>
+<li>
+<p><strong>Code Generation</strong>: Properties that control how Art elements are transformed into C++ code, and other properties that affect the generated code</p>
+</li>
+<li>
+<p><strong>Build</strong>: Properties that control how generated C++ code is built into a library or an executable</p>
+</li>
+</ul>
 <p>Each available TC property has its own widget for viewing and editing the value. The type of widget depends on the type of TC property. For example, an enumerated property like "C++ Code Standard" uses a drop down menu.</p>
 <p><img alt="" src="../images/tc-editor-cpp-code-standard.png" /></p>
 <p>Click the info button to view documentation about a certain TC property. Click the button again to hide the documentation.</p>
@@ -1768,6 +1821,19 @@ <h2 id="editing-transformation-configurations">Editing Transformation Configurat
 <p>You can tell which TC properties that have a custom (i.e. non-default) value set by looking at the color of the property name. Properties with custom values set have names shown in blue which are hyperlinks that will navigate to the value in the TC file. Such properties also have a "Delete" button which can be used for deleting the property value (i.e. to restore the property to use its default value).</p>
 <p><img alt="" src="../images/tc-with-value.png" /></p>
 <p>You can freely choose if you want to edit TC files as text files or using the form-based TC editor, and you can even use both at the same time. The form-based TC editor is automatically updated as soon as you edit the TC file, and the TC file is automatically updated when a widget with a modified value loses focus. </p>
+<h3 id="custom-tc-properties">Custom TC Properties</h3>
+<p>You can add your own custom properties to a TC by simply assigning a value to them. This allows you to persist your own custom data in TC files. Here is an example:</p>
+<pre><code class="language-js">tc.customBuild = true;
+</code></pre>
+<p>Custom properties are ignored when building the TC, but can be seen and used by <a href="../build-variants/">Build Variant scripts</a> when implementing a custom way of building your application.</p>
+<p>In the TC text editor custom properties can be recognized by a tooltip that says "any":</p>
+<p><img alt="" src="../images/custom_property.png" /></p>
+<p>In the form-based TC editor custom properties are not shown, but a hyperlink <strong>More Properties</strong> appears under the title text if the TC has one or many custom properties. You can click this link to navigate to the custom properties in the TC text editor.</p>
+<p><img alt="" src="../images/more_properties.png" /></p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>The <strong>More Properties</strong> hyperlink is also useful for navigating to TC properties which the form-based TC editor doesn't (yet) support, for example the <a href="#threads">threads</a> property.</p>
+</div>
 <h2 id="transformation-configuration-prerequisites">Transformation Configuration Prerequisites</h2>
 <p>A TC can either build a library or an executable. This is controlled by the <a href="#topcapsule">topCapsule</a> property. If this property is set the TC will build an executable, otherwise it will build a library. To ensure that a library gets built before an executable that links with it, you can set the <a href="#prerequisites">prerequisites</a> property of the executable TC to reference the library TC. Doing so will also cause the executable to link with the library automatically (i.e. you then don't need to manually set-up necessary preprocessor include paths or linker paths using other TC properties).</p>
 <p>If you change the prerequisites of a TC you should again <a href="#setting-a-transformation-configuration-as-active">set it as active</a> so that the prerequisite TCs also become active.</p>
@@ -1804,7 +1870,7 @@ <h2 id="art-build-view">Art Build View</h2>
 </li>
 </ul>
 <h2 id="properties">Properties</h2>
-<p>Below is a table that lists all properties that can be used in a TC. Note that many TC properties have default values and you only need to specify a value for a TC property if its different from the default value. Each property is described in a section of its own below the table.</p>
+<p>Below is a table that lists all properties that can be used in a TC (in addition to <a href="#custom-tc-properties">custom properties</a>). Note that many TC properties have default values and you only need to specify a value for a TC property if its different from the default value. Each property is described in a section of its own below the table.</p>
 <p id="tc_properties"/>
 
 <table>

docs/building/images/more_properties.png

@@ -1387,7 +1387,7 @@ <h2>
             <!-- Copyright and theme information -->
             <div><p>If you encounter any problems while using Code RealTime or have questions or suggestions about its features, feel free to <a href="https://github.com/secure-dev-ops/code-realtime/issues">raise an issue</a>, or contact us at <a href="mailto:code-realtime@hcl-software.com">code-realtime@hcl-software.com</a>. We're here to assist you!</p></div>
             <div class="md-footer-copyright">
-                <a href=" https://www.hcltechsw.com/ " title="MkDocs"><p> Copyright &copy; 2022, 2024 HCL Technologies Ltd. IBM Corporation. All Rights Reserved.</p></a>
+                <a href=" https://www.hcltechsw.com/ " title="MkDocs"><p> Copyright &copy; 2022, 2025 HCL Technologies Ltd. IBM Corporation. All Rights Reserved.</p></a>
                 <br>Made with
                 <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
                     Material for MkDocs