Projects and scopes¶
tt has no configuration file. What it acts on follows from where it runs and
from the --scope a command is given: a project, the scope of the current
user, or the scope of the system.
Projects¶
A project is the directory of an application under development. A directory is a project when it holds:
app.manifest.toml, the manifest of a package, or- an instance template:
instances.yaml,config.yamlor both in.templates/<name>/(see Instances).
tt looks for the project from the current directory upward, so the commands
work from any directory inside it: the instance commands, tt package,
tt run, which runs Tarantool in the current directory, tt test, which
runs the tests in the project root, tt wasm and the
modules, such as tt emmylua. A command that finds the project above the
current directory says so on stderr (working on the project in DIR).
-C DIR of the tt package commands and tt test names the project
itself: DIR is taken as it is, and nothing above it is looked into.
tt new creates a project in the current directory, or in DIR with -C,
and tt binary build works on the distribution in the directory it runs
in. The nearest project wins, so a project nested in another is found from
its own subdirectories. Other files - .rocks/, .git/, Lua files, a
config.yaml elsewhere - do not make a project. Neither does .tarantool/:
tt binary install creates it in a directory that is not a project yet.
The application of a project is named by [package].name of its manifest,
or after the project directory without one.
Scopes¶
Binaries, installed applications and the data of their instances live in
one of three scopes, each with its root directory, <root>:
| Scope | <root> |
|---|---|
project |
.tarantool/ in the project directory; the current directory outside a project |
user |
$TT_USER_ROOT; else $XDG_DATA_HOME/tarantool when it is an absolute path; else ~/.local/share/tarantool. On macOS: ~/Library/Application Support/tarantool |
system |
$TT_SYSTEM_ROOT; else /opt/tarantool. On macOS: /Library/Application Support/tarantool |
TT_USER_ROOT and TT_SYSTEM_ROOT must be absolute paths. Every root has
the same layout:
<root>/
├── bin/ # the active tarantool, tt and tcm (links)
├── include/ # the headers of the active tarantool
├── versions/ # installed binaries and, in user and system, applications
├── apps/<app> # user and system: a link to the active version of <app>
├── etc/<app>/ # user and system: the pair of the host, the systemd record
└── var/ # lib/, log/, run/ of every instance, by application
A command acts on one scope and never falls back to another: what it does must not depend on what happens to be installed elsewhere.
tt binaryinstalls and switches binaries in--scope project(the default),userorsystem.tt package installinstalls an archive into a project (the default) or makes it a version of an application in the user or the system scope. See Packages.- The instance commands act on
<app>:<instance>: the current project when it is named<app>, the system scope otherwise. The user scope is reached with--scope useronly, and--scopepicks any scope outright.
The project scope¶
The project scope is the project's own: tt binary install in a project
puts the binaries into its .tarantool/, apart from other applications,
and the instances of the project keep their data in .tarantool/var/.
The commands that run Tarantool in a project - tt instance, tt run,
tt test, tt package build - run .tarantool/bin/tarantool when the
project has one, and the first tarantool on PATH otherwise.
TT_USE_SYSTEM_TARANTOOL=1 makes a project run on the one on PATH even
when it has its own; it does not apply to installed applications. A
Tarantool of another version than the one the lock bundles is a warning,
not an error.
The first tt binary install of a project writes .env/activate.sh and
.env/deactivate.sh into it:
$ source .env/activate.sh # .tarantool/bin first on PATH, TT_PROJECT_DIR set
$ source .env/deactivate.sh # back as it was
activate.sh also points TT_CLI_TARANTOOL_PREFIX to .tarantool, so that
rocks with a C part are built against the headers of the project's
Tarantool.
The user and system scopes¶
The user and system scopes hold installed applications. An application is
a set of versions, <root>/versions/<app>/<app>_<version>/, each a package
laid out as a project, and <root>/apps/<app> points to the active one. An
installed application runs on the Tarantool its package bundles, whatever
<root>/bin/tarantool is. A version is never written to: the instances keep
their data in <root>/var/, and the pair of the host, <root>/etc/<app>/,
describes what runs on this host apart from the version, so both survive an
upgrade.
For the binaries of these scopes, put <root>/bin on PATH.