This is the mail archive of the binutils@sourceware.org mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: PATCH: Support "@file"


Nick Clifton wrote:

>> Where should documentation for the "@file" argument go?
> 
> 
> In the linker doc file (ld/ld.texinfo), the binutils doc file
> (binutils/doc/binutils.texi) *and* the --help output of these programs.
>  (Submitting a separate patch to do this is acceptable).

Here's the binutils patch.  Tested by building GNU/Linux and MinGW tools
and running the various programs with --help to look at the output.

The common options section does document "-V" or "-H" because these are
used inconsistently; some programs use "-V" while others use "-v", and
similarly for "-h" and "-H".

Once this is approved (possibly after iterating with you), I'll do the
equivalent as/ld/gprof changes.

OK to apply?

-- 
Mark Mitchell
CodeSourcery, LLC
mark@codesourcery.com
(916) 791-8304
2005-09-30  Mark Mitchell  <mark@codesourcery.com>

	* addr2line.c (usage): Document @file.
	* ar.c (usage): Likewise.
	* coffdump (usage): Likewise.
	* cxxfilt.c (usage): Likewise.
	* dlltool.c (usage): Likewise.
	* dllwrap.c (usage): Likewise.
	* nlmconv.c (usage): Likewise.
	* nm.c (usage): Likewise.
	* objcopy.c (usage): Likewise.
	* objdump.c (usage): Likewise.
	* readelf.c (usage): Likewise.
	* size.c (usage): Likeise.
	* srconv.c (usage): Likewise.
	* strings.c (usage): Likewise.
	* windres.c (usage): Likewise.
	* doc/binutils.texi: Add section on common options. 

Index: binutils/addr2line.c
===================================================================
RCS file: /cvs/src/src/binutils/addr2line.c,v
retrieving revision 1.25
diff -c -5 -p -r1.25 addr2line.c
*** binutils/addr2line.c	30 Sep 2005 16:37:31 -0000	1.25
--- binutils/addr2line.c	30 Sep 2005 20:49:24 -0000
*************** usage (FILE *stream, int status)
*** 75,84 ****
--- 75,85 ----
  {
    fprintf (stream, _("Usage: %s [option(s)] [addr(s)]\n"), program_name);
    fprintf (stream, _(" Convert addresses into line number/file name pairs.\n"));
    fprintf (stream, _(" If no addresses are specified on the command line, they will be read from stdin\n"));
    fprintf (stream, _(" The options are:\n\
+   @<file>                Read options from <file>\n\
    -b --target=<bfdname>  Set the binary file format\n\
    -e --exe=<executable>  Set the input file name (default is a.out)\n\
    -i --inlines		 Unwind inlined functions\n\
    -s --basenames         Strip directory names\n\
    -f --functions         Show function names\n\
Index: binutils/ar.c
===================================================================
RCS file: /cvs/src/src/binutils/ar.c,v
retrieving revision 1.43
diff -c -5 -p -r1.43 ar.c
*** binutils/ar.c	30 Sep 2005 16:37:31 -0000	1.43
--- binutils/ar.c	30 Sep 2005 20:49:25 -0000
*************** usage (int help)
*** 240,258 ****
        fprintf (s, _("  [c]          - do not warn if the library had to be created\n"));
        fprintf (s, _("  [s]          - create an archive index (cf. ranlib)\n"));
        fprintf (s, _("  [S]          - do not build a symbol table\n"));
        fprintf (s, _("  [v]          - be verbose\n"));
        fprintf (s, _("  [V]          - display the version number\n"));
! 
        ar_emul_usage (s);
      }
    else
      {
        /* xgettext:c-format */
        fprintf (s, _("Usage: %s [options] archive\n"), program_name);
        fprintf (s, _(" Generate an index to speed access to archives\n"));
        fprintf (s, _(" The options are:\n\
    -h --help                    Print this help message\n\
    -V --version                 Print version information\n"));
      }
  
    list_supported_targets (program_name, stderr);
--- 240,260 ----
        fprintf (s, _("  [c]          - do not warn if the library had to be created\n"));
        fprintf (s, _("  [s]          - create an archive index (cf. ranlib)\n"));
        fprintf (s, _("  [S]          - do not build a symbol table\n"));
        fprintf (s, _("  [v]          - be verbose\n"));
        fprintf (s, _("  [V]          - display the version number\n"));
!       fprintf (s, _("  @<file>      - read options from <file>\n"));
!  
        ar_emul_usage (s);
      }
    else
      {
        /* xgettext:c-format */
        fprintf (s, _("Usage: %s [options] archive\n"), program_name);
        fprintf (s, _(" Generate an index to speed access to archives\n"));
        fprintf (s, _(" The options are:\n\
+   @<file>                      Read options from <file>\n\
    -h --help                    Print this help message\n\
    -V --version                 Print version information\n"));
      }
  
    list_supported_targets (program_name, stderr);
Index: binutils/coffdump.c
===================================================================
RCS file: /cvs/src/src/binutils/coffdump.c,v
retrieving revision 1.14
diff -c -5 -p -r1.14 coffdump.c
*** binutils/coffdump.c	30 Sep 2005 16:37:31 -0000	1.14
--- binutils/coffdump.c	30 Sep 2005 20:49:25 -0000
*************** static void
*** 455,464 ****
--- 455,465 ----
  show_usage (FILE *file, int status)
  {
    fprintf (file, _("Usage: %s [option(s)] in-file\n"), program_name);
    fprintf (file, _(" Print a human readable interpretation of a SYSROFF object file\n"));
    fprintf (file, _(" The options are:\n\
+   @<file>                Read options from <file>\n\
    -h --help              Display this information\n\
    -v --version           Display the program's version\n\
  \n"));
  
    if (status == 0)
Index: binutils/cxxfilt.c
===================================================================
RCS file: /cvs/src/src/binutils/cxxfilt.c,v
retrieving revision 1.7
diff -c -5 -p -r1.7 cxxfilt.c
*** binutils/cxxfilt.c	30 Sep 2005 16:37:31 -0000	1.7
--- binutils/cxxfilt.c	30 Sep 2005 20:49:25 -0000
*************** Usage: %s [-_] [-n] [--strip-underscores
*** 86,96 ****
         [--format ");
    print_demangler_list (stream);
    fprintf (stream, "]\n");
  
    fprintf (stream, "\
!        [--help] [--version] [arg...]\n");
    exit (status);
  }
  
  static char mbuffer[32767];
  
--- 86,96 ----
         [--format ");
    print_demangler_list (stream);
    fprintf (stream, "]\n");
  
    fprintf (stream, "\
!        [@file] [--help] [--version] [arg...]\n");
    exit (status);
  }
  
  static char mbuffer[32767];
  
Index: binutils/dlltool.c
===================================================================
RCS file: /cvs/src/src/binutils/dlltool.c,v
retrieving revision 1.66
diff -c -5 -p -r1.66 dlltool.c
*** binutils/dlltool.c	30 Sep 2005 20:04:21 -0000	1.66
--- binutils/dlltool.c	30 Sep 2005 20:49:25 -0000
*************** usage (FILE *file, int status)
*** 3056,3065 ****
--- 3056,3066 ----
    fprintf (file, _("   -n --no-delete            Keep temp files (repeat for extra preservation).\n"));
    fprintf (file, _("   -t --temp-prefix <prefix> Use <prefix> to construct temp file names.\n"));
    fprintf (file, _("   -v --verbose              Be verbose.\n"));
    fprintf (file, _("   -V --version              Display the program version.\n"));
    fprintf (file, _("   -h --help                 Display this information.\n"));
+   fprintf (file, _("   @<file>                   Read options from <file>.\n"));
  #ifdef DLLTOOL_MCORE_ELF
    fprintf (file, _("   -M --mcore-elf <outname>  Process mcore-elf object files into <outname>.\n"));
    fprintf (file, _("   -L --linker <name>        Use <name> as the linker.\n"));
    fprintf (file, _("   -F --linker-flags <flags> Pass <flags> to the linker.\n"));
  #endif
Index: binutils/dllwrap.c
===================================================================
RCS file: /cvs/src/src/binutils/dllwrap.c,v
retrieving revision 1.19
diff -c -5 -p -r1.19 dllwrap.c
*** binutils/dllwrap.c	30 Sep 2005 16:37:31 -0000	1.19
--- binutils/dllwrap.c	30 Sep 2005 20:49:25 -0000
*************** strhash (const char *str)
*** 471,480 ****
--- 471,481 ----
  static void
  usage (FILE *file, int status)
  {
    fprintf (file, _("Usage %s <option(s)> <object-file(s)>\n"), prog_name);
    fprintf (file, _("  Generic options:\n"));
+   fprintf (file, _("   @<file>                Read options from <file>\n"));    
    fprintf (file, _("   --quiet, -q            Work quietly\n"));
    fprintf (file, _("   --verbose, -v          Verbose\n"));
    fprintf (file, _("   --version              Print dllwrap version\n"));
    fprintf (file, _("   --implib <outname>     Synonym for --output-lib\n"));
    fprintf (file, _("  Options for %s:\n"), prog_name);
Index: binutils/nlmconv.c
===================================================================
RCS file: /cvs/src/src/binutils/nlmconv.c,v
retrieving revision 1.26
diff -c -5 -p -r1.26 nlmconv.c
*** binutils/nlmconv.c	30 Sep 2005 16:37:31 -0000	1.26
--- binutils/nlmconv.c	30 Sep 2005 20:49:25 -0000
*************** show_usage (FILE *file, int status)
*** 1103,1112 ****
--- 1103,1113 ----
    -I --input-target=<bfdname>   Set the input binary file format\n\
    -O --output-target=<bfdname>  Set the output binary file format\n\
    -T --header-file=<file>       Read <file> for NLM header information\n\
    -l --linker=<linker>          Use <linker> for any linking\n\
    -d --debug                    Display on stderr the linker command line\n\
+   @<file>                       Read options from <file>.\n\
    -h --help                     Display this information\n\
    -v --version                  Display the program's version\n\
  "));
    if (status == 0)
      fprintf (file, _("Report bugs to %s\n"), REPORT_BUGS_TO);
Index: binutils/nm.c
===================================================================
RCS file: /cvs/src/src/binutils/nm.c,v
retrieving revision 1.47
diff -c -5 -p -r1.47 nm.c
*** binutils/nm.c	30 Sep 2005 16:37:31 -0000	1.47
--- binutils/nm.c	30 Sep 2005 20:49:25 -0000
*************** usage (FILE *stream, int status)
*** 252,261 ****
--- 252,262 ----
        --synthetic        Display synthetic symbols as well\n\
    -t, --radix=RADIX      Use RADIX for printing symbol values\n\
        --target=BFDNAME   Specify the target object format as BFDNAME\n\
    -u, --undefined-only   Display only undefined symbols\n\
    -X 32_64               (ignored)\n\
+   @FILE                  Read options from FILE\n\
    -h, --help             Display this information\n\
    -V, --version          Display this program's version number\n\
  \n"));
    list_supported_targets (program_name, stream);
    if (status == 0)
Index: binutils/objcopy.c
===================================================================
RCS file: /cvs/src/src/binutils/objcopy.c,v
retrieving revision 1.86
diff -c -5 -p -r1.86 objcopy.c
*** binutils/objcopy.c	30 Sep 2005 16:37:31 -0000	1.86
--- binutils/objcopy.c	30 Sep 2005 20:49:25 -0000
*************** copy_usage (FILE *stream, int exit_statu
*** 474,483 ****
--- 474,484 ----
       --prefix-sections <prefix>    Add <prefix> to start of every section name\n\
       --prefix-alloc-sections <prefix>\n\
                                     Add <prefix> to start of every allocatable\n\
                                       section name\n\
    -v --verbose                     List all object files modified\n\
+   @<file>                          Read options from <file>\n\
    -V --version                     Display this program's version number\n\
    -h --help                        Display this output\n\
       --info                        List object formats & architectures supported\n\
  "));
    list_supported_targets (program_name, stream);
Index: binutils/objdump.c
===================================================================
RCS file: /cvs/src/src/binutils/objdump.c,v
retrieving revision 1.114
diff -c -5 -p -r1.114 objdump.c
*** binutils/objdump.c	30 Sep 2005 16:37:31 -0000	1.114
--- binutils/objdump.c	30 Sep 2005 20:49:25 -0000
*************** usage (FILE *stream, int status)
*** 194,203 ****
--- 194,204 ----
    -W, --dwarf              Display DWARF info in the file\n\
    -t, --syms               Display the contents of the symbol table(s)\n\
    -T, --dynamic-syms       Display the contents of the dynamic symbol table\n\
    -r, --reloc              Display the relocation entries in the file\n\
    -R, --dynamic-reloc      Display the dynamic relocation entries in the file\n\
+   @<file>                  Read options from <file>\n\
    -v, --version            Display this program's version number\n\
    -i, --info               List object formats and architectures supported\n\
    -H, --help               Display this information\n\
  "));
    if (status != 2)
Index: binutils/readelf.c
===================================================================
RCS file: /cvs/src/src/binutils/readelf.c,v
retrieving revision 1.321
diff -c -5 -p -r1.321 readelf.c
*** binutils/readelf.c	30 Sep 2005 16:37:31 -0000	1.321
--- binutils/readelf.c	30 Sep 2005 20:49:25 -0000
*************** usage (void)
*** 2614,2623 ****
--- 2614,2624 ----
                           Disassemble the contents of section <number>\n"));
  #endif
    fprintf (stdout, _("\
    -I --histogram         Display histogram of bucket list lengths\n\
    -W --wide              Allow output width to exceed 80 characters\n\
+   @<file>                Read options from <file>\n\
    -H --help              Display this information\n\
    -v --version           Display the version number of readelf\n"));
    fprintf (stdout, _("Report bugs to %s\n"), REPORT_BUGS_TO);
  
    exit (0);
Index: binutils/size.c
===================================================================
RCS file: /cvs/src/src/binutils/size.c,v
retrieving revision 1.24
diff -c -5 -p -r1.24 size.c
*** binutils/size.c	30 Sep 2005 16:37:31 -0000	1.24
--- binutils/size.c	30 Sep 2005 20:49:25 -0000
*************** usage (FILE *stream, int status)
*** 85,94 ****
--- 85,95 ----
    fprintf (stream, _(" The options are:\n\
    -A|-B     --format={sysv|berkeley}  Select output style (default is %s)\n\
    -o|-d|-x  --radix={8|10|16}         Display numbers in octal, decimal or hex\n\
    -t        --totals                  Display the total sizes (Berkeley only)\n\
              --target=<bfdname>        Set the binary file format\n\
+             @<file>                   Read options from <file>\n\
    -h        --help                    Display this information\n\
    -v        --version                 Display the program's version\n\
  \n"),
  #if BSD_DEFAULT
    "berkeley"
Index: binutils/srconv.c
===================================================================
RCS file: /cvs/src/src/binutils/srconv.c,v
retrieving revision 1.17
diff -c -5 -p -r1.17 srconv.c
*** binutils/srconv.c	30 Sep 2005 16:37:31 -0000	1.17
--- binutils/srconv.c	30 Sep 2005 20:49:25 -0000
*************** show_usage (FILE *file, int status)
*** 1722,1731 ****
--- 1722,1732 ----
    fprintf (file, _("Convert a COFF object file into a SYSROFF object file\n"));
    fprintf (file, _(" The options are:\n\
    -q --quick       (Obsolete - ignored)\n\
    -n --noprescan   Do not perform a scan to convert commons into defs\n\
    -d --debug       Display information about what is being done\n\
+   @<file>          Read options from <file>\n\
    -h --help        Display this information\n\
    -v --version     Print the program's version number\n"));
  
    if (status == 0)
      fprintf (file, _("Report bugs to %s\n"), REPORT_BUGS_TO);
Index: binutils/strings.c
===================================================================
RCS file: /cvs/src/src/binutils/strings.c,v
retrieving revision 1.30
diff -c -5 -p -r1.30 strings.c
*** binutils/strings.c	30 Sep 2005 16:37:31 -0000	1.30
--- binutils/strings.c	30 Sep 2005 20:49:25 -0000
*************** usage (FILE *stream, int status)
*** 715,724 ****
--- 715,725 ----
    -t --radix={o,d,x}        Print the location of the string in base 8, 10 or 16\n\
    -o                        An alias for --radix=o\n\
    -T --target=<BFDNAME>     Specify the binary file format\n\
    -e --encoding={s,S,b,l,B,L} Select character size and endianness:\n\
                              s = 7-bit, S = 8-bit, {b,l} = 16-bit, {B,L} = 32-bit\n\
+   @<file>                   Read options from <file>\n\
    -h --help                 Display this information\n\
    -v --version              Print the program's version number\n"));
    list_supported_targets (program_name, stream);
    if (status == 0)
      fprintf (stream, _("Report bugs to %s\n"), REPORT_BUGS_TO);
Index: binutils/windres.c
===================================================================
RCS file: /cvs/src/src/binutils/windres.c,v
retrieving revision 1.26
diff -c -5 -p -r1.26 windres.c
*** binutils/windres.c	30 Sep 2005 20:04:21 -0000	1.26
--- binutils/windres.c	30 Sep 2005 20:49:25 -0000
*************** usage (FILE *stream, int status)
*** 657,666 ****
--- 657,667 ----
    fprintf (stream, _("\
       --yydebug                 Turn on parser debugging\n"));
  #endif
    fprintf (stream, _("\
    -r                           Ignored for compatibility with rc\n\
+   @<file>                      Read options from <file>\n\
    -h --help                    Print this help message\n\
    -V --version                 Print version information\n"));
    fprintf (stream, _("\
  FORMAT is one of rc, res, or coff, and is deduced from the file name\n\
  extension if not specified.  A single file name is an input file.\n\
Index: binutils/doc/binutils.texi
===================================================================
RCS file: /cvs/src/src/binutils/doc/binutils.texi,v
retrieving revision 1.77
diff -c -5 -p -r1.77 binutils.texi
*** binutils/doc/binutils.texi	15 Aug 2005 15:37:13 -0000	1.77
--- binutils/doc/binutils.texi	30 Sep 2005 20:49:25 -0000
*************** section entitled "GNU Free Documentation
*** 164,173 ****
--- 164,174 ----
  * cxxfilt: c++filt.             MS-DOS name for c++filt
  * addr2line::			Convert addresses to file and line
  * nlmconv::                     Converts object code into an NLM
  * windres::			Manipulate Windows resources
  * dlltool::			Create files needed to build and use DLLs
+ * Common Options::              Command-line options for all utilities
  * Selecting The Target System:: How these utilities determine the target.
  * Reporting Bugs::              Reporting Bugs
  * GNU Free Documentation License::  GNU Free Documentation License
  * Index::                       Index
  @end menu
*************** Display the command line options underst
*** 3424,3433 ****
--- 3425,3456 ----
  @c man begin SEEALSO readelf
  objdump(1), and the Info entries for @file{binutils}.
  @c man end
  @end ignore
  
+ @node Common Options
+ @chapter Common Options
+ 
+ The following command-line options are supported by all of the
+ programs described in this manual.
+ 
+ @table @env
+ @item @@@var{file}
+ Read command-line options from @var{file}.  Options are separated by
+ whitespace.  A whitespace character may be included in an option by
+ surrounding the entire option in either single or double quotes.  Any
+ character (including a backslash) may be included by prefixing the
+ character to be included character with a backslash.
+ 
+ @item --help
+ Display the command-line options supported by the program.
+ 
+ @item --version
+ Display the version number of the program.
+ 
+ @end table
+ 
  @node Selecting The Target System
  @chapter Selecting the Target System
  
  You can specify two aspects of the target system to the @sc{gnu}
  binary file utilities, each in several ways:

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]