install: Add EXCLUDE_FROM_ALL option (#14921)

Let us take an example of a project that has some tests in a component
that need to be installed into a dedicated test package.  The user
expectation is that the result could be achieved by typing the
following:

    make
    make tests
    make install
    DESTDIR=/testpkgs make install-tests

However this results in test components in the default installation as
well as the testpkg.

Add an EXCLUDE_FROM_ALL option to the install() command to tell it that
the installation rule should not be included unless its component is
explicitly specified for installation.

19 files changed, 113 insertions, 41 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 5d2add7..189b51c 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -45,11 +45,15 @@ signatures that specify them.  The common options are:
   is associated, such as "runtime" or "development".  During
   component-specific installation only install rules associated with
   the given component name will be executed.  During a full installation
-  all components are installed.  If ``COMPONENT`` is not provided a
-  default component "Unspecified" is created.  The default component
-  name may be controlled with the
+  all components are installed unless marked with ``EXCLUDE_FROM_ALL``.
+  If ``COMPONENT`` is not provided a default component "Unspecified" is
+  created.  The default component name may be controlled with the
   :variable:`CMAKE_INSTALL_DEFAULT_COMPONENT_NAME` variable.
 
+``EXCLUDE_FROM_ALL``
+  Specify that the file is excluded from a full installation and only
+  installed as part of a component-specific installation
+
 ``RENAME``
   Specify a name for an installed file that may be different from the
   original file.  Renaming is allowed only when a single file is
@@ -76,7 +80,8 @@ Installing Targets
            [PERMISSIONS permissions...]
            [CONFIGURATIONS [Debug|Release|...]]
            [COMPONENT <component>]
-           [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
+           [OPTIONAL] [EXCLUDE_FROM_ALL]
+           [NAMELINK_ONLY|NAMELINK_SKIP]
           ] [...])
 
 The ``TARGETS`` form specifies rules for installing targets from a
@@ -172,7 +177,7 @@ Installing Files
           [PERMISSIONS permissions...]
           [CONFIGURATIONS [Debug|Release|...]]
           [COMPONENT <component>]
-          [RENAME <name>] [OPTIONAL])
+          [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
 
 The ``FILES`` form specifies rules for installing files for a project.
 File names given as relative paths are interpreted with respect to the
@@ -206,7 +211,8 @@ Installing Directories
           [DIRECTORY_PERMISSIONS permissions...]
           [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
           [CONFIGURATIONS [Debug|Release|...]]
-          [COMPONENT <component>] [FILES_MATCHING]
+          [COMPONENT <component>] [EXCLUDE_FROM_ALL]
+          [FILES_MATCHING]
           [[PATTERN <pattern> | REGEX <regex>]
            [EXCLUDE] [PERMISSIONS permissions...]] [...])
 
@@ -282,7 +288,7 @@ Custom Installation Logic
 ::
 
   install([[SCRIPT <file>] [CODE <code>]]
-          [COMPONENT <component>] [...])
+          [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
 
 The ``SCRIPT`` form will invoke the given CMake script files during
 installation.  If the script file name is a relative path it will be
@@ -307,7 +313,8 @@ Installing Exports
           [PERMISSIONS permissions...]
           [CONFIGURATIONS [Debug|Release|...]]
           [EXPORT_LINK_INTERFACE_LIBRARIES]
-          [COMPONENT <component>])
+          [COMPONENT <component>]
+          [EXCLUDE_FROM_ALL])
 
 The ``EXPORT`` form generates and installs a CMake file containing code to
 import targets from the installation tree into another project.
diff --git a/Source/cmInstallCommand.cxx b/Source/cmInstallCommand.cxx
index 15a83ee..aa92d74 100644
--- a/Source/cmInstallCommand.cxx
+++ b/Source/cmInstallCommand.cxx
@@ -33,6 +33,7 @@ static cmInstallTargetGenerator* CreateInstallTargetGenerator(cmTarget& target,
                         impLib, args.GetPermissions().c_str(),
                         args.GetConfigurations(), args.GetComponent().c_str(),
                         message,
+                        args.GetExcludeFromAll(),
                         args.GetOptional() || forceOpt);
 }
 
@@ -48,7 +49,8 @@ static cmInstallFilesGenerator* CreateInstallFilesGenerator(
                         programs, args.GetPermissions().c_str(),
                         args.GetConfigurations(), args.GetComponent().c_str(),
                         message,
-                        args.GetRename().c_str(), args.GetOptional());
+                        args.GetExcludeFromAll(), args.GetRename().c_str(),
+                        args.GetOptional());
 }
 
 
@@ -117,6 +119,7 @@ bool cmInstallCommand::HandleScriptMode(std::vector<std::string> const& args)
   int componentCount = 0;
   bool doing_script = false;
   bool doing_code = false;
+  bool exclude_from_all = false;
 
   // Scan the args once for COMPONENT. Only allow one.
   //
@@ -128,6 +131,10 @@ bool cmInstallCommand::HandleScriptMode(std::vector<std::string> const& args)
         ++i;
         component = args[i];
         }
+    if(args[i] == "EXCLUDE_FROM_ALL")
+      {
+      exclude_from_all = true;
+      }
     }
 
   if(componentCount>1)
@@ -175,7 +182,7 @@ bool cmInstallCommand::HandleScriptMode(std::vector<std::string> const& args)
         }
       this->Makefile->AddInstallGenerator(
         new cmInstallScriptGenerator(script.c_str(), false,
-                                     component.c_str()));
+                                     component.c_str(), exclude_from_all));
       }
     else if(doing_code)
       {
@@ -183,7 +190,7 @@ bool cmInstallCommand::HandleScriptMode(std::vector<std::string> const& args)
       std::string code = args[i];
       this->Makefile->AddInstallGenerator(
         new cmInstallScriptGenerator(code.c_str(), true,
-                                     component.c_str()));
+                                     component.c_str(), exclude_from_all));
       }
     }
 
@@ -949,6 +956,7 @@ cmInstallCommand::HandleDirectoryMode(std::vector<std::string> const& args)
   Doing doing = DoingDirs;
   bool in_match_mode = false;
   bool optional = false;
+  bool exclude_from_all = false;
   bool message_never = false;
   std::vector<std::string> dirs;
   const char* destination = 0;
@@ -1130,6 +1138,19 @@ cmInstallCommand::HandleDirectoryMode(std::vector<std::string> const& args)
       // Switch to setting the component property.
       doing = DoingComponent;
       }
+    else if(args[i] == "EXCLUDE_FROM_ALL")
+      {
+      if(in_match_mode)
+        {
+        std::ostringstream e;
+        e << args[0] << " does not allow \""
+          << args[i] << "\" after PATTERN or REGEX.";
+        this->SetError(e.str().c_str());
+        return false;
+        }
+      exclude_from_all = true;
+      doing = DoingNone;
+      }
     else if(doing == DoingDirs)
       {
       // Convert this directory to a full path.
@@ -1273,6 +1294,7 @@ cmInstallCommand::HandleDirectoryMode(std::vector<std::string> const& args)
                                     configurations,
                                     component.c_str(),
                                     message,
+                                    exclude_from_all,
                                     literal_args.c_str(),
                                     optional));
 
@@ -1401,7 +1423,8 @@ bool cmInstallCommand::HandleExportMode(std::vector<std::string> const& args)
       exportSet,
       ica.GetDestination().c_str(),
       ica.GetPermissions().c_str(), ica.GetConfigurations(),
-      ica.GetComponent().c_str(), message, fname.c_str(),
+      ica.GetComponent().c_str(), message,
+      ica.GetExcludeFromAll(), fname.c_str(),
       name_space.GetCString(), exportOld.IsEnabled());
   this->Makefile->AddInstallGenerator(exportGenerator);
 
diff --git a/Source/cmInstallCommandArguments.cxx b/Source/cmInstallCommandArguments.cxx
index 236ca1f..6ded365 100644
--- a/Source/cmInstallCommandArguments.cxx
+++ b/Source/cmInstallCommandArguments.cxx
@@ -27,14 +27,15 @@ cmInstallCommandArguments::cmInstallCommandArguments(
                                            const std::string& defaultComponent)
 :Parser()
 ,ArgumentGroup()
-,Destination   (&Parser, "DESTINATION"   , &ArgumentGroup)
-,Component     (&Parser, "COMPONENT"     , &ArgumentGroup)
-,Rename        (&Parser, "RENAME"        , &ArgumentGroup)
-,Permissions   (&Parser, "PERMISSIONS"   , &ArgumentGroup)
-,Configurations(&Parser, "CONFIGURATIONS", &ArgumentGroup)
-,Optional      (&Parser, "OPTIONAL"      , &ArgumentGroup)
-,NamelinkOnly  (&Parser, "NAMELINK_ONLY" , &ArgumentGroup)
-,NamelinkSkip  (&Parser, "NAMELINK_SKIP" , &ArgumentGroup)
+,Destination   (&Parser, "DESTINATION"     , &ArgumentGroup)
+,Component     (&Parser, "COMPONENT"       , &ArgumentGroup)
+,ExcludeFromAll(&Parser, "EXCLUDE_FROM_ALL", &ArgumentGroup)
+,Rename        (&Parser, "RENAME"          , &ArgumentGroup)
+,Permissions   (&Parser, "PERMISSIONS"     , &ArgumentGroup)
+,Configurations(&Parser, "CONFIGURATIONS"  , &ArgumentGroup)
+,Optional      (&Parser, "OPTIONAL"        , &ArgumentGroup)
+,NamelinkOnly  (&Parser, "NAMELINK_ONLY"   , &ArgumentGroup)
+,NamelinkSkip  (&Parser, "NAMELINK_SKIP"   , &ArgumentGroup)
 ,GenericArguments(0)
 ,DefaultComponentName(defaultComponent)
 {
@@ -110,6 +111,19 @@ bool cmInstallCommandArguments::GetOptional() const
   return false;
 }
 
+bool cmInstallCommandArguments::GetExcludeFromAll() const
+{
+  if (this->ExcludeFromAll.IsEnabled())
+    {
+    return true;
+    }
+  if (this->GenericArguments!=0)
+    {
+    return this->GenericArguments->GetExcludeFromAll();
+    }
+  return false;
+}
+
 bool cmInstallCommandArguments::GetNamelinkOnly() const
 {
   if (this->NamelinkOnly.IsEnabled())
diff --git a/Source/cmInstallCommandArguments.h b/Source/cmInstallCommandArguments.h
index 90347e6..694f1ed 100644
--- a/Source/cmInstallCommandArguments.h
+++ b/Source/cmInstallCommandArguments.h
@@ -30,6 +30,7 @@ class cmInstallCommandArguments
 
     const std::string& GetDestination() const;
     const std::string& GetComponent() const;
+    bool GetExcludeFromAll() const;
     const std::string& GetRename() const;
     const std::string& GetPermissions() const;
     const std::vector<std::string>& GetConfigurations() const;
@@ -48,6 +49,7 @@ class cmInstallCommandArguments
     cmInstallCommandArguments(); // disabled
     cmCAString Destination;
     cmCAString Component;
+    cmCAEnabler ExcludeFromAll;
     cmCAString Rename;
     cmCAStringVector Permissions;
     cmCAStringVector Configurations;
diff --git a/Source/cmInstallDirectoryGenerator.cxx b/Source/cmInstallDirectoryGenerator.cxx
index f2e8609..6ad6c75 100644
--- a/Source/cmInstallDirectoryGenerator.cxx
+++ b/Source/cmInstallDirectoryGenerator.cxx
@@ -23,9 +23,11 @@ cmInstallDirectoryGenerator
                               std::vector<std::string> const& configurations,
                               const char* component,
                               MessageLevel message,
+                              bool exclude_from_all,
                               const char* literal_args,
                               bool optional):
-  cmInstallGenerator(dest, configurations, component, message),
+  cmInstallGenerator(dest, configurations, component, message,
+                     exclude_from_all),
   LocalGenerator(0),
   Directories(dirs),
   FilePermissions(file_permissions), DirPermissions(dir_permissions),
diff --git a/Source/cmInstallDirectoryGenerator.h b/Source/cmInstallDirectoryGenerator.h
index 9b732d3..b137f44 100644
--- a/Source/cmInstallDirectoryGenerator.h
+++ b/Source/cmInstallDirectoryGenerator.h
@@ -27,6 +27,7 @@ public:
                               std::vector<std::string> const& configurations,
                               const char* component,
                               MessageLevel message,
+                              bool exclude_from_all,
                               const char* literal_args,
                               bool optional = false);
   virtual ~cmInstallDirectoryGenerator();
diff --git a/Source/cmInstallExportGenerator.cxx b/Source/cmInstallExportGenerator.cxx
index 9570ba3..80fc054 100644
--- a/Source/cmInstallExportGenerator.cxx
+++ b/Source/cmInstallExportGenerator.cxx
@@ -33,9 +33,11 @@ cmInstallExportGenerator::cmInstallExportGenerator(
   std::vector<std::string> const& configurations,
   const char* component,
   MessageLevel message,
+  bool exclude_from_all,
   const char* filename, const char* name_space,
   bool exportOld)
-  :cmInstallGenerator(destination, configurations, component, message)
+  :cmInstallGenerator(destination, configurations, component, message,
+                      exclude_from_all)
   ,ExportSet(exportSet)
   ,FilePermissions(file_permissions)
   ,FileName(filename)
diff --git a/Source/cmInstallExportGenerator.h b/Source/cmInstallExportGenerator.h
index 885ed05..1b1c046 100644
--- a/Source/cmInstallExportGenerator.h
+++ b/Source/cmInstallExportGenerator.h
@@ -31,6 +31,7 @@ public:
                            const std::vector<std::string>& configurations,
                            const char* component,
                            MessageLevel message,
+                           bool exclude_from_all,
                            const char* filename, const char* name_space,
                            bool exportOld);
   ~cmInstallExportGenerator();
diff --git a/Source/cmInstallFilesCommand.cxx b/Source/cmInstallFilesCommand.cxx
index 68557bd..d3d258e 100644
--- a/Source/cmInstallFilesCommand.cxx
+++ b/Source/cmInstallFilesCommand.cxx
@@ -122,6 +122,7 @@ void cmInstallFilesCommand::CreateInstallGenerator() const
   // Use a file install generator.
   const char* no_permissions = "";
   const char* no_rename = "";
+  bool no_exclude_from_all = false;
   std::string no_component = this->Makefile->GetSafeDefinition(
                                        "CMAKE_INSTALL_DEFAULT_COMPONENT_NAME");
   std::vector<std::string> no_configurations;
@@ -131,7 +132,8 @@ void cmInstallFilesCommand::CreateInstallGenerator() const
     new cmInstallFilesGenerator(this->Files,
                                 destination.c_str(), false,
                                 no_permissions, no_configurations,
-                                no_component.c_str(), message, no_rename));
+                                no_component.c_str(), message,
+                                no_exclude_from_all, no_rename));
 }
 
 
diff --git a/Source/cmInstallFilesGenerator.cxx b/Source/cmInstallFilesGenerator.cxx
index 383031b..3dd5528 100644
--- a/Source/cmInstallFilesGenerator.cxx
+++ b/Source/cmInstallFilesGenerator.cxx
@@ -24,9 +24,11 @@ cmInstallFilesGenerator
                           std::vector<std::string> const& configurations,
                           const char* component,
                           MessageLevel message,
+                          bool exclude_from_all,
                           const char* rename,
                           bool optional):
-  cmInstallGenerator(dest, configurations, component, message),
+  cmInstallGenerator(dest, configurations, component, message,
+                     exclude_from_all),
   LocalGenerator(0),
   Files(files),
   FilePermissions(file_permissions),
diff --git a/Source/cmInstallFilesGenerator.h b/Source/cmInstallFilesGenerator.h
index bfe4039..efaf62b 100644
--- a/Source/cmInstallFilesGenerator.h
+++ b/Source/cmInstallFilesGenerator.h
@@ -26,6 +26,7 @@ public:
                           std::vector<std::string> const& configurations,
                           const char* component,
                           MessageLevel message,
+                          bool exclude_from_all,
                           const char* rename,
                           bool optional = false);
   virtual ~cmInstallFilesGenerator();
diff --git a/Source/cmInstallGenerator.cxx b/Source/cmInstallGenerator.cxx
index 2e1c5f0..660e44f 100644
--- a/Source/cmInstallGenerator.cxx
+++ b/Source/cmInstallGenerator.cxx
@@ -19,11 +19,13 @@ cmInstallGenerator
 ::cmInstallGenerator(const char* destination,
                      std::vector<std::string> const& configurations,
                      const char* component,
-                     MessageLevel message):
+                     MessageLevel message,
+                     bool exclude_from_all):
   cmScriptGenerator("CMAKE_INSTALL_CONFIG_NAME", configurations),
   Destination(destination? destination:""),
   Component(component? component:""),
-  Message(message)
+  Message(message),
+  ExcludeFromAll(exclude_from_all)
 {
 }
 
@@ -146,12 +148,16 @@ void cmInstallGenerator
 
 //----------------------------------------------------------------------------
 std::string
-cmInstallGenerator::CreateComponentTest(const char* component)
+cmInstallGenerator::CreateComponentTest(const char* component,
+                                        bool exclude_from_all)
 {
-  std::string result = "NOT CMAKE_INSTALL_COMPONENT OR "
-    "\"${CMAKE_INSTALL_COMPONENT}\" STREQUAL \"";
+  std::string result = "\"${CMAKE_INSTALL_COMPONENT}\" STREQUAL \"";
   result += component;
   result += "\"";
+  if(!exclude_from_all)
+    {
+    result += " OR NOT CMAKE_INSTALL_COMPONENT";
+    }
   return result;
 }
 
@@ -163,7 +169,7 @@ void cmInstallGenerator::GenerateScript(std::ostream& os)
 
   // Begin this block of installation.
   std::string component_test =
-    this->CreateComponentTest(this->Component.c_str());
+    this->CreateComponentTest(this->Component.c_str(),this->ExcludeFromAll);
   os << indent << "if(" << component_test << ")\n";
 
   // Generate the script possibly with per-configuration code.
diff --git a/Source/cmInstallGenerator.h b/Source/cmInstallGenerator.h
index b8e5b53..db895908 100644
--- a/Source/cmInstallGenerator.h
+++ b/Source/cmInstallGenerator.h
@@ -36,7 +36,8 @@ public:
   cmInstallGenerator(const char* destination,
                      std::vector<std::string> const& configurations,
                      const char* component,
-                     MessageLevel message);
+                     MessageLevel message,
+                     bool exclude_from_all);
   virtual ~cmInstallGenerator();
 
   void AddInstallRule(
@@ -67,12 +68,14 @@ public:
 protected:
   virtual void GenerateScript(std::ostream& os);
 
-  std::string CreateComponentTest(const char* component);
+  std::string CreateComponentTest(const char* component,
+                                  bool exclude_from_all);
 
   // Information shared by most generator types.
   std::string Destination;
   std::string Component;
   MessageLevel Message;
+  bool ExcludeFromAll;
 };
 
 #endif
diff --git a/Source/cmInstallProgramsCommand.cxx b/Source/cmInstallProgramsCommand.cxx
index e6fbe88..b6d0c45 100644
--- a/Source/cmInstallProgramsCommand.cxx
+++ b/Source/cmInstallProgramsCommand.cxx
@@ -85,6 +85,7 @@ void cmInstallProgramsCommand::FinalPass()
   // Use a file install generator.
   const char* no_permissions = "";
   const char* no_rename = "";
+  bool no_exclude_from_all = false;
   std::string no_component = this->Makefile->GetSafeDefinition(
                                        "CMAKE_INSTALL_DEFAULT_COMPONENT_NAME");
   std::vector<std::string> no_configurations;
@@ -94,7 +95,8 @@ void cmInstallProgramsCommand::FinalPass()
     new cmInstallFilesGenerator(this->Files,
                                 destination.c_str(), true,
                                 no_permissions, no_configurations,
-                                no_component.c_str(), message, no_rename));
+                                no_component.c_str(), message,
+                                no_exclude_from_all, no_rename));
 }
 
 /**
diff --git a/Source/cmInstallScriptGenerator.cxx b/Source/cmInstallScriptGenerator.cxx
index 933aa07..d58d039 100644
--- a/Source/cmInstallScriptGenerator.cxx
+++ b/Source/cmInstallScriptGenerator.cxx
@@ -14,8 +14,9 @@
 //----------------------------------------------------------------------------
 cmInstallScriptGenerator
 ::cmInstallScriptGenerator(const char* script, bool code,
-                           const char* component) :
-  cmInstallGenerator(0, std::vector<std::string>(), component, MessageDefault),
+                           const char* component, bool exclude_from_all) :
+  cmInstallGenerator(0, std::vector<std::string>(), component, MessageDefault,
+                     exclude_from_all),
   Script(script), Code(code)
 {
 }
@@ -31,7 +32,7 @@ void cmInstallScriptGenerator::GenerateScript(std::ostream& os)
 {
   Indent indent;
   std::string component_test =
-    this->CreateComponentTest(this->Component.c_str());
+    this->CreateComponentTest(this->Component.c_str(), this->ExcludeFromAll);
   os << indent << "if(" << component_test << ")\n";
 
   if(this->Code)
diff --git a/Source/cmInstallScriptGenerator.h b/Source/cmInstallScriptGenerator.h
index 54a7b21..7e7c0c8 100644
--- a/Source/cmInstallScriptGenerator.h
+++ b/Source/cmInstallScriptGenerator.h
@@ -21,7 +21,7 @@ class cmInstallScriptGenerator: public cmInstallGenerator
 {
 public:
   cmInstallScriptGenerator(const char* script, bool code,
-    const char* component);
+    const char* component, bool exclude_from_all);
   virtual ~cmInstallScriptGenerator();
 
 protected:
diff --git a/Source/cmInstallTargetGenerator.cxx b/Source/cmInstallTargetGenerator.cxx
index 5e88fa2..3d44fe2 100644
--- a/Source/cmInstallTargetGenerator.cxx
+++ b/Source/cmInstallTargetGenerator.cxx
@@ -30,8 +30,10 @@ cmInstallTargetGenerator
                            std::vector<std::string> const& configurations,
                            const char* component,
                            MessageLevel message,
+                           bool exclude_from_all,
                            bool optional):
-  cmInstallGenerator(dest, configurations, component, message),
+  cmInstallGenerator(dest, configurations, component, message,
+                     exclude_from_all),
   TargetName(targetName),
   Target(0),
   FilePermissions(file_permissions),
diff --git a/Source/cmInstallTargetGenerator.h b/Source/cmInstallTargetGenerator.h
index 18b3130..46b4532 100644
--- a/Source/cmInstallTargetGenerator.h
+++ b/Source/cmInstallTargetGenerator.h
@@ -28,6 +28,7 @@ public:
     std::vector<std::string> const& configurations,
     const char* component,
     MessageLevel message,
+    bool exclude_from_all,
     bool optional
     );
   virtual ~cmInstallTargetGenerator();
diff --git a/Source/cmLocalGenerator.cxx b/Source/cmLocalGenerator.cxx
index 1d17032..6b73987 100644
--- a/Source/cmLocalGenerator.cxx
+++ b/Source/cmLocalGenerator.cxx
@@ -2557,7 +2557,7 @@ public:
     cmInstallTargetGenerator(
       t, dest, implib, "", std::vector<std::string>(), "Unspecified",
       cmInstallGenerator::SelectMessageLevel(lg->GetMakefile()),
-      false)
+      false, false)
   {
     this->Compute(lg);
   }
@@ -2584,7 +2584,7 @@ cmLocalGenerator
     // Include the user-specified pre-install script for this target.
     if(const char* preinstall = (*l)->GetProperty("PRE_INSTALL_SCRIPT"))
       {
-      cmInstallScriptGenerator g(preinstall, false, 0);
+      cmInstallScriptGenerator g(preinstall, false, 0, false);
       g.Generate(os, config, configurationTypes);
       }
 
@@ -2645,7 +2645,7 @@ cmLocalGenerator
     // Include the user-specified post-install script for this target.
     if(const char* postinstall = (*l)->GetProperty("POST_INSTALL_SCRIPT"))
       {
-      cmInstallScriptGenerator g(postinstall, false, 0);
+      cmInstallScriptGenerator g(postinstall, false, 0, false);
       g.Generate(os, config, configurationTypes);
       }
     }