The name is the thing listed in the manifest under the name: parameter; the identity is something completely different.
The naming inconsistencies across the ecosystem arose because changes over time in the SwiftPM team lead to changes in its goals and philosophies.
Originally the name’s only purpose was as a user facing label. Style recommendations from that era corresponded to a standard English book title or a UI label, i.e. “My Package”. Hence “SwiftPM”. However, packages revolving around a single module or executable often lacked any name distinct from that of the target, which then inherited the target’s naming conventions, such as “SwiftSyntax” from import SwiftSyntax.
The name’s first machine use was as an optional disambiguator between two identically named targets from different packages, where it went by Swift’s standard string == semantics. This saw little actual use, because clashing module names impeded builds anyway in most cases.
With the proposal of target‐based resolution, the name was to became the link between the target dependency and the package dependency so the resolver could know whether it needed to fetch the dependency in the first place. The manifest API changes were merged, erroneously connecting things by last path component instead of the name under the hood. The resolver improvements were never merged, but over the course of several versions the API was fixed to mach the proposals, then broken again.
During that era of chaos, SwiftPM was able to both infer more of the necessary connections, and support more toolchain versions at once (without #if) when the name matched the last path component. Wanting to save users from typing as much, many packages that sprouted in that time period adopted repository names as package names, such as “swift-argument-parser” (while its read‐me simultaneously calls it “Swift Argument Parser”, which is what the name field was intended to convey).
The swift- prefix in some of the repository names you cite was supposed to mark them as belonging to the Swift project, not as being written in Swift. No one else was supposed to use it. But here too the intent was lost on users in the wild and now it is meaningless.
Later on, changes in the development team lead to a desire to eliminate the name from all its machine uses and attach everything to the last path component (whereas some of the original team had considered URLs ugly, internationalization unfriendly, and something to be contained and not spread throughout the source). Since the change, the display name has even ended up marked with deprecation attributes in places I don’t believe it should be.
Finally, with the introduction of registries, the identity was invented. The last path component that was by then pervasive in the implementation did not exist for registries, so they needed something else. What you read in the registry proposals describes the constraints and conventions of registry identities. They do not apply to URL or path dependencies, which continue to support any URL or path, no matter how gnarly, and likely always will. (Removing support would be severely breaking to extant packages.) A registry identity is the identifier by which a user interacts with a registry dependency (and is thus designed to be machine friendly). But a general identity is the union of registry identities, URLs, etc. that SwiftPM internally uses to track whether two things are the same package or not. It was theoretically never supposed to be surfaced to users.
But then Xcode failed to respect SwiftPM’s API boundaries and integrated it in ways that spilled implementation details out its user interface. Users have been able to see several variations of the supposedly internal identity across a handful of Xcode releases.
So you are right that in the end it is a tangled mess. The best advice I can give is...
- If you are referring to the package in something intended for a user, such as in a read‐me heading, UI list or error message prose, use the string verbatim from the
name field.
- If you are describing to users how to depend on a package, or providing code to copy‐and‐paste, use the URL or registry identity as defined externally by the hosting platform.
- If you are implementing something mechanical that needs to tell packages apart internally, or namespace their contents into some index (such as for a DocC feature) then I guess make use of SwiftPM’s general identity, knowing you have to sanitize it yourself and can not expect it to remain stable as SwiftPM evolves.
That is the state as far as I know, but my participation has waned late and I may have missed still further changes if they were recent enough.
