Add TT CLI 1.0.0 docs (#3414)

Resolves #3413

Author: p7nov

.github/workflows/deploy-branch.yml

@@ -9,7 +9,7 @@ on:
 # for example,
 # `deploy-branch/refs/add-concurrency`.
 #
-# Runs on branches `latest`, `tt`, and also tags, will never be canceled,
+# Runs on branch `latest` and tags will never be canceled,
 # due to having a unique group name
 # `{github.run_id}-{github.run_attempt}`,
 # for example,
@@ -18,7 +18,6 @@ concurrency:
   group: ${{
     (
     github.ref == 'refs/heads/latest' ||
-    github.ref == 'refs/heads/tt' ||
     startsWith(github.ref, 'refs/tags/')
     ) &&
     format('{0}-{1}', github.run_id, github.run_attempt) ||

doc/book/admin/upgrades.rst

@@ -32,7 +32,7 @@ replication cluster (see :ref:`below <admin-upgrades_replication_cluster>`).
 
 #.  Update your application files, if needed.
 
-#.  Launch the updated Tarantool server using ``tarantoolctl`` or ``systemctl``.
+#.  Launch the updated Tarantool server using ``tarantoolctl``, ``tt``, or ``systemctl``.
 
 ..  _admin-upgrades_replication_cluster:
 

doc/concepts/modules.rst

@@ -40,7 +40,8 @@ For example, here's a Lua application that uses ``myfun()`` from
    end
 
 Tarantool provides an `extensive library <https://www.tarantool.io/en/download/rocks>`_ of compatible modules.
-Install them using Tarantool's CLI utility :ref:`tarantoolctl <tarantoolctl>`.
+Install them using Tarantool's CLI utilities like :ref:`tarantoolctl <tarantoolctl>`
+or :ref:`tt CLI <tt-cli>`.
 Some modules are also included in the Tarantool repository and can be installed
 via your operating system's package manager.
 

doc/reference/tooling/index.rst

@@ -8,6 +8,7 @@ to work with Tarantool.
     :maxdepth: 1
 
     interactive_console
+    tt_cli/index
     tarantoolctl
     luajit_memprof
     luajit_getmetrics

doc/reference/tooling/tt_cli/arguments.rst

@@ -0,0 +1,33 @@
+Arguments
+=========
+
+``tt`` has the following arguments:
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 40 60
+        :header-rows: 0
+
+        *   -   ``--cfg=FILE``
+
+                ``-c=FILE``
+            -   Path to the :ref:`configuration file <tt-config_file>`.
+        *   -   ``--internal``
+
+                ``-I``
+            -   Force the use of an internal module even if there is an :doc:`external module <external_modules>` with the same name.
+        *   -   ``--local=DIRECTORY``
+
+                ``-L=DIRECTORY``
+            -   Use the ``tt`` environment from the specified directory.
+                Learn more about the :ref:`local launch mode <tt-config_modes-local>`.
+        *   -   ``--system``
+
+                ``-S``
+            -   Use the ``tt`` environment installed in the system.
+                Learn more about the :ref:`system launch mode <tt-config_modes-system>`.
+        *   -   ``--help``
+
+                ``-h``
+            -   Display help.

doc/reference/tooling/tt_cli/build.rst

@@ -0,0 +1,85 @@
+.. _tt-build:
+
+Building an application
+=======================
+
+..  code-block:: bash
+
+    tt build [PATH] [flags]
+
+
+``tt build`` builds a Tarantool application locally.
+
+Flags
+-----
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 30 70
+        :header-rows: 0
+
+        *   -   ``--spec``
+            -   Path to a ``.rockspec`` file to use for the current build
+
+
+Details
+-------
+
+The ``PATH`` argument should contain the path to the application directory
+(that is, to the build source). The default path is ``.`` (current directory).
+
+The application directory must contain a ``.rockspec`` file to use for the build.
+If there is more than one ``.rockspec`` file in the application directory, specify
+the one to use in the ``--spec`` argument.
+
+``tt build`` builds an application with the ``tt rocks make`` command.
+It downloads the application dependencies into the ``.rocks`` directory,
+making the application ready to run locally.
+
+Pre-build and post-build scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to building the application with LuaRocks, ``tt build``
+can execute *pre-build* and *post-build* scripts. These scripts should
+contain steps to execute right before and after building the application.
+These files must be named ``tt.pre-build`` and ``tt.post-build`` correspondingly
+and located in the application directory.
+
+.. note::
+
+    For compatibility with Cartridge applications,
+    the pre-build and post-build scripts can also have names ``cartridge.pre-build``
+    and ``cartridge.post-build``.
+
+If your application depends on closed-source rocks, or if the build should contain
+rocks from a project added as a submodule, **install** these
+dependencies using the pre-build script **before** building.
+For example, add the following line:
+
+..  code-block:: bash
+
+    tt rocks make --chdir ./third_party/proj
+
+Learn more about :doc:`pre-build and post-build scripts </book/cartridge/cartridge_cli/pre-post-build>`.
+
+Examples
+--------
+
+*   Build the application ``app1`` from its directory:
+
+    ..  code-block:: bash
+
+        tt build
+
+*   Build the application ``app1`` from the ``simple_app`` directory inside the current directory:
+
+    ..  code-block:: bash
+
+        tt build simple_app
+
+*   Build the application ``app1`` from its directory explicitly specifying the rockspec file to use:
+
+    ..  code-block:: bash
+
+        tt build --spec app1-scm-1.rockspec

doc/reference/tooling/tt_cli/cat.rst

@@ -0,0 +1,71 @@
+Printing the contents of .snap and .xlog files
+==============================================
+
+..  code-block:: bash
+
+    tt cat FILE .. [flags]
+
+``tt cat`` prints the contents of :ref:`snapshot <internals-snapshot>` (``.snap``) and
+:ref:`WAL <internals-wal>` (``.xlog``) files to stdout. A single call of ``tt cat`` can
+print the contents of multiple files.
+
+
+Flags
+-----
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 20 80
+        :header-rows: 0
+
+        *   -   ``--format``
+            -   Output format: ``yaml`` (default), ``json``, or ``lua``
+        *   -   ``--from``
+            -   Show operations starting from the given LSN
+        *   -   ``--to``
+            -   Show operations up to the given LSN. Default: 18446744073709551615
+        *   -   ``--replica``
+            -   Filter the output by replica ID. Can be passed more than once
+        *   -   ``--space``
+            -   Filter the output by space ID. Can be passed more than once
+        *   -   ``--show-system``
+            -   Show the contents of system spaces
+
+Details
+-------
+
+When calling ``tt cat`` with filters by LSN (``--from`` and ``--to`` flags) and
+replica ID (``--replica``), remember that LSNs differ across replicas.
+Thus, if you pass more than one replica ID via ``--from`` or ``--to``,
+the result may not reflect the actual sequence of operations.
+
+Examples
+--------
+
+*   Output contents of ``00000000000000000000.xlog`` WAL file in the YAML format:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000000.xlog
+
+*   Output operations on spaces with ``space_id`` 512 and 513 from the
+    ``00000000000000000012.snap`` snapshot file in the JSON format:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000012.snap --space 512 --space 513 --format json
+
+*   Output operations on all spaces, including system spaces,
+    from the ``00000000000000000000.xlog`` WAL file:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000000.xlog --show-system
+
+*   Output operations with LSNs between 100 and 500 on replica 1
+    from the ``00000000000000000000.xlog`` WAL file:
+
+    ..  code-block:: bash
+
+        tt cat 00000000000000000000.xlog --from 100 --to 500 --replica 1

doc/reference/tooling/tt_cli/check.rst

@@ -0,0 +1,34 @@
+Checking an application file
+============================
+
+..  code-block:: bash
+
+    tt check APP_FILE
+
+``tt check`` checks the specified Tarantool application file for syntax errors.
+
+Details
+-------
+
+``tt`` searches for ``APP_FILE`` inside the ``instances_enabled`` directory
+specified in the :ref:`tt configuration file <tt-config_file_app>`. ``APP_FILE`` can be:
+
+*   the name of an application file without the ``.lua`` extension.
+*   the name of a directory containing the ``init.lua`` file. In this case, ``init.lua`` is checked.
+
+
+Examples
+--------
+
+*   Check the syntax of the ``app.lua`` file from the ``instances_enabled`` directory:
+
+    ..  code-block:: bash
+
+        tt check app
+
+
+*   Check the syntax of the ``init.lua`` file from the ``instance1/`` directory inside ``instances_enabled``:
+
+    ..  code-block:: bash
+
+        tt check instance1

doc/reference/tooling/tt_cli/clean.rst

@@ -0,0 +1,54 @@
+.. _tt-clean:
+
+Cleaning instance files
+=======================
+
+..  code-block:: bash
+
+    tt clean INSTANCE|APPLICATION [flags]
+
+``tt clean`` cleans stored files of Tarantool instances: logs, snapshots, and
+other files. To avoid accidental deletion of files, ``tt clean`` shows
+the files it is going to delete and asks for confirmation.
+
+Flags
+-----
+
+..  container:: table
+
+    ..  list-table::
+        :widths: 30 70
+        :header-rows: 0
+
+        *   -   ``-f``
+
+                ``--force``
+            -   Clean files without confirmation
+
+
+Examples
+--------
+
+Single instance
+~~~~~~~~~~~~~~~
+
+*   Clean the files of the ``app`` instance:
+
+    ..  code-block:: bash
+
+        tt clean app
+
+Multiple instances
+~~~~~~~~~~~~~~~~~~
+
+*   Clean the files of all instances of the ``app`` application:
+
+    ..  code-block:: bash
+
+        tt clean app
+
+*   Clean the files of the ``master`` instance of the ``app`` application:
+
+    ..  code-block:: bash
+
+        tt clean app:master