adohe / kpm

KCL Package Manager. KCL is a constraint-based record & functional language mainly used in configuration and policy scenarios. (CNCF Sandbox Project). https://kcl-lang.io

Kpm: KCL Package Manager

English | 简体中文

Introduction | Installation | Quick start

NOTE !

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.

The affected parts are shown below:

kpm
├── pkg
│   ├── api
│   ├── client
│   ├── cmd       # The KPM CLI will deprecated after v0.8.0.
│   ├── constants
│   ├── env
│   ├── errors
│   ├── git
│   ├── oci
│   ├── opt
│   ├── package
│   ├── reporter
│   ├── runner
│   ├── semver
│   ├── settings
│   ├── utils
│   └── version
├── scripts
├── test
│   └── e2e      # The e2e test for KPM CLI will deprecated after v0.8.0.
├── ......

Introduction

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.

Installation

Install KCL

kpm will call KCL compiler to compile the kcl program. Before using kpm, you need to ensure that KCL compiler is installed successfully.

For more information about how to install KCL.

Use the following command to ensure that you install KCL compiler successfully.

kcl -v

Install kpm

Go install

You can download kpm via go install.

go install kcl-lang.io/kpm@latest

If the command kpm can not be found after executing the above command, please refer to:

• go install cannot find command after installation.

Download from GITHUB release page

You can also get kpm from the github release and set the kpm binary path to the environment variable PATH.

# KPM_INSTALLATION_PATH is the path of the `kpm` binary.
export PATH=$KPM_INSTALLATION_PATH:$PATH  

Use the following command to ensure that you install kpm successfully.

kpm --help

If you get the following output, you have successfully installed kpm and you can proceed to the following steps.

Quick Start

Init an empty kcl package

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.

kpm init my_package

kpm will create two kcl package configuration files: kcl.mod and kcl.mod.lock in the directory where you executed the command.

- my_package
      |- kcl.mod
      |- kcl.mod.lock
      |- # You can write your kcl program directly in this directory.

kcl.mod.lock is the file generated by kpm to fix the dependency version. Do not modify this file manually.

kpm initializes kcl.mod for an empty project as shown below:

[package]
name = "my_package"
edition = "0.0.1"
version = "0.0.1"

Add a dependency from Git Registry

You can then add a dependency to the current kcl package using the kpm add command

As shown below, taking the example of adding a package dependency named k8s, the version of the package is 1.27.

kpm add k8s:1.27

You can see that kpm adds the dependency you just added to kcl.mod.

[package]
name = "my_package"
edition = "0.0.1"
version = "0.0.1"

[dependencies]
k8s = "1.27" # The dependency 'k8s' with version '1.27'

Write a kcl program that uses the content in k8s

Create the main.k file in the current package.

- my_package
      |- kcl.mod
      |- kcl.mod.lock
      |- main.k # Your KCL program.

And write the following into the main.k file.

# Import and use the contents of the external dependency 'k8s'.
import k8s.api.core.v1 as k8core

k8core.Pod {
    metadata.name = "web-app"
    spec.containers = [{
        name = "main-container"
        image = "nginx"
        ports = [{containerPort = 80}]
    }]
}

Use the kpm compile the kcl package

In the my_package directory, you can use kpm to compile the main.k file you just wrote.

kpm run

Supports OCI Registry

Beginning in kpm v0.2.0, you can use container registries with OCI support to store and share kcl packages.

For more information about OCI registry support.

Frequently Asked Questions (FAQ)

Q: I am using go install to install kpm, but I get the error command not found.

• A: go install will install the binary file to $GOPATH/bin by default. You need to add $GOPATH/bin to the environment variable PATH.

Contributing

• See contribution guideline.

Learn More

• OCI registry support.
• How to share your kcl package with others using kpm.
• How to use kpm to share your kcl package with others on docker.io
• kpm command reference
• kcl.mod: The KCL package Manifest File
• How to use kpm to push your kcl package by github action
• How to publish KCL package to official Registry