Packages¶
A package is an application described by app.manifest.toml: its name, the
versions of Tarantool and tt it runs on, its dependencies, the components it
is built from and the products it is packed as. A package is developed in a
project, packed into an archive and installed from
it.
The manifest¶
manifest_version = "0.1"
[package]
name = "kv-api"
[platform]
tarantool = ">=3.0.0" # [ce] by default; ">=3.3.0[ee]" for Enterprise
tt = ">=3.0.0"
[dependencies]
checks = ">=3.0.0" # a rock from the rock servers
mylib = { source = "path", path = "../mylib" }
[dev_dependencies]
luatest = "*"
[components.app]
path = "kv"
tt new writes a skeleton; tt package add and tt package remove edit
[dependencies] in place, keeping comments and order, and with --dev
[dev_dependencies]. tt package add NAME of a name declared already
keeps its constraint; tt package add NAME CONSTRAINT changes it. An
unknown field is an
error, so a typo does not go unnoticed. Every field is in the
reference.
The lock¶
app.manifest.lock, next to the manifest, pins the exact version of every
dependency, direct and transitive. Commit it: a build of the same commit
installs the same versions anywhere. For a rock from a server with a
rock index, it pins the sha256 of the files
of the version as well, and an install checks the file of its platform
against it.
The lock changes only when asked to:
tt package add,tt package removeandtt package resolveresolve the lock again for what the manifest declares, keeping every version the lock holds. Only what was added, and what it requires, can move.addandremovewrite the manifest only once the lock resolved: when the resolution fails, for a rock no server has say, both files are left as they were.tt package update [NAME]takes the newest versions the constraints allow, for every dependency or for NAME only.tt package buildandtt package packresolve a lock that no longer matches the manifest, keeping its versions. With--lockedthey fail instead, which is what CI wants.
A version that tracks a branch, scm-1 or dev-1, is taken only when the
constraint names it or the rock has no other, and resolving to it warns
that the lock will not pin fixed code. So is a version tt made from
uncommitted changes, 1.2.0.dirty-1: every such build of a commit has it.
The version tt makes from a commit, 1.2.1.dev.3.gabc1234-1 or
0.0.0.dev.36.g7170ebf-1, names that commit and counts as a release.
The lock matches the manifest by manifest_hash, a hash of what the
manifest says - its tables, keys and values - and not of the bytes of the
file. Comments, blank lines and indentation, the order of keys and tables,
the quoting of a string and the form of a table (inline, dotted keys) do not
count, so such an edit leaves the lock current. A changed key or value
makes the lock out of date, one that pins nothing, such as description,
included; so does a lock of a tt that hashed the manifest another way.
tt package resolve then writes the hash anew and, when no version moved,
says what it rewrote in the lock instead of finding it up to date.
tt package deps shows what the manifest declares and what the lock
resolved it to, with no network.
The dependencies come from rock servers; see Rock servers.
Components and products¶
A component is a part of the package: a directory of files, with an optional build.
A component lays its files out under .rocks/share/tarantool/<namespace>/,
<namespace> being the package name unless the component says otherwise.
Its files are the *.lua and *.so of its path unless include lists
others; a go component lays out only what include lists. A build
backend makes what its block asks for, before the layout, and one
component may make all of it:
- a module, into
.rocks/lib/tarantool/<namespace>/: a native module ofc,lua-c,cargoorzigwithmodule, or ofcmake,makeandshellinoutput; - a data file, into
.rocks/share/tarantool/<namespace>/: a WebAssembly component, say, see Run WebAssembly components, an entry ofoutputwithto = "share"; - a program, into
.rocks/bin/: ofgo,cargoorzigwithbin, or an entry ofoutputwithto = "bin". An external process of the application runs it.
Build a module in Rust describes cargo, and
Build a module in Zig zig. The
kind of a component, "module" or "executable", is deprecated: tt
checks what it says against what the build makes.
A native module is <module>.so in .rocks/lib/tarantool/<namespace>/, and
<module>.dylib on macOS, where Tarantool looks for no other name: the c,
lua-c, cargo and zig backends name it so, cmake copies a .so it built as
.dylib there, and a .dylib a component lays out goes there as a .so
does.
A product is a set of components built and packed together. A manifest
without [products] has one implicit product, default, made of every
component.
Building¶
tt package build resolves the lock, installs the dependencies into
.rocks/, runs the build backends of the components and lays the
components out, with version.lua and rocks.lua of the package.
tt package fetch only installs .rocks/ from the lock, with no build.
-j N runs at most N jobs at once in each component build, one a CPU by
default; see Jobs. --target OS/ARCH
builds for another platform than the machine; see
Other platforms.
The components are laid out in _build/rock/<product>/ and installed into
.rocks/ as a rock of the package's name, at its version: the manifest of
.rocks/ lists their files as it lists those of the dependencies, and a
build at another version replaces the rock. A file of the package that a
dependency also installs fails the build.
_build/rock/<product>/ stays between builds, and
_build/rock/<product>.json records which component put each of its files
there. A build removes from it, and so from .rocks/, what no component
owns any more: a file deleted from the sources, the files of a component
no longer in the product. What a skipped incremental build wrote stays, and
so does what the other components put there when --component builds one.
A file a backend wrote into TT_OUTPUT_DIR once and leaves alone since
stays its own, as an up-to-date make target does; --rebuild starts from
an empty _build/rock/<product>/, so only what the build writes again
stays. A component whose build block changed is built as --rebuild
builds it: what its last build made leaves _build/rock/<product>/ before
the build runs, TT_BUILD_DIR is emptied, and only what the build makes
stays - a module renamed in the block, module = "hello" made module =
"greet", leaves no hello.so behind. A build also removes from
.rocks/ the versions of the dependencies the lock pins other than the one
it pins, and repairs a .rocks/ an older tt left out of step with its
manifest.
- A build backend finds the programs of the project's
.tarantool/bin- whattt binaryandtt wasm prepareinstalled - ahead ofPATH, with or without.env/activate.sh. The build of a dependency rock finds the project'starantoolthere as well: a rock that runstarantoolby name, as the cmake of a rock that looks for it does, runs that one. - A
makeorshellbuild withincremental = trueis skipped while nothing it depends on changed; see Incremental builds. - A
.wasmfile a component lays out, or its build writes intoshare/, has to be a WebAssembly binary: any other fails the build, and a core module, which tarantool-wasm does not load, is laid out with a warning. The check is that of the standard modulewasm, and a distribution without it makes none. tt package build,fetchandpackneed no Tarantool: where tt finds none, neither in.tarantool/binnor inPATH, a package of Lua builds and packs all the same. What is compiled against the headers of Tarantool fails then, saying so: acorlua-ccomponent, before anything is built, and a rock of a server with a C part. Amake,shellorcmakebuild is not told where Tarantool is,TT_TARANTOOL_PREFIXandTT_TARANTOOL_INCLUDE_DIRunset, and fails on its own if it needs the headers. A Tarantool whose headers tt does not find (where it looks) builds the same, and acorlua-ccomponent fails naming the directories tt looked into.
The version of a package is, in order:
- the line of a
VERSIONfile next to the manifest; - the nearest version tag of git,
v1.2.0or1.2.0:1.2.0on the tag,1.2.1-dev.3+gabc1234three commits after it; 0.0.0-dev.<N>+g<sha>without a tag.
A tag with a v is a version as before, v1.2 too; a tag without one only
in full SemVer, 1.2.0 or 1.2.0-rc.1, since a bare number as often names
a date or a build. Any other tag is passed over for the version tag before
it. Of the version tags on one commit the highest version counts, and of
v1.2.0 and 1.2.0 the tag is v1.2.0, whichever of them is annotated or
newer.
Changes not committed, but for the lock, add dirty to the build
metadata: 1.2.0+dirty.
A project in a subdirectory of its repository - one of a monorepo, or a
path dependency inside the repository of the project that depends on it -
is versioned by its directory alone. The version is that of the last commit
that changed the directory, and only a change under it adds dirty: a
commit or a change elsewhere in the repository does not move the version,
nor make the lock of a project that depends on it by path out of date. A
tag counts on that commit or before it, not on a later commit that left the
directory alone: to release the project, tag a commit that changes it.
<N> counts the commits in the history of that commit, the ones elsewhere
too, as the commits after a tag do. A project at the root of its repository
is versioned by HEAD and the whole tree.
The code reads its version as require('<name>.version').version; set
generate_version_lua = false in [package] to leave version.lua out.
The rocks of the build¶
Beside version.lua the build writes rocks.lua, the rocks the package
was built with: the closure of the product the lock pins, the dependencies
of the dependencies included, with no [dev_dependencies]. It is a module
of data alone, the same for the same lock and version, with no time in it:
-- Generated by tt package build. Do not edit.
return {
package = { name = "myapp", version = "0.0.0-dev.0", commit = "", dirty = false },
product = "default",
rocks = {
["my-helper"] = { version = "0.3.0-1", source = "path" },
stat = { version = "0.3.2-1", source = "registry" },
},
}
package is the name of the package and its version, as version.lua
has it; product the product built; rocks every rock of the closure by
name, with the version and the source, registry or path, of the lock.
A path dependency with neither a manifest nor a rockspec, which installs
nothing, is listed with the version ""; a package with no dependency has
rocks = {}. A running application reads it as require('<name>.rocks'),
an instance of the project over iproto too:
$ echo "return require('myapp.rocks').rocks.stat" | tt connect myapp:instance001
---
- version: 0.3.2-1
source: registry
...
Only the package itself gets rocks.lua, not the rock of a path dependency
or of a source rock tt builds: their rocks are the closure of the package.
It is in the .tt archive, which runs the application, and not in the rock
--format rock packs: a project installing the rock resolves rocks of its
own. A component that lays out a rocks.lua of its own into the namespace
of the package fails the build; set generate_rocks_lua = false in
[package] to leave the generated one out, which generate_version_lua
does not do.
Incremental builds¶
A make or shell build of a component, whatever it makes, can be
skipped when nothing it depends on changed since its last build:
[components.calc.build]
backend = "shell"
command = "tarawasm"
args = ["all"]
incremental = true
Before it builds such a component, tt package build hashes its inputs:
- its build block, with
env,cwd,outputand the rest; - the files under its
path: each regular file with its mode and content, and each symbolic link by where it points.
Some files are not inputs:
- the hidden ones, at any depth:
.git,.tarawasm, the.gitignorefiles themselves; - those of a
_build/or a_runtime/directory; - those the
.gitignorefiles ignore - those of the project and of the directories down to the component, and those of the component, each for its subtree, as git reads them, but without the excludes of the git configuration (core.excludesFile,.git/info/exclude).
What a build writes and git does not keep - its output, its bindings - is
so not an input, and the hash stays the same from one build to the next.
Nor is the number of jobs, -j (see
Jobs): a build with other jobs is
skipped as well.
The build is skipped when the hash is the one its last successful build
recorded, in _build/cache/<component>.json, and what that build left is
still there:
- the files
outputlists; - the files of the component the layout took;
- the modules, the data files and the programs it made, by the record of
_build/results.json: the files it created or changed, at any depth, and those an earlier build made and it left alone, as amaketarget that is up to date does.
A build whose files in _build/rock/ were cleared since runs again; a
cleared .rocks/ gets the package's rock again from there. A skipped
build copies the files output lists into _build/rock/ again, and the
component is laid out as after any build. tt -V package build logs every
component it skips.
A skipped build does not run its backend at all. A make target with rules
of its own is cheap when nothing changed, and may not need incremental:
without it, tt runs make every time, and make decides what to rebuild.
The hash does not cover everything a build depends on:
- the compilers and their versions;
- the environment tt runs in, but the
envof the build block; - the files outside the
pathof the component, those of acwdelsewhere included; - the dependencies in
.rocks/.
After a change of these, tt package build --rebuild, and
tt package pack --rebuild, build every incremental component and record
it; removing _build/cache/ does the same, and tt package clean too, for
the components it cleans.
A component whose build writes files no .gitignore ignores gets another
hash at every build, and is built every time, as if it were not
incremental. tt wasm new writes the .gitignore of a WebAssembly
component, and declares it incremental.
Cleaning¶
tt package clean removes what the builds made, and nothing else:
_build/, but_build/tt.lock: the build trees of the components (TT_BUILD_DIR), the records of the incremental builds and of what each component made, the stages, the builds of the path dependencies and the archivestt package packwrote into_build/pack/;- the rock of the package in
.rocks/, by the files its rock manifest lists: those the build installed.
The rocks of the dependencies stay, and so do the packages
tt package install put into .rocks/, the manifest, the lock and the
files of the sources. A file the build made beside the sources stays too,
the files output lists among them: tt cannot tell it from a file the
project keeps. What a tool leaves there, the backend of the component
removes, if it knows how, before tt removes anything; what the project
generates itself, the command of [hooks.clean] in the manifest removes
(see the reference).
The next build builds every component again. Of a package of Lua whose
pre_build hook generates src/gen/year.lua, and whose clean hook removes
src/gen/, as in the example of the reference:
$ tt package clean --dry-run
would run the clean hook
would remove _build/rock
would remove myapp 1.0.0-1 from .rocks (4 files)
.rocks/share/tarantool/rocks/myapp/1.0.0-1/myapp-1.0.0-1.rockspec
.rocks/share/tarantool/myapp/init.lua
.rocks/share/tarantool/myapp/src/gen/year.lua
.rocks/share/tarantool/myapp/version.lua
$ tt package clean
ran the clean hook
removed _build/rock
removed myapp 1.0.0-1 from .rocks (4 files)
$ ls -A _build
tt.lock
A component that builds adds its build tree and records:
_build/component, _build/cache, _build/results.json.
--dry-run removes and runs nothing; -V lists the files of the rock as
the dry run does. tt package clean <component> cleans one component: its
build tree, its records and its files in _build/rock/, and the same of the
builds for other platforms in _build/target/<os>-<arch>/ with the trees
of their packages, after what its
backend cleans. The rock of the package leaves .rocks/ then too, since it
is installed whole, and the next build installs it again, the component
built even when it is incremental and nothing changed. The clean hook runs
on a clean of the whole package only.
One command at a time¶
The commands that change a project hold its lock, _build/tt.lock:
tt package build, fetch, pack, clean, add, remove, update and
resolve, tt package install and uninstall in the project scope,
tt test while it builds, and the commands of modules that change the
project, such as those of tt wasm. Another command that would change the
project meanwhile waits for it, and says so:
$ tt package build
• waiting for another tt working on the project /home/me/myapp (pid 48213)
Ctrl-C stops the wait. The commands that only read a project, such as
tt package deps and list, take no lock and wait for nothing. A tt that
a hook or a build runs on the same project, tt package fetch in a
post_build hook say, works under the lock of the tt that runs it rather
than wait for it: tt names its lock in TT_PROJECT_LOCK, which the
commands it runs inherit. The lock is released when tt exits, however it
exits, so a tt that was killed leaves no lock behind; _build/tt.lock stays
for the next command. A directory without app.manifest.toml gets no lock.
Other platforms¶
tt package build --target linux/arm64 builds the components for
linux/arm64 on a machine of another platform: an x86_64 laptop, a CI
runner. The backends that can build for another platform - cargo, go,
zig, make and shell - are told it, and a component of one that
cannot, c, lua-c or cmake, fails the build before anything is built.
What the builds made is checked against the platform, and kept in
_build/target/linux-arm64/, apart from what a build for the machine made:
neither build takes the other's as up to date. The package is installed
into _build/target/linux-arm64/tree/ rather than into .rocks/, whose
modules and programs are those of the machine, which its Tarantool loads
and tt instance runs; the dependencies are installed into .rocks/ and
built for the machine, as for any build. The platforms, the backends and
what each does are in
Other platforms.
tt package pack --target linux/arm64 packs such a build: the rock of the
platform, and the archive --without-deps (see Packing).
Packing¶
tt package pack builds the package and packs it into
_build/pack/<name>-<version>-<os>-<arch>.tt, a tar.zst archive, printing
its path. The archive is reproducible: packing the same commit twice gives
the same bytes. It holds:
- the manifest, the lock and
VERSION; .rocks/: the rock of the package and those of the dependencies, dev dependencies excepted, with the manifest of the tree; a file of.rocks/no rock owns is left out, with a warning;.templates/: the instance templates of the project, each checked;_runtime/: the Tarantool and the tt the package runs on, and TCM when[platform].tcmasks for it;- the files
[package].includelists, and the license files.
Other files of the project, init.lua at its root say, are not in the
archive unless [package].include lists them. So the cluster config of a
package loads its code as app.module, from .rocks/: app.module: kv
loads the init.lua of a component of the package kv, which the build
lays out as .rocks/share/tarantool/kv/init.lua:
app:
module: kv
The vshard_cluster template of tt create does the same: its component
has namespace = "", and the config loads app.module: storage and
app.module: router, its storage.lua and router.lua.
A config of app.file: init.lua runs in the project, which has init.lua,
and fails in every installed copy of the package, which has only what the
archive carries. If the code has to be loaded from a file, list the file in
[package].include, and the archive carries it at the same place:
[package]
name = "kv"
include = ["init.lua"]
tt package pack warns about an app.file of a template's config.yaml
that names a file the archive does not carry:
⚠ .templates/default/config.yaml: app.file init.lua is not in the archive, so the package installed from it cannot load it; load the code from .rocks/ with app.module: kv, or add "init.lua" to [package].include
Each runtime is the first of these that matches [platform]:
- the highest version in the runtime cache,
~/.cache/tt/runtimes/<tarantool|tt|tcm>/<ce|ee>/<version>/($XDG_CACHE_HOME/tt/runtimes/when that is set,~/Library/Caches/tt/runtimes/on macOS). No command fills it: it holds the builds placed there by hand, a directory withbin/<name>and, for Tarantool, itsLICENSEandinclude/tarantool/; - a tt binary installation of the project, in
.tarantool/versions/: the active one, whichtt binary installandtt binary switchselect, and otherwise the highest version. Sott binary install tarantool 3.8.1in the project, ortt binary install tt, chooses what pack bundles. An[ee]requirement takestarantool-eeandtt-ee; an SDK, or a build named by a commit, is not taken. The headers of the tarantool come along, and the lock records the name of the installation; - the active
tarantoolandtt, with a warning.
With no tarantool found, the first two are the only sources of one, and
the pack fails when neither has a match. tt binary installs a tarantool
without its license file, so pack warns that it bundles one from an
installation without a license.
--without-deps packs the package alone: no _runtime/ and no
dependencies, which tt package install
fetches by the lock; .rocks/ holds the rock of the package only, a
component of namespace = "" included. Such an archive is named ...-any.tt when it holds no
native file.
A pack of a build for another platform, --target linux/arm64 (see
Other platforms), names the archive after that
platform, <name>-<version>-linux-arm64.tt, and checks its native files
against it. It packs --without-deps alone, from the tree of the target:
the Tarantool and the tt it would bundle in _runtime/, and the
dependencies of .rocks/, are those of the machine, so a pack with them
fails before it builds:
⨯ a .tt archive with its dependencies is packed for the machine tt runs on alone, linux-amd64: its _runtime/ is the Tarantool and the tt of this machine, and its .rocks/ the dependencies built for it; pack the archive for linux-arm64 with --without-deps, whose dependencies are installed where it is installed, or pack --format rock
Debug information¶
The c and lua-c builds compile with -g, and a cmake build is
RelWithDebInfo, so the modules and the programs of a package carry their
debug information: a module that crashes Tarantool has a backtrace with its
lines. --debuginfo chooses what the pack does with it: keep, the
default, packs the files as the builds made them, and strip packs them
without it, the symbols kept, so a backtrace still names the functions:
$ tt package pack --debuginfo strip
What is stripped is what the builds of the components of the package
made, its modules and programs in .rocks/ of the archive, and every
native file of the rock, which holds the package alone. The bundled
runtime, the rocks of the dependencies and the files of
[package].include are packed as they are, and the files of the project,
its .rocks/ and _build/, are not touched: the copies being packed are.
The tool is strip --strip-debug on Linux, objcopy --strip-debug when
there is no strip, and strip -S of Xcode on macOS, found in PATH; a
pack that strips with none fails before it builds:
--debuginfo strip needs strip --strip-debug of binutils, or objcopy, in
PATH. A pack for another platform, --target, strips with llvm-strip
--strip-debug, which strips the files of every platform, where the
strip of binutils reads those of the machine alone.
Packing a rock¶
A package other projects depend on, a Tarantool module say, is packed as a
rock: tt package pack --format rock. The rock holds the files the build
laid out, the rock of the package tt package build installs into
.rocks/ but for rocks.lua (see
The rocks of the build), and the license files,
[package].license_files, in doc/, where LuaRocks keeps the documents
of a rock: a project installing the rock
has them in .rocks/share/tarantool/rocks/<name>/<version>/doc/. It is
written with its rockspec beside it:
$ tt package pack --format rock --out dist
.../mylib/dist/mylib-1.2.0-1.linux-x86_64.rock
.../mylib/dist/mylib-1.2.0-1.rockspec
The rock is the binary rock of the platform tt runs on when the package has
a native file, a module or a program, and <name>-<version>.all.rock
otherwise; a native file built for another platform fails the pack. A pack
with --target packs the binary rock of that platform,
<name>-<version>.linux-aarch64.rock for linux/arm64,
macosx-aarch64 for darwin/arm64 (see
Other platforms). The
version is that of the package, with the revision --revision gives, 1 by
default: raise it to publish a new build of a version that is out.
The project needs no rockspec: tt makes it from the manifest. Its
dependencies are the ranges [dependencies] and the components of the
product declare, not the versions the lock pins, and [platform].tarantool
becomes its dependency on tarantool; the source is
[package].repository, at the commit of the version: source.tag is the
tag of the version, named as git has it, and for a version of a commit no
tag names, 1.2.1-dev.3+gabc1234 say, the full sha of the commit, LuaRocks
having no field for a commit. LuaRocks fetches a git source with git clone
--branch, which takes no commit, so it fails to fetch the source of such a
rockspec rather than fetch another commit; tt fetches the source of no rock.
A dirty version, of uncommitted changes, and one a VERSION file gives
name the repository with no commit, a dirty one with a comment saying so;
a package with no repository has the source file://.. [package] gives the
description, the license and the maintainers, [platform].platforms the
supported platforms. The build is done, so the build type is none, and
the rockspec is the same for the rock of every platform. A path dependency
fails the pack: the projects installing the rock have no such directory.
So does a product with no rock of its own, and both fail it before the
build, not after minutes of it. A dependency from a registry of its own is
declared with a warning, since a rockspec cannot name the server.
--out, _build/pack/ by default, is indexed as a rock server once the
rock is written, keeping the rocks already there: a pack on each platform
into the same directory fills one server. The directory gets the LuaRocks
manifests and a rock index,
tt-rocks-index.json, both made from every rock and rockspec in it:
$ ls dist
manifest
manifest-5.1
manifest-5.2
manifest-5.3
manifest-5.4
mylib-1.2.0-1.linux-x86_64.rock
mylib-1.2.0-1.rockspec
tt-rocks-index.json
Another project then depends on the rock from it, and its lock pins the sha256 of every file of the version the index lists, which every install of the rock checks:
[dependencies]
mylib = { version = ">=1.2.0", registry = "/path/to/dist" }
A rock packed anew with the same version and other bytes no longer matches
such a lock: tt package resolve pins it again, and a rock already
published gets a new --revision instead. The rocks of several machines,
collected into one directory - from the jobs of a CI matrix, say - are
indexed with tt package index DIR, which also writes an index kept apart
from the rocks, for rocks on release pages; see
Writing an index.
--format tt,rock packs the .tt archive and the rock from one build;
--without-deps and signing apply to the archive only.
--format rock-src packs the source rock, <name>-<version>.src.rock,
for a platform no binary rock is published for: the same rockspec, and the
files of the project git tracks, those of its submodules included, with a
VERSION file of the version, since the unpacked rock has no git history
to derive it from. The manifest and the license files are packed whether
git tracks them or not, a license file that is not there failing the pack
as it fails the binary rock; a
file of a component git neither tracks nor ignores is left out, with a
warning, since the binary rock has it and a build of the source rock would
not. Out of a git repository, every file of the project is
packed, but _build/, .rocks/ and _runtime/. The rock is reproducible:
its entries carry no mode but the executable bit, and no time of their own:
every entry of either rock is dated 1980-01-01 00:00, the earliest time a
zip says, which unzip -l shows as it is in any time zone. A pack of the
source rock alone builds nothing - no hook, no backend, nothing installed
into .rocks/ - so it needs no compiler and no headers of Tarantool; the
manifest is checked and the lock resolved, or refused under --locked, as a
build does. --format rock,rock-src builds once, for the binary rock. A pack on
each platform with --format rock, or on one machine with the --target of
each platform the backends of the package build for, and one anywhere with
--format rock-src fill a server with every rock of a version.
A project that depends on such a rock builds it from its source rock when
the servers it installs the rock from have no rock of its platform, neither
a binary one nor an .all one: tt downloads the source rock into
_build/src/, builds the package in it with its manifest, as it builds a
path dependency, and installs it into .rocks/ at the version the lock
pins, revision included, with the license files of the package in doc/,
as its binary rock has them; one the source rock does not hold, a file git
did not track where it was packed, is a warning. The hooks of the package
are not run. A rock built
so is not built again while the tree holds it at that version. A source
rock of no tt package, one without app.manifest.toml, fails the build.
Only tt builds a source rock: LuaRocks, tt rocks included, finds nothing
to build in it (see tt rocks).
Publish a module as a rock walks one module through all of it: its manifest, its versions, its rocks, a server and an index for them, and a project that depends on it.
Installing¶
tt package install ARCHIVE installs into one of the
scopes:
- A project (the default): the package becomes a guest of the project.
Its rocks join the project's
.rocks/and its manifest, each checked against what it says it holds, with command wrappers for the project; when two packages lock a dependency at different versions, the install takes one version both accept or fails, explaining why. A project that has no Tarantool of its own gets the bundled one. - The user or the system scope: the archive becomes a version of an
application,
<root>/versions/<name>/<name>_<version>/, and<root>/apps/<name>points to it. Its runtime goes into<root>/versions/, shared like a binarytt binaryinstalls, and the application runs on it whatever<root>/bin/selects; so do the command wrappers of its rocks, written for the version where it is, but those of a signed version, which is installed as it was signed. Versions live side by side, and every install makes the version it installs active;--upgradeinstalls only a version newer than every installed one, and--forcereinstalls one that is there, which is refused while an instance of the application runs.tt package switchmakes another installed version active again, as a rollback does, while the instances run; they move to it ontt instance restart.
tt package list shows what a scope holds; tt package uninstall removes a
guest from a project, or every version of an application from the user or
the system scope, keeping the data of its instances in <root>/var/ and
the pair of the host in <root>/etc/<name>/.
A with-deps archive installs with no network. See Install an application for a user and Run instances under systemd.