| OLD | NEW |
| 1 The analysis package defines support for performing static analysis of Dart | 1 # Analyzer for Dart |
| 2 code. It was designed to support tooling efforts, but has also been used for | |
| 3 such things as statistics gathering and code transformers. | |
| 4 | 2 |
| 5 If you are interested in providing Dart support in a long-running tool, such as | 3 This package provides a low-level _library_ that performs static analysis |
| 6 an editor or IDE, you should use the analysis server instead of this package. | 4 of Dart code. It is useful for tool |
| 7 The analysis server is currently shipped as an executable in the SDK and will | 5 integration and embedding. |
| 8 be released as a package in the near future. In the meantime, if you'd like to | |
| 9 learn more about it, please look at the | |
| 10 [Analysis Server API Specification](http://htmlpreview.github.io/?https://github
.com/dart-lang/sdk/blob/master/pkg/analysis_server/doc/api.html) | |
| 11 or contact the mailing list (see below). | |
| 12 | 6 |
| 13 The API's in this package are, quite frankly, a mess at the moment. They were | 7 End-users should use the [dartanalyzer][analyzercli] command-line tool |
| 8 to analyze their Dart code. |
| 9 |
| 10 Integrators that want to add Dart support to their editor |
| 11 should use the _Dart Analysis Server_. |
| 12 The [Analysis Server API Specification][serverapi] is available. |
| 13 If you are adding Dart support to an editor or IDE, please let us know |
| 14 by emailing our [list][]. |
| 15 |
| 16 ## Configuring the analyzer |
| 17 |
| 18 Both `dartanalyzer` and Dart Analysis Server can be configured with either an |
| 19 `analysis_options.yaml` or `.analysis_options` file. This YAML file can control |
| 20 which files and paths are analyzed, which lints are applied, and more. |
| 21 |
| 22 If you are embedding the analyzer library in your project, you are responsible |
| 23 for finding the analysis options file, parsing it, and configuring the analyzer. |
| 24 |
| 25 The analysis options file should live at the root of your project (for example, |
| 26 next to your `pubspec.yaml`). Different embedders of analyzer, such as |
| 27 `dartanalyzer` or Dart Analysis Server, may choose to find the file in various |
| 28 different ways. Consult their documentation to learn more. |
| 29 |
| 30 Here is an example file that instructs the analyzer to ignore two files: |
| 31 |
| 32 ```yaml |
| 33 analyzer: |
| 34 exclude: |
| 35 - test/_data/p4/lib/lib1.dart |
| 36 - test/_data/p5/p5.dart |
| 37 - test/_data/bad*.dart |
| 38 - test/_brokendata/** |
| 39 ``` |
| 40 |
| 41 Note that you can use globs, as defined by the [glob package][glob]. |
| 42 |
| 43 Here is an example file that enables the analyzer's [strong mode][strongmode]: |
| 44 |
| 45 ```yaml |
| 46 analyzer: |
| 47 strong-mode: true |
| 48 ``` |
| 49 |
| 50 Here is an example file that enables two lint rules: |
| 51 |
| 52 ```yaml |
| 53 linter: |
| 54 rules: |
| 55 - camel_case_types |
| 56 - empty_constructor_bodies |
| 57 ``` |
| 58 |
| 59 Check out all the available [Dart lint rules][lintrules]. |
| 60 |
| 61 You can combine the `analyzer` section and the `linter` section into a single |
| 62 configuration. Here is an example: |
| 63 |
| 64 ```yaml |
| 65 analyzer: |
| 66 exclude: |
| 67 - test/_data/p4/lib/lib1.dart |
| 68 linter: |
| 69 rules: |
| 70 - camel_case_types |
| 71 ``` |
| 72 |
| 73 ## Who uses this library? |
| 74 |
| 75 Many tools embed this library, such as: |
| 76 |
| 77 * [dartfmt] - a formatter for Dart code |
| 78 * [dartdoc] - a documentation generator for Dart code |
| 79 * [Dart Analysis Server][analysis_sever] - a stateful server that supports IDEs
and editors |
| 80 |
| 81 ## Support |
| 82 |
| 83 Post issues and feature requests at https://github.com/dart-lang/sdk/issues |
| 84 |
| 85 Questions and discussions are welcome at the |
| 86 [Dart Analyzer Discussion Group][list]. |
| 87 |
| 88 ## Background |
| 89 |
| 90 The APIs in this package are, quite frankly, a mess at the moment. They were |
| 14 originally machine generated by a translator and were based on an earlier Java | 91 originally machine generated by a translator and were based on an earlier Java |
| 15 implementation. Several of the API's still look like their Java predecessors | 92 implementation. Several of the API's still look like their Java predecessors |
| 16 (or worse) rather than clean Dart API's. | 93 (or worse) rather than clean Dart API's. |
| 17 | 94 |
| 18 In addition, there is currently no clean distinction between public and internal | 95 In addition, there is currently no clean distinction between public and internal |
| 19 API's. We plan to address this issue soon, but doing so will, unfortunately, | 96 APIs. We plan to address this issue but doing so will, unfortunately, |
| 20 require a large number of breaking changes. We will try to minimize the pain | 97 require a large number of breaking changes. We will try to minimize the pain |
| 21 this causes for our clients, but some pain is inevitable. | 98 this causes for our clients, but some pain is inevitable. |
| 22 | 99 |
| 23 Questions and requests for additional functionality are welcome, and can be made | 100 ## License |
| 24 by either opening an issue at | 101 |
| 25 [http://dartbug.com](http://dartbug.com) | 102 See the [LICENSE] file. |
| 26 or by emailing | 103 |
| 27 [analyzer-discuss@dartlang.org](https://groups.google.com/a/dartlang.org/forum/#
!forum/analyzer-discuss). | 104 [serverapi]: https://htmlpreview.github.io/?https://github.com/dart-lang/sdk/blo
b/master/pkg/analysis_server/doc/api.html |
| 105 [analyzercli]: https://github.com/dart-lang/sdk/tree/master/pkg/analyzer_cli |
| 106 [list]: https://groups.google.com/a/dartlang.org/forum/#!forum/analyzer-discuss |
| 107 [lintrules]: http://dart-lang.github.io/linter/lints/ |
| 108 [strongmode]: https://github.com/dart-lang/dev_compiler/blob/master/STRONG_MODE.
md |
| 109 [glob]: https://pub.dartlang.org/packages/glob |
| 110 [LICENSE]: https://github.com/dart-lang/sdk/blob/master/pkg/analyzer/LICENSE |
| 111 [dartfmt]: https://github.com/dart-lang/dart_style |
| 112 [dartdoc]: https://github.com/dart-lang/dartdoc |
| 113 [analysis_sever]: https://github.com/dart-lang/sdk/tree/master/pkg/analysis_serv
er |
| OLD | NEW |