Add --enable-embedded-help option to embed --help messages in binaries

This patch adds a configuration option to embed the help message within
the various executables of LTTng-tools instead of always launching the
man pager. This applies to the following commands:

    lttng --help
    lttng CMD --help
    lttng help CMD
    lttng-crash --help
    lttng-relayd --help
    lttng-sessiond --help

This is meant to be used by distributions which remove man pages or do
not have a man pager (embedded distributions, mostly). For example,
Buildroot is known to remove all man pages before it creates the final
image:

    rm -rf $(TARGET_DIR)/usr/man $(TARGET_DIR)/usr/share/man

If you pass the `--enable-embedded-help` option to the `configure`
script:

1. The configure script checks if `man` exists in the `PATH` environment
   variable. This tool is needed to generate the text versions of the
   man pages.

2. When you build LTTng-tools with `make`, the man pages are generated
   as usual (or they already exist in their troff version from a
   tarball), and their text versions are generated with `man`, with a
   fixed width set to 80 columns.

3. The text versions of the man pages are converted to literal C strings
   thanks to some `sed` magic:

   a. Replace `\` with `\\`.
   b. Replace `"` with `\"`.
   c. Add `"` prefix and `\n"` suffix to each line.

   This file is named `NAME.SECTION.h`, where `NAME` is the name of the
   man page and `SECTION` is its section. For example,
   `lttng-create.1.h`.

   I needed to add a `.PRECIOUS` target in `doc/man/Makefile.am` because
   otherwise `make` treats the troff man page files as intermediate
   files and removes them automatically. Then they need to be rebuilt
   to be installed.

4. In each C file where to show a help message, we check if the
   `--enable-embedded-help` option is set, and if so, we assign the
   included help message string to a static variable to be printed
   instead of executing the man pager.

This string added to the object file in #4 takes binary space, why is
why the `--enable-embedded-help` option is turned off by default.

The directories in the "master" `SUBDIRS` (`Makefile.am`) are reordered
so that `doc` is built before `src` since there's a direct dependency
when you pass `--enable-embedded-help`.

The `--disable-man-pages` and `--enable-embedded-help` options do not
form a valid configuration.

Signed-off-by: Philippe Proulx <[email protected]>
Signed-off-by: Jérémie Galarneau <[email protected]>

Author: eepp

.gitignore

@@ -116,6 +116,7 @@ tests/regression/ust/python-logging/test_python_logging
 /doc/man/*.8
 /doc/man/*.xml
 /doc/man/*.html
+/doc/man/*.h
 /doc/man/asciidoc-attrs.conf
 !/doc/man/lttng-health-check.3
 

Makefile.am

@@ -1,8 +1,8 @@
 ACLOCAL_AMFLAGS = -I m4
 
-DIST_SUBDIRS = include src extras doc tests
+DIST_SUBDIRS = include doc src extras tests
 
-SUBDIRS = include src doc tests
+SUBDIRS = include doc src tests
 
 if BUILD_EXTRAS
 SUBDIRS += extras

configure.ac

@@ -653,6 +653,29 @@ AM_CONDITIONAL([HAVE_ASCIIDOC_XMLTO], [test "x$have_asciidoc_xmlto" = "xyes"])
 
 AC_DEFINE_UNQUOTED([MANPATH], ["`eval eval echo $mandir`"], [Path to man pages.])
 
+# embedded --help message
+AC_ARG_ENABLE(
+	[embedded-help],
+	AS_HELP_STRING(
+		[--enable-embedded-help],
+		[Embed the --help messages in the executable files]
+	),
+	[embedded_help=$enableval],
+	[embedded_help=no]
+)
+AS_IF([test "x$embedded_help" = "xyes"], [
+	AS_IF([test "x$man_pages_opt" = "xno"], [
+		AC_MSG_ERROR([You need the --enable-man-pages option with the --enable-embedded-help option.])
+	])
+	AC_PATH_PROG([man_prog_path], [man], [no])
+	AS_IF([test "x$man_prog_path" = "xno"], [
+		AC_MSG_ERROR([You need man with the --enable-embedded-help option.])
+	])
+	AC_DEFINE_UNQUOTED([LTTNG_EMBED_HELP], 1, [Embed --help messages.])
+	AC_SUBST([MANPROG], [$man_prog_path])
+])
+AM_CONDITIONAL([EMBED_HELP], [test "x$embedded_help" != "xno"])
+
 # Python agent test
 UST_PYTHON_AGENT="lttngust"
 
@@ -1186,6 +1209,9 @@ AS_IF([test "x$man_pages_opt" != "xno"], [
 
 m4_popdef([build_man_pages_msg])
 
+test "x$embedded_help" = xyes && value=1 || value=0
+PPRINT_PROP_BOOL([Embed --help messages], $value, $PPRINT_COLOR_SUBTITLE)
+
 PPRINT_SET_INDENT(1)
 
 report_bindir="`eval eval echo $bindir`"

doc/man/Makefile.am

@@ -73,6 +73,34 @@ MAN3_NO_ASCIIDOC = $(addsuffix .3,$(MAN3_NO_ASCIIDOC_NAMES))
 MAN8_NO_ASCIIDOC = $(addsuffix .8,$(MAN8_NO_ASCIIDOC_NAMES))
 MAN = $(MAN1) $(MAN3) $(MAN8)
 
+# initially empty
+CLEANFILES =
+
+if EMBED_HELP
+MAN1_H = $(addsuffix .1.h,$(MAN1_NAMES))
+MAN3_H = $(addsuffix .3.h,$(MAN3_NAMES))
+MAN8_H = $(addsuffix .8.h,$(MAN8_NAMES))
+MAN_H = $(MAN1_H) $(MAN3_H) $(MAN8_H)
+MAN_H_RECIPE = \
+	MANWIDTH=80 @MANPROG@ --encoding=UTF-8 --no-hyphenation --no-justification --local-file $< > $@ ; \
+	$(SED) -i 's/\\/\\\\/g' $@ ; \
+	$(SED) -i 's/"/\\"/g' $@ ; \
+	$(SED) -i 's/^\(.*\)$$/"\1\\n"/' $@
+
+%.1.h: %.1
+	$(MAN_H_RECIPE)
+
+%.3.h: %.3
+	$(MAN_H_RECIPE)
+
+%.8.h: %.8
+	$(MAN_H_RECIPE)
+
+all-local: $(MAN_H)
+
+CLEANFILES += $(MAN_H)
+endif # EMBED_HELP
+
 if MAN_PAGES_OPT
 # at this point, we know the user asked to build the man pages
 if HAVE_ASCIIDOC_XMLTO
@@ -106,7 +134,7 @@ COMMON_DEPS += $(ASCIIDOC_ATTRS_CONF)
 	$(XTO) $<
 
 # only clean the generated files if we have the tools to generate them again
-CLEANFILES = $(MAN_XML) $(MAN)
+CLEANFILES += $(MAN_XML) $(MAN)
 else # HAVE_ASCIIDOC_XMLTO
 # create man page targets used to stop the build if we want to
 # build the man pages, but we don't have the necessary tools to do so
@@ -148,3 +176,6 @@ endif # !MAN_PAGES_OPT
 # always distribute the source files
 EXTRA_DIST = $(MAN_TXT) $(COMMON_TXT) $(XSL_SRC_FILES) \
 	$(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in
+
+# keep generated man pages that can be considered intermediate files
+.PRECIOUS: %.1 %.3 %.8

src/bin/lttng-crash/Makefile.am

@@ -1,6 +1,10 @@
 AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_srcdir)/src \
 			  -DINSTALL_BIN_PATH=\""$(bindir)"\"
 
+if EMBED_HELP
+AM_CPPFLAGS += -I$(top_builddir)/doc/man
+endif
+
 bin_PROGRAMS = lttng-crash
 
 lttng_crash_SOURCES = lttng-crash.c

src/bin/lttng-crash/lttng-crash.c

@@ -61,6 +61,14 @@
 		0xF1 ^ 0xFF, 0x77 ^ 0xFF, 0xBF ^ 0xFF, 0x17 ^ 0xFF,	\
 	}
 
+static const char *help_msg =
+#ifdef LTTNG_EMBED_HELP
+#include <lttng-crash.1.h>
+#else
+NULL
+#endif
+;
+
 /*
  * Non-static to ensure the compiler does not optimize away the xor.
  */
@@ -207,10 +215,10 @@ static struct option long_options[] = {
 
 static void usage(void)
 {
-	int ret = utils_show_man_page(1, "lttng-crash");
+	int ret = utils_show_help(1, "lttng-crash", help_msg);
 
 	if (ret) {
-		ERR("Cannot view man page lttng-crash(1)");
+		ERR("Cannot show --help for `lttng-crash`");
 		perror("exec");
 		exit(EXIT_FAILURE);
 	}

src/bin/lttng-relayd/Makefile.am

@@ -2,6 +2,10 @@ AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_srcdir)/src \
 			  -DINSTALL_BIN_PATH=\""$(lttnglibexecdir)"\" \
 			  -DINSTALL_LIB_PATH=\""$(libdir)"\"
 
+if EMBED_HELP
+AM_CPPFLAGS += -I$(top_builddir)/doc/man
+endif
+
 AM_CFLAGS = -fno-strict-aliasing
 
 bin_PROGRAMS = lttng-relayd

src/bin/lttng-relayd/main.c

@@ -71,6 +71,14 @@
 #include "connection.h"
 #include "tracefile-array.h"
 
+static const char *help_msg =
+#ifdef LTTNG_EMBED_HELP
+#include <lttng-relayd.8.h>
+#else
+NULL
+#endif
+;
+
 /* command line options */
 char *opt_output_path;
 static int opt_daemon, opt_background;
@@ -250,9 +258,9 @@ static int set_option(int opt, const char *arg, const char *optname)
 		}
 		break;
 	case 'h':
-		ret = utils_show_man_page(8, "lttng-relayd");
+		ret = utils_show_help(8, "lttng-relayd", help_msg);
 		if (ret) {
-			ERR("Cannot view man page lttng-relayd(8)");
+			ERR("Cannot show --help for `lttng-relayd`");
 			perror("exec");
 		}
 		exit(EXIT_FAILURE);

src/bin/lttng-sessiond/Makefile.am

@@ -2,6 +2,10 @@ AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_srcdir)/src \
 			  -DINSTALL_BIN_PATH=\""$(lttnglibexecdir)"\" \
 			  -DINSTALL_LIB_PATH=\""$(libdir)"\"
 
+if EMBED_HELP
+AM_CPPFLAGS += -I$(top_builddir)/doc/man
+endif
+
 AM_CFLAGS = -fno-strict-aliasing
 
 bin_PROGRAMS = lttng-sessiond

src/bin/lttng-sessiond/main.c

@@ -79,6 +79,14 @@
 
 #define CONSUMERD_FILE	"lttng-consumerd"
 
+static const char *help_msg =
+#ifdef LTTNG_EMBED_HELP
+#include <lttng-sessiond.8.h>
+#else
+NULL
+#endif
+;
+
 const char *progname;
 const char *tracing_group_name = DEFAULT_TRACING_GROUP;
 static int tracing_group_name_override;
@@ -4757,9 +4765,9 @@ static int set_option(int opt, const char *arg, const char *optname)
 			tracing_group_name_override = 1;
 		}
 	} else if (string_match(optname, "help") || opt == 'h') {
-		ret = utils_show_man_page(8, "lttng-sessiond");
+		ret = utils_show_help(8, "lttng-sessiond", help_msg);
 		if (ret) {
-			ERR("Cannot view man page lttng-sessiond(8)");
+			ERR("Cannot show --help for `lttng-sessiond`");
 			perror("exec");
 		}
 		exit(ret ? EXIT_FAILURE : EXIT_SUCCESS);

src/bin/lttng/Makefile.am

@@ -1,6 +1,10 @@
 AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_srcdir)/src \
 			  -DINSTALL_BIN_PATH=\""$(bindir)"\"
 
+if EMBED_HELP
+AM_CPPFLAGS += -I$(top_builddir)/doc/man
+endif
+
 AUTOMAKE_OPTIONS = subdir-objects
 
 bin_PROGRAMS = lttng

src/bin/lttng/command.h

@@ -28,13 +28,20 @@
 #define DECL_COMMAND(_name) \
 	extern int cmd_##_name(int, const char **)
 
+#ifdef LTTNG_EMBED_HELP
+# define HELP_MSG_NAME		help_msg
+# define SHOW_HELP_ERROR_LINE	ERR("Cannot show --help for `lttng-%s`", argv[0]);
+#else
+# define HELP_MSG_NAME		NULL
+# define SHOW_HELP_ERROR_LINE	;
+#endif
+
 #define SHOW_HELP() 							\
 	do {								\
-		ret = show_cmd_man_page(argv[0]);			\
+		ret = show_cmd_help(argv[0], HELP_MSG_NAME);		\
 									\
 		if (ret) {						\
-			ERR("Cannot view man page lttng-%s(1)", argv[0]); \
-			perror("exec");					\
+			SHOW_HELP_ERROR_LINE 				\
 			ret = CMD_ERROR;				\
 		}							\
 	} while (0)

src/bin/lttng/commands/add_context.c

@@ -41,6 +41,12 @@ static int opt_jul;
 static int opt_log4j;
 static char *opt_type;
 
+#ifdef LTTNG_EMBED_HELP
+static const char help_msg[] =
+#include <lttng-add-context.1.h>
+;
+#endif
+
 enum {
 	OPT_HELP = 1,
 	OPT_TYPE,

src/bin/lttng/commands/create.c

@@ -51,6 +51,12 @@ static int opt_no_output;
 static int opt_snapshot;
 static unsigned int opt_live_timer;
 
+#ifdef LTTNG_EMBED_HELP
+static const char help_msg[] =
+#include <lttng-create.1.h>
+;
+#endif
+
 enum {
 	OPT_HELP = 1,
 	OPT_LIST_OPTIONS,

src/bin/lttng/commands/destroy.c

@@ -35,6 +35,12 @@ static char *opt_session_name;
 static int opt_destroy_all;
 static int opt_no_wait;
 
+#ifdef LTTNG_EMBED_HELP
+static const char help_msg[] =
+#include <lttng-destroy.1.h>
+;
+#endif
+
 /* Mi writer */
 static struct mi_writer *writer;
 

src/bin/lttng/commands/disable_channels.c

@@ -34,6 +34,12 @@ static int opt_kernel;
 static char *opt_session_name;
 static int opt_userspace;
 
+#ifdef LTTNG_EMBED_HELP
+static const char help_msg[] =
+#include <lttng-disable-channel.1.h>
+;
+#endif
+
 enum {
 	OPT_HELP = 1,
 	OPT_USERSPACE,

src/bin/lttng/commands/disable_events.c

@@ -40,6 +40,12 @@ static int opt_log4j;
 static int opt_python;
 static int opt_event_type;
 
+#ifdef LTTNG_EMBED_HELP
+static const char help_msg[] =
+#include <lttng-disable-event.1.h>
+;
+#endif
+
 enum {
 	OPT_HELP = 1,
 	OPT_TYPE_SYSCALL,

src/bin/lttng/commands/enable_channels.c

@@ -51,6 +51,12 @@ static struct {
 
 static struct mi_writer *writer;
 
+#ifdef LTTNG_EMBED_HELP
+static const char help_msg[] =
+#include <lttng-enable-channel.1.h>
+;
+#endif
+
 enum {
 	OPT_HELP = 1,
 	OPT_DISCARD,

src/bin/lttng/commands/enable_events.c

@@ -55,6 +55,12 @@ static char *opt_channel_name;
 static char *opt_filter;
 static char *opt_exclude;
 
+#ifdef LTTNG_EMBED_HELP
+static const char help_msg[] =
+#include <lttng-enable-event.1.h>
+;
+#endif
+
 enum {
 	OPT_HELP = 1,
 	OPT_TRACEPOINT,

src/bin/lttng/commands/help.c

@@ -24,6 +24,22 @@
 #include "../command.h"
 #include <common/utils.h>
 
+static const char *help_msg =
+#ifdef LTTNG_EMBED_HELP
+#include <lttng-help.1.h>
+#else
+NULL
+#endif
+;
+
+static const char *lttng_help_msg =
+#ifdef LTTNG_EMBED_HELP
+#include <lttng.1.h>
+#else
+NULL
+#endif
+;
+
 enum {
 	OPT_HELP = 1,
 	OPT_LIST_OPTIONS,
@@ -69,14 +85,14 @@ int cmd_help(int argc, const char **argv, const struct cmd_struct commands[])
 
 	if (cmd_name == NULL) {
 		/* Fall back to lttng(1) */
-		ret = utils_show_man_page(1, "lttng");
-
+		ret = utils_show_help(1, "lttng", lttng_help_msg);
 		if (ret) {
-			ERR("Cannot view man page lttng(1)");
+			ERR("Cannot show --help for `lttng`");
 			perror("exec");
 			ret = CMD_ERROR;
-			goto end;
 		}
+
+		goto end;
 	}
 
 	/* Make sure command name exists */