Documentation
¶
Overview ¶
Package scope answers where the root of a scope is, for every command group that installs into a scope or runs from one: tt binary, tt package and tt instance.
A root is the directory a scope keeps its artifacts under: the installed versions of tarantool, tt, tcm and applications, the links selecting the active ones, and the runtime data of the instances started from them. The command groups share one root per scope, so an application installed by tt package finds the tarantool tt binary put next to it, and tt instance finds both. The answer therefore lives below all of them instead of being spelled out by each.
The user and system roots follow the conventions of the operating system and are moved by TT_USER_ROOT and TT_SYSTEM_ROOT: a host that keeps Tarantool elsewhere sets the variable once instead of every command taking a flag. The project root is .tarantool in the project directory, and the project directory is found rather than configured: it is the nearest directory, starting from the one a command works in, that holds a project marker (see FindProject). A command run anywhere inside a project therefore works on the same tree.
Index ¶
- Constants
- Variables
- func CheckVarLinks(root, app, versionDir string) (bool, error)
- func FindProject(start string) (string, bool, error)
- func InstalledTree(dir string) (bool, error)
- func LinkVar(root, app, versionDir string, perm fs.FileMode) error
- func ProjectRoot(projectDir string) string
- func SystemRoot() (string, error)
- func UserRoot() (string, error)
- type Installation
- type VarLink
Constants ¶
const ( // ProjectDirName is the directory in the project directory that is the // root of the project scope. ProjectDirName = ".tarantool" // ManifestFileName is the project manifest, one of the project markers. ManifestFileName = "app.manifest.toml" // TemplatesDirName is the directory holding the project's instance // templates, one per subdirectory. TemplatesDirName = ".templates" // InstancesFileName is the instances description of a template; in any // template it is a project marker. InstancesFileName = "instances.yaml" // ConfigFileName is the cluster config of a template; in any template it // is a project marker as well, since a template of the config alone runs // every instance of its topology. ConfigFileName = "config.yaml" // VersionsDirName is the directory of a user or system root that holds // the installed versions of binaries and applications. VersionsDirName = "versions" // AppsDirName is the directory of a user or system root that holds the // links to the active versions of installed applications. AppsDirName = "apps" // DataDirName, LogDirName and RunDirName are the directories of every // scope root that hold the runtime artifacts of the instances, one // subdirectory per application and instance in each, as // <root>/var/run/<app>/<inst>/. The layout of an instance is built on // them; and the run directory of an instance, which tt instance clean // leaves, tells that the instance has run under the root. DataDirName = "var/lib" LogDirName = "var/log" RunDirName = "var/run" // PidFileName is the pid file the watchdog of an instance keeps in its // run directory, <root>/var/run/<app>/<inst>/tt.pid, while the instance // runs, and removes when it stops. Unlike the directory, it tells that // the instance runs under the root, or has crashed and left it behind. PidFileName = "tt.pid" )
const ( // UserRootEnv names the environment variable that overrides the user root. UserRootEnv = "TT_USER_ROOT" // SystemRootEnv names the environment variable that overrides the system // root. SystemRootEnv = "TT_SYSTEM_ROOT" )
const VarDirName = "var"
VarDirName is the directory of an installed version that a signed install links the layout of its instances from.
Tarantool Enterprise starts with an empty environment when it checks integrity, so the TT_*_DEFAULT variables tt passes the layout through do not reach it, and the paths of an instance fall back to the defaults of Tarantool: var/lib/<inst> for the data, var/run/<inst> for the pid file and the console socket, var/log/<inst> for a log file, under the working directory, which is the version. A signed version therefore holds var/lib, var/run and var/log as links to <root>/var/lib/<app>, <root>/var/run/<app> and <root>/var/log/<app>: the defaults of Tarantool then name the files of the layout tt finds the instance by, and every version of the application leads to the same data.
Variables ¶
var ErrInstalledTree = errors.New("is inside an installed version, not a project")
ErrInstalledTree reports a directory inside the versions/ or apps/ tree of the user or system scope: an installed version, not a project.
var ErrRelativeRoot = errors.New("must be an absolute path")
ErrRelativeRoot is wrapped by the error for a relative TT_USER_ROOT or TT_SYSTEM_ROOT.
var ErrVarLink = errors.New("is not the link to the layout of the instances")
ErrVarLink is wrapped by the error for an entry of var/ in a version that is not the link VarLinks says it is.
Functions ¶
func CheckVarLinks ¶
CheckVarLinks checks the links of VarLinks the version in versionDir has, and reports whether any of them is missing. An entry that is not a link, or a link that leads elsewhere, is an error wrapping ErrVarLink.
func FindProject ¶
FindProject returns the project directory for start: start itself or the nearest of its parents that holds a project marker, up to the filesystem root. found is false when none of them does. A relative start is resolved against the working directory; it must be an existing directory.
A marker is an app.manifest.toml, or an instances.yaml or a config.yaml in any template directory under .templates/: a project is described by its manifest, by its instance templates, or by both, and a template of the cluster config alone runs every instance of its topology. A config.yaml elsewhere, .rocks/, .git/ and Lua files are not markers: they turn up in directories that are not projects. Neither is .tarantool/: tt binary install creates it in a directory that is not a project yet, and that must not capture the directories below it.
A marker counts by its existence alone; its contents are not read. A directory whose manifest does not parse is still the project, and the command that reads the manifest reports the damage. Reading it here would either fail every command run inside a broken project, including those that do not need the manifest, or skip the directory and silently land in an enclosing project, or in none.
The nearest marker wins, so a project nested in another is found from its own subdirectories. The path is climbed as spelled, without resolving symbolic links, so the parents are the ones the caller's path names.
A start inside an installed version (InstalledTree) has no project, even though the version carries a manifest and templates like a project does: the project scope would put its .tarantool and the data of its instances inside a version that is never written to and that a switch replaces.
func InstalledTree ¶
InstalledTree reports whether dir is inside the versions/ or apps/ tree of the user or system scope root, that is, in an installed version of a binary or an application or reached through the link to one.
Both the path as spelled and the path with its links resolved are checked, against the root as spelled and resolved: a shell in <root>/apps/<app> reports the link, while a process that resolved its directory reports the version the link points to, and either way it is the same version.
A root that cannot be placed here (no home directory, an unsupported OS) holds nothing tt installed, so it is skipped. A root set to a relative path is an error, as it is everywhere else the root is used.
func LinkVar ¶
LinkVar creates the links of VarLinks that the version in versionDir does not have yet, with var/ itself of mode perm, and checks those it has. A link is relative, like the link to the active version, so that the root may be moved or mounted elsewhere. Its target need not exist: tt creates the directories of an instance before the instance starts.
func ProjectRoot ¶
ProjectRoot returns the root of the project scope for the project in projectDir.
func SystemRoot ¶
SystemRoot returns the absolute root of the system scope without creating it.
TT_SYSTEM_ROOT names the root outright, on any operating system. Without it, the root is /opt/tarantool on Linux and /Library/Application Support/tarantool on macOS.
func UserRoot ¶
UserRoot returns the absolute root of the user scope without creating it.
TT_USER_ROOT names the root outright, on any operating system. Without it, the root on Linux is $XDG_DATA_HOME/tarantool when XDG_DATA_HOME is an absolute path and ~/.local/share/tarantool otherwise: the XDG Base Directory specification makes a relative value invalid and tells readers to ignore it. On macOS the root is ~/Library/Application Support/tarantool, where the platform keeps application data, and XDG_DATA_HOME is ignored.
Types ¶
type Installation ¶
type Installation struct {
// Root is the scope root, as UserRoot or SystemRoot returns it.
Root string
// User tells the user scope from the system one.
User bool
}
Installation is the scope root whose versions/ or apps/ tree a directory is in.
func FindInstallation ¶
func FindInstallation(dir string) (Installation, bool, error)
FindInstallation reports which scope root's versions/ or apps/ tree dir is in, by the same rules as InstalledTree. found is false outside every such tree. The user root is checked before the system one.
Source Files