From 2673161b6750b239ca3d0f1d40402b9f4f37c1b1 Mon Sep 17 00:00:00 2001
From: Matthew Woehlke <matthew.woehlke@kitware.com>
Date: Fri, 11 Sep 2026 12:22:25 -0400
Subject: [PATCH] install: Improve documentation, argument parsing

Adjust documentation of `install(CODE|SCRIPT)` to more understandably
reflect how the subcommand actually operates. Adjust argument parsing of
the same to "accept" the `COMPONENT` argument being given more than
once, consistent with how single-valued arguments are usually parsed.
---
 Help/command/install.rst                      |  2 +-
 Source/cmInstallCommand.cxx                   | 25 +++++--------------
 .../install/SCRIPT-CODE-arguments-stderr.txt  |  8 ------
 3 files changed, 7 insertions(+), 28 deletions(-)

diff --git a/Help/command/install.rst b/Help/command/install.rst
index cc2b9ecc20..13b062524b 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -841,7 +841,7 @@ Signatures
 
   .. code-block:: cmake
 
-    install([[SCRIPT <file>] [CODE <code>]]
+    install({ SCRIPT <file> | CODE <code> }...
             [ALL_COMPONENTS | COMPONENT <component>]
             [EXCLUDE_FROM_ALL])
 
diff --git a/Source/cmInstallCommand.cxx b/Source/cmInstallCommand.cxx
index 89167ab544..38d514a7c3 100644
--- a/Source/cmInstallCommand.cxx
+++ b/Source/cmInstallCommand.cxx
@@ -923,14 +923,8 @@ bool HandleScriptMode(std::vector<std::string> const& args,
       return ArgumentParser::Continue::No;
     }
 
-    ArgumentParser::Continue AddComponent(cm::string_view value)
-    {
-      this->Components.emplace_back(value);
-      return ArgumentParser::Continue::No;
-    }
-
     std::vector<Script> Scripts;
-    std::vector<std::string> Components;
+    cm::optional<std::string> Component;
     bool ExcludeFromAll = false;
     bool AllComponents = false;
   };
@@ -939,7 +933,7 @@ bool HandleScriptMode(std::vector<std::string> const& args,
     cmArgumentParser<Arguments>{}
       .Bind("SCRIPT"_s, &Arguments::AddScript)
       .Bind("CODE"_s, &Arguments::AddScript)
-      .Bind("COMPONENT"_s, &Arguments::AddComponent)
+      .Bind("COMPONENT"_s, &Arguments::Component)
       .Bind("EXCLUDE_FROM_ALL"_s, &Arguments::ExcludeFromAll)
       .Bind("ALL_COMPONENTS"_s, &Arguments::AllComponents);
 
@@ -949,22 +943,15 @@ bool HandleScriptMode(std::vector<std::string> const& args,
     return false;
   }
 
-  if (arguments.Components.size() > 1) {
-    status.SetError("given more than one COMPONENT for the SCRIPT or CODE "
-                    "signature of the INSTALL command. "
-                    "Use multiple INSTALL commands with one COMPONENT each.");
-    return false;
-  }
-
-  if (arguments.AllComponents && !arguments.Components.empty()) {
+  if (arguments.AllComponents && arguments.Component.has_value()) {
     status.SetError("ALL_COMPONENTS and COMPONENT are mutually exclusive");
     return false;
   }
 
   Helper helper(status);
-  std::string const component = arguments.Components.empty()
-    ? helper.DefaultComponentName
-    : arguments.Components.front();
+  std::string const component = arguments.Component.has_value()
+    ? *arguments.Component
+    : helper.DefaultComponentName;
 
   for (Arguments::Script& script : arguments.Scripts) {
     if (!script.IsCode &&
diff --git a/Tests/RunCMake/install/SCRIPT-CODE-arguments-stderr.txt b/Tests/RunCMake/install/SCRIPT-CODE-arguments-stderr.txt
index feaf4e2dc6..9aba4b03c1 100644
--- a/Tests/RunCMake/install/SCRIPT-CODE-arguments-stderr.txt
+++ b/Tests/RunCMake/install/SCRIPT-CODE-arguments-stderr.txt
@@ -36,14 +36,6 @@ Call Stack \(most recent call first\):
   CMakeLists\.txt:[0-9]+ \(include\)
 
 
-CMake Error at SCRIPT-CODE-arguments\.cmake:[0-9]+ \(install\):
-  install given more than one COMPONENT for the SCRIPT or CODE signature of
-  the INSTALL command\.  Use multiple INSTALL commands with one COMPONENT
-  each\.
-Call Stack \(most recent call first\):
-  CMakeLists\.txt:[0-9]+ \(include\)
-
-
 CMake Error at SCRIPT-CODE-arguments\.cmake:[0-9]+ \(install\):
   install ALL_COMPONENTS and COMPONENT are mutually exclusive
 Call Stack \(most recent call first\):