blob: b37d126362f38424a1ba51757c7554516d249b0d [file] [log] [blame] [view] [edit]
# Building and running a session {#building-and-running-a-session}
A session is the first product-specific component started on boot. The session
component is responsible for building a product's user experience.
## Booting into a session {#booting-into-a-session}
To boot into a session, do the following:
1. For a session to run at boot you need to configure the product build with
the session's URL. Identify the component URL for your session:
<pre><code>
fuchsia-pkg://fuchsia.com/<var>pkg-name</var>#meta/<var>your_session.cm</var>
</code></pre>
Replace the following:
- <var>pkg-name</var>: the package name
- <var>your_session.cm</var>: the name of your session, including the `.cm`
extension.
For more information, see
[`fuchsia-pkg`](/docs/reference/components/url.md#fuchsia-pkg) and
[Package name](/docs/concepts/packages/package_url.md#package-name).
1. Update your `//local/BUILD.gn` to include `product_assembly_overrides`.
<pre><code>
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("<var>custom_session</var>") {
base_packages = [
"<var>//path/to/your/session</var>"
]
platform = {
session = {
enabled = true
}
}
product = {
session = {
url = "fuchsia-pkg://fuchsia.com/<var>pkg-name</var>#meta/<var>your_session.cm"
}
}
}
</code></pre>
1. Run the following command to include `your_session` in your base image and set
the configuration values you defined in `//local:custom_session`.
<pre class="prettyprint"><code class="devsite-terminal">
fx set <var>product</var>.<var>board</var> --assembly-override=//local:<var>custom_session</var>
</code></pre>
`fx list-products` and `fx list-boards` will show lists of the products and
boards available to be used in the `fx set` command. For more information on
`fx` commands see the [fx documentation](/docs/development/build/fx.md).
1. Rebuild and re-pave the device.
```posix-terminal
fx build
fx ota
```
This causes `session_manager` to start and launch your session.
For a full explanation of building a session component, see [Writing a Hello
World Session](/docs/development/sessions/writing-a-hello-world-session.md).
## Launch a session from the command line {#launch-a-session-from-the-command-line}
There are cases when you don't want your session to launch at boot but still
want to be able to launch it from the command line. `session_manager` needs
to be running to launch a session. The `session_manager` target
ensures `session_manager` itself starts, but does not autolaunch a session.
To launch a session from the command line, do the following:
1. Update your `//local/BUILD.gn` with `product_assembly_overrides` using `autolaunch`.
<pre><code>
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("custom_session") {
base_packages = [
"<var>//path/to/your/session</var>"
]
platform = {
session = {
enabled = true
autolaunch = false
}
}
product = {
session = {
url = "fuchsia-pkg://fuchsia.com/<var>pkg-name</var>#meta/<var>your_session.cm"
}
}
}
</code></pre>
1. Add the `session_manager` target in the base dependency set, in
addition to the session target.
<pre class="prettyprint"><code class="devsite-terminal">
fx set <var>product</var>.<var>board</var> --assembly-override=<var>//local:custom_session</var>
</code></pre>
`fx list-products` and `fx list-boards` will show lists of the products and
boards available to be used in the `fx set` command. For more information on
`fx` commands see the [fx documentation](/docs/development/build/fx.md).
1. Run the following command to rebuild and repave the device:
```posix-terminal
fx build
fx ota
```
This causes `session_manager` to start without launching your session.
1. Your session can now be launched from the command line.
Run the following command to launch your session:
<pre class="prettyprint"><code class="devsite-terminal">ffx session launch fuchsia-pkg://fuchsia.com/<var>pkg-name</var>#meta/<var>your_session.cm</var></code></pre>
For more information about the `ffx session` command, run
`ffx session --help`. For more information about `ffx`, see the
[`ffx documentation`](/docs/development/tools/ffx/overview.md).