Add --enable-embedded-help option to embed --help messages in binaries
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Thu, 1 Dec 2016 06:29:38 +0000 (01:29 -0500)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Fri, 5 May 2017 13:32:33 +0000 (09:32 -0400)
commit4fc83d948cea6b10484e65f004a6c167e71ac440
treed1dd7a4fa2af67f2f73ed93ae083192ff3972fd6
parentcf0bcb51ea857687a353d2851e572dba6cc63cb0
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>
38 files changed:
.gitignore
Makefile.am
configure.ac
doc/man/Makefile.am
src/bin/lttng-crash/Makefile.am
src/bin/lttng-crash/lttng-crash.c
src/bin/lttng-relayd/Makefile.am
src/bin/lttng-relayd/main.c
src/bin/lttng-sessiond/Makefile.am
src/bin/lttng-sessiond/main.c
src/bin/lttng/Makefile.am
src/bin/lttng/command.h
src/bin/lttng/commands/add_context.c
src/bin/lttng/commands/create.c
src/bin/lttng/commands/destroy.c
src/bin/lttng/commands/disable_channels.c
src/bin/lttng/commands/disable_events.c
src/bin/lttng/commands/enable_channels.c
src/bin/lttng/commands/enable_events.c
src/bin/lttng/commands/help.c
src/bin/lttng/commands/list.c
src/bin/lttng/commands/load.c
src/bin/lttng/commands/metadata.c
src/bin/lttng/commands/regenerate.c
src/bin/lttng/commands/save.c
src/bin/lttng/commands/set_session.c
src/bin/lttng/commands/snapshot.c
src/bin/lttng/commands/start.c
src/bin/lttng/commands/status.c
src/bin/lttng/commands/stop.c
src/bin/lttng/commands/track-untrack.c
src/bin/lttng/commands/version.c
src/bin/lttng/commands/view.c
src/bin/lttng/lttng.c
src/bin/lttng/utils.c
src/bin/lttng/utils.h
src/common/utils.c
src/common/utils.h
This page took 0.040676 seconds and 4 git commands to generate.