Cookbook for CMake installation packages
I'm not sure if the CMake devs would agree with me, but I found it a huge struggle to understand not only how to build install packages with CMake, but it's nearly impossible to find best practices. The cmake-packages page combined with the find_package()
documentation page serve as good technical documentation for various ways of doing things, but CMake really lacks a "cookbook" for installation packages.
I think such a cookbook should focus on:
- The most modern & recommended way of building install packages (via configuration packages)
- Best practices, such as:
- Keeping things as platform-independent as possible (things like GNUInstallDirs, assuming that's still relevant)
- Facilitating side-by-side installations of packages
- How to version includes, library files (has to be more than
VERSION
andSOVERSION
!), and CMake scripts (target imports, config scripts)
- How to version includes, library files (has to be more than
- Lots and lots (and lots!!!) of examples, continuously updated to work with the latest version of CMake as features progress
The good news is that I'd love to do this for you. However, I need to pick the brains of @brad.king and others that have intricate knowledge of the inner workings of these features, and many things are still undocumented. The most difficult information to obtain is that which we would consider idiomatic to CMake. This mainly involves getting Kitware to sign-off on specific ways of doing things, especially when more than one solution exists. A cookbook needs to serve as a definitive and authoritative guide for users to learn Kitware's best way of doing things, and help guide the CMake community to do things consistently which will benefit everyone.
As I observe things today, config packages had the lofty goal and intention to replace module packages. However, config packages still aren't quite there. Too many people are doing them wrong or differently. I feel like most of that can be solved with a cookbook, some may require further refinements to CMake in the future (but the cookbook will be the go-to source to keep updated with this evolution).
In this issue, I'd like to go over a few things initially:
- Is this a good idea?
- What is the best format for this cookbook? Another page similar to cmake-packages? Should this supplement or replace cmake-packages page? Completely separate page outside of the CMake docs?
- Discuss general approach, target audience, what Kitware would expect from this, document structure (i.e. topics or chapters)
And assuming we get past that, I'll start the brain-picking exercises. I'll dig into CMake code to learn as much as I can, but I'll ultimately need the developers to share their thoughts on what best practices will be. For example, for side-by-side installations of different versions of the same package, it isn't immediately obvious how this should be done. And the way it should be done should work across many platforms which fundamentally represent installations differently (namely Windows vs Linux). Like, how do you version the installed includes
directory in a way that is acceptable across platforms? And furthermore, do we structure/install things based on CMake being the only thing to ever use these installations?