add windows faq doc, add more links to the top level readme (#1571)

* add windows faq doc, add more links to the top level readme

* add security considerations section

README.md

@@ -7,8 +7,16 @@ These packages provide libraries for generating Dart code.
 TODO: bazel_codegen
 -->
 
+[Getting started with build_runner](https://github.com/dart-lang/build/blob/master/docs/getting_started.md)
+
+[General FAQ](https://github.com/dart-lang/build/blob/master/docs/faq.md)
+
+[Windows FAQ](https://github.com/dart-lang/build/blob/master/docs/windows_faq.md)
+
 [FAQ for Builder authors](https://github.com/dart-lang/build/blob/master/docs/builder_author_faq.md).
 
+[Additional Docs](https://github.com/dart-lang/build/blob/master/docs/)
+
 ## [build](https://github.com/dart-lang/build/blob/master/build/README.md)
 
 Defines the interfaces for creating a `Builder` which is a way of doing codegen
@@ -37,13 +45,11 @@ Support for discovering the sub-modules within packages and creating summaries
 of those modules. Used by `build_web_compilers` but should not be used directly
 by most users.
 
-
 ## [build_resolvers](https://github.com/dart-lang/build/blob/master/build_resolers/README.md)
 
 An implementation of the `Resolver` interface to use the analyzer during build
 steps.
 
-
 ## [build_runner](https://github.com/dart-lang/build/blob/master/build_runner/README.md)
 
 Provides utilities to enact builds and a way to automatically run builds based

docs/faq.md

@@ -6,7 +6,7 @@ debug an error which only happens in `dart2js`, you will want to change your
 debug mode compiler to `dart2js`. You can either do this using the `--define`
 command line option:
 
-```
+```text
 --define "build_web_compilers|entrypoint=compiler=dart2js"
 ```
 

docs/windows_faq.md

@@ -0,0 +1,34 @@
+When running on windows there are a few quick tips that can help your file I/O
+performance.
+
+## Exclude your package directory from Windows Defender
+
+You can exclude your package entirely from windows defender by following
+[these instructions](https://support.microsoft.com/en-us/help/4028485/windows-10-add-an-exclusion-to-windows-defender-antivirus).
+
+This gives significant speed improvements (~2x in some light testing), but
+also comes with some obvious security considerations.
+
+### Security Considerations
+
+By opting into this you are potentially opening yourself up to vulnerabilities.
+Any `Builder` which is being applied to your package will no longer have its
+outputs checked by Windows Defender. If you don't trust your (even transitive!)
+dependencies then you should be wary of this option.
+
+Note that the original package dependency sources are not in your package
+directory but instead in your pub cache, so they will still be processed by
+windows defender.
+
+## Hide your output directories and the `.dart_tool` directory from your IDE
+
+It is common for IDEs to run file watchers on your entire package in order to
+update the file tree view among other things. Explicitly telling them to ignore
+the `.dart_tool` directory and any directories that you commonly use with `-o`
+can give a decent performance improvement.
+
+In `VsCode` you can do this using the `files.exclude` option in your
+preferences.
+
+In `Intellij` you can right click on a directory, select `Mark Directory as`,
+and choose `Excluded`.