While reading through the Swift Package Manager Documentation (Swift.org - Package Manager), I was confused by some parts that did not fit my current understanding (which I derived from working with Package.swift files). I would love to know whether my understanding or the documentation is wrong :
"Each target specifies a product […]"
My understanding is that a product includes one or more targets, but a target does not specify a product.
"A target may build either a library or an executable as its product."
My understanding is that a product (not a target) may be/build either a library or an executable.
"A target’s dependencies are modules that are required by code in the package."
My understanding is a target's dependency can be a module (target) if and only if that module is in the same package. For dependencies outside the package, a target's dependency can only be a product, not a module. This becomes visible if the names are not equal. Example: If we have a package APkg that has a library product ALib that contains targets ATarget and BTarget, a target of another package could dependend on the product ALib in APkg, but not on the modules/targets ATarget and BTarget individually.
If my understanding is correct, what would be the best way to get the documentation updated? If not, could someone clarify where I am off?
Your understanding is correct. The documentation needs fixing. The text reads like a design proposal predating the package manger itself, so I suspect it was copied and pasted from something written before the terminology was finalized.
Someone else will have to answer about how to help update it, because I don’t know who builds that part of the site or how.
Somewhat tangentially, is there any sort of glossary that defines and differentiates these terms as used in Swift?
Framework
Library
Module
Package
Product
Target
Although many of us here on the forums presumably have a working understanding of what they mean in practice simply from encountering them “in the wild”, it would be nice to have a definitive source we can point to with their “official” meanings.
"Each target specifies a product […]" and "A target may build either a library or an executable as its product." are probably from this document (also outdated) in SwiftPM's source. Or, they might be from the same source material. I don't know where the third line is from.
cc @Alex_Martini (I assume, because I remember seeing you answer many documentation-related questions)
Thanks for pointing this out @objc (good choice of handle btw :)), could you please file a feedback report for this?
We currently don't offer a way to update the website through an open source process.
For the SwiftPM README that also seems outdated, you can submit a PR, if you'd like. Otherwise, feel free to mention that it also isn't correct in your feedback report.
Thanks for the CC. It looks like the FB9219948 bug has been routed to my colleague who works on the SwiftPM documentation. You might also look at the version in the main Apple developer site:
: