|
1 |
| -# Flutter Plugin Tools |
| 1 | +# Removed |
2 | 2 |
|
3 |
| -This is a set of utilities used in the flutter/plugins and flutter/packages |
4 |
| -repositories. It is no longer explictily maintained as a general-purpose tool |
5 |
| -for multi-package repositories, so your mileage may vary if using it in other |
6 |
| -repositories. |
| 3 | +See https://github.com/flutter/packages/blob/main/script/tool/README.md for the |
| 4 | +current location of this tooling. |
7 | 5 |
|
8 |
| -Note: The commands in tools are designed to run at the root of the repository or `<repository-root>/packages/`. |
| 6 | +## Temporary shim |
9 | 7 |
|
10 |
| -## Getting Started |
| 8 | +This is a temporary, minimal version of the tools sufficient to keep the |
| 9 | +following scripts running until the repository merge is complete and they are |
| 10 | +updated to use flutter/packages instead: |
11 | 11 |
|
12 |
| -In flutter/plugins, the tool is run from source. In flutter/packages, the |
13 |
| -[published version](https://pub.dev/packages/flutter_plugin_tools) is used |
14 |
| -instead. (It is marked as Discontinued since it is no longer maintained as |
15 |
| -a general-purpose tool, but updates are still published for use in |
16 |
| -flutter/packages.) |
17 |
| - |
18 |
| -The commands in tools require the Flutter-bundled version of Dart to be the first `dart` loaded in the path. |
19 |
| - |
20 |
| -### Extra Setup |
21 |
| - |
22 |
| -When updating sample code excerpts (`update-excerpts`) for the README.md files, |
23 |
| -there is some [extra setup for |
24 |
| -submodules](#update-readmemd-from-example-sources) that is necessary. |
25 |
| - |
26 |
| -### From Source (flutter/plugins only) |
27 |
| - |
28 |
| -Set up: |
29 |
| - |
30 |
| -```sh |
31 |
| -cd ./script/tool && dart pub get && cd ../../ |
32 |
| -``` |
33 |
| - |
34 |
| -Run: |
35 |
| - |
36 |
| -```sh |
37 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart <args> |
38 |
| -``` |
39 |
| - |
40 |
| -### Published Version |
41 |
| - |
42 |
| -Set up: |
43 |
| - |
44 |
| -```sh |
45 |
| -dart pub global activate flutter_plugin_tools |
46 |
| -``` |
47 |
| - |
48 |
| -Run: |
49 |
| - |
50 |
| -```sh |
51 |
| -dart pub global run flutter_plugin_tools <args> |
52 |
| -``` |
53 |
| - |
54 |
| -## Commands |
55 |
| - |
56 |
| -Run with `--help` for a full list of commands and arguments, but the |
57 |
| -following shows a number of common commands being run for a specific package. |
58 |
| - |
59 |
| -All examples assume running from source; see above for running the |
60 |
| -published version instead. |
61 |
| - |
62 |
| -Most commands take a `--packages` argument to control which package(s) the |
63 |
| -command is targetting. An package name can be any of: |
64 |
| -- The name of a package (e.g., `path_provider_android`). |
65 |
| -- The name of a federated plugin (e.g., `path_provider`), in which case all |
66 |
| - packages that make up that plugin will be targetted. |
67 |
| -- A combination federated_plugin_name/package_name (e.g., |
68 |
| - `path_provider/path_provider` for the app-facing package). |
69 |
| - |
70 |
| -### Format Code |
71 |
| - |
72 |
| -```sh |
73 |
| -cd <repository root> |
74 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart format --packages package_name |
75 |
| -``` |
76 |
| - |
77 |
| -### Run the Dart Static Analyzer |
78 |
| - |
79 |
| -```sh |
80 |
| -cd <repository root> |
81 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart analyze --packages package_name |
82 |
| -``` |
83 |
| - |
84 |
| -### Run Dart Unit Tests |
85 |
| - |
86 |
| -```sh |
87 |
| -cd <repository root> |
88 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart test --packages package_name |
89 |
| -``` |
90 |
| - |
91 |
| -### Run Dart Integration Tests |
92 |
| - |
93 |
| -```sh |
94 |
| -cd <repository root> |
95 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart build-examples --apk --packages package_name |
96 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart drive-examples --android --packages package_name |
97 |
| -``` |
98 |
| - |
99 |
| -Replace `--apk`/`--android` with the platform you want to test against |
100 |
| -(omit it to get a list of valid options). |
101 |
| - |
102 |
| -### Run Native Tests |
103 |
| - |
104 |
| -`native-test` takes one or more platform flags to run tests for. By default it |
105 |
| -runs both unit tests and (on platforms that support it) integration tests, but |
106 |
| -`--no-unit` or `--no-integration` can be used to run just one type. |
107 |
| - |
108 |
| -Examples: |
109 |
| - |
110 |
| -```sh |
111 |
| -cd <repository root> |
112 |
| -# Run just unit tests for iOS and Android: |
113 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --ios --android --no-integration --packages package_name |
114 |
| -# Run all tests for macOS: |
115 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --macos --packages package_name |
116 |
| -# Run all tests for Windows: |
117 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --windows --packages package_name |
118 |
| -``` |
119 |
| - |
120 |
| -### Update README.md from Example Sources |
121 |
| - |
122 |
| -`update-excerpts` requires sources that are in a submodule. If you didn't clone |
123 |
| -with submodules, you will need to `git submodule update --init --recursive` |
124 |
| -before running this command. |
125 |
| - |
126 |
| -```sh |
127 |
| -cd <repository root> |
128 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart update-excerpts --packages package_name |
129 |
| -``` |
130 |
| - |
131 |
| -### Update CHANGELOG and Version |
132 |
| - |
133 |
| -`update-release-info` will automatically update the version and `CHANGELOG.md` |
134 |
| -following standard repository style and practice. It can be used for |
135 |
| -single-package updates to handle the details of getting the `CHANGELOG.md` |
136 |
| -format correct, but is especially useful for bulk updates across multiple packages. |
137 |
| - |
138 |
| -For instance, if you add a new analysis option that requires production |
139 |
| -code changes across many packages: |
140 |
| - |
141 |
| -```sh |
142 |
| -cd <repository root> |
143 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart update-release-info \ |
144 |
| - --version=minimal \ |
145 |
| - --changelog="Fixes violations of new analysis option some_new_option." |
146 |
| -``` |
147 |
| - |
148 |
| -The `minimal` option for `--version` will skip unchanged packages, and treat |
149 |
| -each changed package as either `bugfix` or `next` depending on the files that |
150 |
| -have changed in that package, so it is often the best choice for a bulk change. |
151 |
| - |
152 |
| -For cases where you know the change time, `minor` or `bugfix` will make the |
153 |
| -corresponding version bump, or `next` will update only `CHANGELOG.md` without |
154 |
| -changing the version. |
155 |
| - |
156 |
| -### Publish a Release |
157 |
| - |
158 |
| -**Releases are automated for `flutter/plugins` and `flutter/packages`.** |
159 |
| - |
160 |
| -The manual procedure described here is _deprecated_, and should only be used when |
161 |
| -the automated process fails. Please, read |
162 |
| -[Releasing a Plugin or Package](https://github.com/flutter/flutter/wiki/Releasing-a-Plugin-or-Package) |
163 |
| -on the Flutter Wiki first. |
164 |
| - |
165 |
| -```sh |
166 |
| -cd <path_to_plugins> |
167 |
| -git checkout <commit_hash_to_publish> |
168 |
| -dart run ./script/tool/bin/flutter_plugin_tools.dart publish --packages <package> |
169 |
| -``` |
170 |
| - |
171 |
| -By default the tool tries to push tags to the `upstream` remote, but some |
172 |
| -additional settings can be configured. Run `dart run ./script/tool/bin/flutter_plugin_tools.dart |
173 |
| -publish --help` for more usage information. |
174 |
| - |
175 |
| -The tool wraps `pub publish` for pushing the package to pub, and then will |
176 |
| -automatically use git to try to create and push tags. It has some additional |
177 |
| -safety checking around `pub publish` too. By default `pub publish` publishes |
178 |
| -_everything_, including untracked or uncommitted files in version control. |
179 |
| -`publish` will first check the status of the local |
180 |
| -directory and refuse to publish if there are any mismatched files with version |
181 |
| -control present. |
182 |
| - |
183 |
| -## Updating the Tool |
184 |
| - |
185 |
| -For flutter/plugins, just changing the source here is all that's needed. |
186 |
| - |
187 |
| -For changes that are relevant to flutter/packages, you will also need to: |
188 |
| -- Update the tool's pubspec.yaml and CHANGELOG |
189 |
| -- Publish the tool |
190 |
| -- Update the pinned version in |
191 |
| - [flutter/packages](https://github.com/flutter/packages/blob/main/.cirrus.yml) |
| 12 | +- [dart-lang analysis](https://github.com/dart-lang/sdk/blob/main/tools/bots/flutter/analyze_flutter_plugins.sh) |
| 13 | +- [flutter/flutter analysis](https://github.com/flutter/flutter/blob/master/dev/bots/test.dart) |
0 commit comments