[SR-8979] System library target documentation needs to warn about uniquely naming the umbrella header

[gwynne]

Previous ID	SR-8979
Radar	None
Original Reporter	@gwynne
Type	Bug

Additional Detail from JIRA

Votes	0
Component/s	Package Manager
Labels	Bug, Screened
Assignee	None
Priority	Medium

md5: 662ad20fc23b784e90d061ff88d1829e

Issue Description:

When creating a system library target for use with SPM 4.2, a common mistake is to create an umbrella header whose name is the same of that of a header it includes:

// Package.swift
// ...
        .systemLibrary(name: "CFoo", pkgConfig: "foo"),
// Sources/CFoo/module.modulemap
module CFoo {
    umbrella header "foo.h"
    link "foo"
    export *
}
// Sources/CFoo/foo.h
#include <foo.h>

It's natural to expect this will pick up the system header (presumably /usr/local/include/foo.h on macOS). This works fine when using swift build and related commands from the commandline on both Linux and macOS.

However, when using swift package generate-xcodeproj, the build context created by the resulting Xcode project gets confused by the naming identity and the Clang importer generates an empty Swift interface for the CFoo module.

The fix in Xcode is already being tracked elsewhere, but the documentation for system library targets (https://github.com/apple/swift-package-manager/blob/master/Documentation/PackageDescriptionV4_2.md#system-library-targets) is woefully minimal and could really use to include a warning about this limitation.

It's also worth noting that the system library documentation at https://github.com/apple/swift-package-manager/blob/master/Documentation/Usage.md#require-system-libraries doesn't even make mention of `.systemLibrary` targets, which is more than a little misleading for those seeking additional help on using them.

[gwynne]

Much thanks to vzsg (JIRA User) for running into the original issue and helping me nail down what was going wrong!

[aciidgh]

We really do need to ramp up our documentation.