工具安装

核心组件

工具安装系统围绕几个关键组件构建，这些组件负责管理工具环境、元数据和可执行访问。

已安装工具管理

InstalledTools 结构体是所有已安装工具的中心管理接口。它负责工具目录组织、环境生命周期和元数据持久化。

InstalledTools 结构体通过在配置的工具根目录下为每个工具创建单独的目录来管理工具隔离。每个工具都有自己的虚拟环境和元数据。

工具元数据结构

两个主要数据结构捕获工具安装元数据

结构	目的	关键字段
`工具`	安装元数据	`requirements`、`constraints`、`entrypoints`、`options`
`ToolEntrypoint`	可执行元数据	`name`、`install_path`

Tool 结构体跟踪安装期间使用的所有需求，包括主要需求、约束、覆盖和构建约束。这使得能够准确地重新安装和管理依赖关系。

来源： crates/uv-tool/src/tool.rs15-337 crates/uv-tool/src/tool.rs100-106

安装流程

工具安装过程遵循多阶段方法，该方法解析需求、创建环境和安装可执行文件。

安装流程处理几个关键场景

新工具安装
工具升级和重新安装
具有约束处理的依赖解析
Python解释器兼容性检查

来源： crates/uv/src/commands/tool/install.rs44-608

请求解析与解析

工具安装开始时，会将包规范解析为 ToolRequest，它可以表示不同的目标类型

解析阶段将用户输入转换为解析器可以处理的结构化 Requirement 对象。这包括处理版本说明符、extras 和源位置。

来源： crates/uv/src/commands/tool/install.rs101-224

工具环境管理

每个已安装的工具都会获得一个隔离的Python环境，以防止工具之间的依赖冲突。

Environment 创建

环境创建过程确保工具具有兼容的Python解释器和隔离的依赖空间

环境创建包括解释器细化，uv可以在初始解释器不满足工具的 requires-python 约束时自动选择不同的Python版本。

来源： crates/uv/src/commands/tool/install.rs432-593 crates/uv/src/commands/tool/common.rs73-159

环境持久化

工具环境以结构化布局持久化存储在文件系统中

tools/
├── {package_name}/
│   ├── pyvenv.cfg
│   ├── bin/python (or Scripts/python.exe)
│   ├── lib/python3.x/site-packages/
│   └── uv-receipt.toml
└── .lock

InstalledTools 结构体提供了管理此持久化的方法

create_environment() - 创建新的虚拟环境
get_environment() - 检索现有环境并进行验证
remove_environment() - 为卸载进行清理

来源： crates/uv-tool/src/lib.rs252-292 crates/uv-tool/src/lib.rs182-203

入口点安装

工具入口点是提供对已安装工具命令行访问的可执行脚本。安装系统会发现这些入口点并创建可访问的可执行文件。

入口点发现

通过检查工具的包元数据和已安装文件来发现入口点

entrypoint_paths() 函数读取包的 RECORD 文件以识别已安装的脚本和入口点，并过滤脚本目录中的可执行文件。

来源： crates/uv-tool/src/lib.rs398-441 crates/uv/src/commands/tool/common.rs162-335

可执行文件安装

install_executables() 函数处理使工具命令系统范围可用这一最后一步

平台	安装方法	位置
Unix	符号链接	`~/.local/bin/` 或 `$XDG_BIN_HOME`
Windows	文件复制	`%APPDATA%\uv\tools\bin\`

安装过程包括冲突检测，确保在没有明确的 --force 标志的情况下，不会覆盖现有可执行文件。

来源： crates/uv/src/commands/tool/common.rs197-335

工具收据系统

工具收据系统维护安装元数据，用于依赖管理、重新安装和卸载操作。

收据结构

工具收据以 TOML 文件形式存储，捕获完整的安装上下文

收据格式支持精确地重建安装环境，支持 --reinstall 和依赖兼容性检查等操作。

来源： crates/uv-tool/src/tool.rs160-308 crates/uv-tool/src/receipt.rs7-52

收据持久化

收据管理包括序列化为 TOML 格式，并采用结构化格式以便于维护

数组使用尾随逗号和换行符以便于清晰的 diff
需求保留原始规格详情
选项捕获在安装过程中使用的解析器和安装程序设置

add_tool_receipt() 方法处理原子收据更新，确保即使操作中断，安装元数据也能保持一致。

来源： crates/uv-tool/src/lib.rs154-171 crates/uv-tool/src/tool.rs190-308