github.com/KusionStack/kpm@v0.8.4-0.20240326033734-dc72298a30e5/README.md (about) 1 <h1 align="center">Kpm: KCL Package Manager</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">Introduction</a> | <a href="#installation">Installation</a> | <a href="#quick-start">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 # NOTE ! 17 [](https://app.fossa.com/projects/git%2Bgithub.com%2Fkcl-lang%2Fkpm?ref=badge_shield) 18 19 20 The KPM CLI will be deprecated after v0.8.0, and the KPM CLI will be replaced by the KCL CLI - https://github.com/kcl-lang/cli. 21 22 The affected parts are shown below: 23 24 ``` 25 kpm 26 ├── pkg 27 │ ├── api 28 │ ├── client 29 │ ├── cmd # The KPM CLI will deprecated after v0.8.0. 30 │ ├── constants 31 │ ├── env 32 │ ├── errors 33 │ ├── git 34 │ ├── oci 35 │ ├── opt 36 │ ├── package 37 │ ├── reporter 38 │ ├── runner 39 │ ├── semver 40 │ ├── settings 41 │ ├── utils 42 │ └── version 43 ├── scripts 44 ├── test 45 │ └── e2e # The e2e test for KPM CLI will deprecated after v0.8.0. 46 ├── ...... 47 ``` 48 49 ## Introduction 50 51 `kpm` is the KCL package manager. `kpm` downloads your KCL package's dependencies, compiles your KCL packages, makes packages, and uploads them to the kcl package registry. 52 53 ## Installation 54 55 ### Install KCL 56 57 `kpm` will call [KCL compiler](https://github.com/KusionStack/KCLVM) to compile the kcl program. Before using `kpm`, you need to ensure that `KCL compiler` is installed successfully. 58 59 [For more information about how to install KCL.](https://kcl-lang.io/docs/user_docs/getting-started/install) 60 61 Use the following command to ensure that you install `KCL compiler` successfully. 62 63 ```shell 64 kcl -v 65 ``` 66 67 ### Install `kpm` 68 69 #### Go install 70 71 You can download `kpm` via `go install`. 72 73 ```shell 74 go install kcl-lang.io/kpm@latest 75 ``` 76 77 If the command `kpm` can not be found after executing the above command, please refer to: 78 79 - [go install cannot find command after installation.](#q-i-am-using-go-install-to-install-kpm-but-i-get-the-error-command-not-found) 80 81 #### Download from GITHUB release page 82 83 You can also get `kpm` from the github release and set the `kpm` binary path to the environment variable PATH. 84 85 ```shell 86 # KPM_INSTALLATION_PATH is the path of the `kpm` binary. 87 export PATH=$KPM_INSTALLATION_PATH:$PATH 88 ``` 89 90 Use the following command to ensure that you install `kpm` successfully. 91 92 ```shell 93 kpm --help 94 ``` 95 96 If you get the following output, you have successfully installed `kpm` and you can proceed to the following steps. 97 98 <img src="./docs/gifs/kpm_help.gif" width="600" align="center" /> 99 100 ## Quick Start 101 102 ### Init an empty kcl package 103 104 Create a new kcl package named `my_package`. And after we have created the package `my_package`, we need to go inside the package by `cd my_package` to complete the following operations. 105 106 ```shell 107 kpm init my_package 108 ``` 109 110 <img src="./docs/gifs/kpm_init.gif" width="600" align="center" /> 111 112 `kpm` will create two kcl package configuration files: `kcl.mod` and `kcl.mod.lock` in the directory where you executed the command. 113 114 ```shell 115 - my_package 116 |- kcl.mod 117 |- kcl.mod.lock 118 |- # You can write your kcl program directly in this directory. 119 ``` 120 121 `kcl.mod.lock` is the file generated by `kpm` to fix the dependency version. Do not modify this file manually. 122 123 `kpm` initializes `kcl.mod` for an empty project as shown below: 124 125 ```shell 126 [package] 127 name = "my_package" 128 edition = "0.0.1" 129 version = "0.0.1" 130 ``` 131 132 ### Add a dependency from Git Registry 133 134 You can then add a dependency to the current kcl package using the `kpm add` command 135 136 As shown below, taking the example of adding a package dependency named `k8s`, the version of the package is `1.27`. 137 138 ```shell 139 kpm add k8s:1.27 140 ``` 141 142 <img src="./docs/gifs/kpm_add_k8s.gif" width="600" align="center" /> 143 144 You can see that `kpm` adds the dependency you just added to kcl.mod. 145 146 ```shell 147 [package] 148 name = "my_package" 149 edition = "0.0.1" 150 version = "0.0.1" 151 152 [dependencies] 153 k8s = "1.27" # The dependency 'k8s' with version '1.27' 154 ``` 155 156 ### Write a kcl program that uses the content in `k8s` 157 158 Create the `main.k` file in the current package. 159 160 ```shell 161 - my_package 162 |- kcl.mod 163 |- kcl.mod.lock 164 |- main.k # Your KCL program. 165 ``` 166 167 And write the following into the `main.k` file. 168 169 ```kcl 170 # Import and use the contents of the external dependency 'k8s'. 171 import k8s.api.core.v1 as k8core 172 173 k8core.Pod { 174 metadata.name = "web-app" 175 spec.containers = [{ 176 name = "main-container" 177 image = "nginx" 178 ports = [{containerPort = 80}] 179 }] 180 } 181 182 ``` 183 184 ### Use the `kpm` compile the kcl package 185 186 In the `my_package` directory, you can use `kpm` to compile the `main.k` file you just wrote. 187 188 ```shell 189 kpm run 190 ``` 191 192 <img src="./docs/gifs/kpm_run.gif" width="600" align="center" /> 193 194 ## Supports OCI Registry 195 196 Beginning in kpm v0.2.0, you can use container registries with OCI support to store and share kcl packages. 197 198 For more information about [OCI registry support](./docs/kpm_oci.md). 199 200 ## Frequently Asked Questions (FAQ) 201 202 ##### Q: I am using `go install` to install `kpm`, but I get the error `command not found`. 203 204 - A: `go install` will install the binary file to `$GOPATH/bin` by default. You need to add `$GOPATH/bin` to the environment variable `PATH`. 205 206 ## Contributing 207 208 - See [contribution guideline](https://kcl-lang.io/docs/community/contribute/). 209 210 ## Learn More 211 212 - [OCI registry support](./docs/kpm_oci-zh.md). 213 - [How to share your kcl package with others using kpm](./docs/publish_your_kcl_packages-zh.md). 214 - [How to use kpm to share your kcl package with others on docker.io](./docs/publish_to_docker_reg.md) 215 - [kpm command reference](./docs/command-reference/index.md) 216 - [kcl.mod: The KCL package Manifest File](./docs/kcl_mod.md) 217 - [How to use kpm to push your kcl package by github action](./docs/push_by_github_action.md) 218 - [How to publish KCL package to official Registry](./docs/publish_pkg_to_ah.md) 219 220 221 ## License 222 [](https://app.fossa.com/projects/git%2Bgithub.com%2Fkcl-lang%2Fkpm?ref=badge_large)