diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml index 56dcd9bedc..3f84895ee7 100644 --- a/src/_data/glossary.yml +++ b/src/_data/glossary.yml @@ -626,3 +626,486 @@ - "covariant" - "contravariance" - "contravariant" + +- term: "Version constraint" +# short_description: |- +# TODO + long_description: |- + A constraint placed on each [dependency][] of a package that specifies which + versions of that dependency the package is expected to work with. + This can be a single version (`0.3.0`) or a range of versions (`^1.2.1`). + While `any` is also allowed, + for performance reasons the Dart team doesn't recommend it. + + [Packages][] should always specify version constraints + for all of their dependencies. + [Application packages][], on the other hand, should usually + allow any version of their dependencies, since they use + the [lockfile][] to manage their dependency versions. + + [dependency]: #dependency + [Packages]: #package + [Application packages]: #application-package + [lockfile]: #lockfile + related_links: + - text: "Dart package version constraints" + link: "/tools/pub/dependencies#version-constraints" + - text: "Pub versioning philosophy" + link: "/tools/pub/versioning" + labels: + - "packages" + - "versioning" + - "dependencies" + - "pubspec" + alternate: + - "dependency constraint" + +- term: "Verified publisher" + short_description: |- + One or more users who own a set of packages. + Each verified publisher is identified by a verified domain name, + such as **dart.dev**. + related_links: + - text: "Verified publishers" + link: "/tools/pub/verified-publishers" + - text: "Creating a verified publisher" + link: "/tools/pub/publishing#verified-publisher" + - text: "Dart team publishers" + link: "/resources/dart-team-packages" + labels: + - "packages" + - "publishing" + - "pub.dev" + +- term: "Uploader" +# short_description: |- +# TODO + long_description: |- + Someone who has administrative permissions for a package. + A package uploader can upload new versions of the package, + and they can also [add and remove other uploaders][] for that package. + + If a package has a verified publisher, + then all members of the publisher can upload the package. + + [add and remove other uploaders]: /tools/pub/publishing#uploaders + related_links: + - text: "Verified publishers" + link: "/tools/pub/verified-publishers" + - text: "Package publishing" + link: "/tools/pub/publishing" + labels: + - "packages" + - "publishing" + - "pub.dev" + +- term: "Transitive dependency" +# short_description: |- +# TODO + long_description: |- + A dependency that your package indirectly uses because + one of its dependencies requires it. + If your package depends on A, which in turn depends on B which + depends on C, then A is an [immediate dependency][] while + B and C are transitive ones. + + [immediate dependency]: #immediate-dependency + related_links: + - text: "Package dependencies" + link: "/tools/pub/dependencies" + labels: + - "packages" + - "versioning" + - "dependencies" + +- term: "Pub system cache" +# short_description: |- +# TODO + long_description: |- + When pub gets a remote package, + it downloads it into a single _system cache_ directory maintained by + pub. On Mac and Linux, this directory defaults to `~/.pub-cache`. + On Windows, the directory defaults to `%LOCALAPPDATA%\Pub\Cache`, + though its exact location may vary depending on the Windows version. + You can specify a different location using the + [`PUB_CACHE`][] environment variable. + + Once packages are in the system cache, + pub creates a `package_config.json` file that maps each package + used by your application to the corresponding package in the cache. + + You only have to download a given version of a package once + and can then reuse it in as many packages as you would like. + If you specify the `--offline` flag to use cached packages, + you can delete and regenerate your `package_config.json` + files without having to access the network. + + [`PUB_CACHE`]: /tools/pub/environment-variables + related_links: + - text: "The system package cache" + link: "/tools/pub/cmd/pub-get#the-system-package-cache" + labels: + - "packages" + - "package config" + - "cache" + alternate: + - "system package cache" + +- term: "Dependency source" +# short_description: |- +# TODO + long_description: |- + A kind of place that pub can get packages from. A source isn't + a specific place like the pub.dev site or some specific Git URL. + Each source describes a general procedure for + accessing a package in some way. + For example, _git_ is one source. + The git source knows how to download packages given a Git URL. + Several different [supported sources][] are available. + + [supported sources]: /tools/pub/dependencies#dependency-sources + related_links: + - text: "Pub dependency source reference" + link: "/tools/pub/dependencies#dependency-sources" + labels: + - "packages" + - "pubspec" + - "dependencies" + - "versioning" + alternate: + - "package source" + - "dependency source" + - "pub source" + +- term: "SDK constraint" +# short_description: |- +# TODO + long_description: |- + The declared versions of the Dart SDK itself that + a package declares that it supports. An SDK constraint is specified using + normal [version constraint](#version-constraint) syntax, but in a + special _environment_ section [in the pubspec][environment constraints]. + + [environment constraints]: /tools/pub/pubspec#sdk-constraints + related_links: + - text: "Pubspec SDK constraints" + link: "/tools/pub/pubspec#sdk-constraints" + labels: + - "packages" + - "pubspec" + - "sdk" + - "versioning" + alternate: + - "dart constraint" + - "flutter version constraint" + +- term: "Package" +# short_description: |- +# TODO + long_description: |- + A collection of [libraries] under a directory, + with a [pubspec.yaml] in the root of that directory. + + Packages can have [dependencies](#dependency) on other packages + *and* can be dependencies themselves. + A package's `/lib` directory contains the + [public libraries][] that other packages can import and use. + They can also include scripts to be run directly. + A package that is not intended to be depended on by other packages is an + [application package][]. + Shared packages are [published][] to pub.dev, + but you can also have non-published packages. + + Don't check the [lockfile][] of a package into source + control, since libraries should support a range of dependency versions. + The [version constraints][] of a package's + [immediate dependencies][] should be as wide as possible while still + ensuring that the dependencies will be compatible with the versions that + were tested against. + + Since [semantic versioning][] requires that libraries increment their + major version numbers for any backwards incompatible changes, + packages will usually require their dependencies' versions to be + greater than or equal to the versions that were tested and + less than the next major version. So if your library + depended on the (fictional) `transmogrify` package and you tested it at + version 1.2.1, your version constraint would be [`^1.2.1`][]. + + [libraries]: #library + [pubspec.yaml]: /tools/pub/pubspec + [public libraries]: /tools/pub/package-layout#public-libraries + [application package]: #application-package + [published]: /tools/pub/publishing + [lockfile]: #lockfile + [version constraints]: #version-constraint + [immediate dependencies]: #immediate-dependency + [semantic versioning]: https://semver.org/spec/v2.0.0-rc.1.html + [`^1.2.1`]: /tools/pub/dependencies#caret-syntax + related_links: + - text: "How to use packages" + link: "/guides/packages" + labels: + - "packages" + - "libraries" + - "dependencies" + alternate: + - "library package" + +- term: "Lockfile" +# short_description: |- +# TODO + long_description: |- + A file named `pubspec.lock` that specifies the concrete versions and + other identifying information for every immediate and transitive dependency + a package relies on. + + Unlike the pubspec, which only lists immediate dependencies and + allows version ranges, the lockfile comprehensively pins down + the entire dependency graph to specific versions of packages. + A lockfile ensures that you can recreate the + exact configuration of packages used by an application. + + The lockfile is generated automatically for you by pub when you run + [`pub get`](/tools/pub/cmd/pub-get), + [`pub upgrade`](/tools/pub/cmd/pub-upgrade), + or [`pub downgrade`](/tools/pub/cmd/pub-downgrade). + Pub includes a [content hash][] for each package + to check against during future resolutions. + + If your package is an [application package][], you will + typically check this into source control. + For regular packages, you usually won't. + + [content hash]: #content-hash + labels: + - "packages" + - "libraries" + - "dependencies" + - "pubspec" + alternate: + - "pubspec.lock" + - "pub lock" + - "lock file" + +- term: "Library" + short_description: |- + A library is a single compilation unit, made up of a single primary file and + any optional number of [parts][]. Libraries have their own private scope. + + [parts]: /resources/glossary#part-file +# long_description: |- +# TODO + related_links: + - text: "Libraries & imports" + link: "/language/libraries" + labels: + - "language" + - "packages" + - "imports" + alternate: + - "libraries" + +- term: "Immediate dependency" + short_description: |- + A [dependency](#dependency) that your package directly uses itself. + The dependencies you list in your pubspec are + your package's immediate dependencies. All other dependencies are + [transitive dependencies](#transitive-dependency). + related_links: + - text: "Package dependencies" + link: "/tools/pub/dependencies" + labels: + - "packages" + - "versioning" + - "dependencies" + alternate: + - "direct dependency" + +- term: "Entrypoint directory" + short_description: |- + A directory inside your package that is allowed to contain Dart entrypoints. + long_description: |- + A directory inside your package that is allowed to contain + [Dart entrypoints](#entrypoint). + + Pub has a list of these directories: `benchmark`, `bin`, `example`, + `test`, `tool`, and `web` (and `lib`, for [Flutter apps][]). + Any subdirectories of those (except `bin`) may also contain entrypoints. + + [Flutter apps]: https://docs.flutter.dev/packages-and-plugins/developing-packages + labels: + - "packages" + - "tools" + - "bin" + alternate: + - "direct dependency" + +- term: "Entrypoint" +# short_description: |- +# TODO + long_description: |- + In the general context of Dart, an _entrypoint_ is + a Dart library that is directly invoked by a Dart implementation. + When you reference a Dart library in a `