I’ve read the definitions in cmake-variables, but I’m still puzzled by the relationship between CMAKE_STAGING_PREFIX and CMAKE_INSTALL_PREFIX.
Some simple experiments seem to indicate that the perform the same function, and if STAGING is set, then it overrides INSTALL. [My test didn’t include any RPATH/RUNPATH entries, so the comment in the description of STAGING_PREFIX in the manual about replacing it with INSTALL_PREFIX didn’t come into play in my tests.]
The description also seems to say that STAGING is only used for cross-compiling, but it appears it overrides INSTALL for bin/lib/include even when CMAKE_CROSSCOMPILING == FALSE.
Hence I’m a little confused.
Should I never set both in the same CMAKE configuration?
Is it expected that if STAGING is the empty string (as opposed to missing) it overrides INSTALL, basically removing the prefix.
The difference is subtle, but important. In general, you want to be setting CMAKE_INSTALL_PREFIX and it would make sense for the project to provide a value for that (but still overridable by the user if they wanted to). If you were producing a package and installing that package on a different machine, it is this path that would be used to create the package contents. This is also the path that affects the embedded RPATH on installed binaries.
The CMAKE_STAGING_PREFIX should not generally be set by the project, it is meant for the developer. In cross-compilation scenarios, the developer might mount the file system of the target machine on their host’s file system. They might want to install directly into that mounted file system. On the host, the path to the install base point might be /mnt/raspi/opt/mything, whereas on the target machine, that same path would be under /opt/mything. In this example, you would set CMAKE_INSTALL_PREFIX to /opt/mything and CMAKE_STAGING_PREFIX to /mnt/raspi/opt/mything.
I would have thought if CMAKE_STAGING_PREFIX was set but empty, it would be ignored, but I can’t confirm if that is the actual behavior. It might be that just having it set at all makes it override CMAKE_INSTALL_PREFIX when doing an install.