I'm creating a library (called fmi2) which I intend to install on my local machine (via a package manager) and then link to with a bunch of other libraries.
I'll be providing a Findfmi2.cmake file so that I can call find_package(fmi2) from my other libraries, but where should this file be conventionally installed?
Here are some choices I've considered and their problems:
/usr/share/cmake-3.8/Modules/Findfmi2.cmake
Advantage: find_package(fmi2) will just work
Disadvantage: Only works for one version of cmake
/usr/share/cmake/Modules/Findfmi2.cmake
Advantage: Should work for any version of cmake
Disadvantage: This is not a default folder. We would need to add set(CMAKE_MODULES_PATH /usr/share/cmake/Modules) and this kills any portability.
${CMAKE_CURRENT_SOURCE_DIR}/cmake/Findfmi2.cmake
Advantage: Portable, just need to add set(CMAKE_MODULES_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
Disadvantage: Not system-wide. Need to manually add this file to each library that uses it. This duplicates files in my framework.
You are authoring content in CMake. You don't need a FindModule. That is designed to find external non-CMake outputs.
This Stackoverflow post from ruslo should help you understand the difference between find_package() module mode and config mode. It also answers your question about paths for FindModules, i.e. they are copied into your CMake project, not discovered system-wide, unless they are part of the official FindModules bundled with CMake in the "Modules" directory.
Modern CMake documentation now finally contains good examples to create a config mode package: cmake-packages
If you want explicit full examples, though using slightly older syntax for the config.cmake files, ruslo has more on Github.
Related
I am learning CMake, and I feel hard to understand when I should use find_package.
For separate compilation, we need to let the compiler knows where to find the header file, and this could be done by target_include_directories. For linking, we need to let the linker knows where the implementation is, and this could be done by target_link_libraries. It seems like that is all we need to do to compile a project. Could anyone explain why and when we should use find_package?
If a package you intend allows for the use of find_package, you should use it. If a package comes with a working configuration script, it'll encourage you to use the library the way it's intended to be used likely come with a simple way to add include directories and dependencies required.
When is it possible to use find_package?
There needs to be either a configuration script (<PackageName>Config.cmake or packagename-config.cmake) that gets installed with the package or find script (Find<PackageName>.cmake). The latter one in some cases even comes with the cmake installation instead of the package installed, see CMake find modules.
Should you create missing scripts yourself?
There are several benefits in creating a package configuration script yourself, even if a package doesn't come with a existing configuration or find script:
The scripts separate the information about libraries from the logic used to create your own target. The use of the 2 commands find_package and target_link_libraries is concise and any logic you may need to collect and apply information like dependencies, include directories, minimal versions of the C++ standard to use, ect. would probably take up much more space in your CMakeLists.txt files thus making it harder to understand.
If makes library used easy to replace. Basically all it takes to go with a different version of the same package would be to modify CMAKE_PREFIX_PATH, CMAKE_MODULE_PATH or package-specific <PackageName>_ROOT variables. If you ever want to try out different versions of the same library, this is incredibly useful.
The logic is reuseable. If you need to use the same functionality in a different project, it takes little effort to reuse the same logic. Even if a library is only used within a single project, but in multiple places, the use of find_package can help keeping the logic for "importing" a lib close to its use (see also the first bullet point).
There can be multiple versions of the same library with automatic selection of applicable ones. Note that this requires the use of a version file, but this file allows you to specify, if a version of the package is suitable for the current project. This allows for the checking the target architecture, ect. This is helpful when cross compiling or when providing both 32 and 64 bit versions of a library on Windows: If a version file indicates a mismatch the search for a suitable version simply continues with different paths instead of failing fatally when considering the first mismatch.
You will probably find CMake's guide on using dependencies helpful. It describes find_package and alternatives, and when each one is relevant / useful. Here's an excerpt from the section on find_package (italics added):
A package needed by the project may already be built and available at some location on the user's system. That package might have also been built by CMake, or it could have used a different build system entirely. It might even just be a collection of files that didn't need to be built at all. CMake provides the find_package() command for these scenarios. It searches well-known locations, along with additional hints and paths provided by the project or user. It also supports package components and packages being optional. Result variables are provided to allow the project to customize its own behavior according to whether the package or specific components were found.
find_package requires that the package provide CMake support in the form of specific files that describe the package's contents to CMake. Some library authors provide this support (the most desirable scenario for you, the package consumer), some don't but are prominent enough that CMake itself comes with such files for those packages, or in the worst case, there is no CMake support at all, in which case you can either do something to get the either of the previous good outcomes, or perform some kludges to get the job done (ie. define the targets yourself in your project's CMake config).
I am creating a cmake package config file (a Foo-config.cmake) for a pre-existing .dll not created by cmake.
The annoying thing is that the .dll depends on some data files.
When a user consumes my package in his own cmake project, I want the INSTALL target to install both the .dll and data files to his specified install location. I don't want him to have to write extra install() rules to do that.
Is it good practice to write the install() rules directly in my Foo-config.cmake? Or is there a better way to do this, maybe with set_target_properties()? I just couldn't find the appropriate property for associating arbitrary file dependencies to a target.
In an alternate universe where this .dll didn't already exist and I had to create it myself using cmake, would I need to create a custom Foo-config.cmake, or is there something in cmake that can automatically generate it for me to achieve the same thing?
FWIW the .dll is an internal legacy library and is normally built by Visual Studio and uploaded in a .zip file to our internal artifactory. I want us to migrate away from manually pulling down .zip files from artifactory and manually integrating the files into Visual Studio projects.
I've since found that there are a couple different ways to do this:
In the config file, simply create one or more variables for the files/dirs you want to install. Then install those using install(FILES) and/or install(DIRECTORY). More info: https://stackoverflow.com/a/46361538/189341
Use file(GET_RUNTIME_DEPENDENCIES). More info:
https://discourse.cmake.org/t/installing-a-pre-built-module-and-its-various-dependencies/5227
How to use cmake file( GET_RUNTIME_DEPENDENCIES in an install statement?
Is it good practice to write the install() rules directly in my Foo-config.cmake?
No.
From 480 *-config.cmake and *Config.cmake files on my system none calls install().
Or is there a better way to do this, maybe with set_target_properties()?
No.
In an alternate universe where this .dll didn't already exist and I had to create it myself using cmake, would I need to create a custom Foo-config.cmake
No. This is unrelated to if you create a .dll or not. If .dll exists, there is no need to create Foo-config.cmake anyway. It is your choice that you want to (or make users to) use find_package.
is there something in cmake that can automatically generate it for me
No.
If you don't intent to support find_package features - VERSION OPTIONAL_COMPONENTS PATHS HINTS CONFIGS etc. - then just go with include(). find_package is just include() with some extra options.
If you want to have install() in your find_package, then just protect it with a variable, like if (FOO_DO_INSTALL) install(....) endif().
I'm currently having this issue with the Google Protobuf Library, but it is a recurring problem and will likely occur with many if not all 3rd-party packages that I want to build and install from source.
I'm developing for Windows, and we need to be able to generate both 32-bit and 64-bit versions of our DLLs. It was relatively straightforward to get CMake to install our own modules to architecture-specific subdirectories, e.g. D:\libraries\bin\i686 and d:\libraries\lib\i686 (and sim. for bin). But I'm having trouble achieving the same thing with 3rd-party libraries such as Protobuf.
I could, of course, use distinct CMAKE_INSTALL_PREFIX and CMAKE_PREFIX_PATH combinations (e.g. D:\libraries-i686 and D:\libraries-x86_64, and will probably end up doing just that, but it bothers me that there doesn't seem to be a better alternative. The docs for find_package() clearly show that the search procedure does attempt architecture-specific search paths, so why do the CMake files of popular libraries not generally seem to support installing to architecture-specific subdirectories?
Or could it be that it is just a matter of setting the right CMAKE_XXX variable?
Thanks to #arrowd for pointing me in the right direction, I now have my answer, though it is not exactly what I had hoped for.
CMAKE_LIBRARY_OUTPUT_DIRECTORY and CMAKE_RUNTIME_OUTPUT_DIRECTORY, however, specify the build output directories, not the install directories. As it turns out though, there are variables for the install directories too, called CMAKE_INSTALL_BINDIR and CMAKE_INSTALL_LIBDIR - they are actually plainly visible (along with plenty more) in the cmake-gui interface when "Advanced" is checked.
I tried setting those two manually (to bin\i686 and lib\i686), and it works: the Protobuf INSTALL target copies the files where I wanted to have them, i.e. where the CMake script of my consumer project will find them in an architecture-safe manner.
I'm not sure how I feel about this - I would have preferred something like a CMAKE_INSTALL_ARCHITECTURE or CMAKE_ARCHITECTURE_SUBDIR variable that CMake would automatically append to relevant install paths. The solution above requires overriding defaults that I would prefer to leave untouched.
Under the circumstances, my fallback approach might still be the better option. That approach however requires that the choice of architecture be made very early on, typically when running the script that initializes the CMake-specific environment variables that will be passed to cmake when configuring build directories. And it's worse when using cmake-gui, which requires the user to set all directories manually.
In the end, I'm still undecided.
I have converted my project to use cmake. During development I'd like to be able to install the product not the normal way, but let (notably) the installed data files be symbolic links to the source tree.
The project is SWI-Prolog which provides functionality to directly navigate and edit source files. If I use this to extend and fix the system libraries however I'm editing the installed copy that I then need to copy back to the sources before I can commit.
I know I can override functions in cmake, but in this case we are dealing with cmake code that is generated.
So looking through the newest release of GLM 0.9.7, I dont see a FindGLM.cmake file anywhere, used to easily include GLM in CMAKE. I could always use an old version of it found online but the following commit had me stumped:
https://github.com/g-truc/glm/commit/62a7daddcf082f754000fc5e42d7bcdf93c895f7
Commit message is "Removed obsolete FindGLM". So, did the developer just dump it or are there in fact a new way to find libraries in CMAKE?
Yes, CMake Find modules (FindXyz.cmake files) are deprecated in favour of Package Config files (usually named XyzConfig.cmake). The original philosophy is that Find modules are shipped and maintained by CMake, while Package Config files are shipped and maintained by the package they are intended to find.
CMake's find_package command actually has two modes: Module mode (legacy, using Find modules) and Config mode (preferred, using Package Config files).
For the client consuming the package, little should change (unless more customisation is desired, which is offered by the Config mode of find_package).
Notice that the very commit to which you linked not only drops FindGLM.cmake, but also adds a glmConfig.cmake file.