From 17427c9184159ac993b75bfd86f01813ce1d0159 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Tue, 21 Oct 2025 12:04:50 -0400 Subject: [PATCH] [doc] Add instructions to upgrade DEE CMake externals --- tools/workspace/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/tools/workspace/README.md b/tools/workspace/README.md index d4fe7b79848e..ad6efafdcec5 100644 --- a/tools/workspace/README.md +++ b/tools/workspace/README.md @@ -185,6 +185,28 @@ If an external required non-trivial changes, even if you were able to make the changes yourself, consider separating that external into its own pull request and assigning it to the associated feature owner. +## drake-external-examples + +The +[drake_cmake_external](https://github.com/RobotLocomotion/drake-external-examples/tree/main/drake_cmake_external) +example demonstrates the use of some of Drake's CMake options for user-provided +external packages as part of the public API. While users may be able to provide +their own versions which don't necessarily match those officially supported by +Drake, the official examples should match and be kept up-to-date as part of the +monthly upgrades process. + +The packages with their canonical versions are listed in Drake's `MODULE.bazel`, +and the corresponding user-provided versions in drake-external-examples are +found in the calls to `ExternalProject_Add` in the example's +[CMakeLists.txt](https://github.com/RobotLocomotion/drake-external-examples/blob/main/drake_cmake_external/CMakeLists.txt). +Any time these packages are upgraded in Drake (via the steps above, or separate +from the monthly upgrades), use the +[automated upgrade script](https://github.com/RobotLocomotion/drake-external-examples/blob/main/private/upgrade_cmake_externals.py) +to create a pull request on drake-external-examples with an upgrade to match +Drake. See the script for its usage requirements; you may have to remove the +"bcr..." from the end of the canonical version string in Drake, to match the +upstream directly outside Bazel. + # Changing the version of third-party software manually The instructions for updating third-party software differ depending on how