Migration Guide to Fast DDS v3
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.
Migration Steps
The following steps describe the possible changes that your project may require to migrate to Fast DDS v3.0.0:
Step 1: Update the package name and CMake configuration
CMake project name: Rename all instances in the CMake project from
fastrtps
tofastdds
. For example, updatetarget_link_libraries(fastrtps)
totarget_link_libraries(fastdds)
, andif(NOT fastrtps_FOUND)
toif(NOT fastdds_FOUND)
.Environment variables:
Rename
FASTRTPS_DEFAULT_PROFILES_FILE
toFASTDDS_DEFAULT_PROFILES_FILE
.The configuration file for loading profiles has been renamed from
DEFAULT_FASTRTPS_PROFILES.xml
toDEFAULT_FASTDDS_PROFILES.xml
.
Step 2: Update dependencies
Fast DDS v3 is only compatible with Fast CDR v2. If you are not using Fast CDR as third-party, please ensure that your local dependencies are up-to-date. Refer to the library deprendencies table to verify version compatibility for all Fast DDS library dependencies.
Step 4: Apply namespace changes
Namespace migration:
First, update all
eprosima::fastrtps::
namespace references toeprosima::fastdds::
.Move built-in topics
SubscriptionBuiltinTopicData
,PublicationBuiltinTopicData
, andParticipantBuiltinTopicData
fromeprosima::fastdds::dds::builtin::
toeprosima::fastdds::rtps::
.Move
Duration_t
andc_TimeInfinite
references fromeprosima::fastdds::
toeprosima::fastdds::dds
.Move
Time_t.hpp
references fromeprosima::fastdds::
toeprosima::fastdds::dds
.
Ensure you update these namespace references across your code to avoid compilation errors.
Renamed types:
Change
EventKindBits::
references toEventKind::
.Change
EventKindEntityId::
references toEntityId::
.Change
StatisticsEventKind::
references tostatistics::EventKind::
.
Refactor the type references as outlined above to maintain compatibility with the new version.
Step 5: Migrate public headers
Header files location:
All the headers in
include/fastrtps
were migrated toinclude/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 v2 file include path
Fast DDS v3 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/dds/domain/qos/DomainParticipantExtendedQos.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 fromfastrtps/utils/fixed_size_string.hpp
tofastcdr/cdr/fixed_size_string.hpp
.File extensions:
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:
ParticipantAttributes.hpp
ReplierAttributes.hpp
RequesterAttributes.hpp
PublisherAttributes.hpp
SubscriberAttributes.hpp
ProxyPool.hpp
Semaphore.hpp
MessageReceiver.hpp
BuiltinProtocols.hpp
shared_mutex.hpp
StringMatching.hpp
TimeConversion.hpp
DBQueue.hpp
ResourceEvent.hpp
TimedEvent.hpp
WriterProxyData.hpp
ReaderProxyData.hpp
ParticipantProxyData.hpp
XML Parser API
UnitsParser.hpp
RTPSMessageGroup.hpp
RTPSMessageCreator.hpp
CDRMessage.hpp
StatefulPersistentReader.hpp
StatefulReader.hpp
StatelessPersistentReader.hpp
StatelessReader.hpp
PersistentWriter.hpp
StatefulPersistentWriter.hpp
StatefulWriter.hpp
StatelessPersistentWriter.hpp
StatelessWriter.hpp
logging.h
Exception.h
Cryptography.h
Authentication.h
AccessControl.h
SecurityException.h
ChangeForReader.hpp
ReaderLocator.hpp
ReaderProxy.hpp
ServerAttributes.hpp
TopicAttributes.hpp
TypeLookupService.hpp
If your project previously included any of these headers, you will need to modify your implementation.
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.
Deprecated methods |
New methods |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
Enum and Variable Changes:
Rename
DiscoveryProtocol_t
toDiscoveryProtocol
.Rename
initialHeartbeatDelay
toinitial_heartbeat_delay
.Rename
heartbeatPeriod
toheartbeat_period
.Rename
nackResponseDelay
tonack_response_delay
.Rename
nackSupressionDuration
tonack_supression_duration
.Rename
heartbeatResponseDelay
toheartbeat_response_delay
.Rename
initialAcknackDelay
toinitial_acknack_delay
.Rename
expectsInlineQos
toexpects_inline_qos
.Rename
m_typeSize
tomax_serialized_type_size
.Rename
m_isGetKeyDefined
tois_compute_key_provided
.Rename
m_topicDataTypeName
totopic_data_typename
.
Extend Built-in Topics:
SubscriptionBuiltinTopicData
has been extended with additional fields to mimic those ofReaderProxyData
.PublicationBuiltinTopicData
has been extended with additional fields to mimic those ofWriterProxyData
.ParticipantBuiltinTopicData
has been extended to include the product version and fields fromParticipantProxyData
.
Other Struct Changes:
SendBuffersAllocationAttributes
has a new attribute to define the allocation configuration of theNetworkBuffers
.TypeConsistencyQos
has been removed fromDataReader
, and theTypeConsistencyEnforcementQosPolicy
andDataRepresentationQosPolicy
have been added.
Step 9: Examples refactor
All examples in the Fast DDS project have been refactored to follow a consistent structure, having renamed files, restructured classes, and updated the overall format. If you have integrated any example into your own implementation, carefully review the updated examples to ensure compatibility with your project. As reference, consider the example Configuration.