Review from Robert, and nits

          --- old/usr/src/tools/cw/cw.1onbld.man.txt
          +++ new/usr/src/tools/cw/cw.1onbld.man.txt

   1    1  CW(1ONBLD)                    illumos Build Tools                   CW(1ONBLD)
   2    2  
   3    3  NAME
   4    4       cw - invoke one or more compilers with argument translation
   5    5  
   6    6  SYNOPSIS
   7    7       cw [-C] [--versions] [--noecho] --primary compiler
   8    8          [--shadow compiler ...] -- compiler args ...
   9    9  
  10   10  DESCRIPTION
  11   11       cw is a facility for invoking one or more compilers, providing
  12   12       translation from Sun style arguments as appropriate.  This allows the use
  13   13       of arbitrary compilers without the need to alter large numbers of
  14   14       makefiles.  A mode called shadow compilation invokes multiple compilers
  15   15       so that warnings and errors may be obtained from both.  See SHADOW
  16   16       COMPILATION for details.  This version of cw supports compilers with both
  17   17       Sun Studio 12 and GCC-style command lines.
  18   18  
  19   19  ARGUMENTS
  20   20       Both the --primary and --secondary parameters take a compiler
  21   21       specification.  This is a comma-separated list of the form
  22   22       name,executable,style Where name is a name for the compiler, executable
  23   23       is the full path to the compiler executable, and style is the style of
  24   24       command-line options the compiler expects, either sun or gnu.
  25   25  
  26   26       --primary compiler
  27   27               Specify the compiler to be used primarily (that which is used for
  28   28               link-editing and pre-processing, and whos objects we deliver).
  29   29  
  30   30       --shadow compiler
  31   31               Specify a shadow compiler, which builds sources for the sake of
  32   32               checking code quality and compatibility, but has its output
  33   33               discarded.
  34   34  
  35   35       --noecho
  36   36               Do not echo the actual command line of any compilers invoked.
  37   37  
  38   38       --versions
  39   39               Request from each configured primary and shadow compiler its
  40   40               version information.
  41   41  
  42   42       -C      The sources being compiled are C++.  This is necessary as it
  43   43               affects the translation of compiler arguments.
  44   44  
  45   45       --      Arguments intended for the compilers themselves must be separated
  46   46               from those of cw by a --.
  47   47  
  48   48       -_name=
  49   49  
  50   50       -_style=
  51   51               Parameters intended for the compiler be guarded with options of
  52   52               the form -_name= and -_style= Where name and style are those
  53   53               passed to --primary and --shadow this allows certain flags to be
  54   54               passed only to certain classes of compiler.
  55   55  
  56   56               For historical reasons, the -_style= option is also translated
  57   57               such that a style of sun may use the flag -_cc= and a style of
  58   58               gnu may use the flag -_gcc=, and when the -C option is given and
  59   59               C++ is in use the style of sun may use the flag -_CC= and the
  60   60               style of gnu may use the flag -_g++=.
  61   61  

  62   62  SHADOW COMPILATION
  63   63       If --shadow compilers are specified cw will invoke shadow compiler, with
  64   64       the outputs modified (as well as any translation for compiler style) as
  65   65       follows:
  66   66  
  67   67       1.   If none of -c, -E, -P, or -S appears in the argument list (that is,
  68   68            linking is attempted), the shadow compilers will not be invoked.
  69   69            This is because the objects built with that compiler which would be
  70   70            linked have been previously discarded.
  71   71  
  72      -     2.   If an option of the form -o filename was provided, it will be
  73      -          replaced by two options of the form -o tempfile
       72 +     2.   If the -o filename option was provided, with or without a separating
       73 +          space, it will be replaced with -o tempfile
  74   74  
  75   75       3.   If the option -o was not provided, -o tempfile will be added to the
  76   76            end of the argument list used to invoke the shadow compilers.
  77   77       When shadow compilation is in effect, cw writes to standard error each
  78   78       compiler's standard error output following its argument list.  Messages
  79   79       from the compilers will not be interleaved.  If cw is used to invoke the
  80   80       preprocessor and no output location is specified, cw will write to
  81   81       standard output the primary compiler's standard output, and the secondary
  82   82       compiler's standard output will be discarded.
  83   83  

  84   84       Because the Sun compilers write intermediate objects to fixed filenames
  85   85       in the current directory when instructed to compile and link multiple
  86   86       source files via a single command line, it would be unsafe to invoke more
  87   87       than one compiler in this fashion.  Therefore cw does not accept multiple
  88   88       source files unless the preprocessor is to be invoked.  An attempt to
  89   89       invoke cw in this manner will result in an error.
  90   90  
  91   91  ARGUMENT TRANSLATION
  92   92       If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
  93   93       default flags is added to the beginning of the argument list, and the
  94   94       remaining arguments are translated to their closest appropriate semantic
  95   95       equivalents and passed in the same order as their counterparts given to
  96   96       cw.  See the comments at the head of usr/src/tools/cw/cw.c for a detailed
  97   97       list of translations.
  98   98  
  99   99  ENVIRONMENT
 100  100       CW_SHADOW_SERIAL
 101  101               If this variable is set in the environment, invoke the primary
 102  102               compiler, wait for it to complete, then invoke the shadow
 103  103               compilers.  Normally the primary and shadow compilers are invoked
 104  104               in parallel.
 105  105  
 106  106       CW_NO_EXEC
 107  107               If this variable is set in the environment, write the usual
 108  108               output to standard error but do not actually invoke any compiler.
 109  109               This is useful for debugging the translation engine.
 110  110  
 111  111  EXIT STATUS
 112  112       The following exit status values are returned:
 113  113  
 114  114       0       The primary compiler, and shadow compilers if invoked, both
 115  115               completed successfully.
 116  116  
 117  117       >0      A usage error occurred, or one or more compilers returned a
 118  118               nonzero exit status.
 119  119  
 120  120  SEE ALSO
 121  121       cc(1), CC(1), gcc(1)
 122  122  
 123  123  BUGS
 124  124       The translations provided for gcc are not always exact and in some cases
 125  125       reflect local policy rather than actual equivalence.
 126  126  
 127  127       Additional compiler types should be supported.
 128  128  
 129  129       The translation engine is hacky.
 130  130  
 131  131  illumos                        February 10, 2018                       illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX