[session] Contributor Documentation: examples
Each directory in //src/session/examples should have an accompanying README targeted at contributors, and the code itself should be consistently documented.
Bug: 43918
Change-Id: Ia562cfbd878152eec923f2ad43789235de3d32b1
diff --git a/src/session/examples/elements/BUILD.gn b/src/session/examples/elements/BUILD.gn
index c7b4c1f..ad3b847 100644
--- a/src/session/examples/elements/BUILD.gn
+++ b/src/session/examples/elements/BUILD.gn
@@ -4,6 +4,7 @@
group("elements") {
deps = [
+ "//src/experiences/examples/spinning_cube",
"//src/session/examples/elements/element_proposer",
"//src/session/examples/elements/element_session",
"//src/session/examples/elements/simple_element",
diff --git a/src/session/examples/elements/README.md b/src/session/examples/elements/README.md
index d563bf2..e44ff58 100644
--- a/src/session/examples/elements/README.md
+++ b/src/session/examples/elements/README.md
@@ -1,76 +1,97 @@
-## Overview
+# Elements
-This directory contains an example implementation of a session that
-instantiates a single element proposer.
+Reviewed on: 2020-02-04
-The element proposer connects to the [`ElementManager`]() service offered by the
-session, and uses said service to add a [`simple_element`]() to the session.
+This directory contains an example implementation of a session that instantiates a single [element proposer](./element_proposer/README.md).
-The `simple_element` then connects to the [`ElementPing`] service exposed to it
-by the session, and throug it notifies the session that it has been successfully
-instantiated.
+The element proposer connects to the [`ElementManager`](//sdk/fidl/fuchsia.session/element_manager.fidl) service offered by the session, and uses that service to add a [`simple_element`](./simple_element/README.md) to the session.
+
+The `simple_element` then connects to the `ElementPing` service exposed to it by the session notifies the session that it has been successfully instantiated.
## Element Session
The element session is configured to:
- 1. Declare a static child: the [`element_proposer`]().
- 2. Declare a child collection with a name which matches the one passed to the
- [`ElementManagement`]() library.
+ 1. Declare a static child: the [`element_proposer`](./element_proposer/README.md).
+ 2. Declare a child collection with a name which matches the one passed to the `ElementManagement` library.
3. Expose the `ElementManager` service.
4. Expose the `ElementPing` service.
5. Offer the `ElementManager` service to the `element_proposer` child.
6. Offer the `ElementPing` service to the child collection mentioned above.
-Details of how this is done can be found in the [`element_session.cml`]() file.
+Details of how this is done can be found in the [`element_session.cml`](./element_session/meta/element_session.cml) file.
Once the session is launched, it exposes the aforementioned services and starts
handling requests.
## Element Proposer
-The element proposer is configured to:
-
- 1. Use the `ElementManager` service.
-
-Details of how this is done can be found in the [`element_proposer.cml`]() file.
+The element proposer is configured to use the `ElementManager` service. Details of how this is done can be found in the [`element_proposer.cml`]() file.
Once the element proposer is started it connects to the `ElementManager` service
and attempts to add an element (`simple_element`) to the session.
## Simple Element
-The simple element is configured to:
-
- 1. Use the `ElementPing` service.
-
-Details of how this is done can be found in the [`simple_element.cml`]() file.
+The simple element is configured to use the `ElementPing` service. Details of how this is done can be found in the [`simple_element.cml`](./simple_element/meta/simple_element.cml) file.
Once the simple element is started, it will call `ElementPing::Ping()`. The
-session will receive the ping and log a confirmation.
+session receives the ping and log a confirmation.
+## Building `element_session`
-## Run the Session
+The example sessions are included in the build when you include `//src/session` with your `fx set`:
-### Boot into Session
+```
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config
+```
-To boot into the example, first edit the session manager cml file to set the
-element session's component url as the argument:
+To see a list of possible products, run: `fx list-products`.
+To see a list of possible boards, run: `fx list-boards`.
+
+## Running `element_session`
+### Boot into `element_session`
+
+To boot into `element_session`, edit the [session manager cml](//src/session/bin/session_manager/meta/session_manager.cml) file to set the element session's component url as the argument:
```
"args": [ "-s", "fuchsia-pkg://fuchsia.com/element_session#meta/element_session.cm" ],
```
+and run
+```
+fx update
+```
To build the relevant components and boot into the session, follow the
-instructions in [//src/session/README.md](../../README.md).
+instructions in [//src/session/README.md](//src/session/README.md).
-### Launch the Session from Command Line
+### Launch `element_session` from Command Line
To instruct a running `session_manager` to launch the session, run:
-
```
fx shell session_control -s fuchsia-pkg://fuchsia.com/element_session#meta/element_session.cm
```
The last command should output a message stating that the element's ping has
been received.
+
+## Testing
+
+Add `--with //src/session:tests` to your existing `fx set` command will include the `element_session` unit tests in the build. The resulting `fx set` looks like:
+```
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config --with //src/session:tests
+```
+To see a list of possible products, run: `fx list-products`.
+
+To see a list of possible boards, run: `fx list-boards`.
+
+The tests are available in the `element_session_tests`, `element_proposer_tests`, and `simple_element_tests` packages.
+```
+$ fx run-test element_session_tests
+$ fx run-test element_proposer_tests
+$ fx run-test simple_element_tests
+```
+
+## Source Layout
+
+The entry point and session units tests are located in `src/main.rs`.
diff --git a/src/session/examples/elements/element_proposer/README.md b/src/session/examples/elements/element_proposer/README.md
index 493492f..54efcc7 100644
--- a/src/session/examples/elements/element_proposer/README.md
+++ b/src/session/examples/elements/element_proposer/README.md
@@ -1,25 +1,11 @@
-## Overview
+# `element_proposer`
-The ElementProposer is a component that uses the `ElementManager` service to
-request Elements be added to the session. A session can contain any number of
-ElementProposer components. Notably, a component runner may act as an
-ElementProposer.
+Reviewed on: 2020-02-04
-ElementProposers commonly act as gateways to make software ecosystems available
-to a product. For example, a component acting as a voice assistant would propose
-Elements in response to voice commands.
+The `element_proposer` is a component that uses the [`ElementManager`](//sdk/fidl/fuchsia.session/element_manager.fidl) service to request that `Element`s get added to the session. A session can contain any number of `ElementProposer` components. Notably, a component runner may act as an `ElementProposer`.
-## ElementProposer
+`ElementProposer`s commonly act as gateways to make software ecosystems available to a product. For example, a component acting as a voice assistant would propose elements in response to voice commands.
-In this example, the
-`fuchsia-pkg://fuchsia.com/element_proposer#meta/element_proposer.cm` component
-is configured to:
+In this example, the `fuchsia-pkg://fuchsia.com/element_proposer#meta/element_proposer.cm` component is configured to use the `ElementManager` service. This is done by using the `ElementManager` protocol in the [`element_proposer.cml`](./meta/element_proposer.cml) file.
- 1. Use the `ElementManager` service.
-
-This is done by using the `ElementManager` protocol in the
-[`element_proposer.cml`]() file.
-
-Once the element proposer is started it connects to the `ElementManager` service
-and attempts to add an element to the session. The element proposer can propose
-both v1 and v2 components the session.
\ No newline at end of file
+Once the element proposer is started, it connects to the `ElementManager` service and attempts to add an element to the session. The element proposer can propose both v1 and v2 components the session.
diff --git a/src/session/examples/elements/element_proposer/src/main.rs b/src/session/examples/elements/element_proposer/src/main.rs
index b3d3eca..a623ba2 100644
--- a/src/session/examples/elements/element_proposer/src/main.rs
+++ b/src/session/examples/elements/element_proposer/src/main.rs
@@ -10,6 +10,8 @@
fuchsia_component::client::connect_to_service,
};
+/// Connect to the `ElementManager` service and propose two elements; the `simple_element` from
+/// these examples and `spinning_cube` from //src/experiences/examples.
#[fasync::run_singlethreaded]
async fn main() -> Result<(), Error> {
let element_manager = connect_to_service::<ElementManagerMarker>()
diff --git a/src/session/examples/elements/element_session/README.md b/src/session/examples/elements/element_session/README.md
new file mode 100644
index 0000000..0f7af51
--- /dev/null
+++ b/src/session/examples/elements/element_session/README.md
@@ -0,0 +1,13 @@
+# `element_session`
+
+Reviewed on: 2020-02-04
+
+`element_session` creates a sample session that exposes the [`ElementManager`](//sdk/fidl/fuchsia.session/element_manager.fidl) and `ElementPing` services. It then listens for messages on these two services.
+
+## `ElementManager` Service
+
+`element_session` listens for a `ProposeElement` message from the `ElementManager` service. Once received, the `element_session` generates a name for the proposed element and tells the `ElementManager` to add the element to the component tree.
+
+## `ElementPing` Service
+
+`element_session` listens for a `Ping` message from the ElementPing Service and logs that it was received.
diff --git a/src/session/examples/elements/element_session/src/main.rs b/src/session/examples/elements/element_session/src/main.rs
index 8251c0e..467f8b8d 100644
--- a/src/session/examples/elements/element_session/src/main.rs
+++ b/src/session/examples/elements/element_session/src/main.rs
@@ -17,13 +17,12 @@
rand::{distributions::Alphanumeric, thread_rng, Rng},
};
+/// This enum allows the session to match on incoming messages.
enum ExposedServices {
ElementManager(ElementManagerRequestStream),
ElementPing(ElementPingRequestStream),
}
-// TODO(38577): Write example tests for the element session.
-
/// The child collection to add elements to. This must match a collection name declared in
/// this session's CML file.
const ELEMENT_COLLECTION_NAME: &str = "elements";
diff --git a/src/session/examples/elements/simple_element/README.md b/src/session/examples/elements/simple_element/README.md
new file mode 100644
index 0000000..31ba677
--- /dev/null
+++ b/src/session/examples/elements/simple_element/README.md
@@ -0,0 +1,5 @@
+# `simple_element`
+
+Reviewed on: 2020-02-04
+
+This is an example implementation of an element that connects to the `ElementPing` service and calls the `ping` function.
diff --git a/src/session/examples/elements/simple_element/src/main.rs b/src/session/examples/elements/simple_element/src/main.rs
index 83ab2cc..90a18c3 100644
--- a/src/session/examples/elements/simple_element/src/main.rs
+++ b/src/session/examples/elements/simple_element/src/main.rs
@@ -9,6 +9,7 @@
fuchsia_async as fasync, fuchsia_component::client::connect_to_service,
};
+/// An `Element` that connects to the `ElementPing` Service and calls the `ping` method.
#[fasync::run_singlethreaded]
async fn main() -> Result<(), Error> {
let element_ping = connect_to_service::<ElementPingMarker>()
diff --git a/src/session/examples/graphical_session/README.md b/src/session/examples/graphical_session/README.md
new file mode 100644
index 0000000..97f64d4
--- /dev/null
+++ b/src/session/examples/graphical_session/README.md
@@ -0,0 +1,59 @@
+# Graphical Session Example
+
+Reviewed on: 2020-02-04
+
+This directory contains an example implementation of a session that uses [`scenic`](//src/ui/scenic) to render and animate an image to the screen.
+
+## Building `graphical_session`
+
+The example sessions are included in the build when you include `//src/session` with your `fx set`:
+
+```
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config
+```
+
+To see a list of possible products, run: `fx list-products`.
+
+To see a list of possible boards, run: `fx list-boards`.
+
+## Running `graphical_session`
+### Boot into `graphical_session`
+
+To boot into `graphical_session`, edit the [session manager cml](//src/session/bin/session_manager/meta/session_manager.cml) file to set the input session's component url as the argument:
+```
+args: [ "-s", "fuchsia-pkg://fuchsia.com/graphical_session#meta/graphical_session.cm" ],
+```
+and run
+```
+fx update
+```
+
+To build the relevant components and boot into the session, follow the instructions in [//src/session/README.md](//src/session/README.md).
+
+### Launch `graphical_session` from Command Line
+
+To instruct a running `session_manager` to launch the session, run:
+```
+fx shell session_control -s fuchsia-pkg://fuchsia.com/graphical_session#meta/graphical_session.cm
+```
+
+## Testing
+
+Add `--with //src/session:tests` to your existing `fx set` command to include the `graphical_session` unit tests in the build. The resulting `fx set` looks like:
+```
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config --with //src/session:tests
+```
+To see a list of possible products, run: `fx list-products`.
+
+To see a list of possible boards, run: `fx list-boards`.
+
+The tests are available in the `graphical_session_tests` package. To run the tests, use:
+```
+$ fx run-test graphical_session_tests
+```
+
+## Source Layout
+
+The entry point and session units tests are located in `src/main.rs`. `src/views.rs` contains a struct that represents the graphical elements and manages the interaction with `scenic`. Creating the connection to `scenic` and handling the timing of updates is done in `src/app.rs`. `src/graphics_util.rs` contains some useful helper functions.
+
+The images that is rendered on the screen is in `/resources`.
diff --git a/src/session/examples/graphical_session/src/main.rs b/src/session/examples/graphical_session/src/main.rs
index 9c9ecb1..f0d64ca 100644
--- a/src/session/examples/graphical_session/src/main.rs
+++ b/src/session/examples/graphical_session/src/main.rs
@@ -7,8 +7,8 @@
mod app;
mod view;
-// TODO(38577): Write example tests for the graphical session.
-
+/// Entry point for the `graphical_session`. It creates an instance of the `App`, runs it, and
+/// waits for it to finish.
#[fuchsia_async::run_singlethreaded]
async fn main() -> Result<(), Error> {
let mut app = app::App::new().await?;
diff --git a/src/session/examples/input_session/README.md b/src/session/examples/input_session/README.md
index 6cc8096..1d059b2 100644
--- a/src/session/examples/input_session/README.md
+++ b/src/session/examples/input_session/README.md
@@ -1,35 +1,62 @@
-## Overview
+# Input Session Example
-This directory contains an example implementation of a session that
-opens input devices and simply logs some of the data from the input reports
-(keyboard key, touch coordinates, mouse coordinates, etc.).
+Reviewed on: 2020-02-04
-## Run the Session
+This directory contains an example implementation of a session that opens input devices and simply logs some of the data from the input reports (keyboard key, touch coordinates, mouse coordinates, etc.).
-### Boot into Session
+## Building `input_session`
-To boot into the example, first edit the session manager cml file to set the
-input session's component url as the argument:
+The example sessions are included in the build when you include `//src/session` with your `fx set`:
```
-"args": [ "-s", "fuchsia-pkg://fuchsia.com/input_session#meta/input_session.cm" ],
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config
```
-To build the relevant components and boot into the session, follow the
-instructions in [//src/session/README.md](../../README.md).
+To see a list of possible products, run: `fx list-products`.
-### Launch the Session from Command Line
+To see a list of possible boards, run: `fx list-boards`.
+
+## Running `input_session`
+### Boot into `input_session`
+
+To boot into `input_session`, first edit the [session manager cml](//src/session/bin/session_manager/meta/session_manager.cml) file to set the input session's component url as the argument:
+
+```
+args: [ "-s", "fuchsia-pkg://fuchsia.com/input_session#meta/input_session.cm" ],
+```
+and run
+```
+fx update
+```
+
+To build the relevant components and boot into the session, follow the instructions in [//src/session/README.md](//src/session/README.md).
+
+### Launch `input_session` from Command Line
To instruct a running `session_manager` to launch the session, run:
-
```
fx shell session_control -s fuchsia-pkg://fuchsia.com/input_session#meta/input_session.cm
```
-The last command should output messages to the system log for each connected (known) input
-device. Some device types (such as keyboard and mouse) have multiple devices under certain
-circumstances, such as when running from a Chrome Remote Desktop session. Typically only
-one of each device type will actually produce events.
+The last command should output messages to the system log for each connected (known) input device. Some device types (such as keyboard and mouse) have multiple devices under certain circumstances, such as when running from a Chrome Remote Desktop session. Typically only one of each device type produces events.
-Once connected, type on the keyboard, click and drag a mouse, or touch the touch screen
-(depending on the device). These actions should print messages to the system log.
+Once connected, type on the keyboard, click and drag a mouse, or touch the touch screen (depending on the device). These actions should print messages to the system log.
+
+## Testing
+
+Add `--with //src/session:tests` to your existing `fx set` command to include the `input_session` unit tests in the build. The resulting `fx set` looks like:
+```
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config --with //src/session:tests
+```
+To see a list of possible products, run: `fx list-products`.
+
+To see a list of possible boards, run: `fx list-boards`.
+
+The tests are available in the `input_session_tests` package. To run the tests, use:
+```
+$ fx run-test input_session_tests
+```
+
+## Source Layout
+
+The entry point and units tests are located in `src/main.rs`.
diff --git a/src/session/examples/input_session/src/main.rs b/src/session/examples/input_session/src/main.rs
index 08fcae9..fd207a6 100644
--- a/src/session/examples/input_session/src/main.rs
+++ b/src/session/examples/input_session/src/main.rs
@@ -1,4 +1,4 @@
-// Copyright 2019 The Fuchsia Authors. All rights reserved.
+// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@@ -11,6 +11,7 @@
input::{input_device, mouse},
};
+/// Creates an `InputEvent` receiver to listen for mouse input. Logs each mouse event as received.
#[fasync::run_singlethreaded]
async fn main() -> Result<(), Error> {
fuchsia_syslog::init_with_tags(&["input_session"]).expect("Failed to initialize logger.");
diff --git a/src/session/examples/scene_manager_session/BUILD.gn b/src/session/examples/scene_manager_session/BUILD.gn
index 3294efb..fedfbe9 100644
--- a/src/session/examples/scene_manager_session/BUILD.gn
+++ b/src/session/examples/scene_manager_session/BUILD.gn
@@ -12,8 +12,17 @@
]
}
+group("tests") {
+ testonly = true
+ deps = [
+ ":scene_manager_session",
+ ":scene_manager_session_tests",
+ ]
+}
+
rustc_binary("scene_manager_session_bin") {
name = "scene_manager_session"
+ with_unit_tests = true
edition = "2018"
deps = [
@@ -49,3 +58,34 @@
},
]
}
+
+package("scene_manager_session_tests") {
+ testonly = true
+ deps = [
+ ":scene_manager_session_bin",
+ ":scene_manager_session_bin_test",
+ "//src/sys/test_adapters/rust",
+ ]
+
+ meta = [
+ {
+ path = "meta/scene_manager_session_bin_test.cml"
+ dest = "scene_manager_session_bin_test.cm"
+ },
+ ]
+
+ binaries = [
+ {
+ name = "rust_test_adapter"
+ },
+ {
+ name = "scene_manager_session"
+ },
+ ]
+
+ tests = [
+ {
+ name = "scene_manager_session_bin_test"
+ },
+ ]
+}
diff --git a/src/session/examples/scene_manager_session/README.md b/src/session/examples/scene_manager_session/README.md
new file mode 100644
index 0000000..28827c0
--- /dev/null
+++ b/src/session/examples/scene_manager_session/README.md
@@ -0,0 +1,57 @@
+# Scene Manager Session Example
+
+Reviewed on: 2020-02-04
+
+This directory contains an example implementation of a session that uses a [`SceneManager`](//src/session/lib/scene_management/src/scene_manager.rs), specifically the [`FlatSceneManager`](//src/session/lib/scene_management/src/flat_scene_manager.rs), to handle rendering things to the screen.
+
+## Building `scene_manager_session`
+
+The example sessions are included in the build when you include `//src/session` with your `fx set`:
+
+```
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config
+```
+
+To see a list of possible products, run: `fx list-products`.
+
+To see a list of possible boards, run: `fx list-boards`.
+
+## Running `scene_manager_session`
+### Boot into `scene_manager_session`
+
+To boot into `scene_manager_session`, first edit the [session manager cml](//src/session/bin/session_manager/meta/session_manager.cml) file to set the input session's component url as the argument:
+```
+args: [ "-s", "fuchsia-pkg://fuchsia.com/scene_manager_session#meta/scene_manager_session.cm" ],
+```
+and run
+```
+fx update
+```
+
+To build the relevant components and boot into the session, follow the instructions in [//src/session/README.md](//src/session/README.md).
+
+### Launch `scene_manager_session` from Command Line
+
+To instruct a running `session_manager` to launch the session, run:
+```
+fx shell session_control -s fuchsia-pkg://fuchsia.com/scene_manager_session#meta/scene_manager_session.cm
+```
+
+## Testing
+
+Add `--with //src/session:tests` to your existing `fx set` command to include the `scene_manager_session` unit tests in the build. The resulting `fx set` looks like:
+```
+fx set <PRODUCT>.<BOARD> --with-base=//src/session,//src/session/bin/session_manager:session_manager.config --with //src/session:tests
+```
+To see a list of possible products, run: `fx list-products`.
+
+To see a list of possible boards, run: `fx list-boards`.
+
+The tests are available in the `scene_manager_session_tests` package. To run the tests, use:
+```
+$ fx run-test scene_manager_session_tests
+```
+
+## Source Layout
+
+The entry point and session units tests are located in `src/main.rs`.
diff --git a/src/session/examples/scene_manager_session/meta/scene_manager_session_bin_test.cml b/src/session/examples/scene_manager_session/meta/scene_manager_session_bin_test.cml
new file mode 100644
index 0000000..6f3395c0
--- /dev/null
+++ b/src/session/examples/scene_manager_session/meta/scene_manager_session_bin_test.cml
@@ -0,0 +1,28 @@
+{
+ program: {
+ binary: "bin/rust_test_adapter",
+ args: ["/pkg/test/scene_manager_session_bin_test",],
+ },
+ use: [
+ {
+ directory: "/dev/class/input-report",
+ from: "realm",
+ rights: [
+ "r*",
+ ],
+ },
+ {
+ protocol: "/svc/fuchsia.logger.LogSink",
+ },
+ // The last "use" statement is needed for the RustTestAdapter trampoline
+ {
+ protocol: "/svc/fuchsia.process.Launcher",
+ },
+ ],
+ expose: [
+ {
+ protocol: "/svc/fuchsia.test.Suite",
+ from: "self",
+ },
+ ],
+}
diff --git a/src/session/examples/scene_manager_session/src/main.rs b/src/session/examples/scene_manager_session/src/main.rs
index cae169c..77aab4d 100644
--- a/src/session/examples/scene_manager_session/src/main.rs
+++ b/src/session/examples/scene_manager_session/src/main.rs
@@ -1,3 +1,7 @@
+// Copyright 2020 The Fuchsia Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
use {
anyhow::Error,
fidl_fuchsia_ui_scenic::ScenicMarker,
@@ -10,6 +14,8 @@
scene_management::{self, SceneManager},
};
+/// Connects to the `scenic` service and creates an instance of the `FlatSceneManager`. It then
+/// sets the cursor position to the middle of the screen.
#[fasync::run_singlethreaded]
async fn main() -> Result<(), Error> {
fsyslog::init_with_tags(&["scene_manager_session"]).expect("Failed to init syslog");
@@ -52,3 +58,11 @@
*target = max;
}
}
+
+#[cfg(test)]
+mod tests {
+ #[test]
+ fn dummy_test() {
+ println!("Don't panic!(), you've got this!");
+ }
+}
