Various option-related tweaks:

- Match the ordering of the non-tool-specific options in the usage message
  with the order in the user manual.  As a result, we now always print
  --alignment and --trace-malloc in the core's usage messages, which saves
  malloc-replacing tools from doing it themselves (and brings it in line
  with options that only apply to error-collecting tools).

- Improved the presentation of the Vex options with --help-debug.

- Removed documentation of -d in the manual because it's a debugging-only flag.

- Documented --read-var-info in the manual.  This fixes bug 201169.

- Renamed --auto-run-dsymutil as --dsymutil and documented it in the usage
  message.

- Fixed an XML error in manual-core-adv.xml.


git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10703 a5019735-40e9-0310-863c-91ae7b9d1cf9

Author: njn

NEWS

@@ -9,7 +9,8 @@ Release 3.5.0 (???)
   - AMD64 (a.k.a. x86-64) are supported, but not as well.
   - Older PowerPC machines are not supported.
   - It requires Mac OS X 10.5 Leopard or later.  Porting to 10.4 is not
-    planned because it would require work and 10.4 is only becoming less common.
+    planned because it would require work and 10.4 is only becoming less
+    common.
 
   Things that don't work:
   - Helgrind and Ptrcheck
@@ -25,6 +26,10 @@ Release 3.5.0 (???)
     Hijack's fault.  See https://bugs.kde.org/show_bug.cgi?id=193917 for
     details and a simple work-around.
 
+  Usage notes:
+  - You will likely find --dsymutil=yes a useful option, as error messages may
+    be imprecise without it.
+
   Many thanks to Greg Parker for developing this port over several years.
 
 * XXX: something about improved Wine support?

coregrind/m_debuginfo/readmacho.c

@@ -917,8 +917,8 @@ Bool ML_(read_macho_debug_info)( struct _DebugInfo* di )
    }
 
    /* There was no dsym file, or it doesn't match.  We'll have to try
-      regenerating it, unless auto-run-dsymutil is disabled, in which
-      case just complain instead. */
+      regenerating it, unless --dsymutil=no, in which case just complain
+      instead. */
 
    /* If this looks like a lib that we shouldn't run dsymutil on, just
       give up.  (possible reasons: is system lib, or in /usr etc, or
@@ -928,13 +928,13 @@ Bool ML_(read_macho_debug_info)( struct _DebugInfo* di )
    if (is_systemish_library_name(di->filename))
       goto success;
 
-   if (!VG_(clo_auto_run_dsymutil)) {
+   if (!VG_(clo_dsymutil)) {
       if (VG_(clo_verbosity) == 1) {
          VG_(message)(Vg_DebugMsg, "%s:\n", di->filename);
       }
       if (VG_(clo_verbosity) > 0)
          VG_(message)(Vg_DebugMsg, "%sdSYM directory %s; consider using "
-                      "--auto-run-dsymutil=yes\n",
+                      "--dsymutil=yes\n",
                       VG_(clo_verbosity) > 1 ? "   " : "",
                       dsymfilename ? "has wrong UUID" : "is missing"); 
       goto success;

coregrind/m_main.c

@@ -111,35 +111,23 @@ static void usage_NORETURN ( Bool debug_help )
    Char* usage1 = 
 "usage: valgrind [options] prog-and-args\n"
 "\n"
-"  common user options for all Valgrind tools, with defaults in [ ]:\n"
+"  tool-selection option, with default in [ ]:\n"
 "    --tool=<name>             use the Valgrind tool named <name> [memcheck]\n"
+"\n"
+"  basic user options for all Valgrind tools, with defaults in [ ]:\n"
 "    -h --help                 show this message\n"
 "    --help-debug              show this message, plus debugging options\n"
 "    --version                 show version\n"
 "    -q --quiet                run silently; only print error msgs\n"
 "    -v --verbose              be more verbose, incl counts of errors\n"
 "    --trace-children=no|yes   Valgrind-ise child processes (follow execve)? [no]\n"
-"    --child-silent-after-fork=no|yes  omit child output between fork & exec? [no]\n"
+"    --child-silent-after-fork=no|yes omit child output between fork & exec? [no]\n"
 "    --track-fds=no|yes        track open file descriptors? [no]\n"
 "    --time-stamp=no|yes       add timestamps to log messages? [no]\n"
 "    --log-fd=<number>         log messages to file descriptor [2=stderr]\n"
 "    --log-file=<file>         log messages to <file>\n"
 "    --log-socket=ipaddr:port  log messages to socket ipaddr:port\n"
 "\n"
-"  uncommon user options for all Valgrind tools:\n"
-"    --run-libc-freeres=no|yes free up glibc memory at exit? [yes]\n"
-"    --sim-hints=hint1,hint2,...  known hints:\n"
-"                                 lax-ioctls, enable-outer [none]\n"
-"    --show-emwarns=no|yes     show warnings about emulation limits? [no]\n"
-"    --smc-check=none|stack|all  checks for self-modifying code: none,\n"
-"                              only for code found in stacks, or all [stack]\n"
-"    --kernel-variant=variant1,variant2,...  known variants: bproc [none]\n"
-"                              handle non-standard kernel variants\n"
-"    --read-var-info=yes|no    read debug info on stack and global variables\n"
-"                              and use it to print better error messages in\n"
-"                              tools that make use of it (Memcheck, Helgrind,\n"
-"                              DRD)\n"
-"\n"
 "  user options for Valgrind tools that report errors:\n"
 "    --xml=yes                 emit error output in XML (some tools only)\n"
 "    --xml-fd=<number>         XML output to file descriptor\n"
@@ -156,15 +144,34 @@ static void usage_NORETURN ( Bool debug_help )
 "    --db-attach=no|yes        start debugger when errors detected? [no]\n"
 "    --db-command=<command>    command to start debugger [%s -nw %%f %%p]\n"
 "    --input-fd=<number>       file descriptor for input [0=stdin]\n"
+"    --dsymutil=no|yes         run dsymutil on Mac OS X when helpful? [no]\n"
 "    --max-stackframe=<number> assume stack switch for SP changes larger\n"
 "                              than <number> bytes [2000000]\n"
 "    --main-stacksize=<number> set size of main thread's stack (in bytes)\n"
 "                              [use current 'ulimit' value]\n"
+"\n"
+"  user options for Valgrind tools that replace malloc:\n"
+"    --alignment=<number>      set minimum alignment of heap allocations [%ld]\n"
+"\n"
+"  uncommon user options for all Valgrind tools:\n"
+"    --smc-check=none|stack|all  checks for self-modifying code: none,\n"
+"                              only for code found in stacks, or all [stack]\n"
+"    --read-var-info=yes|no    read debug info on stack and global variables\n"
+"                              and use it to print better error messages in\n"
+"                              tools that make use of it (Memcheck, Helgrind,\n"
+"                              DRD)\n"
+"    --run-libc-freeres=no|yes free up glibc memory at exit on Linux? [yes]\n"
+"    --sim-hints=hint1,hint2,...  known hints:\n"
+"                                 lax-ioctls, enable-outer [none]\n"
+"    --kernel-variant=variant1,variant2,...  known variants: bproc [none]\n"
+"                              handle non-standard kernel variants\n"
+"    --show-emwarns=no|yes     show warnings about emulation limits? [no]\n"
 "\n";
 
    Char* usage2 = 
 "\n"
 "  debugging options for all Valgrind tools:\n"
+"    -d                        show verbose debugging output\n"
 "    --sanity-level=<number>   level of sanity checking to do [1]\n"
 "    --trace-flags=<XXXXXXXX>   show generated code? (X = 0|1) [00000000]\n"
 "    --profile-flags=<XXXXXXXX> ditto, but for profiling (X = 0|1) [00000000]\n"
@@ -184,13 +191,13 @@ static void usage_NORETURN ( Bool debug_help )
 "    --sym-offsets=yes|no      show syms in form 'name+offset' ? [no]\n"
 "    --command-line-only=no|yes  only use command line options [no]\n"
 "\n"
-"    --vex-iropt-verbosity             0 .. 9 [0]\n"
-"    --vex-iropt-level                 0 .. 2 [2]\n"
-"    --vex-iropt-precise-memory-exns   [no]\n"
-"    --vex-iropt-unroll-thresh         0 .. 400 [120]\n"
-"    --vex-guest-max-insns             1 .. 100 [50]\n"
-"    --vex-guest-chase-thresh          0 .. 99  [10]\n"
-"\n"
+"  Vex options for all Valgrind tools:\n"
+"    --vex-iropt-verbosity=<0..9>           [0]\n"
+"    --vex-iropt-level=<0..2>               [2]\n"
+"    --vex-iropt-precise-memory-exns=no|yes [no]\n"
+"    --vex-iropt-unroll-thresh=<0..400>     [120]\n"
+"    --vex-guest-max-insns=<1..100>         [50]\n"
+"    --vex-guest-chase-thresh=<0..99>       [10]\n"
 "    --trace-flags and --profile-flags values (omit the middle space):\n"
 "       1000 0000   show conversion into IR\n"
 "       0100 0000   show after initial opt\n"
@@ -205,6 +212,9 @@ static void usage_NORETURN ( Bool debug_help )
 "  debugging options for Valgrind tools that report errors\n"
 "    --dump-error=<number>     show translation for basic block associated\n"
 "                              with <number>'th error context [0=show none]\n"
+"\n"
+"  debugging options for Valgrind tools that replace malloc:\n"
+"    --trace-malloc=no|yes     show client malloc details? [no]\n"
 "\n";
 
    Char* usage3 =
@@ -224,8 +234,8 @@ static void usage_NORETURN ( Bool debug_help )
    VG_(log_output_sink).fd = 1;
    VG_(log_output_sink).is_socket = False;
 
-   /* 'usage1' expects one char* argument */
-   VG_(printf)(usage1, gdb_path);
+   /* 'usage1' expects one char* argument and one SizeT argument. */
+   VG_(printf)(usage1, gdb_path, VG_MIN_MALLOC_SZB);
    if (VG_(details).name) {
       VG_(printf)("  user options for %s:\n", VG_(details).name);
       if (VG_(needs).command_line_options)
@@ -474,10 +484,9 @@ void main_process_cmd_line_options ( /*OUT*/Bool* logging_to_fd,
       else if VG_XACT_CLO(arg, "--smc-check=all",   VG_(clo_smc_check),
                                                     Vg_SmcAll);
 
-      else if VG_STR_CLO (arg, "--kernel-variant",   VG_(clo_kernel_variant)) {}
+      else if VG_STR_CLO (arg, "--kernel-variant",  VG_(clo_kernel_variant)) {}
 
-      else if VG_BOOL_CLO(arg, "--auto-run-dsymutil",
-                               VG_(clo_auto_run_dsymutil)) {}
+      else if VG_BOOL_CLO(arg, "--dsymutil",        VG_(clo_dsymutil)) {}
 
       else if VG_BINT_CLO(arg, "--vex-iropt-verbosity",
                        VG_(clo_vex_control).iropt_verbosity, 0, 10) {}

coregrind/m_options.c

@@ -90,7 +90,7 @@ Word   VG_(clo_main_stacksize) = 0; /* use client's rlimit.stack */
 Bool   VG_(clo_wait_for_gdb)   = False;
 VgSmc  VG_(clo_smc_check)      = Vg_SmcStack;
 HChar* VG_(clo_kernel_variant) = NULL;
-Bool   VG_(clo_auto_run_dsymutil) = False;
+Bool   VG_(clo_dsymutil)       = False;
 
 
 /*====================================================================*/

coregrind/m_replacemalloc/replacemalloc_core.c

@@ -74,21 +74,6 @@ Bool VG_(replacement_malloc_process_cmd_line_option)(Char* arg)
    return True;
 }
 
-void VG_(replacement_malloc_print_usage)(void)
-{
-   VG_(printf)(
-"    --alignment=<number>      set minimum alignment of allocations [%d]\n",
-   VG_MIN_MALLOC_SZB
-   );
-}
-
-void VG_(replacement_malloc_print_debug_usage)(void)
-{
-   VG_(printf)(
-"    --trace-malloc=no|yes     show client malloc details? [no]\n"
-   );
-}
-
 /*------------------------------------------------------------*/
 /*--- Useful functions                                     ---*/
 /*------------------------------------------------------------*/

coregrind/pub_core_options.h

@@ -168,7 +168,7 @@ extern HChar* VG_(clo_kernel_variant);
 
 /* Darwin-specific: automatically run /usr/bin/dsymutil to update
    .dSYM directories as necessary? */
-extern Bool VG_(clo_auto_run_dsymutil);
+extern Bool VG_(clo_dsymutil);
 
 /* --------- Functions --------- */
 

docs/xml/manual-core-adv.xml

@@ -228,7 +228,7 @@ tool-specific macros).</para>
   <varlistentry>
    <term><command><computeroutput>VALGRIND_PRINTF_BACKTRACE(format, ...)</computeroutput>:</command></term>
    <listitem>
-    <para>Like <computeroutput>VALGRIND_PRINTF<computeroutput>, but prints
+    <para>Like <computeroutput>VALGRIND_PRINTF</computeroutput>, but prints
     a stack backtrace immediately afterwards.</para>
    </listitem>
   </varlistentry>