Skip to content

tt package

Build, fetch, pack and install Tarantool packages described by app.manifest.toml, manage their dependencies, and manage what is installed. The commands that change a project hold its lock, _build/tt.lock, and wait while another tt holds it; a tt that a hook or a build runs works under the lock of the tt that runs it. What the exit codes mean is in tt help errors.

Usage

tt package
tt package [flags] <command> [command flags]

Commands

Flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package add

Add NAME to [dependencies] — or, with --dev, to [dev_dependencies] — at the given version constraint, then re-resolve app.manifest.lock around it. Without a constraint a new dependency is declared as '*': whatever the registry serves. A name the table already declares keeps its declaration when no constraint is given, and the lock is resolved only if it is missing or stale; with a constraint, the constraint is rewritten in place, and the rest of the declaration, and every comment and blank line in the file, is left exactly as it was. Every version the lock already holds is kept: only the new dependency and whatever it requires can move, because an edit to one dependency is not a request to upgrade the others — that is what tt package update is for. The manifest and the lock are written only once the resolution succeeded: when it fails — an unknown rock, a constraint no version satisfies, a rock server that does not answer — both are left exactly as they were. Nothing is fetched into .rocks/; the next tt package build picks the new lock up.

Usage

tt package add NAME [CONSTRAINT] [flags]

Flags

  • --dev - declare the dependency in [dev_dependencies] instead of [dependencies]
  • --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)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package build

Resolve dependencies, materialize .rocks/, run component build backends and generate version.lua. With no argument every component of the product is built; a component name narrows the build to one.

A make or shell component with incremental = true is built only when its inputs changed since its last build - its build block and its files, but those its .gitignore files ignore - or its outputs are gone; -V logs a skipped one. --rebuild builds them all, for a change the inputs do not cover, such as a new version of a compiler.

A component build keeps what it makes on the way in TT_BUILD_DIR, _build/component/<component>/ - the build tree of a cmake one, where cmake rebuilds what changed - and --rebuild empties it first. A cargo build builds in _build/cargo/, its CARGO_TARGET_DIR.

-j N runs at most N jobs at once in each component build, one a CPU by default: the backend hands N to its tool, and a make or shell build reads it as TT_BUILD_JOBS. It changes no input: a component built with other -j is not built again.

--target OS/ARCH builds the components for another platform than the machine tt runs on: linux/amd64, linux/arm64, darwin/amd64 or darwin/arm64, also spelled linux-arm64, with aarch64 and x86_64 for the architecture. A cargo, go, zig, make or shell build is made for it, and told it in TT_PLATFORM_OS and TT_PLATFORM_ARCH; a c, lua-c or cmake one, which compiles with the toolchain of this machine, fails the build before anything is built, and so does a go build with cgo, and a cargo one for darwin off macOS. The modules and the programs a build made are checked against the platform. The build keeps its state in _build/target/<os>-<arch>/ and installs the package into the tree there, _build/target/<os>-<arch>/tree/, not into .rocks/, whose rocks are those of this machine; the dependencies are installed into .rocks/ and built for this machine as ever. tt package pack --target packs what it built.

Usage

tt package build [COMPONENT] [flags]

Flags

  • -j, --jobs N - run at most N jobs at once in each component build: the compiles of c and lua-c, cmake --build --parallel, cargo -j, go build -p, zig build -j, TT_BUILD_JOBS of make and shell; 0 is one a CPU
  • --locked - fail if the lock is out of date instead of re-resolving it
  • --product string - product to build (default: the product marked default)
  • --rebuild - build the incremental components even when nothing changed, and every component in an empty TT_BUILD_DIR
  • --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)
  • --target OS/ARCH - build the components for the platform OS/ARCH, such as linux/arm64, instead of the machine tt runs on

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package clean

Remove what tt package build made, and nothing else, so that the next build builds everything again: _build/ - the build trees of the components (TT_BUILD_DIR), the records of the incremental builds, the stages, the builds of path dependencies and what tt package pack wrote into _build/pack/ - and the rock of the package in .rocks/, by the files its rock manifest lists. The rocks of the dependencies, the guest packages, the manifest, the lock and the sources stay; so does _build/tt.lock, the lock of the project.

A build backend may clean what its tool leaves beside the sources, which tt does not remove itself: it runs first, for every component of such a backend. A clean of the whole project then runs the clean hook, [hooks.clean] of the manifest, when it declares one.

A component name narrows the clean to the component: its build tree, its records and its files in the stages go, and the rock of the package leaves .rocks/, which the next build installs again with every component; the clean hook does not run.

--dry-run removes nothing and runs nothing, and prints what a clean would remove and run; -V lists the files of the rock as well.

Usage

tt package clean [COMPONENT] [flags]

Flags

  • --dry-run - print what a clean would remove and run, and do nothing

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package deps

Print the runtime dependencies of every product and the dev dependencies, each with the version app.manifest.lock resolved it to. This is what the current manifest declares — not what is installed on disk, which is what tt package list reports. Nothing is resolved and no registry is contacted: the answer comes from the manifest and the lock, so a lock that no longer matches the manifest is reported as stale rather than silently re-resolved.

Usage

tt package deps [flags]

Flags

  • -o, --format string - output format: table, json or yaml (default table)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package download

Fetch rock files from the configured servers into --dir and write the LuaRocks manifest and the rock index (tt-rocks-index.json) that index them, so the directory is itself a rock server: point --registry or TT_REGISTRIES at it and the project builds with no network at all. With no arguments the project's locked closure is mirrored at its exact versions — every product's dependencies and the dev closure — which needs a lock, so run tt package resolve first. A dependency that does not come from a registry has no rock file to mirror and is skipped with a warning. A version a server offers as a bare rockspec, with no source rock and no rock of this platform, gets its source rock packed beside it, as luarocks pack <rockspec> makes it: the sources its source.url names are fetched now, a git repository at the tag or branch the rockspec pins, and the download fails if they cannot be. A rock whose build itself downloads still needs the network. With no arguments, what the builds of the components of the project download themselves is downloaded too, into a directory of their backend, DIR/<backend>, which a build that has DIR among its servers takes it from, offline: the crates the Cargo.lock of a cargo component pins go into DIR/cargo. Re-running overwrites and re-indexes, so a mirror can be extended in place. Each written path is printed to stdout.

Usage

tt package download [NAME[@VERSION]...] [flags]

Flags

  • --dir string - directory to download into (default: the current directory)
  • --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)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package fetch

Fetch and build the pinned dependency closure into .rocks/ strictly from the lock, without re-resolving or running component build backends.

Usage

tt package fetch [flags]

Flags

  • --product string - product to fetch (default: the product marked default)
  • --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)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package index

Write tt-rocks-index.json, the rock index tt package reads before any LuaRocks manifest, from the rocks and rockspecs in DIR: every file of every version by its URL, with its sha256 and size. A project that depends on a rock of the index pins the sha256 of its files in the lock, and every install checks the file of its platform against it. tt package pack, tt package download and tt wasm rock write the index of the directory they write into; this is for one filled otherwise, with the rocks the jobs of a CI matrix packed, say.

By default the index goes into DIR, the LuaRocks manifests beside it, and names the files relative to itself: DIR is a rock server for tt and LuaRocks alike. --index names an index kept apart, a file of a git branch say, and --base-url the URL the files of DIR are downloaded from, the release page of a tag say; without --base-url the files are named relative to the index, which DIR must be below. With either, no manifest is written.

An index that is there is updated, not replaced: the versions of DIR are listed anew, a version marked "yanked": true staying so; a version it lists with files of DIR that are gone is dropped; a version it lists with files elsewhere is kept. A version in DIR that the index lists with files elsewhere fails the command, since a published version does not change: pack the new build as a new revision. The path of the index is printed to stdout.

Usage

tt package index DIR [flags]

Flags

  • --base-url string - the URL the files of DIR are downloaded from (default: relative to the index)
  • --index string - the index to write (default DIR/tt-rocks-index.json)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

Examples

# A directory of rocks as a rock server.
$ tt package index dist

# The rocks of a tag on its release page, the index in a branch of its own.
$ gh release upload v1.0.0 dist/*.rock dist/*.rockspec
$ tt package index dist --index index/tt-rocks-index.json \
    --base-url https://github.com/example/mylib/releases/download/v1.0.0

tt package install

Unpack a package archive into the chosen scope and bring the tree to a runnable state. A with-deps archive is a plain offline extraction; a --without-deps one is unpacked and its dependencies are refetched from the registry using the lock's pins: from the servers --registry or TT_REGISTRIES names, otherwise from the default ones. The runtime a with-deps archive bundles (_runtime/) is installed the way tt binary installs it, into versions/ of the scope root — <root>/versions/ in the user and system scopes, .tarantool/versions/ in the project — unless that version is there already. Several packages installed into one project share a .rocks/ tree, so a dependency they lock at different versions is reconciled to one both accept, or the install fails with an explanation; a project that selects no tarantool yet gets the bundled one selected in .tarantool/bin. In the user and system scopes the archive becomes one version of an application, <root>/versions/<name>/<name>_<version>/, laid out like a project next to what tt binary installs into the same root, and <root>/apps/<name> is pointed at it: install activates the version it installed, whether it is newer or older than the active one, so a plain install of a newer archive is an upgrade already; --upgrade only adds the check that the archive is newer than every installed version, and does nothing otherwise. It runs on the tarantool its lock bundles, whatever <root>/bin/tarantool selects. Versions live side by side; installing one that is already there needs --force, which is refused while instances of the application run. Running instances keep the version they were started from until tt instance restart; install names those that do not run the version it installed. To roll back, or to make any other installed version active again, use tt package switch: it needs no archive and no stop.

Usage

tt package install ARCHIVE... [flags]

Flags

  • --force - reinstall over an existing package or version (destructive)
  • --locked - fail if the archive lock does not match its manifest
  • --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)
  • --scope string - install scope: project (the working directory), user or system (an application version under the root tt binary uses) (default project)
  • --upgrade - install only when the archive version is higher than the installed one (in user and system, than every installed version)
  • -y, --yes - skip the confirmation prompt when reconciling shared dependencies

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package list

Show the packages present in the chosen scope: in the project scope the project's own package plus every guest installed from an archive, read from the metadata install records under .rocks/manifests/; in the user and system scopes every application installed under <root>/versions/, with the version <root>/apps/<name> selects and every installed one. Nothing is fetched and nothing is resolved. This is what is on disk — not what the current manifest declares, which is what tt package deps reports. --tree additionally shows each package's dependencies and, for every one of them, whether another package holds it too — that is, whether it would be removed along with the package or stay; it applies to the project scope, the versions of the user and system scopes sharing no dependencies.

Usage

tt package list [flags]

Flags

  • -o, --format string - output format: table, json or yaml (default table)
  • --scope string - scope to list: project (the working directory), user or system (the applications under the root tt binary uses) (default project)
  • --tree - show each package's dependencies and which of them are shared

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package pack

Run the full build and assemble its result into a reproducible .tt archive. By default the archive is self-contained: it carries _runtime/ (Tarantool, tt and TCM when [platform].tcm is set) and the whole dependency closure in .rocks/, so installing it needs no network. --without-deps drops both. The project's instance templates in .templates/ travel at the archive root in either mode; each .templates/<name>/ must hold config.yaml, instances.yaml or both, and a broken template fails the pack. A separate tt package build beforehand is not needed.

--format rock packs the package as a rock for other projects to depend on: the binary rock of this platform, or an .all rock when the package has no native file, with its rockspec beside it. The rockspec is made from the manifest: the dependencies are the ranges it declares, and the source is [package].repository at the tag of the version, or at its commit, in full in source.tag, when no tag names it. The rock is written into --out, which is then indexed as a rock server, keeping the rocks already there: the LuaRocks manifests and the rock index, tt-rocks-index.json, which has a project that depends on the rock pin the sha256 of its files in the lock (see tt package index). --format tt,rock makes both from one build.

--format rock-src packs the source rock: the same rockspec and the files of the project git tracks, submodules included, with a VERSION file of the version. A pack of the source rock alone builds nothing, so it needs no compiler and no Tarantool headers; the manifest and the lock are checked as a build checks them. A project that depends on the rock builds it from the source rock, with its manifest, where the server has no rock of the platform.

--target OS/ARCH builds the components for another platform than the machine tt runs on: linux/amd64, linux/arm64, darwin/amd64 or darwin/arm64, also spelled linux-arm64, with aarch64 and x86_64 for the architecture. A cargo, go, zig, make or shell build is made for it, and told it in TT_PLATFORM_OS and TT_PLATFORM_ARCH; a c, lua-c or cmake one, which compiles with the toolchain of this machine, fails the build before anything is built, and so does a go build with cgo, and a cargo one for darwin off macOS. The modules and the programs a build made are checked against the platform. The rock is then the binary rock of that platform, <rock>-<version>.linux-aarch64.rock for linux/arm64, and the .tt archive, labeled with it, <package>-<version>-linux-arm64.tt, is packed --without-deps alone: the Tarantool, the tt and the dependencies it would bundle are those of this machine. --debuginfo strip strips them with llvm-strip, which strips the files of every platform.

The paths of what the pack made are printed to stdout, one per line.

Usage

tt package pack [flags]

Flags

  • --debuginfo string - debug information of the modules and programs the package's builds made: keep, or strip it (strip --strip-debug; strip -S on macOS) from what is packed; the project's own files, the bundled runtime and the dependencies are not touched (default keep)
  • --format strings - what to make, comma-separated: tt (the .tt archive), rock (the rock and its rockspec), rock-src (the source rock and its rockspec) (default [tt])
  • -j, --jobs N - run at most N jobs at once in each component build: the compiles of c and lua-c, cmake --build --parallel, cargo -j, go build -p, zig build -j, TT_BUILD_JOBS of make and shell; 0 is one a CPU
  • --locked - fail if the lock is out of date instead of re-resolving it
  • --out string - directory to write into (default _build/pack of the project)
  • --product string - product to pack (default: the product marked default)
  • --rebuild - build the incremental components even when nothing changed, and every component in an empty TT_BUILD_DIR
  • --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)
  • --revision int - LuaRocks revision of the rock: raise it to publish a new build of a version (default 1)
  • --target OS/ARCH - build the components for the platform OS/ARCH, such as linux/arm64, instead of the machine tt runs on
  • --without-deps - pack without _runtime/ and without foreign dependencies in .rocks/

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package remove

Remove NAME from [dependencies] — or, with --dev, from [dev_dependencies] — then re-resolve app.manifest.lock without it. A declaration of NAME in the other table is left as it is, and a name only the other table declares is an error that says so. The rocks that were only there to satisfy it drop out of the closure with it; every other version is held. A name the manifest does not declare is an error rather than a silent success — it is almost always a typo — and so is a name only a component declares, since which component owns a dependency is not this command's decision to unmake. As with tt package add, a resolution that fails leaves the manifest and the lock exactly as they were. Nothing is deleted from .rocks/; tt package uninstall is what removes files.

Usage

tt package remove NAME [flags]

Flags

  • --dev - remove the dependency from [dev_dependencies] instead of [dependencies]
  • --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)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package resolve

Re-resolve app.manifest.lock from app.manifest.toml, so a manifest edited by hand gets its lock back in step without waiting for a build. Nothing is fetched into .rocks/ and no component build backend runs. Every version the lock already holds is kept: a hand edit to one dependency is not a request to upgrade the others, and pulling newer registry versions is what tt package update is for.

Usage

tt package resolve [flags]

Flags

  • --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)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

Search the rock servers for rocks whose name contains TERM, reporting every version each server offers. Unlike resolution, which stops at the first server that has a rock, a search asks all of them: the point is to see what exists. Each version of a server is one row; the rock named TERM comes first, then the others by name, the versions of each newest first and scm or dev versions after the releases. Nothing is downloaded and nothing is written. A term nothing matches is not an error.

Usage

tt package search TERM [flags]

Flags

  • -o, --format string - output format: table, json or yaml (default table)
  • --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)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package switch

Point <root>/apps/<name> at the installed version <root>/versions/<name>/<name>_<version>/, as tt package install does for the version it installs, and so roll back to an earlier version, or forward again, with no archive. The link is replaced in one rename: whoever resolves it at the same time gets the old version or the new one. Nothing is stopped or restarted: an instance runs the version it was started from, restarts after a failure included, until tt instance restart, or systemctl restart for an instance under the units of tt service systemd, which name the application rather than a version. switch names the running instances that do not run the version it made active, and tt instance status --details shows the version every running instance runs. A version whose lock bundles a tarantool that is no longer installed in the scope is refused, as it could not start. Without VERSION, switch offers the installed versions to choose from on a terminal, and otherwise lists them, the active one marked, and fails. The project scope holds one version of every package, so switch applies to the user and system scopes only.

Usage

tt package switch NAME [VERSION] [flags]

Flags

  • --scope string - scope of the application: user or system (the root tt binary uses); the project scope has no versions to switch between (default project)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

Examples

# Roll back to 1.0.0 while the instances run, then restart them.
$ tt package switch kv-api 1.0.0 --scope user
$ tt instance restart kv-api:* --scope user --yes

# Choose a version interactively.
$ tt package switch kv-api --scope user

tt package uninstall

Remove a guest package: its files and its metadata, plus every shared dependency that nothing else still needs. A dependency is owned by every installed package whose lock pins it, so one that another package still holds stays in place. The project's own package — the one app.manifest.toml in the working directory declares — is not a guest, and uninstall refuses to remove it. In the user and system scopes uninstall removes an application: every installed version under <root>/versions/<name>/ and the link <root>/apps/<name>. It refuses while an instance of the application runs, as its pid file under <root>/var/run/<name>/ tells, and keeps the instance data under <root>/var/, the host files under <root>/etc/<name>/ and the runtimes in <root>/versions/ other applications may use.

Usage

tt package uninstall NAME [flags]

Flags

  • --scope string - scope to remove from: project (the working directory), user or system (an application under the root tt binary uses) (default project)
  • -y, --yes - skip the confirmation prompt

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in

tt package update

Re-resolve app.manifest.lock, taking the newest version every constraint allows. This is the only command that pulls newer registry versions: a release upstream never makes a lock stale by itself, so a build keeps the versions it has until an update is asked for. With NAME only that dependency is freed and every other version is held, so the diff stays confined to it and whatever its new version requires. No declaration is changed — app.manifest.toml is not touched at all — and nothing is fetched into .rocks/.

Usage

tt package update [NAME] [flags]

Flags

  • --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)

Global flags

  • -C, --directory string - work on the project in DIR itself, not on the one the current directory is in