coc-autark
Version:
Autark build-script completion for coc.nvim
141 lines (112 loc) • 6.4 kB
Markdown
# coc-autark
[CoC](https://github.com/neoclide/coc.nvim) completion for
[Autark](https://autark.dev) build scripts (`Autark` and `*.autark`).
The extension is context-aware: it recognises the Autark rule bag structure and
only offers what is meaningful at the cursor.
| Cursor position | Completion |
|---|---|
| top level / rule bodies | directives (`set`, `cc`, `run`, `include`, `check`, ...) |
| `set` / `let` / `library` first word | `parent`, `root`, `_` |
| `cc` / `cxx` / `host-cc` / `host-cxx` | `objects`, `consumes`, `modules` |
| `run` / `run-on-install` | `exec`, `shell`, `consumes`, `produces`, `always`, `host` |
| `if` / `and` / `or` | conditions `defined`, `eq`, `prefix`, `contains`, `in`, `and`, `or` and their `!` forms |
| `meta` | `name`, `version`, `license`, ... |
| `toolchain` | `id`, `system`, `arch`, `bits`, `endian`, `cc`, `host-cc`, `runner`, ... |
| `echo` | `init`, `setup`, `build` |
| `check` | check scripts from `.autark/` plus the standard Autark scripts; file paths for `changelog_gnu.sh` / `changelog_md.sh` |
| `call` | macros declared in the buffer |
| `install` / `install-sources` | `exact`, then project files |
| `include` / `configure` | project files |
| `${...}` | built-in variables, `set`/`let`/`library`/`env`/`option`/`macro`/`foreach`/`meta` declarations of the current buffer, `objects { ... }` names, check-script result variables and variables of the included scripts / build cache |
| `S{...}`, `SS{...}`, `C{...}`, `CC{...}`, `%{...}` | paths relative to the project root, the script directory, the project cache or the unit cache |
| `@{...}`, `@@{...}`, `^{...}`, `&{...}` | nothing (commands and expressions) |
Paths, check-script arguments and variables are completed with their documentation;
every item is annotated with a short description in the preview window.
## Requirements
- CoC `0.0.82` or newer: the extension is an ES module and is loaded through
CoC's ESM extension loader, which needs Node started with
`--experimental-vm-modules` (CoC passes that flag by default);
- Node.js 18 or newer;
- a buffer with filetype `autark`. This repository ships the
`ftdetect/autark.vim` runtime file (`Autark`, `*.autark`), so installing the
grammar as a Vim/Neovim plugin is enough;
- for path and variable completion the file has to be saved inside a project,
i.e. below a directory containing the root `Autark` script.
## Installation
```
:CocInstall coc-autark
```
`coc-autark` lives in [`editors/coc`](./) of the
[`Softmotions/tree-sitter-autark`](https://github.com/Softmotions/tree-sitter-autark)
repository and is published to the npm registry from that directory
(`npm publish`).
### Install from a checkout (development)
CoC only installs from the npm registry or from a GitHub repository whose root
`package.json` is the extension, so a local checkout is wired in manually:
```sh
cd editors/coc
ln -sfn "$PWD" ~/.config/coc/extensions/node_modules/coc-autark
```
and add the package to the dependencies of
`~/.config/coc/extensions/package.json`:
```json
{
"dependencies": {
"coc-autark": "*"
}
}
```
Restart Neovim/Vim afterwards. Extension updates must be pulled manually because
CoC skips symbolic links.
## Configuration
Configuration lives in `coc-settings.json` (`:CocConfig`):
| Setting | Default | Description |
|---|---|---|
| `autark.enabled` | `true` | Enable completion. |
| `autark.filetypes` | `["autark"]` | Filetypes where completion is registered. |
| `autark.cacheDir` | `"autark-cache"` | Project cache directory used by `C{}` / `CC{}`. If it does not exist, the first `autark-cache*` directory is used (covers `-H` builds). |
| `autark.checkScriptDirs` | `[".autark", "autark"]` | Directories scanned for check scripts, in the current script directory and its parents. |
| `autark.completePaths` | `true` | Complete file paths. |
## Variable inference
Autark evaluates many variables lazily, so the extension infers names from every
available source instead of only the current buffer. For `${...}` completion the
candidates are, in this order:
1. well-known variables (`AUTARK_*`, `INSTALL_*`, `CC`, `CFLAGS`, `SYSTEM_*`,
`META_*`, `CHANGELOG_*`, ...);
2. declarations of the buffer: `set`/`let`/`library` (including `parent { ... }`
and `root { ... }` scopes), `env`, `option`, `macro`, `foreach`, `meta` and
`objects { NAME }` of `cc`/`cxx`/`host-cc`/`host-cxx`;
3. result variables of check scripts whose last argument is the variable name
(`test_header.sh`, `test_symbol.sh`, `test_blocks.sh`, `fetch_resource.sh`);
4. declarations of the whole project: the root `Autark` script (the parent
scope of every child) and every script reachable through `include`, with the
defining file and line in the item detail;
5. variables recorded by previous builds in the cache: `*.env` files (name and
current value, e.g. check results) and the `e`/`s` environment entries of
`*.deps` files. This scan is bounded (depth 3, 300 files) and cached for a
few seconds.
The last two sources explain why a variable may be suggested even though it is
not declared in the current script.
## Notes and limitations
- Completion only: no diagnostics, no build invocation.
- Variables that come only from `-D` command line options or the environment
(`BUILD_TYPE`, `ENABLE_ASAN`, ...) cannot be inferred statically; the common
conventions are part of the built-in list.
- Autark tokens may contain `-` and `/`, which Vim does not consider keyword
characters. The extension replaces the whole typed token, so completion keeps
working for names such as `run-on-install` and for paths.
- `C{}` / `CC{}` complete existing directories only; run a build to populate
`autark-cache` before completing generated files.
- Cache-derived variables reflect the last build: stale names of removed check
scripts can still be suggested until the cache is cleaned.
## Development
The extension is plain ES module JavaScript (`"type": "module"`) without a build
step. Only `lib/index.js` imports `coc.nvim`; `lib/provider.js` receives the
API as an argument, so registration and configuration are testable with a fake
API, and the completion core (`scan.js`, `paths.js`, `data.js`,
`completion.js`) has no coc dependency at all.
```sh
node test/run.js
```
`test/run.js` documents the expectations of the scanner, the completion core
and the extension wiring.