From 3e48208784ab42306f6ab6ff23766891fb68319b Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 30 Sep 2024 12:08:07 +0000 Subject: [PATCH 01/38] Document pub workspaces --- src/_guides/packages.md | 167 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) diff --git a/src/_guides/packages.md b/src/_guides/packages.md index 891407b156..6c8ef07021 100644 --- a/src/_guides/packages.md +++ b/src/_guides/packages.md @@ -169,6 +169,173 @@ due to conflicting version constraints in the pubspec. To identify out-of-date packages that require editing the pubspec, use [`dart pub outdated`][outdated]. +## Pub Workspaces (Mono-repo Support) + +When working on a project, you might develop multiple Dart packages in the same +version control repository (a mono-repo). + +For example you might have a directory layout like: + +```console +/ + packages/ + shared/ + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json + client_package/ + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json + server_package/ + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json +``` + +There are multiple issues with this organization: + +* You need to run `pub get` once for each package. +* You risk ending up with different versions of dependencies for each package. + Leading to confusion when context switching between the packages. +* If you open the root folder in your IDE, the dart analyzer will have to have a + separate analysis contexts for each package. + +Pub allows you to organize your repository as a "workspace" using a single +shared resolution for all your packages. + +To create a workspace: + +* Add a `pubspec.yaml` at the repository root directory with a `workspace` entry + enummerating the paths to the packages of the respository (the workspace + packages): + +```yaml +name: _ +environment: + sdk: ^3.6.0 +workspace: + - packages/helper + - packages/client_package + - packages/server_package +``` + +* For each of the existing `pubspec.yaml`s, make sure their sdk constraint is at + least `^3.6.0` and add a `resolution` entry: + + ```yaml + environment: + sdk: ^3.6.0 + resolution: workspace + ``` + +* Run `dart pub get` anywhere in the repository, and this will: + * Create a single `pubspec.lock` next to the root `pubspec.yaml` that contains + the a resolution of all the `dependencies` and `dev_dependencies` of all the + workspace packages. + * Create a single shared `.dart_tool/package_config.json` that maps package + names to file locations. + * Delete any other existing `pubspec.lock` and + `.dart_tool/package_config.json` files next to workspace packages. + +Now the file structure looks like this: + +```console +/ + packages/ + shared/ + pubspec.yaml + client_package/ + pubspec.yaml + server_package/ + pubspec.yaml + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json +``` + +{{site.alert.version-note}} +Pub workspaces was introduced in Dart 3.6.0. + +To use pub workspaces, all your workspace packages (but not your dependencies) +must have a sdk version constraint of `^3.6.0` or higher. +{{site.alert.end}} + +### Interdependencies between workspace packages + +If any of the workspace packages depend on each other, they will automatically +resolve to the one in the workspace, regardless of the source. + +Eg. `packages/client_package/pubspec.yaml` might depend on `shared`: + +```yaml +dependencies: + shared: + hosted: https://pub.dev + version: ^2.3.0 +``` + +When resolved inside the workspace, the _local_ version of `shared` will be +used. + +The local version of `shared` would still have to match the constraint +(`^2.3.0`) though. + +But when the package is consumed as a dependency without being part of the +workspace, the original source (here `hosted`) is used. + +So if `client_package` is published to pub.dev and someone depends on it, they +will get the hosted version of `shared` as a transitive dependency. + +### Dependency overrides in a workspace + +All `dependency_overrides:` sections in the workspace packages are respected, +and you can also place a `pubspec_overrides.yaml` file next to any of the +workspace `pubspec.yaml` files. + +You can only override a package once in the workspace. + +### Running a command in a specific workspace package + +Some pub commands, such as `dart pub add`, and `dart pub publish` operate on a +"current" package. You can either change directory, or use `-C` to point pub at +a directory: + +```console +$ dart pub -C packages/client_package publish +# Same as +$ cd packages/client_package ; dart pub publish ; cd - +``` + +### Temporarily resolving a package outside its workspace: + +Sometimes you might want to resolve a workspace package on its own, eg. to +validate its dependency constraints. + +One way to do this is to create a `pubspec_overides.yaml` file that resets the +`resolution:` setting. Like: + +```yaml +# packages/client_package/pubspec_overrides.yaml +resolution: +``` + +Now running `pub get` inside `packages/client_package` will create an +independent resolution. + +### Listing all workspace packages + +You can run `dart pub workspace list` to list the packages of a workspace. + +```console +$ dart pub workspace list +Package Path +_ ./ +client_package packages/client_package/ +server_package packages/server_package/ +shared packages/shared/ +``` + ## More information The following pages have more information about packages and From d81c9c5fdd717aed506f20727a858a32fef9ec8e Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 30 Sep 2024 11:10:52 -0500 Subject: [PATCH 02/38] Fix use of old aside/alert syntax --- src/content/guides/packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 00f3d3f5e6..4586c19f73 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -263,12 +263,12 @@ Now the file structure looks like this: .dart_tool/package_config.json ``` -{{site.alert.version-note}} +:::version-note Pub workspaces was introduced in Dart 3.6.0. To use pub workspaces, all your workspace packages (but not your dependencies) must have a sdk version constraint of `^3.6.0` or higher. -{{site.alert.end}} +::: ### Interdependencies between workspace packages From 3425debdaa192d3d638272bc84bd5c913fc13906 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Fri, 4 Oct 2024 07:39:27 +0000 Subject: [PATCH 03/38] update golink --- firebase.json | 2 +- src/content/guides/packages.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/firebase.json b/firebase.json index 1b682dc5a7..b65b0161fe 100644 --- a/firebase.json +++ b/firebase.json @@ -181,7 +181,7 @@ { "source": "/go/ffi", "destination": "/interop/c-interop", "type": 301 }, { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 }, { "source": "/go/macros", "destination": "/language/macros", "type": 301 }, - { "source": "/go/pub-workspaces", "destination": "https://flutter.dev/go/pub-workspace", "type": 301 }, + { "source": "/go/pub-workspaces", "destination": "/guides/packages#workspaces", "type": 301 }, { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 }, { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 }, { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 }, diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index c428ac93fe..38cf95ffef 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -261,6 +261,7 @@ To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`. [content hash]: /tools/pub/glossary#content-hashes + ## Pub Workspaces (Mono-repo Support) When working on a project, you might develop multiple Dart packages in the same From e8bc54cce9141c9dfd7843ec48e0a9f8a819aff8 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 13:01:53 +0000 Subject: [PATCH 04/38] Add glossary section --- src/content/tools/pub/glossary.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md index e284476f4d..22436db8fb 100644 --- a/src/content/tools/pub/glossary.md +++ b/src/content/tools/pub/glossary.md @@ -307,3 +307,15 @@ since they use the [lockfile](#lockfile) to manage their dependency versions. For more information, see [Pub Versioning Philosophy](/tools/pub/versioning). + +## Workspace + +A collection of packages that are developed together with a shared resolution of +their dependency constrains. Useful for developing in a mono-repo. + +The packages will have a shared `pubspec.lock` and a shared +`.dart_tool/package_config.json`. + +For more information, see +[Pub Workspaces](/guides/packages#workspaces). + From 142210c5dd4082e5f94d3e904aab7d3663df2d46 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 13:45:32 +0000 Subject: [PATCH 05/38] Document command behavior --- src/content/tools/pub/cmd/pub-add.md | 5 +++++ src/content/tools/pub/cmd/pub-deps.md | 5 +++++ src/content/tools/pub/cmd/pub-downgrade.md | 5 +++++ src/content/tools/pub/cmd/pub-lish.md | 5 +++++ src/content/tools/pub/cmd/pub-outdated.md | 4 ++++ src/content/tools/pub/cmd/pub-remove.md | 5 +++++ src/content/tools/pub/cmd/pub-upgrade.md | 8 ++++++++ 7 files changed, 37 insertions(+) diff --git a/src/content/tools/pub/cmd/pub-add.md b/src/content/tools/pub/cmd/pub-add.md index fee7385d4a..2616c93925 100644 --- a/src/content/tools/pub/cmd/pub-add.md +++ b/src/content/tools/pub/cmd/pub-add.md @@ -188,6 +188,11 @@ _Previously the `--sdk=` option_: $ dart pub add foo --sdk=flutter ``` +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub add` will add +dependencies only to the package in the current directory. + ## Options For options that apply to all pub commands, see diff --git a/src/content/tools/pub/cmd/pub-deps.md b/src/content/tools/pub/cmd/pub-deps.md index a55f2a1e83..590371087f 100644 --- a/src/content/tools/pub/cmd/pub-deps.md +++ b/src/content/tools/pub/cmd/pub-deps.md @@ -79,3 +79,8 @@ Generates output in JSON format. {% render 'pub-problems.md' %} + +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub deps` will list +dependencies for all packages in the workspace, one workspace package at a time. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-downgrade.md b/src/content/tools/pub/cmd/pub-downgrade.md index 7bfcfd1abf..fb77a31063 100644 --- a/src/content/tools/pub/cmd/pub-downgrade.md +++ b/src/content/tools/pub/cmd/pub-downgrade.md @@ -122,3 +122,8 @@ resolved versions, and returns a list of the changed constraints. Can be applied to [specific dependencies](#downgrading-specific-dependencies). {% render 'pub-problems.md' %} + +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub downgrade` will +downgrade all dependencies across the workspace. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-lish.md b/src/content/tools/pub/cmd/pub-lish.md index 1d1c9c338b..87b28642b0 100644 --- a/src/content/tools/pub/cmd/pub-lish.md +++ b/src/content/tools/pub/cmd/pub-lish.md @@ -47,3 +47,8 @@ You can either wait a few minutes in between publishing the first and the second to publish the second package immediately, by side-stepping client-side valiation. {% render 'pub-problems.md' %} + +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub publish` publishes +the package in the current directory. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-outdated.md b/src/content/tools/pub/cmd/pub-outdated.md index 03616a5d75..3c0f95f06e 100644 --- a/src/content/tools/pub/cmd/pub-outdated.md +++ b/src/content/tools/pub/cmd/pub-outdated.md @@ -193,6 +193,10 @@ When you edit the `pubspec.yaml` file, you generally update the **dependencies** and **dev_dependencies** sections so that each package uses the versions in the **Resolvable** column. +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub outdated` lists +all dependencies ## Options diff --git a/src/content/tools/pub/cmd/pub-remove.md b/src/content/tools/pub/cmd/pub-remove.md index 7a78fb064a..092ffa7107 100644 --- a/src/content/tools/pub/cmd/pub-remove.md +++ b/src/content/tools/pub/cmd/pub-remove.md @@ -19,6 +19,11 @@ and then calling `dart pub get`: $ dart pub remove http ``` +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub remove` removes +dependencies from the package in the current directory. + ## Options For options that apply to all pub commands, see diff --git a/src/content/tools/pub/cmd/pub-upgrade.md b/src/content/tools/pub/cmd/pub-upgrade.md index ccbb5b420b..7e3761919d 100644 --- a/src/content/tools/pub/cmd/pub-upgrade.md +++ b/src/content/tools/pub/cmd/pub-upgrade.md @@ -99,6 +99,14 @@ offline `dart pub upgrade` locks your app to that old version. The next time you are online, you will likely want to run `dart pub upgrade` again to upgrade to a later version. +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub upgrade` will +upgrade all dependencies in the shared resolution from across all workspace +packages. + +`dart pub upgrade --major-versions` and `dart pub upgrade --tighten` will update +constraints in all workspace `pubspec.yaml`s. ## Options From 391746eb96ea6fb7fb1d13cbb80bcaddebe86ce2 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 15:59:35 +0200 Subject: [PATCH 06/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index db6ca67972..cf2c772075 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -286,7 +286,7 @@ For example you might have a directory layout like: .dart_tool/package_config.json ``` -There are multiple issues with this organization: +There are some downsides to this setup: * You need to run `pub get` once for each package. * You risk ending up with different versions of dependencies for each package. From 7e8aa2231ee7b991e65e4ac4f301f2b8687cb2a6 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 15:59:43 +0200 Subject: [PATCH 07/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index cf2c772075..bdba976aef 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -288,7 +288,7 @@ For example you might have a directory layout like: There are some downsides to this setup: -* You need to run `pub get` once for each package. +* You need to run `dart pub get` once for each package. * You risk ending up with different versions of dependencies for each package. Leading to confusion when context switching between the packages. * If you open the root folder in your IDE, the dart analyzer will have to have a From fcfdb23e66c3c5455aef21c2472a15c700d1f253 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 15:59:53 +0200 Subject: [PATCH 08/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index bdba976aef..210d98bdc1 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -292,7 +292,7 @@ There are some downsides to this setup: * You risk ending up with different versions of dependencies for each package. Leading to confusion when context switching between the packages. * If you open the root folder in your IDE, the dart analyzer will have to have a - separate analysis contexts for each package. + separate analysis contexts for each package (increasing memory usage). Pub allows you to organize your repository as a "workspace" using a single shared resolution for all your packages. From 4506906056461177741d46b600a0759af6dc52b5 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 16:00:19 +0200 Subject: [PATCH 09/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 210d98bdc1..e03f71d2e3 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -297,6 +297,16 @@ There are some downsides to this setup: Pub allows you to organize your repository as a "workspace" using a single shared resolution for all your packages. +:::note +Using a single shared dependency resolution for all your packages increases +the risks of dependency conflicts. Because Dart does not allow multiple versions +of the same package. + +If the packages are going to be used together (as is commonly the case), +this is often a feature, as it forces you to resolve incompatibilities between your +packages when the arise, rather then when you start using the packages. +::: + To create a workspace: * Add a `pubspec.yaml` at the repository root directory with a `workspace` entry From 6734fa02389d19e66c8a3aebbd5c10f5a2540807 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 16:00:46 +0200 Subject: [PATCH 10/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index e03f71d2e3..48e52dd0a9 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -361,7 +361,7 @@ Now the file structure looks like this: Pub workspaces was introduced in Dart 3.6.0. To use pub workspaces, all your workspace packages (but not your dependencies) -must have a sdk version constraint of `^3.6.0` or higher. +must have a SDK version constraint of `^3.6.0` or higher. ::: ### Interdependencies between workspace packages From d403e892f003c231a6a62a795f56ba66c83572b2 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 16:00:51 +0200 Subject: [PATCH 11/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 48e52dd0a9..3773a61388 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -323,7 +323,7 @@ workspace: - packages/server_package ``` -* For each of the existing `pubspec.yaml`s, make sure their sdk constraint is at +* For each of the existing `pubspec.yaml`s, make sure their SDK constraint is at least `^3.6.0` and add a `resolution` entry: ```yaml From f8a0c0371563693207d136b1a0bf2021ac92b7dc Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 16:00:58 +0200 Subject: [PATCH 12/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 3773a61388..503f0a7e2d 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -315,6 +315,7 @@ To create a workspace: ```yaml name: _ +publish_to: none environment: sdk: ^3.6.0 workspace: From 1bf11b6b01a21158c35dd3e9e1cd55f84efeba7c Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 16:01:07 +0200 Subject: [PATCH 13/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 503f0a7e2d..1ceb03adb3 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -424,7 +424,7 @@ One way to do this is to create a `pubspec_overides.yaml` file that resets the resolution: ``` -Now running `pub get` inside `packages/client_package` will create an +Now running `dart pub get` inside `packages/client_package` will create an independent resolution. ### Listing all workspace packages From f3b45fadb7030af8fdb0707c9d3c12a88f6b24e0 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Mon, 7 Oct 2024 16:01:29 +0200 Subject: [PATCH 14/38] Update src/content/guides/packages.md Co-authored-by: Jonas Finnemann Jensen --- src/content/guides/packages.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 1ceb03adb3..be66d83b87 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -397,7 +397,8 @@ All `dependency_overrides:` sections in the workspace packages are respected, and you can also place a `pubspec_overrides.yaml` file next to any of the workspace `pubspec.yaml` files. -You can only override a package once in the workspace. +You can only override a package once in the workspace. To keep overrides organized +it can be preferable to keep `dependency_overrides` in the root `pubspec.yaml`. ### Running a command in a specific workspace package From 46caed45cc302938f8160a7b0fec7c2c1a8307ad Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 7 Oct 2024 22:33:28 -0500 Subject: [PATCH 15/38] Fix site-shared submodule --- site-shared | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-shared b/site-shared index 099062ff0a..43ee194938 160000 --- a/site-shared +++ b/site-shared @@ -1 +1 @@ -Subproject commit 099062ff0a72edd0f5070e39c5ca494f63e0e88b +Subproject commit 43ee1949382ad3961e3192d702681b02af03ca90 From 2efeb9e969310b2807b5f0e6b1fb6025a0512674 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 8 Oct 2024 13:57:51 +0000 Subject: [PATCH 16/38] Don't use explicit hosted: https://pub.dev --- src/content/guides/packages.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index be66d83b87..ea3a40a624 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -374,9 +374,7 @@ Eg. `packages/client_package/pubspec.yaml` might depend on `shared`: ```yaml dependencies: - shared: - hosted: https://pub.dev - version: ^2.3.0 + shared: ^2.3.0 ``` When resolved inside the workspace, the _local_ version of `shared` will be @@ -386,7 +384,7 @@ The local version of `shared` would still have to match the constraint (`^2.3.0`) though. But when the package is consumed as a dependency without being part of the -workspace, the original source (here `hosted`) is used. +workspace, the original source (here implicitly `hosted`) is used. So if `client_package` is published to pub.dev and someone depends on it, they will get the hosted version of `shared` as a transitive dependency. From 309bd3376c15f0655ef5fe4cbba697cccb9aaff3 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Thu, 10 Oct 2024 09:57:43 +0200 Subject: [PATCH 17/38] Update src/content/guides/packages.md --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index ea3a40a624..c297e633f4 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -304,7 +304,7 @@ of the same package. If the packages are going to be used together (as is commonly the case), this is often a feature, as it forces you to resolve incompatibilities between your -packages when the arise, rather then when you start using the packages. +packages when they arise, rather then when you start using the packages. ::: To create a workspace: From 07f1611b766a019d253ee77f678218c469c2a538 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 09:45:42 +0100 Subject: [PATCH 18/38] Update src/content/guides/packages.md Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com> --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index c297e633f4..5548e53283 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -265,7 +265,7 @@ To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`. ## Pub Workspaces (Mono-repo Support) When working on a project, you might develop multiple Dart packages in the same -version control repository (a mono-repo). +version control repository (a _monorepo_). For example you might have a directory layout like: From a487e6820a4746d05dca50957a394ba073b68cc7 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 09:47:55 +0100 Subject: [PATCH 19/38] Update src/content/guides/packages.md Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com> --- src/content/guides/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 5548e53283..d11084ddd7 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -262,7 +262,7 @@ To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`. [content hash]: /tools/pub/glossary#content-hashes -## Pub Workspaces (Mono-repo Support) +## Pub workspaces (Monorepo support) When working on a project, you might develop multiple Dart packages in the same version control repository (a _monorepo_). From ecca39c691b4c87fb0b784609038d746931b9254 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 09:49:05 +0100 Subject: [PATCH 20/38] Update src/content/guides/packages.md Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com> --- src/content/guides/packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index d11084ddd7..7012012445 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -289,8 +289,8 @@ For example you might have a directory layout like: There are some downsides to this setup: * You need to run `dart pub get` once for each package. -* You risk ending up with different versions of dependencies for each package. - Leading to confusion when context switching between the packages. +* You risk ending up with different versions of dependencies for each package + leading to confusion when context switching between the packages. * If you open the root folder in your IDE, the dart analyzer will have to have a separate analysis contexts for each package (increasing memory usage). From 3b8c6afba19aecb2081ed2fa4f3861b3964556ed Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 09:08:58 +0000 Subject: [PATCH 21/38] Move to separate page --- firebase.json | 2 +- site-shared | 2 +- src/_data/side-nav.yml | 2 + src/content/guides/packages.md | 179 +----------------------------- src/content/guides/workspaces.md | 180 +++++++++++++++++++++++++++++++ 5 files changed, 185 insertions(+), 180 deletions(-) create mode 100644 src/content/guides/workspaces.md diff --git a/firebase.json b/firebase.json index 44867abf7c..ca279e848a 100644 --- a/firebase.json +++ b/firebase.json @@ -181,7 +181,7 @@ { "source": "/go/ffi", "destination": "/interop/c-interop", "type": 301 }, { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 }, { "source": "/go/macros", "destination": "/language/macros", "type": 301 }, - { "source": "/go/pub-workspaces", "destination": "/guides/packages#workspaces", "type": 301 }, + { "source": "/go/pub-workspaces", "destination": "/guides/workspaces", "type": 301 }, { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 }, { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 }, { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 }, diff --git a/site-shared b/site-shared index 7527a0e7d3..43ee194938 160000 --- a/site-shared +++ b/site-shared @@ -1 +1 @@ -Subproject commit 7527a0e7d37ec92f8beeae67255788481e69ea68 +Subproject commit 43ee1949382ad3961e3192d702681b02af03ca90 diff --git a/src/_data/side-nav.yml b/src/_data/side-nav.yml index 4ade719300..7f331176a8 100644 --- a/src/_data/side-nav.yml +++ b/src/_data/side-nav.yml @@ -163,6 +163,8 @@ permalink: /tools/pub/publishing - title: Writing package pages permalink: /tools/pub/writing-package-pages + - title: Workspaces (monorepo support) + permalink: /guides/workspaces - title: Package reference expanded: false children: diff --git a/src/content/guides/packages.md b/src/content/guides/packages.md index 7012012445..8b2fa68921 100644 --- a/src/content/guides/packages.md +++ b/src/content/guides/packages.md @@ -261,184 +261,6 @@ To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`. [content hash]: /tools/pub/glossary#content-hashes - -## Pub workspaces (Monorepo support) - -When working on a project, you might develop multiple Dart packages in the same -version control repository (a _monorepo_). - -For example you might have a directory layout like: - -```console -/ - packages/ - shared/ - pubspec.yaml - pubspec.lock - .dart_tool/package_config.json - client_package/ - pubspec.yaml - pubspec.lock - .dart_tool/package_config.json - server_package/ - pubspec.yaml - pubspec.lock - .dart_tool/package_config.json -``` - -There are some downsides to this setup: - -* You need to run `dart pub get` once for each package. -* You risk ending up with different versions of dependencies for each package - leading to confusion when context switching between the packages. -* If you open the root folder in your IDE, the dart analyzer will have to have a - separate analysis contexts for each package (increasing memory usage). - -Pub allows you to organize your repository as a "workspace" using a single -shared resolution for all your packages. - -:::note -Using a single shared dependency resolution for all your packages increases -the risks of dependency conflicts. Because Dart does not allow multiple versions -of the same package. - -If the packages are going to be used together (as is commonly the case), -this is often a feature, as it forces you to resolve incompatibilities between your -packages when they arise, rather then when you start using the packages. -::: - -To create a workspace: - -* Add a `pubspec.yaml` at the repository root directory with a `workspace` entry - enummerating the paths to the packages of the respository (the workspace - packages): - -```yaml -name: _ -publish_to: none -environment: - sdk: ^3.6.0 -workspace: - - packages/helper - - packages/client_package - - packages/server_package -``` - -* For each of the existing `pubspec.yaml`s, make sure their SDK constraint is at - least `^3.6.0` and add a `resolution` entry: - - ```yaml - environment: - sdk: ^3.6.0 - resolution: workspace - ``` - -* Run `dart pub get` anywhere in the repository, and this will: - * Create a single `pubspec.lock` next to the root `pubspec.yaml` that contains - the a resolution of all the `dependencies` and `dev_dependencies` of all the - workspace packages. - * Create a single shared `.dart_tool/package_config.json` that maps package - names to file locations. - * Delete any other existing `pubspec.lock` and - `.dart_tool/package_config.json` files next to workspace packages. - -Now the file structure looks like this: - -```console -/ - packages/ - shared/ - pubspec.yaml - client_package/ - pubspec.yaml - server_package/ - pubspec.yaml - pubspec.yaml - pubspec.lock - .dart_tool/package_config.json -``` - -:::version-note -Pub workspaces was introduced in Dart 3.6.0. - -To use pub workspaces, all your workspace packages (but not your dependencies) -must have a SDK version constraint of `^3.6.0` or higher. -::: - -### Interdependencies between workspace packages - -If any of the workspace packages depend on each other, they will automatically -resolve to the one in the workspace, regardless of the source. - -Eg. `packages/client_package/pubspec.yaml` might depend on `shared`: - -```yaml -dependencies: - shared: ^2.3.0 -``` - -When resolved inside the workspace, the _local_ version of `shared` will be -used. - -The local version of `shared` would still have to match the constraint -(`^2.3.0`) though. - -But when the package is consumed as a dependency without being part of the -workspace, the original source (here implicitly `hosted`) is used. - -So if `client_package` is published to pub.dev and someone depends on it, they -will get the hosted version of `shared` as a transitive dependency. - -### Dependency overrides in a workspace - -All `dependency_overrides:` sections in the workspace packages are respected, -and you can also place a `pubspec_overrides.yaml` file next to any of the -workspace `pubspec.yaml` files. - -You can only override a package once in the workspace. To keep overrides organized -it can be preferable to keep `dependency_overrides` in the root `pubspec.yaml`. - -### Running a command in a specific workspace package - -Some pub commands, such as `dart pub add`, and `dart pub publish` operate on a -"current" package. You can either change directory, or use `-C` to point pub at -a directory: - -```console -$ dart pub -C packages/client_package publish -# Same as -$ cd packages/client_package ; dart pub publish ; cd - -``` - -### Temporarily resolving a package outside its workspace: - -Sometimes you might want to resolve a workspace package on its own, eg. to -validate its dependency constraints. - -One way to do this is to create a `pubspec_overides.yaml` file that resets the -`resolution:` setting. Like: - -```yaml -# packages/client_package/pubspec_overrides.yaml -resolution: -``` - -Now running `dart pub get` inside `packages/client_package` will create an -independent resolution. - -### Listing all workspace packages - -You can run `dart pub workspace list` to list the packages of a workspace. - -```console -$ dart pub workspace list -Package Path -_ ./ -client_package packages/client_package/ -server_package packages/server_package/ -shared packages/shared/ -``` - ## More information The following pages have more information about packages and @@ -449,6 +271,7 @@ the pub package manager. * [Creating packages](/guides/libraries/create-packages) * [Publishing packages](/tools/pub/publishing) +* [Pub workspaces (monorepo support)](/guides/workspaces) ### Reference diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md new file mode 100644 index 0000000000..0ac9c671cf --- /dev/null +++ b/src/content/guides/workspaces.md @@ -0,0 +1,180 @@ +--- +title: Pub workspaces (monorepo support) +short-title: Workspaces +description: Learn more about pub workspaces, a way to manage package monorepos. +--- + +When working on a project, you might develop multiple Dart packages in the same +version control repository (a _monorepo_). + +For example you might have a directory layout like: + +```console +/ + packages/ + shared/ + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json + client_package/ + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json + server_package/ + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json +``` + +There are some downsides to this setup: + +* You need to run `dart pub get` once for each package. +* You risk ending up with different versions of dependencies for each package + leading to confusion when context switching between the packages. +* If you open the root folder in your IDE, the dart analyzer will have to have a + separate analysis contexts for each package (increasing memory usage). + +Pub allows you to organize your repository as a "workspace" using a single +shared resolution for all your packages. + +:::note +Using a single shared dependency resolution for all your packages increases +the risks of dependency conflicts. Because Dart does not allow multiple versions +of the same package. + +If the packages are going to be used together (as is commonly the case), +this is often a feature, as it forces you to resolve incompatibilities between your +packages when they arise, rather then when you start using the packages. +::: + +To create a workspace: + +* Add a `pubspec.yaml` at the repository root directory with a `workspace` entry + enummerating the paths to the packages of the respository (the workspace + packages): + +```yaml +name: _ +publish_to: none +environment: + sdk: ^3.6.0 +workspace: + - packages/helper + - packages/client_package + - packages/server_package +``` + +* For each of the existing `pubspec.yaml`s, make sure their SDK constraint is at + least `^3.6.0` and add a `resolution` entry: + + ```yaml + environment: + sdk: ^3.6.0 + resolution: workspace + ``` + +* Run `dart pub get` anywhere in the repository, and this will: + * Create a single `pubspec.lock` next to the root `pubspec.yaml` that contains + the a resolution of all the `dependencies` and `dev_dependencies` of all the + workspace packages. + * Create a single shared `.dart_tool/package_config.json` that maps package + names to file locations. + * Delete any other existing `pubspec.lock` and + `.dart_tool/package_config.json` files next to workspace packages. + +Now the file structure looks like this: + +```console +/ + packages/ + shared/ + pubspec.yaml + client_package/ + pubspec.yaml + server_package/ + pubspec.yaml + pubspec.yaml + pubspec.lock + .dart_tool/package_config.json +``` + +:::version-note +Pub workspaces was introduced in Dart 3.6.0. + +To use pub workspaces, all your workspace packages (but not your dependencies) +must have a SDK version constraint of `^3.6.0` or higher. +::: + +## Interdependencies between workspace packages + +If any of the workspace packages depend on each other, they will automatically +resolve to the one in the workspace, regardless of the source. + +Eg. `packages/client_package/pubspec.yaml` might depend on `shared`: + +```yaml +dependencies: + shared: ^2.3.0 +``` + +When resolved inside the workspace, the _local_ version of `shared` will be +used. + +The local version of `shared` would still have to match the constraint +(`^2.3.0`) though. + +But when the package is consumed as a dependency without being part of the +workspace, the original source (here implicitly `hosted`) is used. + +So if `client_package` is published to pub.dev and someone depends on it, they +will get the hosted version of `shared` as a transitive dependency. + +## Dependency overrides in a workspace + +All `dependency_overrides:` sections in the workspace packages are respected, +and you can also place a `pubspec_overrides.yaml` file next to any of the +workspace `pubspec.yaml` files. + +You can only override a package once in the workspace. To keep overrides organized +it can be preferable to keep `dependency_overrides` in the root `pubspec.yaml`. + +## Running a command in a specific workspace package + +Some pub commands, such as `dart pub add`, and `dart pub publish` operate on a +"current" package. You can either change directory, or use `-C` to point pub at +a directory: + +```console +$ dart pub -C packages/client_package publish +# Same as +$ cd packages/client_package ; dart pub publish ; cd - +``` + +## Temporarily resolving a package outside its workspace: + +Sometimes you might want to resolve a workspace package on its own, eg. to +validate its dependency constraints. + +One way to do this is to create a `pubspec_overides.yaml` file that resets the +`resolution:` setting. Like: + +```yaml +# packages/client_package/pubspec_overrides.yaml +resolution: +``` + +Now running `dart pub get` inside `packages/client_package` will create an +independent resolution. + +## Listing all workspace packages + +You can run `dart pub workspace list` to list the packages of a workspace. + +```console +$ dart pub workspace list +Package Path +_ ./ +client_package packages/client_package/ +server_package packages/server_package/ +shared packages/shared/ +``` From 35fec1a1becad6c63110f40d7a281aa02cf94058 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 09:11:26 +0000 Subject: [PATCH 22/38] 'In a workspace' consistently after 'options' --- src/content/tools/pub/cmd/pub-add.md | 9 ++++----- src/content/tools/pub/cmd/pub-downgrade.md | 2 -- src/content/tools/pub/cmd/pub-outdated.md | 10 +++++----- src/content/tools/pub/cmd/pub-remove.md | 9 ++++----- src/content/tools/pub/cmd/pub-upgrade.md | 18 +++++++++--------- 5 files changed, 22 insertions(+), 26 deletions(-) diff --git a/src/content/tools/pub/cmd/pub-add.md b/src/content/tools/pub/cmd/pub-add.md index 2616c93925..b139e34ebc 100644 --- a/src/content/tools/pub/cmd/pub-add.md +++ b/src/content/tools/pub/cmd/pub-add.md @@ -188,11 +188,6 @@ _Previously the `--sdk=` option_: $ dart pub add foo --sdk=flutter ``` -## In a workspace - -In a [Pub Workspace](/guides/packages#workspaces) `dart pub add` will add -dependencies only to the package in the current directory. - ## Options For options that apply to all pub commands, see @@ -223,5 +218,9 @@ By default, pub precompiles executables in immediate dependencies (`--precompile`). To prevent precompilation, use `--no-precompile`. +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub add` will add +dependencies only to the package in the current directory. {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-downgrade.md b/src/content/tools/pub/cmd/pub-downgrade.md index fb77a31063..ff791d5dc2 100644 --- a/src/content/tools/pub/cmd/pub-downgrade.md +++ b/src/content/tools/pub/cmd/pub-downgrade.md @@ -96,8 +96,6 @@ In offline mode, pub looks only in your local package cache, trying to find a set of versions that work with your package from what's already available. - - ## Options For options that apply to all pub commands, see diff --git a/src/content/tools/pub/cmd/pub-outdated.md b/src/content/tools/pub/cmd/pub-outdated.md index 3c0f95f06e..ce53c6fa3c 100644 --- a/src/content/tools/pub/cmd/pub-outdated.md +++ b/src/content/tools/pub/cmd/pub-outdated.md @@ -193,11 +193,6 @@ When you edit the `pubspec.yaml` file, you generally update the **dependencies** and **dev_dependencies** sections so that each package uses the versions in the **Resolvable** column. -## In a workspace - -In a [Pub Workspace](/guides/packages#workspaces) `dart pub outdated` lists -all dependencies - ## Options For options that apply to all pub commands, see @@ -238,6 +233,11 @@ are at the latest version (`--no-up-to-date`). To include up-to-date dependencies, use `--up-to-date`. +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub outdated` lists +all dependencies + {% render 'pub-problems.md' %} [`args`]: {{site.pub-pkg}}/args diff --git a/src/content/tools/pub/cmd/pub-remove.md b/src/content/tools/pub/cmd/pub-remove.md index 092ffa7107..041d323d80 100644 --- a/src/content/tools/pub/cmd/pub-remove.md +++ b/src/content/tools/pub/cmd/pub-remove.md @@ -19,11 +19,6 @@ and then calling `dart pub get`: $ dart pub remove http ``` -## In a workspace - -In a [Pub Workspace](/guides/packages#workspaces) `dart pub remove` removes -dependencies from the package in the current directory. - ## Options For options that apply to all pub commands, see @@ -44,5 +39,9 @@ By default, pub precompiles executables in immediate dependencies (`--precompile`). To prevent precompilation, use `--no-precompile`. +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub remove` removes +dependencies from the package in the current directory. {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-upgrade.md b/src/content/tools/pub/cmd/pub-upgrade.md index 7d66ed0a97..0018f8b4c5 100644 --- a/src/content/tools/pub/cmd/pub-upgrade.md +++ b/src/content/tools/pub/cmd/pub-upgrade.md @@ -108,15 +108,6 @@ offline `dart pub upgrade` locks your app to that old version. The next time you are online, you will likely want to run `dart pub upgrade` again to upgrade to a later version. -## In a workspace - -In a [Pub Workspace](/guides/packages#workspaces) `dart pub upgrade` will -upgrade all dependencies in the shared resolution from across all workspace -packages. - -`dart pub upgrade --major-versions` and `dart pub upgrade --tighten` will update -constraints in all workspace `pubspec.yaml`s. - ## Options The `dart pub upgrade` command supports the @@ -168,4 +159,13 @@ When used with a list of packages to unlock, first the transitive closure of those packages' dependencies (in the current resolution) is computed, and then all those packages are unlocked. +## In a workspace + +In a [Pub Workspace](/guides/packages#workspaces) `dart pub upgrade` will +upgrade all dependencies in the shared resolution from across all workspace +packages. + +`dart pub upgrade --major-versions` and `dart pub upgrade --tighten` will update +constraints in all workspace `pubspec.yaml`s. + {% render 'pub-problems.md' %} From f974f71da8a05064f8560bdfe2d5cc8af05e25a4 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 10:16:11 +0100 Subject: [PATCH 23/38] Update src/content/tools/pub/glossary.md Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com> --- src/content/tools/pub/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md index 22436db8fb..519247d4ab 100644 --- a/src/content/tools/pub/glossary.md +++ b/src/content/tools/pub/glossary.md @@ -311,7 +311,7 @@ For more information, see ## Workspace A collection of packages that are developed together with a shared resolution of -their dependency constrains. Useful for developing in a mono-repo. +their dependency constraints. Useful for developing in a monorepo. The packages will have a shared `pubspec.lock` and a shared `.dart_tool/package_config.json`. From afc6ad950cd5b41ad4e18d33c1dfffeb3a713237 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 10:16:20 +0100 Subject: [PATCH 24/38] Update src/content/tools/pub/glossary.md Co-authored-by: Marya <111139605+MaryaBelanger@users.noreply.github.com> --- src/content/tools/pub/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md index 519247d4ab..d9e67251a6 100644 --- a/src/content/tools/pub/glossary.md +++ b/src/content/tools/pub/glossary.md @@ -316,6 +316,6 @@ their dependency constraints. Useful for developing in a monorepo. The packages will have a shared `pubspec.lock` and a shared `.dart_tool/package_config.json`. -For more information, see +For more information, read [Pub Workspaces](/guides/packages#workspaces). From 1cd18bd5219434266f788b0df38c3a926b565303 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 09:19:46 +0000 Subject: [PATCH 25/38] Incorporate suggestions --- src/content/guides/workspaces.md | 8 ++++---- src/content/tools/pub/cmd/pub-upgrade.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md index 0ac9c671cf..a9ed35d866 100644 --- a/src/content/guides/workspaces.md +++ b/src/content/guides/workspaces.md @@ -34,7 +34,7 @@ There are some downsides to this setup: * If you open the root folder in your IDE, the dart analyzer will have to have a separate analysis contexts for each package (increasing memory usage). -Pub allows you to organize your repository as a "workspace" using a single +Pub allows you to organize your repository as a _workspace_ using a single shared resolution for all your packages. :::note @@ -152,11 +152,11 @@ $ cd packages/client_package ; dart pub publish ; cd - ## Temporarily resolving a package outside its workspace: -Sometimes you might want to resolve a workspace package on its own, eg. to -validate its dependency constraints. +Sometimes you might want to resolve a workspace package on its own, for example +to validate its dependency constraints. One way to do this is to create a `pubspec_overides.yaml` file that resets the -`resolution:` setting. Like: +`resolution` setting, like so: ```yaml # packages/client_package/pubspec_overrides.yaml diff --git a/src/content/tools/pub/cmd/pub-upgrade.md b/src/content/tools/pub/cmd/pub-upgrade.md index 0018f8b4c5..3f089373e4 100644 --- a/src/content/tools/pub/cmd/pub-upgrade.md +++ b/src/content/tools/pub/cmd/pub-upgrade.md @@ -166,6 +166,6 @@ upgrade all dependencies in the shared resolution from across all workspace packages. `dart pub upgrade --major-versions` and `dart pub upgrade --tighten` will update -constraints in all workspace `pubspec.yaml`s. +constraints in all workspace `pubspec.yaml` files. {% render 'pub-problems.md' %} From 8f5f78be8b5ef6127489925dade48e502bb610c6 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 12 Nov 2024 10:30:15 +0000 Subject: [PATCH 26/38] Update glossary link --- src/content/tools/pub/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md index d9e67251a6..43763dad5e 100644 --- a/src/content/tools/pub/glossary.md +++ b/src/content/tools/pub/glossary.md @@ -317,5 +317,5 @@ The packages will have a shared `pubspec.lock` and a shared `.dart_tool/package_config.json`. For more information, read -[Pub Workspaces](/guides/packages#workspaces). +[Pub Workspaces](/guides/workspaces). From 1934e67e5f4ab5390f966bc1477cb1677dc0aa01 Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Thu, 14 Nov 2024 10:18:52 -0800 Subject: [PATCH 27/38] minor fixes, site-shared test --- src/content/guides/workspaces.md | 44 ++++++++++++++++---------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md index a9ed35d866..0ed6f37dd4 100644 --- a/src/content/guides/workspaces.md +++ b/src/content/guides/workspaces.md @@ -29,9 +29,9 @@ For example you might have a directory layout like: There are some downsides to this setup: * You need to run `dart pub get` once for each package. -* You risk ending up with different versions of dependencies for each package +* You risk ending up with different versions of dependencies for each package, leading to confusion when context switching between the packages. -* If you open the root folder in your IDE, the dart analyzer will have to have a +* If you open the root folder in your IDE, the dart analyzer will have to have separate analysis contexts for each package (increasing memory usage). Pub allows you to organize your repository as a _workspace_ using a single @@ -39,12 +39,12 @@ shared resolution for all your packages. :::note Using a single shared dependency resolution for all your packages increases -the risks of dependency conflicts. Because Dart does not allow multiple versions +the risks of dependency conflicts, because Dart does not allow multiple versions of the same package. If the packages are going to be used together (as is commonly the case), -this is often a feature, as it forces you to resolve incompatibilities between your -packages when they arise, rather then when you start using the packages. +this risk is a useful feature. It forces you to resolve incompatibilities between +your packages when they arise, rather then when you start using the packages. ::: To create a workspace: @@ -53,19 +53,19 @@ To create a workspace: enummerating the paths to the packages of the respository (the workspace packages): -```yaml -name: _ -publish_to: none -environment: - sdk: ^3.6.0 -workspace: - - packages/helper - - packages/client_package - - packages/server_package -``` + ```yaml + name: _ + publish_to: none + environment: + sdk: ^3.6.0 + workspace: + - packages/helper + - packages/client_package + - packages/server_package + ``` -* For each of the existing `pubspec.yaml`s, make sure their SDK constraint is at - least `^3.6.0` and add a `resolution` entry: +* For each of the existing `pubspec.yaml` filrd, make sure their SDK constraint + is at least `^3.6.0` and add a `resolution` entry: ```yaml environment: @@ -73,7 +73,7 @@ workspace: resolution: workspace ``` -* Run `dart pub get` anywhere in the repository, and this will: +* Run `dart pub get` anywhere in the repository. This will: * Create a single `pubspec.lock` next to the root `pubspec.yaml` that contains the a resolution of all the `dependencies` and `dev_dependencies` of all the workspace packages. @@ -131,12 +131,12 @@ will get the hosted version of `shared` as a transitive dependency. ## Dependency overrides in a workspace -All `dependency_overrides:` sections in the workspace packages are respected, -and you can also place a `pubspec_overrides.yaml` file next to any of the +All `dependency_overrides` sections in the workspace packages are respected. +You can also place a `pubspec_overrides.yaml` file next to any of the workspace `pubspec.yaml` files. -You can only override a package once in the workspace. To keep overrides organized -it can be preferable to keep `dependency_overrides` in the root `pubspec.yaml`. +You can only override a package once in the workspace. To keep overrides organized, +it's preferable to keep `dependency_overrides` in the root `pubspec.yaml`. ## Running a command in a specific workspace package From 7e6358c87e38e6307c9e2d7535d1cce59f9798ef Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Sat, 16 Nov 2024 02:50:59 +0800 Subject: [PATCH 28/38] Reupdate site-shared submodule --- site-shared | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-shared b/site-shared index 43ee194938..7527a0e7d3 160000 --- a/site-shared +++ b/site-shared @@ -1 +1 @@ -Subproject commit 43ee1949382ad3961e3192d702681b02af03ca90 +Subproject commit 7527a0e7d37ec92f8beeae67255788481e69ea68 From 2b2e31ff967ae2b4061f2150d18d8728491de146 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Sat, 16 Nov 2024 02:57:21 +0800 Subject: [PATCH 29/38] Fix pub workspace links --- src/content/tools/pub/cmd/pub-add.md | 2 +- src/content/tools/pub/cmd/pub-deps.md | 2 +- src/content/tools/pub/cmd/pub-downgrade.md | 2 +- src/content/tools/pub/cmd/pub-lish.md | 2 +- src/content/tools/pub/cmd/pub-outdated.md | 2 +- src/content/tools/pub/cmd/pub-remove.md | 2 +- src/content/tools/pub/cmd/pub-upgrade.md | 2 +- src/content/tools/pub/glossary.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/tools/pub/cmd/pub-add.md b/src/content/tools/pub/cmd/pub-add.md index b139e34ebc..44e0e276b4 100644 --- a/src/content/tools/pub/cmd/pub-add.md +++ b/src/content/tools/pub/cmd/pub-add.md @@ -220,7 +220,7 @@ To prevent precompilation, use `--no-precompile`. ## In a workspace -In a [Pub Workspace](/guides/packages#workspaces) `dart pub add` will add +In a [Pub workspace](/guides/workspaces) `dart pub add` will add dependencies only to the package in the current directory. {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-deps.md b/src/content/tools/pub/cmd/pub-deps.md index 590371087f..5776808ac3 100644 --- a/src/content/tools/pub/cmd/pub-deps.md +++ b/src/content/tools/pub/cmd/pub-deps.md @@ -82,5 +82,5 @@ Generates output in JSON format. ## In a workspace -In a [Pub Workspace](/guides/packages#workspaces) `dart pub deps` will list +In a [Pub workspace](/guides/workspaces) `dart pub deps` will list dependencies for all packages in the workspace, one workspace package at a time. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-downgrade.md b/src/content/tools/pub/cmd/pub-downgrade.md index ff791d5dc2..6f0e045bcd 100644 --- a/src/content/tools/pub/cmd/pub-downgrade.md +++ b/src/content/tools/pub/cmd/pub-downgrade.md @@ -123,5 +123,5 @@ Can be applied to [specific dependencies](#downgrading-specific-dependencies). ## In a workspace -In a [Pub Workspace](/guides/packages#workspaces) `dart pub downgrade` will +In a [Pub workspace](/guides/workspaces) `dart pub downgrade` will downgrade all dependencies across the workspace. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-lish.md b/src/content/tools/pub/cmd/pub-lish.md index 1c68422377..e998c117cb 100644 --- a/src/content/tools/pub/cmd/pub-lish.md +++ b/src/content/tools/pub/cmd/pub-lish.md @@ -50,5 +50,5 @@ to publish the second package immediately, by side-stepping client-side validati ## In a workspace -In a [Pub Workspace](/guides/packages#workspaces) `dart pub publish` publishes +In a [Pub workspace](/guides/workspaces) `dart pub publish` publishes the package in the current directory. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-outdated.md b/src/content/tools/pub/cmd/pub-outdated.md index ce53c6fa3c..48c857d0a6 100644 --- a/src/content/tools/pub/cmd/pub-outdated.md +++ b/src/content/tools/pub/cmd/pub-outdated.md @@ -235,7 +235,7 @@ To include up-to-date dependencies, use `--up-to-date`. ## In a workspace -In a [Pub Workspace](/guides/packages#workspaces) `dart pub outdated` lists +In a [Pub workspace](/guides/workspaces) `dart pub outdated` lists all dependencies {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-remove.md b/src/content/tools/pub/cmd/pub-remove.md index 041d323d80..cc7add11fc 100644 --- a/src/content/tools/pub/cmd/pub-remove.md +++ b/src/content/tools/pub/cmd/pub-remove.md @@ -41,7 +41,7 @@ To prevent precompilation, use `--no-precompile`. ## In a workspace -In a [Pub Workspace](/guides/packages#workspaces) `dart pub remove` removes +In a [Pub workspace](/guides/workspaces) `dart pub remove` removes dependencies from the package in the current directory. {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-upgrade.md b/src/content/tools/pub/cmd/pub-upgrade.md index 3f089373e4..953b8a75cd 100644 --- a/src/content/tools/pub/cmd/pub-upgrade.md +++ b/src/content/tools/pub/cmd/pub-upgrade.md @@ -161,7 +161,7 @@ and then all those packages are unlocked. ## In a workspace -In a [Pub Workspace](/guides/packages#workspaces) `dart pub upgrade` will +In a [Pub workspace](/guides/workspaces) `dart pub upgrade` will upgrade all dependencies in the shared resolution from across all workspace packages. diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md index 43763dad5e..eac3d780fc 100644 --- a/src/content/tools/pub/glossary.md +++ b/src/content/tools/pub/glossary.md @@ -317,5 +317,5 @@ The packages will have a shared `pubspec.lock` and a shared `.dart_tool/package_config.json`. For more information, read -[Pub Workspaces](/guides/workspaces). +[Pub workspace](/guides/workspaces). From d0940f6242d25fb7d63e9b39d5c5ddcabf28cdda Mon Sep 17 00:00:00 2001 From: Marya <111139605+MaryaBelanger@users.noreply.github.com> Date: Tue, 19 Nov 2024 13:50:21 -0800 Subject: [PATCH 30/38] Apply suggestions from code review --- src/content/guides/workspaces.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md index 0ed6f37dd4..6e744eefa7 100644 --- a/src/content/guides/workspaces.md +++ b/src/content/guides/workspaces.md @@ -44,7 +44,7 @@ of the same package. If the packages are going to be used together (as is commonly the case), this risk is a useful feature. It forces you to resolve incompatibilities between -your packages when they arise, rather then when you start using the packages. +your packages when they arise, rather than when you start using the packages. ::: To create a workspace: @@ -64,7 +64,7 @@ To create a workspace: - packages/server_package ``` -* For each of the existing `pubspec.yaml` filrd, make sure their SDK constraint +* For each of the existing `pubspec.yaml` files, make sure their SDK constraint is at least `^3.6.0` and add a `resolution` entry: ```yaml @@ -75,7 +75,7 @@ To create a workspace: * Run `dart pub get` anywhere in the repository. This will: * Create a single `pubspec.lock` next to the root `pubspec.yaml` that contains - the a resolution of all the `dependencies` and `dev_dependencies` of all the + the resolution of all the `dependencies` and `dev_dependencies` of all the workspace packages. * Create a single shared `.dart_tool/package_config.json` that maps package names to file locations. @@ -141,7 +141,7 @@ it's preferable to keep `dependency_overrides` in the root `pubspec.yaml`. ## Running a command in a specific workspace package Some pub commands, such as `dart pub add`, and `dart pub publish` operate on a -"current" package. You can either change directory, or use `-C` to point pub at +"current" package. You can either change the directory, or use `-C` to point pub at a directory: ```console From d017546363b1444795429412d226a2cab7b2dbec Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Tue, 26 Nov 2024 14:40:58 -0800 Subject: [PATCH 31/38] close loop on analysis context upside --- src/content/guides/workspaces.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md index 6e744eefa7..74095e74fb 100644 --- a/src/content/guides/workspaces.md +++ b/src/content/guides/workspaces.md @@ -32,10 +32,14 @@ There are some downsides to this setup: * You risk ending up with different versions of dependencies for each package, leading to confusion when context switching between the packages. * If you open the root folder in your IDE, the dart analyzer will have to have - separate analysis contexts for each package (increasing memory usage). + separate [analysis contexts][] for each package (increasing memory usage). Pub allows you to organize your repository as a _workspace_ using a single -shared resolution for all your packages. +shared resolution for all your packages. +A workspace also has a single analysis context, +saving memory usage and improving performance. + +[analysis contexts]: /resources/glossary#analysis-context :::note Using a single shared dependency resolution for all your packages increases From 32c2ffc0110fb5016e71b75eb5354fff6fdca9b9 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 3 Dec 2024 13:51:08 +0000 Subject: [PATCH 32/38] Add section about stray files --- firebase.json | 1 + src/content/guides/workspaces.md | 40 ++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) diff --git a/firebase.json b/firebase.json index ca279e848a..f36177c0bd 100644 --- a/firebase.json +++ b/firebase.json @@ -182,6 +182,7 @@ { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 }, { "source": "/go/macros", "destination": "/language/macros", "type": 301 }, { "source": "/go/pub-workspaces", "destination": "/guides/workspaces", "type": 301 }, + { "source": "/go/workspaces-stray-files", "destination": "/guides/workspaces#stray-files", "type": 301 }, { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 }, { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 }, { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 }, diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md index 74095e74fb..f38d455b61 100644 --- a/src/content/guides/workspaces.md +++ b/src/content/guides/workspaces.md @@ -109,6 +109,46 @@ To use pub workspaces, all your workspace packages (but not your dependencies) must have a SDK version constraint of `^3.6.0` or higher. ::: + +## Stray files + +When you are migrating an existing mono-repo to use Pub workspaces, there will +be existing "stray" `pubspec.lock` and `.dart_tool/package_config.json` files +adjacent to each pubspec. These would shadow the `pubspec.lock` and +`.dart_tool/package_config.json` placed next to the root + +Therefore `pub get` will delete any `pubspec.lock` and +`.dart_tool/package_config.json` located in directories between the root and +(including) any workspace package. + +``` +/ + pubspec.yaml # Root + packages/ + pubspec.lock # Deleted by `pub get` + .dart_tool/package_config.json # Deleted by `pub get` + foo/ + pubspec.yaml # Workspace member + pubspec.lock # Deleted by `pub get` + .dart_tool/package_config.json # Deleted by `pub get` +``` + +If any directory between the workspace root and a workspace package contains a +"stray" `pubspec.yaml` file that is not member of the workspace, `pub get` will +report an error and fail to resolve, as resolving such a `pubspec.yaml` would +create a `.dart_tool/package_config.json` file that shadows the one at the root. + +For example: +``` +/ + pubspec.yaml # Root `workspace: ['foo/']` + packages/ + pubspec.yaml # Not workspace member => error + foo/ + pubspec.yaml # Workspace member +``` + + ## Interdependencies between workspace packages If any of the workspace packages depend on each other, they will automatically From af90c075a42fa0605b3acac43f69a7cf530b04e0 Mon Sep 17 00:00:00 2001 From: Sigurd Meldgaard Date: Tue, 3 Dec 2024 13:52:01 +0000 Subject: [PATCH 33/38] Revert "Add section about stray files" This reverts commit 32c2ffc0110fb5016e71b75eb5354fff6fdca9b9. --- firebase.json | 1 - src/content/guides/workspaces.md | 40 -------------------------------- 2 files changed, 41 deletions(-) diff --git a/firebase.json b/firebase.json index f36177c0bd..ca279e848a 100644 --- a/firebase.json +++ b/firebase.json @@ -182,7 +182,6 @@ { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 }, { "source": "/go/macros", "destination": "/language/macros", "type": 301 }, { "source": "/go/pub-workspaces", "destination": "/guides/workspaces", "type": 301 }, - { "source": "/go/workspaces-stray-files", "destination": "/guides/workspaces#stray-files", "type": 301 }, { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 }, { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 }, { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 }, diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md index f38d455b61..74095e74fb 100644 --- a/src/content/guides/workspaces.md +++ b/src/content/guides/workspaces.md @@ -109,46 +109,6 @@ To use pub workspaces, all your workspace packages (but not your dependencies) must have a SDK version constraint of `^3.6.0` or higher. ::: - -## Stray files - -When you are migrating an existing mono-repo to use Pub workspaces, there will -be existing "stray" `pubspec.lock` and `.dart_tool/package_config.json` files -adjacent to each pubspec. These would shadow the `pubspec.lock` and -`.dart_tool/package_config.json` placed next to the root - -Therefore `pub get` will delete any `pubspec.lock` and -`.dart_tool/package_config.json` located in directories between the root and -(including) any workspace package. - -``` -/ - pubspec.yaml # Root - packages/ - pubspec.lock # Deleted by `pub get` - .dart_tool/package_config.json # Deleted by `pub get` - foo/ - pubspec.yaml # Workspace member - pubspec.lock # Deleted by `pub get` - .dart_tool/package_config.json # Deleted by `pub get` -``` - -If any directory between the workspace root and a workspace package contains a -"stray" `pubspec.yaml` file that is not member of the workspace, `pub get` will -report an error and fail to resolve, as resolving such a `pubspec.yaml` would -create a `.dart_tool/package_config.json` file that shadows the one at the root. - -For example: -``` -/ - pubspec.yaml # Root `workspace: ['foo/']` - packages/ - pubspec.yaml # Not workspace member => error - foo/ - pubspec.yaml # Workspace member -``` - - ## Interdependencies between workspace packages If any of the workspace packages depend on each other, they will automatically From 52de5815e02c39cfc7a2b301b1f57589b4e04eb2 Mon Sep 17 00:00:00 2001 From: Marya Belanger Date: Fri, 6 Dec 2024 14:30:16 -0800 Subject: [PATCH 34/38] remove mention of analysis contexts --- src/content/guides/workspaces.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/content/guides/workspaces.md b/src/content/guides/workspaces.md index 74095e74fb..0f5903bded 100644 --- a/src/content/guides/workspaces.md +++ b/src/content/guides/workspaces.md @@ -31,15 +31,13 @@ There are some downsides to this setup: * You need to run `dart pub get` once for each package. * You risk ending up with different versions of dependencies for each package, leading to confusion when context switching between the packages. -* If you open the root folder in your IDE, the dart analyzer will have to have - separate [analysis contexts][] for each package (increasing memory usage). +* If you open the root folder in your IDE, the dart analyzer will create + separate analysis contexts for each package, increasing memory usage. Pub allows you to organize your repository as a _workspace_ using a single shared resolution for all your packages. -A workspace also has a single analysis context, -saving memory usage and improving performance. - -[analysis contexts]: /resources/glossary#analysis-context +Using workspaces for large repositories reduces the amount of memory +required for analysis, hence improving performance. :::note Using a single shared dependency resolution for all your packages increases From 8d4ff0a74750cb282e1f6297959a715c80ef6b0e Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Wed, 11 Dec 2024 02:12:08 +0800 Subject: [PATCH 35/38] Move to pub directory --- firebase.json | 2 +- src/_data/side-nav.yml | 2 +- src/content/tools/pub/cmd/pub-add.md | 2 +- src/content/tools/pub/cmd/pub-deps.md | 2 +- src/content/tools/pub/cmd/pub-downgrade.md | 2 +- src/content/tools/pub/cmd/pub-lish.md | 2 +- src/content/tools/pub/cmd/pub-outdated.md | 2 +- src/content/tools/pub/cmd/pub-remove.md | 2 +- src/content/tools/pub/cmd/pub-upgrade.md | 2 +- src/content/tools/pub/glossary.md | 4 ++-- src/content/tools/pub/packages.md | 2 +- src/content/{guides => tools/pub}/workspaces.md | 0 12 files changed, 12 insertions(+), 12 deletions(-) rename src/content/{guides => tools/pub}/workspaces.md (100%) diff --git a/firebase.json b/firebase.json index 8055d132cb..74aab83c26 100644 --- a/firebase.json +++ b/firebase.json @@ -181,7 +181,7 @@ { "source": "/go/ffi", "destination": "/interop/c-interop", "type": 301 }, { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 }, { "source": "/go/macros", "destination": "/language/macros", "type": 301 }, - { "source": "/go/pub-workspaces", "destination": "/guides/workspaces", "type": 301 }, + { "source": "/go/pub-workspaces", "destination": "/tools/pub/workspaces", "type": 301 }, { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons#getter-name", "type": 301 }, { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons#field-name", "type": 301 }, { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons#nosuchmethod", "type": 301 }, diff --git a/src/_data/side-nav.yml b/src/_data/side-nav.yml index 73eb28a1b6..75272472b0 100644 --- a/src/_data/side-nav.yml +++ b/src/_data/side-nav.yml @@ -164,7 +164,7 @@ - title: Writing package pages permalink: /tools/pub/writing-package-pages - title: Workspaces (monorepo support) - permalink: /guides/workspaces + permalink: /tools/pub/workspaces - title: Package reference expanded: false children: diff --git a/src/content/tools/pub/cmd/pub-add.md b/src/content/tools/pub/cmd/pub-add.md index 44e0e276b4..a1d32e408f 100644 --- a/src/content/tools/pub/cmd/pub-add.md +++ b/src/content/tools/pub/cmd/pub-add.md @@ -220,7 +220,7 @@ To prevent precompilation, use `--no-precompile`. ## In a workspace -In a [Pub workspace](/guides/workspaces) `dart pub add` will add +In a [Pub workspace](/tools/pub/workspaces) `dart pub add` will add dependencies only to the package in the current directory. {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-deps.md b/src/content/tools/pub/cmd/pub-deps.md index 5776808ac3..c0d3deed01 100644 --- a/src/content/tools/pub/cmd/pub-deps.md +++ b/src/content/tools/pub/cmd/pub-deps.md @@ -82,5 +82,5 @@ Generates output in JSON format. ## In a workspace -In a [Pub workspace](/guides/workspaces) `dart pub deps` will list +In a [Pub workspace](/tools/pub/workspaces) `dart pub deps` will list dependencies for all packages in the workspace, one workspace package at a time. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-downgrade.md b/src/content/tools/pub/cmd/pub-downgrade.md index 6f0e045bcd..50a581a3cd 100644 --- a/src/content/tools/pub/cmd/pub-downgrade.md +++ b/src/content/tools/pub/cmd/pub-downgrade.md @@ -123,5 +123,5 @@ Can be applied to [specific dependencies](#downgrading-specific-dependencies). ## In a workspace -In a [Pub workspace](/guides/workspaces) `dart pub downgrade` will +In a [Pub workspace](/tools/pub/workspaces) `dart pub downgrade` will downgrade all dependencies across the workspace. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-lish.md b/src/content/tools/pub/cmd/pub-lish.md index 1eddbe58e6..c343963790 100644 --- a/src/content/tools/pub/cmd/pub-lish.md +++ b/src/content/tools/pub/cmd/pub-lish.md @@ -50,5 +50,5 @@ to publish the second package immediately, by side-stepping client-side validati ## In a workspace -In a [Pub workspace](/guides/workspaces) `dart pub publish` publishes +In a [Pub workspace](/tools/pub/workspaces) `dart pub publish` publishes the package in the current directory. \ No newline at end of file diff --git a/src/content/tools/pub/cmd/pub-outdated.md b/src/content/tools/pub/cmd/pub-outdated.md index 48c857d0a6..a8bf8a5417 100644 --- a/src/content/tools/pub/cmd/pub-outdated.md +++ b/src/content/tools/pub/cmd/pub-outdated.md @@ -235,7 +235,7 @@ To include up-to-date dependencies, use `--up-to-date`. ## In a workspace -In a [Pub workspace](/guides/workspaces) `dart pub outdated` lists +In a [Pub workspace](/tools/pub/workspaces) `dart pub outdated` lists all dependencies {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-remove.md b/src/content/tools/pub/cmd/pub-remove.md index cc7add11fc..d4e31c60f5 100644 --- a/src/content/tools/pub/cmd/pub-remove.md +++ b/src/content/tools/pub/cmd/pub-remove.md @@ -41,7 +41,7 @@ To prevent precompilation, use `--no-precompile`. ## In a workspace -In a [Pub workspace](/guides/workspaces) `dart pub remove` removes +In a [Pub workspace](/tools/pub/workspaces) `dart pub remove` removes dependencies from the package in the current directory. {% render 'pub-problems.md' %} diff --git a/src/content/tools/pub/cmd/pub-upgrade.md b/src/content/tools/pub/cmd/pub-upgrade.md index 953b8a75cd..3b10ffd2cf 100644 --- a/src/content/tools/pub/cmd/pub-upgrade.md +++ b/src/content/tools/pub/cmd/pub-upgrade.md @@ -161,7 +161,7 @@ and then all those packages are unlocked. ## In a workspace -In a [Pub workspace](/guides/workspaces) `dart pub upgrade` will +In a [Pub workspace](/tools/pub/workspaces) `dart pub upgrade` will upgrade all dependencies in the shared resolution from across all workspace packages. diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md index 5dcae7e9a0..02de85a716 100644 --- a/src/content/tools/pub/glossary.md +++ b/src/content/tools/pub/glossary.md @@ -316,6 +316,6 @@ their dependency constraints. Useful for developing in a monorepo. The packages will have a shared `pubspec.lock` and a shared `.dart_tool/package_config.json`. -For more information, read -[Pub workspace](/guides/workspaces). +For more information, check out +[Pub workspaces](/tools/pub/workspaces). diff --git a/src/content/tools/pub/packages.md b/src/content/tools/pub/packages.md index ec55cd8897..6019984918 100644 --- a/src/content/tools/pub/packages.md +++ b/src/content/tools/pub/packages.md @@ -271,7 +271,7 @@ the pub package manager. * [Creating packages](/tools/pub/create-packages) * [Publishing packages](/tools/pub/publishing) -* [Pub workspaces (monorepo support)](/guides/workspaces) +* [Pub workspaces (monorepo support)](/tools/pub/workspaces) ### Reference diff --git a/src/content/guides/workspaces.md b/src/content/tools/pub/workspaces.md similarity index 100% rename from src/content/guides/workspaces.md rename to src/content/tools/pub/workspaces.md From 2f5900c7ff0c670d8fb07caf6c4e5e7c55df8b6b Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Wed, 11 Dec 2024 02:13:48 +0800 Subject: [PATCH 36/38] Clean up glossary entry --- src/content/tools/pub/glossary.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/content/tools/pub/glossary.md b/src/content/tools/pub/glossary.md index 02de85a716..5c5f882e00 100644 --- a/src/content/tools/pub/glossary.md +++ b/src/content/tools/pub/glossary.md @@ -310,12 +310,11 @@ For more information, see ## Workspace -A collection of packages that are developed together with a shared resolution of -their dependency constraints. Useful for developing in a monorepo. +A collection of packages that are developed together with a +shared resolution of their dependency constraints. +Useful for developing in a monorepo. -The packages will have a shared `pubspec.lock` and a shared -`.dart_tool/package_config.json`. - -For more information, check out -[Pub workspaces](/tools/pub/workspaces). +The packages have a shared `pubspec.lock` and `.dart_tool/package_config.json`. +To learn more about setting up and developing in a workspace, +check out [Pub workspaces](/tools/pub/workspaces). From 3863c2f10fc7cf5a649dae92571b1f2df4e38d5a Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Wed, 11 Dec 2024 02:16:21 +0800 Subject: [PATCH 37/38] Minor formatting fixes to doc --- src/content/tools/pub/workspaces.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/tools/pub/workspaces.md b/src/content/tools/pub/workspaces.md index 0f5903bded..feb5251de5 100644 --- a/src/content/tools/pub/workspaces.md +++ b/src/content/tools/pub/workspaces.md @@ -9,7 +9,7 @@ version control repository (a _monorepo_). For example you might have a directory layout like: -```console +```plaintext / packages/ shared/ @@ -41,7 +41,7 @@ required for analysis, hence improving performance. :::note Using a single shared dependency resolution for all your packages increases -the risks of dependency conflicts, because Dart does not allow multiple versions +the risks of dependency conflicts, because Dart doesn't allow multiple versions of the same package. If the packages are going to be used together (as is commonly the case), @@ -52,7 +52,7 @@ your packages when they arise, rather than when you start using the packages. To create a workspace: * Add a `pubspec.yaml` at the repository root directory with a `workspace` entry - enummerating the paths to the packages of the respository (the workspace + enumerating the paths to the packages of the repository (the workspace packages): ```yaml @@ -86,7 +86,7 @@ To create a workspace: Now the file structure looks like this: -```console +```plaintext / packages/ shared/ @@ -101,10 +101,10 @@ Now the file structure looks like this: ``` :::version-note -Pub workspaces was introduced in Dart 3.6.0. +Support for pub workspaces was introduced in Dart 3.6.0. To use pub workspaces, all your workspace packages (but not your dependencies) -must have a SDK version constraint of `^3.6.0` or higher. +must have an SDK version constraint of `^3.6.0` or higher. ::: ## Interdependencies between workspace packages @@ -120,7 +120,7 @@ dependencies: ``` When resolved inside the workspace, the _local_ version of `shared` will be -used. +used. The local version of `shared` would still have to match the constraint (`^2.3.0`) though. From fc13a5f43102f3984b54ba5c9795314d0fe80910 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Wed, 11 Dec 2024 02:16:54 +0800 Subject: [PATCH 38/38] Add a /to/ link to the workspaces docs --- firebase.json | 1 + 1 file changed, 1 insertion(+) diff --git a/firebase.json b/firebase.json index 74aab83c26..71191663d9 100644 --- a/firebase.json +++ b/firebase.json @@ -375,6 +375,7 @@ { "source": "/to/doc-comment-references", "destination": "/tools/doc-comments/references", "type": 301 }, { "source": "/to/enforce-lockfile", "destination": "/tools/pub/packages#get-dependencies-for-production", "type": 301 }, { "source": "/to/main-function", "destination": "/language/functions#main", "type": 301 }, + { "source": "/to/pub-workspaces", "destination": "/tools/pub/workspaces", "type": 301 }, { "source": "/to/web-debug-extension", "destination": "https://chromewebstore.google.com/detail/dart-debug-extension/eljbmlghnomdjgdjmbdekegdkbabckhm", "type": 301 }, { "source": "/tools/**/download{,.html,/**}", "destination": "/get-dart", "type": 301 },