[SR-803] Generate Human-Readable Imported Module Symbol Map

[swift-ci]

Previous ID	SR-803
Radar	None
Original Reporter	inscrutablemike (JIRA User)
Type	New Feature

Additional Detail from JIRA

| | | |------------------|-----------------| |Votes | 0 | |Component/s | Package Manager | |Labels | New Feature | |Assignee | None | |Priority | Medium | md5: 7abcbd434015409d7a7d10d44a0af859

Issue Description:

There have been many questions on the mailing lists about symbols from external libraries that either aren't imported, are imported with an unexpected name, etc. Even in the simple case, it isn't necessarily clear what symbols are available in Swift when importing a system model.

It would be very useful to have a mode of the package manager that triggers verbose symbol import logging:

1. At what point each symbol was found in the source headers. File, line number, symbol found.

2. The importer's translation result, if any
3. Some status message for exceptional cases - no translation possible, odd corner case for naming, etc.

This feature might look at first glance like a documentation system but I think it would serve the purpose of bootstrapping rather than polishing, more useful immediately to packagers of modules and users of system modules that already have documentation.

[mxcl]

This is the wrong layer for this bug I think. /cc @belkadan

[belkadan]

I'm not actually sure how to sensibly display this to a user. I'd think productizing something like swift-ide-test's interface generation would be more the direction to go. Michael, what sort of interaction are you envisioning?

[swift-ci]

Comment by Michael Henson (JIRA)

My first-draft thinking was that the output would go to stdout or stderr by default with a command-line option to redirect these particular messages to some specific file, or in case of a dependency tree, a directory that would then get files named for each module. Something as straightforward as possible that would work until a better design comes along.

I haven't had experience using swift-ide-test to dump interfaces from the serialized AST. If that tool does already, or can, run an import process that shows the details of import heuristics, either that or something very similar to it would probably fit the common use case more closely.

So rather than something like:

swift build --verbose-import --verbose-import-output=\<some value>

It could be:

swift-system-module --header=\<some header>

I lean more toward the standalone tool the more I think about it. I imagine a couple of workflows:

• Why isn't typedef struct actually_empty_struct;" imported into the module?
  swift-system-module --header=/usr/include/libjpeg.h |grep actually_empty_struct

• What symbols will random library X have when I make a Swift system module?
  swift-system-module --header=/usr/include/my_library.h > my_library_imports.txt

And perhaps as a way to surface the swift-ide-test functionality of dumping symbols from the serialized blobs that exist:

• What symbols does Swift GlibC actually contain?
  swift-system-module --modulemap=/path/to/modulemap

[abertelrud]

Anything human-readable produced by SwiftPM should be designed so that it can potentially be surfaced in an IDE. That doesn't mean of course that we don't also want to support console output for some cases.