cmLocalGenerator: Clarify GetIncludeFlags signature

Make the `config` argument non-optional so all callers must be explicit.
Convert the path style argument to an enumeration to make its role clear
at call sites.

The path style argument is implemented by `ConvertToIncludeReference`,
which was introduced with the Ninja generator by commit 5b114c9bee
(Introduce a cmLocalGenerator::ConvertToIncludeReference function,
2011-09-07, v2.8.7~187^2~4).  Its only purpose is to allow the Ninja
generator to use relative paths in `-I` flags.  Add a comment explaining
this role.

Source/cmExtraSublimeTextGenerator.cxx

@@ -435,7 +435,8 @@ std::string cmExtraSublimeTextGenerator::ComputeIncludes(
   lg->GetIncludeDirectories(includes, target, language, config);
 
   std::string includesString =
-    lg->GetIncludeFlags(includes, target, language, true, false, config);
+    lg->GetIncludeFlags(includes, target, language, config, false,
+                        cmLocalGenerator::IncludePathStyle::Absolute);
 
   return includesString;
 }

Source/cmGlobalXCodeGenerator.cxx

@@ -991,7 +991,10 @@ cmXCodeObject* cmGlobalXCodeGenerator::CreateXCodeSourceFile(
       includes, genexInterpreter.Evaluate(*cincludes, INCLUDE_DIRECTORIES),
       *sf);
   }
-  lg->AppendFlags(flags, lg->GetIncludeFlags(includes, gtgt, lang, true));
+  lg->AppendFlags(
+    flags,
+    lg->GetIncludeFlags(includes, gtgt, lang, std::string(), false,
+                        cmLocalGenerator::IncludePathStyle::Absolute));
 
   cmXCodeObject* buildFile =
     this->CreateXCodeBuildFileFromPath(sf->ResolveFullPath(), gtgt, lang, sf);
@@ -2695,7 +2698,8 @@ void cmGlobalXCodeGenerator::CreateBuildSettings(cmGeneratorTarget* gtgt,
     // GNU assembly files (#16449)
     for (auto const& language : languages) {
       std::string includeFlags = this->CurrentLocalGenerator->GetIncludeFlags(
-        includes, gtgt, language, true, false, configName);
+        includes, gtgt, language, configName, false,
+        cmLocalGenerator::IncludePathStyle::Absolute);
 
       if (!includeFlags.empty()) {
         cflags[language] += " " + includeFlags;

Source/cmLocalGenerator.cxx

@@ -838,16 +838,16 @@ cmProp cmLocalGenerator::GetRuleLauncher(cmGeneratorTarget* target,
 }
 
 std::string cmLocalGenerator::ConvertToIncludeReference(
-  std::string const& path, OutputFormat format, bool forceFullPaths)
+  std::string const& path, IncludePathStyle pathStyle, OutputFormat format)
 {
-  static_cast<void>(forceFullPaths);
+  static_cast<void>(pathStyle);
   return this->ConvertToOutputForExisting(path, format);
 }
 
 std::string cmLocalGenerator::GetIncludeFlags(
-  const std::vector<std::string>& includeDirs, cmGeneratorTarget* target,
-  const std::string& lang, bool forceFullPaths, bool forResponseFile,
-  const std::string& config)
+  std::vector<std::string> const& includeDirs, cmGeneratorTarget* target,
+  std::string const& lang, std::string const& config, bool forResponseFile,
+  IncludePathStyle pathStyle)
 {
   if (lang.empty()) {
     return "";
@@ -923,7 +923,7 @@ std::string cmLocalGenerator::GetIncludeFlags(
       flagUsed = true;
     }
     std::string includePath =
-      this->ConvertToIncludeReference(i, shellFormat, forceFullPaths);
+      this->ConvertToIncludeReference(i, pathStyle, shellFormat);
     if (quotePaths && !includePath.empty() && includePath.front() != '\"') {
       includeFlags << "\"";
     }

Source/cmLocalGenerator.h

@@ -171,13 +171,19 @@ public:
                                             cmGeneratorTarget* target,
                                             const std::string& config,
                                             const std::string& lang);
+
+  enum class IncludePathStyle
+  {
+    Default,
+    Absolute,
+  };
+
   //! Get the include flags for the current makefile and language
-  std::string GetIncludeFlags(const std::vector<std::string>& includes,
-                              cmGeneratorTarget* target,
-                              const std::string& lang,
-                              bool forceFullPaths = false,
-                              bool forResponseFile = false,
-                              const std::string& config = "");
+  std::string GetIncludeFlags(
+    std::vector<std::string> const& includes, cmGeneratorTarget* target,
+    std::string const& lang, std::string const& config,
+    bool forResponseFile = false,
+    IncludePathStyle pathStyle = IncludePathStyle::Default);
 
   using GeneratorTargetVector =
     std::vector<std::unique_ptr<cmGeneratorTarget>>;
@@ -256,11 +262,6 @@ public:
   bool GetRealDependency(const std::string& name, const std::string& config,
                          std::string& dep);
 
-  virtual std::string ConvertToIncludeReference(
-    std::string const& path,
-    cmOutputConverter::OutputFormat format = cmOutputConverter::SHELL,
-    bool forceFullPaths = false);
-
   /** Called from command-line hook to clear dependencies.  */
   virtual void ClearDependencies(cmMakefile* /* mf */, bool /* verbose */) {}
 
@@ -557,6 +558,13 @@ public:
   cmProp GetRuleLauncher(cmGeneratorTarget* target, const std::string& prop);
 
 protected:
+  // The default implementation ignores the IncludePathStyle and always
+  // uses absolute paths.  A generator may override this to use relative
+  // paths in some cases.
+  virtual std::string ConvertToIncludeReference(
+    std::string const& path, IncludePathStyle pathStyle,
+    cmOutputConverter::OutputFormat format);
+
   //! put all the libraries for a target on into the given stream
   void OutputLinkLibraries(cmComputeLinkInformation* pcli,
                            cmLinkLineComputer* linkLineComputer,

Source/cmLocalNinjaGenerator.cxx

@@ -202,10 +202,10 @@ cmGlobalNinjaGenerator* cmLocalNinjaGenerator::GetGlobalNinjaGenerator()
 // Virtual protected methods.
 
 std::string cmLocalNinjaGenerator::ConvertToIncludeReference(
-  std::string const& path, cmOutputConverter::OutputFormat format,
-  bool forceFullPaths)
+  std::string const& path, IncludePathStyle pathStyle,
+  cmOutputConverter::OutputFormat format)
 {
-  if (forceFullPaths) {
+  if (pathStyle == IncludePathStyle::Absolute) {
     return this->ConvertToOutputFormat(
       cmSystemTools::CollapseFullPath(path, this->GetCurrentBinaryDirectory()),
       format);

Source/cmLocalNinjaGenerator.h

@@ -12,6 +12,7 @@
 
 #include "cmListFileCache.h"
 #include "cmLocalCommonGenerator.h"
+#include "cmLocalGenerator.h"
 #include "cmNinjaTypes.h"
 #include "cmOutputConverter.h"
 
@@ -91,9 +92,8 @@ public:
 
 protected:
   std::string ConvertToIncludeReference(
-    std::string const& path,
-    cmOutputConverter::OutputFormat format = cmOutputConverter::SHELL,
-    bool forceFullPaths = false) override;
+    std::string const& path, IncludePathStyle pathStyle,
+    cmOutputConverter::OutputFormat format) override;
 
 private:
   cmGeneratedFileStream& GetImplFileStream(const std::string& config) const;

Source/cmMakefileTargetGenerator.cxx

@@ -854,7 +854,8 @@ void cmMakefileTargetGenerator::WriteObjectRuleFiles(
   vars.Defines = definesString.c_str();
 
   std::string includesString = this->LocalGenerator->GetIncludeFlags(
-    includes, this->GeneratorTarget, lang, true, false, config);
+    includes, this->GeneratorTarget, lang, config, false,
+    cmLocalGenerator::IncludePathStyle::Absolute);
   this->LocalGenerator->AppendFlags(includesString,
                                     "$(" + lang + "_INCLUDES)");
   vars.Includes = includesString.c_str();
@@ -2195,8 +2196,8 @@ void cmMakefileTargetGenerator::AddIncludeFlags(std::string& flags,
                                               lang, this->GetConfigName());
 
   std::string includeFlags = this->LocalGenerator->GetIncludeFlags(
-    includes, this->GeneratorTarget, lang, false, useResponseFile,
-    this->GetConfigName());
+    includes, this->GeneratorTarget, lang, this->GetConfigName(),
+    useResponseFile, cmLocalGenerator::IncludePathStyle::Default);
   if (includeFlags.empty()) {
     return;
   }

Source/cmNinjaTargetGenerator.cxx

@@ -263,9 +263,10 @@ void cmNinjaTargetGenerator::AddIncludeFlags(std::string& languageFlags,
                                               language, config);
   // Add include directory flags.
   std::string includeFlags = this->LocalGenerator->GetIncludeFlags(
-    includes, this->GeneratorTarget, language,
-    language == "RC", // full include paths for RC needed by cmcldeps
-    false, config);
+    includes, this->GeneratorTarget, language, config, false,
+    // full include paths for RC needed by cmcldeps
+    language == "RC" ? cmLocalGenerator::IncludePathStyle::Absolute
+                     : cmLocalGenerator::IncludePathStyle::Default);
   if (this->GetGlobalGenerator()->IsGCCOnWindows()) {
     std::replace(includeFlags.begin(), includeFlags.end(), '\\', '/');
   }
@@ -324,7 +325,8 @@ std::string cmNinjaTargetGenerator::ComputeIncludes(
   }
 
   std::string includesString = this->LocalGenerator->GetIncludeFlags(
-    includes, this->GeneratorTarget, language, true, false, config);
+    includes, this->GeneratorTarget, language, config, false,
+    cmLocalGenerator::IncludePathStyle::Absolute);
   this->LocalGenerator->AppendFlags(includesString,
                                     this->GetIncludes(language, config));
 
@@ -1379,8 +1381,8 @@ void cmNinjaTargetGenerator::WriteObjectBuildStatement(
         cmSystemTools::GetParentDirectory(source->GetFullPath()));
 
       std::string sourceDirectoryFlag = this->LocalGenerator->GetIncludeFlags(
-        sourceDirectory, this->GeneratorTarget, language, false, false,
-        config);
+        sourceDirectory, this->GeneratorTarget, language, config, false,
+        cmLocalGenerator::IncludePathStyle::Default);
 
       vars["INCLUDES"] = cmStrCat(sourceDirectoryFlag, ' ', vars["INCLUDES"]);
     }

Source/cmake.cxx

@@ -649,7 +649,7 @@ bool cmake::FindPackage(const std::vector<std::string>& args)
     this->GlobalGenerator->CreateGenerationObjects();
     const auto& lg = this->GlobalGenerator->LocalGenerators[0];
     std::string includeFlags =
-      lg->GetIncludeFlags(includeDirs, nullptr, language);
+      lg->GetIncludeFlags(includeDirs, nullptr, language, std::string());
 
     std::string definitions = mf->GetSafeDefinition("PACKAGE_DEFINITIONS");
     printf("%s %s\n", includeFlags.c_str(), definitions.c_str());