Towards https://github.com/flutter/flutter/issues/164315.
This PR just writes `bin/cache/engine.stamp` identically to how
`bin/internal/engine.version` would otherwise be written, with a caveat
that _if_ `engine.version` is tracked, it is now _copied_ to
`bin/cache/engine.stamp`.
After this lands, I'll send PRs to update tooling that looks for
`engine.version` and give a heads up to the larger team (i.e. Dart HH
bot or whomever we will break by doing this).
Towards https://github.com/flutter/flutter/issues/162201.
**NOTE**: This renames the environment variable to
`FLUTTER_PREBUILT_ENGINE_VERSION`.
---
We occasionally break ourselves, our users, and the Dart up (or is it
down? side-ways) stream repos (i.e. HHH) when we change how the
undocumented
[`update_engine_version.sh`](https://github.com/flutter/flutter/blob/master/bin/internal/update_engine_version.sh)
script, and it's Windows counterpart
[`update_engine_version.ps1`](https://github.com/flutter/flutter/blob/master/bin/internal/update_engine_version.ps1)
work, but have no way of knowing until N days/weeks later when someone
tells us.
For example,
<https://flutter-review.googlesource.com/c/recipes/+/62400>.
This is my attempt to encode "this is what you can guarantee by calling
this script".
It _still_ will be an internal only API that we might rev at any time,
but at least we:
1. Can tell the Dart team "this is tested and how it works"
2. If we want to change it, the tests will keep us from changing it
without informing folks it changed
These tests should (in theory) cover both Linux/MacOS and Windows.
/cc @a-siva
This auto-formats all *.dart files in the repository outside of the
`engine` subdirectory and enforces that these files stay formatted with
a presubmit check.
**Reviewers:** Please carefully review all the commits except for the
one titled "formatted". The "formatted" commit was auto-generated by
running `dev/tools/format.sh -a -f`. The other commits were hand-crafted
to prepare the repo for the formatting change. I recommend reviewing the
commits one-by-one via the "Commits" tab and avoiding Github's "Files
changed" tab as it will likely slow down your browser because of the
size of this PR.
---------
Co-authored-by: Kate Lovett <katelovett@google.com>
Co-authored-by: LongCatIsLooong <31859944+LongCatIsLooong@users.noreply.github.com>
This applied the improvements from
https://github.com/flutter/engine/pull/57206 to the flutter/flutter
version of that script (hopefully, we can deduplicate this soon with the
repo merge).
The script is modeled after a similar script in the engine (see engine's
[format.dart](https://github.com/flutter/engine/blob/main/ci/bin/format.dart)).
It identifies the files that have been changed and checks if their
formatting is correct. It also offers an option to correct formatting
(`--fix`) and an option to check the formatting of all files in the
repro (not just changed ones, `--all-files`).
When we are enforcing dart format this script will be called as part of
presubmit.
Useful in tooling, releases, etc - where Dart is available
Example usages:
```bash
# Monorepo world
❯ dart ./dev/tools/bin/engine_hash.dart -s head
226e13826c7253c968d798666f323b1f207979f8
# Non-monorepo world
❯ dart ./dev/tools/bin/engine_hash.dart -s head
Error calculating engine hash: Not in a monorepo
```
## Description
This adds a fake dependency to the docs generation for the `flutter_gpu` package so that it will be included in the docs even though Flutter itself doesn't depend on it directly.
## Related Issues
- Fixes https://github.com/flutter/flutter/issues/153320
## Tests
- Adding a test to the canary files that the docs generation script looks for. (Not yet added: still draft)
Fix is in the second commit. The logic here went out of sync with the logic in the snippets generator from https://github.com/flutter/assets-for-api-docs, whose version was bumped as part of this change.
Reverts flutter/flutter#144329
Initiated by: goderbauer
Reason for reverting: broke postsubmit doc generation.
Original PR Author: goderbauer
Reviewed By: {devoncarew, HansMuller, gspencergoog}
This change reverts the following previous change:
Original Description:
Dartpad doesn't have a "master" channel anymore, it got renamed to "main". Sadly, specifying "master" is now falling back to "stable" which breaks some of our examples in the docs that require a more current Flutter version, e.g. https://main-api.flutter.dev/flutter/material/TextButton-class.html
Dartpad doesn't have a "master" channel anymore, it got renamed to "main". Sadly, specifying "master" is now falling back to "stable" which breaks some of our examples in the docs that require a more current Flutter version, e.g. https://main-api.flutter.dev/flutter/material/TextButton-class.html
Part of work on [#101077](https://github.com/flutter/flutter/pull/141194). This is done as a separate PR to avoid a massive diff.
## Context
1. The `FakeCommand` class accepts a list of patterns that's used to match a command given to its `FakeProcessManager`. Since `FakeCommand` can match a list of patterns, not just specifically strings, it can be used to match commands where the exact value of some arguments can't (easily) known ahead of time. For example, a part of the tool may invoke a command with an argument that is the path of a temporarily file that has a randomly-generated basename.
2. The `FakeCommand` class provides on `onRun` parameter, which is a callback that is run when the `FakeProcessManager` runs a command that matches the `FakeCommand` in question.
## Issue
In the event that a `FakeCommand` is constructed using patterns, the test code can't know the exact values used for arguments in the command. This PR proposes changing the type of `onRun` from `VoidCallback?` to `void Function(List<String>)?`. When run, the value `List<String>` parameter will be the full command that the `FakeCommand` matched.
Example:
```dart
FakeCommand(
command: <Pattern>[
artifacts.getArtifactPath(Artifact.engineDartBinary),
'run',
'vector_graphics_compiler',
RegExp(r'--input=/.*\.temp'),
RegExp(r'--output=/.*\.temp'),
],
onRun: (List<String> command) {
final outputPath = (() {
// code to parse `--output` from `command`
})();
testFileSystem.file(outputPath).createSync(recursive: true);
},
)
```
## Description
This re-lands #132353 with some additional options for keeping around the staging directory, so that the recipe for publishing docs can give those options and have the staging directory left around for deploying to the website.
Reverted in #132613
## Related Issues
- https://flutter-review.googlesource.com/c/recipes/+/49580
## Description
This cleans up a lot of issues with the API doc generation.
Here are the main changes:
- Rename `dartdoc.dart` to `create_api_docs.dart`
- Move the bulk of the operations out of `dev/bots/docs.sh` into `create_api_docs.dart`.
- Delete `dashing_postprocess.dart` and `java_and_objc.dart` and incorporate those operations into `create_api_docs.dart`.
- Refactor the doc generation into more understandable classes
- Bump the snippets tool version to 0.4.0 (the latest one)
- Centralize the information gathering about the Flutter repo into the new `FlutterInformation` class.
- Clean up the directory handling, and convert to using the `file` package for all file and directory paths.
- Add an `--output` option to docs.sh that specifies the location of the output ZIP file containing the docs.
- Defaults to placing the output in `dev/docs/api_docs.zip` (i.e. where the previous code generates the file).
- Moved all document generation into a temporary folder that is removed once the documents are generated, to avoid VSCode and other IDEs trying to index the thousands of HTML and JS files in the docs output.
- Updated pubspec dependencies.
## Tests
- Added tests for doc generation.
