From 01d2ec474c4c1828c229830ba4e4961de5f0527d Mon Sep 17 00:00:00 2001
From: Arnaud Giersch <arnaud.giersch@univ-fcomte.fr>
Date: Tue, 26 Mar 2019 22:25:19 +0100
Subject: [PATCH] [sonar] Use a logger for help messages.

---
 include/xbt/log.h           |   6 ++
 include/xbt/sysdep.h        |   2 +
 src/instr/instr_config.cpp  |   6 +-
 src/simgrid/sg_config.cpp   |  41 +++++++-------
 src/surf/surf_interface.cpp |  38 ++++++-------
 src/xbt/config.cpp          |  17 +++---
 src/xbt/log.cpp             | 108 ++++++++++++++++++------------------
 7 files changed, 112 insertions(+), 106 deletions(-)

diff --git a/include/xbt/log.h b/include/xbt/log.h
index a6df1231d9..a65699c37e 100644
--- a/include/xbt/log.h
+++ b/include/xbt/log.h
@@ -644,5 +644,11 @@ extern xbt_log_layout_t xbt_log_default_layout;
  */
 #define XBT_HERE(...) XBT_LOG(xbt_log_priority_trace, "-- was here" __VA_ARGS__)
 
+/** @ingroup XBT_log
+ *  @hideinitializer
+ *  @brief Log help messages through category xbt.xbt_help.
+ */
+#define XBT_HELP(...) XBT_CINFO(xbt_help, __VA_ARGS__)
+
 SG_END_DECL()
 #endif                          /* ! _XBT_LOG_H_ */
diff --git a/include/xbt/sysdep.h b/include/xbt/sysdep.h
index 45d9320da1..f24b717a64 100644
--- a/include/xbt/sysdep.h
+++ b/include/xbt/sysdep.h
@@ -49,8 +49,10 @@ XBT_ATTRIB_NORETURN XBT_PUBLIC void xbt_abort(void);
 
 #ifdef XBT_LOG_LOCALLY_DEFINE_XBT_CHANNEL
 XBT_LOG_NEW_CATEGORY(xbt, "All XBT categories (simgrid toolbox)");
+XBT_LOG_NEW_SUBCATEGORY(xbt_help, xbt, "Help messages");
 #else
 XBT_LOG_EXTERNAL_CATEGORY(xbt);
+XBT_LOG_EXTERNAL_CATEGORY(xbt_help);
 #endif
 
 /** @addtogroup XBT_syscall
diff --git a/src/instr/instr_config.cpp b/src/instr/instr_config.cpp
index c6cdff7c5f..773b0ce502 100644
--- a/src/instr/instr_config.cpp
+++ b/src/instr/instr_config.cpp
@@ -301,15 +301,15 @@ static void print_line(const char* option, const char* desc, const char* longdes
   std::string str = std::string("--cfg=") + option + " ";
 
   int len = str.size();
-  printf("%s%*.*s %s\n", str.c_str(), 30 - len, 30 - len, "", desc);
+  XBT_HELP("%s%*.*s %s", str.c_str(), 30 - len, 30 - len, "", desc);
   if (longdesc != nullptr) {
-    printf ("%s\n\n", longdesc);
+    XBT_HELP("%s\n", longdesc);
   }
 }
 
 void TRACE_help()
 {
-  printf("Description of the tracing options accepted by this simulator:\n\n");
+  XBT_HELP("Description of the tracing options accepted by this simulator:\n");
   print_line(OPT_TRACING_SMPI, "Trace the MPI Interface (SMPI)",
              "  This option only has effect if this simulator is SMPI-based. Traces the MPI\n"
              "  interface and generates a trace that can be analyzed using Gantt-like\n"
diff --git a/src/simgrid/sg_config.cpp b/src/simgrid/sg_config.cpp
index 29ed3104fb..816d265631 100644
--- a/src/simgrid/sg_config.cpp
+++ b/src/simgrid/sg_config.cpp
@@ -63,39 +63,36 @@ static void sg_config_cmd_line(int *argc, char **argv)
       sg_version();
       shall_exit = true;
     } else if (parse_args && (not strcmp(argv[i], "--cfg-help") || not strcmp(argv[i], "--help"))) {
-      printf("Description of the configuration accepted by this simulator:\n");
+      XBT_HELP("Description of the configuration accepted by this simulator:");
       simgrid::config::help();
-      printf(
-          "\n"
-          "Each of these configurations can be used by adding\n"
-          "    --cfg=<option name>:<option value>\n"
-          "to the command line.\n"
-          "\n"
-          "For more information, please refer to:\n"
-          "   --help-aliases for the list of all option aliases.\n"
-          "   --help-logs and --help-log-categories for the details of logging output.\n"
-          "   --help-models for a list of all models known by this simulator.\n"
-          "   --help-tracing for the details of all tracing options known by this simulator.\n"
-          "   --version to get SimGrid version information.\n"
-          "\n"
-        );
+      XBT_HELP("\n"
+               "Each of these configurations can be used by adding\n"
+               "    --cfg=<option name>:<option value>\n"
+               "to the command line.\n"
+               "\n"
+               "For more information, please refer to:\n"
+               "   --help-aliases for the list of all option aliases.\n"
+               "   --help-logs and --help-log-categories for the details of logging output.\n"
+               "   --help-models for a list of all models known by this simulator.\n"
+               "   --help-tracing for the details of all tracing options known by this simulator.\n"
+               "   --version to get SimGrid version information.\n");
       shall_exit = not cfg_continue_after_help;
       argv[j++]  = argv[i]; // Preserve the --help in argv just in case someone else wants to see it
     } else if (parse_args && not strcmp(argv[i], "--help-aliases")) {
-      printf("Here is a list of all deprecated option names, with their replacement.\n");
+      XBT_HELP("Here is a list of all deprecated option names, with their replacement.");
       simgrid::config::show_aliases();
-      printf("Please consider using the recent names\n");
+      XBT_HELP("Please consider using the recent names");
       shall_exit = true;
     } else if (parse_args && not strcmp(argv[i], "--help-models")) {
       model_help("host", surf_host_model_description);
-      printf("\n");
+      XBT_HELP("%s", "");
       model_help("CPU", surf_cpu_model_description);
-      printf("\n");
+      XBT_HELP("%s", "");
       model_help("network", surf_network_model_description);
-      printf("\nLong description of all optimization levels accepted by the models of this simulator:\n");
+      XBT_HELP("\nLong description of all optimization levels accepted by the models of this simulator:");
       for (auto const& item : surf_optimization_mode_description)
-        printf("  %s: %s\n", item.name, item.description);
-      printf("Both network and CPU models have 'Lazy' as default optimization level\n\n");
+        XBT_HELP("  %s: %s", item.name, item.description);
+      XBT_HELP("Both network and CPU models have 'Lazy' as default optimization level\n");
       shall_exit = true;
     } else if (parse_args && not strcmp(argv[i], "--help-tracing")) {
       TRACE_help();
diff --git a/src/surf/surf_interface.cpp b/src/surf/surf_interface.cpp
index 21b718bcd8..2838ee6606 100644
--- a/src/surf/surf_interface.cpp
+++ b/src/surf/surf_interface.cpp
@@ -186,9 +186,9 @@ FILE* surf_fopen(const std::string& name, const char* mode)
 /** Displays the long description of all registered models, and quit */
 void model_help(const char* category, const std::vector<surf_model_description_t>& table)
 {
-  printf("Long description of the %s models accepted by this simulator:\n", category);
+  XBT_HELP("Long description of the %s models accepted by this simulator:", category);
   for (auto const& item : table)
-    printf("  %s: %s\n", item.name, item.description);
+    XBT_HELP("  %s: %s", item.name, item.description);
 }
 
 int find_model_description(const std::vector<surf_model_description_t>& table, const std::string& name)
@@ -248,44 +248,44 @@ void sg_version_get(int* ver_major, int* ver_minor, int* ver_patch)
 
 void sg_version()
 {
-  std::printf("This program was linked against %s (git: %s), found in %s.\n",
-              SIMGRID_VERSION_STRING, SIMGRID_GIT_VERSION, SIMGRID_INSTALL_PREFIX);
+  XBT_HELP("This program was linked against %s (git: %s), found in %s.", SIMGRID_VERSION_STRING, SIMGRID_GIT_VERSION,
+           SIMGRID_INSTALL_PREFIX);
 
 #if SIMGRID_HAVE_MC
-  std::printf("   Model-checking support compiled in.\n");
+  XBT_HELP("   Model-checking support compiled in.");
 #else
-  std::printf("   Model-checking support disabled at compilation.\n");
+  XBT_HELP("   Model-checking support disabled at compilation.");
 #endif
 
 #if SIMGRID_HAVE_NS3
-  std::printf("   NS3 support compiled in.\n");
+  XBT_HELP("   NS3 support compiled in.");
 #else
-  std::printf("   NS3 support disabled at compilation.\n");
+  XBT_HELP("   NS3 support disabled at compilation.");
 #endif
 
 #if SIMGRID_HAVE_JEDULE
-  std::printf("   Jedule support compiled in.\n");
+  XBT_HELP("   Jedule support compiled in.");
 #else
-  std::printf("   Jedule support disabled at compilation.\n");
+  XBT_HELP("   Jedule support disabled at compilation.");
 #endif
 
 #if SIMGRID_HAVE_LUA
-  std::printf("   Lua support compiled in.\n");
+  XBT_HELP("   Lua support compiled in.");
 #else
-  std::printf("   Lua support disabled at compilation.\n");
+  XBT_HELP("   Lua support disabled at compilation.");
 #endif
 
 #if SIMGRID_HAVE_MALLOCATOR
-  std::printf("   Mallocator support compiled in.\n");
+  XBT_HELP("   Mallocator support compiled in.");
 #else
-  std::printf("   Mallocator support disabled at compilation.\n");
+  XBT_HELP("   Mallocator support disabled at compilation.");
 #endif
 
-  std::printf("\nTo cite SimGrid in a publication, please use:\n"
-              "   Henri Casanova, Arnaud Giersch, Arnaud Legrand, Martin Quinson, Frédéric Suter. \n"
-              "   Versatile, Scalable, and Accurate Simulation of Distributed Applications and Platforms. \n"
-              "   Journal of Parallel and Distributed Computing, Elsevier, 2014, 74 (10), pp.2899-2917.\n");
-  std::printf("The pdf file and a BibTeX entry for LaTeX users can be found at http://hal.inria.fr/hal-01017319\n");
+  XBT_HELP("\nTo cite SimGrid in a publication, please use:\n"
+           "   Henri Casanova, Arnaud Giersch, Arnaud Legrand, Martin Quinson, Frédéric Suter. \n"
+           "   Versatile, Scalable, and Accurate Simulation of Distributed Applications and Platforms. \n"
+           "   Journal of Parallel and Distributed Computing, Elsevier, 2014, 74 (10), pp.2899-2917.\n"
+           "The pdf file and a BibTeX entry for LaTeX users can be found at http://hal.inria.fr/hal-01017319");
 }
 
 void surf_init(int *argc, char **argv)
diff --git a/src/xbt/config.cpp b/src/xbt/config.cpp
index 7fbc10f6e1..6c2cc3a457 100644
--- a/src/xbt/config.cpp
+++ b/src/xbt/config.cpp
@@ -339,23 +339,23 @@ void Config::alias(const std::string& realname, const std::string& aliasname)
  */
 void Config::dump(const char *name, const char *indent)
 {
+  XBT_LOG_DEFAULT_CATEGORY(xbt_help);
   if (name)
-    printf("%s>> Dumping of the config set '%s':\n", indent, name);
+    XBT_VERB("%s>> Dumping of the config set '%s':", indent, name);
 
   for (auto const& elm : options)
-    printf("%s  %s: ()%s) %s", indent, elm.first.c_str(), elm.second->get_type_name(),
-           elm.second->get_string_value().c_str());
+    XBT_VERB("%s  %s: ()%s) %s", indent, elm.first.c_str(), elm.second->get_type_name(),
+             elm.second->get_string_value().c_str());
 
   if (name)
-    printf("%s<< End of the config set '%s'\n", indent, name);
-  fflush(stdout);
+    XBT_VERB("%s<< End of the config set '%s'", indent, name);
 }
 
 /** @brief Displays the declared aliases and their replacement */
 void Config::show_aliases()
 {
   for (auto const& elm : aliases)
-    printf("   %-40s %s\n", elm.first.c_str(), elm.second->get_key().c_str());
+    XBT_HELP("   %-40s %s", elm.first.c_str(), elm.second->get_key().c_str());
 }
 
 /** @brief Displays the declared options and their description */
@@ -363,9 +363,8 @@ void Config::help()
 {
   for (auto const& elm : options) {
     simgrid::config::ConfigurationElement* variable = this->options.at(elm.first);
-    printf("   %s: %s\n", elm.first.c_str(), variable->get_description().c_str());
-    printf("       Type: %s; ", variable->get_type_name());
-    printf("Current value: %s\n", variable->get_string_value().c_str());
+    XBT_HELP("   %s: %s", elm.first.c_str(), variable->get_description().c_str());
+    XBT_HELP("       Type: %s; Current value: %s", variable->get_type_name(), variable->get_string_value().c_str());
   }
 }
 
diff --git a/src/xbt/log.cpp b/src/xbt/log.cpp
index 71ffabbe9c..7b1a327bc4 100644
--- a/src/xbt/log.cpp
+++ b/src/xbt/log.cpp
@@ -88,6 +88,8 @@ void xbt_log_init(int *argc, char **argv)
   int j                   = 1;
   int parse_args          = 1; // Stop parsing the parameters once we found '--'
 
+  xbt_log_control_set("xbt_help.threshold:VERBOSE xbt_help.fmt:%m%n");
+
   /* Set logs and init log submodule */
   for (int i = 1; i < *argc; i++) {
     if (strcmp("--", argv[i]) == 0) {
@@ -549,56 +551,56 @@ void xbt_log_additivity_set(xbt_log_category_t cat, int additivity)
 
 static void xbt_log_help(void)
 {
-  printf("Description of the logging output:\n"
-         "\n"
-         "   Threshold configuration: --log=CATEGORY_NAME.thres:PRIORITY_LEVEL\n"
-         "      CATEGORY_NAME: defined in code with function 'XBT_LOG_NEW_CATEGORY'\n"
-         "      PRIORITY_LEVEL: the level to print (trace,debug,verbose,info,warning,error,critical)\n"
-         "         -> trace: enter and return of some functions\n"
-         "         -> debug: crufty output\n"
-         "         -> verbose: verbose output for the user wanting more\n"
-         "         -> info: output about the regular functioning\n"
-         "         -> warning: minor issue encountered\n"
-         "         -> error: issue encountered\n"
-         "         -> critical: major issue encountered\n"
-         "      The default priority level is 'info'.\n"
-         "\n"
-         "   Format configuration: --log=CATEGORY_NAME.fmt:FORMAT\n"
-         "      FORMAT string may contain:\n"
-         "         -> %%%%: the %% char\n"
-         "         -> %%n: platform-dependent line separator (LOG4J compatible)\n"
-         "         -> %%e: plain old space (SimGrid extension)\n"
-         "\n"
-         "         -> %%m: user-provided message\n"
-         "\n"
-         "         -> %%c: Category name (LOG4J compatible)\n"
-         "         -> %%p: Priority name (LOG4J compatible)\n"
-         "\n"
-         "         -> %%h: Hostname (SimGrid extension)\n"
-         "         -> %%P: Process name (SimGrid extension)\n"
-         "         -> %%t: Thread \"name\" (LOG4J compatible -- actually the address of the thread in memory)\n"
-         "         -> %%i: Process PID (SimGrid extension -- this is a 'i' as in 'i'dea)\n"
-         "\n"
-         "         -> %%F: file name where the log event was raised (LOG4J compatible)\n"
-         "         -> %%l: location where the log event was raised (LOG4J compatible, like '%%F:%%L' -- this is a l as "
-         "in 'l'etter)\n"
-         "         -> %%L: line number where the log event was raised (LOG4J compatible)\n"
-         "         -> %%M: function name (LOG4J compatible -- called method name here of course).\n"
-         "\n"
-         "         -> %%b: full backtrace (Called %%throwable in LOG4J). Defined only under windows or when using the "
-         "GNU libc because\n"
-         "                 backtrace() is not defined elsewhere, and we only have a fallback for windows boxes, not "
-         "mac ones for example.\n"
-         "         -> %%B: short backtrace (only the first line of the %%b). Called %%throwable{short} in LOG4J; "
-         "defined where %%b is.\n"
-         "\n"
-         "         -> %%d: date (UNIX-like epoch)\n"
-         "         -> %%r: application age (time elapsed since the beginning of the application)\n"
-         "\n"
-         "   Miscellaneous:\n"
-         "      --help-log-categories    Display the current hierarchy of log categories.\n"
-         "      --log=no_loc             Don't print file names in messages (for tesh tests).\n"
-         "\n");
+  XBT_HELP(
+      "Description of the logging output:\n"
+      "\n"
+      "   Threshold configuration: --log=CATEGORY_NAME.thres:PRIORITY_LEVEL\n"
+      "      CATEGORY_NAME: defined in code with function 'XBT_LOG_NEW_CATEGORY'\n"
+      "      PRIORITY_LEVEL: the level to print (trace,debug,verbose,info,warning,error,critical)\n"
+      "         -> trace: enter and return of some functions\n"
+      "         -> debug: crufty output\n"
+      "         -> verbose: verbose output for the user wanting more\n"
+      "         -> info: output about the regular functioning\n"
+      "         -> warning: minor issue encountered\n"
+      "         -> error: issue encountered\n"
+      "         -> critical: major issue encountered\n"
+      "      The default priority level is 'info'.\n"
+      "\n"
+      "   Format configuration: --log=CATEGORY_NAME.fmt:FORMAT\n"
+      "      FORMAT string may contain:\n"
+      "         -> %%%%: the %% char\n"
+      "         -> %%n: platform-dependent line separator (LOG4J compatible)\n"
+      "         -> %%e: plain old space (SimGrid extension)\n"
+      "\n"
+      "         -> %%m: user-provided message\n"
+      "\n"
+      "         -> %%c: Category name (LOG4J compatible)\n"
+      "         -> %%p: Priority name (LOG4J compatible)\n"
+      "\n"
+      "         -> %%h: Hostname (SimGrid extension)\n"
+      "         -> %%P: Process name (SimGrid extension)\n"
+      "         -> %%t: Thread \"name\" (LOG4J compatible -- actually the address of the thread in memory)\n"
+      "         -> %%i: Process PID (SimGrid extension -- this is a 'i' as in 'i'dea)\n"
+      "\n"
+      "         -> %%F: file name where the log event was raised (LOG4J compatible)\n"
+      "         -> %%l: location where the log event was raised (LOG4J compatible, like '%%F:%%L' -- this is a l as "
+      "in 'l'etter)\n"
+      "         -> %%L: line number where the log event was raised (LOG4J compatible)\n"
+      "         -> %%M: function name (LOG4J compatible -- called method name here of course).\n"
+      "\n"
+      "         -> %%b: full backtrace (Called %%throwable in LOG4J). Defined only under windows or when using the "
+      "GNU libc because\n"
+      "                 backtrace() is not defined elsewhere, and we only have a fallback for windows boxes, not "
+      "mac ones for example.\n"
+      "         -> %%B: short backtrace (only the first line of the %%b). Called %%throwable{short} in LOG4J; "
+      "defined where %%b is.\n"
+      "\n"
+      "         -> %%d: date (UNIX-like epoch)\n"
+      "         -> %%r: application age (time elapsed since the beginning of the application)\n"
+      "\n"
+      "   Miscellaneous:\n"
+      "      --help-log-categories    Display the current hierarchy of log categories.\n"
+      "      --log=no_loc             Don't print file names in messages (for tesh tests).\n");
 }
 
 static void xbt_log_help_categories_rec(xbt_log_category_t category, const std::string& prefix)
@@ -621,7 +623,7 @@ static void xbt_log_help_categories_rec(xbt_log_category_t category, const std::
             [](xbt_log_category_t a, xbt_log_category_t b) { return strcmp(a->name, b->name) < 0; });
 
   for (auto const& cat : cats) {
-    printf("%s%s: %s\n", this_prefix.c_str(), cat->name, cat->description);
+    XBT_HELP("%s%s: %s", this_prefix.c_str(), cat->name, cat->description);
     if (cat == cats.back() && category->parent)
       child_prefix[child_prefix.rfind('|')] = ' ';
     xbt_log_help_categories_rec(cat->firstChild, child_prefix);
@@ -630,7 +632,7 @@ static void xbt_log_help_categories_rec(xbt_log_category_t category, const std::
 
 static void xbt_log_help_categories(void)
 {
-  printf("Current log category hierarchy:\n");
+  XBT_HELP("Current log category hierarchy:");
   xbt_log_help_categories_rec(&_XBT_LOGV(XBT_LOG_ROOT_CAT), "   ");
-  printf("\n");
+  XBT_HELP("%s", "");
 }
-- 
2.20.1