This is a set of utilities used in the flutter/plugins and flutter/packages repositories. It is no longer explictily maintained as a general-purpose tool for multi-package repositories, so your mileage may vary if using it in other repositories.
Note: The commands in tools are designed to run at the root of the repository or <repository-root>/packages/
.
In flutter/plugins, the tool is run from source. In flutter/packages, the published version is used instead. (It is marked as Discontinued since it is no longer maintained as a general-purpose tool, but updates are still published for use in flutter/packages.)
The commands in tools require the Flutter-bundled version of Dart to be the first dart
loaded in the path.
When updating sample code excerpts (update-excerpts
) for the README.md files,
there is some extra setup for
submodules that is necessary.
Set up:
cd ./script/tool && dart pub get && cd ../../
Run:
dart run ./script/tool/bin/flutter_plugin_tools.dart <args>
Set up:
dart pub global activate flutter_plugin_tools
Run:
dart pub global run flutter_plugin_tools <args>
Run with --help
for a full list of commands and arguments, but the
following shows a number of common commands being run for a specific package.
All examples assume running from source; see above for running the published version instead.
Most commands take a --packages
argument to control which package(s) the
command is targetting. An package name can be any of:
- The name of a package (e.g.,
path_provider_android
). - The name of a federated plugin (e.g.,
path_provider
), in which case all packages that make up that plugin will be targetted. - A combination federated_plugin_name/package_name (e.g.,
path_provider/path_provider
for the app-facing package).
cd <repository root>
dart run ./script/tool/bin/flutter_plugin_tools.dart format --packages package_name
cd <repository root>
dart run ./script/tool/bin/flutter_plugin_tools.dart analyze --packages package_name
cd <repository root>
dart run ./script/tool/bin/flutter_plugin_tools.dart test --packages package_name
cd <repository root>
dart run ./script/tool/bin/flutter_plugin_tools.dart build-examples --apk --packages package_name
dart run ./script/tool/bin/flutter_plugin_tools.dart drive-examples --android --packages package_name
Replace --apk
/--android
with the platform you want to test against
(omit it to get a list of valid options).
native-test
takes one or more platform flags to run tests for. By default it
runs both unit tests and (on platforms that support it) integration tests, but
--no-unit
or --no-integration
can be used to run just one type.
Examples:
cd <repository root>
# Run just unit tests for iOS and Android:
dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --ios --android --no-integration --packages package_name
# Run all tests for macOS:
dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --macos --packages package_name
# Run all tests for Windows:
dart run ./script/tool/bin/flutter_plugin_tools.dart native-test --windows --packages package_name
update-excerpts
requires sources that are in a submodule. If you didn't clone
with submodules, you will need to git submodule update --init --recursive
before running this command.
cd <repository root>
dart run ./script/tool/bin/flutter_plugin_tools.dart update-excerpts --packages package_name
update-release-info
will automatically update the version and CHANGELOG.md
following standard repository style and practice. It can be used for
single-package updates to handle the details of getting the CHANGELOG.md
format correct, but is especially useful for bulk updates across multiple packages.
For instance, if you add a new analysis option that requires production code changes across many packages:
cd <repository root>
dart run ./script/tool/bin/flutter_plugin_tools.dart update-release-info \
--version=minimal \
--changelog="Fixes violations of new analysis option some_new_option."
The minimal
option for --version
will skip unchanged packages, and treat
each changed package as either bugfix
or next
depending on the files that
have changed in that package, so it is often the best choice for a bulk change.
For cases where you know the change time, minor
or bugfix
will make the
corresponding version bump, or next
will update only CHANGELOG.md
without
changing the version.
Releases are automated for flutter/plugins
and flutter/packages
.
The manual procedure described here is deprecated, and should only be used when the automated process fails. Please, read Releasing a Plugin or Package on the Flutter Wiki first.
cd <path_to_plugins>
git checkout <commit_hash_to_publish>
dart run ./script/tool/bin/flutter_plugin_tools.dart publish --packages <package>
By default the tool tries to push tags to the upstream
remote, but some
additional settings can be configured. Run dart run ./script/tool/bin/flutter_plugin_tools.dart publish --help
for more usage information.
The tool wraps pub publish
for pushing the package to pub, and then will
automatically use git to try to create and push tags. It has some additional
safety checking around pub publish
too. By default pub publish
publishes
everything, including untracked or uncommitted files in version control.
publish
will first check the status of the local
directory and refuse to publish if there are any mismatched files with version
control present.
For flutter/plugins, just changing the source here is all that's needed.
For changes that are relevant to flutter/packages, you will also need to:
- Update the tool's pubspec.yaml and CHANGELOG
- Publish the tool
- Update the pinned version in flutter/packages