# Plugin creation guide

**URL:** <https://discuss.kakoune.com/t/plugin-creation-guide/447>\
**Category:** Help\
**Created:** [April 10, 2019, 5:16am UTC](https://discuss.kakoune.com/t/plugin-creation-guide/447 "2019-04-10T05:16:45Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![xyuusha](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/xyuusha/32/48_2.png) [@xyuusha](https://discuss.kakoune.com/u/xyuusha)\
**Post date:** [April 10, 2019, 5:16am UTC](https://discuss.kakoune.com/t/plugin-creation-guide/447/1 "2019-04-10T05:16:45Z")

</div>

I was trying to write a plugin for myself but I found several pain points.

- I tried to read other plugins and try the same techniques, but they differ quite a lot and it looks like there is no standar way of doing anything.
- I struggled a lot with debugging and reloading the changes. Is there a way of working other than printing and reopening the files?

I would like to know if there is some guides, guidelines, FAQs, tips, tutorials or something that can help me with creating them and avoiding common pitfalls.

---

<div class="post-metadata">

**Author:** ![andreyorst](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/andreyorst/32/29_2.png) [@andreyorst](https://discuss.kakoune.com/u/andreyorst)\
**Post date:** [April 10, 2019, 5:53am UTC](https://discuss.kakoune.com/t/plugin-creation-guide/447/2 "2019-04-10T05:53:30Z")

</div>

I’ve developed several [semi](https://github.com/andreyorst/plug.kak) [popular](https://github.com/andreyorst/fzf.kak) [plugins](https://github.com/andreyorst/powerline.kak), and that’s the steps I usually go through when developing.

Step one:  
Think about what plugin should do. Define some base functions.  
Step two:  
Roll your face over the keyboard several times to provide clean and understandable Sh code.  
Step three:  
???  
Step four:  
Release!

* * *

On a more serious note, I often create a bunch of commands with `-override` switch to easier reloading, and use `echo -debug` to print debug messages. That’s enough for me to debug, because my main job is to write for SoC, and we have no debuggers, so printing is the only option acutally. Kakoune’s state can be expresses by printing pretty well.

Please, please don’t use aliases for builtin commands like `def`, `set`, `decl` e.t.c. It’s hard to read.

> [@xyuusha](#):
>
> I would like to know if there is some guides, guidelines

[There is](https://github.com/mawww/kakoune/blob/master/doc/writing_scripts.asciidoc). It contains essential bits, but pretty much about overall structure.

> [@xyuusha](#):
>
> I struggled a lot with debugging and reloading the changes. Is there a way of working other than printing and reopening the files?

@alexherbo2 showed me [this way of evaluating buffer, or selection](https://github.com/andreyorst/dotfiles/blob/87ab59dd00ffd35c6319e33892fcd5b116276f62/.config/kak/commands.kak#L141-L149), which I use now instead of `:source %val{buffile}`

---

<div class="post-metadata">

**Author:** ![alexherbo2](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/alexherbo2/32/1140_2.png) [@alexherbo2](https://discuss.kakoune.com/u/alexherbo2)\
**Post date:** [April 10, 2019, 11:39am UTC](https://discuss.kakoune.com/t/plugin-creation-guide/447/3 "2019-04-10T11:39:48Z")

</div>

@xyuusha Don’t do the reloading stuff. It’s better to work with two instances: one for writing the plug-in and one other for testing it.

1. Create a new repository to hold the plug-in’s files.
2. Source your plug-in from your `kakrc`.
3. Write some functionalities, and eventually reconfigure your `kakrc`.
4. In a separate instance / window / place:  
4.1 Open a meaningful document to experiment your functionalities,  
4.2 Do some tests,  
4.3 Quit,  
4.4 Repeat.

If you want to automate _Step 4_, you can do:

```auto
kak document.txt -e "
  your-command
  execute-keys -with-maps -with-hooks <keys>
  …
"

```

If you don’t want to modify your `kakrc` in _Step 2 and 3_, you can inject the configuration in the `kak` command:

```auto
kak document.txt -e "
  source your-plugin.kak
  hook <scope> <event> <filter> %{
    your-command
  }
  map <scope> <mode> <key> ': your-command<ret>'
  …
"

```