Header mapping for C target

[cipolleschi]

Description

Hi there, I'm Riccardo, SWE @ Meta and core maintainer of React Native.

We are working on migrating React Native away from Cocoapods to Swift Package Manager.

React Native is 10 years old and it is a mixture of C++, Objective-C and Objective-C++.

One of the problem that we have is that our import/include statement and our folder structure is not standard. We have a folder named React, where all the Objecitve-C/C++ code is located. The React folder contains several subfolders which may contains source files or other subfolders.
To exaplain the problem, let's consider a file named RCTBridge.h. This file is located in the React/Base path, and the full path is React/Base/RCTBridge.h.

In theory, this file should be imprted using the full path: #import <React/Base/RCTBridge.h>.
However, in the whole codebase and in all the OSS projects that depends on React Native, this is imported with #import <React/RCTBridge.h>, effectively dropping the Base subfolder.

This works with Cocoapods because it allows to remap where the headers must be located. However, Swift PM does not have the same feature.

I also tried to use a custom module map, but the custom module map is never picked up by Swift Package Manager. When I explore the .swiftpm folder, I only find the automatically generated module.modulemap which content is different from what I specified.

Is there a way to achieve what we need? If not, would it be possible to implement a setting to achieve that?

Thank you in advance.

Expected behavior

We would like to enable source files to use the statement:

#import <React/RCTBridge.h>

to import an header file that is located in the React/Base/ subfolder.

Actual behavior

If we use #import <React/RCTBridge.h> the build step fails with a file not found error.

Steps to reproduce

1. Clone https://github.com/cipolleschi/SPMRemapping/ this is a very small reproducer I prepared.
2. swift build, this will fail because Root/MyObject.h can't be found.

Swift Package Manager version/commit hash

6.1

Swift & OS version (output of swift --version && uname -a)

swift-driver version: 1.120.5 Apple Swift version 6.1 (swiftlang-6.1.0.110.21 clang-1700.0.13.3)
Target: arm64-apple-macosx15.0
Darwin mac 24.3.0 Darwin Kernel Version 24.3.0: Thu Jan 2 20:24:22 PST 2025; root:xnu-11215.81.4~3/RELEASE_ARM64_T6041 arm64

[dschaefer2]

That pattern worked with Xcode Frameworks. It would be interesting to know how CocoaPods go that to work.

[cipolleschi]

Hi @dschaefer2, thanks for the answer.

Cocoapods copies everything in some temporary folders, creating a separate folder structure that matches the description in the podspecs. Then, it integrates the binary with the main application.
To achieve that, from an high level perspective, it:

• creates a workspace composed of 2 projects: the app and the Pods project
• injects some scripts in the Pods project to produce the binaries
• modifies the App project to integrate with the binaries by creating some dummy binaries beforehand that are going to be replaced by the one generated by the Pods project
• the build process builds the Pods project first, and then the app project.

[dschaefer2]

That actually sounds horrible, no? Why can't the code be changed to use the actual paths?

[cipolleschi]

Cocoapods works like that for every project, not just React Native.

In our specific case, we don't want to expose the details of how the framework is structured.
For example, our current structure is something like this:

/React
- /Base
  - RCTBridge.h
- /Default
  - RCTUtils.h
- /... 

using the standard way to import files, we would have to ask our users to do:

#import <React/Base/RCTBridge.h>

and

#import <React/Default/RCTUtils.h>

But that will expose the internal structure of the framework, and:

1. This is unnecessary complexity we don't want that our users have to feel
2. It can limit us if we need to move a file from one folder to another, as that would be a breaking change.

Instead, if we ask them to use the following statements:

#import <React/RCTBridge.h>
// or
#import <React/RCTUtils.h>

We can move files internally to different folders without breaking the users' code and without exposing the internal structure of the codebase.

Some alternative we considered, but discarded:

Flatten all the files in the React folder

We could, in theory, flatten the whole structure inside of the React folder. That would allow for the import that we want, but it will be terrible for maintainability. Inside the React folder we have roughly 400 source files IIRC. Having a single, long list of files, not grouped by folders, will make it really hard to understand the state of the repository. So it is not something we want.

Create an umbrella React.h file

This approach adds a React.h that import all the headers that we are exposing, so that users can do #import <React/React.h>, similarly to what we do with #import <Foundation/Foundation.h>.

However, we can't because:

1. This will be a breaking change. We have to communicate to our users that they have to change how they import the files
2. It is bad for compile time: all the files that imports a part of React Native, for example files that only import the RCTBridge.h, now imports all the headers in the framework. Compile time for every header will skyrocket as every file will need access to all the headers in the React folder, which is something we can't afford.

I hope this context helps a little.
Let me know if I can help in any way or if you have suggestions on how to move forward.