[CMakeLists] Building with -DPXR_BUILD_DOCUMENTATION=ON without doxygen will lead to a broken installation

[moddyz]

Description of Issue

If -DPXR_BUILD_DOCUMENTATION=ON is applied during cmake configuration, but doxygen is not available, there will be a warning emitted as follows:

CMake Warning at CMakeLists.txt:76 (message):
  Cannot run doc generation, doxygen not found.

The configuring and & generating process will be marked as "done"... however, this results in the pxr_toplevel_epilogue() not being invoked. The binaries will build and install but it will be missing, for example, the critical trampolining plugInfo.json at $USD_INSTALLATION/lib/usd/plugInfo.json.

It would be more helpful to either:

• hard error during cmake configuration if doxygen is not available and documentation is requested.
• with the soft warning, at least make sure pxr_toplevel_epilogue() is still run.

Steps to Reproduce

1. Run a CMake configure with -DPXR_BUILD_DOCUMENTATION=ON without doyxgen available in the environment.
2. There should be a lack of usd_plugInfo.json in the CMake build dir.

System Information (OS, Hardware)

Ubuntu-18.04

Package Versions

usd-20.02

Build Flags

cmake -DCMAKE_INSTALL_PREFIX="/apps/usd/20.02" -DCMAKE_INSTALL_PREFIX="/apps/usd/20.02" -DCMAKE_PREFIX_PATH="/apps/usd/20.02" -DCMAKE_BUILD_TYPE=Debug -DTBB_USE_DEBUG_BUILD=ON -DTBB_INCLUDE_DIRS="/apps/tbb/4.4.6/include" -DTBB_tbb_LIBRARY_DEBUG="/apps/tbb/4.4.6/lib/libtbb_debug.so" -DTBB_tbb_LIBRARY_RELEASE="/apps/tbb/4.4.6/lib/libtbb.so" -DBoost_INCLUDE_DIR="/apps/boost/1.61.0/include" -DBoost_LIBRARY_DIR_DEBUG="/apps/boost/1.61.0/lib" -DBoost_LIBRARY_DIR_RELEASE="/apps/boost/1.61.0/lib" -DGLEW_INCLUDE_DIR="/apps/glew/2.0.0/include" -DGLEW_LIBRARY="/apps/glew/2.0.0/lib64/libGLEW.so" -DOPENSUBDIV_INCLUDE_DIR="/apps/opensubdiv/3.1.1/include" -DOPENSUBDIV_OSDCPU_LIBRARY="/apps/opensubdiv/3.1.1/lib/libosdCPU.so" -DOPENSUBDIV_OSDGPU_LIBRARY="/apps/opensubdiv/3.1.1/lib/libosdGPU.so" -DPXR_ENABLE_PYTHON_SUPPORT=ON -DBUILD_SHARED_LIBS=ON -DPXR_BUILD_DOCUMENTATION=ON -DPXR_BUILD_TESTS=OFF -DPXR_BUILD_IMAGING=ON -DPXR_BUILD_USD_IMAGING=ON -DPXR_BUILD_USDVIEW=ON -DPXR_ENABLE_PTEX_SUPPORT=OFF -DPXR_ENABLE_OPENVDB_SUPPORT=OFF -DPXR_BUILD_EMBREE_PLUGIN=OFF -DPXR_BUILD_PRMAN_PLUGIN=OFF -DPXR_BUILD_OPENIMAGEIO_PLUGIN=OFF -DPXR_BUILD_OPENCOLORIO_PLUGIN=OFF -DPXR_BUILD_ALEMBIC_PLUGIN=OFF -DPXR_BUILD_DRACO_PLUGIN=OFF -DPXR_BUILD_MATERIALX_PLUGIN=OFF -DPXR_BUILD_KATANA_PLUGIN=OFF -DPXR_BUILD_HOUDINI_PLUGIN=OFF /tmp/staging/usd/USD-20.02

[jilliene]

Filed as internal issue #USD-5895