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

     1  # kcl.mod: The KCL package Manifest File
     2  
     3  ## The Manifest
     4  
     5  The `kcl.mod` file for each module is called its manifest. It is written in the TOML format. It contains metadata that is needed to compile the module.
     6  
     7  In the MVP version, the sections we plan to support are as follows:
     8  - Package metadata:
     9    - [package](#package) - Defines a package.
    10      - [name](#package) — The name of the package.
    11      - [version](#package) — The version of the package.
    12      - [edition](#package) — The KCL compiler edition.
    13  - Dependency tables:
    14    - [dependencies](#dependencies) - Package library dependencies.
    15  - Compiler settings:
    16    - [profile] - The compiler settings.
    17      - [entries](#entries) - The entry points of the package when compiling.
    18  
    19  ## package
    20  
    21  The first section in a `kcl.mod` is [package].
    22  
    23  ```
    24  [package]
    25  name = "hello_world" # the name of the package
    26  version = "0.1.0"    # the current version, obeying semver
    27  edition = "0.5.0"    # the KCL compiler version
    28  ```
    29  
    30  ## dependencies
    31  
    32  Your kcl package can depend on other libraries from OCI registries, git repositories, or subdirectories on your local file system.
    33  
    34  You can specify a dependency by following:
    35  
    36  ```toml
    37  [dependencies]
    38  <package name> = <package_version>
    39  ```
    40  
    41  You can specify a dependency from git repository.
    42  
    43  ```toml
    44  [dependencies]
    45  <package name> = { git = "<git repo url>", tag = "<git repo tag>" } 
    46  ```
    47  
    48  You can specify a dependency from local file path.
    49  
    50  ```toml
    51  # Find the kcl.mod under "./xxx/xxx".
    52  [dependencies]
    53  <package name> = {path = "<package local path>"} 
    54  ```
    55  
    56  ## entries
    57  You can specify the entry points of the package when compiling.
    58  
    59  `entries` is a sub section of `profile` section. 
    60  
    61  ```toml
    62  [profile]
    63  entries = [
    64     ...
    65  ]
    66  ```
    67  
    68  `entries` is the relative path of kcl package root path, the `kcl.mod` file path is the package root path. There are two types of file paths formats supported, `normal paths` and `mod relative paths`.
    69  
    70  - normal path: The path is relative to the current package root path.
    71  - mod relative path: The path is relative to the vendor package root path that can be found by the section [dependencies](#dependencies) in `kcl.mod` file.
    72  
    73  ### For example:
    74  
    75  1. If the `kcl.mod` is localed in `/usr/my_pkg/kcl.mod`, `kpm run` will take `/usr/my_pkg/entry1.k` and `/usr/my_pkg/subdir/entry2.k` as the entry point of the kcl compiler.
    76  
    77  ```toml
    78  entries = [
    79     "entry1.k",
    80     "subdir/entry2.k",
    81  ]
    82  ```
    83  
    84  2. If the `kcl.mod` is localed in `/usr/my_pkg/kcl.mod`, and the current kcl package depends on the kcl package `k8s`. You can use the `mod relative paths` the take the kcl file in the package `k8s` as the entry point of the kcl compiler.
    85  
    86  ```toml
    87  entries = [
    88     "entry1.k",
    89     "subdir/entry2.k",
    90     "${k8s:KCL_MOD}/core/api/v1/deployment.k"
    91  ]
    92  ```
    93  
    94  The `mod relative paths` must contains the preffix `${k8s:KCL_MOD}`, `k8s` is the package name, `${k8s:KCL_MOD}` means the package root path of the package `k8s`. Therefore, if the package root path of `k8s` is `/.kcl/kpm/k8s`, the `entries` show above will take `/usr/my_pkg/entry1.k`, `/usr/my_pkg/subdir/entry2.k` and `/.kcl/kpm/k8s/core/api/v1/deployment.k` as the entry point of the kcl compiler. 
    95  
    96  ### Note
    97  You can use `normal path` to specify the compilation entry point in the current package path, and use `mod relative path` to specify the entry point in a third-party package.
    98  
    99  Therefore, the file path specified by `normal path` must come from the same package, that is, the `kcl.mod` path found from the normal path must only find one `kcl.mod` file, otherwise the compiler will output an error.
   100  
   101  For example:
   102  
   103  In the path `/usr/kcl1`:
   104  ```
   105  /usr/kcl1
   106        |--- kcl.mod
   107        |--- entry1.k
   108  ```
   109  
   110  In the path `/usr/kcl2`:
   111  ```
   112  /usr/kcl2
   113        |--- kcl.mod
   114        |--- entry2.k
   115  ```
   116  
   117  If you compile with this `kcl.mod` in the path `/usr/kcl1`:
   118  ```
   119  entries = [
   120     "entry1.k", # The corresponding kcl.mod file is /usr/kcl1/kcl.mod
   121     "/usr/kcl2/entry2.k", # The corresponding kcl.mod file is /usr/kcl2/kcl.mod
   122  ]
   123  ```
   124  
   125  You will get an error:
   126  ```
   127  error[E3M38]: conflict kcl.mod file paths
   128  ```