Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,15 @@ Behavior that only exists on `main` and not in the latest release is marked "Unr
pages below. [docs/changes.md](docs/changes.md) lists it, and
[docs/install-from-source.md](docs/install-from-source.md) gets you `main`.

## Use cases

By hand, Flutter is a download, an unpack and an edit of `~/.bashrc`, again for every machine and
every version. With the plugin it is `vfox install` and `vfox use`, and `~/.bashrc` has the one
line that hooks vfox into your shell and nothing about Flutter. [docs/use-cases.md](docs/use-cases.md)
sets the two side by side and goes through the situations the plugin is for: a new machine, or one
that has a hand-made install; projects and teams that each use their own Flutter version; upgrading
and going back; trying a beta; a mirror in China; scripts and IDEs; and ARM64 machines.

## Versions and names

A version is a release as `vfox search flutter` prints it: `3.47.4`, or a beta such as
Expand Down
4 changes: 4 additions & 0 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ dart --version

只存在于 `main`、还没进入最新发布版的行为,在下面各页里标有“未发布”。完整列表见 [docs/zh-CN/changes.md](docs/zh-CN/changes.md),想直接用上 `main`,见 [docs/zh-CN/install-from-source.md](docs/zh-CN/install-from-source.md)。

## 使用场景

手动安装 Flutter,就是下载、解压,再改一次 `~/.bashrc`,每台机器、每个版本都要重来一遍。用这个插件只需要 `vfox install` 和 `vfox use`,`~/.bashrc` 里只有把 vfox 挂到 Shell 上的那一行,没有任何和 Flutter 有关的内容。[docs/zh-CN/use-cases.md](docs/zh-CN/use-cases.md) 把两种做法并排放在一起,并逐个讲了插件适用的场景:新机器,或者已经手动装过 Flutter 的机器;各个项目、整个团队各用各的 Flutter 版本;升级与回退;试用 beta;中国的镜像;脚本与 IDE;以及 ARM64 机器。

## 版本与命名

版本就是 `vfox search flutter` 打印出的发布版本:`3.47.4`,或者 `3.50.0-0.1.pre` 这样的 beta。后面加 `-x64` 或 `-arm64`,表示要这个架构而不是本机架构;`stable` 和 `beta` 代表该渠道当前指向的版本。版本必须整串匹配,所以 `flutter@3.47` 不会选中最新的 3.47.x。`vfox use`、`vfox uninstall` 和 `vfox exec` 要写已安装的名字,也就是 `vfox list flutter` 里显示的那个。`flutter@latest` 是列表的第一行,即最新的稳定版。名字、安装后的命名和列表的顺序见 [docs/zh-CN/versions.md](docs/zh-CN/versions.md)。
Expand Down
2 changes: 1 addition & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ Minutes later the same API answered in a second. Without a 429 a failing request
- **A release you expect is missing from `vfox search`.** vfox keeps the result for 12 hours. `vfox config cache.availableHookDuration 0` turns the cache off. Flutter's index may not have it yet either, or your mirror's copy may not.
- **`3.47.4` and `3.47.4-x64` are two installs.** On an x64 machine they are the same Flutter, see [versions.md](versions.md#installed-names).
- **Uninstalling a version switched the global one.** vfox selects the first entry left in `vfox list flutter` when you uninstall the version in use, and that can be a beta.
- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager. `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`.
- **`flutter` is a different Flutter than `vfox use` says.** Another Flutter earlier in your `PATH` wins, such as a manual install in `~/develop/flutter` or one from a package manager. `command -v flutter` shows which one runs, and its path should start with `~/.vfox/sdks/flutter/bin` or, in a project, `.vfox/sdks/flutter/bin`. A project's choice applies only in the directory that holds its `.vfox.toml`, not in the subdirectories, and vfox changes `PATH` when the prompt is shown, so `cd project && flutter run` on one line still runs the Flutter of the directory you came from, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions).
- **Flutter says "A new version of Flutter is available!" and suggests `flutter upgrade`.** Ignore it: `flutter upgrade` moves the SDK under vfox, see [flutter-upgrade.md](flutter-upgrade.md). `vfox install flutter@stable` is the upgrade. `flutter --no-version-check` leaves the banner out.
- **`FLUTTER_ROOT` is not set.** The plugin sets only `PATH`. The `flutter` script finds its own directory.
- **`dart` is there without a Dart plugin.** The Flutter SDK includes the Dart SDK, and `dart` is in its `bin`. There is no need to add the [vfox-dart](https://github.com/version-fox/vfox-dart) plugin next to it.
Expand Down
184 changes: 184 additions & 0 deletions docs/use-cases.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
# Use cases

[中文](zh-CN/use-cases.md) | [English](use-cases.md)

What the plugin is for, as situations you may be in. Each one gives the commands with the plugin, says what the same takes by hand where that helps, and links to the page that has the details. The commands were run in Bash on Ubuntu 26.04.1 (x64) with vfox 1.0.13 and plugin 0.2.5 on 2026-11-03, when Flutter's release index had `3.47.9` as `stable` and `3.50.0-0.3.pre` as `beta`. What vfox itself does (the shell hook, the scopes, `vfox install --all`) is what 1.0.13 does, and other versions may differ.

## A new machine

Installing Flutter by hand is a download, an unpack and an edit of `~/.bashrc`, and the address of the download depends on the operating system, the channel and the version. The plugin does the same with three commands.

### Ubuntu 26.04.1

Execute in Bash,

```bash
curl --location --output /tmp/flutter_linux.tar.xz https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.47.4-stable.tar.xz
mkdir -p ~/develop/
tar -xf /tmp/flutter_linux.tar.xz -C ~/develop/
rm -rf /tmp/flutter_linux.tar.xz
echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

With the plugin that is,

```bash
vfox add flutter
vfox install flutter@3.47.4
vfox use --global flutter@3.47.4
```

Both end with the same Flutter on the `PATH`, and `flutter --version --no-version-check` starts with `Flutter 3.47.4 • channel stable • https://github.com/flutter/flutter.git`. The archive is the same file, too. Step by step:

| By hand | With the plugin |
| --- | --- |
| Build the address of the archive from the operating system, the channel and the version, and `curl` it | `vfox install flutter@3.47.4` finds the release in Flutter's release index, which lists the archive for your operating system and CPU |
| Nothing compares the download with a checksum | vfox verifies it against the SHA-256 of the index and prints `Verifying checksum ...` |
| `mkdir -p ~/develop/` and `tar -xf ...` put one Flutter in one place, `~/develop/flutter` | Every version gets a directory of its own, `~/.vfox/cache/flutter/v-3.47.4/flutter-3.47.4/` |
| `rm -rf /tmp/flutter_linux.tar.xz` | vfox removes the archive after unpacking |
| `echo ... >> ~/.bashrc` and `source ~/.bashrc` | `vfox use --global flutter@3.47.4` |

The last row is the point. vfox has to be hooked into your shell once, with a line that has nothing to do with Flutter and that every SDK you manage with vfox shares (vfox's [quick start](https://vfox.dev/guides/quick-start.html) has the line for other shells):

```bash
echo 'eval "$(vfox activate bash)"' >> ~/.bashrc
source ~/.bashrc
```

After that nothing about Flutter is ever added to `~/.bashrc`, edited in it or removed from it: not when you install another version, not when you switch, not when you uninstall. `vfox use` stops in a shell without the hook: `vfox requires hook support. Please ensure vfox is properly initialized with 'vfox activate'`. The hook runs before each prompt, so a terminal that was open before you switched picks the new choice up at its next prompt. By hand every open terminal has to run `source ~/.bashrc` or be restarted, and the `echo` line puts the `PATH` line in a second time when you run it a second time.

On macOS and Windows the steps by hand are the same, with the `.zip` for your CPU (`flutter_macos_arm64_3.47.4-stable.zip`, `flutter_windows_3.47.4-stable.zip`) and `~/.zshrc` or your user `Path` variable. The three commands with the plugin stay the same, and only the line that hooks vfox into your shell depends on the shell, see [platforms.md](platforms.md).

## You already installed Flutter by hand

Until you select a version with vfox, `flutter` is still the copy in `~/develop/flutter`. Install the version you use, select it, and ask which `flutter` runs.

### Ubuntu 26.04.1

Execute in Bash,

```bash
vfox install flutter@3.47.4
vfox use --global flutter@3.47.4
command -v flutter
```

`command -v flutter` prints `~/.vfox/sdks/flutter/bin/flutter` with your home directory spelled out. vfox puts its directory in front of the old one in `PATH`, whether the `PATH` line comes before or after the hook in `~/.bashrc`, so the new Flutter runs without any other change. To tidy up, look up the old line:

```bash
grep -n 'develop/flutter/bin' ~/.bashrc
```

Delete the line it prints in your editor, open a new terminal (the one you are in still has the old `PATH`), and remove the old SDK:

```bash
rm -rf ~/develop/flutter
```

Flutter's own settings (`~/.config/flutter`) and the pub cache (`~/.pub-cache`) are in your home directory, not in the SDK, so they carry over to the new install.

## Projects on different Flutter versions

An older app has to stay on `3.44.0` while a new one uses `3.47.4`. By hand that is two directories and a `PATH` that you change whenever you switch. With the plugin each version is installed once, and each project says which one it uses:

```bash
vfox install flutter@3.44.0
vfox install flutter@3.47.4
cd ~/work/legacy_app
vfox use --project flutter@3.44.0
cd ~/work/new_app
vfox use --project flutter@3.47.4
```

`vfox use --project` writes the choice to `.vfox.toml` in the project directory (`flutter = "3.44.0"` under `[tools]`) and links the SDK at `.vfox/sdks/flutter`. While you are in that directory `flutter` is the project's Flutter, and in any other directory it is the one you chose with `--global`:

```
$ cd ~/work/legacy_app
$ flutter --version --no-version-check | sed -n 1p
Flutter 3.44.0 • channel stable • https://github.com/flutter/flutter.git
$ cd ~/work/new_app
$ flutter --version --no-version-check | sed -n 1p
Flutter 3.47.4 • channel stable • https://github.com/flutter/flutter.git
```

Every version is a full SDK on disk, see [platforms.md](platforms.md#requirements). Three things about the scopes:

- **The choice applies in the directory that holds `.vfox.toml`, not in its subdirectories.** In `~/work/legacy_app/lib`, `flutter` comes from the session or the global choice. `vfox current flutter` shows which version applies where you are.
- **The hook changes `PATH` when the prompt is shown.** `cd ~/work/new_app && flutter run` on one line still runs the Flutter of the directory you came from. `cd` first and run `flutter` after.
- **`.vfox/` stays out of git.** vfox adds it to the `.gitignore` of the project when there is one and prints `Added '.vfox/' to .gitignore`. It does not create a `.gitignore`.

## A team on one Flutter

Commit `.vfox.toml` and the `.gitignore` change, and everybody builds the project with the Flutter it was written for, and not with whichever one their machine happens to have. Someone who clones the project runs this in its directory:

```bash
vfox add flutter
vfox install --all
vfox use --project flutter@3.44.0
```

`vfox install --all` installs the versions that `.vfox.toml` lists, and asks first (`--yes` skips the question). It does not select them. That is what `vfox use --project` is for, with the version from `.vfox.toml`, and it writes the same `.vfox.toml` again, so git has nothing new to commit. `vfox add flutter` comes first because on a machine without the plugin, `vfox install --all` only adds the plugin, and the SDK follows with the next one.

## Upgrading, and going back

A new Flutter is installed next to the old one, and nothing changes until you select it. `vfox install flutter@stable` installs the release the stable channel points to (`3.47.9` on 2026-11-03):

```bash
vfox install flutter@stable
vfox use --global flutter@3.47.9
```

If the new release breaks something, the old one is still installed:

```bash
vfox use --global flutter@3.47.4
```

`vfox uninstall flutter@3.47.9` removes the release you do not want, and only its directory. `flutter upgrade` changes the SDK in place instead, where vfox does not see it, and what `vfox list flutter` says is then no longer what runs, see [flutter-upgrade.md](flutter-upgrade.md). That is why you can ignore the "A new version of Flutter is available!" box that suggests `flutter upgrade`: `vfox install flutter@stable` is the upgrade, see [troubleshooting.md](troubleshooting.md#things-that-look-wrong-and-are-not).

## Trying a beta in one terminal

```bash
vfox install flutter@beta
vfox use --session flutter@3.50.0-0.3.pre
```

The session choice is for this terminal. The others keep the version they had, and a new terminal does not have the beta. The beta stays installed until you `vfox uninstall flutter@3.50.0-0.3.pre`. `flutter@beta` is replaced by the release it points to (`3.50.0-0.3.pre` on 2026-11-03), and `vfox use` takes that name, see [channels.md](channels.md#use-the-version-not-the-channel).

## A mirror

When `storage.googleapis.com` is slow or cannot be reached, the address by hand changes its host, for example to the CFUG mirror:

```bash
curl --location --output /tmp/flutter_linux.tar.xz https://storage.flutter-io.cn/flutter_infra_release/releases/stable/linux/flutter_linux_3.47.4-stable.tar.xz
```

With the plugin you set `FLUTTER_STORAGE_BASE_URL` once, and every install takes the index and the archive from there:

```bash
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
vfox install flutter@3.47.4
```

The `flutter` tool reads the same variable for what it downloads when you first use it, so keep it set in your shell and not only while you install. How to make it permanent, the other mirrors, and `PUB_HOSTED_URL` for packages, which the plugin does not touch, are in [mirror.md](mirror.md).

## Scripts, containers and IDEs

`vfox use` needs the hook, which a script, a container build or a CI step does not have. `vfox exec` runs one command with the Flutter you name, hook or not:

```bash
vfox exec flutter@3.47.4 -- flutter --version --no-version-check
```

An IDE that should follow your global choice can take `~/.vfox/sdks/flutter` as its Flutter SDK path, and then needs no change when you switch versions. See [Where Flutter is](troubleshooting.md#where-flutter-is).

## ARM64 machines and OpenHarmony

Google publishes no Flutter archive for Linux ARM64 or Windows ARM64, so by hand Flutter comes from a `git clone` of `flutter/flutter`. The plugin does that for the plain name:

```bash
vfox install flutter@3.47.4
```

It offers the releases whose Flutter tool runs with a native Dart SDK there, see [arm64.md](arm64.md). The OpenHarmony fork of Flutter on gitcode.com installs the same way (`vfox install flutter@3.41.10-ohos-1.0.0`), see [ohos.md](ohos.md).
2 changes: 1 addition & 1 deletion docs/versions.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Pick the scope with `vfox use`'s flags: `--global`, `--project` or `--session`.
| `--project` | `.vfox.toml` in the current directory | `.vfox/sdks/flutter/bin` in that directory |
| `--session` | the current shell only | a directory under `~/.vfox/tmp` |

`.vfox.toml` holds the installed name (`flutter = "3.47.4"`). Commit it, so that the project builds with one Flutter for everybody, and keep `.vfox/` out of git: vfox does not add it to your `.gitignore`. vfox also reads an asdf `.tool-versions` (`flutter 3.47.4`) when its `legacyVersionFile.enable` setting is on, which it is by default in vfox 1.0.13. The plugin has no legacy file of its own, so `.fvmrc` and FVM's `.fvm` directory are not read.
`.vfox.toml` holds the installed name (`flutter = "3.47.4"`). Commit it, so that the project builds with one Flutter for everybody, and keep `.vfox/` out of git: vfox 1.0.13 adds it to the `.gitignore` of the project when there is one (it prints `Added '.vfox/' to .gitignore`), and does not create a `.gitignore`. The choice applies in the directory that holds `.vfox.toml` and not in its subdirectories, where `flutter` comes from the session or the global choice, see [use-cases.md](use-cases.md#projects-on-different-flutter-versions). vfox also reads an asdf `.tool-versions` (`flutter 3.47.4`) when its `legacyVersionFile.enable` setting is on, which it is by default in vfox 1.0.13. The plugin has no legacy file of its own, so `.fvmrc` and FVM's `.fvm` directory are not read.

The plugin adds `<sdk>/bin` to `PATH`. That puts `flutter` and `dart` on it. It sets no `FLUTTER_ROOT`, and `~/.pub-cache/bin`, where `dart pub global activate` puts executables, stays yours to add.

Expand Down
2 changes: 1 addition & 1 deletion docs/zh-CN/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,7 @@ gitcode.com 限制匿名客户端的请求次数。超出限制时它回答 HTTP
- **预期的版本在 `vfox search` 里没有。** vfox 会把结果缓存 12 小时。`vfox config cache.availableHookDuration 0` 可以关掉缓存。也可能是 Flutter 的索引里还没有它,或者你的镜像那份里还没有。
- **`3.47.4` 和 `3.47.4-x64` 是两份安装。** 在 x64 机器上它们是同一个 Flutter,见 [versions.md](versions.md#已安装的名称)。
- **卸载一个版本后,全局版本被换掉了。** 卸载正在使用的版本时,vfox 会选 `vfox list flutter` 里剩下的第一项,那可能是个 beta。
- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。
- **`flutter` 运行的不是 `vfox use` 选的那个 Flutter。** `PATH` 里更靠前的另一个 Flutter 会胜出,比如手动装在 `~/develop/flutter` 的,或者包管理器装的。`command -v flutter` 能看到实际运行的是哪一个,它的路径应当以 `~/.vfox/sdks/flutter/bin` 开头,在项目里则是 `.vfox/sdks/flutter/bin`。项目里的选择只在 `.vfox.toml` 所在的目录生效,子目录里不生效;vfox 又是在提示符出现时才改 `PATH`,所以把 `cd project && flutter run` 写在一行里,运行的还是上一个目录的 Flutter,见 [use-cases.md](use-cases.md#项目用不同的-flutter-版本)。
- **Flutter 说“A new version of Flutter is available!”并建议执行 `flutter upgrade`。** 别理它:`flutter upgrade` 会在 vfox 的背后改动 SDK,见 [flutter-upgrade.md](flutter-upgrade.md)。`vfox install flutter@stable` 才是升级。`flutter --no-version-check` 可以不显示这条提示。
- **`FLUTTER_ROOT` 没有设置。** 插件只设置 `PATH`。`flutter` 脚本会自己找到它所在的目录。
- **没有装 Dart 插件,`dart` 却在。** Flutter SDK 包含 Dart SDK,`dart` 就在它的 `bin` 里。不需要再另外添加 [vfox-dart](https://github.com/version-fox/vfox-dart) 插件。
Expand Down
Loading
Loading