Skip to content

Expose the app's build name and number as compile-time constants#187935

Open
Ortes wants to merge 2 commits into
flutter:masterfrom
Ortes:expose-build-name-defines
Open

Expose the app's build name and number as compile-time constants#187935
Ortes wants to merge 2 commits into
flutter:masterfrom
Ortes:expose-build-name-defines

Conversation

@Ortes

@Ortes Ortes commented Jun 12, 2026

Copy link
Copy Markdown

The tool already injects FLUTTER_VERSION, FLUTTER_CHANNEL, framework/engine revisions (exposed as FlutterVersion) and FLUTTER_APP_FLAVOR (exposed as appFlavor) as dart-defines. The application's own version: from pubspec.yaml is the one missing field, even though the tool already parses it (FlutterManifest.buildName/buildNumber) and embeds it into version.json, Info.plist and build.gradle on every build.

Without it, the running version is unknowable on the web: version.json is fetched from the server at runtime, so a stale cached client reports the freshly deployed version instead of its own, and version gates / update prompts built on package_info_plus silently fail for exactly the users they exist for (fluttercommunity/plus_plugins#2675).

This PR:

  • injects FLUTTER_BUILD_NAME and FLUTTER_BUILD_NUMBER (from --build-name/--build-number, falling back to the pubspec version) in FlutterCommand.getBuildInfo, following the FLUTTER_APP_FLAVOR pattern including its reserved-name guards;
  • exposes them as appBuildName / appBuildNumber constants in package:flutter/services.dart (new src/services/app_version.dart, same style as flavor.dart / flutter_version.dart);
  • adds tool tests (injection from pubspec, no injection without a version, environment/dart-define collision guards) and framework tests.

Like all String.fromEnvironment constants, these are tree-shaken when unreferenced, so nothing ships in the binary unless the app reads them.

package_info_plus is ready to consume these defines (fluttercommunity/plus_plugins#3874), which would make the fix transparent for the ecosystem. A companion proposal for the pure-Dart side (dart compile, servers/CLIs) is dart-lang/sdk#38855 — neither subsumes the other, since Flutter does not build through dartdev.

Fixes #187934

Pre-launch Checklist

The tool already injects FLUTTER_VERSION, FLUTTER_CHANNEL, framework and
engine revisions (FlutterVersion) and FLUTTER_APP_FLAVOR (appFlavor) as
dart-defines. The application's own version from pubspec.yaml is the one
missing field, even though the tool already parses it
(FlutterManifest.buildName/buildNumber) and embeds it into version.json,
Info.plist and build.gradle.

Without it, the running version is unknowable on the web: version.json
is fetched from the server at runtime, so a stale cached client reports
the freshly deployed version instead of its own. Version gates and
update prompts built on package_info_plus silently fail for exactly the
users they exist for.

This injects FLUTTER_BUILD_NAME and FLUTTER_BUILD_NUMBER (from the
--build-name/--build-number flags, falling back to the pubspec version)
following the FLUTTER_APP_FLAVOR pattern, and exposes them as
appBuildName/appBuildNumber constants in package:flutter/services.dart.
Like all String.fromEnvironment constants they are tree-shaken when
unreferenced, so nothing ships unless the app reads them.
@github-actions github-actions Bot added tool Affects the "flutter" command-line tool. See also t: labels. framework flutter/packages/flutter repository. See also f: labels. labels Jun 12, 2026

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces 'appBuildName' and 'appBuildNumber' constants to the services library, allowing applications to access their build name and build number at runtime. These values are injected into 'dartDefines' during the build process, with validation to prevent users from manually overriding them. Feedback suggests refining the validation logic when checking existing 'dartDefines' to avoid false positives on custom variables that share a prefix with the framework-defined build variables.

Comment thread packages/flutter_tools/lib/src/runner/flutter_command.dart Outdated
Ortes added a commit to Fullphysio/plus_plugins that referenced this pull request Jun 12, 2026
…allbacks

PackageInfoEnvironment now resolves the web version from, in order:
PACKAGE_INFO_PLUS_VERSION (explicit), FLUTTER_BUILD_NAME
(flutter/flutter#187935, injected by flutter_tools like
FLUTTER_APP_FLAVOR), and dart.package.version (dart-lang/sdk#38855).
Once either upstream proposal lands, apps need no configuration at all.
Ortes added a commit to Fullphysio/plus_plugins that referenced this pull request Jun 12, 2026
…allbacks

PackageInfoEnvironment now resolves the web version from, in order:
PACKAGE_INFO_PLUS_VERSION (explicit), FLUTTER_BUILD_NAME
(flutter/flutter#187935, injected by flutter_tools like
FLUTTER_APP_FLAVOR), and dart.package.version (dart-lang/sdk#38855).
Once either upstream proposal lands, apps need no configuration at all.
User-provided defines that merely share a prefix with a reserved key
(e.g. FLUTTER_BUILD_NAMESPACE vs FLUTTER_BUILD_NAME) no longer trip the
reserved-key validation. Also fixes the same pre-existing prefix match
on FLUTTER_APP_FLAVOR.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

framework flutter/packages/flutter repository. See also f: labels. tool Affects the "flutter" command-line tool. See also t: labels.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose the app's build name/number as compile-time constants (complete the FlutterVersion/appFlavor pattern)

1 participant