diff --git a/docs/building/index.rst b/docs/building/index.rst index 334d3295eeb..14d3d754241 100644 --- a/docs/building/index.rst +++ b/docs/building/index.rst @@ -154,7 +154,7 @@ It requires the following libraries to be available: vcpkg install openssl:x64-windows xerces-c:x64-windows - * Configure OpenDDS by passing the openssl and xerces3 switches. + * Configure OpenDDS by passing the ``--openssl`` and ``--xerces3`` options. As a convenience, it can be helpful to set an environment variable to store the path since it is the same location for both dependencies. .. code-block:: batch @@ -162,7 +162,7 @@ It requires the following libraries to be available: set VCPKG_INSTALL=c:\path\to\vcpkg\installed\x64-windows configure --security --openssl=%VCPKG_INSTALL% --xerces3=%VCPKG_INSTALL% - * Compile with msbuild: + * Compile with ``msbuild``: .. code-block:: batch diff --git a/docs/devguide/conditions_and_listeners.rst b/docs/devguide/conditions_and_listeners.rst index a2e50a0209c..6569b91d2ed 100644 --- a/docs/devguide/conditions_and_listeners.rst +++ b/docs/devguide/conditions_and_listeners.rst @@ -18,7 +18,7 @@ Introduction The DDS specification defines two separate mechanisms for notifying applications of DCPS communication status changes. Most of the status types define a structure that contains information related to the change of status and can be detected by the application using conditions or listeners. -The different status types are described in :ref:`conditions_and_listeners--communication-status-types`. +The different status types are described in :ref:`conditions_and_listeners--communication-status-types`. Each entity type (domain participant, topic, publisher, subscriber, data reader, and data writer) defines its own corresponding listener interface. Applications can implement this interface and then attach their listener implementation to the entity. diff --git a/docs/devguide/content_subscription_profile.rst b/docs/devguide/content_subscription_profile.rst index c4dc9e286d6..147128abe5e 100644 --- a/docs/devguide/content_subscription_profile.rst +++ b/docs/devguide/content_subscription_profile.rst @@ -70,7 +70,7 @@ This data reader is functionally equivalent to a normal data reader except that Filter expressions are first evaluated at the publisher so that data samples which would be ignored by the subscriber can be dropped before even getting to the transport. This feature can be turned off with ``-DCPSPublisherContentFilter 0`` or the equivalent setting in the ``[common]`` section of the configuration file. The behavior of non-default ``DEADLINE`` or ``LIVELINESS`` QoS policies may be affected by this policy. -Special consideration must be given to how the "missing" samples impact the QoS behavior, see the document in ``docs/design/CONTENT_SUBSCRIPTION``. +Special consideration must be given to how the "missing" samples impact the QoS behavior, see the document in :ghfile:`docs/design/CONTENT_SUBSCRIPTION`. .. note:: RTPS_UDP transport does not always do Writer-side filtering. It does not currently implement transport level filtering, but may be able to filter above the transport layer. @@ -498,7 +498,7 @@ Next we have the IDL for the resulting data type: Based on this IDL, the following topic expression can be used to combine data from a topic ``Location`` which uses type ``LocationInfo`` and a topic ``FlightPlan`` which uses type ``PlanInfo``: -:: +.. code-block:: sql SELECT flight_name, x, y, z AS height FROM Location NATURAL JOIN FlightPlan WHERE height < 1000 AND x <23 diff --git a/docs/devguide/dds_security.rst b/docs/devguide/dds_security.rst index b315e8c2ea1..375ee8c2b62 100644 --- a/docs/devguide/dds_security.rst +++ b/docs/devguide/dds_security.rst @@ -337,8 +337,8 @@ Using OpenSSL Utilities for OpenDDS .. Sect<14.5.6> -To generate certificates using the openssl command, a configuration file "openssl.cnf" is required (see below for example commands). -Before proceeding, it may be helpful to review OpenSSL's manpages to get help with the file format. +To generate certificates using the ``openssl`` command, a configuration file ``openssl.cnf`` is required (see below for example commands). +Before proceeding, it may be helpful to review OpenSSL's man pages to get help with the file format. In particular, configuration file format and ca command's documentation and configuration file options. An example OpenSSL CA-Config file used in OpenDDS testing can be found here: :ghfile:`tests/security/certs/identity/identity_ca_openssl.cnf` diff --git a/docs/devguide/getting_started.rst b/docs/devguide/getting_started.rst index c52589b0865..69a306cb04c 100644 --- a/docs/devguide/getting_started.rst +++ b/docs/devguide/getting_started.rst @@ -980,8 +980,7 @@ The specification sets the default to 30 seconds. When the two above processes are started there may be up to a 30 second delay depending on how far apart they are started from each other. This time can be adjusted in OpenDDS configuration files and is discussed in :ref:`run_time_configuration--configuring-for-ddsi-rtps-discovery`. -Because the architecture of OpenDDS allows for pluggable discovery and pluggable transports the two configuration entries called out in the ``rtps.ini`` file above can be changed independently with one using RTPS and the other not using RTPS (e.g. -centralized discovery using ``DCPSInfoRepo``). +Because the architecture of OpenDDS allows for pluggable discovery and pluggable transports the two configuration entries called out in the ``rtps.ini`` file above can be changed independently with one using RTPS and the other not using RTPS (e.g. centralized discovery using ``DCPSInfoRepo``). Setting them both to RTPS in our example makes this application fully interoperable with other non-OpenDDS implementations. .. _getting_started--data-handling-optimizations: diff --git a/docs/devguide/internet_enabled_rtps.rst b/docs/devguide/internet_enabled_rtps.rst index 206df38b880..eb66eaf9ed4 100644 --- a/docs/devguide/internet_enabled_rtps.rst +++ b/docs/devguide/internet_enabled_rtps.rst @@ -77,7 +77,7 @@ Using the RtpsRelay Sect<15.2.1> Support for the RtpsRelay is activated via configuration. -See :ref:`Table 7-5 RTPS Discovery Configuration Options ` and :ref:`Table 7-17 RTPS_UDP Configuration Options `. +See :ref:`RTPS Discovery Configuration Options ` and :ref:`RTPS_UDP Configuration Options `. As an example: .. code-block:: ini @@ -312,13 +312,13 @@ For OpenDDS, ICE can be used to potentially establish connectivity between SPDP SPDP is used as the side channel for SEDP and SEDP is used as the side channel for the ordinary RTPS endpoints. To this, we added two parameters to the RTPS protocol for sending general ICE information and ICE candidates and added the ability to execute the ICE protocol and process STUN messages to the RTPS transports. -ICE is defined in `IETF RFC 8445 `__. -ICE utilizes the STUN protocol that is defined in `IETF RFC 5389 `__. +ICE is defined in :rfc:`8445`. +ICE utilizes the STUN protocol that is defined in :rfc:`5389`. The ICE implementation in OpenDDS does not use TURN servers. ICE is enabled through configuration. The minimum configuration involves setting the ``UseIce`` flag and providing addresses for the STUN servers. -See :ref:`Table 7-5 RTPS Discovery Configuration Options ` and :ref:`Table 7-17 RTPS_UDP Configuration Options ` for details. +See :ref:`RTPS Discovery Configuration Options ` and :ref:`RTPS_UDP Configuration Options ` for details. .. code-block:: ini @@ -395,18 +395,18 @@ OpenDDS includes the following features for mitigation: * Compare the source IP of the SPDP message to the locators. For most applications, the locators advertised by SPDP should match the source IP of the SPDP message. - * See CheckSourceIp in :ref:`Table 7-5 RTPS Discovery Configuration Options ` + * See ``CheckSourceIp`` in :ref:`RTPS Discovery Configuration Options ` * Use the participant lease time from secure discovery and bound it otherwise. By default, OpenDDS will attempt authentication for the participant lease duration specified in the SPDP message. However, this data can't be trusted so a smaller maximum lease time can be specified to force authentication or discovery to terminate before the lease time. - * See MaxAuthTime in :ref:`Table 7-5 RTPS Discovery Configuration Options ` + * See ``MaxAuthTime`` in :ref:`RTPS Discovery Configuration Options ` * Limit the number of outstanding secure discoveries. The number of discovered but not-yet-authenticated participants is capped when using secure discovery. - * See MaxParticipantsInAuthentication in :ref:`Table 7-5 RTPS Discovery Configuration Options ` + * See ``MaxParticipantsInAuthentication`` in :ref:`RTPS Discovery Configuration Options ` .. _internet_enabled_rtps--run-participants-in-a-secure-network: diff --git a/docs/devguide/introduction.rst b/docs/devguide/introduction.rst index 36933439dd1..cf586872ecf 100644 --- a/docs/devguide/introduction.rst +++ b/docs/devguide/introduction.rst @@ -233,14 +233,13 @@ Basic Concepts .. Sect<1.1.1> -:ref:`Figure 1-1 ` shows an overview of the DDS DCPS layer. -The following subsections define the concepts shown in this diagram. +This is an overview of the DDS DCPS layer: -.. _introduction--reffigure0: +.. figure:: images/10000001000001C100000202637D36545E22157D.png -**Figure DCPS Conceptual Overview** + DCPS Conceptual Overview -.. image:: images/10000001000001C100000202637D36545E22157D.png +The following subsections define the concepts shown in the diagram. .. _introduction--domain: @@ -336,7 +335,7 @@ Dynamic data readers are also type-safe, but type checking happens at runtime. .. _introduction--built-in-topics: -Built-In Topics +Built-in Topics =============== .. @@ -348,11 +347,7 @@ While subscribed, the application receives samples indicating changes in the ent The following table shows the built-in topics defined within the DDS specification: -.. _introduction--reftable0: - -**Table Built-in Topics** - -.. list-table:: +.. list-table:: Built-in Topics :header-rows: 1 * - Topic Name @@ -630,15 +625,14 @@ Extensible Transport Framework (ETF) OpenDDS uses the IDL interfaces defined by the DDS specification to initialize and control service usage. Data transmission is accomplished via an OpenDDS-specific transport framework that allows the service to be used with a variety of transport protocols. This is referred to as *pluggable transports* and makes the extensibility of OpenDDS an important part of its architecture. -OpenDDS currently supports TCP/IP, UDP/IP, IP multicast, shared-memory, and RTPS_UDP transport protocols as shown in :ref:`Figure 1-2 `. -Transports are typically specified via configuration files and are attached to various entities in the publisher and subscriber processes. -See :ref:`run_time_configuration--transport-configuration-options` for details on configuring ETF components. +OpenDDS currently supports TCP/IP, UDP/IP, IP multicast, shared-memory, and RTPS_UDP transport protocols as shown below. -.. _introduction--reffigure1: +.. figure:: images/10000001000002E50000018D97FADEED4445DDBB.png -.. image:: images/10000001000002E50000018D97FADEED4445DDBB.png + OpenDDS Transport Framework -**Figure OpenDDS Extensible Transport Framework** +Transports are typically specified via configuration files and are attached to various entities in the publisher and subscriber processes. +See :ref:`run_time_configuration--transport-configuration-options` for details on configuring ETF components. The ETF enables application developers to implement their own customized transports. Implementing a custom transport involves specializing a number of classes defined in the transport framework. @@ -681,11 +675,9 @@ The DCPSInfoRepo process needs to be running whenever OpenDDS is being used in a An RTPS configuration does not use the DCPSInfoRepo. The DCPSInfoRepo is not involved in data propagation, its role is limited in scope to OpenDDS applications discovering one another. -.. _introduction--reffigure2: - -.. image:: images/100000010000045A0000025185A3A43482F62E3D.png +.. figure:: images/100000010000045A0000025185A3A43482F62E3D.png -**Figure : Centralized Discovery with OpenDDS InfoRepo** + Centralized Discovery with DCPSInfoRepo Application developers are free to run multiple information repositories with each managing their own non-overlapping sets of DCPS domains. @@ -704,16 +696,15 @@ Peer-to-Peer Discovery with RTPS DDS applications requiring a Peer-to-Peer discovery pattern can be accommodated by OpenDDS capabilities. This style of discovery is accomplished only through the use of the RTPS protocol as of the current release. -This simple form of discovery is accomplished through simple configuration of DDS application data readers and data writers running in application processes as shown in :ref:`Figure 1-4 `. -As each participating process activates the DDSI-RTPS discovery mechanisms in OpenDDS for their data readers and writers, network endpoints are created with either default or configured network ports such that DDS participants can begin advertising the availability of their data readers and data writers. -After a period of time, those seeking one another based on criteria will find each other and establish a connection based on the configured pluggable transport as discussed in Extensible Transport Framework (ETF). -A more detailed description of this flexible configuration approach is discussed in :ref:`run_time_configuration--transport-concepts` and :ref:`run_time_configuration--rtps-udp-transport-configuration-options`. +This simple form of discovery is accomplished through simple configuration of DDS application data readers and data writers running in application processes as shown below. -.. _introduction--reffigure3: +.. figure:: images/10000001000003FC0000025E8CF71A4C4FCDEFF3.png -.. image:: images/10000001000003FC0000025E8CF71A4C4FCDEFF3.png + Peer-to-peer Discovery with RTPS -**Figure : Peer-to-peer Discovery with RTPS** +As each participating process activates the DDSI-RTPS discovery mechanisms in OpenDDS for their data readers and writers, network endpoints are created with either default or configured network ports such that DDS participants can begin advertising the availability of their data readers and data writers. +After a period of time, those seeking one another based on criteria will find each other and establish a connection using a transport. +A more detailed description of this flexible configuration approach is discussed in :ref:`run_time_configuration--transport-concepts` and :ref:`run_time_configuration--rtps-udp-transport-configuration-options`. The following are additional implementation limits that developers need to take into consideration when developing and deploying applications that use RTPS discovery: @@ -851,11 +842,7 @@ This profile adds the classes ``ContentFilteredTopic``, ``QueryCondition``, and In addition, individual classes can be excluded by using the features given in the table below. -.. _introduction--reftable1: - -**Table : Content-Subscription Class Features** - -.. list-table:: +.. list-table:: Content-Subscription Class Features :header-rows: 1 * - Class diff --git a/docs/devguide/java_bindings.rst b/docs/devguide/java_bindings.rst index 3ec5f437afa..884bb5444fe 100644 --- a/docs/devguide/java_bindings.rst +++ b/docs/devguide/java_bindings.rst @@ -50,11 +50,7 @@ Below is a description of the generated files and which tools generate them. In this example, ``Foo.idl`` contains a single struct ``Bar`` contained in module ``Baz`` (IDL modules are similar to C++ namespaces and Java packages). To the right of each file name is the name of the tool that generates it, followed by some notes on its purpose. -.. _java_bindings--reftable34: - -**Table Generated files descriptions** - -.. list-table:: +.. list-table:: Generated files descriptions :header-rows: 1 * - File diff --git a/docs/devguide/modeling_sdk.rst b/docs/devguide/modeling_sdk.rst index 91c47fe55b6..01ecb1a9541 100644 --- a/docs/devguide/modeling_sdk.rst +++ b/docs/devguide/modeling_sdk.rst @@ -35,23 +35,19 @@ This diagram includes any package structures to be included in the model along w Zero or more of the policy or data definition elements can be included. Zero or one DCPS elements definition can be included in any given model. -.. _modeling_sdk--reffigure5: +.. figure:: images/10000001000003BA000005345220EFBC3B2965C5.png + :scale: 50% -.. image:: images/10000001000003BA000005345220EFBC3B2965C5.png - :scale: 50% - -**Figure Graphical modeling of the data definitions** + Graphical modeling of the data definitions Creating separate models for QoS policies only, data definitions only, or DCPS elements only is supported. References to other models allows externally defined models to be included in a model. This allows sharing of data definitions and QoS policies among different DCPS models as well as including externally defined data in a new set of data definitions. -.. _modeling_sdk--reffigure6: - -.. image:: images/10000001000003CA00000534AF32FC1EC2AA656B.png - :scale: 50% +.. figure:: images/10000001000003CA00000534AF32FC1EC2AA656B.png + :scale: 50% -**Figure Graphical modeling of the DCPS entities** + Graphical modeling of the DCPS entities .. _modeling_sdk--code-generation: @@ -116,12 +112,10 @@ Installation .. Sect<11.2.2> -.. _modeling_sdk--reffigure7: - -.. image:: images/100000000000018A000001582B13D316CA761B88.png - :scale: 150% +.. figure:: images/100000000000018A000001582B13D316CA761B88.png + :scale: 150% -**Figure Eclipse Software Installation Dialog** + Eclipse Software Installation Dialog #. From Eclipse, open the "Help" menu and select "Install New Software". @@ -235,13 +229,9 @@ Generated Code Sect<11.3.2> The OpenDDS Modeling SDK generates model-specific code for use by an OpenDDS Modeling SDK application. -Starting with a .codegen file (which refers to an ``.opendds`` model file), the files described in :ref:`Table 11-1 `. +Starting with a .codegen file (which refers to an ``.opendds`` model file), the files described in the table below. The process of generating code is documented in the Eclipse help. -.. _modeling_sdk--reftable35: - -**Table Generated Files** - .. list-table:: :header-rows: 1 diff --git a/docs/devguide/opendds_idl.rst b/docs/devguide/opendds_idl.rst index 67c88c4b291..3be10ffc04e 100644 --- a/docs/devguide/opendds_idl.rst +++ b/docs/devguide/opendds_idl.rst @@ -4,11 +4,13 @@ opendds_idl ########### +.. program:: opendds_idl + .. Sect<8> -opendds_idl is one of the code generators used in the process of building OpenDDS and OpenDDS applications. -It can be used in a number of different ways to customize how source code is generated from IDL files. +``opendds_idl`` is one of the code generators used in the process of building OpenDDS and OpenDDS applications. +It can be used in a number of different ways to customize how source code is generated from :term:`IDL` files. See :ref:`getting_started--processing-the-idl` for an overview of the default usage pattern. The OpenDDS IDL compiler is invoked using the ``opendds_idl`` executable, located in :ghfile:`bin/` (on the ``PATH``). @@ -32,238 +34,172 @@ opendds_idl Command Line Options .. Sect<8.1> -The following table summarizes the options supported by ``opendds_idl``. - -.. _opendds_idl--reftable29: - -**Table opendds_idl Command Line Options** - -.. list-table:: - :header-rows: 1 - - * - Option - - - Description - - - Default - - * - ``-v`` - - - Enables verbose execution - - - Quiet execution - - * - ``-h`` - - - Prints a help (usage) message and exits - - - N/A - - * - ``-V`` - - - Prints version numbers of both TAO and OpenDDS - - - N/A - - * - ``--idl-version VERSION`` - - - Set the version of IDL to use. - - - 4 - - * - ``--list-idl-versions`` - - - List the versions of IDL at least partially supported. - - - N/A - - * - ``--syntax-only`` - - - Just check syntax of input files, exiting after parsing. - - - Goes on to generate code - - * - ``-Wb,export_macro=macro`` - - - Export macro used for generating C++ implementation code. - ``--export`` is equivalent to ``-Wb,export_macro`` - - - No export macro used - - * - ``-Wb,export_include=file`` - - - Additional header to ``#include`` in generated code -- this header ``#defines`` the export macro - - - No additional include - - * - ``-Wb,pch_include=file`` - - - Pre-compiled header file to include in generated C++ files - - - No pre-compiled header included - - * - ``-Dname[=value]`` - - - Define a preprocessor macro - - - N/A - - * - ``-Idir`` - - - Add ``dir`` to the preprocessor include path - - - N/A +.. option:: --help, -h - * - ``-o outputdir`` + Prints a help message and exits. - - Output directory where ``opendds_idl`` should place the generated files. +.. option:: -v - - The current directory + Enables verbose/debug logging. - * - ``-Wb,java`` +.. option:: --version, -V - - Enable OpenDDS Java Bindings for generated TypeSupport implementation classes + Prints version numbers of both TAO and OpenDDS. - - No Java support +.. option:: --idl-version VERSION - * - ``-Gitl`` + Set the version of the :ref:`IDL specification ` to use. + The default is ``4``. - - Generates "Intermediate Type Language" descriptions of datatypes. - These files are used by the Wireshark dissector or other external applications. +.. option:: --list-idl-versions - - Not generated + List the versions of IDL at least partially supported and exits. - * - ``-GfaceTS`` +.. option:: --syntax-only - - Generates FACE (Future Airborne Capability Environment) Transport Services API + Just check syntax of input files and exit without generating any code. - - Not generated +.. option:: -Wb,export_macro=MACRO - * - ``-Gv8`` + Use the export macro for generating C++ implementation code named *MACRO*. + By default export macros are not used. + ``--export`` is an alias for this. - - Generate type support for converting data samples to/from V8 JavaScript objects +.. option:: -Wb,export_include=FILE - ``-Wb,v8`` is an alternative form of this option + Add an additional header *FILE* to ``#include`` in generated code that has the export macro. - - Not generated +.. option:: -Wb,pch_include=FILE - * - .. _opendds_idl--gxtypes-complete-option: + Include a pre-compiled header *FILE* in generated C++ files. - .. _opendds_idl--gxtypes-complete: +.. option:: -Dname[=value] - ``-Gxtypes-complete`` + Define a preprocessor macro named *name* optionally with value *value* for IDL. - - Generate complete XTypes TypeObjects which can be used to provide type information to applications that don't have compile-time knowledge of the IDL. - See :ref:`xtypes--dynamic-language-binding-1`. +.. option:: -Idir - - Only minimal TypeObjects are generated + Adds *dir* to the preprocessor include path for IDL. - * - ``-Gequality`` +.. option:: -o OUTPUT_PATH - - Generate ``==`` and ``!=`` for structs and unions. - The members of the struct or union must have a type that could appear in a DDS topic and be supported by opendds_idl. + Output directory where generated files are put. + By default this is the current working directory. - - Not generated +.. option:: -Wb,java - * - ``-Lface`` + Generate Java Bindings for generated ``TypeSupport`` implementation classes. + See :ref:`java` for more information. - - Generates IDL-to-C++ mapping for FACE +.. option:: -Gitl - - Not generated + Generate "Intermediate Type Language" descriptions of topic types. + These files are used by the Wireshark dissector or other external applications. - * - ``-Lspcpp`` +.. option:: -GfaceTS - - Generates IDL-to-C++ mapping for Safety Profile + Generate FACE (Future Airborne Capability Environment) Transport Services API. + See :doc:`safety_profile` for more information. - - Not generated +.. option:: -Gv8 - * - ``-Lc++11`` + Generate type support for converting data samples to/from V8 JavaScript objects + ``-Wb,v8`` is an alias for this. - - Generates IDL-to-C++11 mapping +.. option:: -Gxtypes-complete - - Not generated + Generate complete XTypes TypeObjects which can be used to provide type information to applications that don't have compile-time knowledge of the IDL. + By default only minimal TypeObjects are generated. + See :ref:`xtypes--dynamic-language-binding-1` for more information. - * - ``-Wb,tao_include_prefix=s`` +.. option:: -Gequality - - Prefix the string *s* to #include directives meant to include headers generated by ``tao_idl`` + Generate ``==`` and ``!=`` for structs and unions. + The members of the struct or union must have a type that could appear in a DDS topic and be supported by ``opendds_idl``. - - N/A +.. option:: -Lface - * - ``-St`` + Generates IDL-to-C++ mapping for FACE. + See :doc:`safety_profile` for more information. - - Suppress generation of IDL TypeCodes when one of the ``-L`` options are present. +.. option:: -Lspcpp - - IDL TypeCodes generated + Generates IDL-to-C++ mapping for :doc:`safety_profile`. - * - ``--unknown-annotations VAL`` +.. option:: -Lc++11 - - For IDL version 4, control the reaction to unknown annotations. - The options are: + Generates :ref:`IDL-to-C++11 mapping `. - * ``warn-once, the default, warn once per annotation with the same name.`` +.. option:: -Wb,tao_include_prefix=S - * ``warn-all, warn for every use of an unknown annotation.`` + Prefix the string *S* to ``#include`` directives meant to include headers generated by ``tao_idl``. - * ``error, similar to warn-all, but causes the compiler to exit with an error status when finished.`` +.. option:: -St - * ``ignore, ignore all unknown annotations.`` + Suppress generation of IDL TypeCodes when one of the ``-L`` options are present. - - ``warn-once`` +.. option:: --unknown-annotations REACTION - * - ``--no-dcps-data-type-warnings`` + Control the reaction to unknown IDL annotations. + *REACTION* can be: - - Don't warn about ``#pragma DCPS_DATA_TYPE`` + * ``warn-once`` -- the default, warn once per annotation with the same name. - - Warnings are issued, use annotations to silence them + * ``warn-all`` -- warn for every use of an unknown annotation. - * - ``--[no-]default-nested`` + * ``error`` -- similar to ``warn-all``, but causes the compiler to exit with an error status when finished. - - Un-annotated types/modules are treated as nested. - See :ref:`getting_started--topic-types-vs-nested-types` for details. + * ``ignore`` -- ignore all unknown annotations. - - Types are nested by default. +.. option:: --no-dcps-data-type-warnings - * - .. _opendds_idl--default-extensibility: + Don't warn about ``#pragma DCPS_DATA_TYPE``. + See :ref:`getting_started--identifying-topic-types` for more information. - ``--default-extensibility`` +.. option:: --[no-]default-nested - - Set the default XTypes extensibility. - Can be ``final``, ``appendable`` or ``mutable``. - See :ref:`xtypes--extensibility` for details. + Un-annotated types/modules are treated as nested. + By default all types are nested by default + See :ref:`getting_started--topic-types-vs-nested-types` for details. - - ``appendable`` +.. option:: --default-extensibility EXT - * - ``--default-enum-extensibility-zero`` + Set the :ref:`default XTypes extensibility `. + *EXT* can be: - - Do not set the type flags for enums. - This flag is for simulating the behavior of previous versions of OpenDDS. + - ``final`` + - ``appendable`` (default) + - ``mutable`` - - +.. option:: --default-autoid VALUE - * - ``--default-autoid VAL`` + Set the default :ref:`XTypes auto member-id assignment strategy `. + *VALUE* can be ``sequential`` (the default) or ``hash``. - - Set the default XTypes auto member-id assignment strategy: ``sequential`` or ``hash`` -- see :ref:`xtypes--autoid-value` +.. option:: --default-try-construct VALUE - - ``sequential`` + Set the default :ref:`XTypes try-construct strategy `. + *VALUE* can be ``discard`` (the default), ``use-default``, or ``trim``. - * - ``--default-try-construct VAL`` +.. option:: --old-typeobject-encoding - - Set the default XTypes try-construct strategy: ``discard``, ``use-default``, or ``trim`` -- see :ref:`xtypes--customizing-xtypes-per-member` + .. versionadded:: 3.18 - - ``discard`` + Use the pre-3.18 encoding of ``TypeObject``\s when deriving ``TypeIdentifier``\s. - * - ``--old-typeobject-encoding`` +.. option:: --default-enum-extensibility-zero - - Use the pre-3.18 encoding of ``TypeObject``\s when deriving ``TypeIdentifier``\s + .. versionadded:: 3.22 - - Use standard encoding + Do not set the type flags for enums. + This flag is for simulating the behavior of OpenDDS before 3.22. - * - ``--old-typeobject-member-order`` +.. option:: --old-typeobject-member-order - - Use the pre-3.24 struct and union member order for ``TypeObject``\s, which is ordered by member id instead of declared order. - See 3.24.0 news entry for more info. + .. versionadded:: 3.24 - - Use standard declared order + Use the pre-3.24 struct and union member order for ``TypeObject``\s, which is ordered by member id instead of declared order. + See :ref:`3.24.0 news entry <3-24-0-typeobject-fix>` for more info. The code generation options allow the application developer to use the generated code in a wide variety of environments. Since IDL may contain preprocessing directives (``#include``, ``#define``, etc.), the C++ preprocessor is invoked by ``opendds_idl``. diff --git a/docs/devguide/quality_of_service.rst b/docs/devguide/quality_of_service.rst index cb94f384735..b54959668bb 100644 --- a/docs/devguide/quality_of_service.rst +++ b/docs/devguide/quality_of_service.rst @@ -122,11 +122,7 @@ The following examples illustrate how to obtain the default policies for publish The following tables summarize the default QoS policies for each entity type in OpenDDS to which policies can be applied. -.. _quality_of_service--reftable2: - -**Table Default DomainParticipant QoS Policies** - -.. list-table:: +.. list-table:: Default DomainParticipant QoS Policies :header-rows: 1 * - Policy @@ -147,11 +143,7 @@ The following tables summarize the default QoS policies for each entity type in - ``true`` -.. _quality_of_service--reftable3: - -**Table Default Topic QoS Policies** - -.. list-table:: +.. list-table:: Default Topic QoS Policies :header-rows: 1 * - Policy @@ -312,11 +304,9 @@ The following tables summarize the default QoS policies for each entity type in - ``SHARED_OWNERSHIP_QOS`` -.. _quality_of_service--reftable4: +.. _quality_of_service--publisher: -**Table Default Publisher QoS Policies** - -.. list-table:: +.. list-table:: Default Publisher QoS Policies :header-rows: 1 * - Policy @@ -359,9 +349,7 @@ The following tables summarize the default QoS policies for each entity type in .. _quality_of_service--reftable5: -**Table Default Subscriber QoS Policies** - -.. list-table:: +.. list-table:: Default Subscriber QoS Policies :header-rows: 1 * - Policy @@ -404,9 +392,7 @@ The following tables summarize the default QoS policies for each entity type in .. _quality_of_service--reftable6: -**Table Default DataWriter QoS Policies** - -.. list-table:: +.. list-table:: Default DataWriter QoS Policies :header-rows: 1 * - Policy @@ -581,9 +567,7 @@ The following tables summarize the default QoS policies for each entity type in .. _quality_of_service--reftable7: -**Table Default DataReader QoS Policies** - -.. list-table:: +.. list-table:: Default DataReader QoS Policies :header-rows: 1 * - Policy diff --git a/docs/devguide/run_time_configuration.rst b/docs/devguide/run_time_configuration.rst index df05d63f821..0f6014e3f62 100644 --- a/docs/devguide/run_time_configuration.rst +++ b/docs/devguide/run_time_configuration.rst @@ -38,9 +38,7 @@ The configuration file for OpenDDS is a human-readable ini-style text file. .. _run_time_configuration--sections: -**Configuration File Sections** - -.. list-table:: +.. list-table:: Configuration File Sections :header-rows: 1 * - **Focus Area** @@ -174,10 +172,6 @@ For example: The following table summarizes the ``[common]`` configuration options: -.. _run_time_configuration--reftable9: - -**Common Configuration Options** - .. list-table:: :header-rows: 1 @@ -362,7 +356,7 @@ The following table summarizes the ``[common]`` configuration options: - This setting is only available when OpenDDS is compiled with DDS Security enabled. If set to 1, enable DDS Security framework and built-in plugins. Each Domain Participant using security must be created with certain QoS policy values. - See :ref:`dds_security--dds-security`: DDS Security for more information. + See :ref:`dds_security`: DDS Security for more information. - ``0`` @@ -546,8 +540,7 @@ The ``DomainId`` property assigns the integer value of ``1`` needed by a DDS app Multiple domain instances can be identified in a single configuration file in this format. Once one or more domain instances are established, the discovery properties must be identified for that domain. -The ``DiscoveryConfig`` property must either point to another section that holds the discovery configuration or specify one of the internal default values for discovery (e.g. -``DEFAULT_REPO``, ``DEFAULT_RTPS``, or ``DEFAULT_STATIC``). +The ``DiscoveryConfig`` property must either point to another section that holds the discovery configuration or specify one of the internal default values for discovery (e.g. ``DEFAULT_REPO``, ``DEFAULT_RTPS``, or ``DEFAULT_STATIC``). The instance name in our example is ``DiscoveryConfig1``. This instance name must be associated with a section type of either ``[repository]`` or ``[rtps_discovery]``. @@ -581,7 +574,7 @@ For example, if an OpenDDS application assigns a domain ID of 3 to its participa The ``DCPSDefaultDiscovery`` property tells the application to assign any participant that doesn't have a domain id found in the configuration file to use a discovery type of ``DEFAULT_REPO`` which means "use a ``DCPSInfoRepo`` service" and that ``DCPSInfoRepo`` service can be found at ``host3.mydomain.com:12345``. -As shown in :ref:`Table 7-2 ` the ``DCPSDefaultDiscovery`` property has three other values that can be used. +As shown in :ref:`run_time_configuration--common-configuration-options` the ``DCPSDefaultDiscovery`` property has three other values that can be used. The ``DEFAULT_RTPS`` constant value informs participants that don't have a domain configuration to use RTPS discovery to find other participants. Similarly, the ``DEFAULT_STATIC`` constant value informs the participants that don't have a domain configuration to use static discovery to find other participants. @@ -608,13 +601,9 @@ Here is an example: By adding the ``DCPSDefaultDiscovery`` property to the ``[common]`` section, any participant that hasn't been assigned to a domain id of ``1`` or ``2`` will use the configuration of ``DiscoveryConfig2``. For more explanation of a similar configuration for RTPS discovery see :ref:`run_time_configuration--configuring-for-ddsi-rtps-discovery`. -Here are the available properties for the [domain] section. +Here are the available properties for the ``[domain]`` section: -.. _run_time_configuration--reftable10: - -**Table Domain Section Configuration Properties** - -.. list-table:: +.. list-table:: Domain Section Configuration Properties :header-rows: 1 * - Option @@ -635,7 +624,7 @@ Here are the available properties for the [domain] section. * - ``DiscoveryConfig=config instance name`` - A user-defined string that refers to the instance name of a ``[repository]`` or ``[rtps_discovery]`` section in the same configuration file or one of the internal default values (``DEFAULT_REPO``, ``DEFAULT_RTPS``, or ``DEFAULT_STATIC``). - (Also see the ``DCPSDefaultDiscovery`` property in :ref:`Table 7-2 `) + (Also see the ``DCPSDefaultDiscovery`` property in :ref:`run_time_configuration--common-configuration-options`) * - ``DefaultTransportConfig=config`` @@ -773,7 +762,10 @@ The DDS entities in a single OpenDDS process can be associated with multiple DCP The repository information and domain associations can be configured using a configuration file, or via application API. Internal defaults, command line arguments, and configuration file options will work as-is for existing applications that do not want to use multiple ``DCPSInfoRepo`` associations. -See :ref:`Figure 7-1 ` for an example of a process that uses multiple ``DCPSInfoRepo`` repositories. +The following is an example of a process that uses multiple ``DCPSInfoRepo`` repositories. + +.. image:: images/10000001000005B4000003E0BE5C08B1D30CA54A.png + Processes ``A`` and ``B`` are typical application processes that have been configured to communicate with one another and discover one another in ``InfoRepo_1``. This is a simple use of basic discovery. However, an additional layer of context has been applied with the use of a specified domain (Domain ``1``). @@ -785,18 +777,12 @@ This is Process ``E`` in our example. It contains two subscribers, one subscribing to publications from ``InfoRepo_1`` and the other subscribing to publications in ``InfoRepo_2``. What allows this configuration to work can be found in the ``configE.ini`` file. -.. _run_time_configuration--reffigure4: - -.. image:: images/10000001000005B4000003E0BE5C08B1D30CA54A.png - -**Figure Multiple DCPSInfoRepo Configuration** - We will now look at the configuration file (referred to as ``configE.ini``) to demonstrate how Process ``E`` can communicate to both domains and separate ``DCPSInfoRepo`` services. For this example we will only show the discovery aspects of the configuration and not show transport content. .. code-block:: ini + :name: configE.ini - configE.ini [domain/1] DiscoveryConfig=DiscoveryConfig1 @@ -809,7 +795,7 @@ For this example we will only show the discovery aspects of the configuration an [repository/DiscoveryConfig2] RepositoryIor=host2.mydomain.com:12345 -When Process ``E`` in :ref:`Figure 7-1 ` reads in the above configuration it finds the occurrence of multiple domain sections. +When Process ``E`` reads in the above configuration it finds the occurrence of multiple domain sections. As described in :ref:`run_time_configuration--domain-configuration` each domain has an instance integer and a property of ``DiscoveryConfig`` defined. For the first domain (``[domain/1]``), the ``DiscoveryConfig`` property is supplied with the user-defined name of ``DiscoveryConfig1`` value. @@ -826,13 +812,9 @@ There may be any number of repository or domain sections within a single configu .. note:: Individual DCPSInfoRepos can be associated with multiple domains, however domains cannot be shared between multiple DCPSInfoRepos. -Here are the valid properties for a ``[repository]`` section. +Here are the valid properties for a ``[repository]`` section: -.. _run_time_configuration--reftable11: - -**Table Multiple repository configuration sections** - -.. list-table:: +.. list-table:: Multiple repository configuration sections :header-rows: 1 * - Option @@ -926,13 +908,11 @@ Some important implementation notes regarding DDSI-RTPS discovery in OpenDDS are #. OpenDDS's multicast transport (:ref:`run_time_configuration--ip-multicast-transport-configuration-options`) does not work with RTPS Discovery due to the way GUIDs are assigned (a warning will be issued if this is attempted). The OMG DDSI-RTPS specification details several properties that can be adjusted from their defaults that influence the behavior of DDSI-RTPS discovery. -Those properties, along with options specific to OpenDDS's RTPS Discovery implementation, are listed in :ref:`Table 7-5 `. - -.. _run_time_configuration--reftable12: +Those properties, along with options specific to OpenDDS's RTPS Discovery implementation, are listed below. -**Table RTPS Discovery Configuration Options** +.. _run_time_configuration--rtps-disc-config-options: -.. list-table:: +.. list-table:: RTPS Discovery Configuration Options :header-rows: 1 * - Option @@ -1415,10 +1395,10 @@ A domain participant learns about the existence of an endpoint through hints sup .. note:: Currently, static discovery can only be used for endpoints using the RTPS UDP transport. -Static discovery introduces the following configuration file sections: ``[topic/*]``,``[datawriterqos/*]``, ``[datareaderqos/*]``, ``[publisherqos/*]``, ``[subscriberqos/*]``, and ``[endpoint/*]``. -The ``[topic/*]`` (:ref:`Table 7-6 `) section is used to introduce a topic. -The ``[datawriterqos/*]`` (:ref:`Table 7-7 `), ``[datareaderqos/*]`` (:ref:`Table 7-8 `), ``[publisherqos/*]`` (:ref:`Table 7-9 `), and ``[subscriberqos/*]`` (:ref:`Table 7-10 `) sections are used to describe a QoS of the associated type. -The ``[endpoint/*]`` (:ref:`Table 7-11 `) section describes a data reader or writer. +Static discovery introduces the following configuration file sections: ``[topic/*]``, ``[datawriterqos/*]``, ``[datareaderqos/*]``, ``[publisherqos/*]``, ``[subscriberqos/*]``, and ``[endpoint/*]``. +The :ref:`topic ` section is used to introduce a topic. +The :ref:`datawriterqos `, :ref:`datareaderqos `, :ref:`publisherqos `, and :ref:`subscriberqos ` sections are used to describe a QoS of the associated type. +The :ref:`endpoint ` section describes a data reader or writer. Data reader and writer objects must be identified by the user so that the static discovery mechanism can associate them with the correct ``[endpoint/*]`` section in the configuration file. This is done by setting the ``user_data`` of the ``DomainParticipantQos`` to an octet sequence of length 6. @@ -1482,9 +1462,7 @@ The static discovery implementation also checks that the QoS of a data reader or .. _run_time_configuration--reftable13: -**Table [topic/*] Configuration Options** - -.. list-table:: +.. list-table:: [topic/\*] Configuration Options :header-rows: 1 * - Option @@ -1502,15 +1480,13 @@ The static discovery implementation also checks that the QoS of a data reader or * - ``type_name=string`` - Identifier which uniquely defines the sample type. - This is typically a CORBA interface repository type name. + This is typically a CORBA interface repository type name. - ``Required`` .. _run_time_configuration--reftable14: -**Table [datawriterqos/*] Configuration Options** - -.. list-table:: +.. list-table:: [datawriterqos/\*] Configuration Options :header-rows: 1 * - Option @@ -1525,7 +1501,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--durability`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``deadline.period.sec=[`` @@ -1533,7 +1509,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--deadline`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``deadline.period.nanosec=[`` @@ -1541,7 +1517,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--deadline`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``latency_budget.duration.sec=[`` @@ -1549,7 +1525,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--latency-budget`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``latency_budget.duration.nanosec=[`` @@ -1557,7 +1533,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--latency-budget`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``liveliness.kind=[`` @@ -1569,7 +1545,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--liveliness`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``liveliness.lease_duration.sec=[`` @@ -1577,7 +1553,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--liveliness`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``liveliness.lease_duration.nanosec=[`` @@ -1585,13 +1561,13 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--liveliness`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``reliability.kind=[BEST_EFFORT|RELIABILE]`` - See :ref:`quality_of_service--reliability`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``reliability.max_blocking_time.sec=[`` @@ -1599,7 +1575,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reliability`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``reliability.max_blocking_time.nanosec=[`` @@ -1607,7 +1583,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reliability`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``destination_order.kind=[`` @@ -1617,31 +1593,31 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--destination-order`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``history.kind=[KEEP_LAST|KEEP_ALL]`` - See :ref:`quality_of_service--history`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``history.depth=numeric`` - See :ref:`quality_of_service--history`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``resource_limits.max_samples=numeric`` - See :ref:`quality_of_service--resource-limits`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``resource_limits.max_instances=numeric`` - See :ref:`quality_of_service--resource-limits`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``resource_limits.max_samples_per_instance=`` @@ -1649,13 +1625,13 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--resource-limits`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``transport_priority.value=numeric`` - See :ref:`quality_of_service--transport-priority`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``lifespan.duration.sec=[`` @@ -1663,7 +1639,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--lifespan`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``lifespan.duration.nanosec=[`` @@ -1671,25 +1647,23 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--lifespan`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``ownership.kind=[SHARED|EXCLUSIVE]`` - See :ref:`quality_of_service--ownership`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``ownership_strength.value=numeric`` - See :ref:`quality_of_service--ownership-strength`. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. .. _run_time_configuration--reftable15: -**Table [datareaderqos/*] Configuration Options** - -.. list-table:: +.. list-table:: [datareaderqos/\*] Configuration Options :header-rows: 1 * - Option @@ -1704,7 +1678,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--durability`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``deadline.period.sec=[`` @@ -1712,7 +1686,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--deadline`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``deadline.period.nanosec=[`` @@ -1720,7 +1694,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--deadline`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``latency_budget.duration.sec=[`` @@ -1728,7 +1702,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--latency-budget`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``latency_budget.duration.nanosec=[`` @@ -1736,7 +1710,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--latency-budget`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``liveliness.kind=[`` @@ -1748,7 +1722,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--liveliness`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``liveliness.lease_duration.sec=[`` @@ -1756,7 +1730,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--liveliness`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``liveliness.lease_duration.nanosec=[`` @@ -1764,13 +1738,13 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--liveliness`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``reliability.kind=[BEST_EFFORT|RELIABILE]`` - See :ref:`quality_of_service--reliability`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``reliability.max_blocking_time.sec=[`` @@ -1778,7 +1752,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reliability`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``reliability.max_blocking_time.nanosec=[`` @@ -1786,7 +1760,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reliability`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``destination_order.kind=[`` @@ -1796,31 +1770,31 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--destination-order`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``history.kind=[KEEP_LAST|KEEP_ALL]`` - See :ref:`quality_of_service--history`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``history.depth=numeric`` - See :ref:`quality_of_service--history`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``resource_limits.max_samples=numeric`` - See :ref:`quality_of_service--resource-limits`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``resource_limits.max_instances=numeric`` - See :ref:`quality_of_service--resource-limits`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``resource_limits.max_samples_per_instance=`` @@ -1828,7 +1802,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--resource-limits`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``time_based_filter.minimum_separation.sec=[`` @@ -1836,7 +1810,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--time-based-filter`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``time_based_filter.minimum_separation.nanosec=[`` @@ -1844,7 +1818,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--time-based-filter`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``reader_data_lifecycle.`` ``autopurge_nowriter_samples_delay.sec=[`` @@ -1853,7 +1827,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reader-data-lifecycle`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``reader_data_lifecycle.`` ``autopurge_nowriter_samples_delay.nanosec=[`` @@ -1862,7 +1836,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reader-data-lifecycle`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``reader_data_lifecycle.`` ``autopurge_dispose_samples_delay.sec=[`` @@ -1871,7 +1845,7 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reader-data-lifecycle`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``reader_data_lifecycle.`` ``autopurge_dispose_samples_delay.nanosec=[`` @@ -1880,13 +1854,11 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--reader-data-lifecycle`. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. .. _run_time_configuration--reftable16: -**Table [publisherqos/*] Configuration Options** - -.. list-table:: +.. list-table:: [publisherqos/\*] Configuration Options :header-rows: 1 * - Option @@ -1899,31 +1871,29 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--presentation`. - - See :ref:`Table 3-3 `. + - See :ref:`Publisher QoS `. * - ``presentation.coherent_access=[true|false]`` - See :ref:`quality_of_service--presentation`. - - See :ref:`Table 3-3 `. + - See :ref:`Publisher QoS `. * - ``presentation.ordered_access=[true|false]`` - See :ref:`quality_of_service--presentation`. - - See :ref:`Table 3-3 `. + - See :ref:`Publisher QoS `. * - ``partition.name=name0,name1,...`` - See :ref:`quality_of_service--partition`. - - See :ref:`Table 3-3 `. + - See :ref:`Publisher QoS `. .. _run_time_configuration--reftable17: -**Table [subscriberqos/*] Configuration Options** - -.. list-table:: +.. list-table:: [subscriberqos/\*] Configuration Options :header-rows: 1 * - Option @@ -1936,31 +1906,29 @@ The static discovery implementation also checks that the QoS of a data reader or - See :ref:`quality_of_service--presentation`. - - See :ref:`Table 3-4 `. + - See :ref:`Subscriber QoS `. * - ``presentation.coherent_access=[true|false]`` - See :ref:`quality_of_service--presentation`. - - See :ref:`Table 3-4 `. + - See :ref:`Subscriber QoS `. * - ``presentation.ordered_access=[true|false]`` - See :ref:`quality_of_service--presentation`. - - See :ref:`Table 3-4 `. + - See :ref:`Subscriber QoS `. * - ``partition.name=name0,name1,...`` - See :ref:`quality_of_service--partition`. - - See :ref:`Table 3-4 `. + - See :ref:`Subscriber QoS `. .. _run_time_configuration--reftable18: -**Table [endpoint/*] Configuration Options** - -.. list-table:: +.. list-table:: [endpoint/\*] Configuration Options :header-rows: 1 * - Option @@ -2008,25 +1976,25 @@ The static discovery implementation also checks that the QoS of a data reader or - Refers to a ``[datawriterqos/*]`` section. - - See :ref:`Table 3-5 `. + - See :ref:`DataWriter QoS `. * - ``datareaderqos=name`` - Refers to a ``[datareaderqos/*]`` section. - - See :ref:`Table 3-6 `. + - See :ref:`DataReader QoS `. * - ``publisherqos=name`` - Refers to a ``[publisherqos/*]`` section. - - See :ref:`Table 3-3 `. + - See :ref:`Publisher QoS `. * - ``subscriberqos=name`` - Refers to a ``[subscriberqos/*]`` section. - - See :ref:`Table 3-4 `. + - See :ref:`Subscriber QoS `. * - ``config`` @@ -2084,8 +2052,7 @@ Transport Concepts This section provides an overview of the concepts involved in transport configuration and how they interact. Each data reader and writer uses a *Transport Configuration* consisting of an ordered set of *Transport Instances*. -Each Transport Instance specifies a Transport Implementation (i.e. -tcp, udp, multicast, shmem, or rtps_udp) and can customize the configuration parameters defined by that transport. +Each Transport Instance specifies a Transport Implementation (i.e. ``tcp``, ``udp``, ``multicast``, ``shmem``, or ``rtps_udp``) and can customize the configuration parameters defined by that transport. Transport Configurations and Transport Instances are managed by the *Transport Registry* and can be created via configuration files or through programming APIs. Transport Configurations can be specified for Domain Participants, Publishers, Subscribers, Data Writers, and Data Readers. @@ -2321,9 +2288,7 @@ The following table summarizes the options when specifying a transport configura .. _run_time_configuration--reftable19: -**Table Transport Configuration Options** - -.. list-table:: +.. list-table:: Transport Configuration Options :header-rows: 1 * - Option @@ -2398,9 +2363,7 @@ The following table summarizes the transport configuration options that are comm .. _run_time_configuration--reftable20: -**Table Common Transport Configuration Options** - -.. list-table:: +.. list-table:: Common Transport Configuration Options :header-rows: 1 * - Option @@ -2488,8 +2451,7 @@ Almost all of the options available to customize the connection and reconnection The local_address option is used by the peer to establish a connection. By default, the TCP transport selects an ephemeral port number on the NIC with the FQDN (fully qualified domain name) resolved. Therefore, you may wish to explicitly set the address if you have multiple NICs or if you wish to specify the port number. -When you configure inter-host communication, the local_address can not be localhost and should be configured with an externally visible address (i.e. -192.168.0.2), or you can leave it unspecified in which case the FQDN and an ephemeral port will be used. +When you configure inter-host communication, the local_address can not be localhost and should be configured with an externally visible address (i.e. 192.168.0.2), or you can leave it unspecified in which case the FQDN and an ephemeral port will be used. FQDN resolution is dependent upon system configuration. In the absence of a FQDN (e.g. ``example.opendds.org``), OpenDDS will use any discovered short names (e.g. example). @@ -2512,9 +2474,7 @@ The following table summarizes the transport configuration options that are uniq .. _run_time_configuration--reftable21: -**Table TCP/IP Configuration Options** - -.. list-table:: +.. list-table:: TCP Transport Configuration Options :header-rows: 1 * - Option @@ -2632,9 +2592,7 @@ The following table summarizes the transport configuration options that are uniq .. _run_time_configuration--reftable22: -**Table UDP/IP Configuration Options** - -.. list-table:: +.. list-table:: UDP Transport Configuration Options :header-rows: 1 * - Option @@ -2737,9 +2695,7 @@ The following table summarizes the transport configuration options that are uniq .. _run_time_configuration--reftable23: -**Table IP Multicast Configuration Options** - -.. list-table:: +.. list-table:: Multicast Transport Configuration Options :header-rows: 1 * - Option @@ -2908,9 +2864,7 @@ Some implementation notes related to using the ``rtps_udp`` transport protocol a .. _run_time_configuration--reftable24: -**Table RTPS_UDP Configuration Options** - -.. list-table:: +.. list-table:: RTPS/UDP Transport Configuration Options :header-rows: 1 * - Option @@ -3086,9 +3040,7 @@ The ``RtpsUdpInst`` class has a method ``count_messages(bool flag)`` via inherit With count_messages enabled, the transport will track various counters and make them available to the application using the method ``append_transport_statistics(TransportStatisticsSequence& seq)``. The elements of that sequence are defined in IDL: ``OpenDDS::DCPS::TransportStatistics`` and detailed in the tables below. -**TransportStatistics** - -.. list-table:: +.. list-table:: ``TransportStatistics`` :header-rows: 1 * - **Type** @@ -3204,9 +3156,7 @@ As part of transport negotiation (:ref:`run_time_configuration--using-mixed-tran .. _run_time_configuration--reftable25: -**Table Shared-Memory Transport Configuration Options** - -.. list-table:: +.. list-table:: Shared-Memory Transport Configuration Options :header-rows: 1 * - Option @@ -3385,14 +3335,10 @@ By default, the OpenDDS framework will only log serious errors and warnings that An OpenDDS user may increase the amount of logging via the log level and debug logging via controls at the DCPS, Transport, or Security layers. The default destination of these log messages is the process's standard error stream. -See :ref:`Table 7-2 Common Configuration Options ` for options controlling the destination and formatting of log messages. +See :ref:`run_time_configuration--common-configuration-options` for options controlling the destination and formatting of log messages. The highest level logging is controlled by the general log levels listed in the following table. -.. _run_time_configuration--reftable26: - -**Table : Log Levels** - .. list-table:: :header-rows: 1 @@ -3464,7 +3410,10 @@ To do it with command line arguments, pass: Using a configuration file option is similar: -``DCPSLogLevel=notice`` +.. code-block:: ini + + [common] + DCPSLogLevel=notice Doing this from code can be done using an enumerator or a string: @@ -3542,9 +3491,7 @@ For the moment this can only be configured using C++; for example: .. _run_time_configuration--reftable27: -**Table Transport Debug Logging Categories** - -.. list-table:: +.. list-table:: Transport Debug Logging Categories :header-rows: 1 * - Option @@ -3581,14 +3528,12 @@ Security Debug Logging .. Sect<7.6.3> -When OpenDDS is compiled with security enabled, debug logging for security can be enabled using ``DCPSecurityDebug`` (:ref:`Table 7-2 Common Configuration Options `). +When OpenDDS is compiled with security enabled, debug logging for security can be enabled using ``DCPSecurityDebug`` (:ref:`run_time_configuration--common-configuration-options`). Security logging is divided into categories, although ``DCPSSecurityDebugLevel`` is also provided, which controls the categories in a similar manner and using the same scale as ``DCPSDebugLevel``. .. _run_time_configuration--reftable28: -**Table Security Debug Logging Categories** - -.. list-table:: +.. list-table:: Security Debug Logging Categories :header-rows: 1 * - Option @@ -3705,4 +3650,3 @@ All the following are equivalent: OpenDDS::DCPS::security_debug.access_warn = true; OpenDDS::DCPS::security_debug.set_debug_level(1); OpenDDS::DCPS::security_debug.parse_flags(ACE_TEXT("access_warn")); - diff --git a/docs/devguide/safety_profile.rst b/docs/devguide/safety_profile.rst index 3fd575188e2..5b095ae88ba 100644 --- a/docs/devguide/safety_profile.rst +++ b/docs/devguide/safety_profile.rst @@ -95,8 +95,8 @@ Run-time Configurable Options .. Sect<13.4> -The memory pool used by OpenDDS can be configured by setting values in the [common] section of the configuration file. -See :ref:`run_time_configuration--common-configuration-options` and the pool_size and pool_granularity rows of table :ref:`Table 7-2 `. +The memory pool used by OpenDDS can be configured by setting values in the ``[common]`` section of the configuration file. +See ``pool_size`` and ``pool_granularity`` in :ref:`run_time_configuration--common-configuration-options`. .. _safety_profile--running-ace-and-opendds-tests: diff --git a/docs/devguide/the_dcps_information_repository.rst b/docs/devguide/the_dcps_information_repository.rst index 4db9f4981a5..c3c8978e467 100644 --- a/docs/devguide/the_dcps_information_repository.rst +++ b/docs/devguide/the_dcps_information_repository.rst @@ -26,11 +26,7 @@ DCPS Information Repository Options The table below shows the command line options for the ``DCPSInfoRepo`` server: -.. _the_dcps_information_repository--reftable30: - -**Table DCPS Information Repository Options** - -.. list-table:: +.. list-table:: DCPS Information Repository Options :header-rows: 1 * - Option @@ -107,9 +103,7 @@ Currently available configuration options are: .. _the_dcps_information_repository--reftable31: -**Table InfoRepo persistence directives** - -.. list-table:: +.. list-table:: InfoRepo persistence directives :header-rows: 1 * - Options @@ -185,7 +179,7 @@ Failover sequencing will attempt to reach the next repository in numeric sequenc This sequence is unique to each application configured, and should be different to avoid overloading any individual repository. Once the topology information has been specified, then repositories will need to be started with two additional command line arguments. -These are shown in :ref:`Table 9-1 `. +These are shown in :ref:`the_dcps_information_repository--dcps-information-repository-options`. One, ``-FederationId ``, specifies the unique identifier for a repository within the federation. This is a 32 bit numeric value and needs to be unique for all possible federation topologies. @@ -219,16 +213,13 @@ It has a command format syntax of: repoctl -Where each individual command has its own format as shown in :ref:`Table 9-3 `. Some options contain endpoint information. This information consists of an optional host specification, separated from a required port specification by a colon. This endpoint information is used to create a CORBA object reference using the corbaloc: syntax in order to locate the 'Federator' object of the repository server. .. _the_dcps_information_repository--reftable32: -**Table repoctl Repository Management Command** - -.. list-table:: +.. list-table:: repoctl Repository Management Command :header-rows: 1 * - Command @@ -278,13 +269,9 @@ A join command specifies two repository servers (by endpoint) and asks the secon This generates a CORBA object reference of ``corbaloc::otherhost:1812/Federator`` that the federator connects to and invokes a join operation. The join operation invocation passes the default Federation Domain value (because we did not specify one) and the location of the joining repository which is obtained by resolving the object reference ``corbaloc::localhost:2112/Federator``. -A full description of the command arguments are shown in :ref:`Table 9-4 `. - .. _the_dcps_information_repository--reftable33: -**Table Federation Management Command Arguments** - -.. list-table:: +.. list-table:: Federation Management Command Arguments :header-rows: 1 * - Option diff --git a/docs/devguide/xtypes.rst b/docs/devguide/xtypes.rst index 134d133abe9..0bda592343d 100644 --- a/docs/devguide/xtypes.rst +++ b/docs/devguide/xtypes.rst @@ -64,7 +64,7 @@ There are 3 kinds of extensibility for types: This can be considered a non-extensible constructed type, with behavior similar to that of a type created before XTypes. A type can be marked as final with the :ref:`@final ` annotation. -The default extensibility can be changed with the :ref:`--default-extensibility ` opendds_idl option. +The default extensibility can be changed with :option:`opendds_idl --default-extensibility`. Structs, unions, and enums are the only types which can use any of the extensibilities. @@ -647,7 +647,7 @@ Determining Extensibility The extensibility annotations can explicitly define the :ref:`extensibility ` of a type. If no extensibility annotation is used, then the type will have the default extensibility. -This will be `appendable` unless the :ref:`--default-extensibility ` `opendds_idl` option is to override the default. +This will be `appendable` unless the :option:`opendds_idl --default-extensibility` is used to override the default. .. _xtypes--mutable: @@ -873,7 +873,7 @@ Enabling Use of CompleteTypeObjects Sect<16.7.1.1> To enable use of ``CompleteTypeObject``\s needed for the dynamic binding, they must be generated and OpenDDS must be configured to use them. -To generate them, :ref:`-Gxtypes-complete ` must be passed to ``opendds_idl`` (:ref:`opendds_idl--opendds-idl-command-line-options`). +To generate them, use :option:`opendds_idl -Gxtypes-complete`. For MPC, this can be done by adding this to the opendds_idl arguments for idl files in the project, like this: .. code-block:: mpc diff --git a/docs/news.d/_releases/v3.24.0.rst b/docs/news.d/_releases/v3.24.0.rst index 2b4901a3996..258d437962b 100644 --- a/docs/news.d/_releases/v3.24.0.rst +++ b/docs/news.d/_releases/v3.24.0.rst @@ -52,6 +52,8 @@ Fixes - Fixed issue with using ``-o`` in ``tao_idl``/``opendds_idl`` options in ``OPENDDS_TARGET_SOURCES`` and those directories are now automatically included (:ghpr:`4071`) - XTypes (:ghpr:`4078`) + .. _3-24-0-typeobject-fix: + - ``TypeObject``\s struct and union members used to be sorted by member ID, but they are now sorted by declaration order as the XTypes spec calls for. By default member IDs increment starting at 0, and in that case the ``TypeObject``\s will be the same. @@ -61,7 +63,7 @@ Fixes - Topics with final and appendable structs will no longer match. - If ``DISALLOW_TYPE_COERCION`` QoS is being used, then all topics where the order differ will not longer match. Note that this is true for any time the type hash changes. - - Pass the ``--old-typeobject-member-order`` option to ``opendds_idl`` to use the non-standard order. + - Pass the :option:`opendds_idl --old-typeobject-member-order` to use the non-standard order. - The size of XCDR2 member parameters in mutable structs and unions is now correctly interpreted when the "length code" is 5, 6, or 7. diff --git a/docs/news.d/devguide-improvments.rst b/docs/news.d/devguide-improvments.rst new file mode 100644 index 00000000000..6cc56c50fc7 --- /dev/null +++ b/docs/news.d/devguide-improvments.rst @@ -0,0 +1,7 @@ +.. news-prs: 0 + +.. news-start-section: Documentation +- Restructured parts of :ref:`dds_security` page and expanded documentation of some XML security document elements. +- OS-specific instructions will now be automatically selected based on the browser's user agent. +- OMG specification section references are now links to that section in the specification PDF. +.. news-end-section