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.