cmake: add support for staged install dirs

[davvid]

Add DESTDIR support to the documentation steps.

Related-to: https://github.com/aousd/build-ig-initiatives/issues/15

[jesschimein]

Filed as internal issue #USD-11756

❗ Please make sure that a signed CLA has been submitted!

(This is an automated message. See here for more information.)

[pmolodo]

@davvid - so for: cmake: add support for staged install dirs PixarAnimationStudios/OpenUSD#3935

...it's not immediately clear how the PR relates to https://github.com/aousd/build-ig-initiatives/issues/15 - ie, making the pxrConfig.cmake portable. Can you elaborate on that?

Also - personally, I'm not a fan of using env vars - they end up creating "secret inputs" that are hard to track down. Could you add a cmake option/variable instead?

EDIT: Ok, I see now that DESTDIR as an env var is something of a standard: https://www.gnu.org/prep/standards/html_node/DESTDIR.html

However, it's only useful if something is setting DESTDIR - and it seems like more of a standard for makefiles. Is setting DESTDIR something that CMake itself generally does? Is there standard tooling used in the default USD build pipeline (or your build pipeline) that sets it? Or is the assumption that the end user sets it themselves before launching a build (as opposed to a tool setting it)?
If it's the latter, than I'm back to preferring a CMake variable.

EDIT 2: Ok, I'm educating myself here - DESTDIR env is explicitly supported by cmake:

https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html#variable:CMAKE_INSTALL_PREFIX

On UNIX one can use the DESTDIR mechanism in order to relocate the whole installation to a staging area. See the DESTDIR environment variable for more information.

[pmolodo]

It seems odd that we add the DESTDIR prefix to the python path here - where it's presumably supposed to find the USD python libs that have already been written out - without a corresponding change to the code for where those libs get written out (or installed). Is there existing CMake machinery that already incorporates DESTDIR when writing/installing the python libs?

[davvid]

Yes, cmake in both Ninja and Makefile mode both honor DESTDIR. This is used heavily by Linux distro packaging (where the install prefix, e.g. /usr) is not writable, so we want to be able to write into a temporary "staging" directory from which the packages are created.

You'll notice that I didn't have to touch other parts -- that's because the rest of the build already supports DESTDIR. It's just these parts that are deficient.

It's also used by packaging systems that are familiar with this standard.