6 files changed, 64 insertions, 16 deletions
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 <cmake-generator-expressions(7)>`,
+  use the :genex:`$<SEMICOLON>` 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.
diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst
index a9b5638..92bd227 100644
--- a/Help/prop_sf/LANGUAGE.rst
+++ b/Help/prop_sf/LANGUAGE.rst
@@ -7,8 +7,8 @@ A property that can be set to indicate what programming language the
 source file is.  If it is not set the language is determined based on
 the file extension.  Typical values are ``CXX`` (i.e.  C++), ``C``,
 ``CSharp``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``.  Setting
-this property for a file means this file will be compiled.  Do not set this
-for headers or files that should not be compiled.
+this property for a file means this file will be compiled, unless
+:prop_sf:`HEADER_FILE_ONLY` is set.
 
 .. versionchanged:: 3.20
   Setting this property causes the source file to be compiled as the
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 <CMake Language Lists>` 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 <CMake Language Lists>` 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
diff --git a/Modules/CMakeFindBinUtils.cmake b/Modules/CMakeFindBinUtils.cmake
index 16d3106..a6bd0d1 100644
--- a/Modules/CMakeFindBinUtils.cmake
+++ b/Modules/CMakeFindBinUtils.cmake
@@ -173,8 +173,13 @@ else()
     else()
       list(PREPEND _CMAKE_LINKER_NAMES "ld.lld")
     endif()
-    if(NOT APPLE)
+    if(APPLE)
       # llvm-ar does not generate a symbol table that the Apple ld64 linker accepts.
+      # FIXME(#23333): We still need to consider 'llvm-ar' as a fallback because
+      # the 'APPLE' definition may be based on the host in this context, and a
+      # cross-compiling toolchain may not have 'ar'.
+      list(APPEND _CMAKE_AR_NAMES "llvm-ar")
+    else()
       list(PREPEND _CMAKE_AR_NAMES "llvm-ar")
     endif()
     list(PREPEND _CMAKE_RANLIB_NAMES "llvm-ranlib")
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 <sep>``
-      For any of the various ``..._COMMAND`` 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).
+      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).
 
     ``COMMAND <cmd>...``
       Any of the other ``..._COMMAND`` options can have additional commands