CMake config files for OGRE (or: how to correctly find OGRE)

[milliams]

I notice that we currently install a number of build-related cmake file into the <prefix>/lib/OGRE/cmake/ directory. These files should not be installed as they are (with 2 exceptions) only useful for the building of CMake itself.

The exceptions are FindOIS.cmake which I guess is used for finding OIS for the samples but which could also be useful for other projects and FindOGRE.cmake which is a strange (and recommended against by CMake devs) thing to install alongside OGRE given that if one can find that file at all then you already know OGRE is installed.

The correct course of action here would be to make those two files available as part of the 'SDK' but not install them alongside the libraries. These could be available in the documentation folder, on the website, just in the current location in the source distribution or even better, passed upstream to CMake so that everyone can benefit.

You may think that this just makes it harder for cmake-based projects to find OGRE if they have to go off trying to find where FindOGRE.cmake is and include it in their projects but let me explain how dependency finding is supposed to work in CMake...

Let's say I have a game which uses CMake to build it and has OGRE as a dependency. At build time I need to be able to find OGRE. There are two possible scenarios:

• If OGRE was not a CMake-based project then I would have to write (or download from a 3rd party) a FindOGRE.cmake file which contains logic for finding where OGRE is installed to on the system. Then calling FIND_PROJECT(OGRE) within my build system would run the file and find OGRE for me. This file would exist purely within the build system and would not be installed.
• The second scenario (which is our case) is when OGRE is a CMake-based project. In this case, OGRE is supposed to write a small CMake description file (called OGREConfig.cmake) which set variables for use in a dependee's build-system and install this file to a standard location (usually <prefix>/share/cmake/OGREConfig.cmake on Linux) in much the same way that pkg-config works. Then, when I run FIND_PROJECT(OGRE) it will automatically go looking for OGREConfig.cmake (if it can't find it, I can always give it hints e.g. for non-standard install locations) and use that to tell me where OGRE is. You can still do version checking and the like using this system.

I'd like to suggest that we both stop installing the CMake build-system stuff to the lib directory as well as starting to provide OGREConfig.cmake and OGREConfigVersion.cmake files for 3rd party project to be able to easily find OGRE. I am happy to help with this if needed as I already significantly contributed to the prototype of our CMake build system.

There is documentation for all this on the CMake wiki and in the find_package() documentation.

[CABAListic]

I never intended that the FindOGRE script be directly usable to "automagically" find Ogre. It is provided for projects using Ogre to copy to their own CMake files to use and find Ogre and is also used by the samples sources to build against precompiled Ogre SDKs. The latter is the primary reason why it is installed. We can argue about the directory to which to install, it is more or less arbitrary to me.

I personally think that the FindOGRE script is vastly superiour to the OGREConfig approach mainly due to the following arguments:
1) It works reliably (or should) for any Ogre version from 1.6 upwards and perhaps even below that.
2) It works reliably for cross-platform builds, which is something that imho the Config approach does not. This is mostly due to the fact that there is no such thing as a reliable default path on Windows to search for such files. Personally I think setting the OGRE_HOME variable for our FindOGRE script is less obscure than setting CMAKE_PREFIX_PATH, but this is just my preference of course.

Also, when I decided for the FindOGRE script I had some concerns about the structure of the Config file because it seems to me that you can either supply only the name of the libraries and a library include path (which, however, CMake actually discourages) or you need to derive full paths for each library which seemed very cumbersome to do. All in all it seemed like an unnecessary replication of effort with the FindOGRE script.

If you really think OGREConfig is a must, please, by all means, your help will be appreciated It should, however, be able to list all the plugins and components available much like the find script already does.

[CABAListic]

To clarify my concerns about platform interoperability, consider the OGREConfig template which still resides in CMake/Templates/OGREConfig.cmake.in (I think this is more or less the version you originally contributed).
It sets OGRE_PREFIX_DIR to CMAKE_INSTALL_PREFIX. While this will work on Linux/Unix, it is not acceptable for Windows where the install location is not necessarily the location which is used later. The installed SDK can and will be moved around, this is already guaranteed by our precompiled SDKs which we offer, since they can be installed to anywhere on your computer. Therefore, using an absolute path which was fixed during the INSTALL step is not an option for Windows.
We could, of course, only use OGREConfig on non-Windows platforms, but that would mean we need the FindOGRE script anyway, so what would we have gained?

[jacmoe]

Yes, but that does not mean that we shouldn't say yes to a more 'proper' findOGRE script?

[CABAListic]

This isn't about the FindOGRE script or improvements to it, this is about an entirely different route to finding Ogre.

[jacmoe]

Right, but for finding Ogre in our own projects, I'd like to use Milliams script since it seems to be more standard.
I wasn't aware that it was actually used by Ogre itself.

[sinbad]

I use FindOGRE.cmake for my projects - I used it in both MeshMagick and OgreSpeedTree. It works fine against 1.6 and 1.7, on Windows anyway. Might need more work elsewhere, I certainly updated it so that it would work for my purposes for external projects.

I define, for referencing OGRE source builds:

• OGRE_SOURCE pointing at the OGRE source root
• OGRE_BUILD pointing at the root of the CMake-generated build for 1.7, or the source root for 1.6

and for referencing the OGRE SDK I just define OGRE_SDK instead (works for both 1.6 and 1.7).

So as far as I'm concerned this works fine already, I use it in production deployments. I fail to see why we need a separate route to finding OGRE, more variants is just more things to break / remember to test.

Linux may well be a PITA though, I usually find it is I also find its assertion that every library should install in one central location to be hopelessly naive and only works when you have extremely standardised, usually old libraries, that you only build one way and only use stable versions. In practice when I'm developing I always have some libraries where I want to use different build configurations per project, potentially with modifications, and therefore I want to reference them explicitly from a local source, not install them centrally. Since I always work with bleeding edge versions of OGRE, installing it centrally is pretty much never what I want. So IMO concentrating on referencing standardised central versions just isn't that practical in many cases. Talking to some commercial developers who deploy on Linux, they generally seem to prefer to reference local libraries in the main too barring the simplistic stuff, since it's far less of a headache to support across distributions & versions.

[jacmoe]

I use FindOGRE.cmake for my projects - I used it in both MeshMagick and OgreSpeedTree. It works fine against 1.6 and 1.7, on Windows anyway. Might need more work elsewhere, I certainly updated it so that it would work for my purposes for external projects.

Well, yeah. It works great for Ogitor as well, though I'd not call that production quality (yet).

So as far as I'm concerned this works fine already, I use it in production deployments. I fail to see why we need a separate route to finding OGRE, more variants is just more things to break / remember to test.

The only reason why I'd like to see what Milliams proposes is that he's a KDE developer.
Without KDE, CMake would have been far less known, if at all.

The FindOGRE script is a good starting point, so thanks for that.

[CABAListic]

What he proposes is fairly simple. CMake has a two-fold system when searching for dependency packages. One component is the find scripts which we use to find Ogre's dependencies and where we also provide our FindOGRE script. The other part of the find_package system, however, uses a mechanism comparable to what pkg-config does: Libraries / modules which use CMake as their build system (like Ogre) can place a description file of themselves in a standard location (or a location later set in CMAKE_PREFIX_PATH), and if any other CMake build system tries to find Ogre via find_package(OGRE), then this description file is found and used directly to get all necessary information about how to link to Ogre, without you needing any FindOGRE script whatsoever.
Yes, in theory this solution is superior because that description file has absolute knowledge about the Ogre installation whereas the find script needs to check which libraries are available, what build settings were chosen etc.. However, as I said I do see practical issues with it particularly on Windows where the install location of the Ogre library is not a fixed absolute path. That and it doesn't work with older Ogre versions because they do not and will never provide such a file.

[milliams]

I'll respond in more detail later but I want to clear up a few points about how it works:

1. If you install OGRE to a standard, centralised location then the OGREConfig.cmake goes along with it to the standard, centralised location (e.g. /usr/share/cmake/OGREConfig.cmake). However, if you want to install a certain version of OGRE to C:\someweirdfolder\ogre\ then OGREConfig.cmake will be installed alongside it (e.g. C:\someweirdfolder\ogre\OGREConfig.cmake). You have one OGREConfig.cmake per install. To make your project find this version of ogre, you can still set it up to use a specific version with use of a environment variable or CMake argument (e.g. pass OGRE_HOME to the PATHS argument of find_package()).
2. The OGREConfig.cmake can have a bit of code like

   Code: Select all

   get_filename_component(SELF_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)

   so that whenever anyone uses it to get OGRE, they get it's current location. This removes the hard-coding of the install location (from CMAKE_INSTALL_PREFIX) to allow for fully relocatable installations.
3. With multiple HINTS or PATHS passed to find_package() I believe that it will even scan through all of them until it finds a suitable version of OGRE.
4. It is however true that this will not work with old versions of OGRE since they will not have an installed OGREConfig.cmake file.

I'm not suggesting that we get rid of everything we have in FindOGRE.cmake, it's a perfectly valid way of doing it. It just seems a little back-to-front to me and I want to clear up any misconceptions about the FooConfig.cmake way of doing things. I've used it with multiple installs in different filesystem locations in LInux and for finding stuff on Windows in my project and it's always worked smoothly.

[altren]

I define, for referencing OGRE source builds:

• OGRE_SOURCE pointing at the OGRE source root
• OGRE_BUILD pointing at the root of the CMake-generated build for 1.7, or the source root for 1.6

I defined this two vars and I'm using FingOGRE.cmake that comes with Ogre and it works fine until OGRE use threads.
Here's what I'm trying to do:

Code: Select all

	if(WIN32 OR APPLE)
		set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${OGRE_SOURCE}/CMake ${OGRE_SOURCE}/CMake/Packages)
	else()
		set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} /usr/local/lib/OGRE/cmake)
	endif()
	
	FIND_PACKAGE(OGRE)

The problem is that Ogre require boost/poco/tbb headers and CMake scripts in my project never know about it since they use only FingOGRE.cmake .
So what should I do for finding Ogre dependencies properly?

I believe that FingOGRE.cmake should include Ogre deps includes. Or if it is possible - move boost to implementation so if I have compiled Ogre it won't be necessary having boost includes in my project.

[CABAListic]

In case of static Ogre builds the FindOGRE script already looks for the dependencies. That it doesn't for non-static builds is an oversight, sorry.