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

     1  # kcl.mod: KCL 包清单文件
     2  
     3  ## 1. KCL 包清单
     4  
     5  每个模块的 `kcl.mod` 文件都被称为其清单。它采用 TOML 格式编写，包含编译模块所需的元数据。
     6  
     7  目前 `kcl.mod` 中支持如下内容：
     8  
     9  - 包元数据：
    10    - [package](#package) - 定义一个包。
    11      - [name](#package) — 包的名称。
    12      - [version](#package) — 包的版本。
    13      - [edition](#package) — KCL 编译器版本。
    14  - 依赖表：
    15    - [dependencies](#dependencies) - 包库依赖项。
    16  - 编译器设置：
    17    - [profile](#entries) - 编译器设置。
    18      - [entries](#entries) - 编译包的入口点。
    19  
    20  ## 2. package
    21  `kcl.mod` 中的第一个部分是 `[package]`。主要包含 `name`, `version` 和 `edition` 三个字段。
    22  
    23  ### 2.1. name
    24  `name` 是包的名称，它是一个字符串, 这是一个必要的字段, 注意，包的名称中不可以包含`"."`。
    25  
    26  例如: 一个包名为 my_pkg 的 kcl 程序包。
    27  ```
    28  [package]
    29  name = "my_pkg"
    30  ```
    31  
    32  ### 2.2. version
    33  `version` 是包的版本，它是一个字符串, 这是一个必要的字段。注意，目前 KCL 程序包的版本号仅支持语义化版本号。
    34  
    35  例如: `my_pkg` 程序包的版本号为 `0.1.0`。
    36  ```
    37  [package]
    38  name = "my_pkg"
    39  version = "0.1.0"
    40  ```
    41  
    42  ### 2.3. edition
    43  `edition` 是 KCL 编译器版本，它是一个字符串, 这是一个必要的字段。注意，目前 KCL 编译器版本号仅支持语义化版本号。
    44  
    45  例如: `my_pkg` 程序包的版本号为 `0.1.0`, 并且与 0.5.1 的 KCL 编译器兼容。
    46  ```
    47  [package]
    48  name = "my_pkg"
    49  version = "0.1.0"
    50  edition = "0.5.0"
    51  ```
    52  
    53  ## 3. dependencies
    54  
    55  你的 kcl 包可以依赖于来自 OCI 仓库、Git 存储库或本地文件系统子目录的其他库。
    56  
    57  ### 3.1. oci dependency
    58  
    59  kpm 默认将包保存在 oci registry 上，默认使用的 oci registry 是 `ghcr.io/kcl-lang`。
    60  更多内容关于 oci registry 请参考 [kpm 支持 OCI registry](./docs/kpm_oci-zh.md)。
    61  
    62  你可以按照以下方式指定依赖项：
    63  
    64  ```toml
    65  [dependencies]
    66  <package name> = <package_version>
    67  ```
    68  
    69  这将会从 oci registry 中拉取名称为 `<package name>` 的包，版本为 `<package_version>`。
    70  
    71  如果您希望拉取 `k8s` 包的 `1.27` 版本:
    72  
    73  ```toml
    74  [dependencies]
    75  k8s = "1.27"
    76  ```
    77  
    78  ### 3.2. git dependency
    79  
    80  从 Git 存储库指定依赖项:
    81  ```
    82  [dependencies]
    83  <package name> = { git = "<git repo url>", tag = "<git repo tag>" } 
    84  ```
    85  
    86  这将会从 Git 存储库`<git repo url>`中拉取名称为 `<package name>` 的包，`tag` 为 `<git repo tag>`。
    87  
    88  ## 4. entries
    89  
    90  你可以在编译时指定包的入口点。
    91  
    92  `entries` 是 `[profile]` 部分的子部分。entries 是一个字符串数组，包含编译器的入口点。这是一个可选的字段，如果没有指定，则默认为包根目录下的所有 `*.k` 文件。
    93  
    94  ```toml
    95  [profile]
    96  entries = [
    97     ...
    98  ]
    99  ```
   100  
   101  entries 中可以定义绝对路径和相对路径，如果定义的是相对路径，那么就会以当前包的 
   102  
   103  `entries` 是 kcl 包根路径的相对路径，`kcl.mod` 文件路径是包的根路径。支持两种文件路径格式，即 `normal paths` 和 `mod relative paths`。
   104  
   105  - normal path：相对于当前包的根路径。
   106  - mod relative path：相对于 kcl.mod 中 [dependencies](#dependencies) 部分中的三方包的根路径。
   107  
   108  例如：
   109  1. 如果 `kcl.mod` 位于 `/usr/my_pkg/kcl.mod`，则 `kpm run` 将把 `/usr/my_pkg/entry1.k` 和 `/usr/my_pkg/subdir/entry2.k` 作为 `kcl` 编译器的入口点。
   110  
   111  ```
   112  entries = [
   113     "entry1.k",
   114     "subdir/entry2.k",
   115  ]
   116  ```
   117  
   118  2. 如果 `kcl.mod` 位于 `/usr/my_pkg/kcl.mod`，并且当前 `kcl` 包依赖于 `kcl` 包 `k8s`。你可以使用 `mod relative paths` 将来自包 `k8s` 中的 `kcl` 文件作为 `kcl` 编译器的入口点。
   119  
   120  ```
   121  entries = [
   122     "entry1.k",
   123     "subdir/entry2.k",
   124     "${k8s:KCL_MOD}/core/api/v1/deployment.k"
   125  ]
   126  ```
   127  
   128  `mod relative paths` 必须包含前缀 `${k8s:KCL_MOD}`，其中 `k8s` 是包名，`${k8s:KCL_MOD}` 表示包 k8s 的包根路径。因此，如果 `k8s` 的包根路径是 `/.kcl/kpm/k8s`，则上面的 `entries` 将把 `/usr/my_pkg/entry1.k`、`/usr/my_pkg/subdir/entry2.k` 和 `/.kcl/kpm/k8s/core/api/v1/deployment.k` 作为 `kcl` 编译器的入口点。
   129  
   130  ### 注意
   131  你可以使用 `normal path` 指定当前包路径中的编译入口点，使用 `mod relative path` 指定三方包中的入口点。
   132  
   133  因此，使用 `normal path` 制定的文件路径必须来自于同一个包，即从 `normal path` 开始寻找的 `kcl.mod` 路径必须只能找到一个 `kcl.mod` 文件，不然编译器将输出错误。
   134  
   135  例如:
   136  
   137  在路径 `/usr/kcl1` 下
   138  ```
   139  /usr/kcl1
   140        |--- kcl.mod
   141        |--- entry1.k
   142  ```
   143  
   144  在路径 `/usr/kcl2` 下
   145  ```
   146  /usr/kcl2
   147        |--- kcl.mod
   148        |--- entry2.k
   149  ```
   150  
   151  如果你在路径`/usr/kcl1`下使用这样的 kcl.mod 编译：
   152  ```
   153  entries = [
   154     "entry1.k", # 对应的 kcl.mod 文件是 /usr/kcl1/kcl.mod
   155     "/usr/kcl2/entry2.k", # 对应的 kcl.mod 文件是 /usr/kcl2/kcl.mod
   156  ]
   157  ```
   158  
   159  将会得到错误：
   160  ```
   161  error[E3M38]: conflict kcl.mod file paths
   162  ```