[ExternalProject] Documentation: Authoritative example on incorporating transitive ExternalProject's?
Per discussion in this PR:
I was reviewing code in our example repository, drake-shambhala
(shows example of consuming our main project, Drake), and, as a non CMake-expert, it took me a while to understand the ExternalProject
structure that was needed to enable building this example project: drake_cmake_external
I made a brief statement of what I understood:
# This is the superproject for `drake_shambhala`. We call
# `ExternalProject_Add` here, and add `drake_shambhala` afterwards (also as a
# external project) which depends on these external projects, so that it can
# effectively build the external projects during the configuration stage.
(In writing this, I realized I should have stressed that it's needed for the CMake bits that are generated from the upstream project, drake
.)
However, Jamie Snape recommended that we should try to avoid re-creating documentation on every usage of an idiom.
When I was searching around for examples of ExternalProject
, specifically when the project needed to generate / download CMake configuration files (in this case from bazel
, but in other cases from transitive ExternalProject
calls, I'd assume), I could not really find anything that seemed distilled / authoritative.
Is there a good source for this sort of example? If so, is there a way to incorporate this into the main documentation, say in the ExternalProject/Examples section?