[Backport PR-511] feat: add Darwin-style framework search paths (-F, -iframework)

- Introduce DUI::SearchPath with PathKind {Include, Framework, SystemFramework}
  to model GCC/Clang behavior on Darwin.
- Extend openHeader() to search left-to-right across mixed -I/-F/-iframework
  paths, preserving order.
- Implement toAppleFrameworkRelatives() returning both Headers and
  PrivateHeaders candidates for a <Pkg/Hdr.h> include.
- Preserve backward compatibility: if searchPaths is empty, legacy
  includePaths are mirrored as Include paths.
- Update tests to use PathKind::Framework for framework-based includes.

This brings simplecpp closer to GCC/Clang behavior on macOS and enables
robust resolution of framework headers like Foundation/Foundation.h.

Suggested-by: glank <glankk@users.noreply.github.com>

(cherry picked from commit cdd5fc2)

Author: jcfr

simplecpp.cpp

@@ -13,6 +13,7 @@
 #include "simplecpp.h"
 
 #include <algorithm>
+#include <array>
 #include <cassert>
 #include <cctype>
 #include <climits>
@@ -2432,16 +2433,18 @@ static bool isAbsolutePath(const std::string &path)
 #endif
 
 namespace {
-    // "<Pkg/Hdr.h>" -> "<Pkg.framework/Headers/Hdr.h>"
-    static inline std::string
-    toAppleFrameworkRelative(const std::string& header)
+    // "<Pkg/Hdr.h>" -> "<Pkg.framework/Headers/Hdr.h>" (and PrivateHeaders variant).
+    // Returns candidates in priority order (Headers, then PrivateHeaders).
+    static inline std::array<std::string,2>
+    toAppleFrameworkRelatives(const std::string& header)
     {
         const std::size_t slash = header.find('/');
         if (slash == std::string::npos)
-            return header; // no transformation applicable
+            return { header, header }; // no transformation applicable
         const std::string pkg = header.substr(0, slash);
         const std::string tail = header.substr(slash); // includes '/'
-        return pkg + ".framework/Headers" + tail;
+        return { pkg + ".framework/Headers" + tail,
+                 pkg + ".framework/PrivateHeaders" + tail };
     }
 }
 
@@ -3015,23 +3018,34 @@ static std::string openHeader(std::ifstream &f, const simplecpp::DUI &dui, const
         }
     }
 
-    // search the header on the include paths (provided by the flags "-I...")
-    for (const auto &includePath : dui.includePaths) {
-        std::string path = openHeaderDirect(f, simplecpp::simplifyPath(includePath + "/" + header));
-        if (!path.empty())
-            return path;
+    // Build an ordered, typed path list:
+    // - Prefer DUI::searchPaths when provided (interleaved -I/-F/-iframework).
+    // - Otherwise mirror legacy includePaths into Include entries (back-compat).
+    std::vector<simplecpp::DUI::SearchPath> searchPaths;
+    if (!dui.searchPaths.empty()) {
+        searchPaths = dui.searchPaths;
+    } else {
+        searchPaths.reserve(dui.includePaths.size());
+        for (const auto &includePath : dui.includePaths)
+            searchPaths.push_back({includePath, simplecpp::DUI::PathKind::Include});
     }
 
-    // on Apple, try to find the header in the framework path
-    // Convert <includePath>/PKGNAME/myHeader -> <includePath>/PKGNAME.framework/Headers/myHeader
-    // Works on any platform, but only relevant when compiling against Apple SDKs.
-    const std::string appleFrameworkHeader = toAppleFrameworkRelative(header);
-    if (appleFrameworkHeader != header) {
-        for (const auto & includePath: dui.includePaths) {
-            const std::string frameworkCandidatePath = includePath + '/' + appleFrameworkHeader;
-            std::string simplePath = openHeaderDirect(f, simplecpp::simplifyPath(frameworkCandidatePath));
-            if (!simplePath.empty())
-                return simplePath;
+    // Search left-to-right, honoring path kinds.
+    for (const auto &searchPath : searchPaths) {
+        if (searchPath.kind == simplecpp::DUI::PathKind::Include) {
+            const std::string path = openHeaderDirect(f, simplecpp::simplifyPath(searchPath.path + "/" + header));
+            if (!path.empty())
+                return path;
+        } else {
+            // Framework & SystemFramework: try Headers then PrivateHeaders
+            const auto relatives = toAppleFrameworkRelatives(header);
+            if (relatives[0] != header) { // Skip if no framework rewrite was applied.
+                for (const auto &rel : relatives) {
+                    const std::string frameworkPath = openHeaderDirect(f, simplecpp::simplifyPath(searchPath.path + "/" + rel));
+                    if (!frameworkPath.empty())
+                        return frameworkPath;
+                }
+            }
         }
     }
 

simplecpp.h

@@ -340,13 +340,43 @@ namespace simplecpp {
 
     /**
      * Command line preprocessor settings.
-     * On the command line these are configured by -D, -U, -I, --include, -std
+     *
+     * Mirrors typical compiler options:
+     *   -D <name>=<value>       Add macro definition
+     *   -U <name>               Undefine macro
+     *   -I <dir>                Add include search directory
+     *   -F <dir>                Add framework search directory (Darwin)
+     *   -iframework <dir>       Add system framework search directory (Darwin)
+     *   --include <file>        Force inclusion of a header
+     *   -std=<version>          Select language standard (C++17, C23, etc.)
+     *
+     * Path search behavior:
+     *   - If searchPaths is non-empty, it is used directly, preserving the
+     *     left-to-right order and distinguishing between Include, Framework,
+     *     and SystemFramework kinds.
+     *   - If searchPaths is empty, legacy includePaths is used instead, and
+     *     each entry is treated as a normal Include path (for backward
+     *     compatibility).
      */
     struct SIMPLECPP_LIB DUI {
         DUI() : clearIncludeCache(false), removeComments(false) {}
+
+        // Typed search path entry. Mirrors GCC behavior for -I, -F, -iframework.
+        enum class PathKind { Include, Framework, SystemFramework };
+        struct SearchPath {
+            std::string path;
+            PathKind kind;
+        };
+
         std::list<std::string> defines;
         std::set<std::string> undefined;
+
+        // Back-compat: legacy -I list. If searchPaths is empty at use time,
+        // consumers should mirror includePaths -> searchPaths as Include.
         std::list<std::string> includePaths;
+        // New: ordered, interleaved search paths with kind.
+        std::vector<SearchPath> searchPaths;
+
         std::list<std::string> includes;
         std::string std;
         bool clearIncludeCache;

test.cpp

@@ -2158,9 +2158,11 @@ static void appleFrameworkIncludeTest()
     simplecpp::TokenList tokens2(files);
     simplecpp::DUI dui;
 #ifdef SIMPLECPP_SOURCE_DIR
-    dui.includePaths.push_back(std::string(SIMPLECPP_SOURCE_DIR) + "/testsuite");
+    dui.searchPaths.push_back({std::string(SIMPLECPP_SOURCE_DIR) + "/testsuite",
+                               simplecpp::DUI::PathKind::Framework
+                              });
 #else
-    dui.includePaths.push_back("./testsuite");
+    dui.searchPaths.push_back({"./testsuite", simplecpp::DUI::PathKind::Framework});
 #endif
     simplecpp::OutputList outputList;
     simplecpp::preprocess(tokens2, rawtokens, files, cache, dui, &outputList);
@@ -2185,9 +2187,11 @@ static void appleFrameworkHasIncludeTest()
     simplecpp::TokenList tokens2(files);
     simplecpp::DUI dui;
 #ifdef SIMPLECPP_SOURCE_DIR
-    dui.includePaths.push_back(std::string(SIMPLECPP_SOURCE_DIR) + "/testsuite");
+    dui.searchPaths.push_back({std::string(SIMPLECPP_SOURCE_DIR) + "/testsuite",
+                               simplecpp::DUI::PathKind::Framework
+                              });
 #else
-    dui.includePaths.push_back("./testsuite");
+    dui.searchPaths.push_back({"./testsuite", simplecpp::DUI::PathKind::Framework});
 #endif
     dui.std = "c++17"; // enable __has_include