Skip to content

Commit

Permalink
Update migration guide removing things not related to application dev…
Browse files Browse the repository at this point in the history 
…eloper (#1003)

* Refs #22012: Updated Step 4 format

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Modified and expanded Step 1

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Updated Step 4

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Clarified the relocation of fixed_size_string.hpp

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Added TODO comments to start discussion

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Corrected the table in step 4

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Shortened Step 9 significantly

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: corrected typo

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Removed redundant line in step 6

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Solved failing CI

Signed-off-by: Juanjo Garcia <[email protected]>

* Refs #22012: Solved failing CI

Signed-off-by: Juanjo Garcia <[email protected]>

* Update docs/notes/migration_guide.rst

Co-authored-by: Raul Sanchez-Mateos Lizano <[email protected]>
Signed-off-by: juanjo4936 <[email protected]>

---------

Signed-off-by: Juanjo Garcia <[email protected]>
Signed-off-by: juanjo4936 <[email protected]>
Co-authored-by: Raul Sanchez-Mateos Lizano <[email protected]>
  • Loading branch information
@juanjo4936 @rsanchez15
juanjo4936 and rsanchez15 authored Jan 10, 2025
1 parent 79c5d47 commit 7874384
Showing 1 changed file with 15 additions and 129 deletions.
144 changes: 15 additions & 129 deletions docs/notes/migration_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,14 @@ The following steps describe the possible changes that your project may require
Step 1: Update the package name and CMake configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. CMake project name: Rename the CMake project from ``fastrtps`` to ``fastdds``.
1. CMake project name: Rename all instances in the CMake project from ``fastrtps`` to ``fastdds``. For example,
update ``target_link_libraries(fastrtps)`` to ``target_link_libraries(fastdds)``, and ``if(NOT fastrtps_FOUND)`` to
``if(NOT fastdds_FOUND)``.
2. Environment variables:

* 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:

* Rename ``fastrtps.manifest.in`` to ``fastdds.manifest.in``.
* Rename ``fastrtps-config.cmake`` to ``fastdds-config.cmake``.
* Rename ``fastrtps.rc`` to ``fastdds.rc``.
* The configuration file for loading profiles has been renamed from ``DEFAULT_FASTRTPS_PROFILES.xml`` to
``DEFAULT_FASTDDS_PROFILES.xml``.

.. _step-2-update-dependencies:

Expand Down Expand Up @@ -72,10 +69,10 @@ Step 4: Apply namespace changes

1. Namespace migration:

* Update all ``eprosima::fastrtps::`` namespace references to ``eprosima::fastdds::``.
* First, 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::``.
``ParticipantBuiltinTopicData`` from ``eprosima::fastdds::dds::builtin::`` to ``eprosima::fastdds::rtps::``.
* Move ``Duration_t`` and ``c_TimeInfinite`` references from ``eprosima::fastdds::`` to ``eprosima::fastdds::dds``.
* Move ``Time_t.hpp`` references from ``eprosima::fastdds::`` to ``eprosima::fastdds::dds``.

Ensure you update these namespace references across your code to avoid compilation errors.
Expand Down Expand Up @@ -109,7 +106,7 @@ Step 5: Migrate public headers
* - ``fastrtps/eProsima_auto_link.h``
- ``fastdds/fastdds_auto_link.hpp``
* - ``fastrtps/attributes/ParticipantAttributes.h``
- ``fastdds/rtps/DomainParticipantQos.hpp``
- ``fastdds/dds/domain/qos/DomainParticipantExtendedQos.hpp``
* - ``fastrtps/Domain.h``
- ``fastdds/dds/domain/DomainParticipantFactory.hpp``
* - ``fastrtps/log/Log.h``
Expand Down Expand Up @@ -145,7 +142,8 @@ Step 5: Migrate public headers
* - ``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.
Also, the ``fixed_size_string.hpp`` implementation has been migrated from ``fastrtps/utils/fixed_size_string.hpp``
to ``fastcdr/cdr/fixed_size_string.hpp``.

2. File extensions:

Expand Down Expand Up @@ -206,8 +204,6 @@ Since they are no longer public, it is not possible to include them in external
* TypeLookupService.hpp

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:

Expand Down Expand Up @@ -396,117 +392,7 @@ your code to reflect these changes:
Step 9: Examples refactor
^^^^^^^^^^^^^^^^^^^^^^^^^

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/xtypes>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/configuration>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

In the configuration example, the key changes are:

* Included LargeData as an option (builtin transport argument).
* Included all previous QoS examples:

- Deadline
- Disable positive ACKs
- Lifespan
- Liveliness
- Ownership (strength)
- Partitions

`Content Filter <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/custom_payload_pool>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Refactor the CustomPayloadPoolExample example with the current new example format.

`Delivery Mechanism <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/discovery_server>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Refactor the DiscoveryServerExample example with the current new example format.

`Flow Controller <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/flow_control>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

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.
* User can set the following QoS and properties for the Flow Controller:

- Scheduler policy used by the flow controller.
- Maximum number of bytes to be sent to the network per period.
- Period of time in milliseconds during which the flow controller is allowed to send the maximum number of bytes
per period.
- Property `fastdds.sfc.priority`.
- Property `fastdds.sfc.bandwidth_reservation`.

`Request-Reply <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/request_reply>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Refactor the Request-Reply example with the current new example format.

`Static EDP Discovery <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/static_edp_discovery>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Refactor the Static EDP Discovery example with the new example format.

`Security <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/security>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Refactor the SecureHelloWorld example with the current new example format.

`RTPS Entities <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/rtps>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

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.
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 <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/configuration>`_.

0 comments on commit 7874384

Please sign in to comment.