Deep Diving into Flutter’s SDK upgrade process
How Flutter updates its SDK through the command “flutter upgrade”
Every time a new version of Flutter is available to upgrade to, the console says at the start of the output when a Flutter command is used:
A new version of Flutter is available!
To update to the latest version, run “flutter upgrade”.
What’s happening underneath this command?
If you search Google for: “flutter upgrade command GitHub”, the very first link you’ll see is the “upgrade.dart” file in the official Flutter GitHub repository.
Well, this repository is already cloned on your computer if you have Flutter installed. So opening this file under: “<flutter_directory>/packages/flutter_tools/lib/src/commands/upgrade.dart” you can go through the source code of the upgrading process.
This command is separated into two halves:
- The first half starts by running the “flutter upgrade” command.
- The second half starts by running the “flutter upgrade” command AGAIN, but this time the flag “ — continue” needs to be added.
Let’s see what these halves are offering!
Half #1: Synchronizing changes with the remote git repository
This involves many git operations to check for the eligibility of downloading the new changes from the Flutter remote repository:
1- Fetching the remote commit changes of the Flutter repository:
This is done by running “git fetch”.
2- Getting the latest commit revision of the current branch’s upstream:
This is done using “git rev-parse”, and its output is the actual latest commit revision of the current branch we’re checked out to.
Any of the two above git commands can result in some errors, two of the handled error cases are:
- “fatal: HEAD does not point to a branch”
Meaning the current HEAD of the local repository is detached and not pointing to a branch, which can be fixed by checking out to an existing branch, or by doing it using the recommended way, by switching the Flutter channel. - “fatal: no upstream configured for branch”
Meaning the local Flutter repository is detached from the remote repository, or the current local branch does not have a corresponding remote branch. The recommended way to fix it is by reinstalling Flutter.
Other than that, the error message from the git command gets printed directly and the flutter upgrade command gets aborted.
3- Checking the remote repository URL for being “standard”
This means that the local repository is tied to either:
“https://github.com/flutter/flutter.git” through HTTPS, or
“git@github.com:flutter/flutter.git” through SSH.
Any other URLs configured for the remote repository and the upgrade will be denied.
4- No current uncommitted local changes are present
Once the remote revision is fetched successfully, and no uncommitted changes to the local repository are present, then synchronizing with the new changes can be started.
If not, the command is terminated, but the user can optionally re-run the flutter upgrade command to destroy the current local changes.
5- Hard resetting to the latest remote commit revision
This is done by using “git reset” but with a “--hard” flag.
The reset command is used instead of a normal pull command because we may be on a release branch with cherry-picks, and may not have a direct fast-forward route to the next release that we’re looking for.
Once all of these git commands finish successfully, we have the new changes, and your Flutter version is bumped up!
Phew! That’s a lot of git operations!
Half #2: Synchronizing dependencies and setting up
This involves the following steps:
1- Precaching Flutter’s engine artifacts
Flutter needs a set of artifacts (which are native libraries) to be able to run on specific platforms with various architectures, these files are determined at this stage and get downloaded and cached at “<flutter_directory>/bin/cache/artifacts/engine”
2- Updating the dependencies of Flutter’s directories, each with a pubspec.yaml file
This is done using the good old “pub get” command. Flutter is written with Dart, and some Dart dependencies are required to make Flutter fully functional.
3- Running Flutter Doctor
Finally, “flutter doctor” runs to check if any of the requirements have been changed in the new Flutter release.
And that’s it! That is what the “flutter upgrade” command is doing under the hood!
If you liked this kind of deep diving, let me know in the comment section!
Happy Fluttering!
#Note: This article was written on 27/11/2022, the Flutter version which is used at that time is 3.3.5, any future changes to the existing commands code can make the article partially or fully out of date.
