From 52f06fd54b838f24bac11c541d20a59cc7dc0307 Mon Sep 17 00:00:00 2001 From: Joachim Steiger Date: Fri, 9 Apr 2021 23:57:01 +0200 Subject: [PATCH] manuals: generate VTY reference for osmo-pcap-{client,server} Change-Id: I28353f51de798535a3bb6efdc6c2da443d96ddfb Tweaked-By: Vadim Yanitskiy --- .gitignore | 9 +++++ configure.ac | 41 +++++++++++++++++++++ contrib/jenkins.sh | 5 +++ doc/Makefile.am | 5 ++- doc/manuals/Makefile.am | 11 ++++++ doc/manuals/vty/Makefile.vty-reference.inc | 37 +++++++++++++++++++ doc/manuals/vty/osmo-pcap-vty-reference.xml | 35 ++++++++++++++++++ doc/manuals/vty/vty_additions.xml | 2 + src/osmo_client_main.c | 36 +++++++++++++++++- src/osmo_server_main.c | 36 +++++++++++++++++- 10 files changed, 214 insertions(+), 3 deletions(-) create mode 100644 doc/manuals/Makefile.am create mode 100644 doc/manuals/vty/Makefile.vty-reference.inc create mode 100644 doc/manuals/vty/osmo-pcap-vty-reference.xml create mode 100644 doc/manuals/vty/vty_additions.xml diff --git a/.gitignore b/.gitignore index dd48c7d..cd976d9 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,12 @@ tests/testsuite tests/testsuite.log contrib/osmo-pcap.spec + +# manuals +doc/manuals/generated/ +doc/manuals/vty/osmo-pcap-*-vty-reference.pdf +doc/manuals/vty/osmo-pcap-*-vty-reference.xml +doc/manuals/vty/osmo-pcap-*-vty-reference.xml.inc.gen +doc/manuals/vty/osmo-pcap-*-vty-reference.xml.inc.merged +doc/manuals/common +doc/manuals/build diff --git a/configure.ac b/configure.ac index 8ec9c88..f4c004a 100644 --- a/configure.ac +++ b/configure.ac @@ -5,6 +5,46 @@ AC_INIT([osmo-pcap], AM_INIT_AUTOMAKE([dist-bzip2]) AC_CONFIG_TESTDIR(tests) +AC_ARG_ENABLE(manuals, + [AS_HELP_STRING( + [--enable-manuals], + [Generate manual PDFs [default=no]], + )], + [osmo_ac_build_manuals=$enableval], [osmo_ac_build_manuals="no"]) +AM_CONDITIONAL([BUILD_MANUALS], [test x"$osmo_ac_build_manuals" = x"yes"]) +AC_ARG_VAR(OSMO_GSM_MANUALS_DIR, [path to common osmo-gsm-manuals files, overriding pkg-config and "../osmo-gsm-manuals" + fallback]) +if test x"$osmo_ac_build_manuals" = x"yes" +then + # Find OSMO_GSM_MANUALS_DIR (env, pkg-conf, fallback) + if test -n "$OSMO_GSM_MANUALS_DIR"; then + echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from env)" + else + OSMO_GSM_MANUALS_DIR="$($PKG_CONFIG osmo-gsm-manuals --variable=osmogsmmanualsdir 2>/dev/null)" + if test -n "$OSMO_GSM_MANUALS_DIR"; then + echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from pkg-conf)" + else + OSMO_GSM_MANUALS_DIR="../osmo-gsm-manuals" + echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (fallback)" + fi + fi + if ! test -d "$OSMO_GSM_MANUALS_DIR"; then + AC_MSG_ERROR("OSMO_GSM_MANUALS_DIR does not exist! Install osmo-gsm-manuals or set OSMO_GSM_MANUALS_DIR.") + fi + + # Find and run check-depends + CHECK_DEPENDS="$OSMO_GSM_MANUALS_DIR/check-depends.sh" + if ! test -x "$CHECK_DEPENDS"; then + CHECK_DEPENDS="osmo-gsm-manuals-check-depends" + fi + if ! $CHECK_DEPENDS; then + AC_MSG_ERROR("missing dependencies for --enable-manuals") + fi + + # Put in Makefile with absolute path + OSMO_GSM_MANUALS_DIR="$(realpath "$OSMO_GSM_MANUALS_DIR")" + AC_SUBST([OSMO_GSM_MANUALS_DIR]) +fi CFLAGS="$CFLAGS -std=gnu11" @@ -150,5 +190,6 @@ AC_OUTPUT( contrib/osmo-pcap.spec doc/Makefile doc/examples/Makefile + doc/manuals/Makefile tests/Makefile Makefile) diff --git a/contrib/jenkins.sh b/contrib/jenkins.sh index f1779dc..ae5177f 100755 --- a/contrib/jenkins.sh +++ b/contrib/jenkins.sh @@ -41,6 +41,11 @@ $MAKE check || cat-testlogs.sh DISTCHECK_CONFIGURE_FLAGS="--with-pcap-config=/bin/true" \ PCAP_LIBS="-lpcap" PCAP_CFLAGS="" \ $MAKE distcheck || cat-testlogs.sh + +if [ "$WITH_MANUALS" = "1" ] && [ "$PUBLISH" = "1" ]; then + make -C "$base/doc/manuals" publish +fi + $MAKE maintainer-clean osmo-clean-workspace.sh diff --git a/doc/Makefile.am b/doc/Makefile.am index aee2d7b..f04764f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1 +1,4 @@ -SUBDIRS = examples +SUBDIRS = \ + examples \ + manuals \ + $(NULL) diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am new file mode 100644 index 0000000..2e24c6c --- /dev/null +++ b/doc/manuals/Makefile.am @@ -0,0 +1,11 @@ +EXTRA_DIST = vty + +if BUILD_MANUALS + # This is a significantly modified, multi-target adopted copy of + # $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc + VARIANTS = client server + include $(srcdir)/vty/Makefile.vty-reference.inc + + OSMO_REPOSITORY = osmo-pcap + include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc +endif diff --git a/doc/manuals/vty/Makefile.vty-reference.inc b/doc/manuals/vty/Makefile.vty-reference.inc new file mode 100644 index 0000000..ea8c68e --- /dev/null +++ b/doc/manuals/vty/Makefile.vty-reference.inc @@ -0,0 +1,37 @@ +DOCBOOKS = $(foreach v,$(VARIANTS),vty/osmo-pcap-$(v)-vty-reference.xml) +DOCBOOKS_DEPS = $(DOCBOOKS) $(addsuffix .inc,$(DOCBOOKS)) +INC_DIR = $(abspath $(builddir)/vty) + +include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.docbook.inc + +CLEAN_FILES += $(DOCBOOKS_DEPS) +CLEAN_FILES += $(addsuffix .inc.gen,$(DOCBOOKS)) +CLEAN_FILES += $(addsuffix .inc.merged,$(DOCBOOKS)) + +$(INC_DIR): + mkdir -p $@ + +vty/osmo-pcap-%-vty-reference.xml: $(top_builddir)/src/osmo-pcap-% $(INC_DIR) + sed -e "s|@@GENERATED@@|$@.inc|" \ + -e "s|@@VARIANT@@|$(notdir $<)|" \ + -e "s|@@REV_NUMBER@@|$(VERSION)|" \ + -e "s|@@REV_DATE@@|$(shell date +"%dth %B %Y")|" \ + -e "s|@@CR_YEAR@@|$(shell date +"%Y")|" \ + $(srcdir)/vty/osmo-pcap-vty-reference.xml > $@ + +vty/osmo-pcap-%-vty-reference.xml.inc: $(top_builddir)/src/osmo-pcap-% \ + $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \ + $(OSMO_GSM_MANUALS_DIR)/common/chapters/vty.xml \ + $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl \ + $(srcdir)/vty/*.xml $(INC_DIR) + # a) Invoke osmo-pcap-% to generate the list of commands first + $< --vty-ref-mode default --vty-ref-xml > "$@.gen" + # ... filter garbage potentially printed by libraries to stdout + sed -i '/^ "$@.merged" + # c) Convert the result of b) into a valid docbook + xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl "$@.merged" > $@ diff --git a/doc/manuals/vty/osmo-pcap-vty-reference.xml b/doc/manuals/vty/osmo-pcap-vty-reference.xml new file mode 100644 index 0000000..f4955dc --- /dev/null +++ b/doc/manuals/vty/osmo-pcap-vty-reference.xml @@ -0,0 +1,35 @@ + + + + +]> + + + + + + v1 + @@REV_DATE@@ + s.f.m.c. + Automatic build (@@REV_NUMBER@@) + + + + OsmoPCAP VTY Reference + @@VARIANT@@ + + + @@CR_YEAR@@ + + + + This work is copyright by sysmocom - s.f.m.c. GmbH. All rights reserved. + + + + + + &chapter-vty; + diff --git a/doc/manuals/vty/vty_additions.xml b/doc/manuals/vty/vty_additions.xml new file mode 100644 index 0000000..a4c675e --- /dev/null +++ b/doc/manuals/vty/vty_additions.xml @@ -0,0 +1,2 @@ + + diff --git a/src/osmo_client_main.c b/src/osmo_client_main.c index c7d68d4..4ef46cc 100644 --- a/src/osmo_client_main.c +++ b/src/osmo_client_main.c @@ -98,12 +98,41 @@ static void print_help() printf(" -T --timestamp. Print a timestamp in the debug output.\n"); printf(" -e --log-level number. Set a global loglevel.\n"); printf(" -c --config-file filename The config file to use.\n"); + + printf("\nVTY reference generation:\n"); + printf(" --vty-ref-mode MODE VTY reference generation mode (e.g. 'expert').\n"); + printf(" --vty-ref-xml Generate the VTY reference XML output and exit.\n"); +} + +static void handle_long_options(const char *prog_name, const int long_option) +{ + static int vty_ref_mode = VTY_REF_GEN_MODE_DEFAULT; + switch (long_option) { + case 1: + vty_ref_mode = get_string_value(vty_ref_gen_mode_names, optarg); + if (vty_ref_mode < 0) { + fprintf(stderr, "%s: Unknown VTY reference generation " + "mode '%s'\n", prog_name, optarg); + exit(2); + } + break; + case 2: + fprintf(stderr, "Generating the VTY reference in mode '%s' (%s)\n", + get_value_string(vty_ref_gen_mode_names, vty_ref_mode), + get_value_string(vty_ref_gen_mode_desc, vty_ref_mode)); + vty_dump_xml_ref_mode(stdout, (enum vty_ref_gen_mode) vty_ref_mode); + exit(0); + default: + fprintf(stderr, "%s: error parsing cmdline options\n", prog_name); + exit(2); + } } static void handle_options(int argc, char **argv) { while (1) { int option_index = 0, c; + static int long_option = 0; static struct option long_options[] = { {"help", 0, 0, 'h'}, {"daemonize", 0, 0, 'D'}, @@ -112,6 +141,8 @@ static void handle_options(int argc, char **argv) {"timestamp", 0, 0, 'T'}, {"log-level", 1, 0, 'e'}, {"config-file", 1, 0, 'c'}, + {"vty-ref-mode", 1, &long_option, 1}, + {"vty-ref-xml", 0, &long_option, 2}, {0, 0, 0, 0} }; @@ -125,6 +156,9 @@ static void handle_options(int argc, char **argv) print_usage(); print_help(); exit(0); + case 0: + handle_long_options(argv[0], long_option); + break; case 'D': daemonize = 1; break; @@ -197,6 +231,7 @@ int main(int argc, char **argv) vty_init(&vty_info); logging_vty_add_cmds(); osmo_stats_vty_add_cmds(); + vty_client_init(tall_cli_ctx); /* parse options */ handle_options(argc, argv); @@ -226,7 +261,6 @@ int main(int argc, char **argv) LOGP(DCLIENT, LOGL_ERROR, "Failed to allocate osmo_pcap_client.\n"); exit(1); } - vty_client_init(pcap_client); /* initialize the queue */ INIT_LLIST_HEAD(&pcap_client->conns); diff --git a/src/osmo_server_main.c b/src/osmo_server_main.c index 51441a7..9fa00e1 100644 --- a/src/osmo_server_main.c +++ b/src/osmo_server_main.c @@ -108,12 +108,41 @@ static void print_help() printf(" -T --timestamp. Print a timestamp in the debug output.\n"); printf(" -e --log-level number. Set a global loglevel.\n"); printf(" -c --config-file filename The config file to use.\n"); + + printf("\nVTY reference generation:\n"); + printf(" --vty-ref-mode MODE VTY reference generation mode (e.g. 'expert').\n"); + printf(" --vty-ref-xml Generate the VTY reference XML output and exit.\n"); +} + +static void handle_long_options(const char *prog_name, const int long_option) +{ + static int vty_ref_mode = VTY_REF_GEN_MODE_DEFAULT; + switch (long_option) { + case 1: + vty_ref_mode = get_string_value(vty_ref_gen_mode_names, optarg); + if (vty_ref_mode < 0) { + fprintf(stderr, "%s: Unknown VTY reference generation " + "mode '%s'\n", prog_name, optarg); + exit(2); + } + break; + case 2: + fprintf(stderr, "Generating the VTY reference in mode '%s' (%s)\n", + get_value_string(vty_ref_gen_mode_names, vty_ref_mode), + get_value_string(vty_ref_gen_mode_desc, vty_ref_mode)); + vty_dump_xml_ref_mode(stdout, (enum vty_ref_gen_mode) vty_ref_mode); + exit(0); + default: + fprintf(stderr, "%s: error parsing cmdline options\n", prog_name); + exit(2); + } } static void handle_options(int argc, char **argv) { while (1) { int option_index = 0, c; + static int long_option = 0; static struct option long_options[] = { {"help", 0, 0, 'h'}, {"daemonize", 0, 0, 'D'}, @@ -122,6 +151,8 @@ static void handle_options(int argc, char **argv) {"timestamp", 0, 0, 'T'}, {"log-level", 1, 0, 'e'}, {"config-file", 1, 0, 'c'}, + {"vty-ref-mode", 1, &long_option, 1}, + {"vty-ref-xml", 0, &long_option, 2}, {0, 0, 0, 0} }; @@ -135,6 +166,9 @@ static void handle_options(int argc, char **argv) print_usage(); print_help(); exit(0); + case 0: + handle_long_options(argv[0], long_option); + break; case 'D': daemonize = 1; break; @@ -210,6 +244,7 @@ int main(int argc, char **argv) vty_init(&vty_info); logging_vty_add_cmds(); osmo_stats_vty_add_cmds(); + vty_server_init(tall_srv_ctx); /* parse options */ handle_options(argc, argv); @@ -249,7 +284,6 @@ int main(int argc, char **argv) pcap_server->base_path = talloc_strdup(pcap_server, "./"); pcap_server->max_size = 1073741824; pcap_server->max_snaplen = DEFAULT_SNAPLEN; - vty_server_init(pcap_server); if (vty_read_config_file(config_file, NULL) < 0) { LOGP(DSERVER, LOGL_ERROR,