From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Thu, 1 Dec 2016 06:29:38 +0000 (-0500)
Subject: Add --enable-embedded-help option to embed --help messages in binaries
X-Git-Tag: v2.10.0-rc1~33
X-Git-Url: http://git.lttng.org./?a=commitdiff_plain;h=4fc83d948cea6b10484e65f004a6c167e71ac440;hp=4fc83d948cea6b10484e65f004a6c167e71ac440;p=lttng-tools.git

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 <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---