Skip to content

Commit

Permalink
📃 docs: 更新文档
Browse files Browse the repository at this point in the history
  • Loading branch information
@wtklbm
wtklbm committed Sep 4, 2024
1 parent 28b163c commit 9663749
Showing 1 changed file with 10 additions and 10 deletions.
20 changes: 10 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# crm (Cargo registry manager)

[`crm`](https://github.com/wtklbm/crm) 是一个在终端运行的镜像管理程序，能够对 `Cargo` 镜像源进行简单的添加、修改、删除操作，并能帮助您快速的切换不同的 `Cargo` 镜像源。`crm` 内置了多种国内 (中国) 镜像源，它们分别是：`sjtu`, `tuna`, `ustc`, `rsproxy`，`bfsu`, `nju`, `hit`。
[`crm`](https://github.com/wtklbm/crm) 是一个在终端运行的镜像管理程序，能够对 `Cargo` 镜像源进行简单的添加、修改、删除操作，并能帮助您快速的切换不同的 `Cargo` 镜像源。`crm` 内置了多种国内 (中国) 镜像源，它们分别是：`sjtu`, `tuna`, `ustc`, `rsproxy`，`bfsu`, `nju`, `cqu`, `zju`, `cernet`。


在使用 Rust 语言做开发时，使用 Rust 官方镜像源进行 `cargo build` 的速度非常的慢，可能会因为网络的原因导致依赖下载超时而无法完成编译。为了能够在最少的时间内完成打包操作，一般会使用国内镜像源来代替官方镜像。


通常，大家一般会手动修改 `~/.cargo/config` 文件来完成镜像的切换，手动修改配置文件的工作是繁琐的，它需要手动打开文件所在的目录，还要记住每一个镜像源的地址和配置方式，在不知道哪个国内源的网速最快的时候，我们还需要对镜像的速度进行手动的测速，在使用国内镜像源的过程中，如果当前所使用的国内镜像源也挂了，我们还需要切换到另一个国内镜像源，这就显得非常的棘手。如果您手动配置了国内镜像源，并且还经常的通过 `cargo publish` 发包的话 ，那么在发包之前，还需要将国内镜像源再手动切换为官方镜像。在比如，每一个国内镜像源同步镜像的时间是不一样的，如果您刚发了一个包并且想第一时间应用到您的项目中，但是因为国内镜像源的没有及时的同步镜像，而导致包无法下载，这个时候您还需要切换到官方镜像源来下载最新发布的包。每一次手动切换镜像的操作都是繁琐且耗时的，而 `crm` 就是为了解决上述的问题。
通常，大家一般会手动修改 `~/.cargo/config.toml` 文件来完成镜像的切换，手动修改配置文件的工作是繁琐的，它需要手动打开文件所在的目录，还要记住每一个镜像源的地址和配置方式，在不知道哪个国内源的网速最快的时候，我们还需要对镜像的速度进行手动的测速，在使用国内镜像源的过程中，如果当前所使用的国内镜像源也挂了，我们还需要切换到另一个国内镜像源，这就显得非常的棘手。如果您手动配置了国内镜像源，并且还经常的通过 `cargo publish` 发包的话 ，那么在发包之前，还需要将国内镜像源再手动切换为官方镜像。在比如，每一个国内镜像源同步镜像的时间是不一样的，如果您刚发了一个包并且想第一时间应用到您的项目中，但是因为国内镜像源的没有及时的同步镜像，而导致包无法下载，这个时候您还需要切换到官方镜像源来下载最新发布的包。每一次手动切换镜像的操作都是繁琐且耗时的，而 `crm` 就是为了解决上述的问题。



Expand Down Expand Up @@ -112,22 +112,22 @@ $ crm
- `tuna`
- `bfsu`
- `nju`
- `hit`
- ... 一切 `dl` 的值为 `https://crates.io/api/v1/crates` 的镜像都无法获得加速 (有关镜像详情，请参见 [constants.rs](https://github.com/wtklbm/crm/blob/main/src/constants.rs#L80) 文件)



## 在项目中使用来自不同镜像源的依赖

`crm` 在配置镜像源时，会默认在 `~/.cargo/config` 中多增加一个 `registries` 属性对象，通过增加该属性对象，您就可以在项目中应用来自于不同镜像源的依赖。比如您在使用官方镜像源时，可以通过在项目的 `Cargo.toml` 文件中指定依赖的 `registry` 属性来使用不同的国内镜像源。如果您已经在使用国内镜像源了，那么也可以通过修改 `registry` 属性的方式来切换到其他的国内镜像源。以下是一个示例。
`crm` 在配置镜像源时，会默认在 `~/.cargo/config.toml` 中多增加一个 `registries` 属性对象，通过增加该属性对象，您就可以在项目中应用来自于不同镜像源的依赖。比如您在使用官方镜像源时，可以通过在项目的 `Cargo.toml` 文件中指定依赖的 `registry` 属性来使用不同的国内镜像源。如果您已经在使用国内镜像源了，那么也可以通过修改 `registry` 属性的方式来切换到其他的国内镜像源。以下是一个示例。




```toml
# Cargo.toml

# 使用官方镜像源时，`registry` 属性可选的值为： `sjtu`, `tuna`, `ustc`, `rsproxy`, `bfsu`, `nju`, `hit`
# 如果您已经使用 `crm` 切换到了 `rsproxy` 镜像源，那么 `registry` 属性可选的值则为其他国内镜像：`sjtu`, `tuna`, `ustc`, `bfsu`, `nju`, `hit`
# 使用官方镜像源时，`registry` 属性可选的值为： `sjtu`, `tuna`, `ustc`, `rsproxy`, `bfsu`, `nju` ...
# 如果您已经使用 `crm` 切换到了 `rsproxy` 镜像源，那么 `registry` 属性可选的值则为其他国内镜像：`sjtu`, `tuna`, `ustc`, `bfsu`, `nju` ...
# 以此类推
# 值得注意的是，在使用国内镜像源时，您无法直接通过修改 `registry` 属性的方式使用官方镜像源
# 如果您想使用官方镜像源，那么请在终端执行 `crm default` 来切换到官方镜像
Expand Down Expand Up @@ -155,7 +155,7 @@ lazy_static = {version = "1.4.0", registry = "sjtu"}
按照官方说法，使用该协议有两种方式：

1. 将 `export CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse` 加入到 `.bashrc` 或 `.zshrc` 文件中
2. 或者编辑 `~/.cargo/config` 文件：
2. 或者编辑 `~/.cargo/config.toml` 文件：
```bash
[registries.crates-io]
protocol = "sparse"
Expand All @@ -176,8 +176,8 @@ lazy_static = {version = "1.4.0", registry = "sjtu"}
## 注意事项

1. `v0.1.0` 版本以下的 `.crmrc` 配置文件和最新版本的配置文件并不能相互兼容，如果您正在使用小于 `v0.1.0` 的版本，当您更新到最新版本时，请手动删除 `~/.crmrc` 文件
2. `crm` 会修改 `~/.cargo/config` 文件来进行镜像源的切换，如果您使用的是小于 `v0.1.3` 的版本，那么当您使用 `crm` 切换镜像时，`~/.cargo/config` 文件中的文档注释会被删除并且永远无法恢复，如果您在 `~/.cargo/config` 文件中保存了笔记或者文档，请尽快更新到最新版，在最新版中，对此进行了优化，不再自动删除文档注释 (除修改的字段外)
3. `crm` 默认会在 `~/.cargo/config` 文件中增加一个 `env.git-fetch-with-cli` 属性，值为 `true`，在使用 `crm` 时您无法删除该选项，如果您不想使用 `Git` 可执行文件进行 `Git` 操作，请手动修改 `~/.cargo/config` 文件并将 `git-fetch-with-cli` 的值修改为 `false`
2. `crm` 会修改 `~/.cargo/config.toml` 文件来进行镜像源的切换，如果您使用的是小于 `v0.1.3` 的版本，那么当您使用 `crm` 切换镜像时，`~/.cargo/config.toml` 文件中的文档注释会被删除并且永远无法恢复，如果您在 `~/.cargo/config.toml` 文件中保存了笔记或者文档，请尽快更新到最新版，在最新版中，对此进行了优化，不再自动删除文档注释 (除修改的字段外)
3. `crm` 默认会在 `~/.cargo/config.toml` 文件中增加一个 `env.git-fetch-with-cli` 属性，值为 `true`，在使用 `crm` 时您无法删除该选项，如果您不想使用 `Git` 可执行文件进行 `Git` 操作，请手动修改 `~/.cargo/config.toml` 文件并将 `git-fetch-with-cli` 的值修改为 `false`



Expand All @@ -189,7 +189,7 @@ lazy_static = {version = "1.4.0", registry = "sjtu"}
- 2: 写入的镜像地址有误
- 3: 写入的 `dl` 字段值有误
- 4: 命令无效
- 5: `config.json` 配置文件解析失败 (格式有误或字段缺失)
- 5: `config.toml` 配置文件解析失败 (格式有误或字段缺失)
- 6: 属性名错误
- 7: 不能删除内置镜像
- 8: 要删除的镜像不存在
Expand Down

0 comments on commit 9663749

Please sign in to comment.