[docs] Updates to Dart language notes
Some of the usage of Dart in Fuchsia has changed, these
updates bring the documentation up to date.
PiperOrigin-RevId: 248413977
Change-Id: I8660794efea60c62c4dd18832b559382e29c7dcc
diff --git a/docs/development/languages/dart/README.md b/docs/development/languages/dart/README.md
index 76cb6ee..a62c801 100644
--- a/docs/development/languages/dart/README.md
+++ b/docs/development/languages/dart/README.md
@@ -8,7 +8,7 @@
Instead of relying on [`pub`][pub] to manage dependencies, sources of
third-party packages we depend on are checked into the tree under
-[`//third_party/dart-pkg`][dart-3p].
+`//third_party/dart-pkg`.
This is to ensure we use consistent versions of our dependencies across multiple
builds.
@@ -16,6 +16,25 @@
`out/`. That includes `.packages` files which are generated as part of the build
based on a target's dependency.
+## Exiting Dart programs
+
+The Dart runner for Fuchsia does not
+monitor the FIDL channels opened by Dart programs and as a result does not end
+the program normally, but rather waits for the explict call to `fuchsia.exit()`
+to indicate the program should be ended.
+
+Note: Calling exit() from dart:io will result in an exception since components
+are not allowed to call this method since it would shutdown the dart_runner process.
+
+```dart
+import 'package:fuchsia/fuchsia.dart' as fuchsia;
+
+void main(List<String> args) {
+ print('Hello Dart!');
+ fuchsia.exit(23);
+}
+```
+
## Targets
diff --git a/docs/development/languages/dart/analysis.md b/docs/development/languages/dart/analysis.md
index 9f28e75..5162fec 100644
--- a/docs/development/languages/dart/analysis.md
+++ b/docs/development/languages/dart/analysis.md
@@ -5,27 +5,33 @@
For each `dart_library` target, an analysis script gets
also generated in the output directory under:
+
```sh
out/<build-type>/gen/path/to/package/package.analyzer.sh
```
+
Running this script will perform an analysis of the target's sources.
Note that other templates usually define a Dart library they build upon. For
-example, a `flutter_app` `//foo/bar` will yield a `//foo/bar:bar_dart_library`
+example, a _flutter_app_ `//foo/bar` will yield a `//foo/bar:bar_dart_library`
target which can also be analyzed.
As with standard Dart packages, analysis options are defined in an
`analysis_options.yaml` file, which must be placed at the package root.
This file may refer to a common set of options by way of an `include` directive:
+
```
include: relative/path/to/options.file
```
-A canonical set is available at `//topaz/tools/analysis_options.yaml`.
+
+A canonical set is available at [//topaz/tools/analysis_options.yaml](https://fuchsia.googlesource.com/topaz/+/master/tools/analysis_options.yaml)
It is customary to merely include that set from a local options file:
+
```
include: path/to/topaz/tools/analysis_options.yaml
```
Analysis may be disabled altogether for a given target with:
+
```
dart_library("foo") {
disable_analysis = true
@@ -34,12 +40,15 @@
The `//scripts/run-dart-action.py` script makes it easy to run the analysis over
multiple targets:
+
```sh
scripts/run-dart-action.py analyze --out out/<build-type> --tree //topaz/shell/*
```
Regular analyzer flags may also be passed:
+
```sh
scripts/run-dart-action.py analyze --out out/<build-type> --fatal-warnings --lints
```
+
This holds true for the individual analysis scripts.
diff --git a/docs/development/languages/dart/fidl.md b/docs/development/languages/dart/fidl.md
index efd9098..8073b5f 100644
--- a/docs/development/languages/dart/fidl.md
+++ b/docs/development/languages/dart/fidl.md
@@ -3,19 +3,34 @@
[FIDL targets][fidl] generate implicit Dart bindings targets. To use the
bindings generated for:
+
```
//foo/bar
//foo/bar:blah
```
-add a dependency on:
+
+add a dependencies in BUILD.gn:
+
```
-//foo/bar:bar_dart
-//foo/bar:blah_dart
+deps = [
+ ...
+ "//foo/bar",
+ "//foo/bar:blah",
+ ...
+]
```
-and import the resulting Dart sources with:
-```
-import "package:foo.bar/baz.dart";
-import "package:foo.bar..blah/baz.dart";
+
+There are 3 files generated for dart from FIDL. These are found in
+`out/default/dartlang/gen/<path-to-target>/<fidl-servicename>_package/lib`
+
+* fidl.dart - the synchronous bindings
+* fidl_async.dart - the asynchronous bindings
+* fidl_test.dart - the stubbed out implementation of the service.
+
+
+```dart
+import "package:fidl_foo_bar/fidl.dart";
+import "package:fidl_foo_bar_blah/fidl_async.dart";
```
@@ -25,13 +40,13 @@
If two FIDL targets coexist in a single BUILD file:
-* their respective, generated files will currently be placed in the same
+* Their respective, generated files will currently be placed in the same
subdirectory of the output directory. This means that files belonging to one
target will be available to clients of the other target, and this will likely
confuse the analyzer. This should not be a build issue now but could become
one once the generated Dart files are placed in separate directories if
clients do not correctly set up their dependencies.
-* depending on one of these targets from *another* FIDL target that is used by
+* Depending on one of these targets from *another* FIDL target that is used by
a Dart package leads to a `Unable to read Dart source ...` error. The
bindings generator for FIDL builds Dart package names based on the directory
structure containing the included FIDL file, while GN (used to compute
@@ -40,6 +55,19 @@
`lib.foo.fidl._bar`. Depending on the top-level target `lib/foo/fidl`
generates the package `lib.foo.fidl`, which coincides with the Dart FIDL
binding's assumptions.
+
+## Calling a FIDL service
+
+The generated bindings for Dart require the importing of fuchsia_services.
+
+
+```dart
+import 'package:fuchsia_services/services.dart';
+```
+
+
+In order to use the Launcher service to start services that implement a FIDL interface,
+you need to have the `fuchsia.sys.Launcher` service declared in the .cmx
[fidl]: /build/fidl/fidl.gni "FIDL"
diff --git a/docs/development/languages/dart/ides.md b/docs/development/languages/dart/ides.md
index 123c788..840d4e0 100644
--- a/docs/development/languages/dart/ides.md
+++ b/docs/development/languages/dart/ides.md
@@ -56,6 +56,15 @@
```
+## CLion/IntelliJ
+
+* Add the Dart plugin by going to `Settings > Plugins` then searching for
+ Dart language support.
+* Set the Dart path in `Settings > Languages & Frameworks > Dart` by
+ * Check __Enable Dart support for the project <project name>.__
+ * Enter the Dart SDK path "${FUCHSIA_SRC}/third_party/dart/tools/sdks/dart-sdk"
+
+
## Troubleshooting
If you find that the IDE is unable to find imports (red squigglies) that are
diff --git a/docs/development/languages/dart/logging.md b/docs/development/languages/dart/logging.md
index edf2441..8873702 100644
--- a/docs/development/languages/dart/logging.md
+++ b/docs/development/languages/dart/logging.md
@@ -4,19 +4,36 @@
It is highly recommended that you use `lib.logging` package when you want to add
logging statements to your Dart package.
-Include the `lib.logging` package in your BUILD.gn target as a dependency:
+Include the `fuchsia_logger`, which wraps `lib.logging`, package in your
+BUILD.gn target as a dependency:
+
```
deps = [
...
- "//topaz/public/dart/logging:lib.logging",
+ "//topaz/public/dart/fuchsia_logger",
...
]
```
+In the .cmx file the `fuchsia.logger.LogSink` needs to be added to the sandbox:
+
+```
+{
+ "sandbox": {
+ "services": [
+ "fuchsia.logger.LogSink",
+ ...
+ ]
+ }
+}
+```
+
+
In the main function of your Dart / Flutter app, call the `setupLogger()`
function to make sure logs appear in the Fuchsia console in the desired format.
+
```dart
-import 'package:lib.logging/logging.dart';
+import 'package:fuchsia_logger/logger.dart';
main() {
setupLogger();
@@ -25,28 +42,31 @@
After setting this up, you can call one of the following log methods to add log
statements to your code:
+
```dart
-import 'package:lib.logging/logging.dart';
+import 'package:fuchsia_logger/logger.dart';
+
// add logging statements somewhere in your code as follows:
log.info('hello world!');
```
-The `log` object is a `Logger` instance as documented [here][logger-doc].
+The `log` object is a [Logger][logger-doc] instance.
## Log Levels
The log methods are named after the supported log levels. To list the log
methods in descending order of severity:
+
```dart
-log.shout() // maps to LOG_FATAL in FXL.
-log.severe() // maps to LOG_ERROR in FXL.
-log.warning() // maps to LOG_WARNING in FXL.
-log.info() // maps to LOG_INFO in FXL.
-log.fine() // maps to VLOG(1) in FXL.
-log.finer() // maps to VLOG(2) in FXL.
-log.finest() // maps to VLOG(3) in FXL.
+ log.shout() // maps to LOG_FATAL in FXL.
+ log.severe() // maps to LOG_ERROR in FXL.
+ log.warning() // maps to LOG_WARNING in FXL.
+ log.info() // maps to LOG_INFO in FXL.
+ log.fine() // maps to VLOG(1) in FXL.
+ log.finer() // maps to VLOG(2) in FXL.
+ log.finest() // maps to VLOG(3) in FXL.
```
By default, all the logs of which level is INFO or higher will be shown in the
@@ -55,10 +75,14 @@
Currently, the log level should be adjusted in individual Dart apps by providing
the `level` parameter in the `setupLogger()` call. For example:
+
```dart
setupLogger(level: Level.ALL);
```
-will make all log statements appear in the console.
+
+will make all log statements appear in the console. The console is visible by
+running [`fx syslog`][getting_logs].
[logger-doc]: https://pub.dev/documentation/logging/latest/logging/Logger-class.html
+[getting_logs]: /docs/development/workflows/fx#getting_logs
\ No newline at end of file
diff --git a/docs/development/workflows/fx.md b/docs/development/workflows/fx.md
index e338aec..72b21d5 100644
--- a/docs/development/workflows/fx.md
+++ b/docs/development/workflows/fx.md
@@ -400,7 +400,7 @@
## Performing other common tasks
-### Getting logs
+### Getting logs {:#getting_logs}
`fx syslog` captures all logs from low-level and high-level programs,
including the kernel, drivers and other userspace programs. `fx syslog`
