Guide to Configuring the Modular Framework

DEPRECATION WARNING: The Modular framework is being deprecated in favor of the Session Framework.

Requirements

To configure the modular framework, you will need to create a JSON file defining the required configurations for basemgr and sessionmgr as detailed below. The configuration file should be packaged via the build rule modular_config, which will validate your file against a schema. You must then include the modular_config() target in the product's base packages.

The file may contain (non-standard JSON) C-style comments (/* block */ and // inline).

Example

{
  /* This is a block comment.
     Comments are ignored. */
  // This is an inline comment. Comments are ignored.
  "basemgr": {
    "enable_cobalt": false,
    "use_session_shell_for_story_shell_factory": true,
    "base_shell": {
      "url": "fuchsia-pkg://fuchsia.com/dev_base_shell#meta/dev_base_shell.cmx",
    },
    "session_shells": [
      {
        "url": "fuchsia-pkg://fuchsia.com/ermine_session_shell#meta/ermine_session_shell.cmx",
        "display_usage": "near",
        "screen_height": 50.0,
        "screen_width": 100.0
      }
    ]
  },
  "sessionmgr": {
    "use_memfs_for_ledger": true,
    "cloud_provider": "NONE",
    "startup_agents": [
      "fuchsia-pkg://fuchsia.com/startup_agent#meta/startup_agent.cmx"
    ],
    "session_agents": [
      "fuchsia-pkg://fuchsia.com/session_agent#meta/session_agent.cmx"
    ],
    "component_args": [
      {
        "uri": "fuchsia-pkg://fuchsia.com/startup_agent#meta/startup_agent.cmx",
        "args": [ "--foo", "--bar=true" ]
      }
    ],
    "agent_service_index": [
      {
        "service_name": "fuchsia.modular.SomeServiceName",
        "agent_url": "fuchsia-pkg://fuchsia.com/some_agent#meta/some_agent.cmx"
      }
    ],
    "restart_session_on_agent_crash": [
      "fuchsia-pkg://fuchsia.com/some_agent#meta/some_agent.cmx"
    ]
  }
}

Basemgr fields

• base_shell boolean (required)
  • url: string (required)
    • The fuchsia component url for which base shell to use.
  • keep_alive_after_login boolean (optional)
    • When set to true, the base shell is kept alive after a log in. This is used for testing because current integration tests expect base shell to always be running.
    • default: false
  • args string[] (optional)
    • A list of arguments to be passed to the base shell specified by url. Arguments must be prefixed with --.
• session_shells array (required)
  • Lists all the session shells with each shell containing the following fields:
    • url: string (required)
      • The fuchsia component url for which session shell to use.
    • display_usage: string (optional)
      • The display usage policy for this session shell.
      • Options:
        • handheld: the display is used well within arm's reach.
        • close: the display is used at arm's reach.
        • near: the display is used beyond arm's reach.
        • midrange: the display is used beyond arm's reach.
        • far: the display is used well beyond arm's reach.
    • screen_height: float (optional)
      • The screen height in millimeters for the session shell's display.
    • screen_width: float (optional)
      • The screen width in millimeters for the session shell's display.
• story_shell_url: string (optional)
  • The fuchsia component url for which story shell to use.
  • default: fuchsia-pkg://fuchsia.com/mondrian#meta/mondrian.cmx
• enable_cobalt: boolean (optional)
  • When set to false, Cobalt statistics are disabled.
  • default: true
• use_minfs: boolean (optional)
  • When set to true, wait for persistent data to initialize.
  • default: true
• use_session_shell_for_story_shell_factory: boolean (optional)
  • Create story shells through StoryShellFactory exposed by the session shell instead of creating separate story shell components. When set, story_shell_url and any story shell args are ignored.
  • default: false

Sessionmgr fields

• cloud_provider: string (optional)
  • Options:
    • LET_LEDGER_DECIDE: Use a cloud provider configured by ledger.
    • FROM_ENVIRONMENT: Use a cloud provider available in the incoming namespace, rather than initializing and instance within sessionmgr. This can be used to inject a custom cloud provider.
    • NONE: Do not use a cloud provider.
  • default: LET_LEDGER_DECIDE
• enable_cobalt: boolean (optional)
  • When set to false, Cobalt statistics are disabled. This is used for testing.
  • default: true
• enable_story_shell_preload: boolean (optional)
  • When set to false, StoryShell instances are not warmed up as a startup latency optimization. This is used for testing.
  • default: true
• use_memfs_for_ledger: boolean (optional)
  • Tells the sessionmgr whether it should host+pass a memfs-backed directory to the ledger for the user's repository, or to use /data/LEDGER.
  • default: false
• startup_agents: string[] (optional)
  • A list of fuchsia component urls that specify which agents to launch at startup.
• session_agents: string[] (optional)
  • A list of fuchsia component urls that specify which agents to launch at startup with PuppetMaster and FocusProvider services.
• component_args: array (optional)
  • A list of key/value pairs to construct a map from component URI to arguments list for that component. Presence in this list results in the given arguments passed to the component as its argv at launch.
    • uri: The component's uri.
    • args: A list of arguments to be passed to the component specified by uri. Arguments must be prefixed with --.
• agent_service_index: array (optional)
  • A list of key/value pairs to construct a map from service name to the serving agent's URL. Service names must be unique, so only one agent can provide a given named service.
    • service_name: The name of a service offered by a session agent.
    • agent_url: A fuchsia component url that specifies which agent will provide the named service.
• restart_session_on_agent_crash: array (optional)
  • A list of agent URLs that will cause the session to be restarted when they terminate unexpectedly. If an agent is not in this list, sessionmgr will restart it individually, preserving the session.