mirror of
https://github.com/flutter/flutter.git
synced 2025-06-03 00:51:18 +00:00
Fix markdown hyperlinks in the style guide (#150071)
Some of the syntax in the migrated [style guide](14df7be3f9/docs/contributing/Style-guide-for-Flutter-repo.md (lazy-programming)) (and "workarounds for common issues") doesn't show up super well as a `.md` file on GitHub. (related: #145009) <br> #### Current > You may hear team members say "embrace the http://www.catb.org/jargon/html/Y/yak-shaving.html[yak shave]!". This is an encouragement to https://www.youtube.com/watch?v=AbSehcT19u0[take on the larger effort necessary] to perform a proper fix for a problem rather than just applying a band-aid. #### This PR > You may hear team members say "embrace the [yak shave](http://www.catb.org/jargon/html/Y/yak-shaving.html)!". This is an encouragement to [take on the larger effort necessary](https://www.youtube.com/watch?v=AbSehcT19u0) to perform a proper fix for a problem rather than just applying a band-aid. <br> Workarounds-for-common-issues.md: [**before**](14df7be3f9/docs/wiki_archive/Workarounds-for-common-issues.md) / [**after**](c8d84a71b7/docs/wiki_archive/Workarounds-for-common-issues.md)
This commit is contained in:
Nate Wilson
GitHub
parent
0d5bf0f548
commit
a8f903223b
@ -17,7 +17,7 @@ project (the framework itself and all our sample code). Flutter application deve
|
||||
are welcome to follow this style as well, but this is by no means required. Flutter
|
||||
will work regardless of what style is used to author applications that use it.
|
||||
|
||||
The engine repository uses https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style[other style guides for non-Dart code]. The language-neutral sections in this document still apply to engine code, however.
|
||||
The engine repository uses [other style guides for non-Dart code](https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style). The language-neutral sections in this document still apply to engine code, however.
|
||||
|
||||
|
||||
## Overview
|
||||
@ -35,7 +35,7 @@ likelihood of catching bugs quickly, and avoiding arguments when there are
|
||||
disagreements over subjective matters.
|
||||
|
||||
For anything not covered by this document, check the
|
||||
https://www.dartlang.org/guides/language/effective-dart/[Dart style guide]
|
||||
[Dart style guide](https://www.dartlang.org/guides/language/effective-dart/)
|
||||
for more advice. That document is focused primarily on Dart-specific
|
||||
conventions, while this document is more about Flutter conventions.
|
||||
|
||||
@ -84,9 +84,8 @@ that now use it), _and_ implement the feature. It's much better to
|
||||
take longer to fix a problem properly, than to be the one who fixes
|
||||
everything quickly but in a way that will require cleaning up later.
|
||||
|
||||
You may hear team members say "embrace the http://www.catb.org/jargon/html/Y/yak-shaving.html[yak
|
||||
shave]!". This is
|
||||
an encouragement to https://www.youtube.com/watch?v=AbSehcT19u0[take on the larger effort necessary] to perform a
|
||||
You may hear team members say "embrace the [yak shave](http://www.catb.org/jargon/html/Y/yak-shaving.html)!". This is
|
||||
an encouragement to [take on the larger effort necessary](https://www.youtube.com/watch?v=AbSehcT19u0) to perform a
|
||||
proper fix for a problem rather than just applying a band-aid.
|
||||
|
||||
|
||||
@ -217,7 +216,7 @@ features that are unique to one platform or another are unavailable.
|
||||
For Flutter, we want to avoid this by explicitly aiming to be the best way
|
||||
to develop for each platform individually. Our ability to be used cross-
|
||||
platform is secondary to our ability to be used on each platform. For example,
|
||||
https://master-api.flutter.dev/flutter/services/TextInputAction-class.html[TextInputAction]
|
||||
[TextInputAction](https://master-api.flutter.dev/flutter/services/TextInputAction-class.html)
|
||||
has values that only make sense on some platforms. Similarly, our platform
|
||||
channel mechanism is designed to allow separate extensions to be created on
|
||||
each platform.
|
||||
@ -364,13 +363,13 @@ widget for that rather than updating the existing buttons to have the new style.
|
||||
|
||||
### Code that is not copyrighted "The Flutter Authors"
|
||||
|
||||
All code in all Flutter repositories must be contributed by developers who have signed https://cla.developers.google.com/[the Google CLA], and must be licensed using our normal BSD license with a copyright referencing "The Flutter Authors", except if it is "third party code".
|
||||
All code in all Flutter repositories must be contributed by developers who have signed [the Google CLA](https://cla.developers.google.com/), and must be licensed using our normal BSD license with a copyright referencing "The Flutter Authors", except if it is "third party code".
|
||||
|
||||
"Third party code" that is not part of a Dart package must be in a subdirectory of a `third_party` directory at the root of the relevant repository, and the subdirectory in question must contain a `LICENSE` file that details the license covering that code and a `README` describing the provenance of that code.
|
||||
|
||||
"Third party code" that is part of a Dart package and is not Dart code must be in a subdirectory of a `third_party` directory at the root of the package, and the subdirectory in question must contain a `LICENSE` file that details the license covering that code and a `README` describing the provenance of that code. The license must then also be duplicated into the package's `LICENSE` file using the syntax described in the https://master-api.flutter.dev/flutter/foundation/LicenseRegistry-class.html[LicenseRegistry] API docs.
|
||||
"Third party code" that is part of a Dart package and is not Dart code must be in a subdirectory of a `third_party` directory at the root of the package, and the subdirectory in question must contain a `LICENSE` file that details the license covering that code and a `README` describing the provenance of that code. The license must then also be duplicated into the package's `LICENSE` file using the syntax described in the [LicenseRegistry](https://master-api.flutter.dev/flutter/foundation/LicenseRegistry-class.html) API docs.
|
||||
|
||||
"Third party code" that is part of a Dart package and is Dart code must be in a subdirectory of the package's `lib/src/third_party` directory, and the subdirectory in question must contain a `LICENSE` file that details the license covering that code and a `README` describing the provenance of that code. The license must then also be duplicated into the package's `LICENSE` file using the syntax described in the https://master-api.flutter.dev/flutter/foundation/LicenseRegistry-class.html[LicenseRegistry] API docs.
|
||||
"Third party code" that is part of a Dart package and is Dart code must be in a subdirectory of the package's `lib/src/third_party` directory, and the subdirectory in question must contain a `LICENSE` file that details the license covering that code and a `README` describing the provenance of that code. The license must then also be duplicated into the package's `LICENSE` file using the syntax described in the [LicenseRegistry](https://master-api.flutter.dev/flutter/foundation/LicenseRegistry-class.html) API docs.
|
||||
|
||||
All licenses included in this manner must have been reviewed and determined to be legally acceptable licenses.
|
||||
|
||||
@ -386,7 +385,7 @@ of our APIs in other languages, such as ObjectiveC and Java. All public members
|
||||
libraries should have a documentation.
|
||||
|
||||
In general, follow the
|
||||
https://www.dartlang.org/effective-dart/documentation/#doc-comments[Dart documentation guide]
|
||||
[Dart documentation guide](https://www.dartlang.org/effective-dart/documentation/#doc-comments)
|
||||
except where that would contradict this page.
|
||||
|
||||
### Answer your own questions straight away
|
||||
@ -422,7 +421,7 @@ Avoid checking in such documentation, because it is no better than no
|
||||
documentation but will prevent us from noticing that the identifier is
|
||||
not actually documented.
|
||||
|
||||
Example (from http://docs.flutter.io/flutter/material/CircleAvatar-class.html[`CircleAvatar`]):
|
||||
Example (from [`CircleAvatar`](http://docs.flutter.io/flutter/material/CircleAvatar-class.html)):
|
||||
|
||||
```dart
|
||||
// BAD:
|
||||
@ -606,15 +605,15 @@ By definition, if they are looking at the documentation, they are not finding it
|
||||
|
||||
Sample code helps developers learn your API quickly. Writing sample code also helps you think through how your API is going to be used by app developers.
|
||||
|
||||
Sample code should go in a documentation comment that typically begins with `/// {@tool dartpad}`, and ends with `/// {@end-tool}`, with the example source and corresponding tests placed in a file under https://github.com/flutter/flutter/blob/main/examples/api[the API examples directory]. This will then be checked by automated tools, and formatted for display on the API documentation web site https://api.flutter.dev[api.flutter.dev]. For details on how to write sample code, see https://github.com/flutter/flutter/blob/main/examples/api/README.md#authoring[the API example documentation].
|
||||
Sample code should go in a documentation comment that typically begins with `/// {@tool dartpad}`, and ends with `/// {@end-tool}`, with the example source and corresponding tests placed in a file under [the API examples directory](https://github.com/flutter/flutter/blob/main/examples/api). This will then be checked by automated tools, and formatted for display on the API documentation web site [api.flutter.dev](https://api.flutter.dev). For details on how to write sample code, see [the API example documentation](https://github.com/flutter/flutter/blob/main/examples/api/README.md#authoring).
|
||||
|
||||
#### Provide full application samples.
|
||||
|
||||
Our UX research has shown that developers prefer to see examples that are in the context of an entire app. So, whenever it makes sense, provide an example that can be presented as part of an entire application instead of just a snippet that uses the `{@tool snippet}` or ```dart ... ``` indicators.
|
||||
|
||||
An application sample can be created using the `{@tool dartpad}` ... `{@end-tool}` or `{@tool sample}` ... `{@end-tool}` dartdoc indicators. See https://github.com/flutter/flutter/blob/main/examples/api/README.md#authoring[here] for more details about writing these kinds of examples.
|
||||
An application sample can be created using the `{@tool dartpad}` ... `{@end-tool}` or `{@tool sample}` ... `{@end-tool}` dartdoc indicators. See [here](https://github.com/flutter/flutter/blob/main/examples/api/README.md#authoring) for more details about writing these kinds of examples.
|
||||
|
||||
Dartpad examples (those using the dartdoc `{@tool dartpad}` indicator) will be presented on the https://api.flutter.dev[API documentation website] as an in-page executable and editable example. This allows developers to interact with the example right there on the page, and is the preferred form of example. Here is https://api.flutter.dev/flutter/widgets/AnimatedSwitcher-class.html#widgets.AnimatedSwitcher.1[one such example].
|
||||
Dartpad examples (those using the dartdoc `{@tool dartpad}` indicator) will be presented on the [API documentation website](https://api.flutter.dev) as an in-page executable and editable example. This allows developers to interact with the example right there on the page, and is the preferred form of example. Here is [one such example](https://api.flutter.dev/flutter/widgets/AnimatedSwitcher-class.html#widgets.AnimatedSwitcher.1).
|
||||
|
||||
For examples that don't make sense in a web page (for example, code that interacts with a particular platform feature), application examples (using the dartdoc `{@tool sample}` indicator) are preferred, and will be presented on the API documentation website along with information about how to instantiate the example as an application that can be run.
|
||||
|
||||
@ -628,14 +627,14 @@ Examples:
|
||||
|
||||
* A diagram for the AppBar widget
|
||||
|
||||
image::https://flutter.github.io/assets-for-api-docs/assets/material/app_bar.png[]
|
||||
|
||||
|
||||
|
||||
* A screenshot for the Card widget
|
||||
|
||||
image::https://user-images.githubusercontent.com/348942/28338544-2c3681b8-6bbe-11e7-967d-fcd7c830bf53.png[]
|
||||
|
||||
|
||||
When creating diagrams, make sure to provide alternative text https://html.spec.whatwg.org/multipage/images.html#alt[as described in the HTML specification].
|
||||
When creating diagrams, make sure to provide alternative text [as described in the HTML specification](https://html.spec.whatwg.org/multipage/images.html#alt).
|
||||
|
||||
|
||||
### Link to Widget of the Week videos
|
||||
@ -711,7 +710,7 @@ The first paragraph of any dartdoc section must be a short self-contained senten
|
||||
and meaning of the item being documented. Subsequent paragraphs then must elaborate. Avoid having the first paragraph have multiple sentences. (This is because the first paragraph gets extracted and used in tables of
|
||||
contents, etc, and so has to be able to stand alone and not take up a lot of room.)
|
||||
|
||||
When referencing a parameter, use backticks. However, when referencing a parameter that also corresponds to a property, use square brackets instead. (This contradicts the Dart style guide, which says to use square brackets for both. We do this because of https://github.com/dart-lang/dartdoc/issues/1486[dartdoc issue 1486]. Currently, there's no way to unambiguously reference a parameter. We want to avoid cases where a parameter that happens to be named the same as a property despite having no relationship to that property gets linked to the property.)
|
||||
When referencing a parameter, use backticks. However, when referencing a parameter that also corresponds to a property, use square brackets instead. (This contradicts the Dart style guide, which says to use square brackets for both. We do this because of [dartdoc issue 1486](https://github.com/dart-lang/dartdoc/issues/1486). Currently, there's no way to unambiguously reference a parameter. We want to avoid cases where a parameter that happens to be named the same as a property despite having no relationship to that property gets linked to the property.)
|
||||
|
||||
```dart
|
||||
// GOOD
|
||||
@ -794,7 +793,7 @@ global constant.
|
||||
|
||||
As a general rule, when you have a lot of constants, wrap them in a
|
||||
class. For examples of this, see
|
||||
https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/material/colors.dart[lib/src/material/colors.dart].
|
||||
[lib/src/material/colors.dart](https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/material/colors.dart).
|
||||
|
||||
|
||||
### Avoid using `if` chains or `?:` or `==` with enum values
|
||||
@ -867,7 +866,7 @@ Expando objects tend to invite code that is hard to understand because one canno
|
||||
|
||||
### Avoid using `@visibleForTesting`
|
||||
|
||||
The https://api.flutter.dev/flutter/meta/visibleForTesting-constant.html[`@visibleForTesting`] annotation marks a public API so that developers that have not disabled the `invalid_use_of_visible_for_testing_member` analyzer error get a warning when they use this API outside of a `test` directory.
|
||||
The [`@visibleForTesting`](https://api.flutter.dev/flutter/meta/visibleForTesting-constant.html) annotation marks a public API so that developers that have not disabled the `invalid_use_of_visible_for_testing_member` analyzer error get a warning when they use this API outside of a `test` directory.
|
||||
|
||||
This means that the API has to be treated as being public (nothing prevents a developer from using the API even in non-test code), meaning it must be designed to be a public API, it must be documented, it must be tested, etc. At which point, there's really no reason not to just make it a public API. If anything, the use of `@visibleForTesting` becomes merely a crutch to convince ourselves that it's ok that we're making something public that we should really not have made public.
|
||||
|
||||
@ -986,7 +985,7 @@ you should use `@immutable` on the class hierarchy in question.
|
||||
|
||||
### Override `toString`
|
||||
|
||||
Use `https://api.flutter.dev/flutter/foundation/Diagnosticable-mixin.html[Diagnosticable]` (rather than directly overriding `toString`) on all but the most trivial classes. That allows us to inspect the object from https://pub.dartlang.org/packages/devtools[devtools] and IDEs.
|
||||
Use [`Diagnosticable`](https://api.flutter.dev/flutter/foundation/Diagnosticable-mixin.html) (rather than directly overriding `toString`) on all but the most trivial classes. That allows us to inspect the object from [devtools](https://pub.dartlang.org/packages/devtools) and IDEs.
|
||||
|
||||
For trivial classes, override `toString` as follows, to aid in debugging:
|
||||
|
||||
@ -1058,7 +1057,7 @@ suite. (It also makes developing the tests faster because you can run the test f
|
||||
|
||||
### Avoid using `pumpAndSettle`
|
||||
|
||||
As per the API docs for https://main-api.flutter.dev/flutter/flutter_test/WidgetController/pumpAndSettle.html[pumpAndSettle], prefer using explicit https://main-api.flutter.dev/flutter/flutter_test/WidgetController/pump.html[`pump`] calls rather than `pumpAndSettle`.
|
||||
As per the API docs for [pumpAndSettle](https://main-api.flutter.dev/flutter/flutter_test/WidgetController/pumpAndSettle.html), prefer using explicit [`pump`](https://main-api.flutter.dev/flutter/flutter_test/WidgetController/pump.html) calls rather than `pumpAndSettle`.
|
||||
|
||||
Using `pumpAndSettle`, especially without checking its return value, makes it very easy for bugs to sneak in where we trigger animations across multiple frames instead of immediately. It is almost always the case that a call to `pumpAndSettle` is more strictly correctly written as two `pump` calls, one to trigger the animations and one (with a duration) to jump to the point after the animations.
|
||||
|
||||
@ -1117,7 +1116,7 @@ common callsites for the signature.
|
||||
### Spell words in identifiers and comments correctly
|
||||
|
||||
Our primary source of truth for spelling is the
|
||||
https://material.google.com/[Material Design Specification].
|
||||
[Material Design Specification](https://material.google.com/).
|
||||
Our secondary source of truth is dictionaries.
|
||||
|
||||
Avoid "cute" spellings. For example, 'colors', not 'colorz'.
|
||||
@ -1129,7 +1128,7 @@ Prefer compound words over "cute" spellings to avoid conflicts with reserved wor
|
||||
|
||||
### Capitalize identifiers consistent with their spelling
|
||||
|
||||
In general, we use https://dart.dev/guides/language/effective-dart/style#identifiers[Dart's recommendations]'s for naming identifiers. Please consider the following additional guidelines:
|
||||
In general, we use [Dart's recommendations](https://dart.dev/guides/language/effective-dart/style#identifiers) for naming identifiers. Please consider the following additional guidelines:
|
||||
|
||||
If a word is correctly spelled (according to our sources of truth as described in the previous section) as a single word, then it should not have any inner capitalization or spaces.
|
||||
|
||||
@ -1137,7 +1136,7 @@ For examples, prefer `toolbar`, `scrollbar`, but `appBar` ('app bar' in document
|
||||
|
||||
Similarly, prefer `offstage` rather than `offStage`.
|
||||
|
||||
Avoid using class names with `iOS` when possible. The capitalization of `iOS` is supposed to be exactly that, but that doesn't work well with camelCase and even less with UpperCamelCase; use alternatives like "Cupertino" or "UIKit" instead when possible. If you really really must use "iOS" in an identifier, capitalize it to `IOS`. Whether or not https://dart.dev/guides/language/effective-dart/style#do-capitalize-acronyms-and-abbreviations-longer-than-two-letters-like-words[the two-letter exception] applies to "iOS" is debatable, but `IOS` is consistent with Dart APIs, and the alternatives (`IOs`, `Ios`) are even more jarring. (Previous versions of this guide incorrectly indicated that `Ios` was the correct capitalization when necessary; this form should not be used in new code.)
|
||||
Avoid using class names with `iOS` when possible. The capitalization of `iOS` is supposed to be exactly that, but that doesn't work well with camelCase and even less with UpperCamelCase; use alternatives like "Cupertino" or "UIKit" instead when possible. If you really really must use "iOS" in an identifier, capitalize it to `IOS`. Whether or not [the two-letter exception](https://dart.dev/guides/language/effective-dart/style#do-capitalize-acronyms-and-abbreviations-longer-than-two-letters-like-words) applies to "iOS" is debatable, but `IOS` is consistent with Dart APIs, and the alternatives (`IOs`, `Ios`) are even more jarring. (Previous versions of this guide incorrectly indicated that `Ios` was the correct capitalization when necessary; this form should not be used in new code.)
|
||||
|
||||
|
||||
### Avoid double negatives in APIs
|
||||
@ -1211,7 +1210,7 @@ Thus, when you create a TODO, it is almost always your username that is given.
|
||||
|
||||
Including an issue link in a TODO description is required.
|
||||
|
||||
_(See also https://github.com/flutter/flutter/issues/37519[#37519],
|
||||
_(See also [#37519](https://github.com/flutter/flutter/issues/37519),
|
||||
which tracks a proposal to change the syntax of TODOs to not include usernames.)_
|
||||
|
||||
### Comment all `// ignores`
|
||||
@ -1262,7 +1261,7 @@ for consistency and readability reasons.
|
||||
We do not yet use `dartfmt` (except in flutter/packages).
|
||||
Flutter code tends to use patterns that
|
||||
the standard Dart formatter does not handle well. We are
|
||||
https://github.com/flutter/flutter/issues/2025[working with Dart team] to make `dartfmt` aware of these patterns.
|
||||
[working with Dart team](https://github.com/flutter/flutter/issues/2025) to make `dartfmt` aware of these patterns.
|
||||
|
||||
|
||||
### In defense of the extra work that hand-formatting entails
|
||||
@ -1835,20 +1834,20 @@ As per normal Dart conventions, a package should have a single import
|
||||
that reexports all of its API.
|
||||
|
||||
> For example,
|
||||
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/rendering.dart[rendering.dart]
|
||||
> [rendering.dart](https://github.com/flutter/flutter/blob/main/packages/flutter/lib/rendering.dart)
|
||||
> exports all of lib/src/rendering/*.dart
|
||||
|
||||
If a package uses, as part of its exposed API, types that it imports
|
||||
from a lower layer, it should reexport those types.
|
||||
|
||||
> For example,
|
||||
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/material.dart[material.dart]
|
||||
> [material.dart](https://github.com/flutter/flutter/blob/main/packages/flutter/lib/material.dart)
|
||||
> reexports everything from
|
||||
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/widgets.dart[widgets.dart].
|
||||
> [widgets.dart](https://github.com/flutter/flutter/blob/main/packages/flutter/lib/widgets.dart).
|
||||
> Similarly, the latter
|
||||
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/widgets/basic.dart[reexports]
|
||||
> [reexports](https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/widgets/basic.dart)
|
||||
> many types from
|
||||
> https://github.com/flutter/flutter/blob/main/packages/flutter/lib/rendering.dart[rendering.dart],
|
||||
> [rendering.dart](https://github.com/flutter/flutter/blob/main/packages/flutter/lib/rendering.dart),
|
||||
> such as `BoxConstraints`, that it uses in its API. On the other
|
||||
> hand, it does not reexport, say, `RenderProxyBox`, since that is not
|
||||
> part of the widgets API.
|
||||
@ -1889,7 +1888,7 @@ By convention, `dart:ui` is imported using `import 'dart:ui' show
|
||||
level will have done it for you), and as `import 'dart:ui' as ui show
|
||||
...;` for low-level APIs, in both cases listing all the identifiers
|
||||
being imported. See
|
||||
https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/painting/basic_types.dart[basic_types.dart]
|
||||
[basic_types.dart](https://github.com/flutter/flutter/blob/main/packages/flutter/lib/src/painting/basic_types.dart)
|
||||
in the `painting` package for details of which identifiers we import
|
||||
which way. Other packages are usually imported undecorated unless they
|
||||
have a convention of their own (e.g. `path` is imported `as path`).
|
||||
@ -1904,12 +1903,12 @@ We try to be very conservative with what we put in the core framework, because t
|
||||
|
||||
Basically, code is expensive. So before we take it, if possible, we like to see if we can prove the code's value. By creating a package, we can see if people use the feature, how they like it, whether it would be useful for the framework, etc, without having to take on the costs.
|
||||
|
||||
We have two main kinds of packages that are maintained by the Flutter team, both of which live in https://github.com/flutter/packages[flutter/packages]:
|
||||
We have two main kinds of packages that are maintained by the Flutter team, both of which live in [flutter/packages](https://github.com/flutter/packages):
|
||||
|
||||
1. Regular packages, which are pure Dart. Packages can also be written and maintained by people outside the Flutter team.
|
||||
|
||||
2. Plugin packages, which provide access to platform features and therefore include native code (such as Java or Objective-C) as well as Dart.
|
||||
|
||||
You can also consider making an independent package. Packages are published to https://pub.dartlang.org/[pub].
|
||||
You can also consider making an independent package. Packages are published to [pub](https://pub.dartlang.org/).
|
||||
|
||||
Often once we have made a package we find that that is actually sufficient to solve the problem that the code sets out to solve, and there ends up being no need to bring it into the framework at all.
|
||||
@ -1,88 +1,83 @@
|
||||
Common issues Flutter developers might run into and recipes how to fix or work around.
|
||||
|
||||
= Flutter Recipes
|
||||
# Flutter Recipes
|
||||
|
||||
== Flutter installation
|
||||
## Flutter installation
|
||||
|
||||
=== Flutter installation corrupted
|
||||
### Flutter installation corrupted
|
||||
|
||||
The Flutter install directory is in an inconsistent state and that causes all kinds of troubles.
|
||||
|
||||
==== Symptoms
|
||||
#### Symptoms
|
||||
|
||||
// TODO
|
||||
|
||||
==== Causes
|
||||
#### Causes
|
||||
|
||||
Unclear
|
||||
|
||||
==== Ways to fix
|
||||
#### Ways to fix
|
||||
|
||||
- Run the following commands in the Flutter install directory:
|
||||
[source,sh]
|
||||
----
|
||||
```sh
|
||||
git clean -xfd
|
||||
git stash save --keep-index
|
||||
git stash drop
|
||||
git pull
|
||||
flutter doctor
|
||||
----
|
||||
```
|
||||
|
||||
[CAUTION]
|
||||
====
|
||||
The `git stash drop` command drops customizations you might have made to the Flutter installation.
|
||||
====
|
||||
> [!CAUTION]
|
||||
> The `git stash drop` command drops customizations you might have made to the Flutter installation.
|
||||
|
||||
==== Related information
|
||||
#### Related information
|
||||
- https://github.com/flutter/flutter/issues/25220
|
||||
- https://github.com/flutter/flutter/issues/1963
|
||||
|
||||
== Flutter project files
|
||||
## Flutter project files
|
||||
|
||||
=== Generated project files outdated
|
||||
### Generated project files outdated
|
||||
|
||||
==== Symptoms
|
||||
#### Symptoms
|
||||
// TODO
|
||||
|
||||
==== Causes
|
||||
#### Causes
|
||||
|
||||
When a project is created with `flutter create foo` several files in the `ios/` and `android/` sub-directories are created.
|
||||
|
||||
Newer Flutter versions might generate these files a bit differently and projects created with older Flutter versions might cause issues.
|
||||
|
||||
==== Ways to fix
|
||||
#### Ways to fix
|
||||
|
||||
- Delete the `ios/` and `android/` directories and run `flutter create .` to re-generate these directories.
|
||||
|
||||
[CAUTION]
|
||||
====
|
||||
Custom changes will be lost and need to be re-applied.
|
||||
This is easiest if the project is committed to a version control system like Git.
|
||||
====
|
||||
> [!CAUTION]
|
||||
> Custom changes will be lost and need to be re-applied.
|
||||
> This is easiest if the project is committed to a version control system like Git.
|
||||
|
||||
|
||||
==== Related information
|
||||
#### Related information
|
||||
- https://github.com/flutter/flutter/issues/14974
|
||||
- https://github.com/flutter/flutter/issues/12573
|
||||
- https://github.com/flutter/flutter/issues/12983
|
||||
- https://github.com/flutter/flutter/issues/9827
|
||||
|
||||
|
||||
== Pub dependencies
|
||||
## Pub dependencies
|
||||
|
||||
=== Corrupted cache
|
||||
### Corrupted cache
|
||||
|
||||
Especially with plugin packages it was seen several times that the package in the pub cache was corrupted.
|
||||
|
||||
==== Symptoms
|
||||
#### Symptoms
|
||||
Usually syntax errors at build time about code in dependencies.
|
||||
|
||||
==== Causes
|
||||
#### Causes
|
||||
|
||||
Unknown.
|
||||
IDEs or editors used by developers might not prevent editing plugin files and when they navigate into plugin code they might accidentally modify the code.
|
||||
|
||||
==== Ways to fix
|
||||
#### Ways to fix
|
||||
|
||||
- Run `pub cache repair`
|
||||
This might take quite some time and re-downloads every package in the cache, even outdated versions that might not be used anymore by any project on disk.
|
||||
@ -98,84 +93,84 @@ firebase_auth:file:///Users/someuser/.pub-cache/hosted/pub.dartlang.org/firebase
|
||||
```
|
||||
To fix this package delete `///Users/someuser/.pub-cache/hosted/pub.dartlang.org/firebase_auth-0.6.6/` (`lib/` removed) and run `flutter packages get`.
|
||||
|
||||
==== Related information
|
||||
#### Related information
|
||||
- https://www.dartlang.org/tools/pub/cmd/pub-cache
|
||||
- https://www.dartlang.org/tools/pub/environment-variables
|
||||
|
||||
== Proxy
|
||||
## Proxy
|
||||
|
||||
=== Flutter commands can not access the Internet
|
||||
### Flutter commands can not access the Internet
|
||||
|
||||
In a network where the Internet can only be reached through a proxy and Flutter commands fail.
|
||||
|
||||
==== Symtoms
|
||||
#### Symtoms
|
||||
|
||||
// TODO
|
||||
|
||||
==== Causes
|
||||
#### Causes
|
||||
|
||||
Proxy setting incomplete or invalid.
|
||||
|
||||
==== Related information
|
||||
#### Related information
|
||||
(none yet)
|
||||
|
||||
=== Hot-reload not working
|
||||
### Hot-reload not working
|
||||
|
||||
When a proxy is configured hot-reload does often not work.
|
||||
|
||||
==== Symptoms
|
||||
#### Symptoms
|
||||
|
||||
// TODO
|
||||
|
||||
==== Causes
|
||||
#### Causes
|
||||
|
||||
Proxy setting incomplete or invalid.
|
||||
Localhost is redirected to the proxy.
|
||||
|
||||
==== Ways to fix
|
||||
#### Ways to fix
|
||||
|
||||
- Set environment variable `NO_PROXY=127.0.0.1`
|
||||
|
||||
==== Related information
|
||||
#### Related information
|
||||
|
||||
- https://github.com/flutter/flutter/issues/24854
|
||||
- https://github.com/flutter/flutter/issues/16875#issuecomment-384758566
|
||||
- https://stackoverflow.com/questions/9546324/adding-directory-to-path-environment-variable-in-windows[Adding directory to PATH Environment Variable in Windows]
|
||||
- https://stackoverflow.com/questions/19287379/how-do-i-add-to-the-windows-path-variable-using-setx-having-weird-problems[How do I add to the Windows PATH variable using setx? Having weird problems]
|
||||
- [Adding directory to PATH Environment Variable in Windows](https://stackoverflow.com/questions/9546324)
|
||||
- [How do I add to the Windows PATH variable using setx? Having weird problems](https://stackoverflow.com/questions/19287379)
|
||||
|
||||
|
||||
= Empty Template for new recipes
|
||||
# Empty Template for new recipes
|
||||
|
||||
Copy from the following line down
|
||||
|
||||
== Topic name
|
||||
## Topic name
|
||||
|
||||
=== Issue title
|
||||
### Issue title
|
||||
|
||||
Issue description
|
||||
|
||||
==== Symptoms
|
||||
#### Symptoms
|
||||
Explain seen symptoms
|
||||
|
||||
==== Causes
|
||||
#### Causes
|
||||
|
||||
Explain what causes this issue
|
||||
|
||||
==== Ways to fix
|
||||
#### Ways to fix
|
||||
|
||||
- Do this, do that as well
|
||||
|
||||
==== Related information
|
||||
#### Related information
|
||||
- https://example.com/some_link.html
|
||||
|
||||
|
||||
= AsciiDoc Recipes
|
||||
# AsciiDoc Recipes
|
||||
|
||||
==== AsciiDoc Syntax Quick Reference
|
||||
#### AsciiDoc Syntax Quick Reference
|
||||
|
||||
- https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
|
||||
|
||||
==== GitHub Flavored AsciiDoc
|
||||
#### GitHub Flavored AsciiDoc
|
||||
|
||||
Some workarounds for common issues with AsciiDoc on GitHub
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user