From d1de82a85a1667940298adf7d8a1fc5002dc0dce Mon Sep 17 00:00:00 2001 From: Ryan Friedman Date: Thu, 22 Feb 2024 18:34:58 -0700 Subject: [PATCH] Add design docs for versioning export Signed-off-by: Ryan Friedman --- ament_cmake_core/doc/versioning.md | 19 ++++++++++++++++++ .../doc/dependency_versioning_export.md | 20 +++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 ament_cmake_core/doc/versioning.md create mode 100644 ament_cmake_export_dependencies/doc/dependency_versioning_export.md diff --git a/ament_cmake_core/doc/versioning.md b/ament_cmake_core/doc/versioning.md new file mode 100644 index 00000000..cd54e8d4 --- /dev/null +++ b/ament_cmake_core/doc/versioning.md @@ -0,0 +1,19 @@ +## Express Version Compatibility in the Installation + +Add a COMPATIBILITY argument to `ament_package`. Default to AnyNewerVersion if not supplied which matches current behavior. + +User call in `foo's` `CMakeLists.txt`: +```cmake +ament_package(COMPATIBILITY SameMajorVersion) +``` + +The compatibility would be forwarded to `write_basic_package_version_file`. + +Then, you can use it in `bar` +```cmake +find_package(foo_core 4 CONFIG REQUIRED) +``` + +If you forgot to update `foo_core` from 3 to 4 and rebuild your workspace, then colcon +will fail at the configure stage of `bar` with a nice error message. + diff --git a/ament_cmake_export_dependencies/doc/dependency_versioning_export.md b/ament_cmake_export_dependencies/doc/dependency_versioning_export.md new file mode 100644 index 00000000..f376bf57 --- /dev/null +++ b/ament_cmake_export_dependencies/doc/dependency_versioning_export.md @@ -0,0 +1,20 @@ +# Express Version Compatibility in Dependencies + +`ament_export_dependencies` shall propagate the version requested of dependencies to a call to `find_dependency `. + +For example: +`find_package(foo_core CONFIG 4)` results in +`add_dependency(foo_core CONFIG 4)`. + +`find_package(foo_core CONFIG 4.8.3-dev2)` results in +`add_dependency(foo_core CONFIG 4.8.3-dev2)`. + +`find_package(foo_core MODULE)` results in +`add_dependency(foo_core MODULE)`. + +I think this can be done automatically with the use of `foo_core_FIND_VERSION`. + +Adding in the find method of MODULE/CONFIG may be out of scope for this discussion. + +I want to avoid a user manually maintaining versions in multiple places. +It's hard enough as it is to remember when you add a find_package call to also add it to `ament_export_dependencies`.