Sockets and contributions

A module does not edit files. It returns contributions, plain data that says what it adds, and the pipeline puts them together. Shared files, such as bootstrap.dart, have sockets: named places where modules put code without knowing who else does.

Contributions

Contribution	What it adds
BrickContribution	Template files, as a mason bundle, with the variables that the templates read. Every generated file has exactly one owner.
SocketContribution	Code or a value for a socket.
RoleData	Data for a role in the role's own language, such as the routes of a feature for the router.
PubspecContribution	A dependency, an SDK constraint, or a setting of the flutter: section of pubspec.yaml.
CodegenRequest	A request to run build_runner in the new app.
Preflight	Checks of the machine before generation, which can offer to set up what is missing.
PostGenStep	A command to run in the new app, such as dart tool/configure_firebase.dart dev.
ManualStep	A step of the setup that only the developer of the app can do, such as uploading a key to the Firebase console. The run ends with a link to its guide; see steps by hand.

Every contribution can have a when, a set of roles that must all be present for the contribution to apply. A module lists there the roles it only uses, so code that refers to them is generated only in apps that have them. firebase_analytics gives the router its listener of the screen with when: {routerRole}.

A brick and data of a role can also depend on what a role chose, with whenChosen: conditions that a role publishes as constants, such as RouterRole.noStartRoute, which holds in an app that no route starts. flutter_core contributes its fallback start screen, the test of the screen and its two texts under that condition, so an app that a route starts has none of them. A role chooses after the machine is checked, so such a condition decides only what the pipeline renders:

• Validation and --explain take a contribution with conditions as one that applies, and report its problems in every app that may have it.
• A role whose data depends on what another role chose makes its choice after that role, and gets only the data whose conditions hold.
• Once every role has chosen, the contributions whose conditions do not hold leave the app. The render hooks, the templates and the checks of the rendered app do not see them.

Only bricks and data of a role take such conditions, because the pipeline needs the other kinds before any role chooses. A brick with conditions holds no tag of a socket, since an app without the brick would lose what the socket got. See Choices.

Sockets

A socket belongs to a role, to a module or to the pipeline. Its template marks it with a tag in three braces that joins smf_, the owner and the name of the socket, such as {{{smf_app_entry__bootstrap_platform}}}. The pipeline replaces the tag with the rendered contributions. Modules refer to sockets only through typed constants, such as AppEntryRole.bootstrapPlatform, so a misspelled socket does not compile.

This is lib/bootstrap.dart as flutter_core writes it, with the tags of the start-up phases:

{{{smf_app_entry__top_level}}}

Future<void> bootstrap() async {
{{{smf_app_entry__bootstrap_early}}}
{{{smf_app_entry__bootstrap_platform}}}
{{{smf_app_entry__bootstrap_di}}}
{{{smf_app_entry__bootstrap_late}}}
}

The kind of a socket decides what it takes and how its contributions are rendered:

Kind	Takes	Rendered as	Example
CodeSocket	Fragments of code, with the imports they need	One after another	The start-up phases
ArgsSocket	Named arguments of a call	name: value, lines. A list argument unites the items of its contributors, or takes the items of one contributor only. Two values of a single argument conflict.	theme and supportedLocales of MaterialApp
WrapperSocket	A widget around a piece of code, as an opening and a closing part	The first contribution outermost	ProviderScope(child: …) around the root widget
FactoryListSocket	Functions that the socket's owner calls	List items	Navigator observers and listeners of the screen of the router, restorers of the preferences
KeyedSocket	Entries with a key	Merged by key with a policy	Android permissions, Info.plist keys, Gradle plugins, README sections, sections of the guide for coding agents
ValueSocket	One value, rendered at one tag, or at several places with a tag each (ValueSocket.places)	Merged with a policy	The minimum iOS version, the highest any module needs, and the version of core library desugaring, which renders a line in two places of the Gradle file

A fragment of code never imports anything itself. It lists its imports, such as ImportRef('package:firebase_core/firebase_core.dart'), and the pipeline adds them to the file that holds the socket's tag, merged and sorted. ImportRef.app('firebase_options_of_flavor.dart') imports a file of the app without knowing the app's package name.

The sockets of the app entry

The app entry role is open to every module, so any module can use these sockets:

Socket	Where	What goes in
bootstrapEarly, bootstrapPlatform, bootstrapDi, bootstrapLate	bootstrap()	Start-up code, by phase
topLevel	lib/bootstrap.dart	Top-level declarations, such as a handler of background messages
rootWrappers	main()	Widgets around the root widget
appArgs	the root MaterialApp	theme, darkTheme, themeMode and locale, which take one value, localizationsDelegates, which takes the list items of every contributor, and supportedLocales, which takes the list items of one contributor
appBuilder	the builder of the root MaterialApp	Widgets around the content of every route
iosDeploymentTarget	project.pbxproj	The minimum iOS version, where the highest wins
androidManifestPermissions	AndroidManifest.xml	<uses-permission> by name
androidManifestApplicationMeta	AndroidManifest.xml	<meta-data> of the application
androidManifestApplicationComponents	AndroidManifest.xml	<receiver>, <service> and <provider> elements inside <application>, after its meta-data, as XML
mainActivityIntentFilters	AndroidManifest.xml	<intent-filter>s of the main activity, such as deep links
infoPlist	Info.plist	Keys with a string, a boolean, an integer or an array of strings, where arrays are united
iosEntitlements	ios/Runner/Runner.entitlements	Entitlements by key, such as aps-environment, merged as the keys of Info.plist
iosAppDelegateLaunch	AppDelegate.swift	Swift statements that run in application(_:didFinishLaunchingWithOptions:), before the call of super.application that hands the launch to Flutter
gradleSettingsPlugins, gradleAppPlugins, gradleAppDependencies	Gradle files	Plugins with their versions, the plugins the app applies, and dependencies, where the highest version wins
androidCoreLibraryDesugaring	the Gradle file of the app	The version of desugar_jdk_libs, where the highest wins. It turns core library desugaring on in compileOptions and adds the library to dependencies, since the build fails with either line alone.
readmeSections	README.md	Sections by heading, such as the setup of Firebase
agentSections	AGENTS.md	Sections of the guide for coding agents by heading, each with a note

The provider of the app entry creates the root MaterialApp in the build of a widget, below the root wrappers, and evaluates the arguments of appArgs there. So the expression of an argument may read context: it can take its value from an inherited widget that a module put among the rootWrappers, and the root rebuilds when that widget notifies. The theme role gives the root its themeMode this way, and the localization role its locale. That context is above the MaterialApp, so it has neither the theme nor the localizations of the app.

The wrappers of appBuilder are below the MaterialApp, so a widget among them finds the theme and the localizations of the app above it. The app entry role puts one there itself, in every app: StatusBarIcons of lib/core/app/status_bar_icons.dart, which tells the system which icons of the status bar suit the theme.

A few native sockets ask more of what goes in:

• A contribution to androidManifestApplicationComponents indents its elements by eight spaces, and one to iosAppDelegateLaunch its lines by four, as the bodies around their tags are.
• The manifest declares a component of each kind once, <activity-alias> included, under one android:name. The contract harness checks the names as Android reads them, so a name that starts with a dot, or has none, is relative to the namespace of the Gradle file of the app. Android fails to build an app with two declarations of a component that differ, and keeps both of two equal ones.
• The statements of iosAppDelegateLaunch run before Flutter registers the plugins of the app, which the scene of the app does once it connects. So they have no registry of plugins and no channel. local_notifications sets the delegate of the notification center there.

The router role adds observers and screenListeners, and two families of sockets for the annotations of screens and of their parameters, which a router that needs annotations fills. The preferences role adds restorers, for the functions that restore what the modules keep in the preferences when the app starts.

Who may contribute where

• A socket of a role takes contributions from the modules that provide, require or use the role, and from the templates of the role and of the roles that require or use it. The sockets of the app entry are open to every module.
• A socket of a module takes contributions from the modules that depend on it directly.
• The sockets of the pipeline, which are the sections of pubspec.yaml, take no contributions. Modules contribute PubspecContributions instead, and the pipeline merges them.

A module may contribute data only to its own roles, and only a role's providers contribute its implementations. The pipeline checks all of it before it renders anything.

Order

When several modules put code into one socket, or several steps run after generation, they come in an order that the pipeline derives from the modules alone:

1. A module comes after the modules it depends on.
2. A module that requires a role, or names it in when, comes after the role's providers and its template.
3. A role's template comes after the role's providers, and after the providers and templates of the roles that its role requires or that its contributions name in when.

A contributor comes after every contributor it reaches through these edges, even through modules that add nothing to the socket. Otherwise contributors are ordered by id. A cycle is an error. smf create --explain prints the order of every socket with more than one contributor, and the edges that decide it. A step that continues another step runs right after that step instead of in its own place; see Continuing a step.

That is why installCrashReporting() of the crash reporting role runs after Firebase.initializeApp of firebase_core: the role's template comes after its provider, firebase_crashlytics, which depends on firebase_core.

A keyed socket can put its entries in an order of its own instead. The sections of the guide for coding agents do: the section of the app entry comes first, and the others follow in the order of their headings. The pipeline takes the notes of such a socket by the ids of their contributors alone, so a when of a note adds no edge, and no note can make an app impossible to generate. --explain does not list such a socket, which has no order of contributors to explain.

Merging

Keyed and value sockets merge the contributions of several modules with a policy of the socket:

Policy	How values merge	Used for
conflict	Equal values agree, and different values are an error that names both modules.	Android permissions, README sections
max	The highest version wins.	The minimum iOS version, Gradle plugins, core library desugaring
Info.plist	Arrays of strings are united, and every other value must agree.	Info.plist keys, entitlements
notes	The notes under one heading are united, each once: those of roles first, then those of modules.	Sections of the guide for coding agents

The pipeline merges pubspec.yaml itself. It intersects the constraints of a package that several modules add, and an empty intersection is an error. A package that is both a dependency and a dev dependency becomes a dependency.