.. include:: /../getting_started/vars.rst .. _section-Install-Upgrade: Important: How to Use this Guide ******************************** .. _section-Install-Upgrade-Path: Upgrade Path ============ This Migration Guide describes how to upgrade to any of the *RTI® Connext®* 6 or |CONNEXT| 7 releases from release 5.3.1 or later. .. attention:: See the upgrade considerations in this guide for *each applicable release*. For example, if you are upgrading from 6.1.0 to 7.3.0, see *all* of the following sections: :ref:`section-index610`, :ref:`section-index611`, and :ref:`section-index700`. Together, these sections provide important upgrade considerations that apply when upgrading from your current to your new release. Whether you will keep some of your legacy |CONNEXT| systems or migrate entirely to a new *Connext* release, read this guide to see what settings or other changes you may need to make before you upgrade all or part of your system. The full set of changes for your release is described in the *What's New* and *Core Libraries Release Notes* documents for your release: * :link_whats_new_750:`What's New in 7.5.0 <>` and :link_release_notes_750:`Core Libraries Release Notes 7.5.0 <>` (see also individual products' :link_rti_community_doc_s:`Release Notes <750>` in 7.5.0) * :link_whats_new_740:`What's New in 7.4.0 <>` and :link_release_notes_740:`Core Libraries Release Notes 7.4.0 <>` (see also individual products' :link_rti_community_doc_s:`Release Notes <740>` in 7.4.0) * :link_whats_new_730:`What's New in 7.3.0 <>` and :link_release_notes_730:`Core Libraries Release Notes 7.3.0 <>` (see also individual products' :link_rti_community_doc_s:`Release Notes <730>` in 7.3.0) * :link_whats_new_720:`What's New in 7.2.0 <>` and :link_release_notes_720:`What's Fixed in 7.2.0 <>` (these features and fixes are included in 7.3.0) * :link_whats_new_710:`What's New in 7.1.0 <>` and :link_release_notes_710:`What's Fixed in 7.1.0 <>` (these features and fixes are included in 7.3.0) * :link_whats_new_700:`What's New in 7.0.0 <>` and :link_release_notes_700:`What's Fixed in 7.0.0 <>` (these features and fixes are included in 7.3.0) * :link_whats_new_612:`What's New in 6.1.2 <>` and :link_release_notes_612:`Core Libraries Release Notes 6.1.2 <>` (see also individual products' :link_rti_community_doc_dds_s:`Release Notes <612>` in 6.1.2) * :link_connext_whats_new_611:`What's New in 6.1.1 <>` and :link_release_notes_611:`Core Libraries Release Notes 6.1.1 <>` (see also individual products' :link_rti_community_doc_dds_s:`Release Notes <611>` in 6.1.1) * :link_connext_whats_new_610:`What's New in 6.1.0 <>` and :link_release_notes_610:`Core Libraries Release Notes 6.1.0 <>` (see also individual products' :link_rti_community_doc_dds_s:`Release Notes <610>` in 6.1.0) * :link_connext_whats_new_601:`What's New in 6.0.1 <>` and :link_release_notes_601:`Core Libraries Release Notes 6.0.1 <>` (see also individual products' :link_rti_community_doc_dds_s:`Release Notes <601>` in 6.0.1) * :link_connext_whats_new_600:`What's New in 6.0.0 <>` and :link_release_notes_600:`Core Libraries Release Notes 6.0.0 <>` (see also individual products' :link_rti_community_doc_dds_s:`Release Notes <600>` in 6.0.0) This guide describes only those changes that may break old behavior. .. _section-Install-Upgrade-Steps: Upgrade Steps ============= Whenever upgrading to a new, major release, you must regenerate the type-specific code that was generated from your IDL, XML, or XSD definitions with the new version of *rtiddsgen*, then recompile and re-link your applications with the new versions of the |CONNEXT| libraries. The basic steps are as follows: #. Make the changes required for your system, based on the compatibility issues described in this guide: * See the "Product-Specific Compatibility" section for your release, for issues that affect your products. * See the "General Compatibility" section for your release. This section is particularly important if your release will coexist with older releases. * See :ref:`section-regression-index` for any issues that may apply to you. |br| |br| #. Regenerate code as described in :numref:`section-Product-gen-code-compatibility`. |br| |br| #. Update your projects as described in :numref:`section-Product-ABI`. If you need help with your upgrade, contact RTI Support: log into the `Customer Portal `_, send email to support@rti.com, or call the telephone number provided for your region. .. _section-gen-compile: Regenerating Code and Updating Your Projects ============================================ .. _section-Product-gen-code-compatibility: Generated code compatibility ---------------------------- For |CONNEXT| applications defining types in IDL, XML, or XSD, moving between any two releases in this guide requires code regeneration and, depending on your programming language, updating your projects and recompiling. You will need to regenerate the code for your application types using the *RTI Code Generator* shipped with your release. The regeneration process is simple; you only need to run the new version of *Code Generator* using the original input IDL file. For example: .. code-block:: text rtiddsgen -language C++11 -update typefiles MyTypes.idl You should see a message that says you are running one of the following *rtiddsgen* versions depending on your release: .. list-table:: rtiddsgen versions :name: TableRtiddsgenVersions :widths: 50 50 :header-rows: 1 * - |CONNEXT| Version - *rtiddsgen* Version * - 7.5.0 - 4.5.0 * - 7.4.0 - 4.4.0 * - 7.3.0 - 4.3.0 * - 6.1.2 - 3.1.2 * - 6.1.1 - 3.1.1 * - 6.1.0 - 3.1.0 * - 6.0.1 - 3.0.1 * - 6.0.0 - 3.0.0 This process will regenerate the source code for your IDL types. .. _section-Product-ABI: Updating your projects ---------------------- C and C++ applications ~~~~~~~~~~~~~~~~~~~~~~ |CONNEXT| does not provide Application Binary Interface (ABI) compatibility with previous versions of |CONNEXT|. Therefore, an application compiled using a previous version of |CONNEXT| must be recompiled when moving to a new |CONNEXT| version. The |CONNEXT| core primarily consists of libraries and a set of header files. In most cases, upgrading simply requires you to recompile your source using the new header files and link your application with the new libraries. If you're using the makefiles or project files generated with *rtiddsgen*, you can re-generate them with the following command: .. code-block:: text rtiddsgen -language -update makefiles -platform MyTypes.idl See :link_codegen_cmd_usersman_730:`Command-Line Arguments <>` in the *RTI Connext Code Generator User's Manual* for more information. Your architecture (such as ``x64Win64VS2017`` or ``x64Linux3gcc5.4.0``) is the combination of a processor, OS, and compiler version. To see the full list of available architectures, see the "RTI Architecture Abbreviation" columns in the :link_connext_platform_notes_730:`RTI Connext Core Libraries Platform Notes <>`. Java applications ~~~~~~~~~~~~~~~~~ Your |CONNEXT| installation provides the JAR files to build Java applications. You will need to recompile using the new JAR files. If you're using the makefiles or project files generated with *rtiddsgen*, you can re-generate them with the following command: .. code-block:: text rtiddsgen -language Java -update makefiles -platform MyTypes.idl See :link_codegen_cmd_usersman_730:`Command-Line Arguments <>` in the *RTI Connext Code Generator User's Manual* for more information. Your architecture (such as ``x64Win64VS2017`` or ``x64Linux3gcc5.4.0``) is the combination of a processor, OS, and compiler version. To see the full list of available architectures, see the "RTI Architecture Abbreviation" columns in the :link_connext_platform_notes_730:`RTI Connext Core Libraries Platform Notes <>`. .. _section-product-csharp-612: C# applications ~~~~~~~~~~~~~~~ Your |CONNEXT| installation provides the NuGet packages that install the |CONNEXT| C# API. These packages are also provided in nuget.org. You will need to update your project files so they use the new libraries. Follow these instructions to upgrade your existing C# projects to the new |CONNEXT| version: #. (Skip this step if you're using `nuget.org `__ to obtain the |CONNEXT| C# package.) Install the new |CONNEXT| host and .NET support packages. See :link_gsg_csharp_730:`Installing Connext <>` in the *RTI Connext Getting Started Guide* for information. Make sure your Nuget configuration (typically in the ``Nuget.Config`` next to your ``.csproj`` file) points to the new |CONNEXT| installation directory. |br| |br| #. Update your ``.csproj`` files, using one of the following steps: - Edit the ``.csproj`` file and replace ``Version=""`` with the current version. For example, replace ``Version="6.1.2"`` with ``Version="7.3.0"``, or |br| |br| - Update the version using the Visual Studio NuGet package manager, or |br| |br| - Run the following command in the directory where your ``.csproj`` file is to get the latest version: ``dotnet add package Rti.ConnextDds.Extra``. (Don't add ``.Extra`` to the package name if you're using .NET Core 2.x or .NET Framework.) Python applications ~~~~~~~~~~~~~~~~~~~ To upgrade your Python applications, simply upgrade your |CONNEXT| package. The |CONNEXT| package is provided in your |CONNEXT| installation (``rti.connext.activated``) and on pypi.org (``rti.connext``). You can see which package you currently have installed with: .. code-block:: text pip show rti.connext.activated Or: .. code-block:: text pip show rti.connext To update ``rti.connext.activated``, run: .. code-block:: text pip install --upgrade rti.connext.activated -f /resource/python_api To update ``rti.connext``, run: .. code-block:: text pip install --upgrade rti.connext Updating your source code ------------------------- In some cases, minor modifications to your application code might be required; any such changes are noted in this Migration Guide. After you make modifications to your application code, recompile (except for Python) according to the instructions above.