Documentation: Clarify on what items BUILD_RPATH and INSTALL_RPATH are to be used
The following properties:
BUILD_RPATH, BUILD_RPATH_USE_ORIGIN, INSTALL_RPATH, INSTALL_RPATH_USE_LINK_PATH
Concern a dynamic linking thingy called "rpath", important on macOS. Usually when a executable links a dynamic library on macOS it will store both an instruction to load the dynamic library as well as adding a line to the rpath search path list so it is able to find the dynamic library.
All of these properties share a problem in their documentation, which is that it is unclear to me whether they are meant to be set on the library or on the executable. For example, BUILD_RPATH says:
A semicolon-separated list specifying runtime path (RPATH) entries to add to binaries linked in the build tree (for platforms that support it).
This could mean that this is a property you set on the library, and the entries set here are added to binaries linked to that library in the build tree. Or it could mean that this is a property that you set on the executable, and the entries set here are applied directly to the executable (but only the version linked in the build tree). Or I guess it could mean both are supported. To me the most logical thing would be if the property is set on the library (since the rpath is associated with a library in particular, and CMake is already doing bookkeeping to tell which rpaths get associated with which executables; in particular it would be really weird if you can't enable/disable BUILD_RPATH_USE_ORIGIN on a per-library basis) but it's not clear from the doc.
My "expected behavior" is these four docs pages should have a sentence added clarifying this, something like
This property should be set on a library target, and the rpath will be applied to any target that links that library.
I would be happy to create a PR for this but I would need someone to definitively explain to me what the behavior is.