Feature: use a runtime for Janet instead of embedding the core #4

New issue

Closed

opened 2025-08-31 06:06:09 +00:00 by amartin · 1 comment

amartin commented

2025-08-31 06:06:09 +00:00

(Migrated from codeberg.org)

Embedding the core is against koa's philosophy of being extensible and flexible. Following a runtime approach like (Neo)vim would better fit its design philosophy and principles.

There will be key differences with the regular way editors bundle their runtime. Editors such as Neovim will install runtime files at /usr/share/nvim/runtime on Linux systems, and while this is fine, Koa wants to go beyond what we are used to. Instead of being bundled during the installation stage into a directory the user shouldn't touch at all (because /usr/share is for system-wide programs data), Koa will most probably embed the core runtime files during compilation time.

Yes, embedding them is against the core philosophy. However, instead of embedding and running it directly from the embedded file contents as we are doing now, koa will write these files in the following cases into the ~/.local/share/koa/runtime directory:

First launch, alongside directories creation setup (we cannot write to ~/.local/share/koa/runtime if it does not exist, obviously).
If the ~/.local/share/koa/runtime directory does not exist.

Note

There will be a KOA_RUNTIME environment variable which will default to XDG_DATA_HOME or its equivalent, that can be overridden like the one in (Neo)vim, $VIMRUNTIME.

That way, we still use embedded Janet scripts but we use them only for the boostrapping process, being able to just ship the binary when making a new release. Less overhead, less work for the build system, less work for the package maintainers.

For development purposes, another environment variable will be available, KOA_DEV. This one is meant to be used by contributors and maintainers while developing koa. It will completely skip the embedded files and work directly from runtime, that way we won't need to rebuild if we change any Janet file to test the changes.

Embedding the core is against koa's philosophy of being extensible and flexible. Following a runtime approach like (Neo)vim would better fit its design philosophy and principles. There will be key differences with the regular way editors bundle their runtime. Editors such as Neovim will install runtime files at `/usr/share/nvim/runtime` on Linux systems, and while this is fine, Koa wants to go beyond what we are used to. Instead of being bundled during the installation stage into a directory the user shouldn't touch at all (because `/usr/share` is for system-wide programs data), Koa will _most_ probably embed the core runtime files during compilation time. Yes, embedding them is against the core philosophy. However, instead of embedding _and running_ it directly from the embedded file contents as we are doing now, koa will write these files in the following cases into the `~/.local/share/koa/runtime` directory: 1. First launch, alongside directories creation setup (we cannot write to `~/.local/share/koa/runtime` if it does not exist, obviously). 2. If the `~/.local/share/koa/runtime` directory does not exist. > [!NOTE] > There will be a `KOA_RUNTIME` environment variable which will default to `XDG_DATA_HOME` or its equivalent, that can be overridden like the one in (Neo)vim, `$VIMRUNTIME`. --- That way, we still use embedded Janet scripts but we use them only for the boostrapping process, being able to just ship the binary when making a new release. Less overhead, less work for the build system, less work for the package maintainers. For development purposes, another environment variable will be available, `KOA_DEV`. This one is meant to be used by contributors and maintainers while developing koa. It will completely skip the embedded files and work directly from runtime, that way we won't need to rebuild if we change any Janet file to test the changes.

amartin commented

2025-08-31 10:07:14 +00:00

(Migrated from codeberg.org)

NB: The KOA_DEV idea has been dropped, as using the Zig builtin module has a compilation mode enum. That said, Koa will automatically pick up the development runtime automatically when compiled as a debug build (the default).

NB: The `KOA_DEV` idea has been dropped, as using the Zig builtin module has a compilation mode enum. That said, Koa will automatically pick up the development runtime automatically when compiled as a debug build (the default).