This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


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

MAINLINE PATCH: Document How to Add Command-Line Option


When adding the --param command-line option to gcc, I recorded the
necessary steps to add a command-line option.

2001-02-21  Jeffrey D. Oldham  <oldham@codesourcery.com>

        * gcc.c: Add comment explaining how to add a command-line option.
        Add title to specs language comment.

Tested          not.  Because it changes comments, not code.
Approved by     Mark Mitchell (mark@codesourcery.com)

Thanks,
Jeffrey D. Oldham
oldham@codesourcery.com
Index: gcc.c
===================================================================
RCS file: /cvs/gcc/gcc/gcc/gcc.c,v
retrieving revision 1.208
diff -c -p -r1.208 gcc.c
*** gcc.c	2001/02/21 19:45:24	1.208
--- gcc.c	2001/02/21 19:53:06
*************** CC recognizes how to compile each input 
*** 32,37 ****
--- 32,75 ----
  Once it knows which kind of compilation to perform, the procedure for
  compilation is specified by a string called a "spec".  */
  
+ /* A Short Introduction to Adding a Command-Line Option.
+ 
+    Before adding a command-line option, consider if it is really
+    necessary.  Each additional command-line option adds complexity and
+    is difficult to remove in subsequent versions.
+ 
+    In the following, consider adding the command-line argument
+    `--bar'.
+ 
+    1. Each command-line option is specified in the specs file.  The
+    notation is described below in the comment entitled "The Specs
+    Language".  Read it.
+ 
+    2. In this file, add an entry to "option_map" equating the long
+    `--' argument version and any shorter, single letter version.  Read
+    the comments in the declaration of "struct option_map" for an
+    explanation.  Do not omit the first `-'.
+ 
+    3. Look in the "specs" file to determine which program or option
+    list should be given the argument, e.g., "cc1_options".  Add the
+    appropriate syntax for the shorter option version to the
+    corresponding "const char *" entry in this file.  Omit the first
+    `-' from the option.  For example, use `-bar', rather than `--bar'.
+ 
+    4. If the argument takes an argument, e.g., `--baz argument1',
+    modify either DEFAULT_SWITCH_TAKES_ARG or
+    DEFAULT_WORD_SWITCH_TAKES_ARG in this file.  Omit the first `-'
+    from `--baz'.
+ 
+    5. Document the option in this file's display_help().  If the
+    option is passed to a subprogram, modify its corresponding
+    function, e.g., cppinit.c:print_help() or toplev.c:display_help(),
+    instead.
+ 
+    6. Compile and test.  Make sure that your new specs file is being
+    read.  For example, use a debugger to investigate the value of
+    "specs_file" in main().  */
+ 
  #include "config.h"
  #include "system.h"
  #include <signal.h>
*************** static void init_gcc_specs              
*** 272,278 ****
  						 const char *,
  						 const char *));
  
! /* Specs are strings containing lines, each of which (if not blank)
  is made up of a program name, and arguments separated by spaces.
  The program name must be exact and start from root, since no path
  is searched and it is unreliable to depend on the current working directory.
--- 310,318 ----
  						 const char *,
  						 const char *));
  
! /* The Specs Language
! 
! Specs are strings containing lines, each of which (if not blank)
  is made up of a program name, and arguments separated by spaces.
  The program name must be exact and start from root, since no path
  is searched and it is unreliable to depend on the current working directory.

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