Kakoune.cr

Terminal Tools
9

adding it to Homebrew (mac) would be a great move and would make installing it on a mac even quicker and easier (similar to kak-lsp)

10

https://crystal-lang.org/reference/using_the_compiler#creating-a-statically-linked-executable

For webextension-shell, I was using the following Dockerfile and command.

11

Hi, @alexherbo2!

I miss a more informative README in the project repository. Just reading the current one, I can’t tell exactly what this tool does. I guess it has something to do with your previous work on connect.kak, but since I’ve never used it, I can’t understand how Kakoune.cr is meant to be used, apart from some more or less obvious examples. Perhaps it’s easier for those with some background, but for me (and possibly others new to this kind of tool) it’s very hard to understand what it does and how to use it.

Since you are so involved in it, I understand it’s hard for you to see how difficult it is for a novice to understand it. So, I’m gonna try to give you some examples of my difficulties to make it easier for you to see the problem from the eyes of an outsider. I hope it helps =)

An excessive short description

The only description about the project is

kakoune.cr (kcr) is a command-line tool for Kakoune.

OK. A command-line tool. But what does it do? It would be of great help if that sentence would be followed by a paragraph describing the big picture: the main features, what it is supposed to do, how a normal Kakoune user would benefit from it, if it’s meant to be used for scripting or for interactive text editing… that sort of thing.

Unhelpful examples and docstrings

In the Configuration section, it’s written:

map -docstring 'New terminal' global normal <c-n> ': connect-terminal<ret>'

What does connect-terminal do? I can’t say, since it wasn’t mentioned before. So, trying to figure it out, if I have been following the README, at this point I have

evaluate-commands %sh{
  kcr init kakoune
}

in my kakrc. So I can type :connect-terminal in the prompt to see its docstring. And its only description is “Connect a terminal”. It doesn’t help.

Now, if I press <ret> to run this command, it opens another terminal and… what now? What do I do now? It appears to be just a regular terminal…

Next, in the Commands section, there is a

kcr install commands

What does it do? Which commands does it installs? Where are these commands installed?

Then, in the next lines, there is:

kcr install desktop

I guess this command installs a .desktop file at ~/.local/share/applications. But a .desktop file for what? For Kakoune? Is it for being able to launch Kakoune from my system launcher? or is there some additional functionality?

Additionally, there’s this commentary:

See #2 for 'connect' no such command: 'popup' error.

When I jump to the issue, I can read:

Im closing the issue, i just found this sweat_smile :

hook global ModuleLoaded x11 %{
alias global popup x11-terminal
}

Is it something I have to insert in my kakrc? Is this x11-terminal the only option or are there others? What is it supposed to do?

Conclusions

I hope you can see how hard it is for someone not familiar with this kind of tool to understand its scope and how to use it based solely on the docs. Even if I’ve shown some examples, there are others that could be shown, so the point is that the general communication could be improved, not just the ones from the examples I’ve given here.

All in all, I look forward to experiment with this tool. My guess is that it’s very useful indeed.

Thanks! =D

8 Likes
12

The fastest solution is probably to read connect.kak’s docs.

I would add the questions, @alexherbo2, what’s the benefit of kcr vs connect.

1 Like
13

Thanks a lot for this plugin ! There is however one point, the Crystal dependency, that is really blocking for me. Kakoune only requires a C++ compiler to work and this is really important for people deploying it on various setups (eventually without root access to install packages). I am not familiar enough with Crystal, is there really no way we could have a statically linked standalone executable for kcr ?

1 Like
14

(The below paragraph is incorrect, see next comment, left for posterity)
Sadly, no, even with the static support Crystal offers, it has certain gaps on Linux (glibc) and MacOS (system libraries). That said, I believe for the vast majority of use cases, a Crystal binary will “just work”.

Two decades in the Vim community has proven to me, over and over that plugins with no dependencies almost always win – even if functionally worse. I am not saying it is even a functional issue, or purely logical – it is emotional. Adding this with binaries or system requirements “feels bad” and people trend away from it.

I happen to have certain old Redhat machines I use Kakoune on (even had issues compiling Kakoune statically to work on them) – so staring down the barrel of another binary not provided by the distro that I have to make functional was a huge part of why I created the KPMS: Kakoune.com Plugin Maintainers Squad and moved connect.kak into it (with @alexherbo2 help and blessing).

Connect.kak is the single most important plugin, it works amazingly and stays out of my way – and works everywhere I need it to.

5 Likes
15

Huh?

kakoune.cr/.github/workflows/crystal.yml

name: Crystal CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    container:
      image: crystallang/crystal:latest-alpine
    steps:
    - uses: actions/checkout@v2
    - name: Install dependencies
      run: shards install
    - name: Build
      run: shards build --production --static --release --progress

    - uses: "marvinpinto/action-automatic-releases@latest"
      with:
        repo_token: "${{ secrets.GITHUB_TOKEN }}"
        automatic_release_tag: "latest"
        prerelease: true
        title: "Development Build"
        files: |
          ./bin/kcr

The result is statically linked binary (with musl libc) and should work everywhere. Tested on Ubuntu 20.04 and Centos 7. Dunno if GH Actions allow building Mac binaries (and honestly I don’t care). @alexherbo2 feel free to use the code above.

2 Likes
16

@TeddyDD Thanks for the correction, I must have been working off of old info. I thought it had issues it apparently doesn’t.

17

I feel that this is a inherent part of kakoune UNIX design, when you allow people to write plugins in any language. The other solution is to write plugin in “kakscript” which is not optimal neither.

3 Likes
18

Yo @gustavo-hms,

I’ve updated the README with a better documentation and added a playground.

2 Likes
19

For end users, they are quite comparable, but in terms of expressivity and robustness, connect.kak is nowhere near kakoune.cr.

I’m also curious to know how other people compare them.

3 Likes
20

Thank you for taking my observations into account, @alexherbo2! The README is much better now, and the kcr play is of great help (very good idea indeed).

I really like this program. It seems we can now somehow script Kakoune the way I would like to do.

People are complaining about it’s being written in Crystal, but I don’t see it as a problem (specially if you can provide binaries in its releases). Quite the contrary: it opens up the opportunity to be much more flexible in which languages you use to script Kakoune. As noted by @scr, this is exactly the Kakoune and POSIX way of doing things. If you want an inclusive community, you must to be open to tools written in whatever language the author is more familiar with. Diversity is the key.

Regarding kcr play, it’s worthy of notice that it works only with Kakoune compiled from master and not with the last release, since the latter lacks the -method switch of the write command.

2 Likes
21

Just added the support for static builds.

You don’t need Crystal but Docker for building.

Installation

Run make install static=yes or make release for static builds.

The latter generates a target/release.zip that you can ship everywhere.

4 Likes
22

People are complaining about it’s being written in Crystal, but I don’t see it as a problem (specially if you can provide binaries in its releases).

I added it too. =D

2 Likes
23

@alexherbo2 you should add static builds for the major platforms to the github project (a lot of Go & Rust projects do this) … not sure if there is an upcharge or if it is free on github, but I am sure some of us would donate a bit to get those binaries up.

1 Like
24

I don’t know how to do. I have read @TeddyDD’s gist but I don’t understand all the lines.

25

It is a github action responding to push or pull_request (merge) to master. It fires up a docker – builds kcr and then adds to to the github releases page (I think).

If Crystal can cross-compile for Mac from a linux docker, doing a similar thing for Mac would be straightforward. I wonder if Crystal could output both arm and intel builds for the Mac?

26

I was able to cross-compile on Mac for Linux arm64 using this guide. Command I used:

crystal build --cross-compile --target "aarch64-unknown-linux-gnu" --release -o kcr src/cli.cr

llvm target for Mac x86_64 would be:

❯ /usr/local/opt/llvm/bin/llvm-config --host-target
x86_64-apple-darwin20.3.0

so to cross-compile on Linux for Mac there is need to replace target with x86_64-apple-darwin20.3.0 or I suppose just x86_64-apple-darwin will suffice.

2 Likes
27

Cross-compiling can be difficult, because it’s not just about emitting a binary for the target platform, it also involves linking with libraries for the target platform.

I haven’t tried it with Crystal, but in my experience:

  • anything can cross-compile for Linux, because Linux has a stable syscall interface which means the compiler can just hard-code things
  • it’s possible to cross-compile for Windows as long as you’re using the MinGW toolchain, since it includes definitions of Windows APIs and freely-distributable libraries to link against
  • only Windows can build Windows binaries using the Visual C++ toolchain, since Microsoft only permits them to be installed on Windows
  • only macOS can build macOS binaries, since Apple only allows the compiler and toolchain to be installed on Apple hardware

GitHub Actions does provide macOS build agents, so you can build macOS binaries automatically. However, GitHub does not (yet) have macOS build agents running the latest OS version with the latest build tools, so building ARM binaries is not possible.

28

Just added a release with static builds for Linux.

4 Likes