When a module with library evolution enabled either declares or imports an ABI-public type with the same name as a module it imports, the Swift compiler can emit a module interface with invalid type references that cannot be imported. This happens because attempts to prefix type names with that module are instead interpreted as attempts to find a nested type within the identically-named type. This problem is usually invisible until a client tries to read the module interface, which is rarely done in normal development workflows, so the invalid module interface may not be noticed until much later.
(This bug is already tracked indirectly by SR-898, but I am creating a separate bug that is specific to module interfaces so we can clearly document workarounds and track emitting SR-898's new syntax into module interfaces.)
The simplest example is a module which is named after the main type it provides. For instance, suppose a module called Compass has a file which declares:
When you build the Compass module with library evolution enabled, Swift will emit a module interface for this file which looks something like this:
Note that, in the var declaration, Swift prints Compass.Direction to mean "the Direction type in the Compass module". However, when a later Swift compiler tries to import this file (which may only happen if it's a different compiler version), it will resolve the name Compass in Compass.Direction to the class Compass, not the module Compass. This will usually cause a compiler error:
It's possible to see more complicated versions of this bug; for instance, the new type could have the same name as a module imported by the interface, or it could import a type with its own name. Especially in these cases, it's possible that your own module interface will be valid because it never references the affected module, but your clients' module interfaces may be affected.
The simplest, most reliable solution is to rename either the module or the type. For instance, if the module is named CompassKit or Orienteer and the type is named Compass, there will be no conflict between them.
If that isn't possible, you may be able to work around this bug by adding the special compiler flags -Xfrontend -module-interface-preserve-types-as-written to OTHER_SWIFT_FLAGS. This solution is not 100% reliable; in particular, you may have to manually implement conformances to protocols like Hashable to get them to print correctly. It is also something your module's clients may need to adopt if their interfaces refer to types from the affected module.
If all else fails, you can write a script or tool which edits the .swiftinterface files generated by your project. A simple regular expression substitution usually works, but these sorts of tools are often quite fragile, so use them as a last resort.
Swift 5.4 supports a -verify-emitted-module-interface flag which causes it to immediately typecheck .swiftinterface files after emitting them to verify that they are valid. You can add that flag to OTHER_SWIFT_FLAGS to make sure your interfaces are readable.
You can also take a copy of your framework or library, delete the .swiftmodule files from it (leaving the .swiftinterface files alone), and check that you can still import it in a test project.
The root cause of this bug is that Swift's language rules don't provide a way to unambiguously specify a module name. SR-898 tracks this issue; once an appropriate feature is added to the language, we will need to start printing it into module interfaces. This bug will eventually track that adoption work.