Skip to content

tt emmylua

Commands for EmmyLua (github.com/EmmyLuaLs/emmylua-analyzer-rust), the analyzer of annotated Lua: prepare puts its programs into the project as the dev dependency emmylua, check, doc, fmt and ls run them, config writes the configuration they run with, and rock packs the rocks of a release for a rock server.

The programs run with what tt knows of the project: LuaJIT, the globals of Tarantool, the EmmyLua stubs of the Tarantool the project runs on (share/tarantool/emmylua, Tarantool 3.9 and newer) and the modules its rocks install. The project's own .emmyrc.json is read after that and adds to it. The emmylua rock of every platform comes from the index of tarantool-contrib/rocks-repo; prepare --from and rock pack it themselves, from a local build or from the releases the module knows.

The project is the one the current directory is in, found as the other project commands of tt find it. Outside every project check, doc, fmt and ls need no prepare: they run the programs of the rock, fetched once into the user cache (tt/emmylua there), with the configuration kept there too; --rock-server names another server, a directory of rocks to work offline.

Usage

tt emmylua
tt emmylua [flags] <command> [command flags]

Commands

tt emmylua check

Run emmylua_check on the project with the configuration tt writes, then the project's .luarc.json, .emmyrc.json and .emmyrc.lua, as ls reads them. The command fails as emmylua_check does: when it reports an error, or with --warnings-as-errors a warning. --warnings-as-errors, -f/--output-format and --severity go to emmylua_check as they are, its other flags, such as --ignore and --output, after --. Arguments after -- go to the program as they are.

With no PATH the command checks the whole project but .rocks/, .tarantool/ and _build/, and in a git work tree but the files git ignores (.gitignore, .git/info/exclude, core.excludesFile). A PATH, a directory or a file of the project, narrows what is checked to the files under it, git ignoring it or not, and with more than one to the files under any: the rest of the project is read as a library, so its modules resolve and are not checked, and EmmyLua still runs on the root of the project, so the module names, the relative paths of the configuration and the paths it prints are those of the whole project. Outside every project a PATH must be in the current directory.

Outside every project the programs come from the user cache, fetched there once from the rock server (--rock-server, --version), and the configuration tt writes is kept there too, not in the directory.

Usage

tt emmylua check [PATH...] [flags] [-- EMMYLUA_CHECK_ARGS...]

Flags

  • --library stringArray - read the Lua modules of this directory as a library too; repeat for more
  • -f, --output-format string - the format of the report: text, json, sarif, github or gitlab (gitlab from EmmyLua 0.30)
  • --rock-server string - outside a project, the rock server to fetch EmmyLua from: a URL, or a directory of rocks such as tt package download emmylua --registry URL --dir DIR fills, to work offline (default the rock index of tarantool-contrib/rocks-repo)
  • --severity string - report the diagnostics of this severity and above: error, warn, info or hint
  • --version string - outside a project, the EmmyLua release to run; a project runs the one its lock pins (default 0.30.0pre1)
  • --warnings-as-errors - fail on a warning as on an error

Examples

$ tt emmylua check
$ tt emmylua check app --warnings-as-errors -f json -- --output report.json

# Outside a project, with the modules of a checkout of a rock.
$ tt emmylua check --library ~/src/checks

tt emmylua config

Write the configuration tt gives EmmyLua - LuaJIT, the globals of Tarantool, the stubs of the Tarantool the project runs on and the modules its rocks install, with .rocks/, .tarantool/, the build tree _build/ and, in a git work tree, what git ignores left out of the code of the project, and the project's own package, which tt package build installs into .rocks/, out of the libraries - to .tarantool/emmylua/emmyrc.json of the project and print its path: for an editor that runs emmylua_ls itself, through EMMYLUALS_CONFIG. The other commands write it anew on every run.

Outside every project it is written into the user cache, one file for each directory, with the modules of .rocks/ of the directory, and the directory is left as it is.

Usage

tt emmylua config [flags]

Flags

  • --library stringArray - read the Lua modules of this directory as a library too; repeat for more

Examples

$ EMMYLUALS_CONFIG=$(tt emmylua config) code .

tt emmylua doc

Run emmylua_doc_cli on the project with the configuration tt writes, then the project's .luarc.json, .emmyrc.json and .emmyrc.lua, as ls reads them: it writes the documentation of the annotated code, by default as an HTML site in ./output. -o/--output and -f/--output-format go to emmylua_doc_cli as they are, its other flags, such as --site-name, after --. Arguments after -- go to the program as they are.

With no PATH the command documents the whole project but .rocks/, .tarantool/ and _build/, and in a git work tree but the files git ignores (.gitignore, .git/info/exclude, core.excludesFile). A PATH, a directory or a file of the project, narrows what is documented to the files under it, git ignoring it or not, and with more than one to the files under any: the rest of the project is read as a library, so its modules resolve and are not documented, and EmmyLua still runs on the root of the project, so the module names, the relative paths of the configuration and the paths it prints are those of the whole project. Outside every project a PATH must be in the current directory.

Outside every project the programs come from the user cache, fetched there once from the rock server (--rock-server, --version), and the configuration tt writes is kept there too, not in the directory.

Usage

tt emmylua doc [PATH...] [flags] [-- EMMYLUA_DOC_CLI_ARGS...]

Flags

  • --library stringArray - read the Lua modules of this directory as a library too; repeat for more
  • -o, --output string - the directory to write the documentation to, or a file for json (default ./output)
  • -f, --output-format string - the format of the documentation: html, markdown or json (default html)
  • --rock-server string - outside a project, the rock server to fetch EmmyLua from: a URL, or a directory of rocks such as tt package download emmylua --registry URL --dir DIR fills, to work offline (default the rock index of tarantool-contrib/rocks-repo)
  • --version string - outside a project, the EmmyLua release to run; a project runs the one its lock pins (default 0.30.0pre1)

Examples

$ tt emmylua doc -o doc/api -- --site-name "My application"
$ tt emmylua doc -f json -o api.json

tt emmylua fmt

Run luafmt, the formatter of EmmyLua, on PATH (default the project): with --check, the default, it prints how the files would change and fails if any would; with --write it rewrites them. It reads .luafmt.toml or luafmt.toml and .luafmtignore, not the configuration of the analyzer. It parses LuaJIT, as check does, unless [syntax] level of that configuration or --level after -- names another: luafmt alone parses Lua 5.5.

With no PATH, in a git work tree, it formats the Lua files git sees under the project: tracked, and untracked but not ignored by .gitignore, .git/info/exclude or core.excludesFile; luafmt runs in the root of the project, given the list, and still skips the hidden files, those of .luafmtignore and --exclude. A submodule is left out, and so are _build/, where tt builds the project out of its sources, .rocks/ and .tarantool/, even when the project tracks them. Out of a git work tree, in a directory git ignores, or without git, it walks the whole project but _build/, as check, doc and ls do. A PATH is formatted as given.

The other flags of luafmt, such as --list-different, go after --, and one that chooses what luafmt does takes the place of --check; one that formats no files, such as --init, --explain-config or --stdin, gets no list of them. --init with no file writes luafmt.toml into the root of the project, and the configuration it writes gets the [syntax] level of LuaJIT, where luafmt writes Lua55, unless --level follows --. Arguments after -- go to the program as they are.

Outside every project luafmt comes from the user cache, fetched there once from the rock server (--rock-server, --version).

Usage

tt emmylua fmt [PATH...] [flags] [-- LUAFMT_ARGS...]

Flags

  • --check - print how the files would change and fail if any would (the default)
  • --rock-server string - outside a project, the rock server to fetch EmmyLua from: a URL, or a directory of rocks such as tt package download emmylua --registry URL --dir DIR fills, to work offline (default the rock index of tarantool-contrib/rocks-repo)
  • --version string - outside a project, the EmmyLua release to run; a project runs the one its lock pins (default 0.30.0pre1)
  • --write - write the formatted files back

Examples

$ tt emmylua fmt
$ tt emmylua fmt app --write

# A configuration of luafmt for the project, with every setting.
$ tt emmylua fmt -- --init

tt emmylua ls

Run emmylua_ls, the language server of EmmyLua, on the standard streams, in place of tt: make it the command of the Lua server of the editor. It reads the configuration tt writes (through EMMYLUALS_CONFIG), then the project's .luarc.json, .emmyrc.json and .emmyrc.lua. Arguments after -- go to the program as they are.

Outside every project the programs come from the user cache, fetched there once from the rock server (--rock-server, --version), and the configuration tt writes is kept there too, not in the directory. So an editor can run tt emmylua ls in any folder.

Usage

tt emmylua ls [flags] [-- EMMYLUA_LS_ARGS...]

Flags

  • --library stringArray - read the Lua modules of this directory as a library too; repeat for more
  • --rock-server string - outside a project, the rock server to fetch EmmyLua from: a URL, or a directory of rocks such as tt package download emmylua --registry URL --dir DIR fills, to work offline (default the rock index of tarantool-contrib/rocks-repo)
  • --version string - outside a project, the EmmyLua release to run; a project runs the one its lock pins (default 0.30.0pre1)

Examples

# Neovim (nvim-lspconfig):
#   vim.lsp.config('emmylua_ls', { cmd = { 'tt', 'emmylua', 'ls' } })
$ tt emmylua ls -- --log-level debug --log-path /tmp/emmylua_ls.log

tt emmylua prepare

Put EmmyLua into the project.

The manifest declares the binary rock emmylua of the release from the rock server --rock-server names:

[dev_dependencies]
emmylua = { version = "<release>", registry = "<rock server>" }

The lock is re-resolved and the rocks are installed, so the programs are in .rocks/bin. A declaration already there is left as it is. The default server is the rock index of tarantool-contrib/rocks-repo,

https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/

which serves the rock of every platform with its sha256, so the lock pins them all; another may be one tt emmylua rock packs. Any version a server serves is taken.

With --from, the programs of a local build are packed as the rock of this host into .tarantool/registry instead, and the dependency names that directory. The registry is for this host and is not meant to be committed: after a checkout, run tt emmylua prepare --from again. --from packs the releases tt knows: 0.25.1, 0.30.0pre1; TT_EMMYLUA_RELEASES names a JSON file of others.

prepare runs in the root of the project, whose manifest it edits. Outside every project there is nothing to prepare: check, doc, fmt and ls fetch EmmyLua into the user cache themselves.

Usage

tt emmylua prepare [flags]

Flags

  • --from string - pack the programs of a local build of the release in this directory (a cargo target/release) into .tarantool/registry and declare the rock from there
  • --no-install - do not install the rocks: leave that to tt package build
  • --registry stringArray - rock server to use instead of the configured ones: an http(s) URL or a local directory; repeat to give an ordered list (overrides TT_REGISTRIES and [platform].registries)
  • --rock-server string - the rock server to declare the rock from: a URL or a directory relative to the project (default the rock index of tarantool-contrib/rocks-repo)
  • --version string - EmmyLua release: any the rock server serves, or one tt knows with --from (default 0.30.0pre1)

Examples

# The rock of this host, from the index of tarantool-contrib/rocks-repo.
$ tt emmylua prepare

# The release Tarantool checks its own code with.
$ tt emmylua prepare --version 0.25.1

# A local build of EmmyLua, from its checkout.
$ cargo build --release -p emmylua_check -p emmylua_ls -p emmylua_doc_cli \
  -p emmylua_formatter
$ tt emmylua prepare --from ~/src/emmylua-analyzer-rust/target/release

# The rocks of another rock server.
$ tt emmylua prepare --rock-server https://example.org/rocks/

tt emmylua rock

Pack the emmylua rock of every platform of an EmmyLua release into --out, with the manifest that makes the directory a rock server, the assets checked against the sha256 tt holds the release to. The release is one with builds on GitHub to download, by default 0.25.1, the newest of them tt knows. With --from, pack the one local build as the rock of --arch (default this host's), of the release 0.30.0pre1 by default, and keep the rocks already in --out: run it once for the build of each platform. Serve the directory, or upload its files, and declare the dependency from it with tt emmylua prepare --rock-server.

0.30.0pre1, the release tt prepares a project with, is a commit of EmmyLua with no builds to download: its rocks are on the rock index of tarantool-contrib/rocks-repo, and tt package download emmylua --registry https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/ --dir DIR takes the one of this host into a directory that serves as a rock server.

Usage

tt emmylua rock [flags]

Flags

  • --arch string - the LuaRocks arch of the build --from names (linux-x86_64, macosx-aarch64; default this host's)
  • --from string - pack the programs of a local build in this directory instead of downloading them
  • --out string - the directory to pack the rocks into
  • --version string - EmmyLua release (default 0.25.1, or 0.30.0pre1 with --from)

Examples

# The rocks of the newest release on GitHub.
$ tt emmylua rock --out dist/rocks

# Local builds, one per platform.
$ tt emmylua rock --from target/release --out dist/rocks
$ tt emmylua rock --from target/aarch64-apple-darwin/release \
  --arch macosx-aarch64 --out dist/rocks