feat: Darwin-style framework search (-F, -iframework) with ordered path lookup

This change teaches simplecpp to resolve headers from Apple-style Framework
directories while preserving the left-to-right order of interleaved
-I/-F/-iframework search paths (like GCC/Clang on Darwin).

- Add `DUI::SearchPath` with `PathKind {Include, Framework, SystemFramework}`.
- If `DUI::searchPaths` is non-empty, use it verbatim (interleaved -I/-F/-iframework).
  Otherwise preserve back-compat by mirroring `includePaths` as Include paths.
- Update `openHeader()` to consult typed paths, and only rewrite `<Pkg/Hdr.h>`
  to `Pkg.framework/{Headers,PrivateHeaders}/Hdr.h` when a package prefix exists.
- Implement `toAppleFrameworkRelatives()` returning prioritized candidates
  (Headers first, then PrivateHeaders).
- Update CLI: support `-F<dir>` and `-iframework<dir>` (and keep `-I` as before).
- Tests use `PathKind::Framework` when checking framework layout.

Behavior notes
- The order of -I/-F/-iframework is preserved exactly as provided.
- `Framework` vs `SystemFramework` differ only in diagnostic semantics (not lookup).
- Legacy users who only set `DUI::includePaths` see identical behavior.

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

Suggested-by: glankk@users.noreply.github.com

Author: jcfr

integration_test.py

@@ -4,7 +4,15 @@
 import pathlib
 import platform
 import pytest
-from testutils import simplecpp, format_include_path_arg, format_include
+from testutils import (
+    simplecpp,
+    format_include_path_arg,
+    format_framework_path_arg,
+    format_iframework_path_arg,
+    format_include,
+    mk_framework,
+    mk_framework_private,
+)
 
 def __test_relative_header_create_header(dir, with_pragma_once=True):
     header_file = os.path.join(dir, 'test.h')
@@ -236,6 +244,190 @@ def test_same_name_header(record_property, tmpdir):
     assert "OK" in stdout
     assert stderr == ""
 
+def test_framework_basic_F_headers(record_property, tmpdir):
+    # Arrange framework: <tmp>/FwRoot/MyKit.framework/Headers/MyKit.h
+    fw_root = os.path.join(tmpdir, "FwRoot")
+    mk_framework(tmpdir, "FwRoot", "MyKit", "MyKit.h",
+                 '#define ORIGIN "FROM_FRAMEWORK"\n'
+                 'int __force_line_emission; /* anything non-preprocessor */\n')
+
+    # Source uses the macro defined in the framework header
+    source = os.path.join(tmpdir, "t.c")
+    with open(source, "wt") as f:
+        f.write("""
+                #include <MyKit/MyKit.h>
+                ORIGIN
+                """)
+
+    args = [format_framework_path_arg(fw_root), source]
+    print("*" * 10, args)
+    _, stdout, stderr = simplecpp(args, cwd=tmpdir)
+    record_property("stdout", stdout)
+    record_property("stderr", stderr)
+
+    assert stderr == ""
+    assert 'FROM_FRAMEWORK' in stdout
+    # And we should see a #line to the physical framework header path:
+    assert ("/MyKit.framework/Headers/MyKit.h" in stdout.replace("\\", "/"))
+
+def test_framework_privateheaders_when_no_headers(record_property, tmpdir):
+    # Arrange framework with only PrivateHeaders
+    fw_root = os.path.join(tmpdir, "FwRoot2")
+    mk_framework_private(tmpdir, "FwRoot2", "MyKit", "Component.h",
+                         '#define WHERE "PRIVATE"\n'
+                         'int __force_line_emission; /* anything non-preprocessor */\n')
+    # No Headers/Component.h
+
+    source = os.path.join(tmpdir, "t.c")
+    with open(source, "wt") as f:
+        f.write("""
+                #include <MyKit/Component.h>
+                WHERE
+                """)
+
+    args = [format_framework_path_arg(fw_root), source]
+    _, stdout, stderr = simplecpp(args, cwd=tmpdir)
+    record_property("stdout", stdout)
+    record_property("stderr", stderr)
+
+    assert stderr == ""
+    assert "PRIVATE" in stdout
+    # confirm we actually found PrivateHeaders:
+    assert ("/MyKit.framework/PrivateHeaders/Component.h" in stdout.replace("\\", "/"))
+
+def test_order_I_then_F_prefers_I(record_property, tmpdir):
+    incdir = os.path.join(tmpdir, "inc")
+    fw_root = os.path.join(tmpdir, "Fw")
+
+    os.mkdir(incdir)
+
+    # Normal include tree: inc/MyKit/MyKit.h
+    mykit_mykit_h = os.path.join(incdir, "MyKit", "MyKit.h")
+    os.mkdir(os.path.join(incdir, "MyKit"))
+    with open(mykit_mykit_h, "wt") as f:
+        f.write("""
+                #define ORIGIN "FROM_INCLUDE"
+                int __force_line_emission; /* anything non-preprocessor */
+                """)
+
+    # Framework: Fw/MyKit.framework/Headers/MyKit.h
+    mk_framework(tmpdir, "Fw", "MyKit", "MyKit.h",
+                 '#define ORIGIN "FROM_FRAMEWORK"\n'
+                 'int __force_line_emission; /* anything non-preprocessor */\n')
+
+    source = os.path.join(tmpdir, "t.c")
+    with open(source, "wt") as f:
+        f.write("""
+                #include <MyKit/MyKit.h>
+                ORIGIN
+                """)
+
+    # ORDER: -I first, then -F
+    args = [format_include_path_arg(incdir), format_framework_path_arg(fw_root), source]
+    _, stdout, stderr = simplecpp(args, cwd=tmpdir)
+    record_property("stdout", stdout)
+    record_property("stderr", stderr)
+
+    assert stderr == ""
+    assert "FROM_INCLUDE" in stdout
+    assert "FROM_FRAMEWORK" not in stdout
+    # path should point to the include tree:
+    assert (f'{pathlib.PurePath(incdir).as_posix()}/MyKit/MyKit.h') in stdout
+
+def test_order_F_then_I_prefers_F(record_property, tmpdir):
+    fw_root = os.path.join(tmpdir, "Fw")
+    incdir = os.path.join(tmpdir, "inc")
+
+    os.mkdir(incdir)
+
+    mk_framework(tmpdir, "Fw", "MyKit", "MyKit.h",
+                 '#define ORIGIN "FROM_FRAMEWORK"\n'
+                 'int __force_line_emission; /* anything non-preprocessor */\n')
+
+    mykit_mykit_h = os.path.join(incdir, "MyKit", "MyKit.h")
+    os.mkdir(os.path.join(incdir, "MyKit"))
+    with open(mykit_mykit_h, "wt") as f:
+        f.write("""
+                #define ORIGIN "FROM_INCLUDE"
+                int __force_line_emission; /* anything non-preprocessor */
+                """)
+
+    source = os.path.join(tmpdir, "t.c")
+    with open(source, "wt") as f:
+        f.write("""
+                #include <MyKit/MyKit.h>
+                ORIGIN
+                """)
+
+    # ORDER: -F first, then -I
+    args = [format_framework_path_arg(fw_root), format_include_path_arg(incdir), source]
+    _, stdout, stderr = simplecpp(args, cwd=tmpdir)
+    record_property("stdout", stdout)
+    record_property("stderr", stderr)
+
+    assert stderr == ""
+    assert "FROM_FRAMEWORK" in stdout
+    assert "FROM_INCLUDE" not in stdout
+    assert ("/MyKit.framework/Headers/MyKit.h" in stdout.replace("\\", "/"))
+
+def test_interleaved_multiple_paths(record_property, tmpdir):
+    # Layout:
+    #   I1/MyKit/MyKit.h          -> "I1"
+    #   F1/MyKit.framework/...    -> "F1"
+    #   I2/MyKit/MyKit.h          -> "I2"
+    #   F2/MyKit.framework/...    -> "F2"
+
+    I1 = os.path.join(tmpdir, "I1")
+    F1 = os.path.join(tmpdir, "F1")
+    I2 = os.path.join(tmpdir, "I2")
+    F2 = os.path.join(tmpdir, "F2")
+
+    os.mkdir(I1)
+    os.mkdir(I2)
+
+    i1_mykit_mykit_h = os.path.join(I1, "MyKit", "MyKit.h")
+    os.mkdir(os.path.join(I1, "MyKit"))
+    with open(i1_mykit_mykit_h, "wt") as f:
+        f.write("""
+                #define ORIGIN "I1"
+                """)
+
+    mk_framework(tmpdir, "F1", "MyKit", "MyKit.h", '#define ORIGIN "F1"\n')
+
+    i2_mykit_mykit_h = os.path.join(I2, "MyKit", "MyKit.h")
+    os.mkdir(os.path.join(I2, "MyKit"))
+    with open(i2_mykit_mykit_h, "wt") as f:
+        f.write("""
+                #define ORIGIN "I2"
+                """)
+
+    mk_framework(tmpdir, "F2", "MyKit", "MyKit.h", '#define ORIGIN "F2"\n')
+
+    source = os.path.join(tmpdir, "t.c")
+    with open(source, "wt") as f:
+        f.write("""
+                #include <MyKit/MyKit.h>
+                ORIGIN
+                """)
+
+    # Choose an ordering to validate precedence:
+    # e.g. I1, F1, I2, F2  -> expect I1
+    args = [
+        format_include_path_arg(I1),
+        format_framework_path_arg(F1),
+        format_include_path_arg(I2),
+        format_framework_path_arg(F2),
+        source
+    ]
+    _, stdout, stderr = simplecpp(args, cwd=tmpdir)
+    record_property("stdout", stdout)
+    record_property("stderr", stderr)
+
+    assert stderr == ""
+    assert '"I1"' in stdout
+    for other in ("\"F1\"", "\"I2\"", "\"F2\""):
+        assert other not in stdout
+
 def test_pragma_once_matching(record_property, tmpdir):
     test_dir = os.path.join(tmpdir, "test_dir")
     test_subdir = os.path.join(test_dir, "test_subdir")

main.cpp

@@ -43,7 +43,13 @@ int main(int argc, char **argv)
             }
             case 'I': { // include path
                 const char * const value = arg[2] ? (argv[i] + 2) : argv[++i];
-                dui.includePaths.push_back(value);
+                dui.searchPaths.push_back({value, simplecpp::DUI::PathKind::Include});
+                found = true;
+                break;
+            }
+            case 'F': { // framework path
+                const char * const value = arg[2] ? (argv[i] + 2) : argv[++i];
+                dui.searchPaths.push_back({value, simplecpp::DUI::PathKind::Framework});
                 found = true;
                 break;
             }
@@ -54,6 +60,9 @@ int main(int argc, char **argv)
                 } else if (std::strncmp(arg, "-is",3)==0) {
                     use_istream = true;
                     found = true;
+                } else if (std::strncmp(arg, "-iframework", 11)==0) {
+                    dui.searchPaths.push_back({arg + 11, simplecpp::DUI::PathKind::SystemFramework});
+                    found = true;
                 }
                 break;
             case 's':
@@ -100,6 +109,8 @@ int main(int argc, char **argv)
         std::cout << "simplecpp [options] filename" << std::endl;
         std::cout << "  -DNAME          Define NAME." << std::endl;
         std::cout << "  -IPATH          Include path." << std::endl;
+        std::cout << "  -FPATH          Framework path." << std::endl;
+        std::cout << "  -iframeworkPATH System framework path." << std::endl;
         std::cout << "  -include=FILE   Include FILE." << std::endl;
         std::cout << "  -UNAME          Undefine NAME." << std::endl;
         std::cout << "  -std=STD        Specify standard." << std::endl;