Skip to content

Your first package

This tutorial writes a small Tarantool application as a package: it declares a dependency, builds, runs a test, packs the application into an archive and installs the archive for the current user.

Create the manifest

$ mkdir hello && cd hello
$ git init
$ tt new
created /home/me/hello/app.manifest.toml for package hello
$ tt binary install tarantool

tt new writes app.manifest.toml, named after the directory. The package name is lowercase letters, digits and dashes, starting with a letter; give another one with -n. tt binary install tarantool gives the project the Tarantool it builds and runs on.

Add dependencies

$ tt package add checks '>=3.0.0'
added checks >=3.0.0 to [dependencies]
  checks 3.4.1-1
$ tt package add luatest --dev
added luatest * to [dev_dependencies]
  luatest 1.4.5-1

tt package add declares a dependency in the manifest and resolves it into app.manifest.lock, which pins the exact versions; commit both. A --dev dependency is for the tests and tools only: it does not go into the archive.

Write the code

The code of a package is its components. Declare one for the hello directory:

[components.app]
path = "hello"

hello/init.lua:

local checks = require('checks')

local function greet(name)
    checks('string')
    return 'Hello, ' .. name .. '!'
end

return {greet = greet}

Build and run

$ tt package build
$ tt run -e "print(require('hello').greet('tt'))" - </dev/null
Hello, tt!

tt package build installs the dependencies into .rocks/ and lays out the files of the components under .rocks/share/tarantool/hello/, with a version.lua, so the code is require('hello'). tt run runs the Tarantool of the project with the arguments as given; without a script it starts an interactive console. It runs in the current directory, as tarantool started there would, so a script path is relative to it, and works from any subdirectory of the project: Tarantool finds .rocks/ by searching upward, and below the root tt puts the root at the head of LUA_PATH and LUA_CPATH for the sources there. -h and --help before the script name print the help of tt run; everything from the script name on is the script's, -h included.

Test

test/hello_test.lua:

local t = require('luatest')
local hello = require('hello')

local g = t.group()

g.test_greet = function()
    t.assert_equals(hello.greet('world'), 'Hello, world!')
end
$ tt test
.
Ran 1 tests in 0.001 seconds, 1 succeeded, 0 failed

tt test builds the package and runs luatest over test/. Paths relative to the project narrow the run, as many as you name: tt test test/unit test/integration. Arguments after -- go to luatest: tt test test/hello_test.lua -- --verbose.

Describe the instances

.templates/default/config.yaml is the cluster config the package runs from:

app:
  module: hello

groups:
  group-001:
    replicasets:
      replicaset-001:
        instances:
          instance-001:
            iproto:
              listen:
              - uri: 127.0.0.1:3311

app.module loads the code from .rocks/, where it is both in the project and in an installed package. A template of config.yaml alone runs every instance of its topology; tt instance start runs it in the project too.

Pack

Commit the project and tag the version: the version of a package is the one of its VERSION file, or else of the nearest version tag, v1.0.0 or 1.0.0.

$ printf '.rocks/\n.tarantool/\n.env/\n_build/\n' > .gitignore
$ git add -A && git commit -m 'hello 1.0.0' && git tag v1.0.0
$ tt package pack
/home/me/hello/_build/pack/hello-1.0.0-linux-amd64.tt

The archive carries the package, its dependencies and, in _runtime/, the Tarantool and the tt it runs on, so it installs with no network. Changes not committed, untracked files among them, give the version a +dirty suffix.

Preview note. tt package pack bundles a tt that matches [platform].tt of the manifest: the one tt binary install tt put into the project, or else the tt that runs it (Packing has the whole order). See the note in Install for a tt built from source.

Install for the user

$ tt package install _build/pack/hello-1.0.0-linux-amd64.tt --scope user
installed hello 1.0.0 into user scope
$ tt package list --scope user
NAME   ACTIVE  VERSIONS  DESCRIPTION
hello  1.0.0   1.0.0
$ tt instance start hello:instance-001 --scope user
$ echo "return require('hello').greet('user scope')" | tt connect hello:instance-001 --scope user -f-
---
- Hello, user scope!
...
$ tt instance stop hello:* --scope user --yes

The user scope is ~/.local/share/tarantool on Linux. The package becomes the version versions/hello/hello_1.0.0/ there, and apps/hello points to it; the instances keep their data under var/ of the scope. See Projects and scopes and Install an application for a user.

Next