Proposal: make the project side-by-side installable with Ogre (1.x)

[j-rivero]

Motivation

It would be great to be able to install this software project in a system that already has installed the previous ogre 1.x. Given that both projects are being developed and maintained there are some use cases where someone wants to have both installed to use them in a third party software. This is the case of the library ignition-rendering which has support for both.

We, at Open Robotics, are currently generating a Debian/Ubuntu package that is being installed together with ogre-1.x . To do so we are using -DOGRE_LIB_DIRECTORY to inject lib/$(DEB_HOST_MULTIARCH)/OGRE-$(OGRE_VERSION) and our packaging scripts are moving software pieces into a "versioned" directory (OGRE-2.2) and modifying pkgconfig/cmake to be compatible with this change.

I believe that these changes would be best hosted in the buildsystem of ogre-next so from source installations can also be installed in the same way.

Please note that I’m not proposing the changes needed to have a third party project being able to compile and link against both ogre-1.x and ogre-next at the same time, which would require some very intrusive changes in different levels.

Changes required

Thinking on the changes needed to make the project side-by-side installable with Ogre 1.x:

• Change project name from Ogre to Ogre-Next or Ogre-next. Change project naming to OGRE-Next #234
• OGRE_LIB_DIRECTORY probably needs to add an /ogre-next/ subdirectory by default to avoid conflicting with Ogre 1.x libraries since library names are the same. Alternatively/additionally the libraries could be renamed from libOgre to libOgreNext.
• Headers installed under typically under include/OGRE (many hardcoded paths in the code) would need to be placed in include/OGRE-Next”
• OGRE_MEDIA_PATH from "share/OGRE/Media" to “share/OGRE-Next/Media”
• Change the name of cmake/pkg-config modules to include ogre-next instead of just ogre.

I'm probably missing some pieces here. Just brainstorming a little bit what I was able to found. Please feel free to correct or add the missing parts.

Migration

For third party software using CMake/pkg-config with a system installation

The changes in pkgconfig and CMake modules should probably be enough to hide the modified paths and allow the consumers of the project to keep things working.

Renaming pkgconfig and cmake modules installed could be the biggest problem for migrations in this scenario, since all users should need to modify calls to find the project. We could approach this problem by having a deprecation cycle long enough to give users time to migrate. So when people use: find_package(Ogre) the thing still works but generates a warning asking users to update to `find_package(Ogre-Next).

Other kind of installations

I think that there is a little we can do to fix other build systems (i.e: bazel, manual Makefiles, etc.), they will need to be fixed to the adapt to the new paths.

I have no experience with other kind of installations, but can probably provide advise if needed.

Thanks.

[darksylinc]

In Ogre-Next we're encouraging out-of-source builds over system installation builds due to multiple reasons:

1. Right now include paths aren't always matching 1:1, so when a user needs to move from an SDK to a bleeding edge version they find themselves the SDK include paths no longer match with out of source builds
2. Ogre Next has multiple CMake settings that will break ABI. e.g. OGRE_BUILD_COMPONENT_PLANAR_REFLECTIONS, OGRE_DEBUG_LEVEL_RELEASE, OGRE_CONFIG_THREADS, OGRE_FLEXIBILITY_LEVEL etc. changing one of these means breaking ABI.
3. ABI compatibility isn't even guaranteed between patch versions (ok that's our bad).
4. Right now Ogre and Ogre-Next can only have one version (i.e. multiple versions can't coexist) so if Package A depends on Ogre 2.1 and Package B depends on Ogre 2.2; they can't easily coexist. This is a problem we should address now that we can; but also a reason why we recommend out of source builds

System-level installations are fine if you're e.g. a Debian maintainer and ensure all system packages are built with the same version and same settings. Although that also means lowest common denominator. e.g. if a package needs OGRE_BUILD_COMPONENT_PLANAR_REFLECTIONS then all packages will link against an Ogre version that has this feature and penalize their performance.

That being said, there are cases where it's useful (such as gazebo's), so these changes may be less disruptive than you think:

Change project name from Ogre to Ogre-Next or Ogre-next.

Sounds slightly disruptive, but it would break only a few CMake scripts that are easy to fix

OGRE_LIB_DIRECTORY probably needs to add an /ogre-next/ subdirectory by default to avoid conflicting with Ogre 1.x libraries since library names are the same. Alternatively/additionally the libraries could be renamed from libOgre to libOgreNext.

Changing libOgre* to libOgreNext* is very disruptive. I'd much prefer changing the much more harmless OGRE_LIB_DIRECTORY change

Headers installed under typically under include/OGRE (many hardcoded paths in the code) would need to be placed in include/OGRE-Next”

50/50 disruptive. Depends on the project (i.e. some do #include <Ogre.h> others do #include <OGRE/Ogre.h>). But I don't see a better solution.

Fortunately a little bit of "Search & Replace in files" from multiple IDEs should easily solve this problem.

OGRE_MEDIA_PATH from "share/OGRE/Media" to “share/OGRE-Next/Media”

I don't see this being a problem at all

Change the name of cmake/pkg-config modules to include ogre-next instead of just ogre.

I don't know how disruptive this is.

I'll ask Eugene his thoughts on the topic.

[traversaro]

Clearly identify ogre-next as a different project from ogre v1 would also help now that ogre v1 is now actually released as ogre 13 (see https://www.ogre3d.org/2021/08/14/ogre-13-released), and I guess it would simplify the process of packaging of ogre-next in conda-forge.

[j-rivero]

Thanks Matias for the answer, some comments inline:

In Ogre-Next we're encouraging out-of-source builds over system installation builds due to multiple reasons:
...(snipped)...

Thanks for the details on the stability of Ogre code and the reasons for recommending against binary distribution. I think that they fit well into what has been the software development techniques over the last decades and the pros and cons of the different approaches (even with some approaches in the middle). It is not my intention trying to change the software recommendations but also work on having a binary distribution which is something valuable for some use cases. Hopefully, as you said, we can live with both approaches with some small changes :)

ABI compatibility isn't even guaranteed between patch versions (ok that's our bad).

This is the only point that I'm encouraging to change, getting ABI stability on patch versions would be really valuable.

Change project name from Ogre to Ogre-Next or Ogre-next.

Sounds slightly disruptive, but it would break only a few CMake scripts that are easy to fix

I'm happy that we three are agree that is desired change to be made, I'll send the PR.

OGRE_LIB_DIRECTORY probably needs to add an /ogre-next/ subdirectory by default to avoid conflicting with Ogre 1.x libraries since library names are the same. Alternatively/additionally the libraries could be renamed from libOgre to libOgreNext.

Changing libOgre* to libOgreNext* is very disruptive. I'd much prefer changing the much more harmless OGRE_LIB_DIRECTORY change

Understood.

Headers installed under typically under include/OGRE (many hardcoded paths in the code) would need to be placed in include/OGRE-Next”

50/50 disruptive. Depends on the project (i.e. some do #include <Ogre.h> others do #include <OGRE/Ogre.h>). But I don't see a better solution.

Fortunately a little bit of "Search & Replace in files" from multiple IDEs should easily solve this problem.

Agree, we should be able to handle the change in source code.

OGRE_MEDIA_PATH from "share/OGRE/Media" to “share/OGRE-Next/Media”

I don't see this being a problem at all

Perfect.

Change the name of cmake/pkg-config modules to include ogre-next instead of just ogre.

I don't know how disruptive this is.

For the own project should not be really relevant nor difficult to change hopefully. It goes inline with the rest of the changes proposed. For the rest of the software out there using CMake/pkg-config to find Ogre-Next development libraries and headers they will need to change just the name.

Thanks again Matias, Silvio.

[darksylinc]

This one has been merged manually.

Thanks for your PR!

[j-rivero]

This one has been merged manually.

Thanks for your PR!

Wow, thanks! A good first step. However, if you don't mind @darksylinc , would you mind if we leave this issue open to track the changes needed to complete the proposal?