From 611ffce98c731be0b86b25a2ff415190810546a0 Mon Sep 17 00:00:00 2001
From: Ben Boeckel <ben.boeckel@kitware.com>
Date: Wed, 27 Mar 2024 06:43:15 -0400
Subject: ExternalProject: add an example of `LIST_SEPARATOR` usage
---
Modules/ExternalProject.cmake | 13 ++++++++++++-
1 file changed, 12 insertions(+), 1 deletion(-)
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 8b10135..89bee52 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -909,7 +909,18 @@ Miscellaneous Options
replace ``;`` with ``<sep>`` in the specified command lines.
This can be useful where list variables may be given in commands where
they should end up as space-separated arguments (``<sep>`` would be a
- single space character string in this case).
+ single space character string in this case). Note that the separator should
+ be chosen to avoid being confused for non-list-separator usages of the
+ sequence. For example, using ``LIST_SEPARATOR`` allows for passing list
+ values to CMake cache variables on the command line:
+
+ .. code-block:: cmake
+
+ ExternalProject_Add(example
+ ... # Download options, etc.
+ LIST_SEPARATOR ","
+ CMAKE_ARGS "-DCMAKE_PREFIX_PATH:STRING=${first_prefix},${second_prefix}"
+ )
``COMMAND <cmd>...``
Any of the other ``..._COMMAND`` options can have additional commands
--
cgit v0.12
From 5d33f41e239563cc2f75b6fef1129e78a2613067 Mon Sep 17 00:00:00 2001
From: Ben Boeckel <ben.boeckel@kitware.com>
Date: Wed, 27 Mar 2024 06:59:44 -0400
Subject: ExternalProject: reword `LIST_SEPARATOR` to indicate what it *does*
Also remove the (IMO) confusing suggestion to have ` ` as a separator as
it interferes with things like spaces in argument values (e.g., paths)
or generated arguments such as `-GUnix Makefiles`. The new example is
likely more common usage of the facility.
---
Modules/ExternalProject.cmake | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 89bee52..965b25c 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -906,13 +906,13 @@ Miscellaneous Options
``LIST_SEPARATOR <sep>``
For any of the various ``..._COMMAND`` options, and ``CMAKE_ARGS``,
- replace ``;`` with ``<sep>`` in the specified command lines.
- This can be useful where list variables may be given in commands where
- they should end up as space-separated arguments (``<sep>`` would be a
- single space character string in this case). Note that the separator should
- be chosen to avoid being confused for non-list-separator usages of the
- sequence. For example, using ``LIST_SEPARATOR`` allows for passing list
- values to CMake cache variables on the command line:
+ ``ExternalProject`` will replace ``<sep>`` with ``;`` in the specified
+ command lines. This can be used to ensure a command has a literal ``;`` in it
+ where direct usage would otherwise be interpreted as argument separators to
+ CMake APIs instead. Note that the separator should be chosen to avoid being
+ confused for non-list-separator usages of the sequence. For example, using
+ ``LIST_SEPARATOR`` allows for passing list values to CMake cache variables on
+ the command line:
.. code-block:: cmake
--
cgit v0.12