Add documentation for environment variables expansion on XML (#556)

* Refs #19583. Add documentation for environment variables expansion on XML. Signed-off-by: Miguel Company <[email protected]> * Refs #19583. Document environment variable name restrictions. Signed-off-by: Miguel Company <[email protected]> * Refs #19583. Document environment variable mixing with text. Signed-off-by: Miguel Company <[email protected]> --------- Signed-off-by: Miguel Company <[email protected]>
eProsima · Sep 20, 2023 · c29cd6e · c29cd6e
1 parent 8ab06ab
commit c29cd6e
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 0 deletions.
diff --git a/code/XMLTesterSkipValidation.xml b/code/XMLTesterSkipValidation.xml
@@ -78,3 +78,25 @@
     </type>
 </types>
 <!--STAND_ALONE_TYPES_END-->
+
+<!-->XML_PROFILE_ENVIRONMENT_VARIABLES<-->
+<?xml version="1.0" encoding="UTF-8" ?>
+<dds xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
+    <profiles>
+        <participant profile_name="env_var_parsing_example">
+            <rtps>
+                <name>This is app '${MY_APP_NAME}' running on host '${MY_HOST_NAME}'</name>
+                <builtin>
+                    <initialPeersList>
+                        <locator>
+                            <udpv4>
+                                <address>${REMOTE_IP_ADDRESS}</address>
+                            </udpv4>
+                        </locator>
+                    </initialPeersList>
+                </builtin>
+            </rtps>
+        </participant>
+    </profiles>
+</dds>
+<!--><-->
diff --git a/docs/fastdds/xml_configuration/making_xml_profiles.rst b/docs/fastdds/xml_configuration/making_xml_profiles.rst
@@ -125,3 +125,36 @@ XML profile. This allows the user to read and modify predefined XML profiles bef
     :start-after: //XML-MIX-WITH-CODE
     :end-before: //!--
     :dedent: 8
+
+Dynamic content by leveraging environment variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For deployment scenarios that require part of the XML content to be dynamically generated, Fast DDS supports using
+environment variables on the text content of any XML tag.
+The format for environment variables expansion is ``${ENV_VAR_NAME}``, where ``ENV_VAR_NAME`` follows the restrictions
+from `IEEE 1003.1 <https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html>`_:
+
+.. note::
+
+    Environment variable names ... consist solely of uppercase letters, digits, and the '_' (underscore) from the
+    characters defined in Portable Character Set and do not begin with a digit.
+
+More than one environment variable can be used, and they can be mixed with literal text.
+
+The expansion will take place when the XML file is loaded, so changing the value of an environment variable afterwards
+will have no effect.
+
+The following is an example of an XML allowing a participant to exclusively communicate with the participants on a
+fixed IP address, taken from ``REMOTE_IP_ADDRESS`` environment variable.
+It also gives the participant a name that mixes literal text with the content from two environment variables.
+
+.. literalinclude:: /../code/XMLTesterSkipValidation.xml
+    :language: xml
+    :start-after: <!-->XML_PROFILE_ENVIRONMENT_VARIABLES<-->
+    :end-before: <!--><-->
+
+.. warning::
+
+    The `Fast DDS XSD schema <https://github.com/eProsima/Fast-DDS/blob/master/resources/xsd/fastRTPS_profiles.xsd>`_
+    does not support the environment variables expansion feature, so validation of an XML file with environment
+    variables expansion expressions will fail.