Add a warning for cases in which SwiftPM generates a module map for unsupported header layouts

[abertelrud]

The problem here is actually that the logic in SwiftPM always creates a module map with either an umbrella header or an umbrella directory for every C target, even though the documentation says that a module map will only be created for a C target under particular conditions. According to https://github.com/apple/swift-package-manager/blob/master/Documentation/Usage.md#creating-c-language-targets, here are the rules:

Swift Package Manager will automatically generate a modulemap for each
C language library target for these 3 cases:

• If “include/Foo/Foo.h” exists and “Foo” is the only directory under the
“include” directory, then “include/Foo/Foo.h” becomes the umbrella header.

• If “include/Foo.h” exists and “include” contains no other subdirectory then
“include/Foo.h” becomes the umbrella header.

• Otherwise, if the “include” directory only contains header files and no
other subdirectory, it becomes the umbrella directory.

In case of complicated include layouts, a custom module.modulemap can be
provided inside “include”. SwiftPM will error out if it can not generate
a modulemap with respect to the above rules.

But the problem is that the third of those bullet points is not how the logic works. Any header layout that doesn't match one of the first two cases automatically became an umbrella directory in the generated module map.

This bug was masked because module map files weren’t passed from one C target to another until https://bugs.swift.org/browse/SR-10707 was fixed, at which point this started breaking. For C targets whose module maps were passed to Swift targets, it was always broken (but only surfaced as errors from the compiler as a result of trying to build a module from the non-modularized headers, not surfaced as errors from SwiftPM about an incorrect header layout).

We don’t want to undo the fix for SR-10707, nor is it right to tie this behavior to particular Swift tools versions, since that only postpones the problem. It’s perfectly legitimate to want to wrap an unmodified C or C++ library (with non-modularized header layout) in an authored C wrapper target that then presents a Swift-friendly modular interface to Swift targets, so non-modular C-to-C target imports should continue to be supported. The code also alludes to this, at BuildPlan.swift:409 in current main branch:

// FIXME: We should probably only warn if we're unable to generate the
// modulemap because the clang target is still a valid, it just can't be
// imported from Swift targets.

This is above the line that does a try that ends up passing on any errors if there’s a problem with the layout.

After having gone through the code, and discussing this in some detail, and trying a couple of different approaches, I think the right thing to do for 5.3 is to keep the current behavior but emit a warning asking package authors to add a custom module map. We also update the documentation to account for one other case that’s already being checked in the logic for case 1, which is that there are no headers next to the umbrella directory.

Suggesting to use a custom module map for the cases in which the package target doesn't conform to the documented layout seems like the right thing even for packages that currently happen to work.

rdar://65692136

[abertelrud]

@swift-ci please smoke test

[abertelrud]

@swift-ci please smoke test

[abertelrud]

@swift-ci please smoke test