From be66f3730a8e079f0de0ff5d089845265e472c85 Mon Sep 17 00:00:00 2001 From: Qiheng He Date: Tue, 3 Nov 2026 13:33:46 +0800 Subject: [PATCH] docs: explain the apt install line of the README example and run it first The README example installs curl, git, unzip, xz-utils, zip and libglu1-mesa with apt, and did not say where the line comes from or that it is different on every system. - README.md, README_CN.md: install the packages first, because the plugin runs git while it installs, and add a paragraph that explains the line. - docs/platforms.md, docs/zh-CN/platforms.md: a "System packages" section with the source of the command (Flutter's "Install Flutter manually" guide), what each package is for, why they come before `vfox install`, and what other systems need. --- README.md | 10 +++++++++- README_CN.md | 4 +++- docs/platforms.md | 33 ++++++++++++++++++++++++++++++++- docs/zh-CN/platforms.md | 33 ++++++++++++++++++++++++++++++++- 4 files changed, 76 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 41be94b..ac7228b 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,9 @@ https://github.com/version-fox/vfox-dart . ### Example: Ubuntu 26.04.1 ```bash +sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa vfox add flutter vfox install flutter@3.47.4 -sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa vfox use --global flutter@3.47.4 ``` @@ -41,6 +41,14 @@ flutter --version --no-version-check dart --version ``` +The `sudo apt install` line is not a vfox command, and it is not the same on every system. It +installs the packages that [Flutter's installation guide](https://docs.flutter.dev/install/manual) +asks for on Linux, with `apt`, the package manager of Ubuntu and other Debian-based distributions. +It comes first because the plugin runs `git` while it installs. Other Linux distributions have +their own package managers and package names, macOS gets `git` from the Xcode command-line tools +and Windows from Git for Windows. See [docs/platforms.md](docs/platforms.md#system-packages) for +what each package is for and what other systems need. + `vfox search flutter` lists the versions you can install. In an interactive terminal it lets you pick one and installs it. diff --git a/README_CN.md b/README_CN.md index d31b059..8d15af3 100644 --- a/README_CN.md +++ b/README_CN.md @@ -21,9 +21,9 @@ Flutter SDK 自带 Dart SDK;如果通过本插件安装 Flutter SDK,就不 ### 示例:Ubuntu 26.04.1 ```bash +sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa vfox add flutter vfox install flutter@3.47.4 -sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa vfox use --global flutter@3.47.4 ``` @@ -34,6 +34,8 @@ flutter --version --no-version-check dart --version ``` +示例里的 `sudo apt install` 不是 vfox 命令,每个系统的命令也不一样。它用 `apt`(Ubuntu 和其他基于 Debian 的发行版的包管理器),安装 [Flutter 手动安装指南](https://docs.flutter.cn/install/manual)里为 Linux 要求的软件包。它排在最前面,是因为插件安装时要运行 `git`。其他 Linux 发行版有自己的包管理器和包名,macOS 的 `git` 来自 Xcode 命令行工具,Windows 的来自 Git for Windows。每个软件包的用途以及其他系统需要什么,见 [docs/zh-CN/platforms.md](docs/zh-CN/platforms.md#系统软件包)。 + `vfox search flutter` 会列出可以安装的版本,在交互式终端里还可以直接选一个并安装。 只存在于 `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)。 diff --git a/docs/platforms.md b/docs/platforms.md index 0f76589..424118c 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -21,9 +21,40 @@ What each machine gets for `3.47.4`, `3.47.4-x64` and `3.47.4-arm64` is in [arm6 - **vfox**, hooked into your shell, so that `flutter` is on the `PATH` after `vfox use`, see vfox's [quick start](https://vfox.dev/guides/quick-start.html). The plugin declares vfox 0.3.0 as the oldest it loads on. The tests run against the latest vfox release and against vfox's `main`, and a Windows account whose home directory contains a space needs vfox 1.0.13 or later ([vfox#712](https://github.com/version-fox/vfox/pull/712)). - **`git`**, for Linux ARM64 and Windows ARM64 (every install), for OpenHarmony builds, and for the drift check of [flutter-upgrade.md](flutter-upgrade.md). That check asks `git` for the SDK's commit when it installs; without `git` the install still succeeds, writes a `.vfox-manifest` that has no commit, and `vfox use` never warns. Flutter itself needs `git` as well. -- **Flutter's own tools.** Android, iOS, Linux, Windows and web development have requirements of their own (Android SDK, Xcode, Visual Studio, GTK and more). vfox does not install them, see [Flutter's installation guide](https://docs.flutter.dev/install). The example in the [README](../README.md#install) installs `curl git unzip xz-utils zip libglu1-mesa` for Ubuntu. +- **Flutter's own tools.** Android, iOS, Linux, Windows and web development have requirements of their own (Android SDK, Xcode, Visual Studio, GTK and more). vfox does not install them, see [Flutter's installation guide](https://docs.flutter.dev/install). The packages that the [README](../README.md#install) example installs on Ubuntu are a separate matter, see [System packages](#system-packages). - **Disk space.** An archive is 1.6 to 2.3 GB (see [versions.md](versions.md#installing)), and vfox removes it after unpacking. The SDK grows as the `flutter` tool downloads what it needs for the platforms you build for. A source install needs room for the checkout as well. Every name you install is a separate SDK, see [versions.md](versions.md#installed-names). +## System packages + +The example in the [README](../README.md#install) runs one command that is not a vfox command: + +```bash +sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa +``` + +It installs the packages that Flutter's [Install Flutter manually](https://docs.flutter.dev/install/manual#download-prerequisites) guide asks for on Linux. The guide gives `apt-get` as its example for Debian-based distributions such as Ubuntu, and the README writes `apt` and `--assume-yes`, the long form of `-y`. The guide runs `sudo apt-get update -y && sudo apt-get upgrade -y` first and the README leaves that out. In a fresh container such as `ubuntu:26.04`, update the package lists before the install (`apt update`): without them `apt` answers `Unable to locate package curl`. + +`sudo apt install --assume-yes` is the part that belongs to Debian, Ubuntu and their derivatives: `apt` is their package manager, `sudo` runs it as root, and `--assume-yes` answers its confirmation with yes. The six names after it are Flutter's list, in Debian's spelling. + +| Package | What Flutter uses it for | +| --- | --- | +| `git` | `flutter` and `dart` stop with `Unable to find git in your PATH` without it (`bin/internal/shared.sh`). The plugin runs `git` too, see [Requirements](#requirements). | +| `curl`, `unzip` | The first `flutter` run of a source install downloads the Dart SDK with `curl` and unpacks it with `unzip` (`bin/internal/update_dart_sdk.sh`). The `flutter` tool also uses `unzip` for the artifacts it downloads later. | +| `xz-utils` | Provides `xz`, which `tar` calls to read Flutter's Linux `.tar.xz` archive. Flutter's manual steps unpack it with `tar -xf`. vfox unpacks the archive itself, so `vfox install` does not call `xz`. | +| `zip` | Earlier versions of Flutter's guide list it among the command-line tools Flutter relies on, without saying what for. | +| `libglu1-mesa` | Provides `libGLU.so.1`, which `flutter test` needs according to earlier versions of Flutter's guide. | + +Install them before `vfox install`, as the README example does: the plugin runs `git` while it installs. Without `git`, a Linux ARM64 or Windows ARM64 install and an OpenHarmony build fail, and any other install succeeds with a `.vfox-manifest` that has no commit, so the drift check never warns, see [Requirements](#requirements). + +The command is different on every system. Flutter's guide tells you to use your own package manager and gives `apt-get` only as an example, and the names above are Debian's: Fedora, for one, calls the package that provides `libGLU.so.1` `mesa-libGLU`. + +| System | What to install | Command | +| --- | --- | --- | +| Ubuntu, Debian and other Debian-based distributions | the six packages above | `sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa` | +| Other Linux distributions | the same tools and library, under your distribution's package names | the install command of your package manager, such as `dnf` or `pacman` | +| macOS | the Xcode command-line tools, which bring the tools Flutter relies on, `git` among them | `xcode-select --install` | +| Windows | [Git for Windows](https://git-scm.com/downloads/win) | `winget install --id Git.Git --source winget --exact` | + ## Where the plugin connects | Host | What for | When | diff --git a/docs/zh-CN/platforms.md b/docs/zh-CN/platforms.md index b0526dd..124c9c6 100644 --- a/docs/zh-CN/platforms.md +++ b/docs/zh-CN/platforms.md @@ -21,9 +21,40 @@ OpenHarmony 构建版本在每种机器上都是从 gitcode.com 检出的,见 - **vfox**,并且已经挂载到 Shell,这样 `vfox use` 之后 `flutter` 才在 `PATH` 里,见 vfox 的[快速入门](https://vfox.dev/zh-hans/guides/quick-start.html)。插件声明 vfox 0.3.0 是它能加载的最老版本。测试跑的是最新的 vfox 发布版和 vfox 的 `main`;主目录里带空格的 Windows 账户需要 vfox 1.0.13 或更新的版本([vfox#712](https://github.com/version-fox/vfox/pull/712))。 - **`git`**:Linux ARM64 和 Windows ARM64 的每次安装、OpenHarmony 构建版本,以及 [flutter-upgrade.md](flutter-upgrade.md) 里的漂移检查都要用。漂移检查在安装时向 `git` 要 SDK 的提交;没有 `git` 时安装依然会成功,写出的 `.vfox-manifest` 里没有提交,`vfox use` 永远不会警告。Flutter 本身也需要 `git`。 -- **Flutter 自己的工具。** Android、iOS、Linux、Windows 和 Web 开发各有各的要求(Android SDK、Xcode、Visual Studio、GTK 等等),vfox 不会安装它们,见 [Flutter 的安装指南](https://docs.flutter.cn/install)。[README](../../README_CN.md#安装) 里的示例为 Ubuntu 装了 `curl git unzip xz-utils zip libglu1-mesa`。 +- **Flutter 自己的工具。** Android、iOS、Linux、Windows 和 Web 开发各有各的要求(Android SDK、Xcode、Visual Studio、GTK 等等),vfox 不会安装它们,见 [Flutter 的安装指南](https://docs.flutter.cn/install)。[README](../../README_CN.md#安装) 示例在 Ubuntu 上装的那些软件包是另一回事,见[系统软件包](#系统软件包)。 - **磁盘空间。** 压缩包 1.6 到 2.3 GB(见 [versions.md](versions.md#安装)),vfox 解压后会把它删掉。Flutter 工具会为你要构建的平台下载所需的内容,SDK 会随之变大。源码安装还要给检出留出空间。你安装的每个名字都是一个独立的 SDK,见 [versions.md](versions.md#已安装的名称)。 +## 系统软件包 + +[README](../../README_CN.md#安装) 的示例里有一条命令不是 vfox 命令: + +```bash +sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa +``` + +它安装的是 Flutter 的[手动安装指南](https://docs.flutter.cn/install/manual#download-prerequisites)里为 Linux 要求的软件包。指南以 `apt-get` 作为基于 Debian 的发行版(比如 Ubuntu)的示例,README 写成 `apt` 和 `--assume-yes`(`-y` 的长写法)。指南先执行 `sudo apt-get update -y && sudo apt-get upgrade -y`,README 没有这一步。在全新的容器里(比如 `ubuntu:26.04`),安装前要先更新软件包列表(`apt update`),否则 `apt` 会报 `Unable to locate package curl`。 + +`sudo apt install --assume-yes` 是属于 Debian、Ubuntu 及其衍生版的部分:`apt` 是它们的包管理器,`sudo` 以 root 身份运行它,`--assume-yes` 对它的确认一律回答“是”。后面的六个名字是 Flutter 给出的清单,写法是 Debian 的包名。 + +| 软件包 | Flutter 用它做什么 | +| --- | --- | +| `git` | 没有它,`flutter` 和 `dart` 会停在 `Unable to find git in your PATH`(`bin/internal/shared.sh`)。插件自己也要运行 `git`,见[前提条件](#前提条件)。 | +| `curl`、`unzip` | 源码安装第一次运行 `flutter` 时,用 `curl` 下载 Dart SDK,用 `unzip` 解压(`bin/internal/update_dart_sdk.sh`)。`flutter` 工具之后下载的产物,也由 `unzip` 解压。 | +| `xz-utils` | 提供 `xz`,`tar` 靠它读取 Flutter 的 Linux `.tar.xz` 压缩包。Flutter 的手动步骤用 `tar -xf` 解压它;vfox 自己解压压缩包,所以 `vfox install` 不会调用 `xz`。 | +| `zip` | 旧版 Flutter 指南把它列在 Flutter 依赖的命令行工具里,没有说明用途。 | +| `libglu1-mesa` | 提供 `libGLU.so.1`;按旧版 Flutter 指南的说法,`flutter test` 需要它。 | + +请在 `vfox install` 之前装好它们,README 的示例就是这样:插件安装时会运行 `git`。没有 `git`,Linux ARM64 和 Windows ARM64 的安装以及 OpenHarmony 构建版本会失败,其他安装仍会成功,但 `.vfox-manifest` 里没有提交,漂移检查就永远不会警告,见[前提条件](#前提条件)。 + +每个系统的命令都不一样。Flutter 的指南让你用自己的包管理器,`apt-get` 只是示例,而上面的名字是 Debian 的写法:比如 Fedora 里提供 `libGLU.so.1` 的包叫 `mesa-libGLU`。 + +| 系统 | 要安装什么 | 命令 | +| --- | --- | --- | +| Ubuntu、Debian 和其他基于 Debian 的发行版 | 上面的六个软件包 | `sudo apt install --assume-yes curl git unzip xz-utils zip libglu1-mesa` | +| 其他 Linux 发行版 | 同样的工具和库,用你的发行版里的包名 | 你的包管理器(比如 `dnf` 或 `pacman`)的安装命令 | +| macOS | Xcode 命令行工具,Flutter 依赖的工具(包括 `git`)随它而来 | `xcode-select --install` | +| Windows | [Git for Windows](https://git-scm.com/downloads/win) | `winget install --id Git.Git --source winget --exact` | + ## 插件会连接的地址 | 主机 | 用来做什么 | 什么时候 |