From 06d469ec4abc612640c624ae4931fc312f91dc34 Mon Sep 17 00:00:00 2001 From: Shengzhou Li Date: Thu, 27 Jan 2022 22:02:24 +0900 Subject: [PATCH] docs(website): add simplifed chinese (#1166) * docs(website): add simplifed chinese * docs: format some documentations --- docs/.vuepress/config.js | 19 + docs/.vuepress/navbar.js | 134 +++++- docs/.vuepress/sidebar.js | 116 ++++- docs/contribute/core.md | 8 +- docs/guide/getting-started.md | 6 +- docs/manage/core.md | 8 +- docs/pt-br/guide/getting-started.md | 24 +- docs/pt-br/guide/introduction.md | 2 +- docs/pt-br/learn-more/faq.md | 4 +- docs/pt-br/manage/core.md | 8 +- docs/zh-hans/contribute/core.md | 112 +++++ docs/zh-hans/contribute/documentation.md | 118 +++++ .../zh-hans/contribute/first-party-plugins.md | 14 + docs/zh-hans/contribute/github-actions.md | 3 + docs/zh-hans/guide/getting-started.md | 347 ++++++++++++++ docs/zh-hans/guide/introduction.md | 57 +++ docs/zh-hans/index.md | 26 ++ docs/zh-hans/learn-more/faq.md | 25 + docs/zh-hans/learn-more/thanks.md | 21 + docs/zh-hans/manage/commands.md | 5 + docs/zh-hans/manage/configuration.md | 110 +++++ docs/zh-hans/manage/core.md | 431 ++++++++++++++++++ docs/zh-hans/manage/plugins.md | 81 ++++ docs/zh-hans/manage/versions.md | 153 +++++++ docs/zh-hans/plugins/create.md | 296 ++++++++++++ 25 files changed, 2096 insertions(+), 32 deletions(-) create mode 100644 docs/zh-hans/contribute/core.md create mode 100644 docs/zh-hans/contribute/documentation.md create mode 100644 docs/zh-hans/contribute/first-party-plugins.md create mode 100644 docs/zh-hans/contribute/github-actions.md create mode 100644 docs/zh-hans/guide/getting-started.md create mode 100644 docs/zh-hans/guide/introduction.md create mode 100644 docs/zh-hans/index.md create mode 100644 docs/zh-hans/learn-more/faq.md create mode 100644 docs/zh-hans/learn-more/thanks.md create mode 100644 docs/zh-hans/manage/commands.md create mode 100644 docs/zh-hans/manage/configuration.md create mode 100644 docs/zh-hans/manage/core.md create mode 100644 docs/zh-hans/manage/plugins.md create mode 100644 docs/zh-hans/manage/versions.md create mode 100644 docs/zh-hans/plugins/create.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index f4e069535..afec69f39 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -14,6 +14,11 @@ module.exports = { lang: "pt-br", title: "asdf", description: "Gerencie múltiplas versões com um simples CLI" + }, + "/zh-hans/": { + lang: "zh-CN", + title: "asdf", + description: "管理多个运行环境版本的简单命令行工具" } }, @@ -38,6 +43,17 @@ module.exports = { // 404 page notFound: ["Parece que estamos perdido!"], backToHome: "Voltar para a página inicial" + }, + "/zh-hans/": { + selectLanguageName: "简体中文", + selectLanguageText: "选择语言", + sidebar: sidebar.zh_hans, + navbar: navbar.zh_hans, + editLinkText: "在 Github 编辑此页面", + + // 404 page + notFound: ["抱歉，您访问的页面不存在！"], + backToHome: "返回首页" } } }, @@ -52,6 +68,9 @@ module.exports = { }, "/pt-br/": { placeholder: "Search" + }, + "/zh-hans/": { + placeholder: "搜索" } } } diff --git a/docs/.vuepress/navbar.js b/docs/.vuepress/navbar.js index f9ca6fc0e..b291e29c4 100644 --- a/docs/.vuepress/navbar.js +++ b/docs/.vuepress/navbar.js @@ -259,4 +259,136 @@ const pt_br = [ } ]; -module.exports = { en, pt_br }; +const zh_hans = [ + { + text: "快速上手", + link: "/zh-hans/guide/getting-started.html", + activeMatch: "/zh-hans/guide/" + }, + { + text: "参考", + children: [ + { + text: "管理", + children: [ + "/zh-hans/manage/core.md", + "/zh-hans/manage/plugins.md", + "/zh-hans/manage/versions.md", + "/zh-hans/manage/configuration.md", + "/zh-hans/manage/commands.md", + { + text: "更新日志", + link: "https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md" + } + ] + } + ] + }, + { + text: "插件", + children: [ + { + text: "成为作者", + children: [ + "/zh-hans/plugins/create.md", + { + text: "插件模板", + link: "https://github.com/asdf-vm/asdf-plugin-template" + } + ] + }, + { + text: "官方插件", + children: [ + { + text: "Elixir", + link: "https://github.com/asdf-vm/asdf-elixir" + }, + { + text: "Erlang", + link: "https://github.com/asdf-vm/asdf-erlang" + }, + { + text: "Node.js", + link: "https://github.com/asdf-vm/asdf-nodejs" + }, + { + text: "Ruby", + link: "https://github.com/asdf-vm/asdf-ruby" + } + ] + }, + { + text: "社区插件", + children: [ + { + text: "asdf-community", + link: "https://github.com/asdf-community" + }, + { + text: "GitHub 主题搜索", + link: "https://github.com/topics/asdf-plugin" + } + ] + }, + { + text: "参考", + children: [ + { + text: "插件缩写索引", + link: "https://github.com/asdf-vm/asdf-plugins" + } + ] + } + ] + }, + { + text: "如何贡献", + children: [ + { + text: "核心", + children: [ + "/zh-hans/contribute/core.md", + "/zh-hans/contribute/documentation.md" + ] + }, + { + text: "插件", + children: ["/zh-hans/contribute/first-party-plugins.md"] + }, + { + text: "持续集成/持续部署", + children: ["/zh-hans/contribute/github-actions.md"] + } + ] + }, + { + text: "了解更多", + children: [ + { + text: "提问", + children: [ + "/zh-hans/learn-more/faq.md", + { + text: "GitHub Issues", + link: "https://github.com/asdf-vm/asdf/issues" + }, + { + text: "GitHub Discussions", + link: "https://github.com/asdf-vm/asdf/discussions" + }, + { + text: "StackOverflow Tag", + link: "https://stackoverflow.com/questions/tagged/asdf-vm" + } + ] + }, + { + text: "资源", + children: ["/zh-hans/learn-more/thanks.md"] + } + ] + } +]; + +module.exports = { en, pt_br, zh_hans }; diff --git a/docs/.vuepress/sidebar.js b/docs/.vuepress/sidebar.js index fa4f058a9..d58931d5b 100644 --- a/docs/.vuepress/sidebar.js +++ b/docs/.vuepress/sidebar.js @@ -215,4 +215,118 @@ const pt_br = { ] }; -module.exports = { en, pt_br }; +const zh_hans = { + "/zh-hans/guide/": [ + "/zh-hans/guide/introduction.md", + "/zh-hans/guide/getting-started.md" + ], + "/zh-hans/manage/": [ + { + text: "管理", + children: [ + "/zh-hans/manage/core.md", + "/zh-hans/manage/plugins.md", + "/zh-hans/manage/versions.md", + "/zh-hans/manage/configuration.md", + "/zh-hans/manage/commands.md", + { + text: "更新日志", + link: "https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md" + } + ] + } + ], + "/zh-hans/plugins/": [ + { + text: "成为作者", + children: [ + "/zh-hans/plugins/create.md", + { + text: "GitHub Plugin 模板", + link: "https://github.com/asdf-vm/asdf-plugin-template" + } + ] + }, + { + text: "官方插件", + children: [ + { + text: "Elixir", + link: "https://github.com/asdf-vm/asdf-elixir" + }, + { + text: "Erlang", + link: "https://github.com/asdf-vm/asdf-erlang" + }, + { + text: "Node.js", + link: "https://github.com/asdf-vm/asdf-nodejs" + }, + { + text: "Ruby", + link: "https://github.com/asdf-vm/asdf-ruby" + } + ] + }, + { + text: "社区插件", + children: [ + { + text: "asdf-community", + link: "https://github.com/asdf-community/" + }, + { + text: "GitHub 主题搜索", + link: "https://github.com/topics/asdf-plugin" + } + ] + }, + { + text: "参考", + children: [ + { + text: "插件缩写索引", + link: "https://github.com/asdf-vm/asdf-plugins" + } + ] + } + ], + "/zh-hans/contribute/": [ + { + text: "如何贡献", + children: [ + "/zh-hans/contribute/core.md", + "/zh-hans/contribute/documentation.md", + "/zh-hans/contribute/first-party-plugins.md", + "/zh-hans/contribute/github-actions.md" + ] + } + ], + "/zh-hans/learn-more/": [ + { + text: "常见问题", + children: [ + "/zh-hans/learn-more/faq.md", + + { + text: "GitHub Issues", + link: "https://github.com/asdf-vm/asdf/issues" + }, + { + text: "GitHub Discussions", + link: "https://github.com/asdf-vm/asdf/discussions" + }, + { + text: "StackOverflow Tag", + link: "https://stackoverflow.com/questions/tagged/asdf-vm" + } + ] + }, + { + text: "资源", + children: ["/zh-hans/learn-more/thanks.md"] + } + ] +}; + +module.exports = { en, pt_br, zh_hans }; diff --git a/docs/contribute/core.md b/docs/contribute/core.md index f86f031b0..84871a334 100644 --- a/docs/contribute/core.md +++ b/docs/contribute/core.md @@ -94,10 +94,10 @@ feat!: feature with breaking change The full list of `` are: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. -* `!`: indicates a breaking change -* `fix`: will create a new SemVer `patch` -* `feat`: will create a new SemVer `minor` -* `!`: will create a new SemVer `major` +- `!`: indicates a breaking change +- `fix`: will create a new SemVer `patch` +- `feat`: will create a new SemVer `minor` +- `!`: will create a new SemVer `major` The Pull Request Title must follow this format. diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index cf16144c1..021765d01 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -17,8 +17,8 @@ `sudo` may be required depending on your system configuration. ::: -| Package Manager | Command | -| --------------- | ------------------------------ | +| Package Manager | Command | +| --------------- | ------------------------- | | Aptitude | `apt install curl git` | | DNF | `dnf install curl git` | | Pacman | `pacman -S curl git` | @@ -243,7 +243,7 @@ Restart your shell so that `PATH` changes take effect. Opening a new terminal ta ## Core Installation Complete! -This completes the installation of the `asdf` core :tada: +This completes the installation of the `asdf` core :tada: `asdf` is only useful once you install a **plugin**, install a **tool** and manage its **versions**. Continue the guide below to learn how to do this. diff --git a/docs/manage/core.md b/docs/manage/core.md index cd0059858..bb22cd1af 100644 --- a/docs/manage/core.md +++ b/docs/manage/core.md @@ -68,11 +68,11 @@ nodejs 16.5.0 `asdf` has a built in command to update which relies on Git (our recommended installation method). If you installed using a different method you should follow the steps for that method: -| Method | Latest Stable Release | Latest commit on `master` | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | -| asdf (via Git) | `asdf update` | `asdf update --head` | +| Method | Latest Stable Release | Latest commit on `master` | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | +| asdf (via Git) | `asdf update` | `asdf update --head` | | Homebrew | `brew upgrade asdf` | `brew upgrade asdf --fetch-HEAD` | -| Pacman | Download a new `PKGBUILD` & rebuild
or use your preferred [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) | | +| Pacman | Download a new `PKGBUILD` & rebuild
or use your preferred [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) | | ## Uninstall diff --git a/docs/pt-br/guide/getting-started.md b/docs/pt-br/guide/getting-started.md index ee2da0d95..74b1f42b2 100644 --- a/docs/pt-br/guide/getting-started.md +++ b/docs/pt-br/guide/getting-started.md @@ -18,18 +18,18 @@ Você pode também acompanhar o passo a passo da instalação através [deste v **Linux**: | Gerenciador de Pacotes | Comando | -| --------------- | ------------------------------ | -| Aptitude | `sudo apt install curl git` | -| DNF | `sudo dnf install curl git` | -| Pacman | `sudo pacman -S curl git` | -| Zypper | `sudo zypper install curl git` | +| ---------------------- | ------------------------------ | +| Aptitude | `sudo apt install curl git` | +| DNF | `sudo dnf install curl git` | +| Pacman | `sudo pacman -S curl git` | +| Zypper | `sudo zypper install curl git` | **macOS**: -| Gerenciador de Pacotes | Comando | -| --------------- | --------------------------------------------------------- | -| Homebrew | As dependências serão automaticamente instaladas pelo Homebrew. | -| Spack | `spack install coreutils curl git` | +| Gerenciador de Pacotes | Comando | +| ---------------------- | --------------------------------------------------------------- | +| Homebrew | As dependências serão automaticamente instaladas pelo Homebrew. | +| Spack | `spack install coreutils curl git` | ## 2. Instalando o asdf @@ -194,7 +194,7 @@ Adicione a seguinte linha ao seu `~/.zshrc`: . $HOME/.asdf/asdf.sh ``` -**OU** utilize um framework para ZSH, como [asdf para oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) que irá adicionar o script e o auto completar. +**OU** utilize um framework para ZSH, como [asdf para oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) que irá adicionar o script e o auto completar. O auto completar pode ser configurado ou pelo plugin do asdf para framework para ZSH, ou através da adição das seguintes linhas ao seu `.zshrc`: @@ -221,7 +221,7 @@ Adicione `asdf.sh` ao seu `~/.zshrc` através do comando: echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc ``` -**OU** utilize um framework para ZSH, como [asdf para oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) que irá adicionar o script e o auto completar. +**OU** utilize um framework para ZSH, como [asdf para oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) que irá adicionar o script e o auto completar. O auto completar pode ser configurado ou pelo framework para ZSH, ou de acordo com as [instruções da Homebrew](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh). Se você está usando um framework para ZSH, pode ser que seja necessário atualizar o plugin do asdf para que o novo auto completar funcione adequadamente através do `fpath`. O plugin do asdf para o Oh-My-ZSH ainda será atualizado, veja: [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837). ::: @@ -249,7 +249,7 @@ Para demonstração, vamos instalar e configurar o [Node.js](https://nodejs.org/ Cada plugin possui algumas dependências, por isso precisamos checar no repositório onde elas estão listadas. Por exemplo, para o `asdf-nodejs` são: -| SO | Instalação de dependencia | +| SO | Instalação de dependencia | | -------------- | --------------------------------------- | | Linux (Debian) | `apt-get install dirmngr gpg curl gawk` | | macOS | `brew install gpg gawk` | diff --git a/docs/pt-br/guide/introduction.md b/docs/pt-br/guide/introduction.md index 1067a9bdf..a4b2974f8 100644 --- a/docs/pt-br/guide/introduction.md +++ b/docs/pt-br/guide/introduction.md @@ -36,7 +36,7 @@ Veja a [documentação do direnv](https://direnv.net/) para mais detalhes. > O gerenciador de pacotes faltante para o macOS (ou Linux) -O Homebrew gerencia seus pacotes e dependências destes pacotes. O `asdf` não gerencia dependencias, não é um gerenciador de pacotes, a escolha do gerenciador de pacotes é reservada ao usuário. +O Homebrew gerencia seus pacotes e dependências destes pacotes. O `asdf` não gerencia dependencias, não é um gerenciador de pacotes, a escolha do gerenciador de pacotes é reservada ao usuário. Veja a [documentação do Homebrew](https://brew.sh/) para mais detalhes. diff --git a/docs/pt-br/learn-more/faq.md b/docs/pt-br/learn-more/faq.md index df4d0e4d4..23ac77d07 100644 --- a/docs/pt-br/learn-more/faq.md +++ b/docs/pt-br/learn-more/faq.md @@ -18,8 +18,8 @@ Pretendemos executar o conjunto de testes no WSL2 quando o suporte ao host runne > Acabei de instalar o `npm -g yarn`, mas não consigo executar o `yarn`. O que da? -`asdf` usa [shims]() para gerenciar executáveis. Aqueles instalados por plug-ins têm shims criados automaticamente, enquanto a instalação de executáveis ​​por meio de uma ferramenta gerenciada `asdf` exigirá que você notifique o` asdf` sobre a necessidade de criar shims. Neste caso, para criar um shim para [Yarn](https://yarnpkg.com/). Veja a documentação do comando [`asdf reshim`](/ manage / core.md # reshim). +`asdf` usa [shims]() para gerenciar executáveis. Aqueles instalados por plug-ins têm shims criados automaticamente, enquanto a instalação de executáveis ​​por meio de uma ferramenta gerenciada `asdf` exigirá que você notifique o`asdf` sobre a necessidade de criar shims. Neste caso, para criar um shim para [Yarn](https://yarnpkg.com/). Veja a documentação do comando [`asdf reshim`](/ manage / core.md # reshim). ## Shell não detecta shims recém-instalados? -Se `asdf reshim` não está resolvendo seu problema, então é mais provável devido ao sourcing de` asdf.sh` ou `asdf.fish` _não_ estar no ** BOTTOM ** de seu arquivo de configuração Shell (`.bash_profile`, `.zshrc`, ` config.fish`, etc). Ele precisa ser fornecido **DEPOIS** de você definir seu `$PATH` e **DEPOIS** de ter fornecido seu framework (oh-meu-zsh etc), se houver. +Se `asdf reshim` não está resolvendo seu problema, então é mais provável devido ao sourcing de`asdf.sh` ou `asdf.fish` _não_ estar no ** BOTTOM ** de seu arquivo de configuração Shell (`.bash_profile`, `.zshrc`, `config.fish`, etc). Ele precisa ser fornecido **DEPOIS** de você definir seu `$PATH` e **DEPOIS** de ter fornecido seu framework (oh-meu-zsh etc), se houver. diff --git a/docs/pt-br/manage/core.md b/docs/pt-br/manage/core.md index 39d444bd0..a48a84d14 100644 --- a/docs/pt-br/manage/core.md +++ b/docs/pt-br/manage/core.md @@ -70,11 +70,11 @@ nodejs 16.5.0 `asdf` has a built in command to update which relies on Git (our recommended installation method). If you installed using a different method you should follow the steps for that method: -| Method | Latest Stable Release | Latest commit on `master` | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | -| asdf (via Git) | `asdf update` | `asdf update --head` | +| Method | Latest Stable Release | Latest commit on `master` | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | +| asdf (via Git) | `asdf update` | `asdf update --head` | | Homebrew | `brew upgrade asdf` | `brew upgrade asdf --fetch-HEAD` | -| Pacman | Obter manualmente um novo `PKGBUILD` e
reconstruir ou usar suas preferências de [AUR](https://wiki.archlinux.org/index.php/AUR_helpers). | | +| Pacman | Obter manualmente um novo `PKGBUILD` e
reconstruir ou usar suas preferências de [AUR](https://wiki.archlinux.org/index.php/AUR_helpers). | | ## Desinstalar diff --git a/docs/zh-hans/contribute/core.md b/docs/zh-hans/contribute/core.md new file mode 100644 index 000000000..a21b1cae5 --- /dev/null +++ b/docs/zh-hans/contribute/core.md @@ -0,0 +1,112 @@ +# asdf + +`asdf` 核心贡献指南. + +## 初始化安装 + +在 Github 上 fork `asdf` 并且/或者使用 Git 克隆默认分支： + +```shell:no-line-numbers +# 克隆你 fork 的 asdf +git clone https://github.com//asdf.git +# 或者直接克隆 asdf +git clone https://github.com/asdf-vm/asdf.git +``` + +核心开发所需的工具都列举在这个存储库的 `.tool-versions` 文件中。如果你想要使用 `asdf` 自身来管理它，请使用以下命令添加这些插件： + +```shell:no-line-numbers +asdf plugin add bats https://github.com/timgluz/asdf-bats.git +asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git +asdf plugin add shfmt https://github.com/luizm/asdf-shfmt.git +``` + +使用以下命令安装这些版本来开发 `asdf`： + +```shell:no-line-numbers +asdf install +``` + +在本地机器的开发过程中不使用 `asdf` 来管理工具 _或许_ 对你有帮助，因为你可能需要打破某些可能会影响到你的开发工具链的功能。以下是所需工具的原始列表： + +- [bats-core](https://github.com/bats-core/bats-core)：Bash 自动化测试系统，用于单元测试 Bash 或 POSIX 兼容脚本。 +- [shellcheck](https://github.com/koalaman/shellcheck)：Shell 脚本的静态分析工具。 +- [shfmt](https://github.com/mvdan/sh)：支持 Bash 的 Shell 解析器、格式化器和解释器；包含 shfmt。 + +## 开发 + +如果你想要在不更改已安装的 `asdf` 的情况下尝试应用你的更改，可以将 `$ASDF_DIR` 变量设置为克隆存储库的路径，并临时将目录的 `bin` 和 `shims` 目录添加到你的路径中。 + +最好在提交或推送到远程之前，在本地做好格式化、lint 检查和测试你的代码。可以使用以下脚本/命令： + +```shell:no-line-numbers +# 脚本检查 +./scripts/shellcheck.bash + +# 格式化 +./scripts/shfmt.bash + +# 测试：所有案例 +bats test/ +# 测试：特定命令 +bats test/list_commands.bash +``` + +::: tip 提示 + +**增加测试！** - 新特性需要进行测试，并加快错误修复的审查速度。请在创建拉取请求之前覆盖新的代码路径。查看 [bats-core 文档](https://bats-core.readthedocs.io/en/stable/index.html) 了解更多。 + +::: + +## Bats 测试 + +**强烈建议**在编写测试之前检查现有的测试套件和 [bats-core 文档](https://bats-core.readthedocs.io/en/stable/index.html)。 + +Bats 调试有时可能很困难。使用带有 `-t` 标识的 TAP 输出将使你能够在测试执行期间打印带有特殊文件描述符 `>&3` 的输出，从而简化调试。例如： + +```shell +# test/some_tests.bats + +printf "%s\n" "Will not be printed during bats test/some_tests.bats" +printf "%s\n" "Will be printed during bats -t test/some_tests.bats" >&3 +``` + +进一步相关文档请查看 bats-core 的 [Printing to the Terminal](https://bats-core.readthedocs.io/en/stable/writing-tests.html#printing-to-the-terminal) 部分. + +## 拉取请求、发布以及约定式提交 + +`asdf` 正在使用一个名为 [Release Please](https://github.com/googleapis/release-please) 的自动发布工具来自动碰撞 [SemVer](https://semver.org/) 版本并生成 [变更日志](https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md)。这个信息是通过读取自上次发布以来的提交历史记录来确定的。 + +[约定式提交](https://www.conventionalcommits.org/zh-hans/) 定义了拉取请求标题的格式，该标题成为默认分支上的提交消息格式。这是通过 Github Action [`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request) 强制执行的。 + +约定式提交遵循以下格式： + +```:no-line-numbers +[optional scope][optional !]: + + +fix: some fix +feat: a new feature +docs: some documentation update +docs(website): some change for the website +feat!: feature with breaking change +``` + +`` 的所有类型包含： `feat`、`fix`、`docs`、`style`、`refactor`、`perf`、`test`、`build`、`ci`、`chore`、`revert`。 + +- `!`：表示重大更改 +- `fix`：将会创建一个新的 SemVer `patch` 补丁 +- `feat`：将会创建一个新的 SemVer `minor` 小版本 +- `!`：将会创建一个新的 SemVer `major` 大版本 + +拉取请求标题必须遵循这种格式。 + +::: tip 提示 + +请使用约定式提交信息格式作为拉取请求标题。 + +::: + +## Docker 镜像 + +[asdf-alpine](https://github.com/vic/asdf-alpine) 和 [asdf-ubuntu](https://github.com/vic/asdf-ubuntu) 项目正在努力提供一些 asdf 工具的容器化镜像。你可以使用这些容器镜像作为开发服务器的基础镜像，或者运行生产应用。 diff --git a/docs/zh-hans/contribute/documentation.md b/docs/zh-hans/contribute/documentation.md new file mode 100644 index 000000000..889585cd8 --- /dev/null +++ b/docs/zh-hans/contribute/documentation.md @@ -0,0 +1,118 @@ +# 文档 & 网站 + +文档 & 网站贡献指南。 + +## 初始化设置 + +在 Github 上 fork `asdf` 并且/或者使用 Git 克隆默认分支： + +```shell:no-line-numbers +# 克隆你 fork 的 asdf +git clone https://github.com//asdf.git +# 或者直接克隆 asdf +git clone https://github.com/asdf-vm/asdf.git +``` + +文档网站开发所需的工具都在文件 `docs/.tool-versions` 中使用 `asdf` 进行管理。使用以下命令添加插件： + +```shell:no-line-numbers +asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs +``` + +使用以下命令安装工具版本： + +```shell:no-line-numbers +asdf install +``` + +- [Node.js](https://nodejs.org/zh-cn/)：基于 Chrome 的 V8 引擎的 JavaScript 运行环境。 + +根据 `docs/package.json` 文件安装 Node.js 依赖： + +```shell:no-line-numbers +npm install +``` + +## 开发 + +[Vuepress (v2)](https://v2.vuepress.vuejs.org/zh/) 是我们用来构建 asdf 文档网站的静态站点生成器（SSG）。它被选中来取代 [Docsify.js](https://docsify.js.org/#/zh-cn/)，因为我们希望在用户没有可用或未启用 JavaScript 时支持仅依靠 HTML。Docsify 无法做到这一点。除此之外，两者特性集合大致相同，重点是 Vuepress 可以用最少的配置编写 Markdown 文件。 + +`package.json` 包含了开发所需的脚本： + +@[code json{3-5}](../../package.json) + +启动本地开发服务器： + +```shell:no-line-numbers +npm run dev +``` + +在提交之前格式化代码： + +```shell:no-line-numbers +npm run format +``` + +## 拉取请求、发布以及约定式提交 + +`asdf` 正在使用依赖 PR 标题中的约定式提交的自动化发布流水线。具体的文档可以查看 [核心贡献指南](./core.md). + +当为文档更改创建 PR 请求时，请确保 PR 标题使用了约定式提交类型 `docs` 以及 `docs: ` 的格式。 + +## Vuepress + +网站的配置包含在几个 JavaScript 文件中，其中 JS 对象用于表示配置。它们是： + +- `docs/.vuepress/config.js`：网站的根配置文件。请查看 [Vuepress 文档](https://v2.vuepress.vuejs.org/zh/guide/configuration.html) 了解更多详情。 + +为了简化根配置文件，更大的 JS 对象表示 _导航栏和侧边栏_ 配置已经被提取并按照语言类型分隔开来。请参考以下文件： + +- `docs/.vuepress/navbar.js` +- `docs/.vuepress/sidebar.js` + +这些配置的官方文档位于 [默认主题参考](https://v2.vuepress.vuejs.org/zh/reference/default-theme/config.html)。 + +## I18n 国际化 + +Vuepress 有一流的国际化支持。根配置文件 `docs/.vuepress/config.js` 定义了支持的语言类型及其 URL、在选择下拉菜单中的标题以及导航栏/侧边栏配置引用。 + +导航栏/侧边栏配置在上述配置文件中捕获，按语言类型分隔开并单独导出。 + +每种语言的 markdown 内容必须位于与根配置文件中 `locale` 键同名的目录位置。也就是： + +```js +{ + ... + themeConfig: { + locales: { + "/": { + selectLanguageName: "English (US)", + sidebar: sidebar.en, + navbar: navbar.en + }, + "/pt-BR/": { + selectLanguageName: "Brazilian Portuguese", + sidebar: sidebar.pt_br, + navbar: navbar.pt_br + } + } + } +} +``` + +`/pt-BR/` 将要求 markdown 文件的同一集合位于 `docs/pt-BR/` 目录下，如下所示： + +```shell:no-line-numbers +docs +├─ README.md +├─ foo.md +├─ nested +│ └─ README.md +└─ pt-BR + ├─ README.md + ├─ foo.md + └─ nested + └─ README.md +``` + +请查看 [Vuepress i18n 国际化官方文档](https://v2.vuepress.vuejs.org/zh/guide/i18n.html#%E7%AB%99%E7%82%B9%E5%A4%9A%E8%AF%AD%E8%A8%80%E9%85%8D%E7%BD%AE) 了解更多详情。 diff --git a/docs/zh-hans/contribute/first-party-plugins.md b/docs/zh-hans/contribute/first-party-plugins.md new file mode 100644 index 000000000..98b8a9b1f --- /dev/null +++ b/docs/zh-hans/contribute/first-party-plugins.md @@ -0,0 +1,14 @@ +# 官方插件 + +asdf 核心团队已经开发了一些与他们日常工作相关的插件。随时欢迎大家维护和改进这些插件。这些插件所对应的存储库链接如下所示： + +- [Elixir](https://github.com/asdf-vm/asdf-elixir) +- [Erlang](https://github.com/asdf-vm/asdf-erlang) +- [Node.js](https://github.com/asdf-vm/asdf-nodejs) +- [Ruby](https://github.com/asdf-vm/asdf-ruby) + +对于社区插件，请参考： + +- [`asdf-community` 组织](https://github.com/asdf-community)：一个用于长期维护 `asdf` 插件的协作、社区驱动的项目。 +- [`asdf-plugins` 缩写存储库](https://github.com/asdf-vm/asdf-plugins)：`asdf` 核心用于查找流行的 `asdf` 插件的缩写列表。 +- [GitHub `asdf-plugin` 主题搜索](https://github.com/topics/asdf-plugin) diff --git a/docs/zh-hans/contribute/github-actions.md b/docs/zh-hans/contribute/github-actions.md new file mode 100644 index 000000000..12fbf8fc6 --- /dev/null +++ b/docs/zh-hans/contribute/github-actions.md @@ -0,0 +1,3 @@ +# GitHub Actions + +感谢你的关注，请参考 [asdf actions repo](https://github.com/asdf-vm/actions) 了解现有的问题、对话和贡献指南。 diff --git a/docs/zh-hans/guide/getting-started.md b/docs/zh-hans/guide/getting-started.md new file mode 100644 index 000000000..b1aaae598 --- /dev/null +++ b/docs/zh-hans/guide/getting-started.md @@ -0,0 +1,347 @@ +# 快速入门 + +`asdf` 安装过程包括： + +1. 安装依赖 +2. 下载 `asdf` 核心 +3. 安装 `asdf` +4. 为每一个你想要管理的工具/运行环境安装插件 +5. 安装工具/运行环境的一个版本 +6. 通过 `.tool-versions` 配置文件设置全局和项目版本 + +## 1. 安装依赖 + +**Linux**： + +::: tip 注意 +根据你的系统配置可能会需要 `sudo` 权限。 +::: + +| 包管理器 | 命令 | +| -------- | ------------------------- | +| Aptitude | `apt install curl git` | +| DNF | `dnf install curl git` | +| Pacman | `pacman -S curl git` | +| Zypper | `zypper install curl git` | + +**macOS**： + +| 包管理器 | 命令 | +| -------- | ----------------------------------- | +| Homebrew | Homebrew 将会自动安装所需要的依赖。 | +| Spack | `spack install coreutils curl git` | + +## 2. 下载 asdf + +尽管还有其他特定于平台的方法，我们建议使用 Git： + +| 方法 | 命令 | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Git | `git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.9.0` | +| Homebrew | `brew install asdf` | +| Pacman | `git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si` 或者使用你更习惯的 [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) | + +## 3. 安装 asdf + +根据 Shell 脚本、操作系统和安装方法的组合不同，相应的配置也会不同。展开以下与你的系统最匹配的选项： + +::: details Bash & Git + +在 `~/.bashrc` 文件中加入以下内容： + +```shell +. $HOME/.asdf/asdf.sh +``` + +补全功能必须在 `.bashrc` 文件中加入以下内容来配置完成： + +```shell +. $HOME/.asdf/completions/asdf.bash +``` + +::: + +::: details Bash & Git (macOS) + +如果你正在使用 **macOS Catalina 或者更新的版本**, 默认的 shell 已经被修改为 **ZSH**。除非修改回 Bash, 否则请遵循 ZSH 的说明。 + +在 `~/.bash_profile` 文件中加入以下内容： + +```shell +. $HOME/.asdf/asdf.sh +``` + +补全功能必须在 `.bash_profile` 文件中使用以下内容手动配置完成： + +```shell +. $HOME/.asdf/completions/asdf.bash +``` + +::: + +::: details Bash & Homebrew (macOS) + +如果你正在使用 **macOS Catalina 或者更新的版本**, 默认的 shell 已经被修改为 **ZSH**。除非修改回 Bash, 否则请遵循 ZSH 的说明。 + +使用以下命令将 `asdf.sh` 加入到 `~/.bash_profile` 文件中： + +```shell:no-line-numbers +echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.bash_profile +``` + +补全功能将需要 [按照 Homebrew 的说明完成配置](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) 或者执行以下命令： + +```shell:no-line-numbers +echo -e "\n. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash" >> ~/.bash_profile +``` + +::: + +::: details Bash & Pacman + +在 `~/.bashrc` 文件中加入以下内容： + +```shell +. /opt/asdf-vm/asdf.sh +``` + +为了让补全功能正常工作需要安装 [`bash-completion`](https://wiki.archlinux.org/title/bash#Common_programs_and_options) 。 +::: + +::: details Fish & Git + +在 `~/.config/fish/config.fish` 文件中加入以下内容： + +```shell +source ~/.asdf/asdf.fish +``` + +补全功能必须按照以下命令手动配置完成： + +```shell:no-line-numbers +mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions +``` + +::: + +::: details Fish & Homebrew + +使用以下命令将 `asdf.fish` 加入到 `~/.config/fish/config.fish` 文件中： + +```shell:no-line-numbers +echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish +``` + +Fish shell 的补全功能可以交给 [ Homebrew 处理](https://docs.brew.sh/Shell-Completion#configuring-completions-in-fish). 很友好！ +::: + +::: details Fish & Pacman + +在 `~/.config/fish/config.fish` 文件中加入以下内容： + +```shell +source /opt/asdf-vm/asdf.fish +``` + +补全功能将会在安装过程中由 AUR 包管理器自动配置完成。 +::: + +::: details Elvish & Git + +使用以下命令将 `asdf.elv` 加入到 `~/.elvish/rc.elv` 文件中： + +```shell:no-line-numbers +mkdir -p ~/.elvish/lib; ln -s ~/.asdf/asdf.elv ~/.elvish/lib/asdf.elv +echo "\n"'use asdf _asdf; fn asdf [@args]{_asdf:asdf $@args}' >> ~/.elvish/rc.elv +echo "\n"'edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.elvish/rc.elv +``` + +补全功能将会自动配置。 + +::: + +::: details Elvish & Homebrew + +使用以下命令将 `asdf.elv` 加入到 `~/.elvish/rc.elv` 文件中： + +```shell:no-line-numbers +mkdir -p ~/.elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.elvish/lib/asdf.elv +echo "\n"'use asdf _asdf; fn asdf [@args]{_asdf:asdf $@args}' >> ~/.elvish/rc.elv +echo "\n"'edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.elvish/rc.elv +``` + +补全功能将会自动配置。 + +::: + +::: details Elvish & Pacman + +使用以下命令将 `asdf.elv` 加入到 `~/.elvish/rc.elv` 文件中： + +```shell:no-line-numbers +mkdir -p ~/.elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.elvish/lib/asdf.elv +echo "\n"'use asdf _asdf; fn asdf [@args]{_asdf:asdf $@args}' >> ~/.elvish/rc.elv +echo "\n"'edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.elvish/rc.elv +``` + +补全功能将会自动配置。 + +::: + +::: details ZSH & Git + +在 `~/.zshrc` 文件中加入以下内容： + +```shell +. $HOME/.asdf/asdf.sh +``` + +**或者** 使用 ZSH 框架插件，比如 [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) 将会使脚本生效并安装补全功能。 + +补全功能会被 ZSH 框架 `asdf` 插件或者通过在 `.zshrc` 文件中加入以下内容自动配置： + +```shell +# append completions to fpath +fpath=(${ASDF_DIR}/completions $fpath) +# initialise completions with ZSH's compinit +autoload -Uz compinit && compinit +``` + +- 如果你正在使用自定义的 `compinit` 配置，请确保 `compinit` 在 `asdf.sh` 生效位置的下方 +- 如果你正在使用自定义的 `compinit` 配置和 ZSH 框架，请确保 `compinit` 在框架生效位置的下方 + +**警告** + +如果你正在使用 ZSH 框架，有关的 `asdf` 插件或许需要更新才能通过 `fpath` 正确地使用最新的 ZSH 补全功能。Oh-My-ZSH asdf 插件还在更新中，请查看 [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837) 了解更多。 +::: + +::: details ZSH & Homebrew + +使用以下命令将 `asdf.sh` 加入到 `~/.zshrc` 文件中： + +```shell +echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc +``` + +**或者** 使用 ZSH 框架插件，比如 [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) 将会使脚本生效并安装补全功能。 + +补全功能可以被 ZSH 框架 `asdf` 或者 [按照 Homebrew 的指引](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh) 完成配置。如果你正在使用 ZSH 框架，有关的 `asdf` 插件或许需要更新才能通过 `fpath` 正确地使用最新的 ZSH 补全功能。Oh-My-ZSH asdf 插件还在更新中，请查看 [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837) 了解更多。 +::: + +::: details ZSH & Pacman + +在 `~/.zshrc` 文件中加入以下内容： + +```shell +. /opt/asdf-vm/asdf.sh +``` + +补全功能会被放在一个对 ZSH 很友好的位置，但是 [ZSH 必须使用自动补全完成配置](https://wiki.archlinux.org/index.php/zsh#Command_completion)。 +::: + +`asdf` 脚本需要在设置好的 `$PATH` **之后**和已经生效的框架（比如 oh-my-zsh 等等）**之后**的位置生效。 + +通常打开一个新的终端标签页来重启你的 shell 让 `PATH` 更改即时生效。 + +## 核心安装完成！ + +这样就完成了 `asdf` 核心的安装 🎉 + +`asdf` 仅在你安装**插件**、**工具**和管理它们的**版本**时才开始真正发挥作用。请继续阅读下面的指南来了解这些是如何做到的。 + +## 4. 安装插件 + +出于演示目的，我们将通过 [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/) 插件来安装和设置 [Node.js](https://nodejs.org/)。 + +### 插件依赖 + +每个插件都有依赖，所以我们需要确认应该列举了这些依赖的插件源码。对于 `asdf-nodejs` 来说，它们是： + +| 操作系统 | 安装依赖 | +| -------------- | --------------------------------------- | +| Linux (Debian) | `apt-get install dirmngr gpg curl gawk` | +| macOS | `brew install gpg gawk` | + +我们应该提前安装这些依赖，因为有些插件有 post-install 钩子。 + +### 安装插件 + +```shell:no-line-numbers +asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git +``` + +## 5. 安装指定版本 + +现在我们已经有了 Node.js 插件，所以我们可以开始安装某个版本了。 + +我们通过 `asdf list all nodejs` 可以看到所有可用的版本或者通过 `asdf list all nodejs 14` 查看版本子集。 + +我们将只安装最新可用的 `latest` 版本： + +```shell:no-line-numbers +asdf install nodejs latest +``` + +::: tip 注意 +`asdf` 强制使用准确的版本。`latest` 是一个通过 `asdf` 来解析到执行时刻的实际版本号的辅助工具。 +::: + +## 6. 设置默认版本 + +`asdf` 在从当前工作目录一直到 `$HOME` 目录的所有 `.tool-versions` 文件中进行工具的版本查找。查找在执行 `asdf` 管理的工具时实时发生。 + +::: warning 警告 +如果没有为工具找到指定的版本，则会出现**错误**。`asdf current` 将显示当前目录中的工具和版本解析结果，或者不存在，以便你可以观察哪些工具将无法执行。 +::: + +### 全局 + +全局默认配置在 `$HOME/.tool-versions` 文件中进行管理。使用以下命令可以设置一个全局版本： + +```shell:no-line-numbers +asdf global nodejs latest +``` + +`$HOME/.tool-versions` 文件内容将会如下所示： + +``` +nodejs 16.5.0 +``` + +某些操作系统已经有一些由系统而非 `asdf` 安装和管理的工具了，`python` 就是一个常见的例子。你需要告诉 `asdf` 将管理权还给系统。[版本参考部分](/zh-hans/manage/versions.md) 将会引导你。 + +### 本地 + +本地版本被定义在 `$PWD/.tool-versions` 文件中（当前工作目录）。通常，这将会是一个项目的 Git 存储库。当在你想要的目录执行： + +```shell:no-line-numbers +asdf local nodejs latest +``` + +`$PWD/.tool-versions` 文件内容将会如下所示： + +``` +nodejs 16.5.0 +``` + +### 使用现有工具版本文件 + +`asdf` 支持从其他版本管理器的现有版本文件中迁移过来，比如 `rbenv` 的 `.ruby-version` 文件。这在每个插件中都原生支持。 + +[`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/) 支持从 `.nvmrc` 和 `.node-version` 文件进行迁移。为了启用此功能，请在 `asdf` 配置文件 `$HOME/.asdfrc` 中加入以下内容： + +``` +legacy_version_file = yes +``` + +请查看 [配置](/zh-hans/manage/configuration.md) 参考页面可以了解更多配置选项。 + +## 完成指南！ + +恭喜你完成了 `asdf` 的快速上手 🎉 你现在可以管理你的项目的 `nodejs` 版本了。对于项目中的其他工具类型可以执行类似步骤即可！ + +`asdf` 还有更多命令需要熟悉，你可以通过运行 `asdf --help` 或者 `asdf` 来查看它们。命令主要分为三类： + +- [`asdf` 核心](/zh-hans/manage/core.md) +- [插件](/zh-hans/manage/plugins.md) +- [（工具的）版本](/zh-hans/manage/versions.md) diff --git a/docs/zh-hans/guide/introduction.md b/docs/zh-hans/guide/introduction.md new file mode 100644 index 000000000..b2bb6bc2d --- /dev/null +++ b/docs/zh-hans/guide/introduction.md @@ -0,0 +1,57 @@ +# 项目简介 + +`asdf` 是一个工具版本管理器。所有的工具版本定义都包含在一个文件（`.tool-versions`）中，你可以将配置文件放在项目的 Git 存储库中以便于和团队其他成员共享，从而确保每个人都使用**完全**相同的工具版本。 + +传统工作方式需要多个命令行版本管理器，而且每个管理器都有其不同的 API、配置文件和实现方式（比如，`$PATH` 操作、垫片、环境变量等等）。`asdf` 提供单个交互方式和配置文件来简化开发工作流程，并可通过简单的插件接口扩展到所有工具和运行环境。 + +## 它是如何工作的 + +一旦 `asdf` 核心在 Shell 配置中设置好之后，你可以安装插件来管理特定的工具。当通过插件安装工具时，安装的可执行程序会为每个可执行程序创建 [垫片]()。当你尝试运行其中一个可执行程序时，将运行垫片，从而允许 `asdf` 识别 `.tool-versions` 文件中设置的工具版本并执行该版本。 + +## 相关项目 + +### nvm / n / rbenv 等 + +[nvm](https://github.com/nvm-sh/nvm), [n](https://github.com/tj/n) 和 [rbenv](https://github.com/rbenv/rbenv) 等工具都是用 Shell 脚本写的，这些脚本能为工具安装的可执行程序创建垫片。 + +`asdf` 非常相似，目的是在工具/运行环境版本管理领域竞争。`asdf` 的区别之处在于它的插件系统，它消除了每个工具/运行环境对管理工具的需求、每个管理工具的不同命令以及存储库中不同的`*-版本`文件。 + + + +### direnv + +> 使用可以根据当前目录加载和卸载环境变量的新功能增强现有 shell。 + +`asdf` 不管理环境变量，但是有一个插件 [`asdf-direnv`](https://github.com/asdf-community/asdf-direnv) 可以用来集成 direnv 的特性到 `asdf` 中。 + +请查看 [direnv 文档](https://direnv.net/) 了解更多。 + +### Homebrew + +> macOS（或者 Linux）上缺失包的管理器 + +Homebrew 管理你的软件包及其上游依赖。`asdf` 不管理上游依赖，它不是包管理器。这个责任取决于用户，尽管我们试图保持依赖关系列表很小。 + +请查看 [Homebrew 文档](https://brew.sh/) 了解更多。 + +### NixOS + +> Nix 是一种采用独特方法进行软件包管理和系统配置的工具 + +NixOS 旨在通过管理每个工具的整个依赖关系树中软件包的确切版本来构建真正可重复的环境，有些是 `asdf` 无法做到的。NixOS 使用自己的编程语言、许多命令行工具和超过 60,000 个包的包集合来实现这一点。 + +同样，`asdf` 不管理上游依赖，并且它不是一个包管理器。 + +请查看 [NixOS 文档](https://nixos.org/guides/how-nix-works.html) 了解更多。 + +## 为什么使用 asdf？ + +`asdf` 确保团队可以使用**完全**相同的工具版本，通过插件系统支持**很多**工具，以及作为 Shell 配置中包含的单个 **Shell** 脚本的 _简单性和熟悉性_ 。 + +::: tip 注意 +`asdf` 并不打算成为一个系统包管理器。它是一个工具版本管理器。仅仅因为你可以为任何工具创建插件并使用 `asdf` 管理其版本，并不意味着这是这个特定工具的最佳实践方案。 +::: diff --git a/docs/zh-hans/index.md b/docs/zh-hans/index.md new file mode 100644 index 000000000..4d9058ae3 --- /dev/null +++ b/docs/zh-hans/index.md @@ -0,0 +1,26 @@ +--- +home: true +title: 首页 +# heroImage: https://vuejs.org/images/logo.png +actions: + - text: 快速上手 + link: /zh-hans/guide/getting-started.html + type: primary + - text: 项目简介 + link: /zh-hans/guide/introduction.html + type: secondary +features: + - title: 一个工具 + details: "使用单个命令行工具和命令界面管理你的每个项目运行环境。" + - title: 插件 + details: "现有运行环境和工具的大型生态系统。简单 API 用于根据需要添加对新工具的支持！" + - title: 向后兼容 + details: "支持从现有配置文件 .nvmrc、.node-versions、.ruby-version 平滑迁移！" + - title: "一个配置文件" + details: "一个可共享的 .tool-versions 配置文件管理所有工具、运行环境及其版本。" + - title: "Shells" + details: "支持 Bash、ZSH、Fish 和 Elvish，并提供补全功能。" + - title: "GitHub Actions" + details: "提供 Github Action 在 CI/CD 工作流中安装和使用 .tool-versions。" +# footer: MIT Licensed∏ +--- diff --git a/docs/zh-hans/learn-more/faq.md b/docs/zh-hans/learn-more/faq.md new file mode 100644 index 000000000..e8d94f0cc --- /dev/null +++ b/docs/zh-hans/learn-more/faq.md @@ -0,0 +1,25 @@ +# FAQ + +以下是 `asdf` 相关的一些常见问题。 + +## 支持 WSL1 吗？ + +WSL1 ([Windows Subsystem for Linux 1](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux#WSL_1)) 不受官方支持。`asdf` 的某些方面可能无法正常工作。我们不打算添加对 WSL1 的官方支持。 + +## 支持 WSL2 吗？ + +WSL2 ([Windows Subsystem for Linux 2](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux#WSL_2)) 应该作为你选择的 WSL 发行版来使用本设置和依赖说明。 + +重要的是，只有当前工作目录是 Unix 驱动器而不是绑定的 Windows 驱动器时，WSL2 _才能_ 正常工作。 + +当 Github Actions 上提供主机运行器支持时，我们打算在 WSL2 上运行测试套件。（Github Actions 目前还未提供 WSL2 支持） + +## 新安装的可执行程序无法运行？ + +> 我执行了 `npm install -g yarn` 命令，但是之后不能运行 `yarn` 命令。这是为什么？ + +`asdf` 使用 [垫片]() 来管理可执行程序。插件所安装的那些命令会自动创建垫片，而通过 `asdf` 管理工具安装过的可执行程序则需要通知 `asdf` 创建垫片的需要。在这个例子中，为 [Yarn](https://yarnpkg.com/) 创建一个垫片即可。请查看 [`asdf reshim` 命令文档](/zh-hans/manage/core.md#reshim) 了解更多。 + +## Shell 没有检测到新安装的垫片？ + +如果 `asdf reshim` 没有解决你的问题，那么很有可能是在 `asdf.sh` 或者 `asdf.fish` 的生效不在你的 Shell 配置文件（`.bash_profile`、`.zshrc`、`config.fish` 等等）的**下方**。这需要你在设置你的 `$PATH` **之后**和生效你的框架（oh-my-zsh 等等）（如果有的话）**之后**再生效。 diff --git a/docs/zh-hans/learn-more/thanks.md b/docs/zh-hans/learn-more/thanks.md new file mode 100644 index 000000000..5b599250f --- /dev/null +++ b/docs/zh-hans/learn-more/thanks.md @@ -0,0 +1,21 @@ +# 致谢 + +asdf 作者和贡献者的感谢页！ + +## 作者 + +我 ([@HashNuke](https://github.com/HashNuke))，高烧、感冒、咳嗽。 + +版权 2014 直到时间尽头 ([MIT License](https://github.com/asdf-vm/asdf/blob/master/LICENSE)) + +## 维护者 + +- [@HashNuke](https://github.com/HashNuke) +- [@danhper](https://github.com/danhper) +- [@Stratus3D](https://github.com/Stratus3D) +- [@vic](https://github.com/vic) +- [@jthegedus](https://github.com/jthegedus) + +## 贡献者 + +请查看 Github 上的 [贡献者名单](https://github.com/asdf-vm/asdf/graphs/contributors) 🙏 了解更多。 diff --git a/docs/zh-hans/manage/commands.md b/docs/zh-hans/manage/commands.md new file mode 100644 index 000000000..ef8436c56 --- /dev/null +++ b/docs/zh-hans/manage/commands.md @@ -0,0 +1,5 @@ +# 所有命令 + +`asdf` 中所有可用命令的列表。这个列表就是 `asdf help` 命令的打印内容。 + +@[code](../../../help.txt) diff --git a/docs/zh-hans/manage/configuration.md b/docs/zh-hans/manage/configuration.md new file mode 100644 index 000000000..102f08c8e --- /dev/null +++ b/docs/zh-hans/manage/configuration.md @@ -0,0 +1,110 @@ +# 配置 + +`asdf` 配置既包括可共享的 `.tool-versions` 文件，也包括用户特定的自定义 `.asdfrc` 和环境变量。 + +## `.tool-versions` + +无论何时 `.tool-versions` 出现在目录中，它所声明的工具版本将会被用于该目录和任意子目录。 + +::: warning 注意 +全局默认配置将设置在文件`$HOME/.tool-versions` 中 +::: + +一个 `.tool-versions` 文件示例如下所示： + +```:no-line-numbers +ruby 2.5.3 +nodejs 10.15.0 +``` + +你也可以包含注释在里面： + +```:no-line-numbers +ruby 2.5.3 # 这是一个注释 +# 这是另一个注释 +nodejs 10.15.0 +``` + +版本号可以有如下格式： + +- `10.15.0` - 实际的版本号。支持下载二进制文件的插件将会下载二进制文件。 +- `ref:v1.0.2-a` 或者 `ref:39cb398vb39` - 指定标签/提交/分支从 github 下载并编译。 +- `path:/src/elixir` - 要使用的工具的自定义编译版本的路径。这种方式供语言开发者等使用。 +- `system` - 此关键字会导致 asdf 传递系统上未由 asdf 管理的工具版本。 + +::: tip 提示 + +多版本可以通过空格将它们分隔开来。比如，使用 Python `3.7.2` 回退到 Python `2.7.15` 最后回退到 `system` Python，可以将以下行的内容添加到 `.tool-versions` 文件中。 + +```:no-line-numbers +python 3.7.2 2.7.15 system +``` + +::: + +为了安装 `.tool-versions` 文件中定义的所有工具，在包含 `.tool-versions` 文件的目录中不带其他参数执行 `asdf install` 命令。 + +为了安装 `.tool-versions` 文件中定义的某个工具，在包含 `.tool-versions` 文件的目录中运行 `asdf install ` 命令。这个工具将会安装 `.tool-versions` 文件所指定的版本。 + +可以直接编辑这个文件或者使用 `asdf local` （或者 `asdf global`）来更新工具版本。 + +## `$HOME/.asdfrc` + +给你的家目录添加一个 `.asdfrc` 文件然后 asdf 将会使用这个文件所指定的配置。下面的文件展示了所需的格式，其中包含用于演示的默认值： + +```:no-line-numbers +legacy_version_file = no +use_release_candidates = no +always_keep_download = no +plugin_repository_last_check_duration = 60 +``` + +### `legacy_version_file` + +插件 **支持** 读取其他版本管理器使用的版本文件，比如，Ruby 的 `rbenv` 的 `.ruby-version` 文件。 + +| 选项 | 描述 | +| :------------------------------------------------------ | :------------------------------------------------------- | +| `no` | 从 `.tool-versions` 文件读取版本 | +| `yes` | 如果可行的话，从传统版本文件读取版本（`.ruby-versions`） | + +### `use_release_candidates` + +配置 `asdf update` 命令以升级到最新的候选版本，而不是最新的语义版本。 + +| 选项 | 描述 | +| :------------------------------------------------------ | :------------- | +| `no` | 语义版本被使用 | +| `yes` | 候选版本被使用 | + +### `always_keep_download` + +配置 `asdf install` 命令以保留或删除下载的源代码或二进制文件。 + +| 选项 | 描述 | +| :------------------------------------------------------ | :--------------------------------- | +| `no` | 在成功安装后删除源代码或二进制文件 | +| `yes` | 在成功安装后保留源代码或二进制文件 | + +### `plugin_repository_last_check_duration` + +配置自上次 asdf 插件存储库同步到下一次存储库同步的持续时间。命令 `asdf plugin add ` 或者 `asdf plugin list all` 将会触发持续时间的检查，如果持续时间已过，则进行同步。 + +| 选项 | 描述 | +| :-------------------------------------------------------------------------------------------- | :------------------------------------------------- | +| 从 `1` 到 `999999999` 的数字
为 `60` | 如果已过自上次同步的持续时间，触发器事件发生时同步 | +| `0` | 每个触发器事件发生时同步 | +| `never` | 从不同步 | + +## 环境变量 + +- `ASDF_CONFIG_FILE` - 如上所述默认为 `~/.asdfrc` 文件。可以被设置在任何位置。 +- `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME` - 存储工具名称和版本的文件名。默认为 `.tool-versions`。可以是任何有效的文件名。通常，除非你知道你希望 asdf 忽略 `.tool-versions` 文件，否则不应该覆盖默认值。 +- `ASDF_DIR` - 默认为 `~/.asdf` - `asdf` 脚本的位置。如果你把 `asdf` 安装到了其他目录，请设置该变量到那个目录。比如，如果通过 AUR 进行安装，则应设置该变量为 `/opt/asdf-vm`。 +- `ASDF_DATA_DIR` - 默认为 `~/.asdf` - `asdf` 安装插件、垫片和安装器的位置。可以被设置在上一节提到的生效 `asdf.sh` 或者 `asdf.fish` 之间的任何位置。对于 Elvish，这可以设置在 `use asdf` 上面。 + +## 内部配置 + +用户不必担心本节，因为它描述了对包管理器和集成者有用的 `asdf` 的内部配置。 + +- `$ASDF_DIR/asdf_updates_disabled`：当此文件存在时（内容无关），通过 `asdf update` 命令进行的更新 将会被禁用。像 Pacman 或者 Homebrew 等包管理器使用它来确保个性化安装的正确的更新方法。 diff --git a/docs/zh-hans/manage/core.md b/docs/zh-hans/manage/core.md new file mode 100644 index 000000000..32d1a3551 --- /dev/null +++ b/docs/zh-hans/manage/core.md @@ -0,0 +1,431 @@ +# 核心 + +核心 `asdf` 命令列表很小，但可以促进很多工作流。 + +## 安装和配置 + +请查看 [快速上手](/zh-hans/guide/getting-started.md) 了解更多详情。 + +## Exec + +```shell:no-line-numbers +asdf exec [args...] +``` + +执行当前版本的命令垫片。 + + + +## Env + +```shell:no-line-numbers +asdf env [util] +``` + + + +## Info + +```shell:no-line-numbers +asdf info +``` + +用于打印操作系统、Shell 和 `asdf` 调试信息的辅助命令。在报告 bug 时需要共享这些信息。 + +## Reshim + +```shell:no-line-numbers +asdf reshim +``` + +这将为某个包的当前版本重新创建垫片。默认情况下，垫片是在某个工具安装的过程中由插件创建。一些工具像 [npm 命令行](https://docs.npmjs.com/cli/) 允许全局安装可执行程序，比如使用 `npm install -g yarn` 命令安装 [Yarn](https://yarnpkg.com/)。因为这个可执行程序不是通过插件生命周期安装的，所以还没有对应的垫片存在。`asdf reshim nodejs ` 命令将会强制重新计算任何新可执行程序的垫片，类似 `nodejs` 的 `versions` 版本下的 `yarn`。 + +## Shim-versions + +```shell:no-line-numbers +asdf shim-versions +``` + +列举为命令提供垫片的插件和版本。 + +例如，[Node.js](https://nodejs.org/) 附带了两个可执行程序，`node` 和 `npm`。当使用 [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/)`插件安装了这些工具的很多版本时，执行`shim-versions` 命令会返回： + +```shell:no-line-numbers +➜ asdf shim-versions node +nodejs 14.8.0 +nodejs 14.17.3 +nodejs 16.5.0 +``` + +```shell:no-line-numbers +➜ asdf shim-versions npm +nodejs 14.8.0 +nodejs 14.17.3 +nodejs 16.5.0 +``` + +## 更新 + +`asdf` 有一个依赖于 Git （我们推荐的安装方法）的内置命令用于更新。如果你使用了其他方法安装，则应按照该方法的步骤操作： + +| 方法 | 最新稳定版本 | `master` 分支上的最新提交 | +| ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | +| asdf (Git) | `asdf update` | `asdf update --head` | +| Homebrew | `brew upgrade asdf` | `brew upgrade asdf --fetch-HEAD` | +| Pacman | 下载一个新的 `PKGBUILD` 并且重新编译
或者使用你习惯的 [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) | | + +## 卸载 + +根据以下步骤卸载 `asdf`： + +::: details Bash & Git + +1. 在 `~/.bashrc` 配置文件中移除生效 `asdf.sh` 和补全功能的行： + +```shell +. $HOME/.asdf/asdf.sh +. $HOME/.asdf/completions/asdf.bash +``` + +2. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Bash & Git (macOS) + +1. 在 `~/.bash_profile` 配置文件中移除生效 `asdf.sh` 和补全功能的行： + +```shell +. $HOME/.asdf/asdf.sh +. $HOME/.asdf/completions/asdf.bash +``` + +2. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Bash & Homebrew (macOS) + +如果你正在使用 **macOS Catalina 以及更新版本**，默认的 shell 已经变成了 **ZSH**。如果你在 `~/.bash_profile` 文件中找不到任何配置，则可能位于 `~/.zshrc` 中。在这种情况下，请按照 ZSH 指南进行操作。 + +1. 在 `~/.bash_profile` 配置文件中移除生效 `asdf.sh` 和补全功能的行： + +```shell +. $(brew --prefix asdf)/libexec/asdf.sh +. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash +``` + +补全功能可能已经如 [Homebrew 的指南](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) 那样配置了，因此请按照他们的指南找出要删除的内容。 + +2. 用包管理器卸载： + +```shell:no-line-numbers +brew uninstall asdf --force +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Bash & Pacman + +1. 在 `~/.bashrc` 配置文件中移除生效 `asdf.sh` 和补全功能的行： + +```shell +. /opt/asdf-vm/asdf.sh +``` + +2. 用包管理器卸载： + +```shell:no-line-numbers +pacman -Rs asdf-vm +``` + +3. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} +``` + +4. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Fish & Git + +1. 在 `~/.config/fish/config.fish` 配置文件中移除生效 `asdf.fish` 的行： + +```shell +source ~/.asdf/asdf.fish +``` + +以及使用以下命令移除补全功能： + +```shell:no-line-numbers +rm -rf ~/.config/fish/completions/asdf.fish +``` + +2. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Fish & Homebrew + +1. 在 `~/.config/fish/config.fish` 配置文件中移除生效 `asdf.fish` 的行： + +```shell +source "(brew --prefix asdf)"/libexec/asdf.fish +``` + +2. 用包管理器卸载： + +```shell:no-line-numbers +brew uninstall asdf --force +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Fish & Pacman + +1. 在 `~/.config/fish/config.fish` 配置文件中移除生效 `asdf.fish` 的行： + +```shell +source /opt/asdf-vm/asdf.fish +``` + +2. 用包管理器卸载： + +```shell:no-line-numbers +pacman -Rs asdf-vm +``` + +3. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} +``` + +4. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Elvish & Git + +1. 在 `~/.elvish/rc.elv` 配置文件中移除使用 `asdf` 模块的行： + +```shell +use asdf _asdf; fn asdf [@args]{_asdf:asdf $@args} +edit:completion:arg-completer[asdf] = $_asdf:arg-completer~ +``` + +以及使用以下命令卸载 `asdf` 模块： + +```shell:no-line-numbers +rm -f ~/.elvish/lib/asdf.elv +``` + +2. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +if (!=s $E:ASDF_DATA_DIR "") { rm -rf $E:ASDF_DATA_DIR } else { rm -rf ~/.asdf } +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Elvish & Homebrew + +1. 在 `~/.elvish/rc.elv` 配置文件中移除使用 `asdf` 模块的行： + +```shell +use asdf _asdf; fn asdf [@args]{_asdf:asdf $@args} +edit:completion:arg-completer[asdf] = $_asdf:arg-completer~ +``` + +以及使用以下命令卸载 `asdf` 模块： + +```shell:no-line-numbers +rm -f ~/.elvish/lib/asdf.elv +``` + +2. 用包管理器卸载： + +```shell:no-line-numbers +brew uninstall asdf --force +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details Elvish & Pacman + +1. 在 `~/.elvish/rc.elv` 配置文件中移除使用 `asdf` 模块的行： + +```shell +use asdf _asdf; fn asdf [@args]{_asdf:asdf $@args} +edit:completion:arg-completer[asdf] = $_asdf:arg-completer~ +``` + +以及使用以下命令卸载 `asdf` 模块： + +```shell:no-line-numbers +rm -f ~/.elvish/lib/asdf.elv +``` + +2. 用包管理器卸载： + +```shell:no-line-numbers +pacman -Rs asdf-vm +``` + +3. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +if (!=s $E:ASDF_DATA_DIR "") { rm -rf $E:ASDF_DATA_DIR } else { rm -rf ~/.asdf } +``` + +4. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details ZSH & Git + +1. 在 `~/.zshrc` 配置文件中移除生效 `asdf.sh` 和补全功能的行： + +```shell +. $HOME/.asdf/asdf.sh +# ... +fpath=(${ASDF_DIR}/completions $fpath) +autoload -Uz compinit +compinit +``` + +**或者** ZSH 框架插件（如果用了的话） + +2. 移除 `$HOME/.asdf` 目录： + +```shell:no-line-numbers +rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details ZSH & Homebrew + +1. 在 `~/.zshrc` 配置文件中移除生效 `asdf.sh` 的行： + +```shell +. $(brew --prefix asdf)/libexec/asdf.sh +``` + +2. 用包管理器卸载： + +```shell:no-line-numbers +brew uninstall asdf --force && brew autoremove +``` + +3. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +::: details ZSH & Pacman + +1. 在 `~/.zshrc` 配置文件中移除生效 `asdf.sh` 的行： + +```shell +. /opt/asdf-vm/asdf.sh +``` + +2. 用包管理器卸载： + +```shell:no-line-numbers +pacman -Rs asdf-vm +``` + +3. 移除 `$HOME/.asdf` 目录 + +```shell:no-line-numbers +rm -rf ${ASDF_DATA_DIR:-$HOME/.asdf} +``` + +4. 执行以下命令移除 `asdf` 所有配置文件： + +```shell:no-line-numbers +rm -rf $HOME/.tool-versions $HOME/.asdfrc +``` + +::: + +恭喜你完成了 🎉 diff --git a/docs/zh-hans/manage/plugins.md b/docs/zh-hans/manage/plugins.md new file mode 100644 index 000000000..ce941a15a --- /dev/null +++ b/docs/zh-hans/manage/plugins.md @@ -0,0 +1,81 @@ +# 插件 + +插件告诉 `asdf` 如何处理不同的工具，如 Node.js、 Ruby、 Elixir 等。 + +请参考 [创建插件](/zh-hans/plugins/create.md) 了解用于支持更多工具的插件 API。 + +## 添加 + +通过 Git URL 地址添加插件： + +```shell:no-line-numbers +asdf plugin add +# asdf plugin add elm https://github.com/vic/asdf-elm +``` + +或者通过插件存储库中的缩写添加插件： + +```shell:no-line-numbers +asdf plugin add +# asdf plugin add erlang +``` + +::: tip 建议 +推荐独立于缩写存储库的、更长的 `git-url` 方法。 +::: + +## 列举已安装 + +```shell:no-line-numbers +asdf plugin list +# asdf plugin list +# java +# nodejs +``` + +```shell:no-line-numbers +asdf plugin list --urls +# asdf plugin list +# java https://github.com/halcyon/asdf-java.git +# nodejs https://github.com/asdf-vm/asdf-nodejs.git +``` + +## 列举缩写存储库中的所有插件 + +```shell:no-line-numbers +asdf plugin list all +``` + +请参考 [插件缩写索引](https://github.com/asdf-vm/asdf-plugins) 了解插件的完整缩写列表。 + +## 更新 + +```shell:no-line-numbers +asdf plugin update --all +``` + +如果你想要更新特定的包，如下所示。 + +```shell:no-line-numbers +asdf plugin update +# asdf plugin update erlang +``` + +这种更新方式将会获取插件存储库的 _源代码_ 的 _默认分支_ 的 _最新提交_。版本化的插件和更新正在开发中 ([#916](https://github.com/asdf-vm/asdf/pull/916))。 + +## 移除 + +```bash:no-line-numbers +asdf plugin remove +# asdf plugin remove erlang +``` + +移除一个插件将会移除该插件安装的所有工具。这可以当作是清理/修剪工具的许多未使用版本的简单方法。 + +## 同步缩写存储库 + +缩写存储库将同步到你的本地计算机并定期刷新。这个周期由以下方法确定： + +- 命令 `asdf plugin add ` 或者 `asdf plugin list all` 将会触发同步 +- 如果在过去的 `X` 分钟内没有同步，则进行同步 +- `X` 默认是 `60`，但可以通过在 `.asdfrc` 文件中配置 `plugin_repository_last_check_duration` 选项来进行配置。请查看 [asdf 配置文档](/zh-hans/manage/configuration.md) 了解更多。 diff --git a/docs/zh-hans/manage/versions.md b/docs/zh-hans/manage/versions.md new file mode 100644 index 000000000..0204b6a89 --- /dev/null +++ b/docs/zh-hans/manage/versions.md @@ -0,0 +1,153 @@ +# 版本 + +## 安装版本 + +```shell:no-line-numbers +asdf install +# asdf install erlang 17.3 +``` + +如果一个插件支持从源代码下载和编译，你可以指定 `ref:foo`，其中 `foo` 是特定的分支、标签或者提交。卸载该版本时，你也需要使用相同的名称和引用。 + +## 安装最新稳定版本 + +```shell:no-line-numbers +asdf install latest +# asdf install erlang latest +``` + +安装给定字符串开头的最新稳定版本。 + +```shell:no-line-numbers +asdf install latest: +# asdf install erlang latest:17 +``` + +## 列举已安装版本 + +```shell:no-line-numbers +asdf list +# asdf list erlang +``` + +筛选出以给定字符串开头的版本。 + +```shell:no-line-numbers +asdf list +# asdf list erlang 17 +``` + +## 列举所有可用版本 + +```shell:no-line-numbers +asdf list all +# asdf list all erlang +``` + +筛选出以给定字符串开头的版本。 + +```shell:no-line-numbers +asdf list all +# asdf list all erlang 17 +``` + +## 显示最新稳定版本 + +```shell:no-line-numbers +asdf latest +# asdf latest erlang +``` + +显示以给定字符串开头的最新稳定版本。 + +```shell:no-line-numbers +asdf latest +# asdf latest erlang 17 +``` + +## 设置当前版本 + +```shell:no-line-numbers +asdf global [...] +asdf shell [...] +asdf local [...] +# asdf global elixir 1.2.4 + +asdf global latest[:] +asdf local latest[:] +# asdf global elixir latest +``` + +`global` 将版本写到 `$HOME/.tool-versions` 文件中。 + +`shell` 仅为当前 shell 会话将版本设置为一个名为 `ASDF_${LANG}_VERSION` 的环境变量。 + +`local` 将版本写到 `$PWD/.tool-versions` 文件中，如果有需要也会创建此文件。 + +请查看 [配置部分](/zh-hans/manage/configuration.md) 的 `.tool-versions` 文件了解更多详情。 + +:::warning 可选 +如果你只是想为当前 shell 会话或者在特定工具版本下执行一条命令，你可以设置一个类似 `ASDF_${TOOL}_VERSION` 的环境变量。 +::: + +下面的示例在版本为 `1.4.0` 的 Elixir 项目上运行测试。 +版本格式与 `.tool-versions` 文件支持的版本格式相同。 + +```shell:no-line-numbers +ASDF_ELIXIR_VERSION=1.4.0 mix test +``` + +## 回退到系统版本 + +要使用工具 `` 的系统版本而非 asdf 管理版本，你可以将工具的版本设置为 `system`。 + +使用 `global`、`local` 或者 `shell` 设置系统，如上面的 [设置当前版本](#设置当前版本) 部分所述。 + +```shell:no-line-numbers +asdf local system +# asdf local python system +``` + +## 显示当前版本 + +```shell:no-line-numbers +asdf current +# asdf current +# erlang 17.3 (set by /Users/kim/.tool-versions) +# nodejs 6.11.5 (set by /Users/kim/cool-node-project/.tool-versions) + +asdf current +# asdf current erlang +# 17.3 (set by /Users/kim/.tool-versions) +``` + +## 卸载版本 + +```shell:no-line-numbers +asdf uninstall +# asdf uninstall erlang 17.3 +``` + +## 垫片（Shims） + +当 asdf 安装一个包时，它会在 `$ASDF_DATA_DIR/shims` 目录（默认为 `~/.asdf/shims`）中为该包中的每个可执行程序创建垫片。这个位于 `$PATH` 中（通过 `asdf.sh`、 `asdf.fish` 等等实现）的目录是已安装程序在环境中可用的方式。 + +垫片本身是非常简单的包装器，它 `exec` （执行）一个辅助程序 `asdf exec`，向其传递插件的名称和垫片正在包装的已安装包中的可执行程序的路径。 + +`asdf exec` 辅助程序确定要使用的软件包版本（比如在 `.tool-versions` 文件中指定，通过 `asdf local ...` 或者 `asdf global ...` 命令选择）、软件包安装目录中的可执行程序的最终路径（这可以在插件中通过 `exec-path` 回调来操作）以及要在其中执行的环境（也由插件 - `exec-env` 脚本提供），最后完成执行。 + +::: warning 注意 +因为此系统使用 `exec` 调用，所以软件包中的任何脚本如果要由 shell 生效而不是执行的脚本都需要直接访问，而不是通过垫片包装器进行访问。两个 `asdf` 命令：`which` 和 `where` 可以通过返回已安装软件包的路径来帮助解决这个问题。 +::: + +```shell +# 返回当前版本中主要可执行程序的路径 +source $(asdf which ${PLUGIN})/../script.sh + +# 返回软件包安装目录的路径 +source $(asdf where ${PLUGIN} $(asdf current ${PLUGIN}))/bin/script.sh +``` + +### 绕过 asdf 垫片 + +如果由于某种原因，你希望绕过 asdf 垫片，或者希望在进入项目目录时自动设置环境变量，则 [asdf-direnv](https://github.com/asdf-community/asdf-direnv) 插件可能会有所帮助。请务必查看其 README 文件了解更多详情。 diff --git a/docs/zh-hans/plugins/create.md b/docs/zh-hans/plugins/create.md new file mode 100644 index 000000000..0b4d1a288 --- /dev/null +++ b/docs/zh-hans/plugins/create.md @@ -0,0 +1,296 @@ +# 创建插件 + +## 插件里有什么 + +插件是一个包含几个可执行脚本的 git 存储库，用于支持对某种语言或工具进行版本控制。这些脚本在执行 `list-all`、`install` 或者 `uninstall` 命令时被执行。你可以设定或取消设定环境变量，并执行设置工具环境所需的任何操作。 + +## 必要的脚本 + +- `bin/list-all` - 列举所有可安装的版本 +- `bin/download` - 下载指定版本的源代码或二进制文件 +- `bin/install` - 安装指定版本 + +## 环境变量 + +所有脚本除了 `bin/list-all` 之外对以下环境变量有权限进行操作： + +- `ASDF_INSTALL_TYPE` - `version` 或者 `ref` +- `ASDF_INSTALL_VERSION` - 如果 `ASDF_INSTALL_TYPE` 是 `version`，那么这将是版本号。否则它将传递为 git 的 ref。可能指向存储库的一个标签/提交/分支。 +- `ASDF_INSTALL_PATH` - _已经_ 安装到的目录（或 `bin/install` 脚本执行情况下 _应该_ 安装到的目录） + +这些附加的环境变量将可用于 `bin/install` 脚本： + +- `ASDF_CONCURRENCY` - 编译源代码时使用的内核数。对于配置 `make -j` 非常有用。 +- `ASDF_DOWNLOAD_PATH` - `bin/download` 脚本下载源代码或二进制文件的路径。 + +这些附加的环境变量将可用于 `bin/download` 脚本： + +- `ASDF_DOWNLOAD_PATH` - 源代码或二进制文件应该下载到的路径。 + +#### bin/list-all + +必须打印一个带有空格分隔的版本列表的字符串，示例输出如下所示： + +```shell +1.0.1 1.0.2 1.3.0 1.4 +``` + +请注意，最新版本应列在最后，以便它看起来更接近用户的提示。这很有帮助，因为 `list-all` 命令会在自己的行打印每个版本。如果有很多版本，那么早期版本可能会不在屏幕上。 + +如果从网站上的发布页面拉取版本，建议尽可能不对版本进行排序。通常，版本已经按照正确的顺序排列，或者以相反的顺序排列，在这种情况下，像 `tac` 这样的东西就足够了。如果必须手动对版本进行排序，则不能依赖 `sort -V`，因为 OSX 操作系统不支持。一种可以替代的排序功能是 [更好的选择](https://github.com/vic/asdf-idris/blob/master/bin/list-all#L6)。 + +#### bin/download + +此脚本必须下载源代码或者二进制文件到 `ASDF_DOWNLOAD_PATH` 环境变量包含的路径。如果下载的源代码或者二进制文件是压缩的，则只有未压缩的源代码或二进制文件会放置在 `ASDF_DOWNLOAD_PATH` 目录中。 + +下载成功后脚本必须以 `0` 状态退出。如果下载失败，脚本必须以任何非零退出状态退出。 + +如果可能，脚本应该仅将文件放在 `ASDF_DOWNLOAD_PATH` 中。如果下载失败，则不应将任何文件放在目录中。 + +如果此脚本不存在，asdf 将假设存在 `bin/install` 脚本，将下载并安装该版本。asdf 仅在没有此脚本的情况下才能支持传统插件。所有插件都必须包含此脚本，最终将删除对传统插件的支持。 + +#### bin/install + +本脚本应在 `ASDF_INSTALL_PATH` 中安装版本。默认情况下，asdf 将为 `$ASDF_INSTALL_PATH/bin` （可以通过可选的 [bin/list-bin-paths](#binlist-bin-paths) 脚本自定义）目录中的任意文件创建垫片。 + +安装成功时，安装脚本应以 `0` 状态退出。如果安装失败，脚本应以任何非零退出状态退出。 + +如果可能，脚本应仅在安装脚本认为工具的生成和安装成功后，才将文件放在 `ASDF_INSTALL_PATH` 目录中。asdf 检查 `ASDF_INSTALL_PATH` 目录的 [扩展](https://github.com/asdf-vm/asdf/blob/242d132afbf710fe3c7ec23c68cec7bdd2c78ab5/lib/utils.sh#L44) 以确认是否安装了该工具版本。如果在安装过程开始时填充了 `ASDF_INSTALL_PATH` 目录，则在安装过程中在其他终端中运行的其他 asdf 命令可能会认为该工具版本已经安装，即使它还未完全安装。 + +如果你希望你的插件使用 asdf 0.7._ 及更早版本和 0.8._ 及更高版本，请检查是否存在 `ASDF_DOWNLOAD_PATH` 环境变量。如果未设置，请在 `bin/install` 脚本回调时下载源代码。如果设置，则假设 `bin/downlaod` 脚本已经下载源代码。 + +## 可选脚本 + +#### bin/help 脚本 + +这不是一个回调脚本，而是一组回调脚本，每个脚本将打印不同的文档到 STDOUT。下面列出了可能的回调脚本。请注意，`bin/help.overview` 是一种特殊情况，因为必须存在才能为脚本显示任何帮助输出。 + +- `bin/help.overview` - 此脚本应该输出有关插件和所管理工具的一般描述。不应该打印任何标题，因为 asdf 将打印标题。输出可以是自由格式的文本，但理想情况下只有一个短段落。如果你希望 asdf 为你的插件提供帮助信息，则必须存在此脚本。所有其他的帮助回调脚本都是可选的。 +- `bin/help.deps` - 此脚本应该输出为操作系统量身定制的依赖项列表。每行一个依赖项。 +- `bin/help.config` - 此脚本应该打印对插件和工具可能有用的任何必需或可选配置。安装或编译该工具所需的任何环境变量或其他标志（尽可能针对用户的操作系统）。输出可以是自由格式的文本。 +- `bin/help.links` - 这应该是与插件和工具相关的链接列表（同样，尽可能针对当前操作系统量身定制）。每行一个链接。行的格式可以是 `: <link>` 或只是 `<link>`。 + +这些脚本的每一个都应根据当前操作系统调整其输出。例如，在 Ubuntu 上，依赖脚本可以将依赖项输出为必须安装的 apt-get 包。设置变量时，脚本还应该根据设置变量 `ASDF_INSTALL_VERSION` 和 `ASDF_INSTALL_TYPE` 的值。它们是可选的，并不总是被设置。 + +帮助回调脚本**不得**输出核心 asdf-vm 文档中已涵盖的任何信息。不得出现一般的 asdf 使用信息。 + +#### bin/latest-stable + +如果实现了此回调，asdf 将使用它来确定工具的最新稳定版本，而不是尝试自行判断。`asdf latest` 通过查看由 `list-all` 回调打印的最新版本，在从输出中排除了几种类型的版本（如发布候选版本）之后推断出最新版本。当你的插件的 `list-all` 回调打印同一工具的不同变体并且最新版本不是你希望默认使用的变体的最新稳定版本时，这种默认行为是不可取的。例如，对于 Ruby，最新的稳定版本应该是 Ruby（MRI）的常规实现，但最后 `list-all` 回调打印的是 truffleruby 版本。 + +此回调使用单个 “过滤器” 字符串调用，因为它是唯一的参数。这应该用于过滤所有最新稳定版本。例如对于 Ruby，用户可以选择传入 `jruby` 以选择 `jruby` 的最新稳定版本。 + +#### bin/list-bin-paths + +列举指定工具版本的可执行程序。必须打印一个带有空格分隔的包含可执行文件的目录路径列表的字符串。路径必须相对于传递的安装路径。示例输出如下所示： + +```shell +bin tools veggies +``` + +这将指示 asdf 为 `<install-path>/bin`、`<install-path>/tools` 和 `<install-path>/veggies` 中的文件创建垫片。 + +如果未指定此脚本，asdf 将在安装中查找 `bin` 目录并为这些脚本创建垫片。 + +#### bin/exec-env + +设置环境变量以运行包中的二进制文件。 + +#### bin/exec-path + +获取工具的指定版本的可执行程序路径。必须打印具有相对可执行程序路径的字符串。这允许插件有条件地覆盖垫片指定的可执行程序路径，否则返回垫片指定的默认路径。 + +```shell +用法： + plugin/bin/exec-path <install-path> <command> <executable-path> + +例子调用： + ~/.asdf/plugins/foo/bin/exec-path "~/.asdf/installs/foo/1.0" "foo" "bin/foo" + +输出： + bin/foox +``` + +#### bin/uninstall + +卸载某个工具的指定版本。 + +#### bin/list-legacy-filenames + +为此插件注册其他设置器文件。必须打印一个带有空格分隔的文件名列表的字符串。 + +```shell +.ruby-version .rvmrc +``` + +注意：这仅适用于在 `~/.asdfrc` 配置文件中启用了 `legacy_version_file` 选项的用户。 + +#### bin/parse-legacy-file + +这可用于进一步解析 asdf 找到的传统文件。如果 `parse-legacy-file` 未实现，asdf 将会简单读取文件来确定版本。脚本将传递文件路径作为其第一个参数。 + +#### bin/post-plugin-add + +这可用于在插件添加到 asdf 后运行任何安装后操作。 + +该脚本可以访问插件的安装路径（`${ASDF_PLUGIN_PATH}`）和源 URL（`${ASDF_PLUGIN_SOURCE_URL}`），如果有的话。 + +其他请参考相关钩子： + +- `pre_asdf_plugin_add` +- `pre_asdf_plugin_add_${plugin_name}` +- `post_asdf_plugin_add` +- `post_asdf_plugin_add_${plugin_name}` + +#### bin/post-plugin-update + +这可用于在 asdf 下载更新的插件后运行任何插件更新后操作。 + +该脚本可以访问插件的安装路径（`${ASDF_PLUGIN_PATH}`）、更新前的 git-ref（`${ASDF_PLUGIN_PREV_REF}`）和更新后的 git-ref（`${ASDF_PLUGIN_POST_REF}`）。 + +其他请参考相关钩子： + +- `pre_asdf_plugin_updated` +- `pre_asdf_plugin_updated_${plugin_name}` +- `post_asdf_plugin_updated` +- `post_asdf_plugin_updated_${plugin_name}` + +#### bin/pre-plugin-remove + +这可用于在从 asdf 中删除插件之前运行任何预删除操作。 + +该脚本可以访问安装插件的路径（`${ASDF_PLUGIN_PATH}`）。 + +其他请参考相关钩子： + +- `pre_asdf_plugin_remove` +- `pre_asdf_plugin_remove_${plugin_name}` +- `post_asdf_plugin_remove` +- `post_asdf_plugin_remove_${plugin_name}` + +## asdf 命令行的扩展命令 + +插件可以通过提供 `lib/commands/command*.bash` 脚本或者可执行程序来定义新的 asdf 命令，这些脚本或可执行程序将使用插件名称作为 asdf 命令的子命令进行调用。 + +例如，假设一个 `foo` 插件有以下文件： + +```shell +foo/ + lib/commands/ + command.bash + command-bat.bash + command-bat-man.bash + command-help.bash +``` + +用户现在可以执行： + +```shell +$ asdf foo # 等同于运行 `$ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash` +$ asdf foo bar # 等同于运行 `$ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash bar` +$ asdf foo help # 等同于运行 `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-help.bash` +$ asdf foo bat man # 等同于运行 `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat-man.bash` +$ asdf foo bat baz # 等同于运行 `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat.bash baz` +``` + +插件作者可以使用此功能来提供与其工具相关的实用命令，或者可以创建 asdf 本身的新命令扩展的插件。 + +调用时，如果扩展命令未设置其可执行位，则它们将作为 bash 脚本获取，且具有来自 `$ASDF_DIR/lib/utils.bash` 的所有可用功能。 +此外，`$ASDF_CMD_FILE` 解析所获取文件的完整路径。 +如果设置了可执行位，则只是执行它们并替换 asdf 执行。 + +这个功能的一个很好的例子是像 [`haxe`](https://github.com/asdf-community/asdf-haxe) 这样的插件。 +它提供了 `asdf haxe neko-dylibs-link` 来修复 haxe 可执行文件期望找到相对于可执行目录的动态链接库的问题。 + +如果你的插件提供了 asdf 扩展命令，请务必在插件的 README 文件中提及。 + +## 自定义垫片模板 + +**请仅在真的需要时才使用此功能** + +asdf 允许自定义垫片模板。对于名为 `foo` 的可执行程序，如果有一个 `shims/foo` 的文件在插件中，那么 asdf 将复制这个文件替代使用标准垫片模板。 + +必须明智地使用这一点。对于目前的 AFAIK，它仅仅被使用在了 Elixir 插件中，因为一个可执行程序除了是可执行程序文件之外，还被读作为 Elixir 文件，这使得无法使用标准的 bash 垫片。 + +## 测试插件 + +`asdf` 包含 `plugin-test` 命令用于测试插件。你可以像下面这样使用它： + +```shell +asdf plugin test <plugin-name> <plugin-url> [--asdf-tool-version <version>] [--asdf-plugin-gitref <git-ref>] [test-command*] +``` + +只有前两个参数是必须的。 +如果指定了 \__version_，则该工具将随指定版本一起安装。默认返回为 `asdf latest <plugin-name>`。 +如果指定了 _git-ref_，则插件将检查提交/分支/标签。这对于在该插件的 CI 上测试拉取请求非常有用。 + +剩下的参数被视为要执行的命令，以确保安装的工具正常工作。通常情况下，它需要带 `--version` 或者 `--help`。例如，要测试 NodeJS 插件，我们可以运行： + +```shell +asdf plugin test nodejs https://github.com/asdf-vm/asdf-nodejs.git node --version +``` + +我们强烈建议你在 CI 环境中测试你的插件，并确保它可以在 Linux 和 OSX 上运行。 + +#### GitHub Action 示例 + +[asdf-vm/actions](https://github.com/asdf-vm/actions) 存储库为托管在 github 的项目提供了使用 Github Action 来测试插件的可能。 + +```yaml +steps: + - name: asdf_plugin_test + uses: asdf-vm/actions/plugin-test@v1 + with: + command: "my_tool --version" + env: + GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} # 自动提供 +``` + +#### TravisCI 配置示例 + +这是一个 `.travis.yml` 示例文件，请根据你的需要进行自定义： + +```yaml +language: c +script: asdf plugin test nodejs $TRAVIS_BUILD_DIR 'node --version' +before_script: + - git clone https://github.com/asdf-vm/asdf.git asdf + - . asdf/asdf.sh +os: + - linux + - osx +``` + +注意： +当使用其他 CI 时，你将需要确认哪些变量映射到存储库路径。 + +你还可以选择将相对路径传递给 `plugin-test`。 + +例如，如果在存储库目录中运行测试脚本：`asdf plugin test nodejs . 'node --version'`。 + +## GitHub API 频率限制 + +如果你的插件的 `list-all` 依赖于访问 GitHub API，请确保在访问时提供授权令牌，否则你的测试可能会因频率限制而失败。 + +为此，创建一个仅具有 `public_repo` 权限的 [新个人令牌](https://github.com/settings/tokens/new)。 + +然后，在 travis.ci 构建设置中添加一个名为 `GITHUB_API_TOKEN` 的 _安全_ 环境变量。并且 _绝对不要_ 在你的代码中公布你的 token。 + +最后，添加如下内容到 `bin/list-all`： + +```shell +cmd="curl -s" +if [ -n "$GITHUB_API_TOKEN" ]; then + cmd="$cmd -H 'Authorization: token $GITHUB_API_TOKEN'" +fi + +cmd="$cmd $releases_path" +``` + +## 向官方插件存储库提交插件 + +`asdf` 可以通过指定插件存储库 url 轻松安装插件，比如 `plugin add my-plugin https://github.com/user/asdf-my-plugin.git`。 + +为了使你的用户更轻松，你可以将插件添加到官方插件存储库中，以列出你的插件并使用较短的命令轻松安装，比如 `asdf plugin add my-plugin`。 + +请查看插件存储库 [asdf-vm/asdf-plugins](https://github.com/asdf-vm/asdf-plugins) 中的说明了解更多。