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

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:

    
       fuchsia-pkg://fuchsia.com/pkg-name#meta/your_session.cm
    

    Replace the following:

    • pkg-name: the package name
    • your_session.cm: the name of your session, including the .cm extension.

    For more information, see fuchsia-pkg and Package name.

  2. Run the following command to include session_manager and your_session in your base image, configuring session_manager to start your session:

    
      fx set product.board \
         --with-base=//src/session/bin/session_manager \
         --with-base=//path/to/your/session \
         --args=product_config.session_url="fuchsia-pkg://fuchsia.com/pkg-name#meta/your_session.cm"
    

    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.

  3. Rebuild and re-pave the device.

    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.

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 launch a session.

To launch a session from the command line, do the following:

  1. Add the session_manager target in the base dependency set, in addition to the session target.

    fx set product.board --with-base=//src/session/bin/session_manager --with=//path/to/your/session

    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.

  2. Run the following command to rebuild and repave the device:

    fx build
    fx ota
    

    This causes session_manager to start without launching your session.

  3. Your session can now be launched from the command line.

    Run the following command to launch your session:

    ffx session launch fuchsia-pkg://fuchsia.com/pkg-name#meta/your_session.cm

    For more information about the ffx session command, run ffx session --help. For more information about ffx, see the ffx documentation.