[FAQ] Error when trying to create and use a plugin: Need some clarifications please

[soubinan]

The issue encountered

Hello, I was not sure if this one should go to the BUG category or no.
Could someone confirm the procedure to create and use a plugin, please ? For python (for golang if python is not possible).
I checked the doc (from v0.4 to v0.9) but it seems something is missing...

I followed both the golang and the python examples, but none of them worked for me, and always receiving the same error message as shared below:

Error: error[E2F04]: CannotFindModule
 --> /test.k:1:1
  |
1 | import kcl_plugin.my_plugin
  | ^ the plugin package `kcl_plugin.my_plugin` is not found, please confirm if plugin mode is enabled
  |

In some document version we are supposed to use kcl_plugin (but not explained how to install it)
In some other I found it is an alias of the kclvm.tools.plugin python package
In some (the more recent), there is no mention of these steps
None of all versions I checked is mentioning what is the plugin mode and how to enable it (but it is mentioned it was disabled by default for python, then not sure if it has been re-enabled or no)

But all share the same thing, none of those procedures works for me.
It is a bit confusing and lead me to many questions:

• how to create a plugin ? (it is mentioned is old versions, no longer in newer, so not sure what to do)
• where to store it so kcl will be able to see it ?
• how to enable the plugin mode ?
• how to use a plugin in a kcl file ? (it is mentioned, but since it is not working for me, a clarification/confirmation of to do would be great)

Additional info

I am currently using the latest kcl version:

$ kclvm_cli version
Version: 0.9.2-c020ab3eb4b9179219d6837a57f5d323
Platform: x86_64-unknown-linux-gnu
GitCommit: VERGEN_IDEMPOTENT_OUTPUT

$ kcl version
0.9.4-linux-amd64

Thanks !

[Peefy]

Hello @soubinan

https://www.kcl-lang.io/docs/reference/plugin/overview

According to the latest documentation of KCL v0.9, it is currently supported to use Go, Python, and Java to write plugins for KCL, but they need to be used in the corresponding Go SDK, Python SDK, or Java SDK, such as for the Go SDK.

package main

import (
    "fmt"

    "kcl-lang.io/kcl-go/pkg/kcl"
    "kcl-lang.io/kcl-go/pkg/native"                // Import the native API
    _ "kcl-lang.io/kcl-go/pkg/plugin/hello_plugin" // Import the hello plugin
)

func main() {
    // Note we use `native.MustRun` here instead of `kcl.MustRun`, because it needs the cgo feature.
    yaml := native.MustRun("main.k", kcl.WithCode(code)).GetRawYamlResult()
    fmt.Println(yaml)
}

const code = `
import kcl_plugin.hello

name = "kcl"
three = hello.add(1,2)  # hello.add is written by Go
`

The plugin location is here. https://github.com/kcl-lang/kcl-plugin/tree/main/hello

There are some other examples:

• KCL Helm Plugin: https://github.com/cakehappens/kcfoil/blob/main/cmd/kcf/template.go

[soubinan]

Hello @Peefy, thank you for your feedback
I checked the examples your shared and tried my best to have a working example, still at the same point with questions neither the exemples or the documentation answer.

• where to store the plugin so kcl will be able to see it ? the location your shared is an example repo. Not sure to get the point, is this means I have to store my plugin there to use it ? I assume there is a local location where plugins should be stored, it is what I am looking for actually.
• You said I have to use it via the SDK: is this meaning it is not possible to use something like kcl run my_config.k ? but instead I have to use something like python my_plugin.py ?
  Sorry for asking it again but the examples shared do not contains any guidance about the way they have been created, neither how they should be used.
• Lets get the https://github.com/cakehappens/kcfoil/blob/main/cmd/kcf/template.go as key example: when I see https://github.com/cakehappens/kcfoil/blob/main/example.k my first though is that it will work with kcl run example.k but it is not. Then I do not see any command example about how to use this plugin, nor how to get/store it. Should I use kcl mod add command? I understood module and plugins are different so not sure at all where to go from this. Or a git pull and store it somewhere (where) on my machine ?). It is not very straightforward to guess since the most evident commands I tried did not worked. It is more like a go project rather than a kcl one.
• Following your example since it is different from the other your shared, I have been a bit more confudsed..
  If I just want to reporduce your example, is that means the kcl configuration where I want to import my plugin should be wrapped in a go or python code ? so I will have to use python my_plugin.py ? what is about the previous examples then ?
  My plugin is supposed to be used in many part of my configuration and I am using abstractions so my commands are lioke kcl run test.k main.k -D option1=value1 -D option2=value2, how to deal with it using the SDK ?

[Peefy]

Thank you for your detailed reply. Currently, plugins are only supported in the SDK for various languages such as Python, Go and Java. If you want to use plugins in the CLI, the plugin author would need to release a new version of the KCL plugin that includes the plugin for CLI usage. The KCL does not yet support automated management and registration of plugins, but this may be supported in a future version.

Just as an example, I will show you how to use Go and Python to create and publish KCL CLI with plugins.

• Go

kcl-lang/cli#120

• Python

Just like Go, you can write Python code to call KCL Python API for extension.

[Peefy]

In addition, with package management in languages such as Go and Python, you can store these packages anywhere you like by registering them before calling the KCL API.

[soubinan]

Thank you @Peefy
I finally got it!
Very grateful for your help!