Add header_map rule

[luispadron]

This adds a new header_map rule for creating binary .hmap files which are required to support #import <Foo/Foo.h> semantics without restructuring an entire project.

Header maps are generated by default when using Xcode, so projects built in Xcode tend to end up relying on them. When migrating an existing project to use Bazel this lack of header map support has been a source of confusion in several threads on the Bazel Slack. Users either end up using rules_ios, which this implementation comes from, or they end up copying the header map rule locally.

By adding it to rules_apple we can help folks who are migrating existing projects. Along with documentation to make this less confusing.

My goal here is to start a discussion around the addition of the rule and it's implementation and eventually extend experimental_mixed_language_library to support generating these header maps (with this rule) when requested.

Closes #1757

Open questions

- Do we want to use the C implementation from rules_ios? There is a Swift implementation we could look at taking from
- If we do want to use the C implementation, should we spend some time getting the dependencies (lines/uthash) as Bazel modules (or at least consumed via download) vs. copying the sources into the source tree?

Decided on using Swift implementation

[luispadron]

I added a Swift implementation to see the difference between the two. Either works for me but Swift requires a bit less LOC to maintain.

[luispadron]

@keith @brentleyjones for when you two have a chance to review. I can add tests and such when we align on the hmap implementation

[thii]

Do we want to use the C implementation from rules_ios? There is a Swift implementation we could look at taking from

No strong opinion on this—I think this would rarely change, so either is fine. It would be great if you could do a perf test on a large project and/or add a Starlark flag to allow switching.

If we do want to use the C implementation, should we spend some time getting the dependencies (lines/uthash) as Bazel modules (or at least consumed via download) vs. copying the sources into the source tree?

Yes, I think we should (as a non-module dependency is fine). (Same if we use the Swift implementation)

[luispadron]

Thanks for the review @thii, some thoughts:

No strong opinion on this—I think this would rarely change, so either is fine. It would be great if you could do a perf test on a large project and/or add a Starlark flag to allow switching.

Lets go with Swift then, it's less code and a bit easier to keep maintained IMO.

If we do want to use the C implementation, should we spend some time getting the dependencies (lines/uthash) as Bazel modules (or at least consumed via download) vs. copying the sources into the source tree?

Yes, I think we should (as a non-module dependency is fine). (Same if we use the Swift implementation)

I actually changed the Swift one up a bit and had to make my own CLI around the headermap code so we'd just keep the two files in here for that one.

[mattrobmattrob]

It's my preference that we have an explicit mixed language example with header_map used and one without, if that's not too difficult. I think not muddling them together might make the path for folks more clear.

I didn't review the tools/hmaptool very closely since I'm not that familiar with the format/this functionality. 🙏

[luispadron]

It's my preference that we have an explicit mixed language example with header_map used and one without, if that's not too difficult. I think not muddling them together might make the path for folks more clear.

Do you mean you want me to add a new example specifically for header_map? If so, I can do that!

[mattrobmattrob]

It's my preference that we have an explicit mixed language example with header_map used and one without, if that's not too difficult. I think not muddling them together might make the path for folks more clear.

Do you mean you want me to add a new example specifically for header_map? If so, I can do that!

That's my preference. Something like (1) an example without header map and (2) an example with header map. In the future, it'll be easy to use it to demonstrate the two different pathways for the mixed language macro. 🙏

[luispadron]

@mattrobmattrob Makes sense, I added a new examples/multi_platform/MixedLibWithHeaderMap example and reverted the changes to the existing example.