github.com/KusionStack/kpm@v0.8.4-0.20240326033734-dc72298a30e5/README-zh.md (about)

     1  <h1 align="center">Kpm: KCL 包管理器</h1>
     2  
     3  <p align="center">
     4  <a href="./README.md">English</a> | <a href="./README-zh.md">简体中文</a>
     5  </p>
     6  <p align="center">
     7  <a href="#introduction">介绍</a> | <a href="#installation">安装</a> | <a href="#quick-start">快速开始</a>
     8  </p>
     9  
    10  <p align="center">
    11  <img src="https://coveralls.io/repos/github/KusionStack/kpm/badge.svg">
    12  <img src="https://img.shields.io/badge/license-Apache--2.0-green">
    13  <img src="https://img.shields.io/badge/PRs-welcome-brightgreen">
    14  </p>
    15  
    16  # 注意 !
    17  
    18  KPM CLI 将在 v0.8.0 版本后被弃用，并且 KPM CLI 将被 KCL CLI 替代 - https://github.com/kcl-lang/cli.
    19  
    20  受到影响的部分如下所示:
    21  
    22  ```
    23  kpm
    24  ├── pkg
    25  │   ├── api
    26  │   ├── client
    27  │   ├── cmd       # KPM CLI 将在 v0.8.0 版本后被弃用.
    28  │   ├── constants
    29  │   ├── env
    30  │   ├── errors
    31  │   ├── git
    32  │   ├── oci
    33  │   ├── opt
    34  │   ├── package
    35  │   ├── reporter
    36  │   ├── runner
    37  │   ├── semver
    38  │   ├── settings
    39  │   ├── utils
    40  │   └── version
    41  ├── scripts
    42  ├── test
    43  │   └── e2e      # KPM CLI 的 e2e 测试将在 v0.8.0 版本后被弃用.
    44  ├── ......
    45  ```
    46  
    47  ## 介绍
    48  
    49  `kpm` 是 KCL 包管理器。`kpm` 会下载您的 KCL 包的依赖项、编译您的 KCL 包、制作可分发的包并将其上传到 KCL 包的仓库中。
    50  
    51  ## 安装
    52  
    53  ### 安装 KCL
    54  
    55  `kpm` 将调用 [KCL 编译器](https://github.com/KusionStack/KCLVM) 来编译 KCL 程序。在使用 `kpm` 之前，您需要确保 KCL 编译器 已经成功安装。
    56  
    57  [如需了解如何安装 KCL 的更多信息，请参考此处。](https://kcl-lang.io/docs/user_docs/getting-started/install)
    58  
    59  使用以下命令来确保您已成功安装 `KCL`。
    60  
    61  ```shell
    62  kcl -V
    63  ```
    64  
    65  ### 安装 `kpm`
    66  
    67  #### 使用 `go install` 安装
    68  
    69  您可以使用 `go install` 命令安装 `kpm`。
    70  
    71  ```shell
    72  go install kcl-lang.io/kpm@latest
    73  ```
    74  
    75  如果您在执行完上述命令后,使用 `kpm` 时,无法找到命令 `kpm` 请参考:
    76  
    77  - [go install 安装后找不到命令。](#q-我在使用go-install安装kpm后出现了command-not-found的错误)
    78  
    79  #### 从 Github release 页面手动安装
    80  
    81  您也可以从 Github release 中获取 `kpm` ，并将 `kpm` 的二进制文件路径设置到环境变量 PATH 中。
    82  
    83  ```shell
    84  # KPM_INSTALLATION_PATH 是 `kpm` 二进制文件的所在目录.
    85  export PATH=$KPM_INSTALLATION_PATH:$PATH  
    86  ```
    87  
    88  请使用以下命令以确保您成功安装了 `kpm`。
    89  
    90  ```shell
    91  kpm --help
    92  ```
    93  
    94  如果你看到以下输出信息，那么你已经成功安装了 `kpm`，可以继续执行下一步操作。
    95  
    96  <img src="./docs/gifs/kpm_help.gif" width="600" align="center" />
    97  
    98  ## 快速开始
    99  
   100  ### 初始化一个空的 KCL 包
   101  
   102  使用 `kpm init` 命令创建一个名为 `my_package` 的 kcl 程序包, 并且在我们创建完成一个名为 `my_package` 的包后，我们需要通过命令 `cd my_package` 进入这个包来进行后续的操作。
   103  
   104  ```shell
   105  kpm init my_package
   106  ```
   107  
   108  <img src="./docs/gifs/kpm_init.gif" width="600" align="center" />
   109  
   110  `kpm` 将会在执行 `kpm init my_package` 命令的目录下创建两个默认的配置文件 `kcl.mod` 和 `kcl.mod.lock`。
   111  
   112  ```shell
   113  - my_package
   114          |- kcl.mod
   115          |- kcl.mod.lock
   116          |- # 你可以直接在这个目录下写你的kcl程序。
   117  ```
   118  
   119  `kcl.mod.lock` 是 `kpm` 用来固定依赖版本的文件，是自动生成的，请不要人工修改这个文件。
   120  
   121  `kpm` 将会为这个新包创建一个默认的 `kcl.mod`。如下所示:
   122  
   123  ```shell
   124  [package]
   125  name = "my_package"
   126  edition = "0.0.1"
   127  version = "0.0.1"
   128  ```
   129  
   130  ### 为 KCL 包添加依赖
   131  
   132  然后，您可以通过 `kpm add` 命令来为您当前的库添加一个外部依赖。
   133  
   134  如下面的命令所示，为当前包添加一个版本号为 `1.27` 并且名为 `k8s` 的依赖包。
   135  
   136  ```shell
   137  kpm add k8s:1.27
   138  ```
   139  
   140  <img src="./docs/gifs/kpm_add_k8s.gif" width="600" align="center" />
   141  
   142  `kpm` 会为您将依赖添加到 kcl.mod 文件中.
   143  
   144  ```shell
   145  [package]
   146  name = "my_package"
   147  edition = "0.0.1"
   148  version = "0.0.1"
   149  
   150  [dependencies]
   151  k8s = "1.27" # The dependency 'k8s' with version '1.27'
   152  ```
   153  
   154  ### 编写一个程序使用包 `konfig` 中的内容
   155  
   156  在当前包中创建 `main.k`。
   157  
   158  ```shell
   159  - my_package
   160          |- kcl.mod
   161          |- kcl.mod.lock
   162          |- main.k # Your KCL program.
   163  ```
   164  
   165  并且将下面的内容写入 `main.k` 文件中。
   166  
   167  ```kcl
   168  # 导入并使用外部依赖 `k8s` 包中的内容。
   169  import k8s.api.core.v1 as k8core
   170  
   171  k8core.Pod {
   172      metadata.name = "web-app"
   173      spec.containers = [{
   174          name = "main-container"
   175          image = "nginx"
   176          ports = [{containerPort = 80}]
   177      }]
   178  }
   179  
   180  ```
   181  
   182  ### 使用 `kpm` 编译 kcl 包
   183  
   184  你可以使用 kpm 编译刚才编写的 `main.k` 文件, 得到编译后的结果。
   185  
   186  ```shell
   187  kpm run
   188  ```
   189  
   190  <img src="./docs/gifs/kpm_run.gif" width="600" align="center" />
   191  
   192  ## OCI Registry 的支持
   193  
   194  从 kpm v0.2.0 版本开始，kpm 支持通过 OCI Registries 保存和分享 KCL 包。
   195  
   196  了解更多如何在 kpm 中使用，查看 [OCI registry 支持](./docs/kpm_oci-zh.md).
   197  
   198  ## 常见问题 (FAQ)
   199  
   200  ##### Q: 我在使用 `go install` 安装 `kpm` 后，出现了 `command not found` 的错误。
   201  
   202  A: `go install` 默认会将二进制文件安装到 `$GOPATH/bin` 目录下，您需要将 `$GOPATH/bin` 添加到环境变量 `PATH` 中。
   203  
   204  ## 了解更多
   205  
   206  - [OCI registry 支持](./docs/kpm_oci-zh.md).
   207  - [如何使用 kpm 与他人分享您的 kcl 包](./docs/publish_your_kcl_packages-zh.md)
   208  - [如何使用 kpm 在 docker.io 上与他人分享您的 kcl 包](./docs/publish_to_docker_reg-zh.md)
   209  - [kpm 命令参考](./docs/command-reference-zh/index.md)
   210  - [kcl.mod: KCL 包清单文件](./docs/kcl_mod-zh.md)
   211  - [如何使用 kpm 通过 github action 来推送您的 kcl 包](./docs/push_by_github_action-zh.md)
   212  - [发布 KCL 包到官方 Registry](./docs/publish_pkg_to_ah-zh.md)