Skip to content

Filesystem layout

The root of a scope

Every scope has a root with the same layout: .tarantool/ of a project, the root of the user scope, or of the system scope.

<root>/
├── bin/                                  # the active binaries (links)
│   ├── tarantool
│   ├── tt
│   └── tcm
├── include/tarantool                     # the headers of the active tarantool (link)
├── versions/
│   ├── tarantool/tarantool_3.8.1/        # tarantool, include/tarantool/, share/tarantool/, LICENSE, AUTHORS
│   ├── tarantool-ee/tarantool-ee_3.8.1/
│   ├── tt/tt_3.0.0/
│   ├── tcm/tcm_1.3.1/
│   ├── tarantool-sdk/                    # which SDK components belong together
│   └── kv-api/kv-api_1.1.0/              # an installed application (user, system)
├── registry/                             # the rock server of tt wasm/emmylua prepare --from (project)
├── apps/
│   └── kv-api -> ../versions/kv-api/kv-api_1.1.0
├── etc/
│   └── kv-api/                           # the pair of the host (user, system)
│       ├── config.yaml
│       ├── instances.yaml
│       └── systemd.yaml                  # the instances systemd units manage
└── var/
    ├── lib/<app>/<instance>/             # data; working directory of an external process
    ├── log/<app>/<instance>/tt.log       # the output of the instance and its watchdog
    └── run/<app>/<instance>/             # tt.pid, tarantool.pid, tarantool.control,
                                          # tarantool.sock, process.pid, launch.json,
                                          # last_exit.json
File
run/.../tt.pid the pid of the watchdog of the instance
run/.../launch.json what the watchdog runs, as tt instance start resolved it, while the watchdog runs
run/.../last_exit.json how the last process of the instance ended and when, left by its watchdog for tt instance status --details
run/.../tarantool.pid the pid file Tarantool writes
run/.../tarantool.control the console socket tt connect <app>:<instance> uses
run/.../tarantool.sock the binary port, unless the cluster config or the script listens elsewhere
run/.../process.pid the pid of an external process, and of TCM
log/.../tt.log everything the instance writes and the messages of its watchdog

TCM, the record with kind: tcm (see Run TCM), has a few files of its own:

File
run/<app>/<tcm>/tcm.yaml the config of TCM, written anew by every tt instance start, mode 0600
lib/<app>/<tcm>/admin.secret the password of the first login of admin, generated on the first start, mode 0600
lib/<app>/<tcm>/etcd/ the data of the embedded etcd of TCM, for an application without a config storage
lib/<app>/<tcm>/embedded-etcd.json the ports tt chose for that etcd

Nothing of var/, or of the rest of .tarantool/, goes into a package: tt package pack refuses an include entry in .tarantool/.

tt wasm prepare adds to the root of a project what WebAssembly components are built with: under versions/, tarawasm and the tools tt installs, each linked into bin/, and, with --from, registry/, a rock server holding the wasm rock of a local build for this machine:

.tarantool/
├── bin/
│   ├── tarawasm -> <root>/versions/tarawasm/tarawasm_<commit>/bin/tarawasm
│   ├── wasm-tools -> <root>/versions/wasm-tools/wasm-tools_1.261.0/wasm-tools
│   ├── wkg
│   ├── componentize-py                   # in the environment of tarawasm (Python)
│   ├── tinygo, wasm-opt                  # Go
│   └── wit-bindgen                       # C
├── registry/
│   ├── manifest
│   └── wasm-0.1.0-1.linux-x86_64.rock
└── versions/
    ├── tarawasm/tarawasm_<commit>/       # a Python virtual environment
    ├── wasm-tools/wasm-tools_1.261.0/
    ├── wkg/wkg_0.16.1/
    ├── tinygo/tinygo_0.43.0/             # with Binaryen laid over it
    ├── wasi-sdk/wasi-sdk_34/             # not linked: see tarawasm.local.json below
    └── wit-bindgen/wit-bindgen_0.62.0/

A project

myapp/
├── app.manifest.toml          # the manifest of the package
├── app.manifest.lock          # the versions the dependencies resolved to; commit it
├── VERSION                    # optional: the version of the package
├── .templates/
│   └── default/               # an instance template: the pair of the project
│       ├── config.yaml
│       └── instances.yaml
├── .rocks/                    # dependencies and built components (generated)
│   ├── share/tarantool/<name>/
│   └── bin/                   # programs the components built
├── _build/pack/               # archives tt package pack makes (generated)
├── _build/rock/<product>/     # the components laid out, installed into .rocks/ (generated)
├── _build/rock/<product>.json # which component put each file there (generated)
├── _build/results.json        # what each component built: modules, data files, programs (generated)
├── _build/cache/              # what the last incremental builds hashed and left (generated)
├── _build/component/<component>/ # TT_BUILD_DIR of each component: a cmake build tree, objects and cache of c and lua-c (generated)
├── _build/cargo/              # the target directory of the cargo components (generated)
├── _build/target/<os>-<arch>/ # the same of a build for another platform, --target, with tree/, its package (generated)
├── _build/tt.lock             # the lock of the project, which tt package clean keeps (generated)
├── .env/                      # activate.sh, deactivate.sh (generated)
└── .tarantool/                # the root of the project scope (generated)

Keep the generated directories out of git:

.rocks/
_build/
.env/
.tarantool/

A WebAssembly component

tt wasm new router --lang python makes a tarawasm project in router/:

router/
├── .gitignore                    # what tarawasm generates, written by tt wasm new
├── main.py                       # the source
├── wit/
│   ├── app.wit                   # the world of the component, named after it
│   └── deps/                     # the WIT of the SDK
├── tarawasm.json                 # the language, the world, the output
├── tarawasm.tarantool.lock.json  # the SDK release the component is built with
├── tarawasm.local.json           # where the tools of this machine are (C; generated)
├── .tarawasm/                    # the SDK, restored by tt wasm prepare (generated)
├── wit_world/, poll_loop.py ...  # the bindings (generated)
└── dist/router.wasm              # the component (generated)

Commit the source, wit/ with its deps/, tarawasm.json, tarawasm.tarantool.lock.json and .gitignore; the rest is generated, and .gitignore keeps it out.

An archive

tt package pack makes <name>-<version>-<os>-<arch>.tt, a tar.zst archive:

app.manifest.toml
app.manifest.lock
VERSION
.templates/...
.rocks/...
_runtime/tarantool/bin/tarantool
_runtime/tt/bin/tt
_runtime/tcm/bin/tcm           # with [platform].tcm set

A signed archive also has hashes.json, env_hashes.json and their .sig files; see Sign packages.

The user cache

tt wasm and tt emmylua keep what they download under tt/ of the user cache: $XDG_CACHE_HOME, ~/.cache by default, ~/Library/Caches on macOS. Outside every project, tt emmylua check, doc, fmt and ls run the programs of the emmylua rock from there, and write their configuration there rather than into the directory (see Check and format Lua code with EmmyLua):

<user cache>/tt/emmylua/
├── <sha256>                          # an asset tt emmylua rock downloaded
├── programs/<sha256>/                # the bin/ of the rock of that sha256
│   ├── emmylua_check
│   ├── emmylua_doc_cli
│   ├── emmylua_ls
│   └── luafmt
├── resolved/<key>.json               # the rock a server, a version and a platform resolved to
└── config/<key>/emmyrc.json          # the configuration of a directory, by its path

The first run fetches the rock and says so; the later ones find it from resolved/ and ask no server. A rock server that is a directory is asked every time. Remove the directory to fetch the rocks anew.