Convert Fast DDS v2 to v3 Migration Changes into a Step-by-Step User …

…Guide (#5281) * Convert Fast DDS v2 to v3 Migration Changes into a Step-by-Step User Guide Signed-off-by: Lucia Echevarria <[email protected]> * Apply suggested changes Signed-off-by: Lucia Echevarria <[email protected]> --------- Signed-off-by: Lucia Echevarria <[email protected]>
eProsima · Sep 30, 2024 · 20a4c10 · 20a4c10
1 parent dd0f7f2
commit 20a4c10
Showing 1 changed file with 134 additions and 97 deletions.
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -3,86 +3,103 @@
 This document aims to help during the migration process from eProsima *Fast DDS version* 2 to *Fast DDS version* 3.
 For more information about all the updates, please refer to the [release notes](https://fast-dds.docs.eprosima.com/en/latest/notes/notes.html).
 
-It is always *required* to regenerate the types with the appropriate version of *eProsima Fast DDS Gen*,
-(see [products compatibility](https://fast-dds.docs.eprosima.com/en/latest/notes/versions.html#eprosima-products-compatibility)).
-The compatible version with *Fast DDS v3.0.0* is *Fast DDS Gen* v4.0.0.
+## Migration Steps
 
-The following sections describe the possible changes that your project may require to migrate to *Fast DDS v3.0.0*.
+The following steps describe the possible changes that your project may require to migrate to *Fast DDS v3.0.0*:
 
-- [Library management](#library-management)
-- [Compatibility with Fast CDR](#compatibility-with-fast-cdr)
-- [Namespace migrations and changes](#namespace-migrations-and-changes)
-- [Public headers migrated to *fastdds*](#public-headers-migrated-to-fastdds)
-- [Public headers moved to private](#public-headers-moved-to-private)
-- [API changes](#api-changes)
-- [Struct, Enum, Variable](#struct-enum-variable)
-- [Examples](#examples)
+- [Step 1: Update the Package Name and CMake Configuration](#step-1-update-the-package-name-and-cmake-configuration)
+- [Step 2: Update Dependencies](#step-2-update-dependencies)
+- [Step 3: Ensure Compability with Related Products](#step-3-ensure-compability-with-related-products)
+- [Step 4: Apply Namespace Changes](#step-4-apply-namespace-changes)
+- [Step 5: Migrate Public Headers](#step-5-migrate-public-headers)
+- [Step 6: Handle Removed or Private Headers](#step-6-handle-removed-or-private-headers)
+- [Step 7: Update API Methods](#step-7-update-api-methods)
+- [Step 8: Update Structs, Enums, and Variables](#step-8-update-structs-enums-and-variables)
+- [Step 9: Refactor Examples](#step-9-refactor-examples)
 
-## Library management
+### Step 1: Update the Package Name and CMake Configuration
 
-The list below exposes exposes the changes related to the package name, environment variables and other library usages.
+1. CMake Project Name: Rename the CMake project from `fastrtps` to `fastdds`.
+2. Environment Variables:
 
-* The CMake project has been renamed from `fastrtps` to `fastdds`.
-* XML profiles loading environment variable has been renamed to: `FASTDDS_DEFAULT_PROFILES_FILE`.
-* The configuration file that Fast DDS looks for to load the profiles has been renamed to `DEFAULT_FASTDDS_PROFILES.xml`.
-* XML Schema namespace in `fastdds_profiles.xsd` has been updated to http://www.eprosima.com.
-* CMake Windows file names have been changed:
+    * Rename `FASTRTPS_DEFAULT_PROFILES_FILE` to `FASTDDS_DEFAULT_PROFILES_FILE`.
+    * The configuration file for loading profiles is now `DEFAULT_FASTDDS_PROFILES.xml`.
+3. Update CMake File Names on Windows:
 
-    * fastdds.manifest.in
-    * fastdds-config.cmake
+    * Rename fastrtps.manifest.in to fastdds.manifest.in
+    * Rename fastrtps-config.cmake to fastdds-config.cmake
+    * Rename fastrtps.rc to fastdds.rc
 
-* The fastrtps.rc file has been renamed as fastdds.rc.
-* Deprecated APIs marked with `FASTDDS_DEPRECATED` and `FASTDDS_TODO_BEFORE` macros have been removed.
 
-## Compatibility with Fast CDR
+### Step 2: Update Dependencies
 
 Fast DDS v3 is only compatible with Fast CDR v2.
 If you are not using Fast CDR as [third-party](https://fast-dds.docs.eprosima.com/en/latest/installation/configuration/cmake_options.html#third-party-libraries-options), please ensure that your local dependencies are up-to-date.
+Refer to the [library deprendencies table](https://fast-dds.docs.eprosima.com/en/latest/notes/versions.html#library-dependencies) to verify version compatibility for all Fast DDS library dependencies.
 
-## Namespace migrations and changes
+### Step 3: Ensure Compability with Related Products
 
-The following list contains the namespace changes and migrations:
+Fast DDS v3 requires Fast DDS Gen v4 for code generation. Make sure to regenerate types using this compatible version.
 
-* All `eprosima::fastrtps::` namespace references were moved to `eprosima::fastdds::`.
-* `SubscriptionBuiltinTopicData`, `PublicationBuiltinTopicData` and `ParticipantBuiltinTopicData` were moved from `fastdds::dds::builtin::` to `fastdds::dds::`.
-* `EventKindBits::` references changed to`EventKind::`.
-* `EventKindEntityId::` references changed to`EntityId::`.
-* `StatisticsEventKind::` references changed to `statistics::EventKind::`.
-* `Duration_t` and `c_TimeInfinite` references were moved to `dds::`.
-* `Time_t.hpp` references were moved from `eprosima::fastdds::` to `eprosima::fastdds::dds`.
+For other compatibility requirements with related products (e.g., Shapes Demo, Discovery Server), refer to the table of [products compatibility](https://fast-dds.docs.eprosima.com/en/latest/notes/versions.html#eprosima-products-compatibility), which outlines version compatibility across the Fast DDS ecosystem.
+Verify these versions and update accordingly to avoid any integration issues.
 
-## Public headers migrated to *fastdds*
+### Step 4: Apply Namespace Changes
 
-All the extensions of the headers under `include`, which are the public headers that applications can include, have been changed to `.hpp`.
-Also, the `fixed_size_string.hpp` implementation has been migrated from Fast DDS package to Fast CDR.
+1. Namespace Migration:
 
-All the headers in `include/fastrtps` were migrated to `include/fastdds`.
-In particular, the following list includes headers that have been relocated to different paths or whose implementations have been incorporated into other headers.
+    * Update all `eprosima::fastrtps::` namespace references to `eprosima::fastdds::`.
+    * Move built-in topics `SubscriptionBuiltinTopicData`, `PublicationBuiltinTopicData` and `ParticipantBuiltinTopicData` from `fastdds::dds::builtin::` to `fastdds::dds::`.
+    * Move `Duration_t` and `c_TimeInfinite` references to `dds::`.
+    * Move `Time_t.hpp` references from `eprosima::fastdds::` to `eprosima::fastdds::dds`.
 
-| Fast DDS 2.x file *include* path | Fast DDS v3.0.0 file *include* path |
-|----------------------------------|-------------------------------------|
-| fastdds/rtps/resources/ResourceManagement.hpp | fastdds/rtps/attributes/ResourceManagement.hpp |
-| fastrtps/eProsima_auto_link.h | fastdds/fastdds_auto_link.hpp |
-| fastrtps/attributes/ParticipantAttributes.h | fastdds/rtps/DomainParticipantQos.hpp |
-| fastrtps/Domain.h | fastdds/dds/domain/DomainParticipantFactory.hpp |
-| fastrtps/log/Log.h | fastdds/dds/log/Log.hpp |
-| fastrtps/qos/DeadlineMissedStatus.h	| fastdds/dds/core/status/DeadlineMissedStatus.hpp |
-| fastrtps/qos/IncompatibleQosStatus.hpp | fastdds/dds/core/status/IncompatibleQosStatus.hpp |
-| fastrtps/qos/LivelinessChangedStatus.h | fastdds/dds/core/status/LivelinessChangedStatus.hpp |
-| fastrtps/qos/QosPolicies.h | fastdds/dds/core/policy/QosPolicies.hpp |
-| fastrtps/qos/ReaderQos.h | fastdds/dds/subscriber/qos/ReaderQos.hpp |
-| fastrtps/qos/WriterQos.h | fastdds/dds/publisher/qos/WriterQos.hpp |
-| fastrtps/qos/SampleRejectedStatus.hpp | fastdds/dds/core/status/SampleRejectedStatus.hpp |
-| fastrtps/participant/Participant.h | fastdds/rtps/participant/RTPSParticipant.hpp |
-| fastrtps/transport/TCPv4TransportDescriptor.h | fastdds/rtps/transport/TCPv4TransportDescriptor.hpp |
-| fastrtps/transport/TCPv6TransportDescriptor.h| 	fastdds/rtps/transport/ TCPv6TransportDescriptor.hpp |
-| fastrtps/transport/UDPv4TransportDescriptor.h | fastdds/rtps/transport/ UDPv4TransportDescriptor.hpp |
-| fastrtps/transport/UDPv6TransportDescriptor.h | fastdds/rtps/transport/ UDPv6TransportDescriptor.hpp |
-| fastrtps/transport/UDPTransportDescritpor.h | fastdds/rtps/transport/UDPTransportDescritpor.hpp |
-| fastrtps/transport/TCPTransportDescritpor.h | fastdds/rtps/transport/TCPTransportDescritpor.hpp |
-| fastdds/rtps/common/Time_t.hpp in namespace{fastdds} | fastdds/dds/core/Time_t.hpp in namespace{fastdds::dds} |
-
-## Public headers moved to private
+Ensure you update these namespace references across your code to avoid compilation errors.
+
+2. Renamed Types:
+
+    * Change `EventKindBits::` references to`EventKind::`.
+    * Change `EventKindEntityId::` references to`EntityId::`.
+    * Change `StatisticsEventKind::` references to `statistics::EventKind::`.
+
+Refactor the type references as outlined above to maintain compatibility with the new version.
+
+### Step 5: Migrate Public Headers
+
+1. File Location headers:
+
+    All the headers in `include/fastrtps` were migrated to `include/fastdds`.
+    In particular, the following list includes headers that have been relocated to different paths or whose implementations have been incorporated into other headers:
+
+    | Fast DDS 2.x file *include* path | Fast DDS v3.0.0 file *include* path |
+    |----------------------------------|-------------------------------------|
+    | fastdds/rtps/resources/ResourceManagement.hpp | fastdds/rtps/attributes/ResourceManagement.hpp |
+    | fastrtps/eProsima_auto_link.h | fastdds/fastdds_auto_link.hpp |
+    | fastrtps/attributes/ParticipantAttributes.h | fastdds/rtps/DomainParticipantQos.hpp |
+    | fastrtps/Domain.h | fastdds/dds/domain/DomainParticipantFactory.hpp |
+    | fastrtps/log/Log.h | fastdds/dds/log/Log.hpp |
+    | fastrtps/qos/DeadlineMissedStatus.h	| fastdds/dds/core/status/DeadlineMissedStatus.hpp |
+    | fastrtps/qos/IncompatibleQosStatus.hpp | fastdds/dds/core/status/IncompatibleQosStatus.hpp |
+    | fastrtps/qos/LivelinessChangedStatus.h | fastdds/dds/core/status/LivelinessChangedStatus.hpp |
+    | fastrtps/qos/QosPolicies.h | fastdds/dds/core/policy/QosPolicies.hpp |
+    | fastrtps/qos/ReaderQos.h | fastdds/dds/subscriber/qos/ReaderQos.hpp |
+    | fastrtps/qos/WriterQos.h | fastdds/dds/publisher/qos/WriterQos.hpp |
+    | fastrtps/qos/SampleRejectedStatus.hpp | fastdds/dds/core/status/SampleRejectedStatus.hpp |
+    | fastrtps/participant/Participant.h | fastdds/rtps/participant/RTPSParticipant.hpp |
+    | fastrtps/transport/TCPv4TransportDescriptor.h | fastdds/rtps/transport/TCPv4TransportDescriptor.hpp |
+    | fastrtps/transport/TCPv6TransportDescriptor.h| 	fastdds/rtps/transport/ TCPv6TransportDescriptor.hpp |
+    | fastrtps/transport/UDPv4TransportDescriptor.h | fastdds/rtps/transport/ UDPv4TransportDescriptor.hpp |
+    | fastrtps/transport/UDPv6TransportDescriptor.h | fastdds/rtps/transport/ UDPv6TransportDescriptor.hpp |
+    | fastrtps/transport/UDPTransportDescritpor.h | fastdds/rtps/transport/UDPTransportDescritpor.hpp |
+    | fastrtps/transport/TCPTransportDescritpor.h | fastdds/rtps/transport/TCPTransportDescritpor.hpp |
+    | fastdds/rtps/common/Time_t.hpp in namespace{fastdds} | fastdds/dds/core/Time_t.hpp in namespace{fastdds::dds} |
+
+    Also, the `fixed_size_string.hpp` implementation has been migrated from Fast DDS package to Fast CDR.
+
+2. File Extentions:
+
+    Rename file extensions from `.h` to `.hpp`.
+
+### Step 6: Handle Removed or Private Headers
 
 The following list contains headers that were previously in the `include` folder and have been relocated to the `src/cpp` folder.
 Since they are no longer public, it is not possible to include them in external projects:
@@ -132,7 +149,10 @@ Since they are no longer public, it is not possible to include them in external
 * TopicAttributes.hpp
 * TypeLookupService.hpp
 
-## API changes
+If your project previously included any of these headers, you will need to modify your implementation.
+Since these headers are now private, you should replace their usage with public alternatives or refactor the related code to ensure it does not depend on private headers.
+
+### Step 7: Update API Methods
 
 The table below contains the list of API changes, showing the previous methods and the corresponding new ones introduced in Fast DDS v3.
 The new API methods achieve the same functionality, even though the signature of the method is different from the deprecated one.
@@ -203,47 +223,64 @@ The new API methods achieve the same functionality, even though the signature of
 | DynamicPubSubType::getKey(const void* const, `InstanceHand`*, bool) | DynamicPubSubType::compute_key(const void* const, `InstanceHand`&, bool) |
 | DynamicPubSubType::getSerializedSizeProvider(const void* const, `DataRepresentationId_t`) | DynamicPubSubType::calculate_serialized_size(const void* const, `DataRepresentationId_t`) |
 
-## Struct, Enum, Variable
-
-The following list shows the changes of the struct, enums and variables that have been modified.
-
-* Extend `SubscriptionBuiltinTopicData` with additional fields to mimic those of `ReaderProxyData`.
-* Extend `PublicationBuiltinTopicData` with additional fields to mimic those of `WriterProxyData`.
-* Extend `ParticipantBuiltinTopicData` adding the the Product version and additional fields to mimic those of `ParticipantProxyData`.
-* `DiscoveryProtocol_t` is `DiscoveryProtocol`.
-* Extend `SendBuffersAllocationAttributes` with a new attribute defining the allocation configuration of the `NetworkBuffers`.
-* `TypeConsistencyQos` was removed from DataReader, and `TypeConsistencyEnforcementQosPolicy` and `DataRepresentationQosPolicy` were included.
-* `initialHeartbeatDelay` is `initial_heartbeat_delay`.
-* `heartbeatPeriod` is `heartbeat_period`.
-* `nackResponseDelay` is `nack_response_delay`.
-* `nackSupressionDuration` is `nack_supression_duration`.
-* `heartbeatResponseDelay` is `heartbeat_response_delay`.
-* `initialAcknackDelay` is `initial_acknack_delay`.
-* `expectsInlineQos` is `expects_inline_qos`.
-* `m_typeSize` is `max_serialized_type_size`
-* `m_isGetKeyDefined` is `is_compute_key_provided`
-* `m_topicDataTypeName` is `topic_data_typename_`
-
-## Examples
+Review your code for any APIs marked with the `FASTDDS_DEPRECATED` and `FASTDDS_TODO_BEFORE` macros.
+Note that these deprecated APIs have been removed in Fast DDS v3.
+Make the necessary updates to your implementation to ensure compatibility with the new version.
+
+### Step 8: Update Structs, Enums, and Variables
+
+As part of the Fast DDS migration, several structs, enums, and variables have been updated. You will need to modify your code to reflect these changes:
+
+1. Enum and Variable Changes:
+
+    * `DiscoveryProtocol_t` is now `DiscoveryProtocol`.
+    * Rename `initialHeartbeatDelay` to `initial_heartbeat_delay`.
+    * Rename `heartbeatPeriod` to `heartbeat_period`.
+    * Rename `nackResponseDelay` to `nack_response_delay`.
+    * Rename `nackSupressionDuration` to `nack_supression_duration`.
+    * Rename `heartbeatResponseDelay` to `heartbeat_response_delay`.
+    * Rename `initialAcknackDelay` to `initial_acknack_delay`.
+    * Rename `expectsInlineQos` to `expects_inline_qos`.
+    * Rename `m_typeSize` to `max_serialized_type_size`.
+    * Rename `m_isGetKeyDefined` to `is_compute_key_provided`.
+    * Rename `m_topicDataTypeName` to `topic_data_typename`.
+
+2. Extend Built-in Topics:
+
+    * `SubscriptionBuiltinTopicData` has been extended with additional fields to mimic those of `ReaderProxyData`.
+    * `PublicationBuiltinTopicData` has been extended with additional fields to mimic those of `WriterProxyData`.
+    * `ParticipantBuiltinTopicData` has been extended to include the product version and fields from `ParticipantProxyData`.
+
+3. Other Struct Changes:
+
+    * `SendBuffersAllocationAttributes` has a new attribute to define the allocation configuration of the `NetworkBuffers`.
+    * `TypeConsistencyQos` has been removed from `DataReader`, and the `TypeConsistencyEnforcementQosPolicy` and `DataRepresentationQosPolicy` have been added.
+
+### Step 9: Refactor Examples
+
+All examples have been refactored to follow a consistent structure across the Fast DDS project.
+This includes renaming files, restructuring classes, and updating the overall format.
+Additionally, it is important to note that some examples have been removed, renamed, or had significant changes to their options and configurations.
+If you have integrated any of these examples into your own implementation, carefully review the updated examples to ensure compatibility with your project.
 
 All the examples have been refactored to follow the same structure:
 * File names, guards, and classes follow new format.
 * Detailed and well-formed README.md with example explanation.
 * Example structured in applications, stopped by `SIGTERM` signal.
 
-### Hello World
+#### Hello World
 Refactor the HelloWorld example with the current new example format.
 In this hello world example, the key changes are:
 * The XML profile is loaded from the environment (if defined), and the `--env` CLI option has been removed.
 * Add a subscriber implementing the waitsets mechanism.
 * Provide XML profiles examples targeting several scenarios (e.g., SampleConfig_Controller, Events, Multimedia).
 
-### X-Types Examples
+#### X-Types Examples
 In this X-Types example, a type is defined at runtime on the publisher side using the Dynamic Types API.
 The subscriber discovers the type, creates a reader for it, and prints the received data.
 This example is type compatible with the Hello World example.
 
-### Configuration
+#### Configuration
 In the configuration example, the key changes are:
 * Included LargeData as an option (builtin transport argument).
 * Included all previous QoS examples:
@@ -254,27 +291,27 @@ In the configuration example, the key changes are:
     * Ownership (strength)
     * Partitions
 
-### Content Filter
+#### Content Filter
 Refactor the ContentFilteresTopicExample example with the current new example format.
 In this content filter example, the main changes are:
 * Added	option to select filter type: Default, Custom, or None.
 * Customizable lower-bound and upper-bound options of the filter as arguments.
     * For the Custom filter, they represent the maximum and minimum values of the message indexes that are filtered out through the filter.
     * For the Default filter, they represent the maximum and minimum value message indexes that are read.
 
-### Custom Payload Pool
+#### Custom Payload Pool
 Refactor the CustomPayloadPoolExample example with the current new example format.
 
-### Delivery Mechanisms
+#### Delivery Mechanisms
 In this delivery mechanisms example, the key changes are:
 * Loans and data-sharing compatible: bounded types, final extensibility.
 * Loans mechanism for data management.
 * Option to select all delivery mechanisms.
 
-### Discovery Server
+#### Discovery Server
 Refactor the DiscoveryServerExample example with the current new example format.
 
-### Flow Controller
+#### Flow Controller
 Refactor the FlowControlExample example with the current new example format.
 In this Flow Controller example, the key changes are:
 * Publishers continuously send samples. The user can set the number of samples to send.
@@ -285,16 +322,16 @@ In this Flow Controller example, the key changes are:
     * Property fastdds.sfc.priority.
     * Property fastdds.sfc.bandwidth_reservation.
 
-### Request-Reply
+#### Request-Reply
 Refactor the Request-Reply example with the current new example format.
 
-### Static EDP Discovery
+#### Static EDP Discovery
 Refactor the Static EDP Discovery example with the new example format.
 
-### Security
+#### Security
 Refactor the SecureHelloWorld example with the current new example format.
 
-### RTPS Entities
+#### RTPS Entities
 Refactor the rtps/Registered example with the current new example format.
 This RTPS example demonstrates a basic RTPS deployment.
 The main change is that serialization and deserialization are done with overload methods from fastcdr.