Variables available to code in install(SCRIPT) and install(CODE)

I was looking into what variables we document as being available to install(SCRIPT) and install(CODE). I was surprised that we don’t seem to document any. I expect that at the very least, we would guarantee that CMAKE_INSTALL_PREFIX would be defined,. We also don’t make any guarantees about the working directory (that I could find). Without CMAKE_INSTALL_PREFIX being documented as available or the working directory guaranteed, you would have no documented way to install anything or access things that have already been installed.

I suspect anyone using these install() subcommands already assumes CMAKE_INSTALL_PREFIX is defined. It seems to be one of the first things defined in the cmake_install.cmake script we generate. Is there any reason we can’t formally document it as always being defined and available? Given that it seems this variable has always been defined and available (from what I can tell, but would be good to confirm), we could add it now (even for 3.22) and not need a versionadded directive.

While we’re at it, $ENV{DESTDIR} should also be documented. Its interactions with ${CMAKE_INSTALL_PREFIX} on Windows is not trivial. I’m sure someone can end up configuring things in a way that such code breaks.

Ouch, yes I had forgotten about that. Looking at a sample cmake_install.cmake, to be robust, yes you would also need to know about $ENV{DESTDIR} and that the full path is expressed as $ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}.

Do we really need to worry about interactions on Windows in CMake’s own docs though? I think even within CMake itself, we just use the above concatenation and it is the user’s responsibility to ensure that makes sense and works. At most, I think we’d just have to say that if you’re on Windows and you set the DESTDIR environment variable, you must ensure that CMAKE_INSTALL_PREFIX does not include a drive letter.

Actually, we already have a warning about this in the docs for the DESTDIR environment variable:

WARNING: DESTDIR may not be used on Windows because installation prefix usually contains a drive letter like in C:/Program Files which cannot be prepended with some other prefix.

Just FYI, Qt’s CI still abuses and sets DESTDIR on Windows and it worked mostly fine over the past 2 years, it just doesn’t prepend the drive letter. e.g. set DESTDIR=/Users/pc/Documents/bla