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.

if (globals.platform.environment[define] != null) {
throwToolExit('$define is used by the framework and cannot be set in the environment.');
}
if (dartDefines.any((String d) => d.startsWith(define))) {

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.

high

Using d.startsWith(define) can cause false positives if a user defines a custom dart-define that starts with the same prefix (e.g., FLUTTER_BUILD_NAME_SUFFIX or FLUTTER_BUILD_NUMBER_PREFIX). To prevent unexpected build failures, we should check for an exact match or a match followed by =.

Suggested change
if (dartDefines.any((String d) => d.startsWith(define))) {
if (dartDefines.any((String d) => d == define || d.startsWith('$define='))) {

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Good catch — fixed in 58b0f53 with an exact-key match (d == define || d.startsWith('$define=')), applied to the pre-existing FLUTTER_APP_FLAVOR check as well since it had the same prefix-match behaviour. Added a regression test covering user defines that share a prefix with each reserved key.

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