From d5c874e1bd82b325d0aec98201747c9e8ee05815 Mon Sep 17 00:00:00 2001
From: Alexander Turenko <alexander.turenko@tarantool.org>
Date: Mon, 23 Oct 2023 11:33:45 +0300
Subject: [PATCH] main: rewrite help message
This commit aims several goals.
First, we're going to recommend `tt` as a tool to run and manage
tarantool instances. The tool is going to replace `tarantoolctl` and it
seems valuable to sync recipes across different parts of the
documentation (including this help message).
Second, the action options and modifier options are separated now. At
least one action option should be specified. I hope, it is more obvious
from the help message now.
Third, single line descriptions are replaced with a bit more extended
ones to give a user basic context to understand an influence of an
option.
Updated the man page accordingly: synchronized the options, removed
`tarantoolctl`.
Part of #8862
NO_TEST=the help message is not an API for a developer
NO_CHANGELOG=nothing new here, just better wording here and there
@TarantoolBot document
Title: Update CLI options documentation
https://www.tarantool.io/en/doc/latest/reference/configuration/#command-options
seems to need an update. See the linked commit for details and updated
`tarantool --help` message.
---
doc/man/tarantool.pod | 85 +++++++++-----
src/main.cc | 148 +++++++++++++++++++------
test/box-py/args.result | 240 +++++++++++++++++++++++++++++++---------
3 files changed, 357 insertions(+), 116 deletions(-)
diff --git a/doc/man/tarantool.pod b/doc/man/tarantool.pod
index 7633e425f9..436c06d8f9 100644
--- a/doc/man/tarantool.pod
+++ b/doc/man/tarantool.pod
@@ -4,6 +4,7 @@ tarantool - a Lua application server and a database management system
=head1 SYNOPSIS
+ tarantool [OPTIONS] --name NAME --config CONFIG
tarantool [OPTIONS] [SCRIPT [ARGS]]
=head1 DESCRIPTION
@@ -99,64 +100,96 @@ The database is a C extension of the application server and can be turned off.
=head1 OPTIONS
-You can use these options before (or instead of) the interpreted 'SCRIPT'
-name:
+All the options are separated into two groups: action options and modifier
+options.
+
+At least one action option should be specified.
+
+All the modifier options are optional.
+
+=head2 ACTION OPTIONS
=over
=item -h, --help
-Display the help screen and exit.
+Print this help message.
-=item -V, -v, --version
+=item -v, -V, --version
-Print the program version and exit.
+Print version and build information.
-=item -c, --config
+=item --help-env-list
-Set a path to yaml config file as 'PATH'.
+Print environment variables list.
-=item -n, --name
+=item -n <...> [-c <...>], --name <...> [--config <...>]
-Set an instance name as 'INSTANCE'.
+Start an instance.
-=item -e EXRP
+The path to the configuration file can be omitted if a configuration is stored
+in etcd and C<TT_CONFIG_ETCD_*> environment variables are set.
-Execute the string 'EXPR'.
+=item <first positional argument> [<..more args..>]
-=item -l NAME
+Run a Lua script file. All the arguments after the script name are stored in
+the `arg` global value.
-Require the library 'NAME'.
+The file may be pointed as `-` to read the script from stdin.
-=item -j CMD
+=item -e <..code..>
-Perform LuaJIT control command.
+Run a Lua code.
-=item -b ...
+It can be used on its own (as an action option) or together with another action
+option (as a modifier).
-Save or list bytecode.
+=item -i
-=item -d
+Run the interactive REPL.
-Activate debugging session for a script.
+=item --failover
-=item -i
+Run a failover coordinator service.
-Enter the interactive mode after executing 'SCRIPT'.
+It is available in Tarantool Enterprise Edition.
-=item --
+=back
+
+=head2 MODIFIER OPTIONS
+
+=over
-Stop handling options.
+=item --force-recovery
-=item -
+Enable force-recovery mode at database loading.
+
+=item -l <module>
+
+C<require> Lua module <module> and set it the same named global variable.
+
+=item -j <cmd>
+
+Perform LuaJIT control command <cmd>.
+
+=item -b <...>
+
+Save or list bytecode.
+
+=item -d
+
+Activate debugging session for a given script.
+
+=item --
-Execute stdin and stop handling options.
+End-of-options marker. All the arguments after the marker are interpreted as
+non-option ones.
=back
=head1 SEE ALSO
-tarantoolctl(1), Tarantool documentation at http://tarantool.org
+Tarantool documentation at https://tarantool.io
=head1 COPYRIGHT
diff --git a/src/main.cc b/src/main.cc
index 933fef626e..a186d28d35 100644
--- a/src/main.cc
+++ b/src/main.cc
@@ -620,41 +620,117 @@ print_version(void)
* Yield Tarantool help message to the given stream.
*/
static void
-print_help(FILE *stream, const char *program)
+print_help(FILE *stream)
{
- static const char help_msg[] = "Tarantool %s\n\n"
- "Run Tarantool instance:\n\n"
- " %s --name example-name --config ./config.yaml\n\n"
- "Connect to an instance:\n\n"
- " tt connect <uri>\n\n"
- "Execute Lua script with bundled LuaJIT:\n\n"
- " %s old-style-script.lua [OPTIONS] [ARGS]\n\n"
- "Run interactive LuaJIT interpreter:\n\n"
- " %s -i\n\n"
- "Usage:\n\n"
- " %s [OPTIONS] [SCRIPT [ARGS]]\n\n"
- "Options:\n\n"
- " -h, --help display this help and exit\n"
- " --help-env-list display env variables taken into account\n"
- " --force-recovery enable force-recovery\n"
- " -v, --version print program version and exit\n"
- " -c, --config PATH set a path to yaml config file as 'PATH'\n"
- " -n, --name INSTANCE set an instance name as 'INSTANCE'\n"
- " -i enter interactive mode\n"
- " -e EXPR execute string 'EXPR'\n"
- " -l NAME require library 'NAME'\n"
- " -j cmd perform LuaJIT control command\n"
- " -b ... save or list bytecode\n"
- " -d activate debugging session for script\n"
- " --failover run a failover coordinator (Enterprise Edition)\n"
- " -- stop handling options\n"
- " - execute stdin and stop handling options\n"
- "\n"
- "Please visit project home page at https://tarantool.org\n"
- "to see online documentation, submit bugs or contribute a patch.\n"
- ;
- fprintf(stream, help_msg, tarantool_version(),
- program, program, program, program);
+ static const char help_msg[] = "Tarantool %s\n"
+ "\n"
+ "----------------------------------------------------------\n"
+ "\n"
+ "The recommended way to work with Tarantool is to use tt\n"
+ "tool.\n"
+ "\n"
+ "Run a Tarantool instance:\n"
+ "\n"
+ "$ tt start --name <instance name>\n"
+ "\n"
+ "Connect to an instance:\n"
+ "\n"
+ "$ tt connect <uri>\n"
+ "\n"
+ "Execute a Lua script:\n"
+ "\n"
+ "$ tt run [OPTIONS] script.lua [ARGS]\n"
+ "\n"
+ "Run an interactive Lua interpreter:\n"
+ "\n"
+ "$ tt run -i\n"
+ "\n"
+ "----------------------------------------------------------\n"
+ "\n"
+ "At the lower level there are the following action options.\n"
+ "\n"
+ "-h\n"
+ "--help\n"
+ "\n"
+ " Print this help message.\n"
+ "\n"
+ "-v, -V\n"
+ "--version\n"
+ "\n"
+ " Print version and build information.\n"
+ "\n"
+ "--help-env-list\n"
+ "\n"
+ " Print environment variables list.\n"
+ "\n"
+ "-n <...> [-c <...>]\n"
+ "--name <...> [--config <...>]\n"
+ "\n"
+ " Start an instance.\n"
+ "\n"
+ " The path to the configuration file can be omitted if a\n"
+ " configuration is stored in etcd and TT_CONFIG_ETCD_*\n"
+ " environment variables are set.\n"
+ "\n"
+ "<first positional argument> [<..more args..>]\n"
+ "\n"
+ " Run a Lua script file. All the arguments after the\n"
+ " script name are stored in the `arg` global value.\n"
+ "\n"
+ " The file may be pointed as `-` to read the script from\n"
+ " stdin.\n"
+ "\n"
+ "-e <..code..>\n"
+ "\n"
+ " Run a Lua code.\n"
+ "\n"
+ " It can be used on its own (as an action option) or\n"
+ " together with another action option (as a modifier).\n"
+ "\n"
+ "-i\n"
+ "\n"
+ " Run the interactive REPL.\n"
+ "\n"
+ "--failover\n"
+ "\n"
+ " Run a failover coordinator service.\n"
+ "\n"
+ " It is available in Tarantool Enterprise Edition.\n"
+ "\n"
+ "The following modifier options are applicable to actions.\n"
+ "\n"
+ "--force-recovery\n"
+ "\n"
+ " Enable force-recovery mode at database loading.\n"
+ "\n"
+ "-l <module>\n"
+ "\n"
+ " `require` Lua module <module> and set it the same named\n"
+ " global variable.\n"
+ "\n"
+ "-j <cmd>\n"
+ "\n"
+ " Perform LuaJIT control command <cmd>.\n"
+ "\n"
+ "-b <...>\n"
+ "\n"
+ " Save or list bytecode.\n"
+ "\n"
+ "-d\n"
+ "\n"
+ " Activate debugging session for a given script.\n"
+ "\n"
+ "--\n"
+ "\n"
+ " End-of-options marker. All the arguments after the\n"
+ " marker are interpreted as non-option ones.\n"
+ "\n"
+ "Please visit project home page at https://tarantool.io\n"
+ "to see online documentation.\n"
+ "\n"
+ "Visit https://github.com/tarantool/tarantool to submit bugs\n"
+ "contribute a patch.\n";
+ fprintf(stream, help_msg, tarantool_version());
}
int
@@ -729,7 +805,7 @@ main(int argc, char **argv)
print_version();
return 0;
case 'h':
- print_help(stdout, basename(argv[0]));
+ print_help(stdout);
return 0;
case 'E':
opt_mask |= O_HELP_ENV_LIST;
@@ -878,7 +954,7 @@ main(int argc, char **argv)
"failover coordinator using --failover CLI option.\n\n"
;
fputs(misuse_msg, stderr);
- print_help(stderr, basename(argv[0]));
+ print_help(stderr);
return EXIT_FAILURE;
}
diff --git a/test/box-py/args.result b/test/box-py/args.result
index b50b992683..0db5d78320 100644
--- a/test/box-py/args.result
+++ b/test/box-py/args.result
@@ -1,90 +1,222 @@
tarantool --help
Tarantool 3.<minor>.<patch>-<suffix>
-Run Tarantool instance:
+----------------------------------------------------------
- tarantool --name example-name --config ./config.yaml
+The recommended way to work with Tarantool is to use tt
+tool.
+
+Run a Tarantool instance:
+
+$ tt start --name <instance name>
Connect to an instance:
- tt connect <uri>
+$ tt connect <uri>
+
+Execute a Lua script:
+
+$ tt run [OPTIONS] script.lua [ARGS]
+
+Run an interactive Lua interpreter:
+
+$ tt run -i
+
+----------------------------------------------------------
+
+At the lower level there are the following action options.
+
+-h
+--help
+
+ Print this help message.
+
+-v, -V
+--version
+
+ Print version and build information.
+
+--help-env-list
+
+ Print environment variables list.
+
+-n <...> [-c <...>]
+--name <...> [--config <...>]
+
+ Start an instance.
+
+ The path to the configuration file can be omitted if a
+ configuration is stored in etcd and TT_CONFIG_ETCD_*
+ environment variables are set.
+
+<first positional argument> [<..more args..>]
+
+ Run a Lua script file. All the arguments after the
+ script name are stored in the `arg` global value.
+
+ The file may be pointed as `-` to read the script from
+ stdin.
+
+-e <..code..>
+
+ Run a Lua code.
+
+ It can be used on its own (as an action option) or
+ together with another action option (as a modifier).
+
+-i
+
+ Run the interactive REPL.
+
+--failover
+
+ Run a failover coordinator service.
+
+ It is available in Tarantool Enterprise Edition.
+
+The following modifier options are applicable to actions.
+
+--force-recovery
+
+ Enable force-recovery mode at database loading.
+
+-l <module>
+
+ `require` Lua module <module> and set it the same named
+ global variable.
+
+-j <cmd>
-Execute Lua script with bundled LuaJIT:
+ Perform LuaJIT control command <cmd>.
- tarantool old-style-script.lua [OPTIONS] [ARGS]
+-b <...>
-Run interactive LuaJIT interpreter:
+ Save or list bytecode.
- tarantool -i
+-d
-Usage:
+ Activate debugging session for a given script.
- tarantool [OPTIONS] [SCRIPT [ARGS]]
+--
-Options:
+ End-of-options marker. All the arguments after the
+ marker are interpreted as non-option ones.
- -h, --help display this help and exit
- --help-env-list display env variables taken into account
- --force-recovery enable force-recovery
- -v, --version print program version and exit
- -c, --config PATH set a path to yaml config file as 'PATH'
- -n, --name INSTANCE set an instance name as 'INSTANCE'
- -i enter interactive mode
- -e EXPR execute string 'EXPR'
- -l NAME require library 'NAME'
- -j cmd perform LuaJIT control command
- -b ... save or list bytecode
- -d activate debugging session for script
- --failover run a failover coordinator (Enterprise Edition)
- -- stop handling options
- - execute stdin and stop handling options
+Please visit project home page at https://tarantool.io
+to see online documentation.
-Please visit project home page at https://tarantool.org
-to see online documentation, submit bugs or contribute a patch.
+Visit https://github.com/tarantool/tarantool to submit bugs
+contribute a patch.
tarantool -h
Tarantool 3.<minor>.<patch>-<suffix>
-Run Tarantool instance:
+----------------------------------------------------------
- tarantool --name example-name --config ./config.yaml
+The recommended way to work with Tarantool is to use tt
+tool.
+
+Run a Tarantool instance:
+
+$ tt start --name <instance name>
Connect to an instance:
- tt connect <uri>
+$ tt connect <uri>
+
+Execute a Lua script:
+
+$ tt run [OPTIONS] script.lua [ARGS]
+
+Run an interactive Lua interpreter:
+
+$ tt run -i
+
+----------------------------------------------------------
+
+At the lower level there are the following action options.
+
+-h
+--help
+
+ Print this help message.
+
+-v, -V
+--version
+
+ Print version and build information.
+
+--help-env-list
+
+ Print environment variables list.
+
+-n <...> [-c <...>]
+--name <...> [--config <...>]
+
+ Start an instance.
+
+ The path to the configuration file can be omitted if a
+ configuration is stored in etcd and TT_CONFIG_ETCD_*
+ environment variables are set.
+
+<first positional argument> [<..more args..>]
+
+ Run a Lua script file. All the arguments after the
+ script name are stored in the `arg` global value.
+
+ The file may be pointed as `-` to read the script from
+ stdin.
+
+-e <..code..>
+
+ Run a Lua code.
+
+ It can be used on its own (as an action option) or
+ together with another action option (as a modifier).
+
+-i
+
+ Run the interactive REPL.
+
+--failover
+
+ Run a failover coordinator service.
+
+ It is available in Tarantool Enterprise Edition.
+
+The following modifier options are applicable to actions.
+
+--force-recovery
+
+ Enable force-recovery mode at database loading.
+
+-l <module>
+
+ `require` Lua module <module> and set it the same named
+ global variable.
+
+-j <cmd>
-Execute Lua script with bundled LuaJIT:
+ Perform LuaJIT control command <cmd>.
- tarantool old-style-script.lua [OPTIONS] [ARGS]
+-b <...>
-Run interactive LuaJIT interpreter:
+ Save or list bytecode.
- tarantool -i
+-d
-Usage:
+ Activate debugging session for a given script.
- tarantool [OPTIONS] [SCRIPT [ARGS]]
+--
-Options:
+ End-of-options marker. All the arguments after the
+ marker are interpreted as non-option ones.
- -h, --help display this help and exit
- --help-env-list display env variables taken into account
- --force-recovery enable force-recovery
- -v, --version print program version and exit
- -c, --config PATH set a path to yaml config file as 'PATH'
- -n, --name INSTANCE set an instance name as 'INSTANCE'
- -i enter interactive mode
- -e EXPR execute string 'EXPR'
- -l NAME require library 'NAME'
- -j cmd perform LuaJIT control command
- -b ... save or list bytecode
- -d activate debugging session for script
- --failover run a failover coordinator (Enterprise Edition)
- -- stop handling options
- - execute stdin and stop handling options
+Please visit project home page at https://tarantool.io
+to see online documentation.
-Please visit project home page at https://tarantool.org
-to see online documentation, submit bugs or contribute a patch.
+Visit https://github.com/tarantool/tarantool to submit bugs
+contribute a patch.
tarantool -Z
tarantool: invalid option
--
GitLab