From cc665190ca803d0352d370cc1b06935363813841 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Mon, 28 Oct 2024 11:53:52 -0700
Subject: [PATCH 1/4] Begin adding pub glossary terms to shared glossary
---
src/_data/glossary.yml | 285 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 285 insertions(+)
diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml
index 56dcd9bedc..ce3d7ee4f4 100644
--- a/src/_data/glossary.yml
+++ b/src/_data/glossary.yml
@@ -626,3 +626,288 @@
- "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"
+ category: "packages"
+ labels:
+ - "versioning"
+ - "dependencies"
+ - "pubspec"
+ alternate:
+ - "dependency constraint"
+
+- term: "Verified publisher"
+ short_description: |-
+ TODO
+ long_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: "List of verified publishers"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "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: "TODO"
+ category: "packages"
+ labels:
+ - "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: "Types of dependencies"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "versioning"
+ - "dependencies"
+
+- term: "Pub system cache"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "package config"
+ - "cache"
+ alternate:
+ - "system cache"
+
+- term: "Source"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "pubspec"
+ - "dependencies"
+ - "versioning"
+ alternate:
+ - "pub source"
+
+- term: "SDK constraint"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "pubspec"
+ - "sdk"
+ - "versioning"
+ alternate:
+ - "dart constraint"
+ - "flutter version constraint"
+
+- term: "Package"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "libraries"
+ - "dependencies"
+ alternate:
+ - "library package"
+
+- term: "Lockfile"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "libraries"
+ - "dependencies"
+ - "pubspec"
+ alternate:
+ - "pubspec.lock"
+ - "pub lock"
+ - "lock file"
+
+- term: "Library"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "language"
+ labels:
+ # TODO(parlough): Perhaps labels and categories should just be combined.
+ # This fits in the "language" and "packages" categories
+ - "packages"
+ - "imports"
+ alternate:
+ - "libraries"
+
+- term: "Immediate dependency"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "Types of dependencies"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "versioning"
+ - "dependencies"
+ alternate:
+ - "direct dependency"
+
+- term: "Entrypoint directory"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "tools"
+ labels:
+ - "packages"
+ - "bin"
+ alternate:
+ - "direct dependency"
+
+- term: "Entrypoint"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "tools"
+ labels:
+ - "packages"
+ - "bin"
+ alternate:
+ - "Entrypoint package"
+ - "Root package"
+ - "Runnable library"
+
+- term: "Dependency"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "dependencies"
+ - "package dependency"
+ - "libraries"
+
+- term: "Content hash"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "pubspec"
+ - "pubspec.lock"
+ - "dependencies"
+ alternate:
+ - "pub hash"
+ - "checksum"
+
+- term: "Application package"
+ short_description: |-
+ TODO
+ long_description: |-
+ TODO
+ related_links:
+ - text: "TODO"
+ link: "TODO"
+ category: "packages"
+ labels:
+ - "apps"
+ - "pubspec.lock"
+ alternate:
+ - "app package"
+ - "app"
\ No newline at end of file
From 58c34c80563bee8af46596ef876771b7b41a2266 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Sun, 17 Nov 2024 18:44:56 +0800
Subject: [PATCH 2/4] Remove use of categories
---
src/_data/glossary.yml | 34 ++++++++++++++++------------------
1 file changed, 16 insertions(+), 18 deletions(-)
diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml
index ce3d7ee4f4..131a15e2a3 100644
--- a/src/_data/glossary.yml
+++ b/src/_data/glossary.yml
@@ -652,8 +652,8 @@
link: "/tools/pub/dependencies#version-constraints"
- text: "Pub versioning philosophy"
link: "/tools/pub/versioning"
- category: "packages"
labels:
+ - "packages"
- "versioning"
- "dependencies"
- "pubspec"
@@ -674,8 +674,8 @@
link: "/tools/pub/publishing#verified-publisher"
- text: "List of verified publishers"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "publishing"
- "pub.dev"
@@ -696,8 +696,8 @@
link: "/tools/pub/verified-publishers"
- text: "Package publishing"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "publishing"
- "pub.dev"
@@ -715,8 +715,8 @@
related_links:
- text: "Types of dependencies"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "versioning"
- "dependencies"
@@ -728,8 +728,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "package config"
- "cache"
alternate:
@@ -743,8 +743,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "pubspec"
- "dependencies"
- "versioning"
@@ -759,8 +759,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "pubspec"
- "sdk"
- "versioning"
@@ -776,8 +776,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "libraries"
- "dependencies"
alternate:
@@ -791,8 +791,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "libraries"
- "dependencies"
- "pubspec"
@@ -809,10 +809,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "language"
labels:
- # TODO(parlough): Perhaps labels and categories should just be combined.
- # This fits in the "language" and "packages" categories
+ - "language"
- "packages"
- "imports"
alternate:
@@ -826,8 +824,8 @@
related_links:
- text: "Types of dependencies"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "versioning"
- "dependencies"
alternate:
@@ -841,9 +839,9 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "tools"
labels:
- "packages"
+ - "tools"
- "bin"
alternate:
- "direct dependency"
@@ -856,9 +854,9 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "tools"
labels:
- "packages"
+ - "tools"
- "bin"
alternate:
- "Entrypoint package"
@@ -873,8 +871,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "dependencies"
- "package dependency"
- "libraries"
@@ -887,8 +885,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "pubspec"
- "pubspec.lock"
- "dependencies"
@@ -904,8 +902,8 @@
related_links:
- text: "TODO"
link: "TODO"
- category: "packages"
labels:
+ - "packages"
- "apps"
- "pubspec.lock"
alternate:
From b571a7f5f5c718d78fadcbd6014d502f8cfa9233 Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Sun, 17 Nov 2024 19:00:23 +0800
Subject: [PATCH 3/4] Move pub glossary terms to shared glossary
---
src/_data/glossary.yml | 356 ++++++++++++++++++++++++++++++++---------
1 file changed, 278 insertions(+), 78 deletions(-)
diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml
index 131a15e2a3..812d6e6218 100644
--- a/src/_data/glossary.yml
+++ b/src/_data/glossary.yml
@@ -628,8 +628,8 @@
- "contravariant"
- term: "Version constraint"
- short_description: |-
- TODO
+# 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.
@@ -662,8 +662,6 @@
- term: "Verified publisher"
short_description: |-
- TODO
- long_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**.
@@ -672,16 +670,16 @@
link: "/tools/pub/verified-publishers"
- text: "Creating a verified publisher"
link: "/tools/pub/publishing#verified-publisher"
- - text: "List of verified publishers"
- link: "TODO"
+ - text: "Dart team publishers"
+ link: "/resources/dart-team-packages"
labels:
- "packages"
- "publishing"
- "pub.dev"
- term: "Uploader"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
Someone who has administrative permissions for a package.
A package uploader can upload new versions of the package,
@@ -695,15 +693,15 @@
- text: "Verified publishers"
link: "/tools/pub/verified-publishers"
- text: "Package publishing"
- link: "TODO"
+ link: "/tools/pub/publishing"
labels:
- "packages"
- "publishing"
- "pub.dev"
- term: "Transitive dependency"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
A dependency that your package indirectly uses because
one of its dependencies requires it.
@@ -713,52 +711,85 @@
[immediate dependency]: #immediate-dependency
related_links:
- - text: "Types of dependencies"
- link: "TODO"
+ - text: "Package dependencies"
+ link: "/tools/pub/dependencies"
labels:
- "packages"
- "versioning"
- "dependencies"
- term: "Pub system cache"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
- TODO
+ 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: "TODO"
- link: "TODO"
+ - text: "The system package cache"
+ link: "/tools/pub/cmd/pub-get#the-system-package-cache"
labels:
- "packages"
- "package config"
- "cache"
alternate:
- - "system cache"
+ - "system package cache"
-- term: "Source"
- short_description: |-
- TODO
+- term: "Dependency source"
+# short_description: |-
+# TODO
long_description: |-
- TODO
+ 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: "TODO"
- link: "TODO"
+ - 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
+# short_description: |-
+# TODO
long_description: |-
- TODO
+ 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: "TODO"
- link: "TODO"
+ - text: "Pubspec SDK constraints"
+ link: "/tools/pub/pubspec#sdk-constraints"
labels:
- "packages"
- "pubspec"
@@ -769,13 +800,50 @@
- "flutter version constraint"
- term: "Package"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
- TODO
+ 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: "TODO"
- link: "TODO"
+ - text: "How to use packages"
+ link: "/guides/packages"
labels:
- "packages"
- "libraries"
@@ -784,13 +852,31 @@
- "library package"
- term: "Lockfile"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
- TODO
- related_links:
- - text: "TODO"
- link: "TODO"
+ 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-hashes
labels:
- "packages"
- "libraries"
@@ -803,12 +889,15 @@
- term: "Library"
short_description: |-
- TODO
- long_description: |-
- TODO
+ 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: "TODO"
- link: "TODO"
+ - text: "Libraries & imports"
+ link: "/language/libraries"
labels:
- "language"
- "packages"
@@ -818,12 +907,13 @@
- term: "Immediate dependency"
short_description: |-
- TODO
- long_description: |-
- TODO
+ 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: "Types of dependencies"
- link: "TODO"
+ - text: "Package dependencies"
+ link: "/tools/pub/dependencies"
labels:
- "packages"
- "versioning"
@@ -833,12 +923,16 @@
- term: "Entrypoint directory"
short_description: |-
- TODO
+ A directory inside your package that is allowed to contain Dart entrypoints.
long_description: |-
- TODO
- related_links:
- - text: "TODO"
- link: "TODO"
+ 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"
@@ -847,13 +941,25 @@
- "direct dependency"
- term: "Entrypoint"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
- TODO
- related_links:
- - text: "TODO"
- link: "TODO"
+ 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 `<script>` tag or
+ pass it as a command-line argument to the standalone Dart VM,
+ that library is the entrypoint.
+ In other words, it's usually the `.dart` file that contains `main()`.
+
+ In the context of pub, an _entrypoint package_ or _root package_ is
+ the root of a dependency graph. It will usually be an application.
+ When you run your app, it's the entrypoint package.
+ Every other package it depends on will not be an entrypoint in that context.
+
+ A package can be an entrypoint in some contexts and not in others. Say your
+ app uses a package `A`. When you run your app, `A` is not the entrypoint
+ package. However, if you go over to `A` and execute its tests, in that
+ context, it *is* the entrypoint since your app isn't involved.
labels:
- "packages"
- "tools"
@@ -864,13 +970,23 @@
- "Runnable library"
- term: "Dependency"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
- TODO
+ Another package that your package relies on.
+ If your package wants to import code from some other package,
+ that package must be a dependency.
+ Dependencies are specified in your package's [pubspec][] and
+ described in [Package dependencies][].
+
+ To see the dependencies used by a package, use [`pub deps`][].
+
+ [pubspec]: /tools/pub/pubspec
+ [Package dependencies]: /tools/pub/dependencies
+ [`pub deps`]: /tools/pub/cmd/pub-deps
related_links:
- - text: "TODO"
- link: "TODO"
+ - text: "Package dependencies"
+ link: "/tools/pub/dependencies"
labels:
- "packages"
- "dependencies"
@@ -878,13 +994,83 @@
- "libraries"
- term: "Content hash"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
- TODO
+ The pub.dev repository maintains a sha256 hash of
+ each package version it hosts.
+ Pub clients can use this hash to
+ validate the integrity of downloaded packages,
+ and protect against changes on the repository.
+
+ When `dart pub get` downloads a package,
+ it computes the hash of the downloaded archive.
+ The hash of each hosted dependency is stored with the
+ [resolution][] in the [lockfile][].
+
+ The pub client uses this content hash
+ to verify that running `dart pub get` again using the same lockfile,
+ potentially on a different computer, uses exactly the same packages.
+
+ If the locked hash doesn't match what's currently in the pub cache,
+ pub redownloads the archive. If it still doesn't match, the lockfile
+ updates and a warning is printed. For example:
+
+ ```plaintext
+ $ dart pub get
+ Resolving dependencies...
+ [!Cached version of foo-1.0.0 has wrong hash - redownloading.!]
+ ~ foo 1.0.0 (was 1.0.0)
+ [!The existing content-hash from pubspec.lock doesn't match contents for:!]
+ * foo-1.0.0 from "pub.dev"
+ This indicates one of:
+ * The content has changed on the server since you created the pubspec.lock.
+ * The pubspec.lock has been corrupted.
+
+ [!The content-hashes in pubspec.lock has been updated.!]
+
+ For more information see:
+ https://dart.dev/go/content-hashes
+
+ Changed 1 dependency!
+ ```
+
+ The updated content hash will show up in your version control diff,
+ and should make you suspicious.
+
+ To make a discrepancy become an error instead of a warning, use
+ [`dart pub get --enforce-lockfile`][].
+ The `--enforce-lockfile` option causes resolution to fail if
+ pub can't find package archives with the same hashes,
+ without updating the lockfile.
+
+ ```plaintext
+ $ dart pub get [!--enforce-lockfile!]
+ Resolving dependencies...
+ Cached version of foo-1.0.0 has wrong hash - redownloading.
+ ~ foo 1.0.0 (was 1.0.0)
+ The existing content-hash from pubspec.lock doesn't match contents for:
+ * foo-1.0.0 from "pub.dev"
+
+ This indicates one of:
+ * The content has changed on the server since you created the pubspec.lock.
+ * The pubspec.lock has been corrupted.
+
+ For more information see:
+ https://dart.dev/go/content-hashes
+ [!Would change 1 dependency.!]
+ [!Unable to satisfy `pubspec.yaml` using `pubspec.lock`.!]
+
+ To update `pubspec.lock` run `dart pub get` without
+ `--enforce-lockfile`.
+ ```
+
+ [resolution]: /tools/pub/cmd/pub-get
+ [lockfile]: #lockfile
+ [`dart pub get --enforce-lockfile`]: /tools/pub/cmd/pub-get#enforce-lockfile
related_links:
- - text: "TODO"
- link: "TODO"
+ - text: "Enforce lockfile option"
+ link: "/tools/pub/cmd/pub-get#enforce-lockfile"
labels:
- "packages"
- "pubspec"
@@ -895,13 +1081,27 @@
- "checksum"
- term: "Application package"
- short_description: |-
- TODO
+# short_description: |-
+# TODO
long_description: |-
- TODO
- related_links:
- - text: "TODO"
- link: "TODO"
+ A package that contains a program or app, with a [main entrypoint][].
+ Meant to be run directly, either on the command line or in a browser.
+
+ Application packages may have [dependencies][] on other packages,
+ but are never depended on themselves.
+ Unlike regular [packages][], they are not intended to be shared.
+
+ Application packages should check their [lockfiles][] into source
+ control, so that everyone working on the application and every location the
+ application is deployed has a consistent set of dependencies. Because their
+ dependencies are constrained by the lockfile, application packages usually
+ specify `any` for their dependencies' [version constraints][].
+
+ [main entrypoint]: #entrypoint
+ [dependencies]: #dependency
+ [packages]: #package
+ [lockfiles]: #lockfile
+ [version constraints]: #version-constraint
labels:
- "packages"
- "apps"
From 7d5ed3a07c8fac04c42054e21036e626dc4029ae Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Sun, 17 Nov 2024 19:02:48 +0800
Subject: [PATCH 4/4] Fix content hashes link
---
src/_data/glossary.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/_data/glossary.yml b/src/_data/glossary.yml
index 812d6e6218..3f84895ee7 100644
--- a/src/_data/glossary.yml
+++ b/src/_data/glossary.yml
@@ -876,7 +876,7 @@
typically check this into source control.
For regular packages, you usually won't.
- [content hash]: #content-hashes
+ [content hash]: #content-hash
labels:
- "packages"
- "libraries"