Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[22012] Update migration guide removing things not related to application developer #1003

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

[22012] Update migration guide removing things not related to application developer #1003

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
956249c
Refs #22012: Updated Step 4 format
juanjo4936 Dec 20, 2024
486afce
Refs #22012: Modified and expanded Step 1
juanjo4936 Dec 23, 2024
8b436d3
Refs #22012: Updated Step 4
juanjo4936 Dec 23, 2024
a1d8b70
Refs #22012: Clarified the relocation of fixed_size_string.hpp
juanjo4936 Dec 24, 2024
1cd570e
Refs #22012: Added TODO comments to start discussion
juanjo4936 Dec 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 24 additions & 17 deletions docs/notes/migration_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,18 @@ The following steps describe the possible changes that your project may require

.. _step-1-update-the-package-name-and-cmake-configuration:

Step 1: Update the package name and CMake configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Step 1: Update the package name and CMake and Colcon configurations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. CMake project name: Rename the CMake project from ``fastrtps`` to ``fastdds``.
2. Environment variables:
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. If using Colcon, update the package name in ``colcon.pkg`` from ``fastrtps`` to ``fastdds``.
3. 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 +70,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 @@ -145,7 +143,10 @@ 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``.

.. TODO:: Fix this table, ``fastdds/rtps/DomainParticipantQos.hpp`` has wrong path and doesn't include the content.
Copy link
Contributor Author

@juanjo4936 juanjo4936 Dec 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is not in this path, and doesn't match the content. I think maybe fastdds/dds/domain/qos/DomainParticipantExtendedQos.hpp? The class would then be DomainParticipantExtendedQos, a change that should be mentioned.


2. File extensions:

Expand Down Expand Up @@ -209,6 +210,8 @@ If your project previously included any of these headers, you will need to modif
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.

.. TODO:: Add a note about which headers to use instead of the private ones.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this is way too brief. Shouldn't we explain what they should include instead?

.. _step-7-update-api-methods:

Step 7: Update API methods
Expand Down Expand Up @@ -396,6 +399,9 @@ your code to reflect these changes:
Step 9: Examples refactor
^^^^^^^^^^^^^^^^^^^^^^^^^

.. TODO:: What to do here? Write which examples in 2 turned into which examples in 3?
A lot of the info seems too much.

Copy link
Contributor Author

@juanjo4936 juanjo4936 Dec 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have doubts the section itself is necessary. In any case, what would a user look for here? They would be trying to update the previous version, so the changes we made are not as important, right? I would imagine something like what Juan suggested, mention which examples in v2 became what examples in v3, to maintain their function. Note that it doesn't seem straightforward to me at all, given their naming changes.

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
Expand All @@ -409,15 +415,16 @@ All the examples have been refactored to follow the same structure:
* Detailed and well-formed README.md with example explanation.
* Example structured in applications, stopped by ``SIGTERM`` signal.

Please refactor the examples in your project to match the new format.

`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).
* Added a subscriber implementing the waitsets mechanism.

`X-Types Examples <https://github.com/eProsima/Fast-DDS/tree/master/examples/cpp/xtypes>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Expand Down
Loading