Skip to content

Commit

Permalink
Add documentation for environment variables expansion on XML (#556)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
MiguelCompany authored Sep 20, 2023
1 parent 8ab06ab commit c29cd6e
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 0 deletions.
22 changes: 22 additions & 0 deletions code/XMLTesterSkipValidation.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
<!--><-->
33 changes: 33 additions & 0 deletions docs/fastdds/xml_configuration/making_xml_profiles.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit c29cd6e

Please sign in to comment.