From c4117d911685d57b505876f2443cc96fb135ca98 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Mar 2022 11:15:53 -0500 Subject: ExternalProject: Document that LIST_SEPARATOR works for CMAKE_ARGS too Since `CMAKE_ARGS` is used to construct the default `CONFIGURE_COMMAND` for CMake-based external projects, the `LIST_SEPARATOR` option works for it too. --- Modules/ExternalProject.cmake | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 14864d5..7f16fdc 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -807,11 +807,11 @@ External Project Definition **Miscellaneous Options:** ``LIST_SEPARATOR `` - For any of the various ``..._COMMAND`` options, replace ``;`` with - ```` 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 (```` would be a single space character - string in this case). + For any of the various ``..._COMMAND`` options, and ``CMAKE_ARGS``, + replace ``;`` with ```` 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 (```` would be a + single space character string in this case). ``COMMAND ...`` Any of the other ``..._COMMAND`` options can have additional commands -- cgit v0.12 From 02cf404ace01ac4ea7a078dca75a817f95c3bdd3 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 11 Mar 2022 11:36:41 -0500 Subject: Help: Add advice for dealing with semicolons in lists Issue: #23315 --- Help/manual/cmake-language.7.rst | 42 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index b7f0861..e7d2694 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -627,3 +627,45 @@ in list elements, thus flattening nested lists: .. code-block:: cmake set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c" + +In general, lists do not support elements containing ``;`` characters. +To avoid problems, consider the following advice: + +* The interfaces of many CMake commands, variables, and properties accept + semicolon-separated lists. Avoid passing lists with elements containing + semicolons to these interfaces unless they document either direct support + or some way to escape or encode semicolons. + +* When constructing a list, substitute an otherwise-unused placeholder + for ``;`` in elements when. Then substitute ``;`` for the placeholder + when processing list elements. + For example, the following code uses ``|`` in place of ``;`` characters: + + .. code-block:: cmake + + set(mylist a "b|c") + foreach(entry IN LISTS mylist) + string(REPLACE "|" ";" entry "${entry}") + # use "${entry}" normally + endforeach() + + The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an + example of an interface built using this approach. + +* In lists of :manual:`generator expressions `, + use the :genex:`$` generator expression. + +* In command calls, use `Quoted Argument`_ syntax whenever possible. + The called command will receive the content of the argument with + semicolons preserved. An `Unquoted Argument`_ will be split on + semicolons. + +* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``, + which do not distinguish semicolons in values from those separating values. + Instead, prefer using named positional arguments and the ``ARGC`` and + ``ARGV#`` variables. + When using :command:`cmake_parse_arguments` to parse arguments, prefer + its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables. + + Note that this approach does not apply to :command:`macro` implementations + because they reference arguments using placeholders, not real variables. -- cgit v0.12 From 8abd714176a8b5fd76f7660a144f4cc88d7746e0 Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 15 Mar 2022 13:59:54 -0400 Subject: Help: Clarify that ENVIRONMENT test properties take ;-separated lists Follow up commit 79f64cc773 (Help: ENVIRONMENT_MODIFICATION clarify only supports singular values, 2022-02-23) to specifically call out the list format. Issue: #23315 --- Help/prop_test/ENVIRONMENT.rst | 8 ++++---- Help/prop_test/ENVIRONMENT_MODIFICATION.rst | 9 +++++---- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/Help/prop_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 43bcdbe..07b96bb 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -3,7 +3,7 @@ ENVIRONMENT Specify environment variables that should be defined for running a test. -If set to a list of environment variables and values of the form -``MYVAR=value`` those environment variables will be defined while running -the test. The environment changes from this property do not affect other -tests. +Set to a :ref:`semicolon-separated list ` list +of environment variables and values of the form ``MYVAR=value``. +Those environment variables will be defined while running the test. +The environment changes from this property do not affect other tests. diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst index 1e17329..a80651a 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -7,10 +7,11 @@ Specify environment variables that should be modified for running a test. Note that the operations performed by this property are performed after the :prop_test:`ENVIRONMENT` property is already applied. -If set to a list of environment variables and values of the form -``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an -environment variable to be modified. Entries are considered in the -order specified in the property's value. The ``OP`` may be one of: +Set to a :ref:`semicolon-separated list ` of +environment variables and values of the form ``MYVAR=OP:VALUE``, +where ``MYVAR`` is the case-sensitive name of an environment variable +to be modified. Entries are considered in the order specified in the +property's value. The ``OP`` may be one of: - ``reset``: Reset to the unmodified value, ignoring all modifications to ``MYVAR`` prior to this entry. Note that this will reset the variable to -- cgit v0.12