Avatar CLI

目录

1. 介绍
2. 原因
3. 如何安装 Avatar-CLI
4. 如何使用 Avatar-CLI
5. 在 CI/CD 管道中使用 Avatar-CLI
6. 在脚本中使用 Avatar-CLI
7. 在 JetBrains IDE 中使用 Avatar-CLI
8. 故障排除
9. 如何贡献
10. 社区

介绍

Avatar-CLI 是一个命令行工具，允许您在系统上无需安装即可运行成千上万的 CLI 程序，用于您的开发项目。

Avatar-CLI 以多种方式简化了开发流程

• 使任何类型的项目中使用的任何类型工具的版本固定成为可能。无需复杂的设置或超特定工具，如 nvm、nodeenv、pyenv、rbenv、goenv、asdf-vm 等。我想你已经看到了这个模式。
• 为什么？

Avatar-CLI 存在的原因以及它试图解决的问题是什么？

Avatar-CLI 是如何创建的以及它试图解决什么问题？

• Avatar-CLI 是为了缩短开发环境的设置时间到几乎为零而创建的。
• Avatar-CLI 允许每个项目将其开发环境定义为代码，并通过源控制作为配置文件共享。请参阅 Avatarfile 示例。

Avatar-CLI 及其相关实践解决的问题

• 在我的机器上运行 - 使用 Avatar-CLI，每个开发人员（和/或 CI 代理）都获得了一个由 docker 镜像组合构建的持续和可重复的环境。
• Avatar-CLI 有助于对抗配置漂移。CI/CD 环境和开发人员环境中的工具和配置往往会随着时间的推移积累差异和不匹配。Avatar-CLI 允许使用完全相同的工具，拥有它们配置的唯一真相来源。

如何安装 Avatar-CLI

首先，如果您还没有安装，请安装 Docker。

下载预编译的二进制文件

您可以从发布版部分获取我们的预编译二进制文件。目前我们只能提供 Linux 二进制文件，但将来我们也将提供适用于 Macos 的二进制文件。

通过 Cargo

如果您想在 Macos 中使用 Avatar-CLI，或者不介意等待其编译的时间更长一些，您可以使用cargo¹来安装它

cargo install avatar-cli

1: 如果您的系统中没有 cargo，您可以通过 rustup 获取它。

如何使用 Avatar-CLI

在命令行中

# 1. Enter into your project directory
cd /your/project/path

# 2. Initialize Avatar-CLI for this project, this will create a new config file.
#    You only have to do this one single time per project.
avatar init

# 3. Edit the generated configuration file, without modifying its
#    `internalProjectId` property. You can see an example in the next code
#    block of this README.md file.

# 4. Now you can enter into an Avatar-CLI subshell and use all the configured
#    tools. If, for example, you configured a specific version of NodeJS, then
#    it will be available inside that subshell.
avatar shell

# Now you can use the software you specified in the configuration, even if it
# was not installed in your system.

配置示例

---
# This is of no use... for now, but it must be there
avatarVersion: '0.17.0'

# Keep the value generated by `avatar init`, don't share it across projects.
# This value is used (among other things) to keep track of managed volumes and
# containers
projectInternalId: v2ZmtbkGuVdvGwVE

# The field shellConfig is optional, it allows you to define some settings for
# the Avatar-CLI subshell (started via `avatar shell`).
shellConfig:
  # You can define environment variables for the subshell
  env:
    SOME_ENV_VAR: 42
  # In the case of the $PATH environment variable, Avatar-CLI forbids declaring
  # it through the `env` field, but you can extend it adding multiple paths to
  # the `extraPaths` field. This can be useful if you want to access tools
  # provided by some package manager, like `npm` or `composer`, as if they were
  # installed globally.
  extraPaths:
    - ./node_modules/.bin

# In this section we declare the OCI images that we'll use in our project
images:
  # Image name
  node:
    tags:
      14-buster:
        # The runConfig block allows us to tweak our containers, to improve
        # their integration with our development environment.
        runConfig:
          # You can specify hardcoded environment variables for your containers,
          # in this example we use this to configure NPM's cache
          env:
            npm_config_cache: /caches/.npm

          # You can pass host environment variables to your containers
          envFromHost:
            - NPM_TOKEN

          # You can specify which container paths have to be mounted as volumes,
          # this is specially useful for package managers' caches
          volumes:
            /caches/.npm: {} # In most cases, we won't need to configure volumes
            /another/example:
              # Volume names are usually autogenerated, use this configuration
              # option only in case you want to share volumes accross projects
              name: exotic_volume

              # By default, the scope of a volume is "Project", allowed values
              # are "Project", "OCIImage" and "Binary".
              # This setting defines how volumes are shared between containers,
              # and has no effect if a custom volume name has been set.
              scope: Project

          # In most cases, bindings won't be necessary, and it's advisable to
          # avoid them as they difficult to share development environments with
          # other people. But, if you really need to map a container path to
          # your host filesystem, they will allow you to do so.
          bindings:
            /container/path: /host/path

      # For each image, we can declare which binaries we want to expose to our
      # project.
      binaries:
        node:
          path: node # The path can also be an absolute path

          # Although we don't do it in this example, each binary can have its
          # own `runConfig` block, and its values will override the ones defined
          # at the image tag level

        # Usually we can skip configuring the binary, we just have to list it
        npm: {}
        npx: {}
        yarn: {}

  # Image name
  rust:
    tags:
      1.45-stretch:
        binaries:
          cargo:
            path: cargo

在 CI/CD 管道中使用 Avatar-CLI

如果您想在您的 CI/CD 管道中使用 Avatar-CLI，您可以依赖生成的 OCI 图像。我们通过三个不同的注册表提供 Avatar-CLI 图像

• Gitlab CI 注册表： registry.gitlab.com/avatar-cli/avatar-cli:[ major[.minor[.patch]] | latest ]
• Github 注册表： docker.pkg.github.com/avatar-cli/avatar-cli/avatar-cli:[ major[.minor[.patch]] | latest ]
• Docker Hub： avatarcli/avatar-cli:[ major[.minor[.patch]] | latest ]

在脚本中使用 Avatar-CLI

考虑到在脚本内部创建子 shell 可能过于繁琐，您还可以“source”avatar export-env命令的输出。

在 Bash 脚本中，您可以这样做

#!/bin/bash

source <(avatar export-env)

如果您想与 POSIX shell 完全兼容，那么您必须首先创建一个文件，然后 source 它

#!/bin/sh

avatar export-env > /your/temporary/file
. /your/temporary/file

在 JetBrains IDE 中使用 Avatar-CLI

当使用您首选的 IDE 时，有时您必须指定 Python 或 PHP 等解释器的路径。

为此，Avatar-CLI 在项目的.avatar-cli/volatile/wrappers目录中生成包装脚本，您可以让您的 IDE 在那里找到解释器。

顺便提一下，请注意，还有一个类似的目录（.avatar-cli/volatile/bin），这是 avatar shell使用的符号链接所在的位置，并且它们与您的 IDE 不兼容。

故障排除

使用由 Avatar-CLI 管理的工具的交互式 Git Hooks

Git hooks 默认是非交互式的，如果您想将它们转换为交互式程序，程序必须将其标准输入连接到伪终端设备（通常是 /dev/tty）。

如果这样的git钩子使用Avatar管理的工具，您必须确保在启动任何管理容器之前执行TTY连接，因为一旦容器已经连接并启动，就没有合理的方法为Avatar-CLI附加一个终端。

所述问题的例子之一是NodeJS、Husky和Commitizen等工具的组合。Husky将为每个git钩子启动一个shell脚本，并在一些检查后将执行控制权传递给npm。

在Avatar-CLI的具体情况下，我们通过为Husky创建补丁（PR #747）并创建项目分支来解决此问题，同时Husky项目维护者决定是否接受此PR。

自定义$PATH环境变量

如果您通过如~/.bashrc之类的配置脚本自定义了$PATH环境变量，您应该使用条件语句包装该重新定义，以避免破坏Avatar-CLI的工作方式。

例如，以下内容应转换为：

export PATH="/custom/extra/bin/path:${PATH}";

应该转换为以下内容：

if [ -z "${AVATAR_CLI_SESSION_TOKEN}" ]; then
  export PATH="/custom/extra/bin/path:${PATH}";
fi

请放心，您声明的路径仍然可用，但Avatar-CLI必须确保其自己的管理路径是首先被评估的。

如何贡献

阅读贡献指南。

社区

• Discord: Avatar-CLI在Discord有一个小型社区，我们可以讨论疑问、问题和开发过程本身。
• Twitter: 我们有一个官方Twitter账户，我们用它来发布公告。

许可证

Avatar-CLI在GPL 3.0许可证下授权。